@sabaiway/agent-workflow-kit 10.1.0 → 10.3.0

package/tools/ack-store.mjs

@@ -0,0 +1,57 @@
+// ack-store.mjs — the family-owned neutral acknowledgement store: its path, its closed lane->key registry,
+// the one fact fingerprint and the one guarded reader. Contract: docs/ai/specs/kit/ack-store.md.
+// A READ-ONLY leaf (the writer is ack-write.mjs). Dependency-free, Node >= 22; no side effects on import.
+
+import { createHash } from 'node:crypto';
+import { lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { assertContainedRealPath } from './fs-safe.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+
+export const ACKS_FILE = 'docs/ai/acks.json';
+export const ACKS_LANE_KEY = 'sandboxLaneAck';
+export const ACKS_WORKTREES_DIR_KEY = 'worktreesDirAck';
+export const ACKS_COVERAGE_DOMAIN_KEY = 'coverageDomainAck';
+export const ACKS_SOURCE_SIZE_COPY_KEY = 'sourceSizeCopyAck';
+export const ACKS_SPEC_ADOPTION_KEY = 'specAdoptionAck';
+
+// The CLOSED-WORLD ack-lane registry: the lane name an advisor item renders on the writer's command line ->
+// the store key that writer sets. A lane the registry does not name is a usage refusal at the writer.
+export const ACK_LANES = Object.freeze({
+  'sandbox-lane': ACKS_LANE_KEY,
+  'worktrees-dir': ACKS_WORKTREES_DIR_KEY,
+  'coverage-domain': ACKS_COVERAGE_DOMAIN_KEY,
+  'source-size-copy': ACKS_SOURCE_SIZE_COPY_KEY,
+  'spec-adoption': ACKS_SPEC_ADOPTION_KEY,
+});
+
+export const FINGERPRINT_LENGTH = 16;
+
+// The one fingerprint over an acknowledged FACT (a canonical string the caller composed).
+export const factFingerprint = (fact) => createHash('sha256').update(fact).digest('hex').slice(0, FINGERPRINT_LENGTH);
+
+// readAckValue(root, deps, key) -> the recorded string at `key`, or null for the not-yet-acked states
+// (an absent file or docs/ai, a non-string value). The path chain is guarded no-follow and the leaf is
+// read descriptor-bound (`deps.nofollow` injects that door), so a leaf swapped after the guard cannot
+// change the bytes read. A symlinked ancestor/leaf, an escape, a non-regular target, an IO error, a
+// malformed or non-object store all THROW (the caller's stated-skip lane).
+export const readAckValue = (root, deps = {}, ackKey) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const absPath = join(root, ACKS_FILE);
+  try {
+    assertContainedRealPath(root, absPath, { lstat });
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  }
+  const read = readRegularFileNoFollow(absPath, deps.nofollow ?? {});
+  if (read.outcome === 'absent') return null;
+  if (read.outcome === 'foreign') throw new Error(`${ACKS_FILE} is a ${read.className}, not a regular file — refusing to read it`);
+  if (read.outcome !== 'ok') throw new Error(`${ACKS_FILE} cannot be read (${read.code})`);
+  const parsed = JSON.parse(read.content);
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${ACKS_FILE}: expected a JSON object`);
+  }
+  const value = parsed[ackKey];
+  return typeof value === 'string' ? value : null;
+};

package/tools/ack-write.mjs

@@ -29,7 +29,7 @@ import { lstatSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isDirectRun } from './direct-run.mjs';
-import { ACKS_FILE, ACK_LANES } from './recommendations.mjs';
+import { ACKS_FILE, ACK_LANES } from './ack-store.mjs';
 import { assertDocsAiDeployment, writeDocsAiFileAtomic, lstatNoFollow } from './atomic-write.mjs';
 import { shellQuoteArg } from './review-state.mjs';
 

package/tools/doc-parity.mjs

@@ -72,6 +72,8 @@ import { RELAYED_ENSURE_TOKENS, RELAYED_FAILURE_CAUSES } from './ensure-vocabula
 // The MCP registration's four public strings. Imported from the READ-ONLY leaf, never from the
 // writer: a read-only lint must not pull the atomic-write core into its import graph.
 import { ENABLED_KEY as MCP_ENABLED_KEY, MCP_JSON_REL, SERVER_NAME as MCP_SERVER_NAME, allowRulesFor } from './mcp-registration.mjs';
+// The spec-adoption state tokens the status mode doc must name (contract: kit/spec-adoption).
+import { ADOPTION_STATES, SPEC_ADOPTION_LANE } from './spec-adoption.mjs';
 
 const AUTONOMY_DOCTOR_DOC = 'references/modes/autonomy-doctor.md';
 const RECOMMENDATIONS_DOC = 'references/modes/recommendations.md';
@@ -86,6 +88,7 @@ const RECEIPT_DEADLINE_DOC = 'references/modes/receipt-deadline.md';
 const GATES_DOC = 'references/modes/gates.md';
 const MCP_DOC = 'references/modes/mcp.md';
 const UNINSTALL_DOC = 'references/modes/uninstall.md';
+const STATUS_DOC = 'references/modes/status.md';
 // One literal for the dispatch mode doc: the structure leaf already names it as the file it anchors
 // its table in, and a second copy here is exactly the drift this lint exists to catch.
 const DISPATCH_DOC = ADVISOR_MATRIX_DOC;
@@ -236,6 +239,11 @@ export const BINDINGS = Object.freeze([
   valueBinding('mcp-enabled-key', MCP_ENABLED_KEY, `\`${MCP_ENABLED_KEY}\``, [MCP_DOC, UNINSTALL_DOC]),
   valueBinding('mcp-server-name', MCP_SERVER_NAME, `\`"${MCP_SERVER_NAME}"\``, [MCP_DOC, UNINSTALL_DOC]),
   ...allowRulesFor().map((rule) => valueBinding(`mcp-allow-rule:${rule}`, rule, `\`${rule}\``, [MCP_DOC, UNINSTALL_DOC])),
+  // The spec-adoption state tokens: status.md renders a plain phrase per token, so the doc must name
+  // every token the survey can answer — a fifth state added to the leaf with no phrase fails here.
+  // The decline lane rides both the status line and the advisor item, so both docs name it.
+  ...ADOPTION_STATES.map((state) => valueBinding(`spec-adoption:${state}`, state, `\`${state}\``, [STATUS_DOC])),
+  valueBinding('spec-adoption-lane', SPEC_ADOPTION_LANE, `--lane ${SPEC_ADOPTION_LANE}`, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────

package/tools/ensure-ops.mjs

@@ -16,8 +16,8 @@
 //   • The DECISION lives where it already lived. The orchestration `_README` refresh asks
 //     orchestration-config.mjs (refreshReadme / the known-prior canonical set) and writes through
 //     orchestration-write.mjs — the file's one writer. Nothing here re-derives either.
-//   • Every token names a state this run PROVED. `already-present` follows a probe; `skipped-no-node`
-//     names the missing package.json; an ADR-layout read that fails is `adr-layout-unverifiable` and
+//   • Every token names a state this run PROVED. `already-present` follows a probe; `skipped-no-node-evidence`
+//     names every Node probe that answered absent; an ADR-layout read that fails is `adr-layout-unverifiable` and
 //     writes NOTHING (the STRICT survey, fail-closed — the lenient status wrapper reads an unreadable
 //     tree as `none`, which here would mean seeding a rotator beside a store nobody could inspect).
 //   • A failed op is a non-zero signal, never a line that reads like success.
@@ -34,6 +34,7 @@ import { GATES_REL } from './gates-declaration.mjs';
 import { AUTONOMY_REL } from './autonomy-config.mjs';
 import { surveyAdrLayoutStrict } from './family-registry.mjs';
 import { ENSURE_TOKENS, FAILURE_CAUSES, SEED_SCRIPTS } from './ensure-vocabulary.mjs';
+import { NODE_EVIDENCE, describeNodeProbes, probeNodeEvidence } from './node-evidence.mjs';
 
 // The closed vocabulary lives in its own PURE leaf so the read-only doc-parity lint can bind the
 // relayed token set without importing this module's writer graph. Re-exported here because every
@@ -49,7 +50,6 @@ export {
   WRITE_TOKENS,
 } from './ensure-vocabulary.mjs';
 
-const PACKAGE_JSON = 'package.json';
 const SCRIPTS_DIR = 'scripts';
 
 const outcome = (op, token, lines, failed = false) => {
@@ -204,9 +204,19 @@ export const ensureAutonomy = ({ cwd, kitRoot, dryRun = false, deps = {} }) =>
 
 // ── 4. scripts/ — the ADR-cascade enforcement pairs, detect-first ──────────────────────────────────
 
-// A project with no package.json at its root is not where Node enforcement scripts belong. Stated,
-// never silent: the token names the evidence, and the three config ensures still run.
-export const isNodeProject = (cwd, lstat) => lstatNoFollow(join(cwd, PACKAGE_JSON), lstat) !== null;
+// The Node-evidence refusal every ensure that places Node scripts shares (contract: kit/node-evidence):
+// null when Node provably runs here, else the ONE outcome the caller returns — a stated skip naming the
+// probes that answered absent, or a fail-closed failure when a probe could not be read.
+export const nodeEvidenceRefusal = (op, cwd, lstat) => {
+  const evidence = probeNodeEvidence(cwd, lstat);
+  if (evidence.state === NODE_EVIDENCE.UNREADABLE) {
+    return loud(op, 'node-evidence-unverifiable', `${SCRIPTS_DIR}/: whether Node runs here could not be read (${evidence.error}), so nothing was written — resolve it by hand, then re-run`);
+  }
+  if (evidence.state === NODE_EVIDENCE.NONE) {
+    return ok(op, 'skipped-no-node-evidence', `${SCRIPTS_DIR}/: no Node evidence in this tree — probed ${describeNodeProbes(evidence)}, no regular file present; the seeded pairs are Node enforcement, so nothing written`);
+  }
+  return null;
+};
 
 const OLD_ADR_LAYOUTS = new Set(['old', 'old-unrotated']);
 
@@ -221,9 +231,8 @@ const partialNote = (lines) => {
 export const ensureScripts = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   const lstat = deps.lstat ?? lstatSync;
   const read = deps.readFile ?? readFileSync;
-  if (!isNodeProject(cwd, lstat)) {
-    return ok('scripts', 'skipped-no-node', `${SCRIPTS_DIR}/: no ${PACKAGE_JSON} at the project root — the seeded pairs are Node enforcement; nothing written`);
-  }
+  const refusal = nodeEvidenceRefusal('scripts', cwd, lstat);
+  if (refusal) return refusal;
   let layout;
   try {
     layout = surveyAdrLayoutStrict(cwd, deps);

package/tools/ensure-specs.mjs

@@ -26,7 +26,7 @@ import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { writeContainedFileAtomic, writeProjectFileCreateOnly } from './atomic-write.mjs';
 import { classifyDeployedScript } from './script-priors.mjs';
-import { composeFailure, composeOutcome, isNodeProject, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
+import { composeFailure, composeOutcome, nodeEvidenceRefusal, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
 
 const OP = 'specs';
 const SCRIPTS_DIR = 'scripts';
@@ -159,9 +159,8 @@ const renderStoreRoot = (kitRoot, read, today) => {
 export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   const lstat = deps.lstat ?? lstatSync;
   const read = deps.readFile ?? readFileSync;
-  if (!isNodeProject(cwd, lstat)) {
-    return ok('skipped-no-node', [`${SCRIPTS_DIR}/: no package.json at the project root — the spec reader and checker are Node scripts; nothing written`]);
-  }
+  const refusal = nodeEvidenceRefusal(OP, cwd, lstat);
+  if (refusal) return refusal;
   const survey = (name) => surveyScript({ cwd, kitRoot, name, read, lstat });
   const reader = READER_PAIR.map(survey);
   const checker = CHECKER_PAIR.map(survey);

package/tools/ensure-vocabulary.mjs

@@ -31,7 +31,7 @@ export const ENSURE_TOKENS = Object.freeze([
   'already-present',
   'customized-preserved',
   'malformed-preserved',
-  'skipped-no-node',
+  'skipped-no-node-evidence',
   'old-adr-layout-migration-instructed',
   'failed',
 ]);
@@ -44,6 +44,9 @@ export const FAILURE_CAUSES = Object.freeze([
   'template-unreadable',
   'bundle-unreadable',
   'adr-layout-unverifiable',
+  // A Node probe (package.json, a kit-seeded script) failed with anything but ENOENT: whether Node runs
+  // here is unproven, so the ensures that place Node scripts write nothing (contract: kit/node-evidence).
+  'node-evidence-unverifiable',
   'wrong-node-kind',
   'write-refused',
   'unexpected-error',
@@ -75,7 +78,7 @@ export const RELAYED_ENSURE_TOKENS = Object.freeze([
   'customized-preserved',
   'malformed-preserved',
   'already-present',
-  'skipped-no-node',
+  'skipped-no-node-evidence',
   'old-adr-layout-migration-instructed',
   'failed',
 ]);

package/tools/family-registry.mjs

@@ -82,6 +82,8 @@ import {
 import { detectSurface } from './surface.mjs';
 import { toViewModel } from './view-model.mjs';
 import { render } from './renderers.mjs';
+// The feature-spec adoption state (contract: kit/spec-adoption) — read-only leaves, no cycle.
+import { ADOPTION, readDeclineAck, surveySpecAdoption } from './spec-adoption.mjs';
 
 // ── manifestState values — re-export the EXACT public subset family-registry exported before B1 ─────
 // (the 7 state constants + DISPLAY_NAMES) so every existing importer (uninstall.mjs, the test suites)
@@ -428,9 +430,33 @@ const surveyAdrLayout = (dir, deps) => {
   }
 };
 
+// The spec-adoption survey, LENIENT for the read-only view — two facts, each failing on its own: a
+// survey that throws becomes the `unreadable` state with its reason, and an ack read that throws
+// keeps the store state and carries `declineError` beside `declined: false` — the status line still
+// renders, never a crash, never a silent "not adopted" and never a decline it could not read.
+const surveySpecs = (dir, deps) => {
+  const survey = (() => {
+    try {
+      return surveySpecAdoption(dir, deps);
+    } catch (err) {
+      return { state: ADOPTION.UNREADABLE, live: 0, draft: 0, reason: localizeError(err) };
+    }
+  })();
+  const decline = (() => {
+    if (survey.state === ADOPTION.ADOPTED) return { declined: false, declineError: null };
+    try {
+      return { declined: readDeclineAck(dir, deps), declineError: null };
+    } catch (err) {
+      return { declined: false, declineError: localizeError(err) };
+    }
+  })();
+  return { state: survey.state, live: survey.live, draft: survey.draft, reason: survey.reason, ...decline };
+};
+
 // surveyProject → the deploy axis for a target project dir: the per-member deployment stamps, whether
-// docs/ai/ exists, the ADR-store layout, and whether the hidden-mode fence is present. Pure (fs reads
-// only, all injectable), no git subprocess — the read-only `status` view must never mutate or spawn.
+// docs/ai/ exists, the ADR-store layout, the spec-adoption state, and whether the hidden-mode fence is
+// present. Pure (fs reads only, all injectable), no git subprocess — the read-only `status` view must
+// never mutate or spawn.
 export const surveyProject = (projectDir, deps = {}) => {
   const exists = deps.exists ?? existsSync;
   const dir = resolve(projectDir);
@@ -445,7 +471,7 @@ export const surveyProject = (projectDir, deps = {}) => {
     }
   })();
   const deployed = stamps.some((s) => s.version != null) || docsAiPresent;
-  return { dir, deployed, docsAiPresent, adrLayout: surveyAdrLayout(dir, deps), hiddenFence: hasHiddenFence(dir, deps), stamps };
+  return { dir, deployed, docsAiPresent, adrLayout: surveyAdrLayout(dir, deps), specs: surveySpecs(dir, deps), hiddenFence: hasHiddenFence(dir, deps), stamps };
 };
 
 // ── report ───────────────────────────────────────────────────────────────────────
@@ -683,6 +709,9 @@ export const buildEnvelope = (family, project = null, extras = {}) => {
       deployed: project.deployed,
       docsAi: project.docsAiPresent,
       adrLayout: project.adrLayout, // 'old' | 'old-unrotated' | 'migrated' | 'none' — a user-safe token, never a raw path
+      // { state: not-adopted | adopting | adopted | unreadable, live, draft, reason, declined, declineError }
+      // — an envelope predating the field omits it (the view-model reads that as unknown, never as a state).
+      ...(project.specs ? { specs: project.specs } : {}),
       // member + display + version only — never the internal stamp FILENAME (s.file).
       deployStamps: project.stamps.map((s) => ({ member: s.name, display: displayOf(s.name), version: s.version ?? null })),
     };

package/tools/lens-region.mjs

@@ -62,7 +62,10 @@ Apply this as part of §2 before any user-facing summary:
 - **No condescension, no filler.** Own a miss plainly and fix it in the same message.
 - **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.
 - **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.`;
-export const COMMS_PRIORS = [COMMS_PRIOR_PRE_AD054, COMMS_PRIOR_AD054, COMMS_PRIOR_PLAIN_LANGUAGE];
+// The canon that shipped between the closing-state-block contract and the contradicted-skip bullet.
+const COMMS_PRIOR_STATE_BLOCK = `${COMMS_PRIOR_PLAIN_LANGUAGE}
+- **The closing state block answers three DIFFERENT questions.** Close a user-facing message with three labelled slots — *now* · *what I need from you* · *what's next*. The slot LABELS stay ENGLISH — an English label is what lets a state-block checker FIND the block and its slots at all; everything written INTO a slot is in the project's dialogue language; when that language is not English, the checker's English phrase sets do not judge those values. **Now** = the state at this instant: what is RUNNING, or what the work is stopped on. It is **never a report of finished work** — what you completed goes in the message BODY, above the block. **From you** = the real unblocker, named; a turn that is ENDING always has one. **Next** = what follows. A *now* slot that opens with what was completed buries the one fact the reader opened the message for, and the three slots collapse into one restatement.`;
+export const COMMS_PRIORS = [COMMS_PRIOR_PRE_AD054, COMMS_PRIOR_AD054, COMMS_PRIOR_PLAIN_LANGUAGE, COMMS_PRIOR_STATE_BLOCK];
 
 const stripCr = (line) => (line.endsWith('\r') ? line.slice(0, -1) : line);
 const isBoundary = (bareLine) => bareLine === '---' || /^#{2,3} /.test(bareLine);

package/tools/node-evidence.mjs

@@ -0,0 +1,77 @@
+// node-evidence.mjs — does Node PROVABLY run in this project tree? Contract: docs/ai/specs/kit/node-evidence.md.
+// Pure over an injectable lstat; no writes, no side effects on import. Dependency-free, Node >= 22.
+
+import { lstatSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const NODE_EVIDENCE = Object.freeze({
+  PACKAGE_JSON: 'package-json',
+  DEPLOYED_SCRIPTS: 'deployed-node-scripts',
+  NONE: 'none',
+  UNREADABLE: 'unreadable',
+});
+
+export const PACKAGE_JSON_REL = 'package.json';
+export const SCRIPTS_DIR = 'scripts';
+
+// The runnable scripts the bootstrap copies from references/scripts/ — pinned against the bundle by the suite.
+export const NODE_EVIDENCE_SCRIPTS = Object.freeze([
+  'archive-caps.mjs',
+  'archive-changelog.mjs',
+  'archive-decisions.mjs',
+  'archive-issues.mjs',
+  'check-docs-size.mjs',
+  'install-git-hooks.mjs',
+  'markdown-blocks.mjs',
+  'migrate-gates.mjs',
+  'spec-schema.mjs',
+]);
+
+export const NODE_EVIDENCE_PROBES = Object.freeze([PACKAGE_JSON_REL, ...NODE_EVIDENCE_SCRIPTS.map((name) => `${SCRIPTS_DIR}/${name}`)]);
+
+const ENOENT = 'ENOENT';
+const kindOf = (st) => (st.isSymbolicLink() ? 'a symlink' : st.isDirectory() ? 'a directory' : st.isFile() ? 'a regular file' : 'not a regular file');
+
+const answer = (state, evidence, wrongKind, extra = {}) =>
+  Object.freeze({ state, evidence, probed: NODE_EVIDENCE_PROBES, wrongKind: Object.freeze(wrongKind), ...extra });
+
+// probeNodeEvidence(cwd, lstat) -> { state, evidence, probed, wrongKind, error? }: the first regular file
+// among the probes answers; a probe failing with anything but ENOENT answers unreadable at once; a path of
+// the wrong node kind is not evidence — it is recorded in `wrongKind` and the walk continues. lstat does
+// not follow the LEAF but walks THROUGH a symlinked scripts/, whose files are not this tree's — so the
+// directory is proven plain before any script inside it counts.
+export const probeNodeEvidence = (cwd, lstat = lstatSync) => {
+  const wrongKind = [];
+  const probeKind = (rel, wanted) => {
+    let st;
+    try {
+      st = lstat(join(cwd, rel));
+    } catch (err) {
+      if (err && err.code === ENOENT) return 'absent';
+      throw Object.assign(err, { probedRel: rel });
+    }
+    if (wanted === 'dir' ? st.isDirectory() && !st.isSymbolicLink() : st.isFile()) return wanted;
+    wrongKind.push(`${rel} is ${kindOf(st)}`);
+    return 'wrong-kind';
+  };
+  try {
+    if (probeKind(PACKAGE_JSON_REL, 'file') === 'file') return answer(NODE_EVIDENCE.PACKAGE_JSON, PACKAGE_JSON_REL, wrongKind);
+    if (probeKind(SCRIPTS_DIR, 'dir') === 'dir') {
+      for (const rel of NODE_EVIDENCE_PROBES.slice(1)) {
+        if (probeKind(rel, 'file') === 'file') return answer(NODE_EVIDENCE.DEPLOYED_SCRIPTS, rel, wrongKind);
+      }
+    }
+  } catch (err) {
+    return answer(NODE_EVIDENCE.UNREADABLE, null, wrongKind, { error: `${err.code || err.message || 'lstat failed'} on ${err.probedRel}` });
+  }
+  return answer(NODE_EVIDENCE.NONE, null, wrongKind);
+};
+
+export const hasNodeEvidence = (probe) => probe.state === NODE_EVIDENCE.PACKAGE_JSON || probe.state === NODE_EVIDENCE.DEPLOYED_SCRIPTS;
+
+// The sentence a skip line carries: every probe checked, and what of the wrong kind sat at any of them.
+export const describeNodeProbes = (probe = null) => {
+  const probes = `${PACKAGE_JSON_REL} and the kit-seeded ${SCRIPTS_DIR}/ files (${NODE_EVIDENCE_SCRIPTS.join(', ')})`;
+  const wrong = probe?.wrongKind?.length ? ` — not evidence: ${probe.wrongKind.join('; ')}` : '';
+  return `${probes}${wrong}`;
+};

package/tools/recommendations.mjs

@@ -32,7 +32,6 @@
 // idiom).
 
 import { readFileSync, readdirSync, lstatSync, existsSync } from 'node:fs';
-import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -84,6 +83,25 @@ import { DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
 import { loadWorktreesConfig, resolveProbeDir } from './worktrees.mjs';
 import { preflightCheapAgents } from './cheap-agents.mjs';
+// The ack store's path, keys, lane registry, fingerprint and guarded reader live in their own leaf
+// (contract: kit/ack-store) — `status` reads the same store, and a second copy is what drifts.
+import {
+  ACKS_FILE,
+  ACKS_LANE_KEY,
+  ACKS_WORKTREES_DIR_KEY,
+  ACKS_COVERAGE_DOMAIN_KEY,
+  ACKS_SOURCE_SIZE_COPY_KEY,
+  ACK_LANES,
+  factFingerprint,
+  readAckValue,
+} from './ack-store.mjs';
+import { ADOPTION, STORE_DIR_REL as SPEC_STORE_DIR_REL, SPEC_ADOPTION_LANE, declineFingerprint, readDeclineAck, surveySpecAdoption } from './spec-adoption.mjs';
+import { ENSURE_OPS } from './ensure-vocabulary.mjs';
+
+// The upgrade ensure that seeds the spec store — the not-adopted item's apply; pinned to the vocabulary.
+const SPEC_LAYER_ENSURE = ENSURE_OPS.includes('specs') ? 'specs' : null;
+
+export { ACKS_FILE, ACKS_LANE_KEY, ACKS_WORKTREES_DIR_KEY, ACKS_COVERAGE_DOMAIN_KEY, ACKS_SOURCE_SIZE_COPY_KEY, ACK_LANES, factFingerprint };
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const toolPath = (rel) => join(HERE, rel);
@@ -163,6 +181,11 @@ export const SEVERITIES = Object.freeze({
   'sandbox-masks': SEVERITY_OPTIONAL,
   'sandbox-lane': SEVERITY_OPTIONAL,
   'worktrees-dir': SEVERITY_OPTIONAL,
+  // The layer is opt-in, so both arms are OFFERS under the frozen registry (attention is a CONFIGURED
+  // declaration that is broken): an absent store offers the seed, a store with no live contract offers
+  // the decline. Neither arm can leave the flow-optimal line standing — an offer is still an item.
+  'spec-adoption': SEVERITY_OPTIONAL,
+  'spec-adoption.adopting': SEVERITY_OPTIONAL,
 });
 // The per-item render tags (frozen presentation data, same language contract as the templates).
 export const SEVERITY_LABELS = Object.freeze({
@@ -234,6 +257,8 @@ export const WHATS = Object.freeze({
   'sandbox-masks.stale-real': '{n} sandbox device mask(s) clutter git status — the exclude block is stale; {m} fenced entr(ies) are REAL paths (a fresh apply drops them)',
   'sandbox-lane': 'the wired review wrappers declare a session-sandbox recipe (egress hosts + writable state dirs) not yet acknowledged for this project',
   'worktrees-dir': 'write access to the worktrees parent dir {dir} is not confirmed — provision may still stop',
+  'spec-adoption': 'feature-spec store absent (docs/ai/specs) — no feature contract can govern a plan here yet; seed the store, or record the decline',
+  'spec-adoption.adopting': 'feature-spec store: {n} draft spec(s), no live contract — nothing governs a plan through it yet; land a live contract, or record the decline',
 });
 
 // ── the shape contract (D2): registry strings AND composed items stay one line under the cap ────
@@ -290,6 +315,7 @@ export const BENEFITS = Object.freeze({
   'sandbox-masks': 'zero clutter — git status shows only your changes (the review domain already ignores the masks by construction)',
   'sandbox-lane': 'discoverability — the manifest-declared observed sandbox recipe for bridge runs surfaces itself instead of waiting to be asked',
   'worktrees-dir': 'parallel features — the host-specific write allowance or terminal fallback is surfaced before provision',
+  'spec-adoption': 'contracts — a plan names the contract it builds to, and a change to a governed slice is visible at review instead of after it',
 });
 
 // ── the CLOSED opt-in capability registry (OPT-IN-SHIPS-INVISIBLE) ──────────────────────────────
@@ -332,6 +358,9 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   { id: 'mcp-channel', mode: 'mcp', advisorKey: 'mcp-channel' },
   { id: 'worktrees-dir', mode: 'worktrees', advisorKey: 'worktrees-dir' },
   { id: 'family-freshness', mode: 'upgrade', advisorKey: 'family-freshness' },
+  // The feature-spec layer is delivered by upgrade's spec-layer ensure (there is no specs mode), so
+  // its adoption state is declared where the store is seeded.
+  { id: 'spec-adoption', mode: 'upgrade', advisorKey: 'spec-adoption' },
   { id: 'adr-store-migration', mode: 'migrate-adr-store', advisorKey: 'adr-store-migration' },
   { id: 'review-recipe', mode: 'set-recipe', advisorKey: 'review-recipe' },
   // The execute slot is a DISTINCT opt-in from the review slot, and the same probe reports both —
@@ -1042,41 +1071,13 @@ export const recipeFingerprint = ({ hosts, dirs, home }) => {
     if (abs === homeAbs) return '~';
     return abs.startsWith(`${homeAbs}/`) ? `~/${abs.slice(homeAbs.length + 1)}` : abs;
   };
-  const canonical = JSON.stringify({ hosts: [...hosts].sort(), dirs: [...new Set(dirs.map(norm))].sort() });
-  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+  return factFingerprint(JSON.stringify({ hosts: [...hosts].sort(), dirs: [...new Set(dirs.map(norm))].sort() }));
 };
 
-// The fingerprint for an acknowledgment whose subject is already a canonical STRING — the census
-// fact, the sorted set of declared tool-elsewhere claims — rather than a hosts ∪ dirs recipe. Same
-// 16-hex shape the ack writer validates, so every lane records one comparable token; the canonical
-// form is the caller's, because only the caller knows which part of its fact is durable and which
-// is churn (the census binds the verdict + extension set, never per-file counts).
-export const factFingerprint = (fact) => createHash('sha256').update(fact).digest('hex').slice(0, 16);
-
-// The kit-owned neutral ack store (D4; AD-055 Part I): a FAMILY-OWNED strict-JSON file no host
-// validator guards — top-level key `sandboxLaneAck` (+ optional `_README`), unknown keys tolerated
-// on read (future acks are siblings). This is the PRIMARY ack channel; the legacy settings-scope
-// keys below are read for one deprecation window. The sandbox/permissions security keys are NEVER
-// consulted as an ack.
-export const ACKS_FILE = 'docs/ai/acks.json';
-export const ACKS_LANE_KEY = 'sandboxLaneAck';
-export const ACKS_WORKTREES_DIR_KEY = 'worktreesDirAck';
-export const ACKS_COVERAGE_DOMAIN_KEY = 'coverageDomainAck';
-export const ACKS_SOURCE_SIZE_COPY_KEY = 'sourceSizeCopyAck';
-// The CLOSED-WORLD ack-lane registry: the lane name an advisor item renders on the writer's
-// command line → the store key that writer sets. A lane the registry does not name is a usage
-// refusal at the writer, never a newly-invented key in the shared store.
-//
-// An ack lane exists for a state the maintainer can only ANSWER, never converge: a tracked tree the
-// coverage domain cannot reach, a checker deliberately vendored elsewhere. It is deliberately NOT
-// available to a state that is simply BROKEN — a dead checker/producer pair is fixed, not
-// acknowledged, so no lane names it.
-export const ACK_LANES = Object.freeze({
-  'sandbox-lane': ACKS_LANE_KEY,
-  'worktrees-dir': ACKS_WORKTREES_DIR_KEY,
-  'coverage-domain': ACKS_COVERAGE_DOMAIN_KEY,
-  'source-size-copy': ACKS_SOURCE_SIZE_COPY_KEY,
-});
+// The ack store (D4; AD-055 Part I) is the kit-owned PRIMARY ack channel; the legacy settings-scope
+// keys below are read for one deprecation window. An ack lane exists for a state the maintainer can
+// only ANSWER, never converge — a dead checker/producer pair is fixed, not acknowledged, so no lane
+// names it. The store's path, keys, lane registry and reader are ack-store.mjs (re-exported above).
 
 // The opt-in read-lane toggle file (AD-055 Part II) — the SAME kit-owned docs/ai/lanes.json the
 // placed hook reads live. The read-lane item offers to enable it once the hook is placed+wired.
@@ -1146,38 +1147,6 @@ const declarationCarriesMarker = (root, deps) => {
 export const SANDBOX_LANE_ACK_PARENT = 'agentWorkflow';
 export const SANDBOX_LANE_ACK_KEY = 'sandboxLaneAck';
 
-// Read the family-owned ack store. An ABSENT file (or absent docs/ai) is the NORMAL not-yet-acked
-// state → null (plain fall-through, never a skip). A parse/IO error on an EXISTING file THROWS — the
-// probe's catch turns it into a stated skip line (Decisions 2). A non-object root is a malformed
-// store (fail-closed skip); a non-string value at the key is tolerated → null (the item re-fires).
-// The WHOLE path chain (root / docs / ai / acks.json) is guarded WITHOUT following symlinks
-// BEFORE any read: a symlinked ANCESTOR could otherwise read an ack from OUTSIDE the project (the
-// writer refuses such a deployment — the reader must too), a symlinked/dangling LEAF must not read as
-// not-yet-acked, and a non-regular target (FIFO/dir/device) is a fail-closed SKIP — never read it (a
-// FIFO would BLOCK the advisor). ENOENT-safe: an absent file/dir is the NORMAL not-yet-acked null.
-const readAckValue = (root, deps, ackKey) => {
-  const readFile = deps.readFile ?? readFileSync;
-  const lstat = deps.lstat ?? lstatSync;
-  const absPath = join(root, ACKS_FILE);
-  let st;
-  try {
-    assertContainedRealPath(root, absPath, { lstat }); // symlinked root/ancestor/leaf or escape → throws
-    st = lstat(absPath);
-  } catch (err) {
-    if (err?.code === 'ENOENT') return null; // genuinely absent (file or docs/ai) — normal not-yet-acked
-    throw err; // a symlinked ancestor/leaf, an escape, or a real IO error — stated skip
-  }
-  if (!st.isFile()) {
-    throw new Error(`${ACKS_FILE} is not a regular file — refusing to read it`);
-  }
-  const parsed = JSON.parse(readFile(absPath, 'utf8'));
-  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error(`${ACKS_FILE}: expected a JSON object`);
-  }
-  const value = parsed[ackKey];
-  return typeof value === 'string' ? value : null;
-};
-
 // Read the opt-in read-lane toggle for the read-lane item. An ABSENT file (or absent docs/ai) →
 // false (the lane is off — offer it). `readLane === true` → enabled (converged). A parse/IO error on
 // an EXISTING file, a symlinked ancestor/leaf, an escape, or a non-object root THROWS — the probe
@@ -1208,7 +1177,38 @@ const readReadLaneToggle = (root, deps) => {
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel']);
+export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel', 'spec-adoption']);
+
+// The feature-spec layer's adoption state (contract: kit/spec-adoption). The canon lets a plan cite
+// zero governing specs while a project adopts the layer, and nothing ever said whether adoption had
+// started — an owner found the store absent only by asking. The survey reads the store through
+// spec-check's own census; a recorded decline (the `spec-adoption` ack lane) is the fact that
+// silences the item, and an unreadable store is a stated skip so the flow-optimal line never renders
+// over it. The not-adopted apply is the spec-layer ensure; the decline preview rides the recipe line.
+export const probeSpecAdoption = ({ root, deps, add, skip }) => {
+  try {
+    const survey = surveySpecAdoption(root, deps);
+    if (survey.state === ADOPTION.UNREADABLE) {
+      skip('spec-adoption', new Error(`${survey.reason} — the adoption state under ${SPEC_STORE_DIR_REL} cannot be judged`));
+      return;
+    }
+    if (survey.state === ADOPTION.ADOPTED || readDeclineAck(root, deps)) return;
+    const decline = `node ${q(toolPath('ack-write.mjs'))} --lane ${SPEC_ADOPTION_LANE} --fingerprint ${declineFingerprint()} --cwd ${q(root)}`;
+    if (survey.state === ADOPTION.NOT_ADOPTED) {
+      add(
+        'spec-adoption',
+        fillTemplate(WHATS['spec-adoption'], {}),
+        `node ${q(toolPath('ensure-configs.mjs'))} --reconcile --only ${SPEC_LAYER_ENSURE} --cwd ${q(root)}`,
+        'spec-adoption',
+        `HAND-APPLY alternative (instead of the apply, never after it): decline the layer by recording it — ${decline}`,
+      );
+      return;
+    }
+    add('spec-adoption', fillTemplate(WHATS['spec-adoption.adopting'], { n: survey.draft }), decline, 'spec-adoption.adopting');
+  } catch (err) {
+    skip('spec-adoption', err);
+  }
+};
 
 const probeSandboxLane = ({ root, deps, add, skip }) => {
   try {
@@ -1491,6 +1491,7 @@ const PROBES = Object.freeze([
   probeSandboxLane,
   probeWorktreesDir,
   probeMcpChannel,
+  probeSpecAdoption,
 ]);
 
 export const buildRecommendations = ({ cwd, deps = {} } = {}) => {

package/tools/renderers.mjs

@@ -8,6 +8,7 @@
 // Pure, no side effects, Node >= 22.
 
 import { BLOCK_TITLES, SETTINGS_LABELS, glyphsFor, NO_DEPLOYMENT } from './presentation.mjs';
+import { describeAdoption } from './spec-adoption.mjs';
 
 const MEMBER_COL = 20;
 const VERSION_COL = 12;
@@ -96,6 +97,14 @@ const renderProject = (vm, { color }) => {
   if (ACTIONABLE_ADR_LAYOUTS.includes(p.adrLayout)) {
     lines.push(`  ${pad('ADR store', STAMP_COL)}old layout — run /agent-workflow-kit migrate-adr-store`);
   }
+  // Every state renders — an owner opens this surface deliberately, so "not adopted" is the one line
+  // that must never be missing; an envelope without the field says so rather than inventing a state.
+  if (p.specs) {
+    const declineNote = p.specs.declineError ? ` (decline ack unreadable: ${p.specs.declineError})` : '';
+    lines.push(`  ${pad('specs', STAMP_COL)}${describeAdoption(p.specs, { declined: p.specs.declined })}${declineNote}`);
+  } else {
+    lines.push(`  ${pad('specs', STAMP_COL)}unknown — the installed kit predates the adoption state`);
+  }
   if (p.visibility) {
     const v = p.visibility.error ? `error: ${p.visibility.error}` : p.visibility.phrase;
     lines.push(`  ${pad('visibility', STAMP_COL)}${v}`);