Keyoku v3: revision-bound Factfile and Progress & attention

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,14 +1,22 @@
-## Summary
+## Reviewer brief
 
-Brief description of the changes.
+What single outcome does this contribution deliver, and why does it matter?
 
-## Changes
+## Outcome and Factfile
 
-- ...
+- Keyoku outcome: <!-- .keyoku/outcomes/<id>.yaml -->
+- Contribution id: <!-- keyoku contribution show <id> -->
+- Factfile: <!-- GitHub Check/artifact, committed receipt, or “not applicable” with reason -->
+- Exact head SHA: <!-- filled by Keyoku Check -->
+
+## Human judgment still required
+
+<!-- What cannot be decided by a test, scanner, or agent? -->
 
 ## Checklist
 
-- [ ] Tests pass (`npm test`)
-- [ ] Build succeeds (`npm run build`)
-- [ ] New functionality has tests
+- [ ] This is one coherent reviewer outcome; unrelated work is split or stacked
+- [ ] Relevant behavior has evidence (test, screenshot, trace, report, or code tour)
 - [ ] Breaking changes are documented
+- [ ] Declared outcome criteria pass for the exact proposed snapshot
+- [ ] I read the Factfile limits and understand what passing does not claim

.github/workflows/ci.yml

@@ -8,13 +8,18 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [20, 22]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
-          node-version: 20
+          node-version: ${{ matrix.node-version }}
           cache: npm
       - run: npm ci
       - run: npm run typecheck
       - run: npm test
       - run: npm run eval # gate on muscle-memory retrieval quality, not just correctness
+      - run: npm audit --omit=dev

.github/workflows/keyoku-proof.yml

@@ -0,0 +1,45 @@
+name: Keyoku proof
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+# Outcome probes execute the proposed repository revision. Keep this job
+# read-only; GitHub's native PR review owns the human decision.
+permissions:
+  contents: read
+
+concurrency:
+  group: keyoku-proof-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  factfile:
+    name: Keyoku / outcome proof
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 20
+          cache: npm
+      - name: Install project dependencies
+        run: npm ci
+      - name: Build this source revision
+        run: npm run build
+      - name: Prove Keyoku's own GitHub outcome
+        id: proof
+        env:
+          KEYOKU_BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before || github.sha }}
+        run: node dist/index.js proof ci github-proof-v1 --base "$KEYOKU_BASE_SHA"
+      - name: Attach the full Factfile
+        if: always()
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: keyoku-factfile-${{ github.sha }}
+          path: .keyoku/contributions/${{ steps.proof.outputs.contribution_id }}/factfile.*
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/release.yml

@@ -12,39 +12,45 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version: 22
           cache: npm
           registry-url: https://registry.npmjs.org
       # npm >= 11.5 is required for OIDC Trusted Publishing (tokenless + provenance).
-      - run: npm install -g npm@latest
+      - run: npm install -g npm@12.0.2
       - run: npm ci
       - run: npm run typecheck
       - run: npm test
-      - run: npm run eval # quality gate: muscle-memory retrieval, not just correctness
+      - run: npm run eval
+      - run: npm audit --omit=dev
       - run: node scripts/preflight.mjs # release integrity: version single-sourced, changelog present, built artifact matches package.json (npm test already built dist/)
       # Publish path, in order of preference:
       #   1. npm Trusted Publishing (OIDC, tokenless, provenance) — configure once at
       #      npmjs.com → package 'keyoku' → Settings → Trusted Publishing → add this repo
       #      (Keyoku-ai/keyoku) + workflow 'release.yml'. Then this just works.
       #   2. NPM_TOKEN secret (Automation type) as a fallback.
-      # Idempotent (skips a version already on npm), and degrades to a loud warning
-      # instead of a red build when neither auth path is configured (maintainer then
-      # publishes via CLI). It never silently claims success.
+      # Idempotent (skips a version already on npm). Prereleases go to `next` so
+      # the v2 `latest` line remains a rollback boundary. Publish failures are
+      # real release failures; a green workflow must never mean "nothing shipped".
       - name: Publish to npm
         run: |
           VERSION=$(node -p "require('./package.json').version")
-          if npm view "keyoku@${VERSION}" version >/dev/null 2>&1; then
-            echo "keyoku@${VERSION} already on npm — skipping publish."
-            exit 0
+          if [[ "${GITHUB_REF_NAME}" != "v${VERSION}" ]]; then
+            echo "::error title=Tag/version mismatch::Tag ${GITHUB_REF_NAME} does not match package v${VERSION}."
+            exit 1
           fi
-          if npm publish --provenance --access public; then
-            echo "Published keyoku@${VERSION} with provenance."
+          if [[ "${VERSION}" == *-* ]]; then
+            DIST_TAG=next
           else
-            echo "::warning title=npm publish skipped::Could not publish keyoku@${VERSION} — enable Trusted Publishing for Keyoku-ai/keyoku (release.yml) at npmjs.com, or set the NPM_TOKEN secret. Until then publish from the maintainer CLI: npm publish --access public"
+            DIST_TAG=latest
+          fi
+          if npm view "keyoku@${VERSION}" version >/dev/null 2>&1; then
+            echo "keyoku@${VERSION} already on npm — skipping publish."
             exit 0
           fi
+          npm publish --provenance --access public --tag "${DIST_TAG}"
+          echo "Published keyoku@${VERSION} with provenance on ${DIST_TAG}."
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -8,3 +8,23 @@ dist/
 .DS_Store
 *.tmp
 *.tgz
+.keyoku/runtime/
+.keyoku/contributions/
+.playwright-cli/
+output/
+.vitest-results.json
+preview-factfile.html
+
+# Local product/market working papers. Public documentation belongs in the
+# README, FACTFILE-STANDARD, GITHUB, SECURITY, and contributor guides.
+docs/KEYOKU-PROOF-V1.md
+docs/KEYOKU-CONTRIBUTION-GATE.html
+
+# Retired product explorations are kept locally for reference. Do not publish
+# internal briefs or obsolete UI captures with the generic proof harness.
+archive/experimental-control-plane/docs/
+docs/artifacts/factfile-human-review.png
+docs/artifacts/keyoku-control-plane-desktop.png
+docs/artifacts/keyoku-control-plane-mobile.png
+docs/artifacts/keyoku-intervention-channel-desktop.png
+docs/artifacts/keyoku-intervention-channel-mobile.png

.gitleaksignore

@@ -0,0 +1,11 @@
+# Reviewed public-history false positives: synthetic credential-redaction tests
+# and model identifiers. Fingerprint scoping preserves detection everywhere else.
+5d57b56527daf6864c01a1834ce29b05719ec8e8:tests/activity.test.ts:curl-auth-header:154
+5d57b56527daf6864c01a1834ce29b05719ec8e8:tests/mcp-e2e.test.ts:curl-auth-header:92
+8a9db83a91a4df8ab4d2422a22f65f080c79e050:tests/activity.test.ts:generic-api-key:143
+8a9db83a91a4df8ab4d2422a22f65f080c79e050:tests/activity.test.ts:generic-api-key:149
+8a9db83a91a4df8ab4d2422a22f65f080c79e050:tests/activity.test.ts:curl-auth-header:146
+5d57b56527daf6864c01a1834ce29b05719ec8e8:VALIDATION-REPORT-2026-07-02.md:curl-auth-header:43
+66eab48d48f66892cbd2dc4a447f6181f31dd70c:packages/openclaw/src/init.ts:generic-api-key:288
+66eab48d48f66892cbd2dc4a447f6181f31dd70c:packages/openclaw/src/init.ts:generic-api-key:318
+1052ae1dcefda24aeb3dfb3880a17b7939bbb30e:packages/openclaw/src/init.ts:generic-api-key:306

.keyoku/architecture.yaml

@@ -0,0 +1,94 @@
+schemaVersion: keyoku.dev/architecture/v1alpha1
+projectId: keyoku
+title: Keyoku proof and attention layer
+updatedAt: 2026-08-15T18:35:00Z
+components:
+  - id: contributors
+    label: People + coding agents
+    summary: Any human, harness, model, or CI process can produce a contribution.
+    layer: execution
+    icon: agent
+    view: { x: 40, y: 250 }
+    external: true
+  - id: outcome-contract
+    label: Outcome contract
+    summary: Repository-owned intent, constraints, proof claims, scope, and human criteria.
+    layer: source
+    icon: git
+    view: { x: 280, y: 70 }
+    owns:
+      - .keyoku/outcomes
+      - docs/FACTFILE-STANDARD.md
+  - id: repository-snapshot
+    label: Exact Git snapshot
+    summary: Base, head, committed diff, worktree digest, changed paths, and outcome history.
+    layer: source
+    icon: git
+    view: { x: 280, y: 300 }
+    owns:
+      - src/contribution.ts
+  - id: project-onboarding
+    label: One-command setup
+    summary: Project detection, starter outcome, and safe GitHub workflow generation.
+    layer: experience
+    icon: plug
+    view: { x: 280, y: 500 }
+    owns:
+      - src/project-profile.ts
+      - tests/project-profile.test.ts
+  - id: proof-evaluator
+    label: Proof evaluator
+    summary: Executes repository-defined observations, fails closed, and separates machine facts from judgment.
+    layer: proof
+    icon: proof
+    view: { x: 520, y: 190 }
+    owns:
+      - src/engine.ts
+      - src/probes.ts
+      - src/assert.ts
+      - tests/contribution.test.ts
+  - id: factfile
+    label: Factfile renderers
+    summary: Canonical JSON plus concise GitHub Markdown, detailed Markdown, HTML, and architecture SVG.
+    layer: proof
+    icon: keyoku
+    view: { x: 760, y: 190 }
+    owns:
+      - src/contribution.ts
+      - src/architecture.ts
+  - id: github
+    label: GitHub pull request
+    summary: Read-only Check summary and downloadable exact-revision proof artifact.
+    layer: experience
+    icon: git
+    view: { x: 1000, y: 70 }
+    external: true
+  - id: human-reviewer
+    label: Accountable reviewer
+    summary: Judges coherence, usability, maintainability, risk, and final acceptance.
+    layer: control
+    icon: human
+    view: { x: 1000, y: 330 }
+    external: true
+relations:
+  - from: contributors
+    to: repository-snapshot
+    kind: changes source
+  - from: outcome-contract
+    to: proof-evaluator
+    kind: defines claims
+  - from: repository-snapshot
+    to: proof-evaluator
+    kind: binds exact scope
+  - from: project-onboarding
+    to: proof-evaluator
+    kind: installs workflow
+  - from: proof-evaluator
+    to: factfile
+    kind: emits evidence
+  - from: factfile
+    to: github
+    kind: attaches summary
+  - from: factfile
+    to: human-reviewer
+    kind: requests judgment

.keyoku/outcomes/archive-abandoned-surfaces.yaml

@@ -0,0 +1,69 @@
+schemaVersion: keyoku.dev/outcome/v1alpha1
+id: archive-abandoned-surfaces
+revision: 1
+title: Abandoned product surfaces leave the active build
+objective: >-
+  Code and positioning that only support the abandoned Omnigent fleet-runner and regulated Outcome
+  Engine directions are recoverably archived, while shared verification, connector, security,
+  learning, and provenance primitives remain active and tested.
+owner:
+  kind: human
+  id: keyoku-owner
+  name: Tye
+  role: accountable product owner
+constraints:
+  - Archive rather than permanently delete historical implementation and tests.
+  - Remove archived code from compilation, packaging, CLI, MCP, and active product promises.
+  - Preserve provider-neutral connectors and autonomy approvals.
+  - Preserve all deterministic goal, probe, assertion, evidence, and workflow-learning behavior.
+criteria:
+  - description: The active TypeScript source and tests contain no Omnigent-specific runtime dependency
+    probe:
+      kind: command
+      run: >-
+        sh -c "! grep -R -i -l omnigent src tests --include='*.ts' | grep -q ."
+      timeoutMs: 30000
+      parse: text
+    assert:
+      path: exitCode
+      op: eq
+      value: 0
+  - description: Legacy source, dedicated tests, and positioning are present with recovery documentation
+    probe:
+      kind: command
+      run: >-
+        sh -c "test -f archive/legacy-omnigent/README.md &&
+        test $(find archive/legacy-omnigent/src -name '*.ts' | wc -l) -eq 5 &&
+        test $(find archive/legacy-omnigent/tests -name '*.ts' | wc -l) -eq 5 &&
+        test -f archive/legacy-positioning/OUTCOME-ENGINE.md &&
+        test -f archive/legacy-positioning/README.md"
+      timeoutMs: 30000
+      parse: text
+    assert:
+      path: exitCode
+      op: eq
+      value: 0
+  - description: CLI and MCP no longer advertise archived fleet-runner commands or tools
+    probe:
+      kind: command
+      run: >-
+        sh -c "npm run build >/dev/null &&
+        ! node dist/index.js help | grep -E 'omnigent|keyoku (run|converge|guardrails|connect)'"
+      timeoutMs: 120000
+      parse: text
+    assert:
+      path: exitCode
+      op: eq
+      value: 0
+  - description: The complete active Keyoku suite passes after archival
+    probe:
+      kind: command
+      run: npm test
+      timeoutMs: 300000
+      parse: text
+    assert:
+      path: exitCode
+      op: eq
+      value: 0
+createdAt: 2026-08-09T00:28:00Z
+updatedAt: 2026-08-09T00:28:00Z