@sabaiway/agent-workflow-kit 1.33.0 → 1.35.0

package/tools/seed-gates.mjs

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+// seed-gates.mjs — the consent-gated docs/ai/gates.json seeder (AD-042). Reached ONLY through
+// explicitly-consenting prose (the bootstrap accelerators block and the gates.md consent-seed
+// section) — it is NOT a routable mode token, it sits OUTSIDE every velocity allowlist tier
+// (a consent-per-run writer is never pre-approved), and the shipped gates.json TEMPLATE stays
+// 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):
+//   • 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);
+//   • 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);
+//   • the review-state candidate appears ONLY when docs/ai/orchestration.json DECLARES
+//     reviewed/council on plan-execution.review — the slot the checker enforces — with the
+//     resolved, QUOTED tool path (spaces survive; executes from the project root).
+//
+// Write discipline: preview (dry-run) is the DEFAULT and writes NOTHING — a declined offer leaves
+// the file byte-identical. `--apply` appends EXACTLY the consented entries (`--only <id>`
+// repeatable) through the shared atomic-write core (tools/atomic-write.mjs — exclusive-create
+// tmp+rename, TOCTOU re-check, symlink STOPs): append-only, never modifies or removes an existing
+// entry, refuses id collisions, refuses a malformed declaration (never writes over what it cannot
+// parse). Deployment-gated: docs/ai presence (lstat, no-follow) on EVERY run; the
+// .workflow-version == lineage-head stamp gate on --apply only (the velocity/gate-hook precedent).
+//
+// Exit codes: 0 done / dry-run; 1 precondition STOP (no deployment, stamp, symlink, malformed
+// declaration, id collision); 2 usage. Dependency-free, Node >= 18. No side effects on import.
+
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { discoverGateCandidates, EXPECTED_WORKFLOW_VERSION } from './velocity-profile.mjs';
+import { GATES_REL, validateDeclaration } from './run-gates.mjs';
+import { loadConfig } from './orchestration-config.mjs';
+import { assertDocsAiDeployment, writeDocsAiFileAtomic, lstatNoFollow } from './atomic-write.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = resolve(HERE, '..');
+const TEMPLATE_PATH = join(KIT_ROOT, 'references', 'templates', 'gates.json');
+const REVIEW_STATE_TOOL = join(KIT_ROOT, 'tools', 'review-state.mjs');
+const STAMP_REL = join('docs', 'ai', '.workflow-version');
+
+const EXIT_OK = 0;
+const EXIT_PRECONDITION = 1;
+const EXIT_USAGE = 2;
+
+export const SEED_GATES_STOP = 'SEED_GATES_STOP';
+const stop = (message) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'SeedGatesStop', code: SEED_GATES_STOP, exitCode: EXIT_PRECONDITION });
+const usageFail = (message) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: EXIT_USAGE });
+
+// The trust-chain disclosure (AD-042) — printed with EVERY preview, token-pinned by the tests: a
+// consent-seeded command becomes auto-approvable only after TWO explicit consents.
+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.';
+
+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}`;
+
+// ── candidate classification (the LOCKED derivation invariants) ────────────────────────
+// The derived cmd (`<pm> run <name>`) 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.
+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) =>
+  String(text)
+    .split(splitter)
+    .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.
+const MUTATING_VARIANT_NAME_PATTERN = /(^|[:._-])(fix|write|update|snapshot)([:._-]|$)/i;
+const MUTATING_BODY_FLAG_PATTERN = /(^|\s)(--fix|--write|--update(?:-snapshot)?|--updateSnapshot|-w|-u)(=|\s|$)/;
+
+export const kebabIdOf = (name) =>
+  String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+// package manager: the package.json `packageManager` field wins, else the lockfile probe, else npm.
+export const detectPackageManager = (cwd, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  const exists = deps.exists ?? existsSync;
+  const fromField = (() => {
+    try {
+      const pkg = JSON.parse(String(read(join(cwd, 'package.json'), 'utf8')));
+      const pm = typeof pkg.packageManager === 'string' ? pkg.packageManager.split('@')[0] : null;
+      return pm === 'pnpm' || pm === 'yarn' || pm === 'npm' ? pm : null;
+    } catch {
+      return null;
+    }
+  })();
+  if (fromField) return fromField;
+  if (exists(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (exists(join(cwd, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+};
+
+// The script-derived offer entries. Order = package.json scripts order (the offer the user reads).
+export const deriveScriptEntries = (cwd, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  const pkg = (() => {
+    try {
+      return JSON.parse(String(read(join(cwd, 'package.json'), 'utf8')));
+    } catch {
+      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 ?? {})
+    .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;
+    });
+};
+
+// 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
+// config never see it. The cmd carries the resolved, QUOTED tool path and passes the validator.
+// Double-quote-unsafe shell metacharacters: inside `"…"` bash still expands `$`, backticks and
+// backslashes, and a `"` breaks the quoting entirely. A candidate cmd is hook-auto-approvable, so a
+// path that cannot be safely double-quoted is WITHHELD with a loud note — never offered wrongly.
+const DQ_UNSAFE_PATH_PATTERN = /["$`\\\r\n]/;
+
+export const reviewStateCandidate = (cwd, deps = {}) => {
+  const toolPath = deps.reviewStateTool ?? REVIEW_STATE_TOOL;
+  try {
+    const { config } = loadConfig(resolve(cwd), deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
+    const declared = config?.['plan-execution']?.review;
+    if (declared !== 'reviewed' && declared !== 'council') return { candidate: null, note: null };
+    if (DQ_UNSAFE_PATH_PATTERN.test(toolPath)) {
+      return {
+        candidate: null,
+        note:
+          `the review-state candidate was withheld: the resolved kit path contains shell ` +
+          `metacharacters that do not survive double-quoting (${toolPath}) — declare the gate ` +
+          `by hand per references/modes/review-state.md step 3`,
+      };
+    }
+    return {
+      candidate: {
+        id: 'review-state',
+        title: 'Review receipts current for the uncommitted tree',
+        cmd: `node "${toolPath}" --check`,
+      },
+      note: null,
+    };
+  } catch (err) {
+    return {
+      candidate: null,
+      note: `orchestration config unreadable (${err.message}) — the review-state candidate was not evaluated`,
+    };
+  }
+};
+
+// Every --only id must name an OFFERED entry — enforced in BOTH paths (dry-run and apply), before
+// any empty-offer shortcut, so a typo is a loud usage error, never a silent filter or a silent
+// "nothing to offer" success.
+const assertOnlyIdsOffered = (offer, onlyIds = []) => {
+  const offered = new Set(offer.entries.map((e) => e.id));
+  const unknown = onlyIds.filter((id) => !offered.has(id));
+  if (unknown.length) {
+    throw usageFail(`--only names ids not in the offer: ${unknown.join(', ')} (offered: ${[...offered].join(', ') || 'none'})`);
+  }
+};
+
+// The full offer: script entries + the conditional review-state candidate (last), plus loud notes.
+export const buildOffer = (cwd, deps = {}) => {
+  const entries = deriveScriptEntries(cwd, deps);
+  const { candidate, note } = reviewStateCandidate(cwd, deps);
+  return {
+    entries: candidate ? [...entries, candidate] : entries,
+    notes: note ? [note] : [],
+  };
+};
+
+// The RUNNABLE apply invocation for a given project — this tool has no bin and no mode token, so
+// the consent step must print the real command, never a bare `seed-gates`. Consent integrity: a
+// previewed --only subset is carried into the hint VERBATIM (ids are shell-safe by construction —
+// kebabIdOf output / the fixed `review-state`), so following the hint can never widen the consent.
+// Paths that do not survive double-quoting (the reviewStateCandidate screen, same pattern) make
+// this return null — the preview then falls back to a generic, unquoted instruction.
+export const applyInvocationFor = (cwd, onlyIds = []) => {
+  const ownPath = fileURLToPath(import.meta.url);
+  if (DQ_UNSAFE_PATH_PATTERN.test(ownPath) || DQ_UNSAFE_PATH_PATTERN.test(cwd)) return null;
+  const only = onlyIds.map((id) => ` --only ${id}`).join('');
+  return `node "${ownPath}" --cwd "${cwd}" --apply${only}`;
+};
+
+const GENERIC_APPLY_HINT = 're-run this same command with --apply [--only <id>]...';
+
+export const formatPreview = (offer, applyInvocation = null, { explicitOnly = false } = {}) => {
+  const lines = ['[agent-workflow-kit] gates seeding preview (dry-run — nothing was written):'];
+  if (!offer.entries.length) {
+    lines.push('  nothing to offer — no seedable terminating verification scripts were found.');
+  }
+  for (const e of offer.entries) {
+    lines.push(`  ${e.id}: ${e.cmd}   (${e.title})`);
+  }
+  for (const note of offer.notes) lines.push(`  note: ${note}`);
+  if (offer.entries.length) {
+    const suffix = explicitOnly ? '' : ' [--only <id>]...';
+    lines.push(`  apply exactly the entries you consent to: ${applyInvocation ?? GENERIC_APPLY_HINT}${applyInvocation ? suffix : ''}`);
+  }
+  lines.push(`  ${TRUST_CHAIN_DISCLOSURE}`);
+  return lines.join('\n');
+};
+
+// ── the existing declaration (append-only source) ──────────────────────────────────────
+const loadExistingDeclaration = (cwd, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  const full = join(cwd, GATES_REL);
+  const leaf = lstatNoFollow(full, lstat);
+  if (leaf === null) return { outcome: 'missing' };
+  // Refuse a symlinked leaf HERE, before any read/parse — the atomic core would refuse it at write
+  // time anyway, but the honest STOP names the symlink, not a misleading parse error on its target.
+  if (leaf.isSymbolicLink()) {
+    throw stop(`${GATES_REL} is a symlink — refusing to touch it (a write would clobber the link target)`);
+  }
+  const parsed = (() => {
+    try {
+      return JSON.parse(String(read(full, 'utf8')));
+    } catch (err) {
+      throw stop(`${GATES_REL}: malformed JSON (${err.message}) — fix it by hand; the seeder never writes over a declaration it cannot parse`);
+    }
+  })();
+  const gates = (() => {
+    try {
+      return validateDeclaration(parsed);
+    } catch (err) {
+      throw stop(`${err.message} — fix it by hand; the seeder never writes over an invalid declaration`);
+    }
+  })();
+  return { outcome: 'loaded', readme: typeof parsed._README === 'string' ? parsed._README : undefined, gates };
+};
+
+const templateReadme = (deps = {}) => {
+  const read = deps.readTemplate ?? readFileSync;
+  try {
+    const parsed = JSON.parse(String(read(TEMPLATE_PATH, 'utf8')));
+    if (typeof parsed._README !== 'string') throw new Error('template has no _README');
+    return parsed._README;
+  } catch (err) {
+    throw stop(`the bundled gates.json template is unreadable (${err.message}) — the kit install is incomplete`);
+  }
+};
+
+const readStampValue = (cwd, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  try {
+    const v = String(read(join(cwd, STAMP_REL), 'utf8')).trim();
+    return v.length ? v : null;
+  } catch {
+    return null;
+  }
+};
+
+// ── apply (append exactly the consented entries) ───────────────────────────────────────
+export const applySeed = ({ cwd, onlyIds = [] }, deps = {}) => {
+  assertDocsAiDeployment(cwd, deps, { stop, noun: 'a gate declaration', rel: GATES_REL });
+  const stampValue = readStampValue(cwd, deps);
+  if (stampValue !== EXPECTED_WORKFLOW_VERSION) {
+    throw stop(
+      `--apply is deployment-gated: ${STAMP_REL} is ${stampValue ?? 'absent'} but this kit expects ` +
+        `${EXPECTED_WORKFLOW_VERSION} (the preview works on any deployment; run upgrade first)`,
+    );
+  }
+  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' };
+  const selected = onlyIds.length ? offer.entries.filter((e) => onlyIds.includes(e.id)) : offer.entries;
+
+  const existing = loadExistingDeclaration(cwd, deps);
+  const existingGates = existing.outcome === 'loaded' ? existing.gates : [];
+  const existingIds = new Set(existingGates.map((g) => g.id));
+  const collisions = selected.filter((e) => existingIds.has(e.id)).map((e) => e.id);
+  if (collisions.length) {
+    throw stop(
+      `id collision — already declared in ${GATES_REL}: ${collisions.join(', ')} (append-only: the ` +
+        `seeder never modifies or removes an existing entry; pick the others with --only, or edit by hand)`,
+    );
+  }
+
+  const merged = {
+    _README: existing.outcome === 'loaded' && existing.readme !== undefined ? existing.readme : templateReadme(deps),
+    gates: [...existingGates, ...selected],
+  };
+  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) };
+};
+
+// ── CLI ────────────────────────────────────────────────────────────────────────────────
+export const parseArgs = (argv) => {
+  const parsed = argv.reduce(
+    (acc, a, i) => {
+      if (acc.skip) return { ...acc, skip: false };
+      if (a === '--help' || a === '-h') return { ...acc, help: true };
+      // A consent-gated writer never lets a later flag silently decide whether it mutates:
+      // mixed --dry-run/--apply is a usage error, whichever order they arrive in.
+      if (a === '--dry-run') {
+        if (acc.apply === true) throw usageFail('--dry-run and --apply are mutually exclusive — pick one');
+        return { ...acc, apply: false, dryRunExplicit: true };
+      }
+      if (a === '--apply') {
+        if (acc.dryRunExplicit) throw usageFail('--dry-run and --apply are mutually exclusive — pick one');
+        return { ...acc, apply: true };
+      }
+      if (a === '--cwd') {
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('-')) throw usageFail('--cwd needs a value: --cwd <dir>');
+        return { ...acc, cwd: value, skip: true };
+      }
+      if (a === '--only') {
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('-')) throw usageFail('--only needs a gate id');
+        return { ...acc, only: [...acc.only, value], skip: true };
+      }
+      throw usageFail(`unknown argument: ${a}`);
+    },
+    { help: false, apply: false, dryRunExplicit: false, cwd: undefined, only: [], skip: false },
+  );
+  return parsed;
+};
+
+export const main = (argv = process.argv.slice(2), deps = {}) => {
+  const log = deps.log ?? console.log;
+  const error = deps.error ?? console.error;
+  try {
+    const args = parseArgs(argv);
+    if (args.help) {
+      log(USAGE);
+      return EXIT_OK;
+    }
+    const cwd = resolve(args.cwd ?? process.cwd());
+    assertDocsAiDeployment(cwd, deps, { stop, noun: 'a gate declaration', rel: GATES_REL });
+    if (!args.apply) {
+      const offer = buildOffer(cwd, deps);
+      assertOnlyIdsOffered(offer, args.only); // a dry-run --only typo is loud too
+      const filtered = args.only.length ? { ...offer, entries: offer.entries.filter((e) => args.only.includes(e.id)) } : offer;
+      log(formatPreview(filtered, applyInvocationFor(cwd, args.only), { explicitOnly: args.only.length > 0 }));
+      return EXIT_OK;
+    }
+    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.');
+      return EXIT_OK;
+    }
+    log(`[agent-workflow-kit] appended ${result.appended.length} consented gate(s) to ${GATES_REL}: ${result.appended.join(', ')}`);
+    log(`[agent-workflow-kit] ${TRUST_CHAIN_DISCLOSURE}`);
+    return EXIT_OK;
+  } catch (err) {
+    error(err?.message ?? String(err));
+    return err?.exitCode ?? EXIT_PRECONDITION;
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) process.exit(main(process.argv.slice(2)));

package/tools/setup-backends.mjs

@@ -99,6 +99,78 @@ const probeMarker = (file, fs) => {
   }
 };
 
+// ── overwrite honesty (D5) — state what a refresh replaced, never a silent wipe ────────────────────
+
+// The host-level settings surface a refresh NEVER touches — the one place a bridge tweak survives a
+// kit upgrade (bridge CODE stays kit-owned; only these knobs persist). Named wherever a refresh
+// reports overwriting a local edit, so the recovery is always a copy-paste away.
+const SETTINGS_FILE_HINT = '${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf';
+const SETTINGS_CMD_HINT = '/agent-workflow-kit bridge-settings';
+
+// Bundle-owned regular files whose PLACED copy differs from the bundle (a local edit an equal-version
+// refresh would overwrite) or cannot be read (indeterminate — an honest degrade). Mirrors
+// copyTreeRefresh's src dispatch so it flags EXACTLY the files the overwrite touches: a symlink src is
+// additive (copyTreeRefresh skips an existing dest — never overwritten) and a dir recurses; a
+// bundled-only file (no placed copy) is a pure add, no loss. The BUNDLE read is our own shipped
+// artifact — a failure there is a loud corrupt-kit error upstream (never swallowed here); only the
+// PLACED read is caught (EACCES/EIO → 'unreadable', and the refresh still proceeds). Sorted output is
+// deterministic for the stated line. Exported for a direct unit test (the full driver cannot observe a
+// symlinked placed file — copyTreeRefresh refuses to overwrite one, so the refresh fails before any line).
+export const scanBundleOwnedDrift = (bundleDir, skillDir, fs) => {
+  const drifted = [];
+  const unreadable = [];
+  const walk = (rel) => {
+    const src = join(bundleDir, rel);
+    const dest = join(skillDir, rel);
+    const st = fs.lstat(src);
+    if (st.isSymbolicLink()) return;
+    if (st.isDirectory()) {
+      for (const entry of fs.readdir(src)) walk(rel ? join(rel, entry) : entry);
+      return;
+    }
+    // lstat the PLACED path NO-FOLLOW first — never read THROUGH a symlink (copyTreeRefresh's
+    // assertContainedRealPath would refuse to overwrite a symlinked dest, so reading its target here
+    // would be both unsafe and moot). Absent → a bundled-only addition (no local loss); a symlink /
+    // non-regular / unreadable placed node → "could not compare" without a read-through.
+    const destStat = (() => {
+      try {
+        return fs.lstat(dest);
+      } catch (err) {
+        return err && err.code === 'ENOENT' ? 'absent' : 'error';
+      }
+    })();
+    if (destStat === 'absent') return;
+    if (destStat === 'error' || destStat.isSymbolicLink() || !destStat.isFile()) {
+      unreadable.push(rel);
+      return;
+    }
+    const srcBytes = fs.readFile(src);
+    const destBytes = (() => {
+      try {
+        return fs.readFile(dest);
+      } catch {
+        unreadable.push(rel);
+        return null;
+      }
+    })();
+    if (destBytes === null) return;
+    if (!Buffer.from(srcBytes).equals(Buffer.from(destBytes))) drifted.push(rel);
+  };
+  walk('');
+  return { drifted: drifted.sort(), unreadable: unreadable.sort() };
+};
+
+// One user-facing sentence naming what an equal-version re-sync overwrote — or null when nothing local
+// was lost. Callers apply their own indent; the pointer names the settings file that survives a refresh.
+const driftSummary = (drift) => {
+  if (!drift) return null;
+  const parts = [];
+  if (drift.drifted.length) parts.push(`overwrote ${drift.drifted.length} locally-changed file(s): ${drift.drifted.join(', ')}`);
+  if (drift.unreadable.length) parts.push(`could not compare ${drift.unreadable.length} file(s) (kept the bundled copy): ${drift.unreadable.join(', ')}`);
+  if (!parts.length) return null;
+  return `${parts.join('; ')} — bridge code is kit-owned and always refreshed; persist host tweaks in ${SETTINGS_FILE_HINT} (survives every refresh): ${SETTINGS_CMD_HINT}`;
+};
+
 // ── path resolution ──────────────────────────────────────────────────────────
 
 const skillDirOf = (entry, deps) =>
@@ -253,14 +325,26 @@ const assertNoDowngrade = (plan, deps = {}) => {
   if (compareSemver(placed, bundled) === 1) throw stop(downgradeReason(placed, bundled), { skillDir: plan.skillDir, wouldDowngrade: true });
 };
 
+// Copy the bundle over the placed skill dir (the refresh overwrite), FIRST scanning bundle-owned files
+// for local drift so the caller can STATE what the overwrite replaced (D5 — overwrite honesty). Scan
+// only on a refresh: a `place` writes into an absent/empty dir, so there is nothing local to lose. The
+// copy proceeds either way — bridge code is kit-owned. Returns the drift report (null for a place).
+const copyBridgeWithHonesty = (action, bundleDir, skillDir, deps) => {
+  const fs = fsDeps(deps);
+  const drift = action === 'refresh' ? scanBundleOwnedDrift(bundleDir, skillDir, fs) : null;
+  copyTreeRefresh(bundleDir, skillDir, skillDir, fs);
+  return drift;
+};
+
 // Place/refresh the bundled bridge skill. Re-inspects before writing (never trusts a stale plan).
+// Returns the plan plus `drift`: on a refresh, the bundle-owned files whose local edits it overwrote.
 export const placeSkill = (name, deps = {}) => {
   const entry = registryEntry(name);
   if (!entry) throw stop(`unknown backend: ${name}`);
   const plan = inspectSkillDir(entry, deps);
   assertNoDowngrade(plan, deps);
-  copyTreeRefresh(plan.bundleDir, plan.skillDir, plan.skillDir, fsDeps(deps));
-  return plan;
+  const drift = copyBridgeWithHonesty(plan.action, plan.bundleDir, plan.skillDir, deps);
+  return { ...plan, drift };
 };
 
 // Link the wrappers onto `bindir`. PREFLIGHT all (source is a regular non-symlink file inside the
@@ -413,9 +497,12 @@ export const planFor = (backend, deps = {}) => {
 // in the plan across the read→write gap). Throws on a mid-flight conflict / fs error (honest partial
 // failure — placeSkill/chmod/symlink all converge on a re-run, so there is nothing to roll back).
 const applyBackend = (plan, deps) => {
-  if (plan.place.action === 'place' || plan.place.action === 'refresh') placeSkill(plan.name, deps);
+  const placed = (plan.place.action === 'place' || plan.place.action === 'refresh')
+    ? placeSkill(plan.name, deps)
+    : null;
   const manifest = readBundledManifest(plan.place.bundleDir, deps);
   linkWrappers(plan.skillDir, manifest, { ...deps, bindir: plan.bindir, platform: plan.platform });
+  return { drift: placed?.drift ?? null };
 };
 
 // ── formatting ─────────────────────────────────────────────────────────────────
@@ -442,6 +529,11 @@ const formatBackend = (plan, applied) => {
   }
   const placeVerb = applied ? { place: 'placed', refresh: 'refreshed' } : { place: 'will place', refresh: 'will refresh' };
   lines.push(`      • skill: ${placeVerb[plan.place.action]}${versionLabel(plan)} → ${plan.skillDir}`);
+  // Overwrite honesty (D5): on an equal-version re-sync that clobbered a local edit, say so (a version
+  // upgrade's diffs are the version delta — versionLabel's arrow already signals that change).
+  const equalVersionRefresh = plan.place.action === 'refresh' && (!plan.priorVersion || plan.priorVersion === plan.version);
+  const driftLine = equalVersionRefresh ? driftSummary(plan.drift) : null;
+  if (driftLine) lines.push(`      ↳ ${driftLine}`);
   for (const l of plan.links) {
     const verb = l.dstState === 'ours' ? 'already linked' : applied ? 'linked' : 'will link';
     lines.push(`      • wrapper ${l.cmd}: ${verb} → ${l.dst}`);
@@ -463,10 +555,10 @@ const formatBackend = (plan, applied) => {
 // a per-bridge lock file would be new machinery for a user-driven, self-healing race.
 const refreshSkillOnly = (entry, deps = {}) => {
   const fresh = inspectSkillDir(entry, deps);
-  if (fresh.action !== 'refresh') return false;
+  if (fresh.action !== 'refresh') return { refreshed: false, drift: null };
   assertNoDowngrade(fresh, deps);
-  copyTreeRefresh(fresh.bundleDir, fresh.skillDir, fresh.skillDir, fsDeps(deps));
-  return true;
+  const drift = copyBridgeWithHonesty('refresh', fresh.bundleDir, fresh.skillDir, deps);
+  return { refreshed: true, drift };
 };
 
 const NOT_PLACED_LINE = 'skipped — not placed (placement is opt-in: /agent-workflow-kit setup)';
@@ -499,7 +591,8 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
       if (plan.outcome === 'stop' || plan.outcome === 'error') {
         return { name: plan.name, outcome: 'failed', line: `  ${plan.name}: could not refresh — ${stripPrefix(plan.reason)}; recover with /agent-workflow-kit setup` };
       }
-      if (!refreshSkillOnly(registryEntry(plan.name), deps)) {
+      const refresh = refreshSkillOnly(registryEntry(plan.name), deps);
+      if (!refresh.refreshed) {
         return { name: plan.name, outcome: 'not-placed', line: `  ${plan.name}: ${NOT_PLACED_LINE}` };
       }
       const manifest = readBundledManifest(plan.place.bundleDir, deps);
@@ -507,10 +600,14 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
       const current = plan.version !== null && plan.priorVersion === plan.version;
       // The equal-version line still states the copy that ran (repair-on-rerun) — the tool never
       // reports a mutation-free "already current" while it re-synced files underneath.
+      const base = `  ${plan.name}: ${current ? `already current${versionLabel(plan)} — files re-synced from the bundled copy` : `refreshed${versionLabel(plan)}`}`;
+      // Overwrite honesty (D5): only an EQUAL-version re-sync can prove a byte diff is a LOCAL edit —
+      // a version upgrade's diffs are the version delta, which the (vOld → vNew) arrow already states.
+      const summary = current ? driftSummary(refresh.drift) : null;
       return {
         name: plan.name,
         outcome: current ? 'already-current' : 'refreshed',
-        line: `  ${plan.name}: ${current ? `already current${versionLabel(plan)} — files re-synced from the bundled copy` : `refreshed${versionLabel(plan)}`}`,
+        line: summary ? `${base}\n     ↳ ${summary}` : base,
       };
     } catch (err) {
       // A downgrade STOP raised at the write boundary (a newer bridge landed between plan and apply)
@@ -647,7 +744,8 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
     let plan = planFor(name, runDeps);
     if (!args.dryRun && plan.outcome === 'ok') {
       try {
-        applyBackend(plan, runDeps);
+        const { drift } = applyBackend(plan, runDeps);
+        plan = { ...plan, drift };
         appliedOk = true;
       } catch (err) {
         plan = { ...plan, outcome: err.code === SETUP_STOP ? 'stop' : 'error', reason: err.message };

package/tools/velocity-profile.mjs

@@ -364,8 +364,12 @@ const isScriptMap = (scripts) => Boolean(scripts) && typeof scripts === 'object'
 const isMutatingScriptName = (name) =>
   MUTATING_SCRIPT_NAME_PATTERN.test(name) || MUTATING_SCRIPT_HOOK_PATTERN.test(name);
 
+// `scriptName` is ADDITIVE (AD-042): the seed-gates offer layer maps a candidate to a
+// package-manager-aware `{ id, title, cmd }` and needs the raw script name for that derivation;
+// `command` stays the advisory's own npm-run spelling (this fn is otherwise unchanged).
 const makeGateCandidate = (name) => ({
   command: `${NPM_RUN_COMMAND} ${name}`,
+  scriptName: name,
   addByHand: ADD_BY_HAND,
   ...(isMutatingScriptName(name) ? { warn: DO_NOT_ADD_WARNING } : {}),
 });

package/tools/view-model.mjs

@@ -32,6 +32,13 @@ const bridgeVm = (b) => ({
   readiness: b.readiness,
   // preserve the three-state wrapper status (present | missing | unknown) — the renderer maps to a glyph.
   wrappers: (b.wrappers ?? []).map((w) => ({ cmd: w.cmd, state: w.state })),
+  // fact-only host-level settings: the active knobs for this bridge, or a localized error; null when
+  // nothing is set (the renderer then adds no sub-line — the block stays as it was before any knob).
+  settings: b.settings?.error
+    ? { error: b.settings.error }
+    : b.settings?.active?.length
+      ? { active: b.settings.active.map((a) => ({ key: a.key, value: a.value, source: a.source })) }
+      : null,
 });
 
 const visibilityVm = (v) => {
@@ -65,6 +72,12 @@ const velocityVm = (v) => {
   return { defaultMode: v.defaultMode ?? null, allow: { project: v.allowEntries?.project ?? 0, local: v.allowEntries?.local ?? 0 } };
 };
 
+const agentsVm = (a) => {
+  if (!a) return null;
+  if (a.error) return { error: a.error };
+  return { bundled: a.bundled ?? 0, placed: a.placed ?? 0 };
+};
+
 const hookVm = (h) => {
   if (!h) return null;
   if (h.error) return { error: h.error };
@@ -72,6 +85,12 @@ const hookVm = (h) => {
     wired: Boolean(h.wired),
     filePlaced: Boolean(h.filePlaced),
     declarationPresent: Boolean(h.declarationPresent),
+    // 0 = absent/empty declaration; null = unreadable/malformed OR an envelope predating the
+    // field — unknown reads as unknown, never as a count (the welcome-mat hook rung keys on > 0).
+    declaredGates: h.declaredGates ?? null,
+    // The preserved validation reason for a null count (null when absent) — rendered beside the
+    // unknown marker so a malformed declaration is never a silent bare "?".
+    declarationError: h.declarationError ?? null,
   };
 };
 
@@ -81,6 +100,7 @@ const settingsVm = (s) =>
         recipes: recipesVm(s.recipes),
         attribution: attributionVm(s.attribution),
         velocity: velocityVm(s.velocity),
+        agents: agentsVm(s.agents),
         hook: hookVm(s.hook),
       }
     : null;