@sabaiway/agent-workflow-kit 1.31.0 → 1.33.0

package/CHANGELOG.md

@@ -4,6 +4,91 @@ 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.33.0 — The agent-rules lens region: render + reconcile from the engine canon (AD-041)
+
+A **feature** release (new shipped tool + wiring; deployment-lineage head stays `1.3.0` — the
+refresh is stamp-independent, no migration). The deployed `docs/ai/agent_rules.md` lens section
+is now a RENDER of the engine's canonical fragment, kept current by the kit:
+
+- **New `tools/lens-region.mjs`** — the lens reconcile: heading-anchored region (no markers; a
+  renamed heading is a natural preserve+advise), render with the file's OWN section number,
+  refresh IFF the body matches the engine fragment or a known-prior body (fragment + prior store
+  read LIVE from the installed engine — no kit-side prior constants), a customized region
+  preserved verbatim + a one-line advisory, cap-guard from the target's frontmatter `maxLines`
+  (loud non-fatal refusal; no frontmatter → stated skip), atomic write, document EOL preserved.
+  Lazy + fail-loud: an absent/invalid engine is a STOP with the install command; a valid engine
+  older than 1.13.0 (no lens pair) is a stated soft skip. CLI:
+  `node tools/lens-region.mjs reconcile <path/to/agent_rules.md>`; invariants pinned by
+  `tools/lens-region.test.mjs` incl. the canon-change simulation (v1 deploy + v2 engine →
+  refreshed; re-run → zero-diff).
+- **`Mode: upgrade` step 3** gains the SEVENTH stamp-independent reconcile (plain-language
+  outcomes: refreshed / already current / custom preserved + note / file absent / engine too
+  old / over the line cap), reported in both the step-4 and step-8 exit reports; the stale
+  "other three reconciles" phrasing went count-free.
+  `references/shared/composition-handoff.md` runs the same reconcile in BOTH bootstrap paths
+  (its own precondition: after `docs/ai/agent_rules.md` exists) — this is what converges a
+  stale-memory seed; `handoffPlan` names the lens region in `kitWrites` for both paths.
+- **`family-registry`**: a distinct plain-language `status` caveat for an engine that does not
+  ship the lens canon — keyed on the PAIR (fragment + prior store), so a half-shipped engine
+  never reports healthy.
+- **`test/lens-mirror.test.mjs` REWRITTEN** to render-parity vs the known-canonical set (each
+  template lens block byte-equals a render of the engine fragment or a prior-store entry; the
+  checkout additionally pins the CURRENT render; injected non-vacuity). The 22-token × 4-file
+  vocabulary mesh is deleted — token presence now lives in the ENGINE's own lens-fragment guard,
+  so a future lens wording change is an engine-only release (no forced kit/memory diffs).
+- `references/templates/agent_rules.md` §2.5 intro carries the provenance clause (the render);
+  `tools/engine-source.mjs` exports `LENS_FRAGMENT_REL` + `LENS_PRIORS_REL`. Tarball 115 → 116
+  (`lens-region.mjs` reverse-pinned). AD-039 byte budgets hold unchanged.
+- Repo-local release harness: `scripts/release/smoke-init.mjs` gains repeatable
+  `--expect-file <sandbox-HOME-relative path>=<substring>` (installed-file content assertions;
+  both path dialects fenced to the sandbox HOME).
+
+## 1.32.0 — Approval-idle reduction: the opt-in `velocity --kit-tools` tier, an audited core extension, and the standing-consent advisory (AD-040)
+
+A **feature** release; packaging-only for deployments (lineage stays `1.3.0` — no `docs/ai`
+structure change, no migration). Routine read-only kit-tool invocations — the session-start
+discovery line, the procedures advisor, the status/backends/gates checks — stop idling on
+approval prompts, opt-in and honestly labeled; nothing that writes, commits, or publishes gets
+any quieter.
+
+- **`velocity --kit-tools` (opt-in tier).** On top of the read-only core, seeds 12 entries derived
+  from the RUNNING skill's own location at seed time: 8 read-only kit tools as resolved-absolute
+  script path + args wildcard (`recipes` / `procedures` / `family-registry` / `detect-backends` /
+  `commands` / `review-state` / `manifest/validate` / `release-scan`), `run-gates.mjs` as ONE
+  exact byte-string pinned `--cwd <resolved project root>` and advertised **project-exec, never
+  "read-only"** (a wildcard would be broader than the AD-037 hook boundary), and the three
+  default-dry-run writers' exact arg-free preview byte-strings (`velocity-profile`,
+  `cheap-agents`, `gate-hook`) — every `--apply`/`--write`/`--yes` still prompts. Fail-safe by
+  construction: a moved skill or stale path simply prompts again; non-POSIX / space- /
+  quote-carrying paths are refused up front with a typed error (hand-add fallback). Flagless
+  `velocity` behavior is unchanged (validates core-only, never depends on skill paths).
+- **Dead-rule prevention as a test.** The `velocity.md` tier subsection lists the covered dispatch
+  line per tool (the documented-invocation source); the new `test/kit-readonly-tools.test.mjs`
+  substitutes the resolved skill dir (+ project root for run-gates) into each line and asserts the
+  seeded byte-form matches (prefix for wildcard, equality for exact) — plus the tier ↔
+  `commands.mjs` catalog-partition guard (run-gates the only project-exec member; the two
+  non-mode-backed validators get a writes-nothing source assertion).
+- **Audited read-only core 18 → 31 (the AD-021 empirical method, probe record in AD-040).**
+  Survivors: `diff`, `stat`, `du`, `basename`, `dirname`, `realpath`, `git rev-parse`,
+  `git blame`, `git shortlog`, `git describe`, and the FIXED forms `git tag --list`,
+  `git stash list`, `git worktree list` (their bare forms mutate — probe-proven). FAILED and
+  excluded: `file` (`-C -m` compiles a magic FILE WRITE) and `git cat-file` (`--textconv`/
+  `--filters` run configured filters; `git show` already covers the reads). The PreToolUse hook's
+  `SEEDED_READONLY_CORE` extends in LOCKSTEP (order-sensitive parity guard); an already-placed
+  hook keeps the OLD core (a strict subset) until a delete-to-reseed refresh.
+- **Sharper pre-existing advisory.** `node …`-shaped allow entries OUTSIDE the derived tier
+  (foreign script path, foreign `run-gates --cwd` root) are now flagged for hand review — the
+  tier's shape can never hide arbitrary local JS.
+- **`set-recipe` standing-consent advisory (wording-only).** After a `--write` that names a
+  reviewed/council recipe, the mode file now advises the one-time HAND-adds
+  (`codex-review` / `agy-review` / `grounding.mjs`) to `settings.local.json` — stating plainly
+  that auto-approval spends subscription quota without a per-run prompt, the kit never writes
+  that file, and the entry must match the invocation byte-form including quoting. Solo recipes
+  get no advisory; the tool echo is untouched.
+- **Honesty floor, twinned.** The velocity residual notice + its `velocity.md` prose mirror now
+  both carry the approval floor: every writer apply-class flag still prompts, clobber-protection
+  STOPs still stop, the three release asks (commit/push/publish) stay maintainer-owned.
+
 ## 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

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: '1.31.0'
+  version: '1.33.0'
 ---
 
 # agent-workflow-kit
@@ -75,7 +75,7 @@ Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide
 
 - **absent** → bootstrap (a fresh deployment).
 - **stamp < `1.3.0`** (the deployment-lineage head) → `upgrade`.
-- **stamp == `1.3.0`** → already current; only the stamp-independent reconciles may run — the FULL set lives in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3 (pointer slots · hidden-mode footprint · both `.json` config ensures · the enforcement-script ensure · the placed-bridge refresh); run step 3 rather than enumerating from memory.
+- **stamp == `1.3.0`** → already current; only the stamp-independent reconciles may run — the FULL set lives in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3 (pointer slots · hidden-mode footprint · both `.json` config ensures · the enforcement-script ensure · the placed-bridge refresh · the agent-rules lens refresh); run step 3 rather than enumerating from memory.
 - **stamp > head / unparseable** → STOP — never-downgrade gate (see `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 2).
 
 **Two independent version axes — never conflate them:**

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.31.0",
+  "version": "1.33.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/hooks/gate-approve.mjs

@@ -71,6 +71,13 @@ export const SEEDED_READONLY_CORE = Object.freeze([
   'Bash(git ls-files:*)',
   'Bash(git check-ignore:*)',
   'Bash(git branch --list:*)',
+  'Bash(git rev-parse:*)',
+  'Bash(git blame:*)',
+  'Bash(git shortlog:*)',
+  'Bash(git describe:*)',
+  'Bash(git tag --list:*)',
+  'Bash(git stash list:*)',
+  'Bash(git worktree list:*)',
   'Bash(npm view:*)',
   'Bash(npm ls:*)',
   'Bash(npm outdated:*)',
@@ -82,6 +89,12 @@ export const SEEDED_READONLY_CORE = Object.freeze([
   'Bash(readlink:*)',
   'Bash(which:*)',
   'Bash(grep:*)',
+  'Bash(diff:*)',
+  'Bash(stat:*)',
+  'Bash(du:*)',
+  'Bash(basename:*)',
+  'Bash(dirname:*)',
+  'Bash(realpath:*)',
 ]);
 
 // Baked frozen copy of velocity-profile.mjs RUNTIME_RESIDUAL_FORMS (the documented residual a

package/references/modes/set-recipe.md

@@ -16,6 +16,7 @@ Run **`node ${CLAUDE_SKILL_DIR}/tools/set-recipe.mjs [--set <activity>.<slot>=<r
 1. **Grammar — always fully-qualified `<activity>.<slot>`** (the kit never guesses the activity; a bare `review=council` is rejected). `review` accepts `solo|reviewed|council`; `execute` accepts `solo|delegated`. Activities/slots: `plan-authoring.review`, `plan-execution.execute`, `plan-execution.review`.
 2. **Preview by default** — prints `current → proposed` for the **changed** slots only, plus the **effective recipe resolved against live backend readiness** (degradation stated honestly, e.g. *council requested, 1 ready reviewer → runs reviewed until a 2nd backend is ready*). It writes **nothing**. Re-run with **`--write`** to apply (same effective/degradation note — a direct `--write` is never quieter than the preview). `--unset` returns a slot to its computed default (reverting needs no hand-edit either). A no-op `--set` (slot already equals) writes nothing and never re-seeds the onboarding note.
 3. **`--write`** applies via a hardened, atomic write (deployment-gated — refuses to scatter a config into a repo with no `docs/ai`; exclusive-create temp + rename; symlink/TOCTOU-safe; last-writer-wins). It preserves the onboarding note + every untouched slot, normalizing to canonical 2-space JSON.
+   **Standing-consent advisory (after a successful `--write` only, and only when the written config names a `reviewed`/`council` recipe — a solo recipe gets NO advisory):** advise the ONE-TIME **hand-adds** to the maintainer's `.claude/settings.local.json` — `Bash(codex-review:*)` + `Bash(agy-review:*)` + `Bash(node <skill-dir>/tools/grounding.mjs:*)`, with the path your project actually reaches the kit by. State plainly: (a) auto-approving a review wrapper **spends subscription quota without a per-run prompt** — that is exactly what standing consent means here, so it is the maintainer's call; (b) the kit **never writes that file** — these stay hand-adds; (c) `grounding.mjs --out` writes ONE scratch facts file — that write is what the standing consent covers; (d) the entry must match the invocation **byte-form your project actually uses, INCLUDING quoting** — the procedures advisor renders a QUOTED skill path, and a hand-add covering it must use the same spelling (a mismatched spelling is a dead rule that simply prompts).
 4. **Exit codes:** `0` success (an explicit recipe that gracefully degrades is still `0`); `2` usage (a bare/duplicate op, or `--write` with no ops); `1` config error (malformed/unreadable config — the file is left **untouched**, never clobbered) or a write STOP (no deployment / a symlinked config). A `1`/`2` failure is loud; on a malformed config, offer to show the parse error so you can help the user fix the JSON.
 
 Output is **English/structured** — **localize it to the user's conversational language** when you narrate. Surface the effective-recipe/degradation note plainly.

package/references/modes/upgrade.md

@@ -32,15 +32,25 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    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`).
+   downgrade**). Like the other stamp-independent 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.
+
+   **Agent-rules lens refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.**
+   Run `node ${CLAUDE_SKILL_DIR}/tools/lens-region.mjs reconcile <project>/docs/ai/agent_rules.md`
+   and relay its outcome in plain language: the planning/review lens section was **refreshed** to
+   the current canon · was **already current** · carries a **custom edit — preserved verbatim** (+
+   its one-line note) · the **file is absent — skipped** · the **engine is too old — skipped**
+   (refresh it with `npx @sabaiway/agent-workflow-engine@latest init`, then re-run) · **over the
+   file's line cap — refused** (trim the file, re-run). The section is found by its heading — no
+   markers; a renamed heading is preserved + noted. A fully absent/invalid engine is the same hard
+   STOP as (c). Exit 0 covers every soft outcome; only the STOP is non-zero.
+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 stamp-independent 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); the **agent-rules lens** outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*); 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**.
+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) and the step-3 **agent-rules lens** outcome (same outcome set as step 4) — 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

@@ -4,15 +4,30 @@ The opt-in onboarding **velocity profile** — it seeds a fixed, audited **read-
 
 **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>]`:
+Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [--kit-tools] [--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:
+2. **Ask the opt-ins** via **`AskUserQuestion` where supported** — two separate choices, the safe option FIRST in each. First the **`--kit-tools` tier** (separate from `acceptEdits`; **"core only" remains the default answer** — seed the tier only on an explicit yes, then add `--kit-tools` to the `--apply` re-run). Then the `acceptEdits` opt-in:
    - **"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`.
+   - **"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). The approval **floor** (never auto-approved, with or without the tier): every writer `--apply`/`--write`/`--yes` still prompts; clobber-protection STOPs still stop; the three release asks (commit/push/publish) stay maintainer-owned. 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.**
 
+**The `--kit-tools` tier (opt-in).** On top of the read-only core, `--kit-tools` seeds an audited kit-tool tier — every path **resolved absolute from the running skill at seed time**, so the posture is **fail-safe**: a moved or reinstalled skill leaves a stale rule that simply **prompts again** (re-run velocity to reseed; nothing widens silently). A seeded entry equals its covered dispatch line below with `${CLAUDE_SKILL_DIR}` replaced by the resolved skill dir and `${PROJECT_ROOT}` by this project's resolved root, **UNQUOTED** — a quoted path is a different byte string and will still prompt (a dead rule, not a hole). The covered dispatch lines (this list IS the documented-invocation source):
+
+- `node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs --active-line` — and any other args (wildcard)
+- `node ${CLAUDE_SKILL_DIR}/tools/procedures.mjs <activity>` (wildcard)
+- `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs --json` (wildcard)
+- `node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs` (wildcard)
+- `node ${CLAUDE_SKILL_DIR}/tools/commands.mjs` (wildcard)
+- `node ${CLAUDE_SKILL_DIR}/tools/review-state.mjs --check` (wildcard)
+- `node ${CLAUDE_SKILL_DIR}/tools/manifest/validate.mjs --strict <skill-dir>` (wildcard)
+- `node ${CLAUDE_SKILL_DIR}/tools/release-scan.mjs <path>` (wildcard)
+- `node ${CLAUDE_SKILL_DIR}/tools/run-gates.mjs --cwd ${PROJECT_ROOT}` — **EXACT byte-string only**, and honestly **project-exec, not read-only**: it runs YOUR declared `docs/ai/gates.json` commands — the same trust boundary the opt-in hook grants byte-exact per-cmd. A wildcard would be BROADER than that boundary (`--cwd <dir>` executes another project's declared gates), so the bare cwd-defaulting form, any other `--cwd`, and `--only` forms all still prompt.
+- Writer previews, **exact arg-free dry-run byte-strings only** (for these three writers the arg-free default IS the preview): `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs` · `node ${CLAUDE_SKILL_DIR}/tools/cheap-agents.mjs` · `node ${CLAUDE_SKILL_DIR}/tools/gate-hook.mjs` — every `--apply`/`--write`/`--yes` still prompts, always.
+
+Honesty notes: tier entries get **NO PreToolUse-hook residual coverage** — the opt-in hook's residual ask-net guards only the seeded read-only CORE prefixes, so the tier rides the same settings-level residual posture as the core (redirection / command substitution are not inspectable at the settings layer; see the residual notice). A skill or project path that cannot survive UNQUOTED in a byte-exact rule (spaces, metacharacters, non-POSIX) **STOPs the tier up front with a clear error** — nothing is seeded. Anything you want covered beyond the tier — such paths, this repo's own relative-path spellings, other tools — stays a **BY-HAND add** to your settings, with the path your project actually reaches the kit by. Pre-existing `node …` allow entries that do NOT match the seeded tier byte-forms stay flagged by the advisory for hand review.
+
 **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

@@ -37,3 +37,15 @@ ordered `start → end` pair; a malformed slot (single, reversed, nested, duplic
 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.
+
+**Agent-rules lens refresh (runs in BOTH paths).** Its precondition is its own target file — run it
+only after `<project>/docs/ai/agent_rules.md` exists: after the substrate deploy in the
+**delegated** path, after the fallback-template copy in the **kit** path (never anchored to the
+`AGENTS.md` step above). ONE command:
+`node ${CLAUDE_SKILL_DIR}/tools/lens-region.mjs reconcile <project>/docs/ai/agent_rules.md`.
+This is what converges a substrate seeded by an older memory — a lens section matching a known
+prior canonical body is refreshed from the installed engine; a current seed reports *already
+current* (zero-diff). Relay its outcome in plain language (*refreshed* / *already current* /
+*custom edit preserved + note* / *file absent — skipped* / *engine too old — skipped* / *over the
+line cap — refused*); a fully absent/invalid engine is the same loud STOP + one-line install
+command as the pointer reconcile.

package/references/templates/agent_rules.md

@@ -63,7 +63,7 @@ Before proposing changes or committing, review against:
 - Always run type-checker, linter, and all tests before committing.
 
 ### 2.5. Planning, review & process-fidelity invariants
-Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon.)
+Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
 - **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.

package/tools/delegation.mjs

@@ -83,7 +83,9 @@ export const handoffPlan = (delegate) =>
     ? {
         mode: 'delegate',
         memoryWrites: ['docs/ai/', 'AGENTS.md', 'docs/ai/.memory-version'],
-        kitWrites: ['AGENTS.md methodology slot', 'docs/ai/.workflow-version'],
+        // The lens region runs AFTER the substrate deploy (its own precondition: the file exists)
+        // — it converges a stale-memory seed to the installed engine's canon (AD-041).
+        kitWrites: ['AGENTS.md methodology slot', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
         stampsPresent: ['.memory-version', '.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',
@@ -93,8 +95,9 @@ export const handoffPlan = (delegate) =>
         memoryWrites: [],
         // Fallback now ships the kit's OWN AGENTS.md carrying the EMPTY methodology slot (Plan 2);
         // the kit reconciles it (ensure-slot + inject-because-empty) exactly like the delegate
-        // path — so both paths end with a FILLED slot, not inline methodology.
-        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md methodology slot', 'docs/ai/.workflow-version'],
+        // path — so both paths end with a FILLED slot, not inline methodology. The lens region
+        // runs after the fallback-template copy of docs/ai (same reconcile, both paths — AD-041).
+        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md methodology slot', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
         stampsPresent: ['.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',

package/tools/engine-source.mjs

@@ -31,6 +31,12 @@ export const ORCHESTRATION_FRAGMENT_REL = 'references/orchestration-slot.md';
 // CLI fail loudly on — an engine too old to ship it. readEngineFragment accepts an arbitrary `rel`
 // (no whitelist), so no further plumbing is needed beyond this constant.
 export const PROCEDURES_FRAGMENT_REL = 'references/procedures.md';
+// The agent-rules lens pair — the canonical lens block + its append-only prior store (engine
+// >= 1.13.0; an older engine ships neither). The kit's lens-region reconcile live-reads BOTH via
+// readEngineFragment({ rel }); detectEngine({ rel }) lets it soft-skip a too-old engine (and
+// `status` caveat it) instead of failing the whole reconcile.
+export const LENS_FRAGMENT_REL = 'references/agent-rules-lens.md';
+export const LENS_PRIORS_REL = 'references/agent-rules-lens-priors.md';
 const ENGINE_DEFAULT_REL = '.claude/skills/agent-workflow-engine';
 
 const defaultStatType = (path) => {

package/tools/family-registry.mjs

@@ -26,7 +26,7 @@ import { resolveDir, detectBackends, findOnPath } from './detect-backends.mjs';
 import { parseSemver, compareSemver } from './semver-lite.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { START_MARKER, excludePath, inferVisibility } from './hide-footprint.mjs';
-import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
+import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL, LENS_FRAGMENT_REL, LENS_PRIORS_REL } from './engine-source.mjs';
 import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
 // The config reader lives in orchestration-config.mjs (the single config contract). The read-only status
 // settings-survey reuses THIS reader (one strict-JSON + loud-on-malformed contract), not a second copy.
@@ -171,9 +171,13 @@ export const classifyMember = (member, deps = {}) => {
 // the manifest AND reads the fragment — so an absent, non-file, OR present-but-unreadable fragment all
 // surface (status never claims "ok" for a fragment a reconcile / the procedures CLI would STOP on), and
 // a current, readable fragment never gets the caveat. Read-only, best-effort.
+// Each caveat names the rel(s) its consumer actually needs: the lens reconcile requires the
+// fragment AND its prior store as a PAIR (lens-region soft-skips when either is missing), so its
+// caveat keys on both — an engine missing only the prior store must never report healthy.
 const ENGINE_FRAGMENT_CAVEATS = [
-  { rel: ORCHESTRATION_FRAGMENT_REL, caveat: 'engine present but does not supply the recipes pointer (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
-  { rel: PROCEDURES_FRAGMENT_REL, caveat: 'engine present but does not ship the activity-procedures canon (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
+  { rels: [ORCHESTRATION_FRAGMENT_REL], caveat: 'engine present but does not supply the recipes pointer (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
+  { rels: [PROCEDURES_FRAGMENT_REL], caveat: 'engine present but does not ship the activity-procedures canon (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
+  { rels: [LENS_FRAGMENT_REL, LENS_PRIORS_REL], caveat: 'engine present but does not ship the agent-rules lens canon (the fragment + its prior store; too old / incomplete — engine >= 1.13.0) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
 ];
 
 // The orchestration-config TEMPLATE a current memory ships (added in memory 1.2.0; absent in older
@@ -244,7 +248,7 @@ export const surveyFamily = (deps = {}) =>
           return false; // absent / non-file / unreadable fragment → the engine can't supply it
         }
       };
-      const caveats = ENGINE_FRAGMENT_CAVEATS.filter((f) => !fragmentUsable(f.rel)).map((f) => f.caveat);
+      const caveats = ENGINE_FRAGMENT_CAVEATS.filter((f) => !f.rels.every(fragmentUsable)).map((f) => f.caveat);
       if (caveats.length) row.caveats = caveats;
     }
     // Memory offline caveat (Step 2.2): a distinct probe — the orchestration TEMPLATE file's existence.

package/tools/lens-region.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+// Heading-anchored lens-region reconcile — the composition root's only mutation of a deployed
+// `docs/ai/agent_rules.md`. The planning/review/process-fidelity lens block (`### 2.x. Planning,
+// review & process-fidelity invariants`) has ONE canonical home — the installed engine's
+// `references/agent-rules-lens.md` — and every deployed/template copy is a RENDER of it (the
+// file's own section number substituted into the number-neutral heading). This tool refreshes a
+// deployed region to the current canon under the AD-025 discipline: refresh IFF the region's
+// normalized body matches the current fragment (already current → zero-diff) or a KNOWN PRIOR
+// canonical body (the engine's append-only `references/agent-rules-lens-priors.md`, read live
+// beside the fragment — no kit-side prior constants, so a canon wording change is an engine-only
+// release). Anything else is preserved byte-for-byte + a one-line advisory.
+//
+// The region has NO markers (unlike the AGENTS.md pointer slots): it is located by the heading
+// through the next structural boundary (`---` / `##` / `###`) or EOF — the extraction rule the
+// lens-mirror guard pioneered, promoted here as the shipped implementation. A user-renamed
+// heading is therefore a natural preserve+advise; bytes outside the region are never touched.
+//
+// The live read is lazy + fail-loud: the engine is consulted only when a present region must be
+// classified; a fully absent/invalid engine is a loud STOP (never a silent fallback), a valid
+// engine that merely predates the lens pair (<1.13.0) is a stated soft skip. Cap-guard: a refresh
+// that would push the file over its own frontmatter `maxLines` is a loud, non-fatal refusal —
+// never a silent truncate; a file without frontmatter/`maxLines` skips the guard with a stated
+// note (such a file is outside the docs cap gate anyway).
+//
+// Pure string functions (fs only in the CLI); dependency-free, Node >= 18.
+
+import { normalizeCanonical } from './orchestration-config.mjs';
+
+// The deployed-heading matcher (prefix, like the historical extractLensBlock: robust to a future
+// heading-tail tweak) and the number-neutral form the engine fragment carries.
+export const LENS_HEADING_RE = /^### 2\.(\d+)\. Planning, review & process-fidelity/;
+const NEUTRAL_HEADING_RE = /^### 2\.x\. Planning, review & process-fidelity/;
+const HEADING_LABEL = '### 2.x. Planning, review & process-fidelity invariants';
+
+const stripCr = (line) => (line.endsWith('\r') ? line.slice(0, -1) : line);
+const isBoundary = (bareLine) => bareLine === '---' || /^#{2,3} /.test(bareLine);
+
+// Count lines independent of a trailing newline (the inject-methodology contract).
+const lineCount = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+
+// ── the frozen prior-store format (documented in the store file's own header) ─────
+// A delimiter is a line that starts with `<!-- prior` and ends with `-->`; an entry body is
+// everything after it up to the next delimiter / EOF, trimmed. The pre-delimiter header is
+// ignored. APPEND-ONLY on the engine side — this parser must keep reading a newer engine's file.
+export const parseLensPriors = (text) => {
+  const entries = [];
+  let current = null;
+  for (const line of String(text).split('\n')) {
+    const bare = stripCr(line);
+    if (bare.startsWith('<!-- prior') && bare.endsWith('-->')) {
+      if (current) entries.push(current.join('\n'));
+      current = [];
+    } else if (current) current.push(line);
+  }
+  if (current) entries.push(current.join('\n'));
+  return entries.map((e) => normalizeCanonical(e)).filter((e) => e !== '');
+};
+
+// renderLens(fragment, number) → the number-neutral canonical block bound to the file's OWN
+// section number (memory-seeded files say 2.6, kit-fallback files 2.5 — the fragment never
+// hardcodes one). LF-canonical; the CLI converts to the document's EOL style on write.
+export const renderLens = (fragment, number) =>
+  normalizeCanonical(fragment).replace(NEUTRAL_HEADING_RE, (m) => m.replace('2.x', `2.${number}`));
+
+// normalizeLensBody(body) → the number-neutral, whitespace/EOL-normalized comparison form
+// (heading number → `2.x`, trim, CRLF→LF) every known-set match uses.
+export const normalizeLensBody = (body) =>
+  normalizeCanonical(String(body).replace(/^### 2\.\d+\./, '### 2.x.'));
+
+// extractLensRegion(text) → { found: false } | { found, start, end, number, body }.
+// `start`/`end` are line indices over text.split('\n') — heading line through (exclusive) the
+// next structural boundary; EOF is a valid region end (no following boundary required). `body`
+// is the CR-stripped block with trailing blank lines dropped (the comparison form); the raw
+// region lines (including trailing blanks) are what replaceLensRegion preserves around a render.
+export const extractLensRegion = (text) => {
+  const lines = String(text).split('\n');
+  const start = lines.findIndex((line) => LENS_HEADING_RE.test(stripCr(line)));
+  if (start === -1) return { found: false };
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (isBoundary(stripCr(lines[i]))) {
+      end = i;
+      break;
+    }
+  }
+  const number = stripCr(lines[start]).match(LENS_HEADING_RE)[1];
+  const regionLines = lines.slice(start, end);
+  let bodyEnd = regionLines.length;
+  while (bodyEnd > 0 && stripCr(regionLines[bodyEnd - 1]).trim() === '') bodyEnd -= 1;
+  const body = regionLines.slice(0, bodyEnd).map(stripCr).join('\n');
+  return { found: true, start, end, number, body };
+};
+
+// replaceLensRegion(text, region, renderedBody) → the document with ONLY the region's block
+// lines replaced; trailing blank lines inside the region and every byte outside it are
+// preserved verbatim. Output keeps the document's EOL style (CRLF documents stay CRLF).
+export const replaceLensRegion = (text, region, renderedBody) => {
+  const lines = String(text).split('\n');
+  const crlf = String(text).includes('\r\n');
+  const regionLines = lines.slice(region.start, region.end);
+  let bodyEnd = regionLines.length;
+  while (bodyEnd > 0 && stripCr(regionLines[bodyEnd - 1]).trim() === '') bodyEnd -= 1;
+  const trailing = regionLines.slice(bodyEnd); // preserved verbatim (their own CR bytes intact)
+  const newBody = renderedBody.split('\n').map((l) => (crlf ? `${l}\r` : l));
+  const out = [...lines.slice(0, region.start), ...newBody, ...trailing, ...lines.slice(region.end)];
+  // In a CRLF document, only a line FOLLOWED by another line carries the CR byte; when the new
+  // body's last line is the final line of the whole document (EOF region, no trailing newline),
+  // strip the CR we just added so no stray byte lands at EOF.
+  if (crlf && trailing.length === 0 && region.end === lines.length) {
+    out[out.length - 1] = stripCr(out[out.length - 1]);
+  }
+  return out.join('\n');
+};
+
+// reconcileLensText(text, fragment, priors) — the PURE policy decision:
+//   { status: 'no-region' }  — heading absent/renamed → preserve + advise (caller words it).
+//   { status: 'current' }    — the region already renders the current canon → zero-diff.
+//   { status: 'refreshed', text } — the region matched the canon or a known prior → re-rendered
+//                                   with the file's OWN number (cap-guard is the caller's, so the
+//                                   decision stays pure).
+//   { status: 'custom' }     — anything else → preserved byte-for-byte + advisory.
+export const reconcileLensText = (text, fragment, priors) => {
+  const region = extractLensRegion(text);
+  if (!region.found) return { status: 'no-region', text };
+  const current = normalizeLensBody(region.body);
+  const canon = normalizeLensBody(fragment);
+  if (current === canon) return { status: 'current', text };
+  const known = priors.map((p) => normalizeLensBody(p));
+  if (!known.includes(current)) return { status: 'custom', text };
+  return { status: 'refreshed', text: replaceLensRegion(text, region, renderLens(fragment, region.number)) };
+};
+
+// frontmatterMaxLines(text) → the file's own `maxLines:` frontmatter value, or null when the
+// file has no frontmatter block or the block carries no maxLines (→ the cap-guard is skipped
+// with a stated note, never a throw — such a file is outside the docs cap gate anyway).
+export const frontmatterMaxLines = (text) => {
+  const lines = String(text).split('\n').map(stripCr);
+  if (lines[0] !== '---') return null;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i] === '---') return null;
+    const m = lines[i].match(/^maxLines:\s*(\d+)\s*$/);
+    if (m) return Number(m[1]);
+  }
+  return null;
+};
+
+// ── CLI: `lens-region.mjs reconcile <path/to/agent_rules.md>` ─────────────────────
+// Outcome lines are the contract the upgrade/bootstrap prose relays in plain language; exit 0 on
+// every classified outcome (including the soft skips and the cap refusal), exit 1 ONLY on the
+// hard engine STOP or an unexpected fs error, exit 2 on usage.
+export const runCli = async (argv, deps = {}) => {
+  const log = deps.log ?? console.log;
+  const logError = deps.logError ?? console.error;
+  const env = deps.env ?? process.env;
+  const fs = deps.fs ?? (await import('node:fs/promises'));
+  const { dirname, basename, join, resolve } = await import('node:path');
+  const { homedir } = await import('node:os');
+  const { resolveEngineDir, detectEngine, readEngineFragment, LENS_FRAGMENT_REL, LENS_PRIORS_REL } = await import('./engine-source.mjs');
+
+  if (argv[0] !== 'reconcile' || !argv[1] || argv.length > 2) {
+    logError('usage: lens-region.mjs reconcile <path/to/agent_rules.md>');
+    return 2;
+  }
+  const targetPath = resolve(argv[1]);
+
+  // 1. Absent file → a stated skip (the memory substrate owns seeding; nothing to reconcile).
+  const text = await (async () => {
+    try {
+      return await fs.readFile(targetPath, 'utf8');
+    } catch (err) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+  })();
+  if (text === null) {
+    log(`[lens-region] ${argv[1]} is absent — skipped (nothing to reconcile; the substrate seeds it at bootstrap).`);
+    return 0;
+  }
+
+  // 2. No matching heading → preserve + advise, engine never consulted (the outcome is preserve
+  //    regardless, so the lazy contract holds).
+  if (!extractLensRegion(text).found) {
+    log(`[lens-region] no "${HEADING_LABEL}" section in ${argv[1]} — left untouched.`);
+    log('[lens-region] note: the planning/review lens section is missing or renamed — it cannot be auto-refreshed; restore the canonical heading to re-enable refresh.');
+    return 0;
+  }
+
+  // 3. A present region must be classified → live-read the engine's fragment + prior store.
+  //    Fully absent/invalid engine → loud STOP; valid-but-pre-lens engine → stated soft skip.
+  const { dir, source } = resolveEngineDir({ env, home: deps.home ?? homedir() });
+  const lensPairPresent =
+    detectEngine(dir, { source, rel: LENS_FRAGMENT_REL }).ok && detectEngine(dir, { source, rel: LENS_PRIORS_REL }).ok;
+  if (!lensPairPresent) {
+    if (detectEngine(dir, { source }).ok) {
+      log('[lens-region] skipped — the installed engine is too old (or incomplete) to supply the lens canon; refresh it with `npx @sabaiway/agent-workflow-engine@latest init`, then re-run.');
+      return 0;
+    }
+    try {
+      readEngineFragment(dir, { source, rel: LENS_FRAGMENT_REL }); // throws the canonical install-me error
+      return 1; // defensive: the pair is unusable — never proceed to a read
+    } catch (err) {
+      logError(`[lens-region] reconcile STOP — ${err.message}`);
+      return 1;
+    }
+  }
+  // TOCTOU guard: a fragment that vanishes between detect and read is a corruption STOP, never a
+  // silent proceed — readEngineFragment's own throw carries the install command.
+  let fragment;
+  let priors;
+  try {
+    fragment = readEngineFragment(dir, { source, rel: LENS_FRAGMENT_REL });
+    priors = parseLensPriors(readEngineFragment(dir, { source, rel: LENS_PRIORS_REL }));
+  } catch (err) {
+    logError(`[lens-region] reconcile STOP — ${err.message}`);
+    return 1;
+  }
+
+  // 4. The pure decision + the cap-guard + one atomic write.
+  const result = reconcileLensText(text, fragment, priors);
+  if (result.status === 'current') {
+    log('[lens-region] lens section already current — nothing to do (zero-diff).');
+    return 0;
+  }
+  if (result.status === 'custom') {
+    log('[lens-region] lens section carries a custom edit — preserved verbatim.');
+    log('[lens-region] note: the canonical planning/review lens has changed since this section was edited — compare it with the project methodology canon when convenient; your wording is never overwritten.');
+    return 0;
+  }
+  // refreshed → cap-guard from the TARGET's own frontmatter, then atomic write.
+  const maxLines = frontmatterMaxLines(text);
+  if (maxLines === null) {
+    log('[lens-region] note: no `maxLines` frontmatter on the target — the line-cap guard is skipped.');
+  } else if (lineCount(result.text) > maxLines) {
+    log(`[lens-region] refused — refreshing would push ${argv[1]} to ${lineCount(result.text)} lines (cap ${maxLines}); trim the file and re-run. Nothing was changed.`);
+    return 0;
+  }
+  const tmp = join(dirname(targetPath), `.${basename(targetPath)}.tmp-${process.pid}-${Date.now()}`);
+  try {
+    await fs.writeFile(tmp, result.text, 'utf8');
+    await fs.rename(tmp, targetPath);
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+  log('[lens-region] refreshed the planning/review lens section to the current canon.');
+  return 0;
+};
+
+const { pathToFileURL } = await import('node:url');
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) process.exitCode = await runCli(process.argv.slice(2));

package/tools/velocity-profile.mjs

@@ -1,6 +1,6 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 // Velocity-profile core + writer: a fixed, audited read-only allowlist that an onboarding step seeds
 // into `.claude/settings.json` so routine read-only commands stop idling on approval prompts.
@@ -40,6 +40,13 @@ export const UNIVERSAL_READONLY_ALLOWLIST = Object.freeze([
   'Bash(git ls-files:*)',
   'Bash(git check-ignore:*)',
   'Bash(git branch --list:*)',
+  'Bash(git rev-parse:*)',
+  'Bash(git blame:*)',
+  'Bash(git shortlog:*)',
+  'Bash(git describe:*)',
+  'Bash(git tag --list:*)',
+  'Bash(git stash list:*)',
+  'Bash(git worktree list:*)',
   'Bash(npm view:*)',
   'Bash(npm ls:*)',
   'Bash(npm outdated:*)',
@@ -51,6 +58,12 @@ export const UNIVERSAL_READONLY_ALLOWLIST = Object.freeze([
   'Bash(readlink:*)',
   'Bash(which:*)',
   'Bash(grep:*)',
+  'Bash(diff:*)',
+  'Bash(stat:*)',
+  'Bash(du:*)',
+  'Bash(basename:*)',
+  'Bash(dirname:*)',
+  'Bash(realpath:*)',
 ]);
 
 // Per-tool POSITIVE allowlists, as frozen arrays. NOTE: `Object.freeze` on a Set does NOT prevent
@@ -64,6 +77,18 @@ export const GIT_READONLY_SUBCOMMANDS = Object.freeze([
   'ls-files',
   'check-ignore',
   'branch --list',
+  'rev-parse',
+  'blame',
+  'shortlog',
+  'describe',
+  // `git cat-file` is deliberately ABSENT (diff-council fold, AD-040): `--textconv`/`--filters`
+  // activate CONFIGURED external filters under an auto-approved command, and its read utility is
+  // marginal next to the kept `git show`.
+  // Fixed read-only forms ONLY — the bare `git tag` / `git stash` / `git worktree` forms mutate
+  // (probe-proven, AD-040), the same multi-token precedent as 'branch --list'.
+  'tag --list',
+  'stash list',
+  'worktree list',
 ]);
 export const NPM_READONLY_SUBCOMMANDS = Object.freeze(['view', 'ls', 'outdated']);
 export const SHELL_READONLY = Object.freeze([
@@ -75,7 +100,56 @@ export const SHELL_READONLY = Object.freeze([
   'readlink',
   'which',
   'grep',
+  // AD-040 audit survivors. `file` deliberately FAILED the audit (`-C -m <magic>` compiles a magic
+  // FILE WRITE — probe-proven) and stays a hand-add candidate only. `diff -l/--paginate` execs `pr`
+  // by a build-time FIXED absolute path (probed NOT PATH-resolved) — not arbitrary exec, kept.
+  'diff',
+  'stat',
+  'du',
+  'basename',
+  'dirname',
+  'realpath',
+]);
+
+// ── the opt-in --kit-tools tier (AD-040) ────────────────────────────────────────────────
+// A SEPARATE frozen tier, never an extension of UNIVERSAL_READONLY_ALLOWLIST: the core stays the
+// hook-parity surface (test/gate-hook-core-parity.test.mjs), while tier entries are derived at
+// seed time from the RUNNING tool's own location — resolved-absolute, so a moved or reinstalled
+// skill leaves a stale rule that FAIL-SAFE prompts again (never a silent widening).
+//
+// Membership (9, frozen): the read-only kit tools plus run-gates.mjs — which is NOT read-only but
+// project-exec (it runs the project's OWN declared gates.json commands), so it seeds as ONE exact
+// byte-string pinned to this project root (`--cwd <resolved root>`): a wildcard would be BROADER
+// than the AD-037 hook boundary (`--cwd <dir>` executes an arbitrary OTHER project's gates.json)
+// and a cwd-defaulting entry would follow the shell's current directory into subdirs. NEVER the
+// writers. review-state.mjs's read-only git spawns are in-scope read-only.
+export const KIT_RUN_GATES_TOOL = 'tools/run-gates.mjs';
+export const KIT_READONLY_TOOLS = Object.freeze([
+  'tools/recipes.mjs',
+  'tools/procedures.mjs',
+  'tools/family-registry.mjs',
+  'tools/detect-backends.mjs',
+  'tools/commands.mjs',
+  'tools/review-state.mjs',
+  KIT_RUN_GATES_TOOL,
+  'tools/manifest/validate.mjs',
+  'tools/release-scan.mjs',
+]);
+// Writer previews: ONLY writers whose ARG-FREE invocation is a documented dry-run ("Default is
+// --dry-run" in their usage) seed an EXACT preview byte-string — every --apply/--write/--yes keeps
+// its prompt. set-recipe is excluded (its preview takes variable --set ops); setup-backends and
+// hide-footprint are excluded (their arg-free forms APPLY); uninstall is excluded (a guarded
+// teardown documents --dry-run explicitly — its bare form is not its preview contract).
+export const KIT_WRITER_PREVIEW_TOOLS = Object.freeze([
+  'tools/velocity-profile.mjs',
+  'tools/cheap-agents.mjs',
+  'tools/gate-hook.mjs',
 ]);
+const KIT_WILDCARD_TOOLS = Object.freeze(KIT_READONLY_TOOLS.filter((rel) => rel !== KIT_RUN_GATES_TOOL));
+// The kit root this tool runs from (tools/..) — the tier's seed-time path anchor.
+const KIT_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const KIT_TOOL_INVOKER = 'node';
+const RUN_GATES_CWD_FLAG = '--cwd';
 
 // Characters that make a pattern NOT a single read-only command, so the screen rejects them.
 // Per current Claude Code permission semantics: the recognized command SEPARATORS are
@@ -125,6 +199,9 @@ export const VELOCITY_SYMLINK = 'VELOCITY_SYMLINK';
 const VELOCITY_ERROR_NAME = 'VelocityProfileError';
 const ERROR_PREFIX = '[agent-workflow-kit]';
 const BASH_ALLOW_PATTERN = /^Bash\((.+):\*\)$/u;
+// The EXACT (non-wildcard) allow form `Bash(cmd)` — tier-only (run-gates + writer previews); the
+// git/npm/shell core classes stay wildcard-only so the pre-existing advisory behavior never shifts.
+const BASH_EXACT_ALLOW_PATTERN = /^Bash\((.+)\)$/u;
 const BASH_PERMISSION_PATTERN = /^Bash\(.+\)$/u;
 const WHITESPACE_PATTERN = /\s+/u;
 const GIT_COMMAND = 'git';
@@ -143,6 +220,7 @@ const JSON_NEWLINE_PATTERN = /\n/gu;
 const FLAG_DRY_RUN = '--dry-run';
 const FLAG_APPLY = '--apply';
 const FLAG_ACCEPT_EDITS = '--accept-edits';
+const FLAG_KIT_TOOLS = '--kit-tools';
 const FLAG_CWD = '--cwd';
 const FLAG_HELP = '--help';
 const SHORT_FLAG_HELP = '-h';
@@ -155,12 +233,16 @@ const MUTATING_SCRIPT_HOOK_PATTERN = /^(pre|post)/iu;
 // refusal is named, tested, and produces a clear message).
 const MUTATING_ALLOW_COMMAND_PATTERN = /^(?:git\s+(?:commit|push)|npm\s+publish)(?:\s|$)/iu;
 const RESIDUAL_NOTICE =
-  'residual: seeded read-only allow entries are a trust-posture convenience, NOT a sandbox; settings-level rules cannot inspect runtime redirection/command-substitution/--output writes; commit/push/publish are never allowlisted (a DIRECT invocation still ASKs, but the runtime residual is not closed here); the residual guard ships as the opt-in PreToolUse hook — Mode: hook (/agent-workflow-kit hook).';
+  'residual: seeded read-only allow entries are a trust-posture convenience, NOT a sandbox; settings-level rules cannot inspect runtime redirection/command-substitution/--output writes; commit/push/publish are never allowlisted (a DIRECT invocation still ASKs, but the runtime residual is not closed here); the residual guard ships as the opt-in PreToolUse hook — Mode: hook (/agent-workflow-kit hook). floor (never auto-approved, with or without the tier): every writer --apply/--write/--yes still prompts; clobber-protection STOPs still stop; the three release asks (commit/push/publish) stay maintainer-owned.';
 
-const USAGE = `usage: velocity-profile [--dry-run | --apply] [--accept-edits] [--cwd <dir>] [--help]
+const USAGE = `usage: velocity-profile [--dry-run | --apply] [--kit-tools] [--accept-edits] [--cwd <dir>] [--help]
 
 Seeds the fixed read-only Claude Code allowlist into .claude/settings.json.
-Default is --dry-run. --apply writes; --accept-edits only sets defaultMode when applying.`;
+Default is --dry-run. --apply writes; --accept-edits only sets defaultMode when applying.
+--kit-tools additionally seeds the audited kit-tool tier: 8 read-only kit tools by resolved
+absolute path (args wildcard), run-gates.mjs as ONE exact project-root-pinned byte-string
+(project-exec - it runs YOUR declared gates.json), and the writers' exact arg-free dry-run
+preview byte-strings. Never touches settings.local.json.`;
 
 const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
 
@@ -245,6 +327,36 @@ const getBashAllowCommand = (pattern) => {
   return match ? match[1] : undefined;
 };
 
+// Parse the exact (non-wildcard) form ONLY when the wildcard form does not match — `Bash(cmd:*)`
+// would otherwise parse here as `cmd:*`.
+const getBashExactCommand = (pattern) => {
+  if (typeof pattern !== 'string' || BASH_ALLOW_PATTERN.test(pattern)) return undefined;
+  const match = pattern.match(BASH_EXACT_ALLOW_PATTERN);
+  return match ? match[1] : undefined;
+};
+
+// Characters that survive whitespace tokenization but break an UNQUOTED byte-exact path rule:
+// shell quoting syntax and glob brackets (SHELL_METACHARACTERS owns the command-level separators/
+// redirections/expansions — `*`/`?` globs included — but not these four).
+const PATH_BREAKING_CHARACTERS = Object.freeze(["'", '"', '[', ']']);
+
+// A path token that can be seeded UNQUOTED into a byte-exact allow rule: POSIX-absolute, no
+// whitespace, no shell metacharacter, no quoting/glob syntax.
+const isSeedablePathToken = (token) =>
+  typeof token === 'string' &&
+  token.startsWith('/') &&
+  !/\s/u.test(token) &&
+  !hasShellMetacharacter(token) &&
+  !PATH_BREAKING_CHARACTERS.some((ch) => token.includes(ch));
+
+// A tier path token must be SEEDABLE (a relative or shell-syntax-carrying spelling is a dead rule
+// the screen refuses to bless) and end on a known tier-tool tail. Any seedable absolute prefix is
+// accepted — the user's own kit copy elsewhere is legitimate shape-wise; entries OUTSIDE the
+// derived tier are still flagged by the pre-existing advisory, and membership in the SEEDED set
+// stays enforced separately by validateProfile's audited-set check.
+const isKitToolPathToken = (token, relPaths) =>
+  isSeedablePathToken(token) && relPaths.some((rel) => token.endsWith(`/${rel}`));
+
 const isSingleShellToken = (cmd, tokens) => tokens.length === 1 && cmd === tokens[0];
 
 const isScriptMap = (scripts) => Boolean(scripts) && typeof scripts === 'object' && !Array.isArray(scripts);
@@ -309,11 +421,23 @@ const assertClaudeDirSafe = (cwd, deps = {}) => {
   return { claudeDirAbsent: false };
 };
 
-const collectPreExistingNonReadonly = (sources) =>
+// A kit-tool-SHAPED entry (any `node …` allow entry, wildcard or exact) passes the shape screen on
+// any absolute path — but only the entries the tier itself derives for THIS kit + THIS root are
+// audited. Everything else `node`-shaped is arbitrary local JS / foreign project-exec and must
+// stay flagged for hand review (diff-council fold, AD-040).
+const isKitToolShapedCommand = (entry) => {
+  const cmd = getBashAllowCommand(entry) ?? getBashExactCommand(entry);
+  return cmd !== undefined && tokenizeCommand(cmd)[0] === KIT_TOOL_INVOKER;
+};
+
+const collectPreExistingNonReadonly = (sources, derivedTier = []) =>
   sources.flatMap(({ source, data }) =>
     getAllowEntries(data)
       .filter((entry) => typeof entry === 'string' && BASH_PERMISSION_PATTERN.test(entry))
-      .filter((entry) => !screenAllowlistEntry(entry))
+      .filter(
+        (entry) =>
+          !screenAllowlistEntry(entry) || (isKitToolShapedCommand(entry) && !derivedTier.includes(entry)),
+      )
       .map((entry) => ({ source, entry })),
   );
 
@@ -351,6 +475,21 @@ const formatAllowlist = (result) => [
   `already present: ${result.alreadyPresent.length}`,
 ];
 
+// The tier's honest posture, printed on every --kit-tools run: run-gates is project-exec (never
+// "read-only"), previews stay dry-run-only, and the tier gets none of the hook's residual ask-net.
+const KIT_TIER_NOTICE =
+  'kit-tools tier: paths are resolved absolute at seed time (fail-safe - a moved skill or stale path simply prompts again); run-gates.mjs is seeded as ONE exact byte-string pinned to this project root and is project-exec - it runs YOUR declared gates.json commands, never "read-only"; writer previews are exact dry-run byte-strings - every --apply/--write/--yes still prompts; tier entries get NO PreToolUse-hook residual coverage (settings-level posture only - see the velocity mode notes).';
+
+const formatKitTier = (result) =>
+  result.kitTools
+    ? [
+        `${result.wrote ? 'added' : 'would add'} kit-tools tier entries: ${result.tierToAdd.length}`,
+        ...formatEntryList(result.tierToAdd),
+        `already present (tier): ${result.tierAlreadyPresent.length}`,
+        KIT_TIER_NOTICE,
+      ]
+    : [];
+
 const formatGateAdvisory = (gateCandidates) => [
   'gate advisory: candidates you may add BY HAND to .claude/settings.json or settings.local.json; this tool will NOT add them',
   ...(gateCandidates.length
@@ -375,6 +514,7 @@ const formatVelocityProfileResult = (result) =>
   [
     result.dryRun ? 'agent-workflow velocity profile - DRY RUN (no changes)' : 'agent-workflow velocity profile - APPLY',
     ...formatAllowlist(result),
+    ...formatKitTier(result),
     formatDefaultMode(result),
     ...formatGateAdvisory(result.gateCandidates),
     ...formatPreExistingAdvisory(result.preExistingNonReadonly),
@@ -386,16 +526,69 @@ const formatVelocityProfileResult = (result) =>
 const exitCodeFor = (err) => err?.exitCode ?? EXIT_PRECONDITION;
 
 // `:*` is the trailing word-boundary wildcard: equivalent to a trailing ` *`, recognized only at the
-// end of a pattern per Claude Code semantics.
+// end of a pattern per Claude Code semantics. Two forms are recognized: the wildcard form (the
+// git/npm/shell core + the kit-tool wildcard class) and the EXACT form (tier-only: the root-pinned
+// run-gates byte-string + the writer-preview dry-run byte-strings).
 export const screenAllowlistEntry = (pattern) => {
-  const cmd = getBashAllowCommand(pattern);
-  if (!cmd) return false;
-  if (hasShellMetacharacter(cmd)) return false;
-
-  const tokens = tokenizeCommand(cmd);
-  if (tokens[0] === GIT_COMMAND) return GIT_READONLY_SUBCOMMANDS.includes(getSubcommand(tokens));
-  if (tokens[0] === NPM_COMMAND) return NPM_READONLY_SUBCOMMANDS.includes(getSubcommand(tokens));
-  return isSingleShellToken(cmd, tokens) && SHELL_READONLY.includes(cmd);
+  const wildcardCmd = getBashAllowCommand(pattern);
+  if (wildcardCmd !== undefined) {
+    if (hasShellMetacharacter(wildcardCmd)) return false;
+    const tokens = tokenizeCommand(wildcardCmd);
+    if (tokens[0] === GIT_COMMAND) return GIT_READONLY_SUBCOMMANDS.includes(getSubcommand(tokens));
+    if (tokens[0] === NPM_COMMAND) return NPM_READONLY_SUBCOMMANDS.includes(getSubcommand(tokens));
+    // Kit-tool wildcard class: `node <abs kit tool>` + args wildcard. run-gates is deliberately NOT
+    // here (Decision 3: only its exact root-pinned form below — a wildcard would cover `--cwd <any>`).
+    if (tokens[0] === KIT_TOOL_INVOKER) return tokens.length === 2 && isKitToolPathToken(tokens[1], KIT_WILDCARD_TOOLS);
+    return isSingleShellToken(wildcardCmd, tokens) && SHELL_READONLY.includes(wildcardCmd);
+  }
+  const exactCmd = getBashExactCommand(pattern);
+  if (exactCmd === undefined || hasShellMetacharacter(exactCmd)) return false;
+  const tokens = tokenizeCommand(exactCmd);
+  if (tokens[0] !== KIT_TOOL_INVOKER) return false;
+  // Writer preview: the arg-free dry-run byte-string of a preview-class writer.
+  if (tokens.length === 2) return isKitToolPathToken(tokens[1], KIT_WRITER_PREVIEW_TOOLS);
+  // run-gates: EXACTLY `node <abs run-gates> --cwd <abs root>` — any other form keeps prompting.
+  return (
+    tokens.length === 4 &&
+    isKitToolPathToken(tokens[1], [KIT_RUN_GATES_TOOL]) &&
+    tokens[2] === RUN_GATES_CWD_FLAG &&
+    isSeedablePathToken(tokens[3])
+  );
+};
+
+/**
+ * Derive the opt-in kit-tools tier for a project: 8 wildcard entries (resolved-absolute script
+ * path + args wildcard), ONE exact run-gates entry pinned to the resolved project root, and the
+ * writer-preview exact dry-run byte-strings. Pure derivation — a stale path simply prompts again.
+ */
+// A seedable path must survive UNQUOTED inside a byte-exact allow rule: POSIX-absolute, no
+// whitespace, no shell metacharacter, no quoting/glob syntax (isSeedablePathToken). Anything else
+// is refused UP FRONT with a clear error (a Windows-shaped, space- or quote-carrying path would
+// otherwise die downstream as a confusing VELOCITY_NON_READONLY, or seed dead/shell-reinterpreted
+// byte strings) — the hand-add advisory is the fallback.
+const assertSeedablePath = (label, absPath) => {
+  if (isSeedablePathToken(absPath)) return;
+  throw makeVelocityProfileError(
+    VELOCITY_INVALID_ARGUMENT,
+    `kit-tools tier: the ${label} "${absPath}" is not a POSIX absolute path free of spaces/metacharacters/quoting - byte-exact allow rules cannot be seeded for it; add hand-picked entries to your settings instead (hand-add)`,
+    { entry: absPath },
+  );
+};
+
+export const deriveKitToolsAllowlist = ({ projectDir } = {}) => {
+  if (typeof projectDir !== 'string' || projectDir === '') {
+    throw makeVelocityProfileError(VELOCITY_INVALID_ARGUMENT, 'kit-tools derivation needs a project directory', {
+      entry: projectDir,
+    });
+  }
+  const projectRoot = resolve(projectDir);
+  assertSeedablePath('resolved project root', projectRoot);
+  assertSeedablePath('resolved skill dir', join(KIT_ROOT, '.'));
+  return Object.freeze([
+    ...KIT_WILDCARD_TOOLS.map((rel) => `Bash(${KIT_TOOL_INVOKER} ${join(KIT_ROOT, rel)}:*)`),
+    `Bash(${KIT_TOOL_INVOKER} ${join(KIT_ROOT, KIT_RUN_GATES_TOOL)} ${RUN_GATES_CWD_FLAG} ${projectRoot})`,
+    ...KIT_WRITER_PREVIEW_TOOLS.map((rel) => `Bash(${KIT_TOOL_INVOKER} ${join(KIT_ROOT, rel)})`),
+  ]);
 };
 
 export const discoverGateCandidates = (packageJson) => {
@@ -405,12 +598,14 @@ export const discoverGateCandidates = (packageJson) => {
 };
 
 /**
- * Validate that what we are about to write is a subset of the audited read-only core: every entry
+ * Validate that what we are about to write is a subset of the SELECTED audited set: every entry
  * must (a) NOT be a commit/push/publish allow entry, (b) pass the read-only screen, and (c) be a
- * member of UNIVERSAL_READONLY_ALLOWLIST (a guard against the constant drifting). Pure; owns no exit
- * codes — a CLI maps the typed `.code` to a process exit.
+ * member of the audited set (a guard against the constants drifting). The argument-less call keeps
+ * its exact historical semantics — the full core validated against itself; a --kit-tools run
+ * additionally validates the derived tier against core + tier. Pure; owns no exit codes — a CLI
+ * maps the typed `.code` to a process exit.
  */
-export const validateProfile = (allowEntries = UNIVERSAL_READONLY_ALLOWLIST) => {
+export const validateProfile = (allowEntries = UNIVERSAL_READONLY_ALLOWLIST, auditedSet = UNIVERSAL_READONLY_ALLOWLIST) => {
   if (!Array.isArray(allowEntries)) {
     throw makeVelocityProfileError(VELOCITY_INVALID_ARGUMENT, 'allow entries must be an array', { entry: allowEntries });
   }
@@ -422,7 +617,7 @@ export const validateProfile = (allowEntries = UNIVERSAL_READONLY_ALLOWLIST) =>
     if (!screenAllowlistEntry(entry)) {
       throw makeVelocityProfileError(VELOCITY_NON_READONLY, `not a read-only allow entry: ${entry}`, { entry });
     }
-    if (!UNIVERSAL_READONLY_ALLOWLIST.includes(entry)) {
+    if (!auditedSet.includes(entry)) {
       throw makeVelocityProfileError(VELOCITY_OFFCORE, `allow entry is outside the audited core: ${entry}`, { entry });
     }
   }
@@ -480,10 +675,25 @@ export const preflightVelocityProfile = ({ cwd }, deps = {}) => {
     );
   }
 
-  const preExistingNonReadonly = collectPreExistingNonReadonly([
-    { source: SETTINGS_FILE, data: projectSettings.data },
-    { source: SETTINGS_LOCAL_FILE, data: localSettings.data },
-  ]);
+  // The advisory compares kit-tool-shaped entries against the tier derived for THIS kit + root.
+  // Defensive derive: on a machine whose paths cannot seed (space/metacharacter — the tier itself
+  // refuses loudly on --kit-tools), the flagless advisory falls back to flagging EVERY node-shaped
+  // entry — over-flagging is the safe direction, and flagless behavior never gains a new failure
+  // mode from local skill paths.
+  const derivedTier = (() => {
+    try {
+      return deriveKitToolsAllowlist({ projectDir });
+    } catch {
+      return [];
+    }
+  })();
+  const preExistingNonReadonly = collectPreExistingNonReadonly(
+    [
+      { source: SETTINGS_FILE, data: projectSettings.data },
+      { source: SETTINGS_LOCAL_FILE, data: localSettings.data },
+    ],
+    derivedTier,
+  );
   const gateCandidates = discoverGateCandidates(readPackageJson(projectDir, deps));
 
   return {
@@ -500,21 +710,30 @@ export const preflightVelocityProfile = ({ cwd }, deps = {}) => {
   };
 };
 
-export const planVelocityProfile = (preflight, { acceptEdits } = {}) => {
+export const planVelocityProfile = (preflight, { acceptEdits, kitTools } = {}) => {
   const projectAllow = getAllowEntries(preflight.projectSettings?.data);
   const toAdd = UNIVERSAL_READONLY_ALLOWLIST.filter((entry) => !projectAllow.includes(entry));
   const alreadyPresent = UNIVERSAL_READONLY_ALLOWLIST.filter((entry) => projectAllow.includes(entry));
-  return { toAdd, alreadyPresent, setsDefaultMode: acceptEdits === true };
+  const tier = kitTools === true ? deriveKitToolsAllowlist({ projectDir: preflight.cwd }) : [];
+  const tierToAdd = tier.filter((entry) => !projectAllow.includes(entry));
+  const tierAlreadyPresent = tier.filter((entry) => projectAllow.includes(entry));
+  return { toAdd, alreadyPresent, tierToAdd, tierAlreadyPresent, kitTools: kitTools === true, setsDefaultMode: acceptEdits === true };
 };
 
-export const writeVelocityProfile = ({ cwd, acceptEdits = false, dryRun = true } = {}, deps = {}) => {
+export const writeVelocityProfile = ({ cwd, acceptEdits = false, dryRun = true, kitTools = false } = {}, deps = {}) => {
   const projectDir = cwd ?? deps.cwd ?? process.cwd();
   const preflight = preflightVelocityProfile({ cwd: projectDir }, deps);
-  const plan = planVelocityProfile(preflight, { acceptEdits });
+  const plan = planVelocityProfile(preflight, { acceptEdits, kitTools });
   // Drift guard runs on BOTH dry-run and apply (so a dry-run faithfully predicts the apply) and
   // validates the FULL audited core, not just the to-add delta — a drifted core entry is caught even
   // when it is already present in the user's allow list (and toAdd is a subset of the core anyway).
   validateProfile();
+  // A --kit-tools run additionally validates the SELECTED tier against core + tier — flagless
+  // behavior never depends on local skill paths (the derivation does not even run without the flag).
+  if (kitTools === true) {
+    const tier = deriveKitToolsAllowlist({ projectDir });
+    validateProfile(tier, [...UNIVERSAL_READONLY_ALLOWLIST, ...tier]);
+  }
   const resultBase = { ...preflight, ...plan };
   if (dryRun) return { wrote: false, dryRun: true, ...resultBase };
 
@@ -528,7 +747,7 @@ export const writeVelocityProfile = ({ cwd, acceptEdits = false, dryRun = true }
   const fs = fsDeps(deps);
   const settingsPath = join(projectDir, SETTINGS_FILE);
   if (preflight.claudeDirAbsent) fs.mkdir(join(projectDir, CLAUDE_DIR), { recursive: true });
-  const merged = mergeProjectSettings(preflight.projectSettings.data, plan.toAdd, acceptEdits);
+  const merged = mergeProjectSettings(preflight.projectSettings.data, [...plan.toAdd, ...plan.tierToAdd], acceptEdits);
   fs.writeFile(settingsPath, formatJson(merged, preflight.projectSettings.eol ?? LF), UTF8);
   return { wrote: true, dryRun: false, settingsPath, ...resultBase };
 };
@@ -541,6 +760,7 @@ export const parseArgs = (argv) => {
       if (arg === FLAG_DRY_RUN) return { ...state, dryRunFlag: true };
       if (arg === FLAG_APPLY) return { ...state, apply: true };
       if (arg === FLAG_ACCEPT_EDITS) return { ...state, acceptEdits: true };
+      if (arg === FLAG_KIT_TOOLS) return { ...state, kitTools: true };
       if (arg === FLAG_CWD) {
         const next = allArgs[index + 1];
         if (next === undefined || next.startsWith('-')) throw fail(EXIT_USAGE, `${FLAG_CWD} needs a directory argument`);
@@ -549,7 +769,7 @@ export const parseArgs = (argv) => {
       if (arg.startsWith('-')) throw fail(EXIT_USAGE, `unknown flag: ${arg}`);
       throw fail(EXIT_USAGE, `unexpected argument: ${arg}`);
     },
-    { help: false, dryRunFlag: false, apply: false, acceptEdits: false, cwd: undefined, skipNext: false },
+    { help: false, dryRunFlag: false, apply: false, acceptEdits: false, kitTools: false, cwd: undefined, skipNext: false },
   );
 
   if (parsed.dryRunFlag && parsed.apply) throw fail(EXIT_USAGE, `${FLAG_DRY_RUN} and ${FLAG_APPLY} cannot be used together`);
@@ -558,6 +778,7 @@ export const parseArgs = (argv) => {
     dryRun: parsed.apply ? false : true,
     apply: parsed.apply,
     acceptEdits: parsed.acceptEdits,
+    kitTools: parsed.kitTools,
     cwd: parsed.cwd,
   };
 };
@@ -572,7 +793,7 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       return EXIT_OK;
     }
     const result = writeVelocityProfile(
-      { cwd: args.cwd ?? deps.cwd ?? process.cwd(), acceptEdits: args.acceptEdits, dryRun: args.dryRun },
+      { cwd: args.cwd ?? deps.cwd ?? process.cwd(), acceptEdits: args.acceptEdits, dryRun: args.dryRun, kitTools: args.kitTools },
       deps,
     );
     log(formatVelocityProfileResult(result));