@sabaiway/agent-workflow-kit 1.42.0 → 1.43.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ 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.43.0 — Closed-world gate seeding: lifecycle hooks die by construction (AD-052)
+
+A **feature** release (kit-only; memory/engine/bridges unchanged, lineage head stays `2.0.0`). The
+consent-gated `gates.json` seeder (`seed-gates.mjs`) moves from BLOCKLIST screening to a
+**closed-world** offer derivation — the structural fix for **Issue-011**, whose three residuals the
+AD-042 council could only ever push one gap further, never close. Since a declared gate is
+hook-auto-approvable, the offer is now conservative BY CONSTRUCTION: the worst case is a legit
+command not offered (add it by hand), never a dangerous one offered.
+
+- **Uniform hook-free exec form.** The seeded cmd is
+  `COREPACK_ENABLE_NETWORK=0 <pm> exec -- <allowlisted-body>` for the detected package manager.
+  `exec` runs a command, not a named script, so no `pre<name>`/`post<name>` lifecycle hook can fire
+  — structurally and uniformly across **npm, pnpm, and yarn** (classic + berry). Never `<pm> run
+  <name>`, which would re-expose hooks and let a later `package.json` edit change what a byte-exact
+  approved gate runs.
+- **Body allowlist, not blocklist.** The script body must be a string member of a 9-entry literal
+  runner allowlist (`node --test`, `vitest run`, `jest`, `jest --ci`, `eslint .`,
+  `prettier --check .`, `tsc --noEmit`, `tsc -p . --noEmit`, `vite build`) after a pinned
+  ASCII-only normalization; anything else — an injected `curl … | sh`, a `release:npm` alias, an
+  env/path body — is not offered, by non-membership. Editing the allowlist ADDS a test-guarded
+  entry; it can never weaken a filter.
+- **Per-PM fail-closed floor.** npm is pinned `--offline --script-shell /bin/sh` (no registry fetch
+  of a missing runner; a hostile `.npmrc script-shell` loses); the `COREPACK_ENABLE_NETWORK=0`
+  prefix blocks a Corepack-shimmed PM from fetching a hostile `packageManager` pin before exec;
+  pnpm/yarn fail closed natively; a package manager whose exec contract cannot be verified is
+  WITHHELD with a loud note. Screened-out gate-class scripts are counted and named — never silently
+  absent (preview and apply alike).
+- **Preflight parent-chain guard.** `assertDocsAiDeployment` (`atomic-write.mjs`) now walks the
+  `docs` parent chain (refusing a symlinked `docs` parent or cwd root) before any read, closing the
+  seeder's preview-path escape; all four write consumers inherit it. ENOENT-safe — a brand-new
+  project still gets the normal no-deployment stop.
+- **Scoped safety claim.** Safe-by-construction is the OFFER DERIVATION, not a runtime sandbox: a
+  script gate runs the project's own tooling (project-controlled code), the disclosed residual
+  bounded by the two-consent trust chain. The preview discloses it.
+
 ## 1.42.0 — Opt-in ADR-store migration mode + old-layout detection (AD-051)
 
 A **feature** release, co-released with **memory 2.0.0 (MAJOR)** — the one-file-per-ADR store that

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.42.0'
+  version: '1.43.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

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

package/references/modes/gates.md

@@ -16,6 +16,6 @@ Declared gates can also be **auto-approved** (no permission prompt on a byte-exa
 
 **Candidate line — the review-receipt gate (opt-in, never auto-seeded; AD-021).** Projects that configure a reviewed/council `plan-execution.review` recipe can declare the AD-038 review-state check as one more gate — the exact candidate `{ id, title, cmd }` line and its contract live under `${CLAUDE_SKILL_DIR}/references/modes/review-state.md` (step 3). The template `gates.json` stays EMPTY; adding the line is the maintainer's explicit consent — by hand, or through the consent-gated seeder below (AD-042).
 
-**Consent-gated seeding — a separate WRITER CLI, not part of the runner (AD-042).** Bootstrap recon already records the project's own daily commands; the seeder turns them into a preview of `{ id, title, cmd }` entries. Protocol: run `node ${CLAUDE_SKILL_DIR}/tools/seed-gates.mjs --cwd <project>` (dry-run by default — prints the derived entries and **writes NOTHING**; declining leaves the file byte-identical), show the user the EXACT entries (`AskUserQuestion` preview where supported, prose otherwise), and only on an explicit yes run it again with `--apply [--only <id>]…` — it **appends exactly the consented entries** (append-only: existing entries are never modified or removed; an id collision is refused loudly; a malformed declaration is never written over). Only terminating verification commands are offered (test / lint / type-check / build — never dev/watch/serve, never a formatter write-mode, never a release/publish/deploy script), commands are package-manager-aware, and the review-state candidate above is included automatically when the project's orchestration config declares reviewed/council on `plan-execution.review`. **Disclose before the yes** (the preview prints it): once the approval hook is wired, it auto-approves byte-exact declared gate commands — seeding and hook wiring are two separate consents.
+**Consent-gated seeding — a separate WRITER CLI, not part of the runner (AD-042).** Bootstrap recon already records the project's own daily commands; the seeder turns them into a preview of `{ id, title, cmd }` entries. Protocol: run `node ${CLAUDE_SKILL_DIR}/tools/seed-gates.mjs --cwd <project>` (dry-run by default — prints the derived entries and **writes NOTHING**; declining leaves the file byte-identical), show the user the EXACT entries (`AskUserQuestion` preview where supported, prose otherwise), and only on an explicit yes run it again with `--apply [--only <id>]…` — it **appends exactly the consented entries** (append-only: existing entries are never modified or removed; an id collision is refused loudly; a malformed declaration is never written over). The offer is **closed-world** (AD-052): only a terminating-class script NAME (test / lint / type-check / build — never dev/watch/serve, never a write-mode or release/publish/deploy variant) whose BODY is a member of the seeder's literal runner allowlist is offered — membership, never blocklist screening: the worst case is a legit command not offered, never a dangerous one offered. The seeded cmd is the uniform hook-free **`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <allowlisted-body>`** — `exec` runs a command, not a named script, so no pre/post hook can fire (npm/pnpm/yarn alike; never `<pm> run <name>`, which re-exposes hooks), and the Corepack env prefix blocks a hostile `packageManager` pin from fetching the PM binary before exec. npm is pinned `--offline --script-shell /bin/sh` (no fetch of a missing runner; a hostile `.npmrc script-shell` loses); pnpm/yarn refuse an absent runner without network (a user-installed cache/global/PATH runner executing is user machine state — part of the disclosed residual); a family without a verified fail-closed exec contract is WITHHELD loudly. A gate-class script screened out on its BODY is counted and named in a note (add it by hand if you trust it); the review-state candidate above joins automatically on a reviewed/council `plan-execution.review`. **Disclose before the yes** (the preview prints it): the wired hook auto-approves byte-exact declared commands — two separate consents — and a script gate runs project-controlled tooling the seeder does not sandbox (safe-by-construction = the OFFER DERIVATION).
 
 **Invariants:** the runner writes nothing by default (`--record` delegates its ONE ledger write to the review-ledger sole writer, `recordGateRun` — the runner itself never opens the ledger) · never commits · never runs a subscription CLI · executes only the project's OWN declared commands (never a kit-invented one) · the bash contract fails loud, never reinterprets · the seeder is a separate consent-per-run CLI — preview-first, append-only, never pre-approved by any velocity tier.

package/tools/atomic-write.mjs

@@ -53,6 +53,19 @@ export const assertDocsAiDeployment = (cwd, deps = {}, opts = {}) => {
   const noun = opts.noun ?? 'a file';
   const rel = opts.rel ?? 'under docs/ai';
   const docsAi = join(cwd, 'docs', 'ai');
+  // Parent-chain preflight (AD-052, Issue-011 residual 3): refuse a symlinked cwd ROOT or a
+  // symlinked `docs` PARENT before any read — the walk the write path already enforces
+  // (writeContainedFileAtomic), aligned onto the gate every consumer runs first. The walk covers
+  // the PARENT chain only (the linkManaged precedent, fs-safe.mjs): the docs/ai LEAF keeps the
+  // dedicated checks below, whose exact STOP messages each consumer's tests pin. ENOENT-safe —
+  // an absent component is a no-op walk, so a brand-new project still reaches the normal
+  // "no deployment" STOP below. The walk throws a plain Error; re-throw as the CALLER's typed
+  // stop so every consumer's `.code` contract holds.
+  try {
+    assertContainedRealPath(cwd, join(cwd, 'docs'), { lstat });
+  } catch (err) {
+    throw stop(String(err?.message ?? err).replace(/^\[agent-workflow-kit\] /, ''));
+  }
   const docsAiStat = lstatNoFollow(docsAi, lstat);
   if (docsAiStat === null) {
     throw stop(`no agent-workflow deployment here (docs/ai is absent) — run init/bootstrap before writing ${rel}`);

package/tools/seed-gates.mjs

@@ -6,14 +6,28 @@
 // EMPTY (AD-021/AD-038): a populated declaration is per-entry maintainer consent recorded through
 // this preview, never auto-seeding.
 //
-// What it offers (the derivation invariants, test-pinned):
+// What it offers (the derivation invariants, test-pinned) — CLOSED-WORLD since AD-052: an entry
+// is offered only when every axis is proven safe by MEMBERSHIP in a finite, test-guarded set,
+// never by absence from a blocklist (Issue-011 killed the blocklist model — one more gap per
+// review round, unprovable):
 //   • sources: discoverGateCandidates over package.json scripts (velocity-profile.mjs stays
 //     read-only; THIS module owns the offer mapping) + the conditional review-state candidate;
-//   • warn-flagged candidates (release/publish/deploy/push/version/commit/tag, pre*/post*) NEVER
-//     enter the offer — excluded, not offered-with-a-warning;
-//   • only TERMINATING verification classes are offered (test / lint / type-check / build) —
-//     never dev/start/watch/serve/preview, never a formatter write-mode;
-//   • commands are package-manager-aware (packageManager field, else lockfile probe, else npm);
+//   • NAME screens shape WHICH entries are offered: warn-flagged candidates (release/publish/
+//     deploy/push/version/commit/tag, pre*/post*) never enter; only terminating verification
+//     class NAMES (test / lint / type-check / build) pass, never dev/start/watch/serve/preview,
+//     never a mutating-variant name; a shell-unsafe name is screened first;
+//   • the BODY must be a string member of the literal BODY_ALLOWLIST after a pinned ASCII-only
+//     normalization — anything else is screened out with a LOUD note (never silently absent);
+//   • the cmd is the per-PM HOOK-FREE form `COREPACK_ENABLE_NETWORK=0 <pm> exec -- <allowlisted-body>`
+//     (packageManager field, else lockfile probe, else npm): `exec` runs a command, not a named
+//     script, so the pre/post lifecycle-hook class dies structurally on npm/pnpm/yarn alike, and
+//     the Corepack env prefix blocks a hostile packageManager pin from fetching the PM binary; a
+//     family with no verified fail-closed exec contract is WITHHELD with a loud note. NEVER
+//     `<pm> run <name>` — that re-exposes hooks and lets a later package.json edit change a
+//     byte-exact-approved gate;
+//   • the safety claim is scoped to the OFFER DERIVATION, not a runtime sandbox: a gate still
+//     executes project-controlled tooling (a node_modules/.bin PATH shim intercepts under every
+//     form) — the documented residual, disclosed in the preview, bounded by the two consents;
 //   • ids derive kebab-case from script names (build:prod → build-prod) and every offered entry
 //     passes the runner's validateDeclaration (the seeder imports the validator — NEVER the
 //     reverse: run-gates.mjs stays a runner that writes nothing);
@@ -62,33 +76,35 @@ const usageFail = (message) =>
 export const TRUST_CHAIN_DISCLOSURE =
   'Disclosure: once the optional approval hook is wired (/agent-workflow-kit hook), it ' +
   'auto-approves byte-exact declared gate commands from the project root — seeding (this consent) ' +
-  'and hook wiring (its own consent) are two separate yeses.';
+  'and hook wiring (its own consent) are two separate yeses. A script gate runs the project\'s ' +
+  'own tooling, which executes project-controlled code (the seeder does not sandbox it; the two ' +
+  'consents bound it).';
 
 const USAGE = `usage: seed-gates [--dry-run | --apply] [--only <id>]... [--cwd <dir>] [--help]
 
 Consent-gated seeder for the project's own docs/ai/gates.json. Default is --dry-run: prints the
 derived { id, title, cmd } entries and writes NOTHING. --apply APPENDS exactly the consented
 entries (--only <id> selects a subset; append-only — existing entries are never modified or
-removed, an id collision is refused). Only terminating verification commands are offered
-(test / lint / type-check / build); release/publish/deploy scripts and watch/serve modes never
-enter the offer. ${TRUST_CHAIN_DISCLOSURE}`;
+removed, an id collision is refused). The offer is CLOSED-WORLD: only a terminating-class script
+name (test / lint / type-check / build — never release/publish/deploy, never watch/serve, never a
+write-mode variant) whose BODY is a member of the literal runner allowlist is offered, as the
+hook-free \`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <body>\` form for the detected package manager. A gate-class script whose
+body is NOT in the allowlist is screened out with a note naming it (a command you trust can still
+be declared by hand); non-gate-class names are excluded silently, as always.
+${TRUST_CHAIN_DISCLOSURE}`;
 
-// ── candidate classification (the LOCKED derivation invariants) ────────────────────────
-// The derived cmd (`<pm> run <name>`) is bash-interpolated by the gate runner and can become
+// ── candidate classification: the NAME screens (the LOCKED derivation invariants) ──────
+// NAME screens shape WHICH safe entries are offered; the danger axis (the BODY) is closed-world
+// below (AD-052). The derived cmd is bash-interpolated by the gate runner and can become
 // hook-auto-approvable, so only shell-SAFE script names ever enter the offer: a name carrying
 // whitespace or any shell metacharacter (`test:ci && echo pwn`) is screened out entirely.
 const SAFE_SCRIPT_NAME_PATTERN = /^[A-Za-z0-9:_.-]+$/;
 const TERMINATING_CLASS_PATTERN = /^(test|lint|type-?check|types|tsc|build)([:._-]|$)/i;
-// Non-terminating screening is TOKEN-set based, position-independent (never an anchored regex —
-// the anchored form missed `build:preview` and a bare `vite preview` body): a non-terminating
-// token in ANY name segment, or as ANY bare/dashed body word, disqualifies; `watch` disqualifies
-// as a substring anywhere (watchAll, --watchAll). Conservative on purpose — a screened-out script
-// can still be declared by hand; a wrongly-included one would become hook-auto-approvable.
+// Non-terminating NAME screening is TOKEN-set based, position-independent (never an anchored
+// regex — the anchored form missed `build:preview`): a non-terminating token in ANY name segment
+// disqualifies; `watch` disqualifies as a substring anywhere (watchAll). Conservative on purpose —
+// a screened-out script can still be declared by hand.
 const NON_TERMINATING_TOKENS = new Set(['dev', 'start', 'serve', 'watch', 'preview']);
-// A terminating-looking NAME can still hide release work in its BODY (`"test": "npm publish"`):
-// the same token classes the warn-name screen rejects are rejected as bare body words too — an
-// offered cmd is hook-auto-approvable, so a dangerous body must never ride a clean name.
-const DANGEROUS_BODY_TOKENS = new Set(['release', 'publish', 'deploy', 'push', 'version', 'commit', 'tag']);
 const WATCH_ANYWHERE_PATTERN = /watch/i;
 const wordOf = (raw) => raw.toLowerCase().replace(/^-+/, '').split('=')[0];
 const hasTokenIn = (text, splitter, tokens) =>
@@ -97,16 +113,82 @@ const hasTokenIn = (text, splitter, tokens) =>
     .some((part) => tokens.has(wordOf(part)));
 const isNonTerminatingName = (name) =>
   hasTokenIn(name, /[:._-]/, NON_TERMINATING_TOKENS) || WATCH_ANYWHERE_PATTERN.test(name);
-const isNonTerminatingBody = (body) =>
-  hasTokenIn(body, /\s+/, NON_TERMINATING_TOKENS) || WATCH_ANYWHERE_PATTERN.test(body);
-const isDangerousBody = (body) => hasTokenIn(body, /\s+/, DANGEROUS_BODY_TOKENS);
-// A MUTATING VARIANT of a terminating class never enters the offer — a hook-auto-approvable gate
-// must never be a writer. Screened on BOTH axes: the script NAME (lint:fix, test:update,
-// build:write, test:snapshot) and the script BODY's write-mode flags (eslint --fix,
-// prettier --write / -w, jest -u / --updateSnapshot, tsc -w). Conservative by design: an excluded
-// candidate can still be declared by hand — a wrongly-included one would be silently auto-approved.
+// A MUTATING VARIANT NAME of a terminating class never enters the offer (lint:fix, test:update,
+// build:write, test:snapshot) — a hook-auto-approvable gate must never be a writer. Write-mode
+// BODIES need no screen: the closed-world allowlist simply has no write-mode member.
 const MUTATING_VARIANT_NAME_PATTERN = /(^|[:._-])(fix|write|update|snapshot)([:._-]|$)/i;
-const MUTATING_BODY_FLAG_PATTERN = /(^|\s)(--fix|--write|--update(?:-snapshot)?|--updateSnapshot|-w|-u)(=|\s|$)/;
+
+// ── the CLOSED-WORLD body contract (AD-052 — the Issue-011 structural fix) ─────────────
+// The body axis is ALLOWLIST MEMBERSHIP, never blocklist screening. The failure direction flips
+// by construction: worst case = a legit command not offered (mild, add-by-hand) — never a
+// dangerous one offered. Extension contract (edit-safety): adding an entry = adding the literal
+// here + classifying its stem in the partition below + its own test case; the self-safety test
+// pins every entry against shell metacharacters, write-mode flags, and unrecognized runner stems.
+// Deliberately EXCLUDED: `tsc -p .` without --noEmit — it EMITS compiled .js into the tree by
+// default, a write side-effect a verification gate must not have.
+export const BODY_ALLOWLIST = Object.freeze([
+  'node --test',
+  'vitest run',
+  'jest',
+  'jest --ci',
+  'eslint .',
+  'prettier --check .',
+  'tsc --noEmit',
+  'tsc -p . --noEmit',
+  'vite build',
+]);
+// The FIXED executable-source partition of the allowlist stems (test-pinned, never a runtime
+// probe): a host-runtime stem (`node`) is always on PATH and never a node_modules package — no
+// local-bin resolution applies to it; a package-runner stem resolves from the project's own
+// node_modules (or Berry .pnp.cjs) via `<pm> exec`, under the per-PM no-network-fetch rule below.
+export const HOST_RUNTIME_STEMS = Object.freeze(['node']);
+export const PACKAGE_RUNNER_STEMS = Object.freeze(['vitest', 'jest', 'eslint', 'prettier', 'tsc', 'vite']);
+
+// Decision-3 order, test-pinned: (1) string-typed, else not offered; (2) reject ANY char outside
+// printable ASCII + space/tab BEFORE trimming — String.trim() strips \n/NBSP/BOM at the EDGES and
+// would mask a leading/trailing forbidden char; (3) trim + collapse ASCII space/tab runs to one
+// space; (4) literal membership. No case folding, no arg reordering, no separate env/path reject
+// axis — `FOO=bar node --test` and `./scripts/x.sh` are already rejected by NON-MEMBERSHIP.
+const PRINTABLE_ASCII_BODY_PATTERN = /^[\x20-\x7E\t]*$/;
+const allowlistedBodyOf = (body) => {
+  if (typeof body !== 'string') return null;
+  if (!PRINTABLE_ASCII_BODY_PATTERN.test(body)) return null;
+  const normalized = body.replace(/^[ \t]+|[ \t]+$/g, '').replace(/[ \t]+/g, ' ');
+  return BODY_ALLOWLIST.includes(normalized) ? normalized : null;
+};
+
+// The per-PM HOOK-FREE exec form (Decision 1, host-proven npm 12 / pnpm 10 / yarn 1 + berry 4):
+// `exec` runs a COMMAND, not a named script — no pre/post lifecycle exists to fire, uniformly.
+// The `--` keeps a body flag (`jest --ci`) from being absorbed by the PM. Per-PM hardening — the
+// pinned invariant is NO NETWORK FETCH of an absent runner, not "no user-machine fallback":
+//   npm  — `--script-shell /bin/sh` beats a hostile per-project `.npmrc script-shell` (proven the
+//          flag wins) and `--offline` refuses an absent runner as a cache miss, never a registry
+//          fetch; a hit on a previously-installed real package (the npm cache OR the host's
+//          global tree — both user machine state, not project content) is the documented runtime
+//          residual (Decision 2 ii / 6), not a separate guard.
+//   pnpm — no network fetch; an absent runner fails closed when no project-local or
+//          PATH-resolvable runner exists (a user-installed one executing is the same
+//          user-machine-state residual). Reads no npm `.npmrc script-shell`.
+//   yarn — same contract, uniform for classic + berry (berry resolves via .pnp.cjs; proven).
+// The `COREPACK_ENABLE_NETWORK=0` prefix closes ONE more attacker-reachable fetch axis: when the
+// PM binary is a Corepack shim, a hostile `packageManager: "<pm>@<uncached-version>"` field makes
+// Corepack DOWNLOAD that PM release from the registry BEFORE exec even resolves the runner. The env
+// var disables that provisioning (proven: it fails closed "Network access disabled" on an uncached
+// pin, and is inert when the PM is a real install or already provisioned) — so the no-network
+// contract holds for the PM-provision step too, not just the runner. Applies to all three (Corepack
+// can shim npm/pnpm/yarn alike). An UNKNOWN family has no verified fail-closed exec contract → cmd
+// null (withheld, loud note) — the mild worst case, never a hole. detectPackageManager can only
+// yield npm/pnpm/yarn today (bun collapses to npm — characterized), so this is the builder floor.
+const COREPACK_NO_NETWORK = 'COREPACK_ENABLE_NETWORK=0';
+export const execCmdFor = (pm, body) => {
+  if (pm === 'npm') return { cmd: `${COREPACK_NO_NETWORK} npm exec --offline --script-shell /bin/sh -- ${body}`, note: null };
+  if (pm === 'pnpm') return { cmd: `${COREPACK_NO_NETWORK} pnpm exec -- ${body}`, note: null };
+  if (pm === 'yarn') return { cmd: `${COREPACK_NO_NETWORK} yarn exec -- ${body}`, note: null };
+  return {
+    cmd: null,
+    note: `no fail-closed exec form is verified for this package manager (${pm}) — add the gate by hand`,
+  };
+};
 
 export const kebabIdOf = (name) =>
   String(name)
@@ -133,8 +215,11 @@ export const detectPackageManager = (cwd, deps = {}) => {
   return 'npm';
 };
 
-// The script-derived offer entries. Order = package.json scripts order (the offer the user reads).
-export const deriveScriptEntries = (cwd, deps = {}) => {
+// The script-derived offer: entries + loud honesty notes (a gate-class script screened out on its
+// body, or a whole family withheld, is COUNTED and NAMED — never silently absent). Order =
+// package.json scripts order (the offer the user reads). `deps.packageManager` injects a family
+// token past the detector for the builder-boundary fail-closed proof (T4b).
+const deriveScripts = (cwd, deps = {}) => {
   const read = deps.readFile ?? readFileSync;
   const pkg = (() => {
     try {
@@ -143,29 +228,48 @@ export const deriveScriptEntries = (cwd, deps = {}) => {
       return null; // no/unreadable package.json → no script candidates (an honest empty offer)
     }
   })();
-  const pm = detectPackageManager(cwd, deps);
-  const seen = new Set();
-  const bodyOf = (name) => String(pkg?.scripts?.[name] ?? '');
-  return discoverGateCandidates(pkg ?? {})
+  const pm = deps.packageManager ?? detectPackageManager(cwd, deps);
+  const named = discoverGateCandidates(pkg ?? {})
     .filter((c) => !c.warn) // warn-flagged NEVER enter the offer
     .filter((c) => SAFE_SCRIPT_NAME_PATTERN.test(c.scriptName)) // shell-safe names only, FIRST
     .filter((c) => TERMINATING_CLASS_PATTERN.test(c.scriptName))
     .filter((c) => !isNonTerminatingName(c.scriptName))
-    .filter((c) => !MUTATING_VARIANT_NAME_PATTERN.test(c.scriptName) && !MUTATING_BODY_FLAG_PATTERN.test(bodyOf(c.scriptName)))
-    .filter((c) => !isNonTerminatingBody(bodyOf(c.scriptName)))
-    .filter((c) => !isDangerousBody(bodyOf(c.scriptName)))
-    .map((c) => ({
-      id: kebabIdOf(c.scriptName),
-      title: `Project script: ${pm} run ${c.scriptName}`,
-      cmd: `${pm} run ${c.scriptName}`,
-    }))
-    .filter((e) => {
-      if (!e.id || seen.has(e.id)) return false; // an empty or duplicate derived id never enters the offer
-      seen.add(e.id);
-      return true;
-    });
+    .filter((c) => !MUTATING_VARIANT_NAME_PATTERN.test(c.scriptName));
+  const seen = new Set(); // first occurrence of a derived id wins, whatever its outcome (conservative)
+  const entries = [];
+  const screenedIds = [];
+  const withheld = [];
+  for (const c of named) {
+    const id = kebabIdOf(c.scriptName);
+    if (!id || seen.has(id)) continue; // an empty or duplicate derived id never enters the offer
+    seen.add(id);
+    const body = allowlistedBodyOf(pkg?.scripts?.[c.scriptName]);
+    if (body === null) {
+      screenedIds.push(id);
+      continue;
+    }
+    const { cmd, note } = execCmdFor(pm, body);
+    if (cmd === null) {
+      withheld.push({ id, note });
+      continue;
+    }
+    entries.push({ id, title: `Project script ${c.scriptName}: ${body}`, cmd });
+  }
+  const notes = [];
+  if (screenedIds.length) {
+    notes.push(
+      `${screenedIds.length} gate-class script(s) screened out — body not in the closed-world ` +
+        `allowlist: ${screenedIds.join(', ')} — a command you trust can still be declared by hand in ${GATES_REL}`,
+    );
+  }
+  if (withheld.length) {
+    notes.push(`${withheld.length} script gate(s) withheld: ${withheld.map((w) => w.id).join(', ')} — ${withheld[0].note}`);
+  }
+  return { entries, notes };
 };
 
+export const deriveScriptEntries = (cwd, deps = {}) => deriveScripts(cwd, deps).entries;
+
 // The conditional review-state candidate — keyed on the SLOT the checker enforces
 // (plan-execution.review, tools/review-state.mjs), read via the shared config reader. Offered only
 // when the config DECLARES reviewed/council there; solo configs and a council-on-plan-authoring-only
@@ -256,14 +360,13 @@ const assertOnlyIdsOffered = (offer, onlyIds = []) => {
 // plus loud notes. Both review candidates key on the same slot (plan-execution.review reviewed/council)
 // but gate distinct axes (receipt presence vs review-round convergence) — offered together.
 export const buildOffer = (cwd, deps = {}) => {
-  const entries = deriveScriptEntries(cwd, deps);
+  const scripts = deriveScripts(cwd, deps);
   const rs = reviewStateCandidate(cwd, deps);
   const rl = reviewLedgerCandidate(cwd, deps);
   const candidates = [rs.candidate, rl.candidate].filter(Boolean);
-  const notes = [rs.note, rl.note].filter(Boolean);
   return {
-    entries: [...entries, ...candidates],
-    notes,
+    entries: [...scripts.entries, ...candidates],
+    notes: [...scripts.notes, rs.note, rl.note].filter(Boolean),
   };
 };
 
@@ -361,7 +464,7 @@ export const applySeed = ({ cwd, onlyIds = [] }, deps = {}) => {
   }
   const offer = buildOffer(cwd, deps);
   assertOnlyIdsOffered(offer, onlyIds); // BEFORE the empty-offer return — a typo is never masked
-  if (!offer.entries.length) return { outcome: 'nothing' };
+  if (!offer.entries.length) return { outcome: 'nothing', notes: offer.notes };
   const selected = onlyIds.length ? offer.entries.filter((e) => onlyIds.includes(e.id)) : offer.entries;
 
   const existing = loadExistingDeclaration(cwd, deps);
@@ -382,7 +485,7 @@ export const applySeed = ({ cwd, onlyIds = [] }, deps = {}) => {
   validateDeclaration(merged); // every written declaration passes the runner's validator, always
   const body = `${JSON.stringify(merged, null, 2)}\n`;
   const { writtenPath } = writeDocsAiFileAtomic(cwd, GATES_REL, body, deps, { stop, noun: 'a gate declaration' });
-  return { outcome: 'written', writtenPath, appended: selected.map((e) => e.id) };
+  return { outcome: 'written', writtenPath, appended: selected.map((e) => e.id), notes: offer.notes };
 };
 
 // ── CLI ────────────────────────────────────────────────────────────────────────────────
@@ -439,9 +542,11 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
     const result = applySeed({ cwd, onlyIds: args.only }, deps);
     if (result.outcome === 'nothing') {
       log('[agent-workflow-kit] nothing to offer — no seedable terminating verification scripts were found; wrote nothing.');
+      for (const note of result.notes) log(`  note: ${note}`); // the user learns WHY (same note as the preview)
       return EXIT_OK;
     }
     log(`[agent-workflow-kit] appended ${result.appended.length} consented gate(s) to ${GATES_REL}: ${result.appended.join(', ')}`);
+    for (const note of result.notes) log(`  note: ${note}`); // a mixed offer never silently omits what was screened
     log(`[agent-workflow-kit] ${TRUST_CHAIN_DISCLOSURE}`);
     return EXIT_OK;
   } catch (err) {