@sabaiway/agent-workflow-kit 1.29.0 → 1.31.0

package/CHANGELOG.md

@@ -4,6 +4,92 @@ 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.
 
+## 1.31.0 — Progressive disclosure: SKILL.md becomes a thin router over references/modes + references/shared (AD-039)
+
+A **feature** release; packaging-only for deployments (the deployment lineage stays `1.3.0` — no
+`docs/ai` structure change, no migration). The 112,106 B / 680-line SKILL.md monolith — loaded
+whole on EVERY invocation — becomes a **10,139 B router** plus per-mode files, so an invocation
+reads only what it needs:
+
+- **The router** keeps the always-needed core: the composition-root decision (detect → delegate /
+  fallback + the init refresh-cascade), the safe-routing rule + version-status routing note, and
+  16 bare `### Mode:` headers each carrying ONE line — the catalog `kind` EXACTLY + ``read
+  `${CLAUDE_SKILL_DIR}/references/modes/<mode>.md` before acting.``
+- **`references/modes/<key>.md` ×16** — the mode bodies, moved verbatim (set-equality-guarded
+  against the `tools/commands.mjs` catalog). **`references/shared/`** — the point-of-use
+  contracts: `report-footer.md` (backend-status line · version block + welcome mat · version
+  disclosure), `composition-handoff.md` (hand-off + bounded pointer reconciliation),
+  `deploy-tail.md` (Gotchas · Setup contracts · System principles · Hard-Constraints template).
+  Each mode file opens with one `Requires:` line naming its shared reads (bootstrap/upgrade → all
+  three; status → the report footer; the daily modes none).
+- **Byte budgets are acceptance, not vibes** — the new `test/router-contract.test.mjs` asserts,
+  over the real files: router ≤ 10,240 B · router + any mode ≤ 28,672 · every full read set
+  ≤ 53,248 · the daily no-shared modes ≤ 16,384 (realized: 10,139 · 27,392 · 48,419 · 14,121 —
+  a daily `help` run is ~10× lighter, the worst path (`upgrade`) ~2.3×). It also pins the D4
+  pointer audits permanently: every `Requires:` resolves, zero italic/plain cross-mode refs, zero
+  bare kit-relative links, moved shared-section references carry their pointer.
+- **Nothing else moved:** runtime routing untouched (`routeInvocation` never reads SKILL.md);
+  packaging additive (`references/` already rides `files[]`; the npx installer copies it
+  recursively; tarball 96 → 115 files, exact-count-pinned); frontmatter byte-compatible with the
+  twin version readers; 7 content-coupled guards re-anchored to the new files.
+
+## 1.30.0 — Review-recipe enforcement: the configured recipe is impossible to miss, "reviewed ≠ shipped" is detectable, grounding is a command (AD-038)
+
+A **feature** release (ships the bundled bridges refreshed to **2.2.0**). Origin: a real
+council-substitution incident + independent kit-user feedback — the configured review recipe could
+be silently skipped, downgraded, or run before later edits, and nothing could detect it. Three
+mechanisms, each self-firing at its point of use:
+
+- **The discovery line** — `tools/recipes.mjs --active-line` (`Mode: recipes`): exactly ONE
+  machine-composed line rendering the **CONFIGURED** recipe of every activity/slot from
+  `docs/ai/orchestration.json` + live readiness — source labeled, degradation stated, wrapper set
+  named, explicitly contrasted with the readiness recommendation (which is informational). Wired
+  where a session already reads: the deployed `agent_rules.md` §1.1 gains step 2 (read the
+  orchestration config BEFORE picking a task; a silent recipe downgrade is a forbidden
+  substitution) and `handover.md` gains a standing **"Active recipes:"** slot — both template
+  regions byte-identical with the memory copies (new `test/template-region-parity.test.mjs`,
+  injected-divergence non-vacuous); `set-recipe` now ECHOES the freshly composed line + a
+  handover-slot reminder after every successful `--write` (additive `activeLine` field in
+  `--json`). New `test/active-recipe-line.test.mjs` proves the line derives from the CONFIG, not
+  the recommendation.
+- **`/agent-workflow-kit review-state`** (`tools/review-state.mjs`, read-only + colocated tests) —
+  makes "reviewed ≠ shipped" mechanically detectable. The 2.2.0 review wrappers append one JSONL
+  receipt per SUCCESSFUL review to `<git dir>/agent-workflow-review-receipts.jsonl`
+  (`AW_REVIEW_RECEIPTS` overrides; never committable by construction); the checker resolves the
+  effective `plan-execution.review` recipe, recomputes the canonical **uncommitted-state
+  fingerprint** (sha256 over staged diff + unstaged diff + untracked-not-ignored contents — exactly
+  the review-payload domain), and `--check` exits 0 only when every recipe-named backend holds a
+  **fresh, grounded, current-fingerprint** receipt (**presence, not unanimity** — verdicts stay
+  orchestrator judgment). Any later edit stales the receipts; plan/diff receipts and continuations
+  (`fresh:false`) are informational-only — after a fold, only a fresh grounded re-run restores
+  green. Normative exit contract in the tool header; plan-in-flight detector keyed on the
+  documented `docs/plans` naming convention; honest residual stated (`--no-verify`, receipt-file
+  deletion — discipline, not a sandbox). The gate line is **never auto-seeded** ([[AD-021]]): the
+  template `gates.json` stays empty; the candidate line lives in `Mode: review-state`/`Mode: gates`
+  prose. New `test/review-fingerprint-parity.test.mjs` proves bash (both wrappers, byte-identical
+  block) ↔ node fingerprint parity — hash, serialization, AND behavioral domain equality.
+- **`/agent-workflow-kit grounding`** (`tools/grounding.mjs` + colocated tests) — the
+  grounded-review facts assembler, catalogued honestly as a **WRITER**: `--constraints` slices the
+  root `AGENTS.md` Hard-Constraints section verbatim (exactly-one-match, else a loud STOP);
+  `--plan <path>` extracts the decision-bearing sections (`## Approach` + `## Verification`
+  required, `## Decisions (locked)` when present; duplicates STOP); output honors the wrapper's
+  `AGY_MAX_PROMPT_BYTES` budget minus `--reserve-bytes` with a loud tail-trim; `--out` accepts only
+  gitignored / out-of-repo scratch (a tracked or in-repo not-ignored path is refused — a new
+  untracked file would move the fingerprint it grounds). `procedures.mjs` renders the invocation as
+  a POPULATED pre-step whenever agy is dispatched (exactly one plan in flight → its path; else a
+  placeholder + discovery caveat; additive `groundingPreStep` in `--json`).
+- **Bundled bridges 2.2.0** (mirrors byte-refreshed): `codex-review.sh` mandates + parses ONE
+  literal `Verdict: ship|revise|rethink` line (schema mode reads the JSON field); `agy-review.sh`
+  records the `### Verdict` token verbatim (SHIP / SHIP WITH NITS / REWORK), `grounded` +
+  `factsHash` from `--facts` (an empty payload is visible), and marks continuations `fresh:false`
+  with a one-line fresh-run notice; a receipt write failure warns and never fails the review. The
+  review-role `capability.json` contracts gain the `receipt` block (the fingerprint definition
+  home) — three-way lockstep wrapper `--help` ↔ manifest ↔ `detect-backends.mjs` registry,
+  drift-guarded.
+- **Catalog/report wiring:** two new SKILL modes + README rows; the bootstrap/upgrade report
+  footers paste the active-recipe line beside the backend-status line; `package-content` pin
+  94 → 96 (the two new tools).
+
 ## 1.29.0 — Velocity scope C: an opt-in PreToolUse gate-approval hook
 
 A **feature** release (ships the bundled bridges unchanged at **2.1.0**). The shipped, probe-proven

package/README.md

@@ -234,6 +234,8 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/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. |
 | `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/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** (never auto-seeded). 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 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. Prints to stdout; `--out` writes **one scratch file only** (gitignored / outside the repo — a tracked or not-ignored in-repo path is refused). 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. |
 | `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a runtime residual remains at the settings level — its guard ships as the opt-in `hook` command); a direct commit/push/publish still asks. `--dry-run` first. |
 | `/agent-workflow-kit agents` | Claude Code · opt-in | **cheap-lane subagents** — places bundled subagent definitions (`.claude/agents/`) pinned to a **cheap model** (haiku, low effort, read-only tools) for mechanical work: extraction sweeps, changelog fact-skeletons, gate-failure triage. Judgment, review, and real code stay on your main lane — these vehicles only extract and draft, and their output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |
@@ -304,7 +306,8 @@ One kit, two tiers — **no logic is duplicated per tool:**
 - The **output** (`AGENTS.md` + `docs/ai/`) is read natively by Claude Code (via the `CLAUDE.md`
   alias) · Codex · Cursor · Devin Desktop · Copilot · Gemini CLI & 20+ tools.
 - The **bootstrapper** runs from Claude Code · Codex · Devin Desktop — their launchers point at the
-  same `SKILL.md`, so deployment logic lives in one place.
+  same `SKILL.md` router (which loads its `references/modes/` + `references/shared/` files per
+  invocation), so deployment logic lives in one place.
 
 ---
 
@@ -313,10 +316,12 @@ One kit, two tiers — **no logic is duplicated per tool:**
 ```
 agent-workflow-kit/
 ├── README.md        ← you are here (the kit's manual)
-├── SKILL.md         ← agent-facing deploy / upgrade algorithm
+├── SKILL.md         ← thin agent-facing router: mode index + safe routing
 ├── CHANGELOG.md     ← version history
 ├── capability.json  ← agent-workflow family manifest (composition-root)
 ├── references/
+│   ├── modes/       ← one file per mode (deploy/upgrade/… procedures)
+│   ├── shared/      ← shared contracts (footer · hand-off · tail)
 │   ├── templates/   ← AGENTS.md + every docs/ai file
 │   ├── scripts/     ← caps / archive / index + tests
 │   └── contracts.md ← visibility / language / attribution rules