@sabaiway/agent-workflow-kit 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,80 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 3.0.0 — strip-the-kit: the hardened computed core replaces the ledger machinery (AD-059)
+
+> ### ⚠ BREAKING — the review loop is now computed, not recorded
+>
+> The review-ledger / fold-completeness / verification-profile / sarif / seed-gates tools, their
+> modes, and their git-dir stores are **DELETED**. `run-gates --record` is a usage error (exit 7
+> retired); the loop's ONE receipt is `run-gates --final`. Review receipts without a self-declared
+> `posture` field (any pre-3.0.0/4.0.0 bridge wrapper) **stop satisfying** the review-state gate —
+> fail-closed, like the AD-057 probe marker; re-run the reviews on the refreshed bridges. Node
+> floor is **>= 22** family-wide. The consented `migrate-gates.mjs` migrates an existing
+> `docs/ai/gates.json` (see `migrations/3.0.0-hardened-core-loop.md`).
+
+The MAJOR family release (memory **3.0.0** / engine **2.0.0** / bundled codex bridge **3.0.0** /
+bundled antigravity bridge **4.0.0**; deployment-lineage head **3.0.0**). One theme: **every claim
+the loop makes is computed from artifacts it can re-verify — never remembered, never recorded prose.**
+
+- **The hardened core (new tools):** `core-evidence.mjs` — the ONE git-dir evidence writer
+  (red-proof records with observed-red 3/3 custody + content hashes; explicit per-backend degrade
+  records; the stateless end-of-loop `summary`) · `coverage-check.mjs` — the D3(d) final-run
+  checker (changed-line lcov coverage + red-proof verification + the `lcov-sha256=` machine line) ·
+  `commit-guard.mjs` — the D10 read-only pre-commit (binds a commit to the LATEST green final
+  receipt at the exact tree fingerprint; `--no-verify` stays a stated residual).
+- **`run-gates --final`:** canonical realpath-anchored core checks (review-state + coverage-check,
+  checker LAST), evidence-store drift teeth, the checker-bound lcov sha with an end re-hash, ONE
+  attempt-linked receipt (green/red DERIVED, integrity failures explicit), `AW_GIT_DIR` exported
+  to every gate child on every run.
+- **`review-state` D3(b):** ship-class-only on the latest NORMAL receipt; a recognized negative is
+  an authoritative VETO; unknown verdicts, probe-marked, unmarked, posture-less, and malformed
+  receipts never attest (each with its stated recovery); explicit degrade records are the only
+  escape and never all backends.
+- **Consumer lanes:** `gates-init.mjs` (D9 consented fill preview; the coverage-check candidate
+  appended LAST so a whole-offer apply is final-run-ready) · `migrate-gates.mjs` (D8, mirrored
+  from the memory canon: canonical-anchor matching with move/collision semantics, the full lcov
+  reporter flag set, retired-store cleanup, symlink/control-byte STOPs) · the hook installer's
+  explicit `--commit-guard <path>` arm with strict carry-forward · a `commit-guard`
+  Recommendations item gated on final-run-capability.
+- **Bundled bridges (D4/D5):** a verdict-less review run exits 4 with NO receipt (exact agy
+  `### Verdict` parse; structural top-level JSON verdict in codex schema mode); one stderr banner
+  states the ACTUAL dispatch posture and every receipt records the same `posture{}`; control-byte
+  and unknowable-model postures refuse pre-spend. Manifests carry VALIDATED posture pins; the kit
+  renders the CONFIGURED posture (pins + the bridge-settings tier overlay) in the backend status
+  line, drift-guarded end to end (`posture-parity`).
+- **Suite economics note:** the supervisory ledger cluster (~98% of the old 94s unit matrix) is
+  gone with its machinery; the dedicated speedup pass (plan Phase 5) follows post-release.
+
+## 2.1.0 — agy code review fails CLOSED pre-spend: grounded facts required, `--ungrounded` is the explicit escape (AD-058)
+
+> ### ⚠ the bundled antigravity bridge takes MAJOR 3.0.0 — bare `agy-review code` now refuses
+>
+> `agy-review code` without a NON-EMPTY `--facts` payload exits 2 **before spending a run**
+> (previously: a loud warning, then a spent subscription run whose `grounded:false` receipt the
+> review-state gate rejects — a guaranteed-wasted spend). Scripts calling bare `agy-review code`
+> must add `--facts @f` (grounded) or `--ungrounded` (explicit throwaway opinion; the receipt still
+> records `grounded:false` and never attests). `plan`/`diff` modes and continuations are unchanged.
+> The kit itself is a MINOR carrier — the incompatibility is created, and declared, by the bridge.
+
+A **fail-closed** release (kit MINOR carrying antigravity-cli-bridge **3.0.0** MAJOR in-tarball;
+codex-cli-bridge 2.8.0 / engine 1.17.0 / memory 2.3.0 unchanged; the deployment-lineage head stays
+`2.0.0`). One theme: **a run that cannot produce a usable result refuses before the money is spent.**
+
+- **The refusal prints the recovery:** the exact `grounding.mjs` invocation — resolved from the
+  wrapper's own location across the three real install layouts (monorepo canon / deployed skills
+  sibling / kit-bundled mirror), quoted so an install path with spaces still yields a runnable
+  command — plus the `agy-review code --facts @<file>` re-run line.
+- **Escapes, both honest:** `--ungrounded` (code-mode only, contradicts `--facts`, refused on a
+  continuation) and `AGY_PROBE=1` (a probe may now run ungrounded — a probe receipt never attests
+  either way; its `modeCatalog` descriptor now marks the facts file optional).
+- **Every declaration home moves in lockstep** (drift-guarded both directions): `--help` ⟷
+  `capability.json` (`roles.review.contract` + `modeCatalog` `review.code` operands/guardrails +
+  the `AGY_PROBE` env-hook) ⟷ the kit registry mirror (`tools/detect-backends.mjs`) ⟷ `SKILL.md` ⟷
+  `references/driving-agy.md` / `models-and-flags.md` / `review-prompt.md`.
+- **Receipt contract scoped honestly:** in `code` mode an absent/empty facts payload now means NO
+  run and NO receipt; the `grounded:false`-on-empty clause applies to `plan`/`diff` only.
+
 ## 2.0.0 — Bridge mode catalog (manifest-as-source) + a review receipt that SELF-DECLARES (AD-057)
 
 > ### ⚠ BREAKING — a review receipt written before this release no longer attests a tree

package/README.md

@@ -13,7 +13,7 @@ decisions. Works with Claude Code, Codex, Cursor, and any agent that reads `AGEN
 [![license](https://img.shields.io/npm/l/@sabaiway/agent-workflow-kit)](./LICENSE)
 [![node](https://img.shields.io/node/v/@sabaiway/agent-workflow-kit)](https://nodejs.org)
 
-`Node ≥ 18`  ·  `dependency-free scripts`  ·  `no telemetry in family code`
+`Node ≥ 22`  ·  `dependency-free scripts`  ·  `no telemetry in family code`
 
 **One command to start:**
 
@@ -229,7 +229,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps — then prints a **read-only** one-line backend-status line (what's set up vs missing); refreshes the already-placed bridges from the kit's bundled copies (never installs a new one — set one up with `/agent-workflow-kit setup`) |
 | `/agent-workflow-kit help` | any time | **read-only command index** — every command, grouped (Inspect / Configure / Orchestrate / Lifecycle) and tagged read-only / writer / guarded. The discoverable entry point, and where any unrecognized invocation lands (always read-only — a garbage invocation never writes). Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit backends` | any time | **read-only** check of the optional execution-backends (the `codex` / `agy` bridges): what's set up vs missing and the next step. Never writes, never commits, never runs a subscription CLI (credentials = marker-file presence, not a live login). |
-| `/agent-workflow-kit gates` | any time | **project gate runner** — runs the verification commands **your project itself declares** in `docs/ai/gates.json` (seeded at deploy; hand-editable `{ id, title, cmd }` entries, each `cmd` one bash line) as one batch: a per-gate **PASS/FAIL table** + one machine-readable summary line, exit 0 iff all green; a failing gate's own output is shown verbatim; `--only <id>` re-runs one. Honest distinct outcomes for a missing / empty / malformed declaration — never a silent green. The runner writes nothing **by default** and never commits — opt-in `--record` mints ONE `gate-run` record into the review ledger **via the ledger's sole writer** (the segment's green-baseline receipt: full declaration + what ran + pre/post tree fingerprints; a red run records honestly; a failed record is its own loud exit 7); it executes only your own declared commands (a batching convenience, not a sandbox). The velocity tier auto-approves only the exact no-`--record` form — the recording run stays explicit. |
+| `/agent-workflow-kit gates` | any time | **project gate runner** — runs the verification commands **your project itself declares** in `docs/ai/gates.json` (seeded at deploy; hand-editable `{ id, title, cmd }` entries, each `cmd` one bash line) as one batch: a per-gate **PASS/FAIL table** + one machine-readable summary line, exit 0 iff all green; a failing gate's own output is shown verbatim; `--only <id>` re-runs one. Honest distinct outcomes for a missing / empty / malformed declaration — never a silent green. The runner writes nothing **by default** and never commits — opt-in `--final` runs the FULL declared matrix and mints ONE final-run receipt into the git-dir core-evidence store (status green/red, pre/post tree fingerprints, the declaration, the consumed lcov's sha; the receipt the commit-guard binds); it executes only your own declared commands (a batching convenience, not a sandbox). The velocity tier auto-approves only the exact no-`--final` form — the recording run stays explicit. |
 | `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit status` | any time | **read-only** single view of **versions + deployment + settings + bridges**: which members (kit / memory / engine / the two bridges) are installed and at what version (with an honest "installed on this machine" note when one is behind) and — in a project — what's deployed (`docs/ai`, the version stamps, and the **visibility**: visible / hidden / unclear), plus your settings (orchestration recipes, attribution, velocity) and the bridges' readiness. The two version axes (package number vs deployment-structure head) stay decoupled. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents four named recipes for composing the bridges into plan → execute → review — **Solo / Reviewed / Council / Delegated** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready), and offers the choice. The orchestrator runs it via the bridge skills and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
@@ -237,9 +237,10 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend, never commits**; hand-editing stays fully supported. |
 | `/agent-workflow-kit review-state` | any time | **read-only review-receipt checker** — makes "reviewed ≠ shipped" detectable: the bridge review wrappers append a receipt per successful review (into a file inside the git dir — never committable); this checks that every backend your configured `plan-execution.review` recipe names holds a **fresh, grounded receipt for the current uncommitted tree** (any later edit moves the fingerprint and stales the receipt; a review continuation never re-attests a folded tree). `--check` gives a gate exit code to declare in `docs/ai/gates.json` **by hand or via the consent-gated seeder** (preview → your explicit yes; never without consent). `--await [--timeout <s>]` (AD-049) BLOCKS until every recipe-named backend has receipted the current tree — the durable completion signal is the receipt, never a process event — so you wait for the bridges instead of hand-polling. Never writes, never commits, never runs a subscription CLI; it spawns read-only `git` queries to fingerprint the tree — and `git commit --no-verify` stays possible (discipline, not a sandbox). |
 | `/agent-workflow-kit sandbox-masks` | any time | **cosmetic exclude lane for sandbox device masks** — an OS sandbox (Claude Code) injects character-device masks into the work tree as untracked `git status` noise; the review domain already ignores them **by construction** (never-committable untracked classes — char/block devices, FIFOs, sockets — are excluded from the fingerprint, the assembled review payload, and the clean checks). This mode hides them from `git status` too: flagless = read-only probe (derives the CURRENT mask set from the unfiltered walk + lstat — never a frozen list — and revalidates fenced entries, loudly flagging one that became a real path); `--apply` = consent-gated FULL-BLOCK replace of its own fenced block in `git rev-parse --git-path info/exclude` (stale masks drop by construction; `--clear` always means REMOVE the block — it takes precedence over the derivation). Writes ONLY its fence — never `.gitignore`, never global config; symlinked/non-regular exclude paths and malformed fences fail closed. Watch note: a real file at an excluded path is silently skipped by bulk staging (`git add -A`/`git add .`) — delete the stale line first; the probe flags exactly this case. |
-| `/agent-workflow-kit grounding` | any time | **grounded-review facts assembler** — mechanizes populating `agy-review --facts @f`: slices your entry-point's **Hard Constraints** section verbatim (exactly one match, else a loud stop) and/or a plan's decision-bearing sections (`## Approach` + `## Verification` required, `## Decisions (locked)` when present; duplicates stop), under the same byte budget the agy wrapper enforces (minus `--reserve-bytes` for the artifact share), with a loud tail-trim on overflow. `--autonomy` (AD-044) appends the COMPUTED effective autonomy policy from the git-top `docs/ai/autonomy.json` (every red-line + per-activity level, stated source line; absent file → the computed defaults ARE the policy, exit 0; a malformed policy fails CLOSED, exit 1). `--ledger-summary` (AD-049) appends a COMPUTED review-ledger digest for the single in-flight segment (rounds · origins · classifications · verdicts · overrides — unrelated loops excluded), so the reviewer sees the loop's own history without hand-copying. Prints to stdout; `--out` writes **one scratch file only** — system-temp outside the repo ($TMPDIR / /tmp, rewritable) or a **fresh** gitignored in-repo path (create-only, exclusive write; an existing in-repo file, even gitignored, is refused — the `.env` clobber class); tracked, not-ignored-in-repo, other outside-repo, and symlink/non-regular destinations are all refused. Never commits, never runs a subscription CLI. |
-| `/agent-workflow-kit review-ledger` | any time | **review-round ledger** — turns the review-loop stop rule into a **computed** signal: record each plan-execution review round, its triage, and any recorded **overrides** (`oracle-change` lifts named tampered test files; `red-proof` waives the observed-red proof for exactly one `testId`; v4 adds **`size-cap`** — the exact sanctioned magnitude for a surface over the diff cap, segment-scoped — all loud, durable, auditable waivers, never silent) into a JSONL ledger inside the git dir (never committable), and read the stop decision (`converged > resolved-residual > triage-required > continue`) from the records — never from a remembered rule. **Since v4 every record carries `base` = the HEAD commit and the whole loop is SEGMENT-scoped (AD-048):** round numbering, the caps, and every tooth reset ONLY at a gated commit — a multiphase plan records fully while round 4 within one segment stays refused; `gate-run` records (minted by `gates --record`) make gates-before-review a computed precondition; the triage class **`refuted`** is the honest phantom-finding lane (grounds mandatory); `--telemetry` renders counts-only gate-efficacy data across all loops and both ledgers. `--status` replaces the hand-composed per-round tally; `record --from-receipts` (AD-049) DRAFTS the `backends[]` from the current-fingerprint receipts (verdict per backend, counts from the supplied findings) instead of hand-composing them — a recipe-named backend with no receipt is a loud stop; a **`batch`** verb applies an ordered list of record/classify/override ops in ONE writer call (the prompt-economy lane — the whole envelope is validated structurally first with zero writes, then ops apply sequentially and fail-fast; prior ops stay recorded, append-only); `--check` is a fail-closed gate exit code for `docs/ai/gates.json` (by hand or via the consent-gated seeder). A `fixable-bug` triage **requires its red→green `testId`** (v1..v3 records stay valid on read — old records never enter a segment). The writer refuses a round (past the hard-max, while a triage is pending, or lacking a grounded review receipt) and refuses an override outside its single in-flight loop. Honest residual: records are forgeable — self-discipline, not a security boundary. Never commits, never runs a subscription CLI. |
-| `/agent-workflow-kit fold-completeness` | any time | **fold-completeness gate** — attests the review loop's folded fixes were proven the HONEST way (no fix theater): the runner executes your suite ONCE under `NODE_V8_COVERAGE`, checks every changed executable line is **executed**, probes every bound `testId` N times (`AW_FOLD_RERUNS`), records content hashes, and scans the test surface for tamper; the `--red` verb observes a test FAILING on the pre-fold tree — **BEFORE the fix** — and mints an **observed-red receipt**. The read-only checker (`--status` / `--check`) then requires, per bound test: the receipt, receipt-precedes-run order, N/N-green probes, and content **custody** (the green test is byte-identical to the one seen failing) — the receipt+custody half waivable for exactly one `testId` by a recorded `red-proof` override; mixed/timed-out probes are QUARANTINE (never converted, no override); **v3 records carry `base` and the proof is segment-scoped (AD-048)** — a committed phase's custody obligations close with its commit, and a receipt never crosses a commit boundary; tampered pre-existing test files fail closed unless covered by a recorded `oracle-change` override. Honest residuals: coverage proves **execution, not assertion**, and records are forgeable — self-discipline, not a security boundary. v1 scope is JS/V8 (pluggable via `AW_FOLD_BOUND_CMD`): changed TS/JSX fails closed, docs/config changes are listed but never block, and **no mutation testing ships**. Wire the gate by hand — the consent-gated seeder deliberately does not offer it yet (JS-only hold). Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit grounding` | any time | **grounded-review facts assembler** — mechanizes populating `agy-review --facts @f`: slices your entry-point's **Hard Constraints** section verbatim (exactly one match, else a loud stop) and/or a plan's decision-bearing sections (`## Approach` + `## Verification` required, `## Decisions (locked)` when present; duplicates stop), under the same byte budget the agy wrapper enforces (minus `--reserve-bytes` for the artifact share), with a loud tail-trim on overflow. `--autonomy` (AD-044) appends the COMPUTED effective autonomy policy from the git-top `docs/ai/autonomy.json` (every red-line + per-activity level, stated source line; absent file → the computed defaults ARE the policy, exit 0; a malformed policy fails CLOSED, exit 1). Prints to stdout; `--out` writes **one scratch file only** — system-temp outside the repo ($TMPDIR / /tmp, rewritable) or a **fresh** gitignored in-repo path (create-only, exclusive write; an existing in-repo file, even gitignored, is refused — the `.env` clobber class); tracked, not-ignored-in-repo, other outside-repo, and symlink/non-regular destinations are all refused. Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit core-evidence` | any time | **the ONE loop-evidence writer** (strip-the-kit) — every core evidence record lands in a single append-only JSONL store inside the git dir (never committable; versioned schema, latest-per-key supersession, byte-identical duplicates refused, malformed lines fail every reader closed). `red-proof "<file>#<pattern>"` declares an observed-red **BEFORE a bugfix** (N/N red runs + content custody + base + the pre-fix fingerprint; green/mixed/timeout are DISTINGUISHED refusals — nothing written); `degrade --backend --reason` is the ONLY escape for an unavailable review backend (per-tree, never all backends); `summary` renders the whole loop state statelessly (gate result · per-backend verdicts · red-proofs · degrades) — no ledger, no rounds, nothing remembered. Honest residual: records are forgeable — self-discipline, not a security boundary. Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit coverage-check` | any time | **the final-run checker** (D3(c)+(d)) — reads the lcov the declared `unit-tests` gate produced at the FIXED git-dir path and fails on any uncovered CHANGED executable Node line (listed `file:line`; a changed file absent from the map is a file-level red; out-of-domain/unsupported files are LISTED — the claim narrowed honestly); VERIFIES every current-base red-proof declaration (bound test exists · custody hash unchanged · green N/N now · pre-fix fingerprint differs); prints `lcov-sha256=<hex|none>` of the exact bytes it consumed — the sha the `--final` receipt binds and re-hashes. An absent lcov is a LOUD `skipped-no-lcov`; a symlinked path is a refusal. `--check` is the gate exit code — declare it as the LAST gate (`run-gates --final` refuses otherwise). Read-only. |
+| `/agent-workflow-kit commit-guard` | any time | **the read-only pre-commit guard** (D10) — binds the LATEST completed `run-gates --final` receipt to the EXACT current tree: refuses on a missing/red/stale receipt, fingerprint drift under the run, a dangling later attempt, declaration content drift, evidence-hash or lcov drift, or unsatisfied review obligations (the same review-state decision, recomputed over a sanitized env — forged out-of-repo stores never satisfy). Re-runs NO gate or test. Wire it into `.git/hooks/pre-commit` (the installer writes the RESOLVED invocation). `git commit --no-verify` stays the stated residual. |
 | `/agent-workflow-kit recommendations` | any time (every `upgrade` ends with it) | **read-only deployment advisor** (AD-044) — computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, OS sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe) and renders **verdict-first**: one composed verdict line (does anything need attention?), then each item as **{severity · what · one-line benefit · an optional `recipe:` line (sandbox-lane only) · the exact consent-gated apply one-liner}**. The agent PRESENTS the section in the user's conversational language — every fact and count, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request — and runs EXACTLY the rendered one-liners only on your yes, surfacing each item's posture note first. Renders **present-even-when-empty** (`no recommendations — flow optimal.`); a failed probe degrades to a stated skip line. Registry strings are fact-true frozen one-line data (posture/risk notes live in the mode doc at the consent moment); the kit never seeds `sandbox.network.allowedDomains` / `filesystem.allowWrite` (**HAND-APPLY** territory), and the sandbox-lane item's convergence is a neutral fingerprint acknowledgement recorded by a consent-gated ack writer into `docs/ai/acks.json` — never a security key (the recipe is documented per bridge in `capability.json` `networkHosts` + `writableDirs`). `--cwd` is required (the target project is explicit); never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit doc-parity` | any time | **read-only doc-parity lint** (AD-049) — kills the doc-drift class where a mode-contract doc silently lags a code constant (a `--check` doc still reading `300` after the diff cap moved to `400`): a **closed, exported registry** binds each live constant (review caps, schema versions, the ledger's own class/scope vocabulary, and the autonomy-doctor EXIT/status/trusted-dir contract) to the exact token its `references/modes/*.md` contract must carry, and asserts the CURRENT value renders into every bound file — a drifted doc, an unreadable file, or an absent token **fails closed**. The values are sourced from the live imports (never re-typed), so the lint can't itself go stale; adding a binding is adding a checked entry (closed-world, edit-safe). `--check` is a gate exit code for `docs/ai/gates.json`. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '2.0.0'
+  version: '3.0.0'
 ---
 
 # agent-workflow-kit
@@ -71,14 +71,14 @@ Pick the mode from the user's invocation — the mapping is pinned by `tools/com
 Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide the route — an **internal** routing decision, **not** a line you print (version display: *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`). Route:
 
 - **absent** → bootstrap (a fresh deployment).
-- **stamp < `2.0.0`** (the deployment-lineage head) → `upgrade`.
-- **stamp == `2.0.0`** → already current; only the stamp-independent reconciles may run — the FULL set lives in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3; run step 3 (never enumerate the reconciles from memory).
+- **stamp < `3.0.0`** (the deployment-lineage head) → `upgrade`.
+- **stamp == `3.0.0`** → already current; only the stamp-independent reconciles may run — the FULL set lives in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3; run step 3 (never enumerate the reconciles from memory).
 - **stamp > head / unparseable** → STOP — never-downgrade gate (see `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 2).
 - **Exempt:** `autonomy-doctor` provisions the OS, not the deployment — stamp-independent (stated in its mode file).
 
 **Two independent version axes — never conflate them:**
 
-1. **Project deployment** — `docs/ai/.workflow-version` vs the lineage head (`2.0.0`). This is the **only** axis this skill compares.
+1. **Project deployment** — `docs/ai/.workflow-version` vs the lineage head (`3.0.0`). This is the **only** axis this skill compares.
 2. **Kit freshness** — this skill's own files vs the published npm package. That is the **npx installer's** job: `npx @sabaiway/agent-workflow-kit@latest init` (it refuses a stale-cache downgrade by comparing the version on disk — **no network**). This skill never checks npm, and the package version is **not** the lineage head.
 
 **Refreshed the kit but nothing changed?** After the npx installer updates `~/.claude/skills/agent-workflow-kit/`, **restart the session** so the agent reloads the new skill files.
@@ -171,13 +171,17 @@ read-only — read `${CLAUDE_SKILL_DIR}/references/modes/review-state.md` before
 
 writer — read `${CLAUDE_SKILL_DIR}/references/modes/grounding.md` before acting.
 
-### Mode: review-ledger
+### Mode: core-evidence
 
-writer — read `${CLAUDE_SKILL_DIR}/references/modes/review-ledger.md` before acting.
+writer — read `${CLAUDE_SKILL_DIR}/references/modes/core-evidence.md` before acting.
 
-### Mode: fold-completeness
+### Mode: coverage-check
 
-writer — read `${CLAUDE_SKILL_DIR}/references/modes/fold-completeness.md` before acting.
+project-exec — read `${CLAUDE_SKILL_DIR}/references/modes/coverage-check.md` before acting.
+
+### Mode: commit-guard
+
+read-only — read `${CLAUDE_SKILL_DIR}/references/modes/commit-guard.md` before acting.
 
 ### Mode: doc-parity
 

package/bin/install.mjs

@@ -28,7 +28,7 @@
 // them from this package's own bundled copies — a purely LOCAL copy, no third server contact —
 // skippable with `--no-bridges`. No tracking either way.
 //
-// Dependency-free, Node >= 18.
+// Dependency-free, Node >= 22.
 
 import { readFile, mkdir, rm } from 'node:fs/promises';
 import { existsSync, lstatSync, realpathSync } from 'node:fs';

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: antigravity-cli-bridge
 description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its no-JSON headless behaviour.
 metadata:
-  version: '2.7.0'
+  version: '4.0.0'
 ---
 
 # antigravity-cli-bridge
@@ -118,15 +118,27 @@ review **guesses** (stale-model and partial-diff false positives). `agy-review`
 POSTURE + a **model/cutoff GUARD** + your **`--facts`** (the verified facts the model reviews AGAINST)
 + **`--decided`** (the anti-circling list) + **`--focus`** + the artifact + a strict output shape, then
 delegates execution to `agy-run` (one home for the timeout, the subscription invariant, and the byte
-ceiling).
+ceiling). In `code` mode grounding **fails closed**: without a non-empty `--facts` payload the wrapper
+refuses **before spending a run** (an ungrounded code receipt records `grounded:false`, which the
+review-state gate rejects — the run would attest nothing). The explicit escapes are `--ungrounded`
+(a throwaway opinion) and `AGY_PROBE=1` (a probe never attests anyway); `plan`/`diff` keep the loud
+warning and proceed.
 
 ```bash
-agy-review code [--facts @facts.md] [--decided @decided.md] [--focus "…"]   # the repo-complete diff
-agy-review plan <plan-file> [--facts @f] …      # critique a plan
+agy-review code --facts @facts.md [--decided @decided.md] [--focus "…"]   # the repo-complete diff (facts REQUIRED — fails closed pre-spend)
+agy-review code --ungrounded                    # explicit escape: throwaway ungrounded opinion (receipt never attests)
+agy-review plan <plan-file> [--facts @f] …      # critique a plan (no facts ⇒ loud warning)
 agy-review diff <diff-file> [--facts @f] …      # review a supplied diff
 agy-review --continue --decided @round1.md --focus "still-open items"   # round-2 delta, no re-assembly
 ```
 
+**Honesty + posture (D4/D5):** a run with no recognized `### Verdict` section — empty output
+included — **exits 4 with NO receipt**: treat it as a *failed review to re-run*, never a fatal
+session error. One stderr banner states the actual posture (`review posture: model=…`) and the
+receipt records the same `posture {model}`; an attesting review with `AGY_MODEL` explicitly
+emptied refuses pre-spend (`AGY_PROBE=1` exempt), and control bytes in a model string refuse
+pre-spend in every mode.
+
 Frontier default `Gemini 3.1 Pro (High)`; **any** model is allowed (a sub-frontier one earns a
 silenceable `AGY_PROBE=1` advisory). An oversized `code` review trips the byte ceiling with trim/split
 guidance; `AGY_REVIEW_ALLOW_ADDDIR=1` offloads only the change set to a private `--add-dir` staging dir

package/bridges/antigravity-cli-bridge/bin/agy-review-honesty.test.mjs

@@ -0,0 +1,150 @@
+// agy-review-honesty.test.mjs — the round-1 hardening pins for the D4/D5 arms (strip Phase 4):
+// the verdict parse is EXACT (an inexact heading or a token buried mid-line never attests —
+// `NOT SHIP` must not read as SHIP), and the empty-AGY_MODEL pre-spend refusal is scoped to the
+// ATTESTING branch only (plan / diff / --ungrounded code never attest, so they run and record
+// posture.model null). Colocated separately from agy-review.test.mjs — that file is
+// red-proof-frozen; this one carries its own minimal standalone harness (the family idiom).
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, chmodSync, existsSync, readdirSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WRAPPER = join(HERE, 'agy-review.sh');
+
+const FAKE_AGY = [
+  '#!/usr/bin/env bash',
+  'set -u',
+  'printf invoked > "${AGY_FAKE_SENTINEL:-/dev/null}"',
+  'printf "%s\\n" "${AGY_FAKE_OUTPUT:-### Verdict}"',
+  'exit 0',
+  '',
+].join('\n');
+
+const makePathWithout = (root, exclude = []) => {
+  const skip = new Set(exclude);
+  const dir = mkdtempSync(join(root, 'nobin-'));
+  for (const d of (process.env.PATH || '').split(':').filter(Boolean)) {
+    let names;
+    try { names = readdirSync(d); } catch { continue; }
+    for (const name of names) {
+      if (skip.has(name)) continue;
+      const link = join(dir, name);
+      if (existsSync(link)) continue;
+      try { symlinkSync(resolve(d, name), link); } catch { /* dup / race — ignore */ }
+    }
+  }
+  return dir;
+};
+
+const makeSandbox = () => {
+  const home = mkdtempSync(join(tmpdir(), 'agy-honesty-'));
+  const bin = join(home, '.local', 'bin');
+  mkdirSync(bin, { recursive: true });
+  writeFileSync(join(bin, 'agy'), FAKE_AGY, { mode: 0o755 });
+  chmodSync(join(bin, 'agy'), 0o755);
+  const repo = join(home, 'repo');
+  mkdirSync(repo);
+  const g = (...args) => spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
+  g('init', '-q');
+  g('config', 'user.email', 'probe@example.com');
+  g('config', 'user.name', 'probe');
+  writeFileSync(join(repo, 'base.txt'), 'committed base\n');
+  g('add', '-A');
+  g('commit', '-qm', 'base');
+  writeFileSync(join(repo, 'pending.txt'), 'PENDING\n');
+  writeFileSync(join(repo, 'plan.md'), '# a plan artifact\n');
+  return { home, bin, repo };
+};
+
+const run = (sb, { args, env = {} } = {}) => {
+  const sentinel = join(sb.home, 'cap-sentinel');
+  const r = spawnSync('bash', [WRAPPER, ...args], {
+    cwd: sb.repo,
+    encoding: 'utf8',
+    timeout: 30000,
+    env: {
+      HOME: sb.home,
+      PATH: `${sb.bin}:${makePathWithout(sb.home, ['agy', 'agy-run'])}`,
+      TMPDIR: process.env.TMPDIR ?? '/tmp',
+      AGY_FAKE_SENTINEL: sentinel,
+      ...env,
+    },
+  });
+  return { ...r, invoked: existsSync(sentinel) };
+};
+
+const readReceipts = (repo) => {
+  const p = join(repo, '.git', 'agent-workflow-review-receipts.jsonl');
+  if (!existsSync(p)) return [];
+  return readFileSync(p, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+};
+
+describe('agy-review — the verdict parse is EXACT (M1): a buried token never attests', () => {
+  it('`NOT SHIP` on the verdict line is a FAILED run — never a SHIP receipt', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: '### Verdict\nNOT SHIP — blocked.' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0, 'NOT SHIP must never read as SHIP');
+    assert.equal(receipts.length, 0);
+  });
+
+  it('an INEXACT heading (`### Verdicts`) never parses — the D4 failed-run arm owns it', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: '### Verdicts\nSHIP — but under the wrong heading.' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0);
+    assert.equal(receipts.length, 0);
+  });
+
+  it('a WORD-PREFIX (`SHIPPING it`) never matches; punctuation forms (`SHIP.` / `SHIP — …`) do', () => {
+    const sb1 = makeSandbox();
+    const bad = run(sb1, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_OUTPUT: '### Verdict\nSHIPPING it today.' } });
+    const badReceipts = readReceipts(sb1.repo);
+    rmSync(sb1.home, { recursive: true, force: true });
+    assert.notEqual(bad.status, 0, 'SHIPPING is not in the closed vocabulary');
+    assert.equal(badReceipts.length, 0);
+    for (const [out, want] of [['### Verdict\nSHIP.', 'SHIP'], ['### Verdict\nSHIP — clean.', 'SHIP'], ['### Verdict\nSHIP WITH NITS — two nits.', 'SHIP WITH NITS']]) {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_OUTPUT: out } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(receipts[0].verdict, want);
+    }
+  });
+});
+
+describe('agy-review — the empty-model refusal is scoped to the ATTESTING branch (M3)', () => {
+  it('plan and diff modes with AGY_MODEL= RUN (never attest) and record posture.model null', () => {
+    for (const args of [['plan', 'plan.md'], ['diff', 'plan.md']]) {
+      const sb = makeSandbox();
+      const r = run(sb, { args, env: { AGY_MODEL: '', AGY_FAKE_OUTPUT: '### Verdict\nSHIP — fine.' } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, `${args[0]} must run with an emptied model: ${r.stderr}`);
+      assert.equal(r.invoked, true);
+      assert.deepEqual(receipts[0].posture, { model: null }, 'an unknowable model is recorded null');
+    }
+  });
+
+  it('code --ungrounded with AGY_MODEL= RUNS (its receipt never attests); grounded code still refuses', () => {
+    const sb = makeSandbox();
+    const un = run(sb, { args: ['code', '--ungrounded'], env: { AGY_MODEL: '', AGY_FAKE_OUTPUT: '### Verdict\nSHIP — throwaway.' } });
+    const unReceipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(un.status, 0, un.stderr);
+    assert.deepEqual(unReceipts[0].posture, { model: null });
+    const sb2 = makeSandbox();
+    const grounded = run(sb2, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_MODEL: '' } });
+    rmSync(sb2.home, { recursive: true, force: true });
+    assert.notEqual(grounded.status, 0, 'the ATTESTING branch still refuses pre-spend');
+    assert.equal(grounded.invoked, false);
+  });
+});

package/bridges/antigravity-cli-bridge/bin/agy-review-model-screen.test.mjs

@@ -0,0 +1,76 @@
+// agy-review-model-screen.test.mjs — the round-2 ordering pin (strip Phase 4, M6): the
+// control-byte screen fires IMMEDIATELY after AGY_MODEL resolution — BEFORE the off-frontier
+// advisory (or any other interpolation) can echo raw control bytes into stderr/the terminal.
+// Colocated separately: both earlier agy spec files are red-proof-frozen. Standalone harness.
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, chmodSync, existsSync, readdirSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WRAPPER = join(HERE, 'agy-review.sh');
+
+const FAKE_AGY = '#!/usr/bin/env bash\nset -u\nprintf invoked > "${AGY_FAKE_SENTINEL:-/dev/null}"\nprintf "### Verdict\\nSHIP\\n"\nexit 0\n';
+
+const makePathWithout = (root, exclude = []) => {
+  const skip = new Set(exclude);
+  const dir = mkdtempSync(join(root, 'nobin-'));
+  for (const d of (process.env.PATH || '').split(':').filter(Boolean)) {
+    let names;
+    try { names = readdirSync(d); } catch { continue; }
+    for (const name of names) {
+      if (skip.has(name)) continue;
+      const link = join(dir, name);
+      if (existsSync(link)) continue;
+      try { symlinkSync(resolve(d, name), link); } catch { /* dup / race — ignore */ }
+    }
+  }
+  return dir;
+};
+
+describe('agy-review — the control-byte screen precedes EVERY interpolation of AGY_MODEL (M6)', () => {
+  it('a control-byte NON-frontier model refuses pre-spend with NO advisory echo and NO raw byte on stderr', () => {
+    const home = mkdtempSync(join(tmpdir(), 'agy-model-screen-'));
+    const bin = join(home, '.local', 'bin');
+    mkdirSync(bin, { recursive: true });
+    writeFileSync(join(bin, 'agy'), FAKE_AGY, { mode: 0o755 });
+    chmodSync(join(bin, 'agy'), 0o755);
+    const repo = join(home, 'repo');
+    mkdirSync(repo);
+    const g = (...args) => spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
+    g('init', '-q');
+    g('config', 'user.email', 'probe@example.com');
+    g('config', 'user.name', 'probe');
+    writeFileSync(join(repo, 'base.txt'), 'base\n');
+    g('add', '-A');
+    g('commit', '-qm', 'base');
+    writeFileSync(join(repo, 'pending.txt'), 'PENDING\n');
+    const sentinel = join(home, 'cap-sentinel');
+    const r = spawnSync('bash', [WRAPPER, 'code', '--facts', 'a tiny fact'], {
+      cwd: repo,
+      encoding: 'utf8',
+      timeout: 30000,
+      env: {
+        HOME: home,
+        PATH: `${bin}:${makePathWithout(home, ['agy', 'agy-run'])}`,
+        TMPDIR: process.env.TMPDIR ?? '/tmp',
+        AGY_FAKE_SENTINEL: sentinel,
+        AGY_MODEL: `hostile${String.fromCharCode(27)}model`, // ESC — a terminal-control byte
+      },
+    });
+    const invoked = existsSync(sentinel);
+    const receiptsPath = join(repo, '.git', 'agent-workflow-review-receipts.jsonl');
+    const receipts = existsSync(receiptsPath) ? readFileSync(receiptsPath, 'utf8').trim() : '';
+    rmSync(home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0, 'a control-byte model refuses pre-spend');
+    assert.equal(invoked, false, 'agy is never invoked');
+    assert.equal(receipts, '', 'no receipt is minted');
+    assert.match(r.stderr, /control/i, 'named as the control-byte class');
+    assert.doesNotMatch(r.stderr, /non-frontier model/, 'the advisory never fires on a value the screen must refuse');
+    assert.ok(!r.stderr.includes(String.fromCharCode(27)), 'no raw control byte ever reaches stderr');
+  });
+});