Keyoku v3: revision-bound Factfile and Progress & attention

[tyejcoleman]

Candidate

Exact head: 2e50f91494556adc8910901c8a4848432a7f48f8

This draft assembles the Keyoku v3 modernization candidate while preserving Keyoku's boundary as a harness-neutral assurance layer, not an agent runner or orchestration control plane.

Genuinely functional

• Exact-source Factfiles with verification receipts and source digests
• Stale-proof rejection and explicit recapture
• Progress and attention events with human-decision states
• Local CLI, MCP, JSONL/file, webhook-oriented adapter contracts, and generic EvidenceProvider/WorkEvent conformance fixtures
• Deterministic replay, idempotency, duplicate/conflict handling, and source-bound projections
• Local-first operation without Engine; Engine remains an optional durable service
• macOS mutable-checkout monitoring that distinguishes deferred APFS clone materialization from real content/topology/ownership changes while retaining exact before/after source-state checks

Revision-bound verification

Run from the clean exact head above:

• npm test — 40/40 files, 434/434 tests passed
• npm run typecheck — passed
• npm audit --audit-level=high and npm audit --omit=dev — 0 vulnerabilities
• npm run eval — PASS; precision@1 100%, pitfall surface 100%, false-positive 0%
• npm run preflight — 9/9 candidate checks passed
• keyoku proof ci github-proof-v1 --base 5d57b56527daf6864c01a1834ce29b05719ec8e8 — 8/8 automated claims passed; 4 human decisions correctly remain pending
• repeated fresh local Desktop/APFS clones — 20/20 reached the expected evidence-gap result; 0 mutation-monitor false positives
• exact clean archive install — keyoku-3.0.0-alpha.1.tgz, SHA-256 0a68bfc4653c8d524a92a1e411917d5f940fa360223dce4fa6d4aed99bbe211b
• clean-archive fresh-clone repetition — 5/5 reached the expected evidence-gap result
• adversarial coverage rejects write/restore with mtime reset, chmod/restore in executable probe copies, transient add/delete, ignored-path rename/restore, symlink retarget/restore, byte-identical inode replacement, watcher uncertainty, stale source, and probe mutation

Evidence and release boundaries are documented in:

• docs/SECURITY-REVIEW.md
• docs/PRODUCTION-READINESS.md
• README.md

Mutable-checkout regression and repair

The authentic Claude Code + MCP fixture exposed intermittent false source-changed-during-probes and source-changed-after-capture errors in fresh local macOS clones even when captured/current hashes were identical. APFS was asynchronously normalizing directory metadata and emitting deferred ItemCloned/inode-only events after Git returned.

The repaired monitor now:

• removes directory mtime from source identity while preserving directory object identity;
• runs executable verification only in fresh disposable checkouts outside the source tree;
• uses macOS FSEvents semantics to ignore only clone-materialization signatures while failing closed on content, topology, ownership, overflow, root-change, and watcher uncertainty;
• keeps direct entry monitoring strict after executable-probe setup;
• revalidates exact bytes, paths, modes, inode, size, and mtime after every probe;
• fails transient ignored-path churn closed while excluding only Keyoku's generated ledgers and Git internals; and
• ships an installable macOS watcher dependency from its integrity-locked npm tarball, verified from the exact clean archive.

Honest limitations

• This is an alpha review candidate, not a public-release approval.
• PR CI must pass on this exact head before it can be used for final recorded evidence.
• The concise live Claude Code + Keyoku MCP soak/recording is still pending and will be added only if this exact candidate remains green.
• Final independent acceptance, security reporting, licensing/repository-posture approval, and npm trusted publication remain release gates.
• The current mark is provisional; separate owner-reviewed brand directions are pending.
• Keyoku Engine is separate and is not included in this PR.
• The public README and hosted site remain on the prior version until separately approved merge/deployment steps.

Rollout and rollback

Review this draft and its checks first. A later, separately approved merge/release can promote the exact accepted candidate. Rollback is unchanged: main, the currently published README, the current hosted site, and the existing npm v2 package remain the preserved public version; closing this PR and deleting its branch leaves them untouched.

No package publication, protected-branch merge, license change, repository visibility change, site deployment/access change, or external announcement is performed by this draft.