@sabaiway/agent-workflow-kit 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.4.0 — review-state names a latent arm on a clean-tree PASS (AD-064)
+
+`review-state --check` under a configured `reviewed` or `council` recipe on a clean tree no longer
+returns a bare `PASS — nothing to review`. It now NAMES every plan still in flight and states the
+forward consequence — `this gate arms as soon as the
+tree is dirty` — so a spent boot prompt left under a bare name is discoverable BEFORE it blocks,
+instead of surfacing at the worst moment: a pending commit, or the landing of a feature worktree when
+main first turns dirty. The quiet case (configured `solo`, no plan in flight, a non-git cwd) still
+passes silently through the earlier-returning arms; dirty-tree behaviour is unchanged. A `doc-parity`
+binding pins the
+live notice to `references/modes/review-state.md`, so a reworded doc that drops it fails the gate — a
+prose-only bar becomes a mechanism. This is the safe, converged slice of the deferred parallel-track
+work (AD-063), shipped on its own with no worktrees-ownership coupling.
+
 ## 3.3.0 — version-pin honesty: the profile stops claiming a limit it never observed (AD-062)
 
 `velocity --autonomy` told every user their credentials could not be protected by the sandbox —

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: '3.3.0'
+  version: '3.4.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/review-state.md

@@ -5,7 +5,7 @@ Read-only **review-receipt checker** (AD-038) — it makes *"reviewed ≠ shippe
 Run `node ${CLAUDE_SKILL_DIR}/tools/review-state.mjs [--check] [--json]`:
 
 1. Plain run → the human report: resolved recipe + source, plan-in-flight, tree fingerprint, per-backend receipt state (current / stale / ungrounded / probe / rejected / missing) with verdict + grounding + timestamp.
-2. **`--check`** → the gate exit code. The **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a CONFIGURED solo recipe (a computed readiness-degrade NEVER silently becomes solo — it needs the explicit degrade record below), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a non-git cwd, or every recipe-named backend SATISFIED for the current tree. **Satisfaction is ship-class-only on the LATEST NORMAL receipt (D3(b)):** per backend, the latest probe-free current-fingerprint receipt is selected FIRST and THEN verdict-checked — only the recognized ship-class vocabulary (`ship` / `ship with nits`) satisfies; a recognized NEGATIVE (`revise` / `rethink` / `rework`) is an authoritative VETO (an earlier ship never survives a later revise); an UNRECOGNIZED verdict (e.g. `unknown` from a dead run) fails CLOSED unconditionally — a later `unknown` never lets an earlier SHIP stand, and a fresh normal re-run supersedes it. **The ONLY escape is an explicit degrade RECORD** (`core-evidence.mjs degrade --backend <name> --reason "…"`, fingerprint-bound to the current tree) — and never all backends: ≥1 non-degraded ship-class receipt is required whenever ≥1 backend is configured; a malformed evidence store denies the escape fail-closed but never fails an independently-satisfied tree. Exit 1 otherwise — missing, **stale** (ANY edit after a review moves the fingerprint), ungrounded, vetoed, or unrecognized. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review runs with the frontier-model/max-effort guard OFF, so the wrapper stamps `probe:true` and this checker excludes it — per receipt, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a malformed *or* absent probe marker is rejected fail-closed and stated in the check line. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
+2. **`--check`** → the gate exit code. The **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a CONFIGURED solo recipe (a computed readiness-degrade NEVER silently becomes solo — it needs the explicit degrade record below), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a non-git cwd, or every recipe-named backend SATISFIED for the current tree. **A clean-tree PASS under a NON-SOLO review obligation is never silent about a latent arm:** when a `reviewed` or `council` recipe is configured, it NAMES every plan in flight and states that this gate arms as soon as the tree is dirty — the condition is discoverable BEFORE it blocks, instead of surfacing at the worst moment (a pending commit, or the landing of a feature worktree when main first turns dirty). Nothing is announced under a configured `solo` recipe or a non-git cwd, where the gate can never arm. **Satisfaction is ship-class-only on the LATEST NORMAL receipt (D3(b)):** per backend, the latest probe-free current-fingerprint receipt is selected FIRST and THEN verdict-checked — only the recognized ship-class vocabulary (`ship` / `ship with nits`) satisfies; a recognized NEGATIVE (`revise` / `rethink` / `rework`) is an authoritative VETO (an earlier ship never survives a later revise); an UNRECOGNIZED verdict (e.g. `unknown` from a dead run) fails CLOSED unconditionally — a later `unknown` never lets an earlier SHIP stand, and a fresh normal re-run supersedes it. **The ONLY escape is an explicit degrade RECORD** (`core-evidence.mjs degrade --backend <name> --reason "…"`, fingerprint-bound to the current tree) — and never all backends: ≥1 non-degraded ship-class receipt is required whenever ≥1 backend is configured; a malformed evidence store denies the escape fail-closed but never fails an independently-satisfied tree. Exit 1 otherwise — missing, **stale** (ANY edit after a review moves the fingerprint), ungrounded, vetoed, or unrecognized. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review runs with the frontier-model/max-effort guard OFF, so the wrapper stamps `probe:true` and this checker excludes it — per receipt, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a malformed *or* absent probe marker is rejected fail-closed and stated in the check line. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
 3. **Wire it as a gate by hand OR via the explicit-consent init preview — never without consent (AD-021/D9).** The candidate line for your own `docs/ai/gates.json`: `{ "id": "review-state", "title": "Review receipts current for the uncommitted tree", "cmd": "node <path-to-this-skill>/tools/review-state.mjs --check" }` — with the path your project actually reaches the kit by, QUOTED so a path with spaces survives, executable from the project root. The consent-gated gates-init preview (`${CLAUDE_SKILL_DIR}/references/modes/gates.md`, consent-fill section) offers exactly this entry — path resolved and quoted — ONLY when your `docs/ai/orchestration.json` declares `reviewed`/`council` on `plan-execution.review` (the slot this checker enforces); it writes nothing without your explicit yes. Once declared, the opt-in `${CLAUDE_SKILL_DIR}/references/modes/hook.md` auto-approves it like any other declared gate — and `run-gates --final` requires this check among its canonical core gates.
 4. **`--await [--timeout <s>]`** (BUGFREE-3 / AD-049) → BLOCK until every recipe-named backend is SATISFIED for the current tree (i.e. until `--check` would PASS), or the bounded timeout elapses (a loud exit 1; default 900s). Run it after dispatching the review bridges to WAIT for their receipts to land instead of hand-polling a pid: the durable completion signal is the **receipt**, never a process event (a harness "completed" notification fires early; a bridge's output late-flushes). It inherits the `--check` decision whole — a backend with a current-tree degrade RECORD stops being waited on (the shared decideCheck), so you never hand-`--await` around a known degrade. Still read-only (it re-reads the receipts + the evidence store); solo / no-plan / clean-tree resolve instantly.
 

package/tools/doc-parity.mjs

@@ -33,6 +33,7 @@ import {
   ACKS_FILE,
 } from './recommendations.mjs';
 import { SKIPPED_READONLY } from './setup-backends.mjs';
+import { LATENT_ARM_NOTICE } from './review-state.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -41,6 +42,7 @@ const RECOMMENDATIONS_DOC = 'references/modes/recommendations.md';
 const UPGRADE_DOC = 'references/modes/upgrade.md';
 const VELOCITY_DOC = 'references/modes/velocity.md';
 const SETUP_DOC = 'references/modes/setup.md';
+const REVIEW_STATE_DOC = 'references/modes/review-state.md';
 
 // A typed usage failure (exit 2) for the CLI parser — the codebase's typed-error idiom (no classes).
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
@@ -90,6 +92,10 @@ export const BINDINGS = Object.freeze([
   // (setup.md owns --refresh-placed; upgrade.md pastes its lines) — a reworded doc dropping the
   // outcome fails this pin plus the gate. The token tracks the exported SETUP constant.
   valueBinding('refresh-skipped-readonly', SKIPPED_READONLY, SKIPPED_READONLY, [SETUP_DOC, UPGRADE_DOC]),
+  // The "the tool knows and does not say" contract: a clean-tree PASS must still name a latent arm.
+  // It was a prose-only bar a doc could silently drop, so it is pinned to the live string the tool
+  // actually emits — a reworded doc dropping the notice fails this pin plus the gate.
+  valueBinding('latent-arm-notice', LATENT_ARM_NOTICE, LATENT_ARM_NOTICE, [REVIEW_STATE_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -135,8 +141,9 @@ Usage:
 
 A CLOSED, exported registry binds each live code constant — the autonomy-doctor contract (the EXIT
 table, the status tokens, the trusted-dir allowlist), the recommendations/upgrade presentation
-contract (section header, empty line, verdict templates), the acks-store path, and the setup
-refresh degrade token — to the exact token its references/modes/*.md contract must carry, and
+contract (section header, empty line, verdict templates), the acks-store path, the setup refresh
+degrade token, and the review-state clean-tree latent-arm notice — 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 bound file,
 or an absent token FAILS CLOSED.
 

package/tools/review-state.mjs

@@ -13,7 +13,11 @@
 //           absent config with no reviewer backend ready); when no plan is in flight (docs/plans/
 //           holds no top-level .md that is not queue.md and not scratch by the naming convention:
 //           prefixes EXECUTE- / FEEDBACK-, or a name containing PROMPT / prompt / handoff); when
-//           the tree is clean (nothing to review); when the cwd is not a git work tree; and when
+//           the tree is clean (nothing to review — under a non-solo review obligation the PASS
+//           still NAMES every plan in flight and states that the gate arms as soon as the tree
+//           turns dirty, so a latent arm is discoverable before it blocks a pending commit); when
+//           the cwd is not a git work tree
+//           (the gate can never arm there, so nothing is announced); and when
 //           the obligations are SATISFIED: under `reviewed`, >=1 backend's latest normal receipt
 //           attests SHIP-CLASS (ship / ship with nits) for the current tree; under `council`,
 //           EVERY review-capable backend attests ship-class OR carries an explicit current-tree
@@ -172,6 +176,25 @@ const maskAdvisoryLine = (state) =>
 
 // ── plan-in-flight detector (the AD-038 naming convention; documented in queue.md) ─────
 
+// The clean-tree PASS wording, split so the doc-parity registry can bind the forward-looking half
+// to the mode doc — the notice is the contract, not decoration.
+export const CLEAN_TREE_PASS = 'the working tree is clean — nothing to review';
+export const LATENT_ARM_NOTICE = 'this gate arms as soon as the tree is dirty';
+
+const UNSAFE_INLINE_SCALARS = /[\u007f-\u009f\u2028\u2029]/gu;
+// A plan FILENAME reaches a one-line gate report. JSON quoting handles the C0 control bytes; the C1
+// range (DEL + U+0080..U+009F, including the U+0085 line break) and the two Unicode line separators
+// survive JSON.stringify and can still break a line, so they are escaped explicitly — every escape a
+// valid JSON \uXXXX, so the token round-trips through JSON.parse. The plan set stays STRING-typed for
+// its consumers (procedures / worktrees / the JSON surface); a name carrying INVALID UTF-8 bytes is a
+// stated residual (queue: PARALLEL-TRACK-REDESIGN — two such names could collapse in the DISPLAY only,
+// never in the gate decision, which keys on the receipt fingerprint, not the name).
+export const quoteReportName = (name) =>
+  JSON.stringify(name).replace(
+    UNSAFE_INLINE_SCALARS,
+    (value) => `\\u${value.codePointAt(0).toString(16).padStart(4, '0')}`,
+  );
+
 // Scratch by the naming convention: EXECUTE-/FEEDBACK- prefixes, or a name carrying PROMPT/prompt/
 // handoff. queue.md is the series index, never a plan.
 export const isScratchPlanName = (name) =>
@@ -183,7 +206,7 @@ export const isScratchPlanName = (name) =>
   name.includes('handoff');
 
 // The in-flight plan files: top-level docs/plans/*.md minus queue.md minus scratch. [] when the
-// directory is absent (no plans → nothing in flight).
+// directory is absent (no plans → nothing in flight). STRING-typed for every consumer.
 export const plansInFlight = (cwd, readdir = readdirSync) => {
   let entries;
   try {
@@ -392,7 +415,14 @@ export const decideCheck = (state) => {
   }
   if (state.plans.length === 0) return { code: 0, reason: `no plan in flight (docs/plans/ holds no active plan) — no receipt required${earlyNotes}` };
   if (state.fingerprint == null) return { code: 0, reason: `not a git work tree — nothing to fingerprint${earlyNotes}` };
-  if (state.clean === true) return { code: 0, reason: `the working tree is clean — nothing to review${earlyNotes}` };
+  // A clean tree PASSES, but never silently: the no-plan arm above already returned, so reaching
+  // here means >=1 plan IS in flight and this gate arms the moment the tree turns dirty. Naming
+  // each file forward-looking is what makes the arm discoverable BEFORE it blocks a pending commit.
+  if (state.clean === true) {
+    // Each name is byte-preserving and quoted because this reason is one gate-report line.
+    const named = state.plans.map((p) => quoteReportName(p)).join(', ');
+    return { code: 0, reason: `${CLEAN_TREE_PASS} — ${state.plans.length} plan(s) in flight: ${named} — ${LATENT_ARM_NOTICE}${earlyNotes}` };
+  }
   const exempt = new Set(state.degradedExempt);
   const satisfied = state.backends.filter((b) => b.state === 'current' && b.shipClass);
   const vetoed = state.backends.filter((b) => b.state === 'current' && !b.shipClass);
@@ -463,7 +493,7 @@ const formatHuman = (state, check) => {
     `review-state — ${ACTIVITY}.${SLOT} = ${state.obligations.recipe ?? '(unknowable)'} (${src})${state.requiredBackends.length ? ` → ${state.requiredBackends.join(' + ')}${state.obligations.perBackend ? '' : ' (any one, ship-class)'}` : ''}`,
   ];
   if (state.detectionWarning) lines.push(`  ⚠ ${state.detectionWarning}`);
-  lines.push(`  plan in flight: ${state.plans.length ? state.plans.join(', ') : '(none)'}`);
+  lines.push(`  plan in flight: ${state.plans.length ? state.plans.map((name) => quoteReportName(name)).join(', ') : '(none)'}`);
   if (state.fingerprint == null) lines.push('  tree: not a git work tree');
   else if (state.clean === true) lines.push('  tree: clean (nothing to review)');
   else lines.push(`  tree fingerprint: ${state.fingerprint}`);
@@ -517,7 +547,8 @@ The ONLY escape for an unavailable backend under council is an explicit current-
 record (node core-evidence.mjs degrade) — and never all backends.
 
 --check exits 0/1 per the normative contract in the tool header: 0 for solo / no plan in flight /
-a clean tree / not-a-git-tree / obligations satisfied (reviewed: >=1 ship-class attestation;
+a clean tree (under a non-solo review obligation the PASS names every plan in flight and its arm) /
+not-a-git-tree / obligations satisfied (reviewed: >=1 ship-class attestation;
 council: every backend ship-class or degrade-recorded, >=1 real ship); 1 on a veto, an
 unrecognized verdict, a missing/stale/ungrounded/probe-only backend without a degrade record,
 an all-degraded tree, or a down detector with no configured recipe.