@sabaiway/agent-workflow-kit 1.41.0 → 1.43.0

package/tools/renderers.mjs

@@ -77,6 +77,10 @@ const renderProject = (vm, { color }) => {
   }
   for (const s of p.deployStamps) lines.push(`  ${pad(s.display, STAMP_COL)}${s.version ?? '—'}`);
   lines.push(`  ${pad('docs/ai present', STAMP_COL)}${p.docsAi ? 'yes' : 'no'}`);
+  // Only the actionable 'old' layout renders a line — a migrated/none store needs no note (AD-051).
+  if (p.adrLayout === 'old') {
+    lines.push(`  ${pad('ADR store', STAMP_COL)}old layout — run /agent-workflow-kit migrate-adr-store`);
+  }
   if (p.visibility) {
     const v = p.visibility.error ? `error: ${p.visibility.error}` : p.visibility.phrase;
     lines.push(`  ${pad('visibility', STAMP_COL)}${v}`);

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) {

package/tools/velocity-profile.mjs

@@ -15,7 +15,7 @@ import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, COMMAND_REDLINES } from '.
 
 // Deployment-lineage head this velocity build targets; bump together with agent-workflow-memory
 // LINEAGE_HEAD when the deployed docs/ai structure changes.
-export const EXPECTED_WORKFLOW_VERSION = '1.3.0';
+export const EXPECTED_WORKFLOW_VERSION = '2.0.0';
 export const SETTINGS_FILE = '.claude/settings.json';
 export const SETTINGS_LOCAL_FILE = '.claude/settings.local.json';
 export const CLAUDE_DIR = '.claude';

package/tools/view-model.mjs

@@ -111,6 +111,7 @@ const projectVm = (p) =>
         dir: p.dir,
         deployed: p.deployed,
         docsAi: p.docsAi,
+        adrLayout: p.adrLayout ?? null,
         deployStamps: (p.deployStamps ?? []).map((st) => ({ display: st.display, version: st.version ?? null })),
         visibility: visibilityVm(p.visibility),
         settings: settingsVm(p.settings),