@sabaiway/agent-workflow-kit 1.29.0 → 1.31.0

package/references/modes/upgrade.md

@@ -0,0 +1,46 @@
+### Mode: upgrade
+
+Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md · ${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md
+
+1. Read `docs/ai/.workflow-version` (the project's stamped lineage). If missing, treat as a pre-versioned deployment and offer to re-bootstrap conservatively.
+2. **Never-downgrade gate — FIRST, before any write.** Compare the stamp to the **deployment-lineage head** (`1.3.0` — NOT this kit's package version). If the stamp is **greater than the head** or unparseable → **STOP and report**; do not touch a newer / unknown deployment at all (not even the methodology slot). This STOP is one of the few places the number is actionable (*Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`): show the user **the `docs/ai` structure version** their deployment carries versus the one this kit expects, plus the plain one-line two-axes note — naming it the structure version, **never** "lineage head".
+3. **Reconcile the bounded pointers — stamp-independent, BEFORE the equal-head short-circuit.** Reached only when the stamp **≤ head**. Run `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md`. ONE call reconciles **two** pointers — the **workflow-methodology** pointer and, right below it, the **orchestration-recipes** pointer (Solo / Reviewed / Council / Delegated, routing to `/agent-workflow-kit recipes`) — and is filled on **every** upgrade, idempotently (zero-diff when both are already present + filled), so even a legacy / current **`1.3.0`** deployment gains them **without a lineage-head bump or a migration** (the deployment-lineage head stays `1.3.0`; the `agent-workflow-memory` **package** template did get a docs-only headroom trim for the second pointer, but no deployed-`docs/ai` structure changed). Per slot it inserts an empty pair at its anchor if absent, preserves a customized pair verbatim, and STOPs (never edits) on a malformed pair, a missing / duplicate anchor, or **when a fill is needed but the installed `agent-workflow-engine` is absent/invalid** (both fragments are read live from it — see the distinct outcomes below).
+
+   **Classify the exit — there are THREE non-zero exits + one soft in-band skip; handle each differently:**
+
+   (a) **Soft, reported skip of the orchestration pointer (CONTINUE the upgrade).** The orchestration pointer is the less-critical second pointer; when it can't be added right now `reconcile` exits **zero**, keeps the methodology pointer, and **reports the skip on stdout** (the `… skipped …` line) — never silent (Hard Constraint). Two reasons: **(i)** the methodology pointer fits but adding the orchestration pointer would push the file past the `AGENTS.md` 100-line cap; or **(ii)** the installed `agent-workflow-engine` is **present but too old** to ship the recipes fragment (`<1.2.0`) — it can still supply the methodology pointer, so only the recipes pointer is withheld. Report it in the successful-exit report (**step 4** equal-head, else **step 8**) in plain language, e.g. *"The orchestration-recipes pointer wasn't added — the entry point is at its 100-line limit / your methodology engine is older than the recipes feature. The recipes are still available any time via `/agent-workflow-kit recipes`; to add the pointer, trim the entry point and/or refresh the engine with `npx @sabaiway/agent-workflow-engine@latest init`, then re-run upgrade."* (The separate case where the **methodology** pointer ITSELF can't fit the cap is a non-zero exit that changes nothing — continue without either pointer, same plain-language framing.)
+
+   (b) **Malformed pair / missing-or-duplicate anchor (either pointer) — a hard STOP (do NOT continue).** A non-zero exit whose message names a marker/anchor problem; never soft-skip it.
+
+   (c) **`methodology engine not found/invalid …` — a hard STOP (do NOT continue).** A fill was needed but the installed `agent-workflow-engine` is **fully absent/invalid** — it can supply **neither** fragment (distinct from (a)(ii), where the engine is valid but merely too old for the recipes one). Report it in plain language with the one-line install command `npx @sabaiway/agent-workflow-engine@latest init` (or note that `npx @sabaiway/agent-workflow-kit@latest init` installs the engine for you), then re-run upgrade once it is present. **Never** treat (c) as a soft-skip (a) — mis-handling it would silently drop the methodology pointer (a no-silent-failures violation). (b) and (c) STOP the upgrade; only (a) continues.
+
+   **No-Node project:** the fragments live only in the **installed `agent-workflow-engine`** (`references/methodology-slot.md` + `references/orchestration-slot.md`, under `~/.claude/skills/agent-workflow-engine` or `$AGENT_WORKFLOW_ENGINE_DIR`) — there is no bundled copy, and a No-Node host cannot run the `npx` engine install. Open `AGENTS.md` and classify **each** pointer by hand: a **filled / customized** pair → leave it verbatim (no engine needed); a **malformed** pair (not exactly one ordered `start → end`) → STOP, do not edit. A pair that needs filling — **absent markers OR a present-but-empty pair** — needs the engine's fragment, so: if the engine is **not installed**, that pointer **cannot be added** — report it plainly (the methodology is already in `docs/ai/agent_rules.md`; the recipes are available via `/agent-workflow-kit recipes`; install the engine to add the pointers). If the engine **is** present, **count the lines first** — if adding/filling would take the file over 100 lines, **skip that pointer and report the skip** (methodology first, then orchestration; the orchestration pair sits right under the methodology end marker). Fill each empty pair from its engine fragment (`methodology-slot.md` / `orchestration-slot.md`) — never inline a copy (that would re-create the retired mirror).
+
+   **Hidden-mode footprint reconcile — stamp-independent, same gate, BEFORE the equal-head short-circuit (D9 / AD-014).** A deployment does not record whether it chose `hidden`, so first **infer visibility**: `node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile --dry-run` (writes **zero bytes**). It reports one of — **visible** (the entry point is tracked) → nothing to do; **ambiguous** (untracked but not ignored — could be a fresh uncommitted repo, or a hide that broke) → **ASK** the user which it is, never guess; **hidden** → re-run without `--dry-run` to migrate any older **machine-global** hide to the **project-local** `.git/info/exclude` (one managed block; folds in the legacy `.claude/skills/` line), idempotently (a clean re-run is zero-diff). Handle its surfaced paths exactly as bootstrap step 9 (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`) (already-committed → show `git rm --cached`, ask before `--include`; generic-name present file → ask; **leftover machine-wide ignore block → ASK before `--remove-global`**, default keep + report). No Node on the agent host / Windows → as bootstrap step 9 (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`). This runs on **every** hidden upgrade, like the methodology slot — no lineage-head bump, no migration file.
+
+   **Orchestration config ensure (seed-or-refresh) — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Ensure `docs/ai/orchestration.json` exists **and its onboarding note is current**: **create it from the template if missing**; **if it already exists, preserve every activity/slot the user set, and refresh ONLY the `_README` note when the existing one still matches a known prior canonical** — the tested `refreshIfCanonical` / `refreshReadme` in `tools/orchestration-config.mjs` is the source of truth for that decision (normalize CRLF/whitespace before comparing; a *customized* `_README` is preserved verbatim; a *malformed* existing config is **preserved + a loud warning**, never clobbered or silently skipped). The current note points at `/agent-workflow-kit set-recipe` (the config is now agent-writable — no more "never written for you"). **The refresh helper is kit-owned** — in the **delegated** path memory only seeds/preserves the file (memory upgrade step 2) and the **kit** then applies the `_README` refresh; in the **fallback** path the kit seeds-or-refreshes directly from `${CLAUDE_SKILL_DIR}/references/templates/orchestration.json`. (Memory stays standalone — it never depends on this helper.) Like the pointer slots + the footprint reconcile, this reaches an equal-head (`1.3.0`) deployment **without a lineage-head bump or a migration file** (it is a `.json`, inherently outside the docs cap-validator). Report it in the step 4 / step 8 success report (config *seeded* / *note refreshed* / *already current* / *customized — preserved*).
+
+   **Gate-declaration ensure (seed-if-missing) — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Ensure `docs/ai/gates.json` exists: **create it from `${CLAUDE_SKILL_DIR}/references/templates/gates.json` if missing** — the kit's OWN template twin, so this works even when the installed memory substrate predates the gates feature (a stale memory never silently loses it); **an existing file is preserved byte-for-byte** (a project's declared gate matrix is authored content — never clobbered, never refreshed in place; unlike the orchestration `_README` there is no note-refresh here). Report it in the step 4 / step 8 success report (*seeded* / *already present*). Like the config ensure, this reaches an equal-head deployment without a lineage-head bump or a migration file (a `.json`, inherently outside the docs cap-validator).
+
+   **Enforcement-script ensure (seed-if-missing) — stamp-independent, same gate, BEFORE the equal-head short-circuit.** A deployment older than the ADR-cascade feature has no `scripts/archive-decisions.mjs`, and an equal-head exit would otherwise never deliver it. Ensure the pair exists in the project's `scripts/`: **copy `archive-decisions.mjs` + `archive-decisions.test.mjs` from `${CLAUDE_SKILL_DIR}/references/scripts/` if missing** (the kit's own fallback copies — byte-identical to the memory canon by the mirror guard); **an existing file is preserved, never overwritten** (drift repair belongs to a lineage migration, not this ensure). The deployed pre-commit hook gains the `archive-decisions.mjs --check` line only when the hook itself is next refreshed (re-run `node scripts/install-git-hooks.mjs` after the ensure and it will refuse a non-marker hook as always); an OLD hook without the line stays consistent-safe — the decisions gate is simply not enforced yet, never a broken hook. Skip this ensure on a No-Node project (the scripts are Node enforcement). Report it in the step 4 / step 8 success report (*added* / *already present*).
+
+   **Placed-bridge refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Run
+   `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs --refresh-placed` and **paste its per-bridge
+   output lines verbatim** — every outcome line is composed by the tool (*refreshed* / *already
+   current* / *skipped — not placed* / *could not refresh* + its recovery); you compose nothing
+   factual. It is **refresh-only**: it refreshes a bridge **`setup` already placed** from this kit's
+   bundled copies and re-links its wrappers; an **absent** bridge is a stated skip, **never a first
+   placement** (placement stays the opt-in `${CLAUDE_SKILL_DIR}/references/modes/setup.md` — AD-009/AD-011 honesty intact), and a
+   placed bridge **newer** than the bundled copy is a stated skip naming the kit update (**never a
+   downgrade**). Like the other three reconciles it runs on **every** upgrade — including an
+   equal-head one — with no lineage-head bump. A *could not refresh* line is non-fatal: relay it
+   plainly with its recovery and continue the upgrade.
+4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the methodology-slot **and** hidden-mode footprint reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
+   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); whether the `docs/ai/gates.json` gate declaration was *seeded* or was *already present* (preserved byte-for-byte); whether the enforcement-script ensure *added* the `archive-decisions` pair to `scripts/` or found it *already present*; the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / *could not refresh* + recovery); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
+   - **Never surface the structure number on this exit.** Whatever step 3 did, do **not** recite the `docs/ai` structure version, the internal versioning vocabulary, or the two-axes note here — the number is inert on an equal-head exit; it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md` (shown at the never-downgrade STOP, the explicit status view, or on an explicit ask). Frame the success itself per the final bullet: if step 3 changed anything, say **what changed** in plain human terms; only a pure zero-diff no-op is *settings already current — no update needed*.
+   - **Print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity`).
+   - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, give the plain **settings already current — no update needed** message (the *Success state* contract in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`) and still print the read-only version block (installed package versions) + backend line — but **no `docs/ai` structure version and no two-axes note** (nothing changed, so the number is inert here).
+5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
+6. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
+7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 **placed-bridge refresh** lines (pasted verbatim) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, on demand only). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing**.

package/references/modes/velocity.md

@@ -0,0 +1,18 @@
+### Mode: velocity
+
+The opt-in onboarding **velocity profile** — it seeds a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so an agent stops idling on approval prompts for routine read-only commands while the maintainer is away. It is the family's **first programmatic `.claude/settings.json` writer** (attribution stayed an agent-driven prose merge). **In-agent, opt-in, writes only `.claude/settings.json`**, on one hard rule: **it never allowlists `commit`/`push`/`publish`** — so a direct commit/push/publish still ASKs; the only caveat is the trust-posture residual (below) — its closure is **shipped, opt-in: `${CLAUDE_SKILL_DIR}/references/modes/hook.md`**.
+
+**Version-status routing (like the other writer modes):** read `docs/ai/.workflow-version` first — not-deployed → bootstrap; stamp < `1.3.0` → `upgrade`; stamp > head / unparseable → STOP. The tool enforces this in code too (`--apply` STOPs unless the stamp is the lineage head).
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [--accept-edits] [--cwd <dir>]`:
+
+1. **`--dry-run` first, always** (the default — changes nothing). It prints: the fixed read-only core it would add; a **read-only advisory** that lists your `package.json` `scripts` as **unaudited candidates you may add BY HAND** (inspect each first) to `.claude/settings.json` / `settings.local.json` — the tool **never** writes them and flags obviously-mutating names as "do not add"; any **pre-existing non-read-only `Bash(...)` entries** to consider removing by hand; and the honest residual notice (below). It STOPs (zero writes) on a symlinked `.claude` / non-regular `settings.json`, malformed settings JSON, or an unsafe `permissions.defaultMode` — `bypassPermissions` or anything outside `default`/`acceptEdits`/`plan`, present in **either** `settings.json` or `settings.local.json`.
+2. **Ask the `acceptEdits` opt-in** via **`AskUserQuestion` where supported**, the safe option FIRST:
+   - **"Keep per-edit approval prompts (recommended)"** — seed only the read-only allowlist; file edits still prompt.
+   - **"Auto-accept file edits (`defaultMode: acceptEdits`)"** — present the honest FULL posture: it auto-applies Edit/Write AND auto-runs `mkdir`/`touch`/`mv`/`cp` in the working dir, is paired with the read-only allowlist, and — stated plainly — a settings-level allow rule is a **trust posture, not a sandbox**: a read-only entry can still write a file via output redirection, and (Claude Code's allow rules do not inspect command substitution) could in principle run another command via `cmd $(…)`. velocity **never adds `commit`/`push`/`publish` as allow rules** — so a direct `git push` still ASKs — and the residual guard for the seeded core ships as the opt-in PreToolUse hook (`${CLAUDE_SKILL_DIR}/references/modes/hook.md`; probe-proven on the `--output` family — current engine builds already intercept redirection/substitution upstream). Note also that a `defaultMode` in `settings.local.json` would override this project-level write (local > project), since velocity writes only `.claude/settings.json`.
+3. **Only on an explicit yes**, re-run with `--apply` (add `--accept-edits` only if they chose the second option). It merges-don't-clobber (preserves `includeCoAuthoredBy`, every key, and existing allow entries) and writes **only** `.claude/settings.json`.
+4. **Surface delegation-readiness, read-only.** If they want a step run Delegated, set it with `/agent-workflow-kit set-recipe --set plan-execution.execute=delegated` (`${CLAUDE_SKILL_DIR}/references/modes/set-recipe.md`) or by hand-editing `docs/ai/orchestration.json`; **velocity itself never writes the orchestration config.**
+
+**Invariants:** creates `.claude/` if absent and writes **only** `.claude/settings.json` (no other file); **never** allowlists commit/push/publish; **never** writes `settings.local.json`; never commits; opt-in `acceptEdits`, never silent.
+
+**Exit codes:** `0` done / dry-run; `1` a precondition STOP (stamp not current, unsafe mode, malformed settings, symlinked `.claude` / non-regular target); `2` bad arguments.

package/references/shared/composition-handoff.md

@@ -0,0 +1,39 @@
+## Hand-off contract & bounded pointer reconciliation (composition root)
+
+**Hand-off contract (explicit; tested independent of agent interpretation).**
+- **Delegated** (memory valid): the kit passes the **target project dir** + the **three setup
+  answers** (visibility / language / attribution) to `agent-workflow-memory`, which writes
+  `docs/ai/` + `AGENTS.md` (carrying the **two empty pointer pairs** — `workflow:methodology` and
+  `workflow:orchestration`) + **`.memory-version`**. The kit then **reconciles both bounded pointers**
+  (below) and writes the kit-fallback **`.workflow-version`**. → **both stamps** present. In **hidden** mode the kit is the **single
+  hide authority**: after the hand-off it runs `tools/hide-footprint.mjs` (bootstrap step 9 — `${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`), which **absorbs
+  memory's project-local footprint lines** into the one canonical `.git/info/exclude` block and adds
+  the external footprint — so there is **no machine-global write** at any step (a stale memory's
+  residual global block is cleaned via the upgrade reconcile, below).
+- **Fallback** (memory absent/invalid): the kit runs the bootstrap procedure (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`) from its own
+  bundled assets — whose entry-point template now ships **two empty pointer pairs** (`workflow:methodology`
+  + `workflow:orchestration`) the kit reconciles + fills — and writes **`.workflow-version`** only.
+  Softly suggest installing `agent-workflow-memory` — never a prerequisite.
+
+**Bounded pointer reconciliation (the kit is the ONLY writer of these slots).** After `AGENTS.md`
+exists, run ONE command — `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile
+<project>/AGENTS.md` — which reconciles **two** bounded pointers in a single atomic write: the
+**workflow-methodology** pointer (the plan → execute → review summary) **and**, right below it, the
+**orchestration-recipes** pointer (the Solo / Reviewed / Council / Delegated vocabulary, routing to
+`/agent-workflow-kit recipes`). Each is **one atomic operation per slot**: **ensure the slot exists**
+(insert an empty marker pair at its anchor when a legacy entry point lacks one) → **inject the bounded
+fragment ONLY IF the slot is empty** (a filled / user-customized slot is preserved verbatim) →
+**cap-check** (the second pointer's check runs on the file *after* the first, so it guards the
+**combined** ≤100-line budget). Both fragments are short summary + pointer, read **live from the
+installed `agent-workflow-engine`** (`references/methodology-slot.md` + `references/orchestration-slot.md`,
+the family's one source of truth) — **not** a bundled mirror, and **not** the full references. The
+live read is **lazy + fail-loud**: the engine is consulted **only when a slot actually needs filling**,
+so a deployment whose pointers are already filled reconciles to a zero-diff no-op even on a host
+without the engine; but when a fill **is** needed and the engine is **absent/invalid**, reconcile
+**STOPs** — report it in plain language with the one-line install command
+`npx @sabaiway/agent-workflow-engine@latest init` (`npx @sabaiway/agent-workflow-kit@latest init`
+installs the engine for you; translate, never leak tool internals). Contract per slot: exactly one
+ordered `start → end` pair; a malformed slot (single, reversed, nested, duplicate) or a missing /
+duplicate anchor → **STOP with an error**, never edit (the file is left byte-for-byte unchanged). The
+**orchestration pointer is soft-skipped** (reported, never silent) when — and only when — adding it
+would exceed the 100-line cap: the methodology pointer still lands and the upgrade continues.

package/references/shared/deploy-tail.md

@@ -0,0 +1,61 @@
+## Gotchas
+
+The non-obvious traps — scan these before bootstrapping or upgrading. Each is also enforced inline in the bootstrap/upgrade procedures (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`, `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md`); this is the consolidated high-signal list.
+
+- **Source vs target directory.** Templates and scripts are read from the skill's own dir (`${CLAUDE_SKILL_DIR}/` in Claude Code, the `SKILL.md` folder elsewhere). The **working directory is the target project** — never write kernel files back into the skill.
+- **The `Co-Authored-By` trailer is added by the harness, not by prose.** When attribution is `off`, a doc directive alone won't stop it — for Claude Code you **must** also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent). Other tools: disable their equivalent co-author/footer setting.
+- **Hidden mode must never touch `package.json`.** Editing it is a *tracked* change and leaks the whole system. Hidden mode wires nothing into `package.json`; the pre-commit hook (untracked in `.git/hooks/`) calls `node scripts/<x>.mjs` directly. After hiding, **verify `git status` shows the artifacts as ignored**.
+- **Hidden mode is project-local, and the hide tool owns the known footprint.** `tools/hide-footprint.mjs` writes **one managed block** in the **project-local `.git/info/exclude`** — never the machine-global `core.excludesFile` (which would silently affect every repo on the host; **AD-014** amends **AD-006**). It hides the kit's own artifacts **and** the known external AI/agent footprint (the `KNOWN_FOOTPRINT` table in [contracts](${CLAUDE_SKILL_DIR}/references/contracts.md#visibility-contract)). A **tracked** file is **never silently un-tracked** — the tool prints the `git rm --cached` it will not run. Never leak its internal marker / asks terms to the user; translate every outcome to plain language.
+- **`CLAUDE.md` is a symlink, not a copy.** `ln -s AGENTS.md CLAUDE.md` — single source, no duplication. A copy drifts; a symlink can't.
+- **Never overwrite an existing entry point or hook.** If `AGENTS.md` / `CLAUDE.md` already exist, or the installer reports a pre-existing non-marker git hook, **stop and ask** the user to merge vs replace — don't clobber.
+- **Unrecognized invocations are read-only.** Only a **known** subcommand reaches its mode; the **bare** invocation bootstraps (and an existing `docs/ai/` makes it ask upgrade-vs-bootstrap first, never overwrite); **any other / ambiguous** token routes to `help` (read-only). A garbage invocation never writes. The mapping is pinned by `tools/commands.mjs` `routeInvocation` (unit-tested) — don't hand-route around it.
+- **No Node runtime → skip enforcement.** If the project has no Node (recon step 1), skip bootstrap steps 8–9 (scripts + hook) and follow the cap/archive/index policy manually, or port the scripts to the project's language.
+- **Conversational language never translates artifacts.** It governs *dialogue only*. Code, identifiers, paths, commands, log output, abbreviations, and every deployed `docs/ai/` / `AGENTS.md` file stay in their source language. See [Communication contract](${CLAUDE_SKILL_DIR}/references/contracts.md#communication-contract).
+- **Never auto-commit.** Report quality-gate results and wait for explicit approval — in both modes.
+- **Never leak kit internals to the user.** No ADR ids, tool / function / operation names (`reconcile`, `inject`, `ensureSlot`), marker / slot / fragment / anchor terminology, or verbatim tool stderr in anything the user reads. Translate every tool outcome into plain language a third-party user — who has never read this `SKILL.md` — can understand and act on (e.g. the cap-refusal report in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3).
+- **Uninstall never deletes user-authored content, and dry-runs first.** `/agent-workflow-kit uninstall` removes only what is **provably ours** (a managed skill dir / wrapper symlink / fenced block / marker hook) and **prints — never runs** the `rm` / `git rm --cached` for `docs/ai` and the entry-point docs, and an **edit** instruction (not an `rm`) for `.claude/settings.json`. Always run `--dry-run` first, show the plan, get consent, then `--yes`. A skill dir or symlink that is not provably ours is a STOP, never a clobber (the `setup` posture, inverted). Removing a shared global (memory/engine/a bridge) may affect another project — say so.
+
+---
+
+## Setup contracts
+
+The three setup choices — **visibility** (step 2), **conversational language** (step 3), and **agent attribution** (step 4) — each have a full contract in [`references/contracts.md`](${CLAUDE_SKILL_DIR}/references/contracts.md). Load it when you need the complete rule (e.g. while filling the matching `AGENTS.md` block, or when an `upgrade` migration touches one). Defaults, in brief: visibility = `visible` (committed); language = whatever the user is already writing in; attribution = `off`. Ask each as a structured multiple-choice prompt where supported (`AskUserQuestion` in Claude Code), otherwise in prose.
+
+---
+
+## System principles (encode these into the project's `AGENTS.md`)
+
+1. **Single entry point.** `AGENTS.md` is the only entry point (tool aliases like `CLAUDE.md` symlink to it); it never bloats — details live in `docs/ai/`.
+2. **Memory Map.** A "read-when / update-when" table for every file. Without it agents get lost.
+3. **Three protocols.** Start of Session → During Work → Task Completion, each a short checklist.
+4. **Update docs BEFORE code.** Page behaviour changing? Update `pages/<page>.md` first, then the code.
+5. **No silent failures.** Every internal validation/guard that rejects an action logs structured context (component, action, ids, inputs); user-facing failures also surface in the UI.
+6. **TDD by default.** Test before code (unit for functions, E2E for user flows).
+7. **ADR for strategic choices.** Long-term-consequence decisions get a `decisions.md` entry.
+8. **Hard Constraints are tool-enforced.** Style rules live in linter/type-checker configs, not prose.
+9. **Ask before commit.** The agent reports quality-gate results and waits for explicit approval; it never auto-commits.
+10. **Honest `known_issues.md`.** Every bug with a workaround gets Impact + Plan so it isn't re-discovered later.
+11. **One conversational language.** Talk to the user in the language chosen at bootstrap; keep code, paths, commands, and abbreviations in their source language. See *Communication contract*.
+12. **Attribution is opt-in.** Honour the *Attribution* block: by default no agent/AI/model mention anywhere (commits, PRs, code, comments, docs), and no `Co-Authored-By` trailer. See *Attribution contract*.
+13. **Orchestrate via a named recipe.** Compose execution through a named recipe (Solo / Reviewed / Council / Delegated) and **always commit yourself** — backends are advisory or delegated, never autonomous. Encoded via the reconciled `workflow:orchestration` pointer (it routes to `/agent-workflow-kit recipes` + the engine canon), not by bloating the entry point.
+
+---
+
+## Hard Constraints (template — adapt to the stack)
+
+Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
+
+| Rule | Enforcement |
+|------|-------------|
+| No `export default` (named exports only) | Linter |
+| No `any` / no unsafe casts | Linter / type-checker |
+| Functional style (no mutation in app code) | Linter |
+| No single-letter variables | Code review |
+| Interactive elements semantic (button/link, not div+onClick) | Linter / a11y |
+| No hardcoded colors — design tokens only | Code review |
+| No business logic in components → hooks/services | Architecture review |
+| No changes without tests (TDD) | Required |
+| Check page docs before changes; update them after | Process |
+| Ask user before committing | Process |
+| Every page has an HTML-validity / a11y E2E test | Required |
+| **No silent failures** — structured logging on every rejected action | Required |

package/references/shared/report-footer.md

@@ -0,0 +1,116 @@
+### The one-line backend-status line (shared by bootstrap + upgrade)
+
+Bootstrap (step 11) and **every** successful `upgrade` exit (steps 4 + 8) print the **same**
+read-only, one-line summary of the optional execution-backends. The line is **machine-composed** —
+run the status-line composer and **paste its single emitted line verbatim**:
+`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs --status-line`
+The tool runs the backend detector and appends the recipe recommendation itself
+(`composeStatusLine`); the agent **composes nothing factual** — no readiness token, no glyph, no
+recipe clause of its own, ever.
+
+- **Placeholder template (structure only — never copy this example; paste the tool's line):**
+  `backends: <alias> <✓|✗> <readiness> · <alias> <✓|✗> <readiness> — run /agent-workflow-kit backends · recipes: <recommendation clause> — see /agent-workflow-kit recipes`
+- The **`recipes:` clause is appended after** the `— run /agent-workflow-kit backends` pointer (never
+  replacing it) and routes to the read-only `recipes` mode (`see /agent-workflow-kit recipes`). It is
+  **never blank**: both backends ready → *"Council available, Reviewed the everyday default"*; one
+  ready → *"Reviewed available (via …)"*; **none installed → *"Solo — run /agent-workflow-kit setup to
+  add a backend"***; a backend present-but-not-ready → Solo with that backend's specific remedy.
+  (Composed by `recommendRecipe` inside the same tool run — never by the agent.)
+- **Invariants:** **read-only · never blocks the commit gate · never runs a subscription CLI · the
+  pointer is the in-agent `backends` mode, never a network fetch · the appended `recipes:` clause
+  routes to the in-agent `recipes` mode the same way · `init`/npx never *places* bridges (it
+  refreshes only what `setup` already placed, AD-011 §5).**
+- **Composer unavailable → skip with a stated reason, never silently.** The composer is a Node script
+  the **agent host** runs (not the target project), so the only skip condition is "**the agent host
+  can't run it**" — `node` is not on the agent's PATH, or the tool itself errors — **not** "the
+  project has no Node runtime". On that condition, skip the line and say so **with the concrete
+  reason**, e.g. *"Couldn't run the backend status-line composer here (node is not on the agent host
+  PATH), so I'm skipping the backend-status line."* — never a silent skip (Hard Constraint — no
+  silent failures).
+
+### The version block + welcome mat (shared by bootstrap + upgrade)
+
+Bootstrap (step 11) and **every** successful `upgrade` exit (steps 4 + 8) close with the same
+**report footer**, in this **canonical order**: success state → **version block** → the **one-line
+backend-status line** → **welcome mat**. Only the version block comes from
+`node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs --json` (add `--dir <project>` for the deploy
+axis) — **never hardcoded semver**; the backend-status line is its own shared contract (above), and
+the welcome mat **composes signals already gathered** (the version block's notes + the backend-status
+line), not a fresh helper call. **Beside the backend-status line**, when the target project carries a
+`docs/ai/orchestration.json`, also paste the one-line **configured-recipe line** verbatim from
+`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs --active-line` (run from the project root; `${CLAUDE_SKILL_DIR}/references/modes/recipes.md`
+documents it; same agent-host skip-with-reason contract as the status line). Present everything in the
+user's conversational language; never paste the JSON or any internal field name.
+
+**Success state — the happy path never leads with a structure number.** No happy-path report surfaces
+the project's internal `docs/ai` structure version, the stamp filename, or the internal versioning
+vocabulary — that number is inert here and only confuses; it belongs to *Version disclosure* (below).
+Frame the success itself plainly, in the **user's conversational language** (never hardcode a phrase):
+- a **zero-diff no-op `upgrade`** (step 4) → **settings already current — no update is required**
+  (illustrative tone for a Russian-speaking user, an example of the meaning, not a literal string to
+  embed: *«Настройки уже актуальны — обновление не требуется»*);
+- a **fresh `bootstrap`** → its normal "deployed and ready" success, minus the number.
+
+**Version block — the installed package versions, fed from `--json`** (the `docs/ai` structure version
+is shown on demand only — see *Version disclosure* below, **not** here):
+- **`Installed on this machine — package versions:`** `kit <v> · memory <v> · engine <v> ·
+  codex-bridge <v> · antigravity-bridge <v>` — one per `installed[]` entry, labelled by its `display`
+  and showing its `version`, or, when there is no version, the plain phrase for its `state` (map
+  below). Append any `installed[].notes` **in plain words** (e.g. the memory-behind refresh+restart
+  line).
+
+**`state` → plain language** (map the envelope's `installed[].state` token; never show the raw token):
+`installed` → its version · `absent` → "not installed" · `other-tool` → "a different tool occupies
+that skill slot" · `placeholder` → "a placeholder, not a working install" · `invalid` → "installed
+but its manifest didn't validate" · `unsupported` → "installed but its manifest schema is too new for
+this kit" · `uncheckable` → "couldn't be checked (a permission error)".
+
+**Helper-failure contract (mirror the backend-status line).** The version block needs the
+family-registry helper, which the **agent host** runs. If the host can't run it (`node` not on the
+agent's PATH, or the helper errors), **skip the version block and say so with the concrete reason** —
+e.g. *"Couldn't run the family-registry helper here (node is not on the agent host PATH), so I'm
+skipping the installed-versions block."* — never a silent skip (Hard Constraint). It is non-essential:
+the rest of the report — and the commit gate — proceeds.
+
+**Welcome mat — the last line(s) of the footer.** After the version block and the backend-status
+line, print *"Run `/agent-workflow-kit help` to see every command."* then **one** recommended next
+step, chosen **caveat-aware** from signals already in hand (the version block's notes + the
+backend-status line — no new helper call) in this priority order:
+1. a member is **behind** (a behind-class `installed[].notes` caveat fired — any member, the bridges
+   included) → *refresh the behind member first*, quoting **that note's own recovery command
+   verbatim** (a memory/engine note carries its `npx …@latest init` + restart the session; a bridge
+   note carries `/agent-workflow-kit setup`). An **uncheckable** member ("couldn't be checked" — an
+   unknown-freshness note) is **never** a refresh trigger: only a behind note fires this step — the
+   uncheckable note already appears in the version block, add nothing more;
+2. else **no backend is ready** (the backend-status line shows none ready) → *set one up with
+   `/agent-workflow-kit setup`*;
+3. else **a backend is ready but the orchestration config is still all-Solo** (no `reviewed` /
+   `council` / `delegated` slot anywhere — inspect `docs/ai/orchestration.json`, or read the
+   procedures advisor's resolved recipes) → *put it to work with `/agent-workflow-kit recipes`*;
+4. else (a backend is ready **and** a backend-backed recipe is already selected) → the optional
+   *`/agent-workflow-kit velocity`* opt-in (never run it without a yes).
+
+Keep it compact — a few short lines, plain language, no kit-internal terms.
+
+### Version disclosure — the `docs/ai` structure version, on demand only
+
+The deployment carries an internal **`docs/ai` structure version** (the envelope's `deploymentHead`) —
+the number `upgrade` compares the project's stamp against to decide whether a migration is due. The
+happy path deliberately **hides** it: a user cannot act on it, and because it advances far more slowly
+than the published package version, it reads as *"why is this smaller than what GitHub shows?"* Surface
+it in exactly **three** places, and nowhere else:
+1. the **never-downgrade STOP** (`${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 2) — the stamp is ahead of what this kit knows,
+   so the number IS the message;
+2. the **explicit version-status view** (`${CLAUDE_SKILL_DIR}/references/modes/status.md`) the user deliberately opens;
+3. when the **user explicitly asks** about versions.
+
+When you show it, **name what it versions — "the `docs/ai` structure version"** (render that meaning in
+the user's conversational language) — **never** "lineage head", "deployment head", or any raw internal
+token. Pair it with **one plain-language line** telling the two axes apart, on demand only:
+
+> the number your project carries versions its `docs/ai` **structure**; the (usually larger) number on
+> npm/GitHub is the **tool's own package version** — the two advance independently, so a bigger package
+> number is **not** a newer deployment.
+
+**Never** print this two-axes line on a successful equal-head exit — only at the STOP, the status view,
+or on an explicit ask.

package/references/templates/agent_rules.md

@@ -18,8 +18,9 @@ Every AI agent working on this project **must** adhere to this protocol before w
 ### 1.1. Start of Session
 Read in order, then confirm before starting:
 1. `docs/ai/handover.md` — where we left off.
-2. `docs/ai/active_plan.md` — pick ONE task from "Immediate Priority".
-3. Confirm with the user: *"I'm taking task X. Confirm?"*
+2. `docs/ai/orchestration.json` — the CONFIGURED orchestration recipes (per activity/slot). Honor them: a silent recipe downgrade is a forbidden substitution.
+3. `docs/ai/active_plan.md` — pick ONE task from "Immediate Priority".
+4. Confirm with the user: *"I'm taking task X. Confirm?"*
 
 ### 1.2. During Work
 **Before any feature:** read the relevant page spec (`docs/ai/pages/<page>.md`). If behaviour changes, update the spec FIRST so docs and code never diverge.

package/references/templates/handover.md

@@ -14,6 +14,7 @@ maxLines: 80
 
 **Last session:** {{DATE}}
 **Branch:** {{BRANCH}}
+**Active recipes:** not recorded yet — paste the configured-recipe line (composed from `docs/ai/orchestration.json`) and refresh it whenever the config changes.
 
 ## What was done last session
 

package/tools/commands.mjs

@@ -131,7 +131,7 @@ const CATALOG = [
     invocation: invocationOf('recipes'),
     group: 'Orchestrate',
     kind: READ_ONLY,
-    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated) and which one fits this environment.',
+    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated), which one fits this environment, and the configured per-activity line to paste at session start.',
   },
   {
     key: 'procedures',
@@ -147,6 +147,20 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Set the orchestration recipe for an activity from plain language — previews the change, then writes the config when you confirm.',
   },
+  {
+    key: 'review-state',
+    invocation: invocationOf('review-state'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Check that every configured review backend has receipted the current uncommitted tree with a fresh grounded review; --check turns it into a gate exit code.',
+  },
+  {
+    key: 'grounding',
+    invocation: invocationOf('grounding'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Assemble the verified-facts payload a grounded review runs against — the entry-point Hard Constraints plus a plan’s decision sections; prints it, or writes ONE scratch file with --out.',
+  },
 ];
 
 // Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime

package/tools/detect-backends.mjs

@@ -88,6 +88,7 @@ const RAW_BACKENDS = [
         ],
         grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
         continue: [],
+        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); a write failure warns, never fails the review',
       },
     },
     bin: 'codex',
@@ -120,6 +121,7 @@ const RAW_BACKENDS = [
           'agy-review --continue [--decided @f] [--focus "…"]',
           'agy-review --conversation <id> [--decided @f] [--focus "…"]',
         ],
+        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); a write failure warns, never fails the review",
       },
     },
     bin: 'agy',

package/tools/engine-source.mjs

@@ -107,7 +107,8 @@ export const detectEngine = (engineDir, { source, rel } = {}, deps = {}) => {
 // on the happy path; THROWS a loud Error naming the resolved dir + the reason + the exact
 // remediation on absent/invalid/unreadable — never a fallback (fail-closed). The "methodology engine
 // not found/invalid" prefix is a stable contract: the agent classifies the reconcile STOP by it
-// (distinct from the cap-skip message), so do not reword it without updating SKILL.md.
+// (distinct from the cap-skip message), so do not reword it without updating the upgrade mode file
+// (references/modes/upgrade.md, step 3 exit classification).
 export const readEngineFragment = (engineDir, deps = {}) => {
   const detection = detectEngine(engineDir, { source: deps.source, rel: deps.rel }, deps);
   const installHint = `npx @sabaiway/agent-workflow-engine@latest init  (or set ${ENGINE_ENV})`;