@sabaiway/agent-workflow-kit 1.47.0 → 1.48.0

package/tools/ack-write.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// ack-write.mjs — the consent-gated writer for the family-owned neutral ack store
+// (docs/ai/acks.json, AD-055 Part I). The upgrade Recommendations `sandbox-lane` item renders THIS
+// tool's PREVIEW one-liner; the preview prints the exact `--apply` command; the agent runs `--apply`
+// only after the mode doc's §3 informed-consent confirmation. It records a NEUTRAL recipe fingerprint
+// acknowledgement — never a security key; the kit never writes sandbox network/filesystem allowances.
+//
+// Family writer discipline (velocity / orchestration-write / gate-hook), verbatim:
+//   • preview-then-mutate — `--dry-run` is the DEFAULT and writes nothing; `--apply` writes;
+//   • deployment-gated — REFUSES an absent docs/ai with a named recovery pointer (run init/bootstrap);
+//   • creates docs/ai/acks.json (and nothing else) if absent;
+//   • merge-preserve — every existing key (a hand-authored `_README`, future sibling acks) is kept;
+//     only the `sandboxLaneAck` key is set;
+//   • symlink / non-regular target → STOP (never write through a link or clobber a device/dir);
+//   • fail-closed on malformed existing JSON (never overwrite an unparseable store);
+//   • atomic — exclusive-create *.tmp + rename (no partial-write state); last-writer-wins;
+//   • never commits.
+//
+// Dependency-free beyond the kit's own atomic-write core + the shared ack constants, Node >= 18. No
+// side effects on import (the isDirectRun idiom).
+
+import { lstatSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ACKS_FILE, ACKS_LANE_KEY } from './recommendations.mjs';
+import { assertDocsAiDeployment, writeDocsAiFileAtomic, lstatNoFollow } from './atomic-write.mjs';
+import { shellQuoteArg } from './review-state.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const ACK_WRITE_TOOL = join(HERE, 'ack-write.mjs');
+
+const ERROR_PREFIX = '[agent-workflow-kit]';
+const EXIT_OK = 0;
+const EXIT_PRECONDITION = 1;
+const EXIT_USAGE = 2;
+const JSON_INDENT = 2;
+// The recipeFingerprint shape (recommendations.mjs: sha256 hex sliced to 16) — a fail-closed guard so
+// the store never records a malformed or injected value.
+export const FINGERPRINT_PATTERN = /^[0-9a-f]{16}$/u;
+
+export const ACK_WRITE_STOP = 'ACK_WRITE_STOP';
+export const stop = (message) =>
+  Object.assign(new Error(`${ERROR_PREFIX} ${message}`), { name: 'AckWriteStop', code: ACK_WRITE_STOP, exitCode: EXIT_PRECONDITION });
+const usageFail = (message) => Object.assign(new Error(message), { exitCode: EXIT_USAGE });
+
+const q = shellQuoteArg;
+
+// Read + parse the existing store (already known to be a regular file). ENOENT (a TOCTOU vanish) is
+// treated as absent; malformed JSON / a non-object root FAILS CLOSED — never overwrite an unparseable
+// store.
+const readExistingStore = (absPath, deps) => {
+  const readFile = deps.readFile ?? readFileSync;
+  let text;
+  try {
+    text = readFile(absPath, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return {};
+    throw stop(`cannot read ${ACKS_FILE} (${err?.code ?? err?.message}) — refusing to overwrite it`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw stop(`${ACKS_FILE} is not valid JSON — refusing to overwrite it (fix or delete it, then re-run)`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw stop(`${ACKS_FILE} is not a JSON object — refusing to overwrite it`);
+  }
+  return parsed;
+};
+
+// Target gate: a symlinked / non-regular acks.json is a STOP (checked BEFORE any read so a FIFO can
+// never block the reader). Returns { existed, existing } — the merge base.
+const preflightTarget = (absPath, deps) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const st = lstatNoFollow(absPath, lstat);
+  if (st === null) return { existed: false, existing: {} };
+  if (st.isSymbolicLink()) throw stop(`${ACKS_FILE} is a symlink — refusing to write through it`);
+  if (!st.isFile()) throw stop(`${ACKS_FILE} exists but is not a regular file — refusing to touch it`);
+  return { existed: true, existing: readExistingStore(absPath, deps) };
+};
+
+// Pure preflight (both dry-run and apply). Validates the fingerprint, refuses an absent deployment,
+// gates the target, and computes the merge — no writes.
+export const planAckWrite = ({ cwd, fingerprint }, deps = {}) => {
+  // typeof BEFORE RegExp.test — .test() coerces its arg to a string, so a number or a single-element
+  // array of 16 hex chars would otherwise pass the guard and be written as a non-string ack the
+  // reader then ignores.
+  if (typeof fingerprint !== 'string' || !FINGERPRINT_PATTERN.test(fingerprint)) {
+    throw usageFail(`--fingerprint must be a 16-char lowercase hex fingerprint (got ${JSON.stringify(fingerprint ?? null)})`);
+  }
+  const root = resolve(cwd);
+  assertDocsAiDeployment(root, deps, { stop, noun: 'the neutral sandbox-lane ack', rel: ACKS_FILE });
+  const absPath = join(root, ACKS_FILE);
+  const { existed, existing } = preflightTarget(absPath, deps);
+  const alreadyAcked = existing[ACKS_LANE_KEY] === fingerprint;
+  const merged = { ...existing, [ACKS_LANE_KEY]: fingerprint };
+  const otherKeys = Object.keys(existing).filter((k) => k !== ACKS_LANE_KEY);
+  return { root, absPath, fingerprint, existed, existing, merged, alreadyAcked, otherKeys };
+};
+
+export const writeAck = ({ cwd, fingerprint, dryRun = true } = {}, deps = {}) => {
+  const plan = planAckWrite({ cwd, fingerprint }, deps);
+  if (dryRun) return { wrote: false, dryRun: true, ...plan };
+  const body = `${JSON.stringify(plan.merged, null, JSON_INDENT)}\n`;
+  writeDocsAiFileAtomic(plan.root, ACKS_FILE, body, deps, { stop, noun: 'the neutral sandbox-lane ack' });
+  return { wrote: true, dryRun: false, ...plan };
+};
+
+// ── report ──────────────────────────────────────────────────────────────────────────────
+export const applyCommand = (root, fingerprint) =>
+  `node ${q(ACK_WRITE_TOOL)} --fingerprint ${fingerprint} --cwd ${q(root)} --apply`;
+
+export const formatResult = (result) => {
+  const merge = result.otherKeys.length > 0 ? ` (merge-preserving ${result.otherKeys.length} existing key(s))` : '';
+  if (result.dryRun) {
+    if (result.alreadyAcked) {
+      return [
+        `agent-workflow ack — DRY RUN: ${ACKS_FILE} already records this recipe fingerprint (${result.fingerprint}) — nothing to do.`,
+      ].join('\n');
+    }
+    return [
+      `agent-workflow ack — DRY RUN (no changes; re-run with --apply)`,
+      `  - would ${result.existed ? 'set' : 'create'} ${ACKS_FILE} "${ACKS_LANE_KEY}" = "${result.fingerprint}"${merge}`,
+      `  - this is a NEUTRAL recipe acknowledgement, never a security key.`,
+      `  to apply: ${applyCommand(result.root, result.fingerprint)}`,
+    ].join('\n');
+  }
+  return [
+    `agent-workflow ack — APPLY`,
+    `  - ${ACKS_FILE}: "${ACKS_LANE_KEY}" = "${result.fingerprint}"${merge}`,
+  ].join('\n');
+};
+
+// ── CLI ─────────────────────────────────────────────────────────────────────────────────
+const USAGE = `usage: ack-write --fingerprint <16-hex> [--dry-run | --apply] [--cwd <dir>] [--help]
+
+Records the NEUTRAL sandbox-lane recipe acknowledgement into ${ACKS_FILE} (the family-owned ack
+store — no host settings validator guards it). Default is --dry-run (a preview; writes nothing) and
+prints the exact --apply command. --apply merges "${ACKS_LANE_KEY}" into ${ACKS_FILE}, preserving
+every existing key. Refuses an absent docs/ai deployment; never a security key; never commits.`;
+
+export const parseArgs = (argv) => {
+  const opts = { fingerprint: undefined, dryRunFlag: false, apply: false, cwd: undefined, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--dry-run') opts.dryRunFlag = true;
+    else if (arg === '--apply') opts.apply = true;
+    else if (arg === '--fingerprint') {
+      i += 1;
+      if (argv[i] === undefined || argv[i].startsWith('-')) throw usageFail('--fingerprint needs a value');
+      opts.fingerprint = argv[i];
+    } else if (arg === '--cwd') {
+      i += 1;
+      if (argv[i] === undefined || argv[i].startsWith('-')) throw usageFail('--cwd needs a directory argument');
+      opts.cwd = argv[i];
+    } else {
+      throw usageFail(`unknown argument: ${arg}`);
+    }
+  }
+  if (opts.dryRunFlag && opts.apply) throw usageFail('--dry-run and --apply cannot be used together');
+  return { help: opts.help, fingerprint: opts.fingerprint, dryRun: !opts.apply, cwd: opts.cwd };
+};
+
+export const main = (argv = process.argv.slice(2), deps = {}) => {
+  const log = deps.log ?? console.log;
+  const errlog = deps.errlog ?? console.error;
+  try {
+    const args = parseArgs(argv);
+    if (args.help) {
+      log(USAGE);
+      return EXIT_OK;
+    }
+    const result = writeAck({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), fingerprint: args.fingerprint, dryRun: args.dryRun }, deps);
+    log(formatResult(result));
+    return EXIT_OK;
+  } catch (err) {
+    errlog(err?.message ?? String(err));
+    if (err?.exitCode === EXIT_USAGE) errlog(USAGE);
+    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/doc-parity.mjs

@@ -34,6 +34,7 @@ import {
   VERDICT_NOTHING_BROKEN,
   VERDICT_OPTIONAL_TEMPLATE,
   VERDICT_SKIPS_TEMPLATE,
+  ACKS_FILE,
 } from './recommendations.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -43,6 +44,7 @@ const FOLD_DOC = 'references/modes/fold-completeness.md';
 const AUTONOMY_DOCTOR_DOC = 'references/modes/autonomy-doctor.md';
 const RECOMMENDATIONS_DOC = 'references/modes/recommendations.md';
 const UPGRADE_DOC = 'references/modes/upgrade.md';
+const VELOCITY_DOC = 'references/modes/velocity.md';
 
 // A typed usage failure (exit 2) for the CLI parser — the codebase's typed-error idiom (no classes).
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
@@ -92,6 +94,11 @@ export const BINDINGS = Object.freeze([
   valueBinding('verdict-nothing-broken', VERDICT_NOTHING_BROKEN, VERDICT_NOTHING_BROKEN, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
   valueBinding('verdict-optional', VERDICT_OPTIONAL_TEMPLATE, VERDICT_OPTIONAL_TEMPLATE, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
   valueBinding('verdict-skips', VERDICT_SKIPS_TEMPLATE, VERDICT_SKIPS_TEMPLATE, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
+  // The ack-store apply target (AD-055 Part I): the family-owned docs/ai/acks.json path — a
+  // drift-guarded constant so the mode docs' ack-store references cannot silently outdate the code
+  // (the incident's "mode-doc apply text stays in lockstep" acceptance as a mechanism, not prose).
+  // Bound in BOTH docs that name the path (recommendations.md + velocity.md).
+  valueBinding('acks-file', ACKS_FILE, ACKS_FILE, [RECOMMENDATIONS_DOC, VELOCITY_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────

package/tools/gate-hook.mjs

@@ -31,8 +31,12 @@
 //     preserved-customization discipline — no refresh-in-place, no marker/checksum machinery);
 //   • never writes settings.local.json; never commits.
 //
+// The `--read-lane` flag is a SEPARATE operation (AD-055 Part II): it enables the opt-in read-only
+// compound lane in docs/ai/lanes.json after a currency check, and never touches settings or
+// gates.json — see the read-lane writer section below.
+//
 // Exit codes: 0 done / dry-run (incl. the report-only diverged-but-wired state); 1 precondition
-// STOP; 2 usage. Dependency-free beyond the kit's own velocity exports, Node >= 18. No side
+// STOP; 2 usage. Dependency-free beyond the kit's own internal exports, Node >= 18. No side
 // effects on import.
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -49,8 +53,13 @@ import {
   readSettingsFile,
   resolveEffectiveMode,
 } from './velocity-profile.mjs';
+import { assertDocsAiDeployment, writeDocsAiFileAtomic } from './atomic-write.mjs';
+import { shellQuoteArg } from './review-state.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
+// This tool's own absolute path — the recovery / apply one-liners the read-lane writer prints.
+export const GATE_HOOK_TOOL = fileURLToPath(import.meta.url);
+const q = shellQuoteArg;
 
 export const BUNDLED_HOOK_PATH = resolve(HERE, '..', 'references', 'hooks', 'gate-approve.mjs');
 export const HOOKS_DIR = '.claude/hooks';
@@ -68,6 +77,11 @@ export const GATE_HOOK_UNSAFE_MODE = 'GATE_HOOK_UNSAFE_MODE';
 export const GATE_HOOK_MALFORMED = 'GATE_HOOK_MALFORMED';
 export const GATE_HOOK_DIVERGED = 'GATE_HOOK_DIVERGED';
 export const GATE_HOOK_BUNDLE = 'GATE_HOOK_BUNDLE';
+// --read-lane (AD-055 Part II): the opt-in read-only compound lane toggle + its currency guard.
+export const LANES_REL = 'docs/ai/lanes.json';
+export const READ_LANE_KEY = 'readLane';
+export const GATE_HOOK_STALE = 'GATE_HOOK_STALE'; // the placed hook is absent/stale — the lane cannot fire
+export const GATE_HOOK_LANE = 'GATE_HOOK_LANE'; // a lanes.json write refusal (deployment/malformed)
 
 const EXIT_OK = 0;
 const EXIT_PRECONDITION = 1;
@@ -84,12 +98,21 @@ const TARGET_CURRENT = 'already-current';
 const TARGET_DIVERGED = 'diverged';
 
 const USAGE = `usage: gate-hook [--dry-run | --apply] [--cwd <dir>] [--help]
+       gate-hook --read-lane [--dry-run | --apply] [--cwd <dir>]   (enable the opt-in read-only compound lane)
 
 Places the bundled PreToolUse gate-approval hook to ${HOOK_FILE_REL} and wires ONE
 PreToolUse "Bash" entry into ${SETTINGS_FILE}. Default is --dry-run (a preview; writes
 nothing). --apply writes. The hook auto-approves byte-exact declared gate cmds
 (docs/ai/gates.json, project root) and asks on seeded-read-only commands carrying the
-documented runtime residual. Never writes ${SETTINGS_LOCAL_FILE}; never commits.`;
+documented runtime residual.
+
+--read-lane enables the opt-in read-only COMPOUND lane in ${LANES_REL} ("${READ_LANE_KEY}": true) — the
+hook then auto-approves compounds of the seeded read-only core carrying zero shell metaprogramming.
+--apply --read-lane verifies the PLACED hook is the CURRENT bundle first (a pre-1.48 hook never reads
+${LANES_REL}) and refuses with the delete-to-reseed recovery otherwise. Never touches ${SETTINGS_FILE}
+or docs/ai/gates.json.
+
+Never writes ${SETTINGS_LOCAL_FILE}; never commits.`;
 
 export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
 
@@ -307,6 +330,166 @@ export const writeGateHook = ({ cwd, dryRun = true } = {}, deps = {}) => {
   return { wrote: placePlanned || wirePlanned, dryRun: false, ...base };
 };
 
+// ── the read-lane writer (--read-lane; AD-055 Part II, Decisions 5/9) ──────────────────
+// Enables the opt-in read-only COMPOUND lane by writing { "readLane": true } into the kit-owned
+// docs/ai/lanes.json (a SEPARATE file — gates.json is never touched). Same family writer discipline
+// as the base flow + ack-write (preview-then-mutate, deployment-gated, create-if-absent,
+// merge-preserve, symlink/non-regular refusal, malformed-JSON fail-closed, atomic), PLUS a CURRENCY
+// CHECK (Decisions 9): --apply refuses unless the PLACED hook is byte-identical to the current
+// bundle — enabling a lane a pre-1.48 hook can never read would be a silent no-op the user paid
+// consent for. The refusal names the delete-to-reseed recovery.
+
+const laneStop = (message) => makeGateHookError(GATE_HOOK_LANE, message);
+
+// Read the existing lanes.json (already gated as a regular file). ENOENT (a TOCTOU vanish) → absent
+// {}; malformed JSON / a non-object root FAILS CLOSED — never overwrite an unparseable toggle file.
+const readExistingLanes = (absPath, deps) => {
+  const readFile = deps.readFile ?? readFileSync;
+  let text;
+  try {
+    text = readFile(absPath, UTF8);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return {};
+    throw laneStop(`cannot read ${LANES_REL} (${err?.code ?? err?.message}) — refusing to overwrite it`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw laneStop(`${LANES_REL} is not valid JSON — refusing to overwrite it (fix or delete it, then re-run)`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw laneStop(`${LANES_REL} is not a JSON object — refusing to overwrite it`);
+  }
+  return parsed;
+};
+
+// Target gate: a symlinked / non-regular lanes.json is a STOP checked BEFORE any read (a FIFO can
+// never block the reader). Returns { existed, existing } — the merge base.
+const preflightLaneTarget = (absPath, deps) => {
+  const fs = fsDeps(deps);
+  const st = lstatNoFollow(absPath, fs);
+  if (st === null) return { existed: false, existing: {} };
+  if (st.isSymbolicLink()) throw makeGateHookError(GATE_HOOK_SYMLINK, `${LANES_REL} is a symlink — refusing to write through it`);
+  if (!st.isFile()) throw makeGateHookError(GATE_HOOK_SYMLINK, `${LANES_REL} exists but is not a regular file — refusing to touch it`);
+  return { existed: true, existing: readExistingLanes(absPath, deps) };
+};
+
+export const applyGateHookCommand = (root) => `node ${q(GATE_HOOK_TOOL)} --apply --cwd ${q(root)}`;
+export const applyReadLaneCommand = (root) => `node ${q(GATE_HOOK_TOOL)} --read-lane --cwd ${q(root)} --apply`;
+
+// The currency check (Decisions 9): the PLACED hook must be byte-identical to the current bundle,
+// else enabling the lane is a no-op. Returns { current, reason, refusal? }; a symlinked / non-regular
+// placed hook is a hard STOP.
+const checkHookCurrency = (root, bundleContent, fs) => {
+  const hookAbs = join(root, HOOK_FILE_REL);
+  const st = lstatNoFollow(hookAbs, fs);
+  if (st === null) {
+    return {
+      current: false,
+      reason: `${HOOK_FILE_REL} is not placed`,
+      refusal: `${HOOK_FILE_REL} is not placed — the read-lane cannot fire. Place the hook first:\n  ${applyGateHookCommand(root)}\nthen re-run with --read-lane.`,
+    };
+  }
+  if (st.isSymbolicLink() || !st.isFile()) {
+    throw makeGateHookError(GATE_HOOK_SYMLINK, `${HOOK_FILE_REL} is not a regular file — refusing to touch it`);
+  }
+  if (fs.readFile(hookAbs, UTF8) !== bundleContent) {
+    return {
+      current: false,
+      reason: `${HOOK_FILE_REL} is not the current bundle`,
+      refusal: `${HOOK_FILE_REL} is NOT the current bundle — enabling the read-lane now would be a silent no-op (a pre-1.48 hook never reads ${LANES_REL}). Reseed it, then re-run with --read-lane:\n  rm ${q(join(root, HOOK_FILE_REL))}\n  ${applyGateHookCommand(root)}`,
+    };
+  }
+  return { current: true, reason: 'the placed hook is the current bundle' };
+};
+
+// Pure preflight (both dry-run and apply): deployment gate + the merge over the existing toggle file.
+export const planReadLane = ({ cwd }, deps = {}) => {
+  const root = resolve(cwd);
+  assertDocsAiDeployment(root, deps, { stop: laneStop, noun: 'the read-lane toggle', rel: LANES_REL });
+  const absPath = join(root, LANES_REL);
+  const { existed, existing } = preflightLaneTarget(absPath, deps);
+  const already = existing[READ_LANE_KEY] === true;
+  const merged = { ...existing, [READ_LANE_KEY]: true };
+  const otherKeys = Object.keys(existing).filter((k) => k !== READ_LANE_KEY);
+  return { root, absPath, existed, existing, merged, already, otherKeys };
+};
+
+// A byte-current hook that is not WIRED never fires — enabling the lane against it is the same
+// silent no-op the currency check guards (council B5). Wired-detection reuses the writer's own
+// isHookWired over BOTH settings scopes (the hooks contract merges both).
+const checkHookWired = (root, deps) => {
+  const project = readSettingsFile(join(root, SETTINGS_FILE), { ...deps, cwd: root });
+  const local = readSettingsFile(join(root, SETTINGS_LOCAL_FILE), { ...deps, cwd: root });
+  return isHookWired(project.data) || isHookWired(local.data);
+};
+
+export const writeReadLane = ({ cwd, dryRun = true } = {}, deps = {}) => {
+  const fs = fsDeps(deps);
+  const bundleContent = readBundledHook(deps);
+  const plan = planReadLane({ cwd: cwd ?? deps.cwd ?? process.cwd() }, deps);
+  const currency = checkHookCurrency(plan.root, bundleContent, fs);
+  const wired = checkHookWired(plan.root, deps);
+  const stamp = readStamp(join(plan.root, WORKFLOW_STAMP), fs);
+  const stampOk = stamp === EXPECTED_WORKFLOW_VERSION;
+  if (dryRun) return { wrote: false, dryRun: true, currency, wired, stamp, stampOk, ...plan };
+  if (!currency.current) throw makeGateHookError(GATE_HOOK_STALE, currency.refusal);
+  if (!wired) {
+    throw makeGateHookError(
+      GATE_HOOK_STALE,
+      `${HOOK_FILE_REL} is placed and current but NOT wired into ${SETTINGS_FILE} — the read-lane cannot fire. Wire it first:\n  ${applyGateHookCommand(plan.root)}\nthen re-run with --read-lane.`,
+    );
+  }
+  if (!stampOk) {
+    throw makeGateHookError(
+      GATE_HOOK_STAMP,
+      `not a deployed agent-workflow project at lineage ${EXPECTED_WORKFLOW_VERSION} (found ${stamp ?? 'none'}) — run init/upgrade first`,
+    );
+  }
+  if (plan.already) return { wrote: false, dryRun: false, currency, wired, stamp, stampOk, ...plan };
+  const body = `${JSON.stringify(plan.merged, null, SETTINGS_JSON_INDENT)}\n`;
+  writeDocsAiFileAtomic(plan.root, LANES_REL, body, deps, { stop: laneStop, noun: 'the read-lane toggle' });
+  return { wrote: true, dryRun: false, currency, wired, stamp, stampOk, ...plan };
+};
+
+const READ_LANE_POSTURE =
+  "posture: an auto-allowed read chain runs UNATTENDED and can read any file you can — the SAME trust boundary as the AUDITED read-only core velocity seeds, extended to COMPOUNDS (and singles) of that core. The subset invariant holds against that AUDITED CORE (every segment is an audited-core read), so the lane is a standalone opt-in grant BOUNDED BY the audited core — never a command outside it; it auto-approves those core commands REGARDLESS of which you seeded as individual settings rules (not strictly a subset of your current settings). This consent is a PROJECT-PERSISTENT declaration in docs/ai/lanes.json — it applies to every future session and to subagents' Bash, and where docs/ai is committed, to every checkout. It bypasses the PROMPT only, never the OS sandbox; on engine builds where a hook allow supersedes an ask rule, the opt-in covers EXACTLY the audited read-only core — nothing else.";
+
+export const formatReadLaneResult = (result) => {
+  const merge = result.otherKeys.length > 0 ? ` (merge-preserving ${result.otherKeys.length} existing key(s))` : '';
+  if (!result.dryRun) {
+    if (result.already) {
+      return `agent-workflow read-lane — APPLY: ${LANES_REL} already enables the read-lane — nothing to do (hook currency verified).`;
+    }
+    return [
+      'agent-workflow read-lane — APPLY',
+      `  - ${LANES_REL}: "${READ_LANE_KEY}" = true${merge}`,
+      '  - hook currency verified: the placed hook is the current bundle — the lane is active for new Bash calls.',
+    ].join(LF);
+  }
+  const lines = [
+    result.already
+      ? `agent-workflow read-lane — DRY RUN: ${LANES_REL} already enables the read-lane ("${READ_LANE_KEY}": true) — nothing to do.`
+      : 'agent-workflow read-lane — DRY RUN (no changes; re-run with --apply --read-lane)',
+  ];
+  if (!result.already) lines.push(`  - would ${result.existed ? 'set' : 'create'} ${LANES_REL} "${READ_LANE_KEY}" = true${merge}`);
+  lines.push(
+    result.currency.current
+      ? '  hook currency: current — the lane will fire once enabled.'
+      : `  hook currency: STALE — ${result.currency.reason}; --apply will REFUSE until you reseed the placed hook.`,
+  );
+  if (!result.wired) {
+    lines.push(`  hook wiring: NOT wired into ${SETTINGS_FILE}; --apply will REFUSE until you wire it (${applyGateHookCommand(result.root)}).`);
+  }
+  if (!result.stampOk) {
+    lines.push(`  deployment stamp: ${result.stamp ?? 'none'} ≠ lineage head ${EXPECTED_WORKFLOW_VERSION}; --apply will REFUSE until init/upgrade runs.`);
+  }
+  lines.push(READ_LANE_POSTURE);
+  if (!result.already) lines.push(`  to apply: ${applyReadLaneCommand(result.root)}`);
+  return lines.join(LF);
+};
+
 // ── report ────────────────────────────────────────────────────────────────────────────
 
 const TRUST_POSTURE_LINE =
@@ -346,12 +529,13 @@ export const formatResult = (result) => {
 // ── CLI ───────────────────────────────────────────────────────────────────────────────
 
 export const parseArgs = (argv) => {
-  const opts = { dryRunFlag: false, apply: false, cwd: undefined, help: false };
+  const opts = { dryRunFlag: false, apply: false, cwd: undefined, help: false, readLane: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') opts.help = true;
     else if (arg === '--dry-run') opts.dryRunFlag = true;
     else if (arg === '--apply') opts.apply = true;
+    else if (arg === '--read-lane') opts.readLane = true;
     else if (arg === '--cwd') {
       i += 1;
       if (argv[i] === undefined || argv[i].startsWith('-')) throw fail(EXIT_USAGE, '--cwd needs a directory argument');
@@ -361,7 +545,7 @@ export const parseArgs = (argv) => {
     }
   }
   if (opts.dryRunFlag && opts.apply) throw fail(EXIT_USAGE, '--dry-run and --apply cannot be used together');
-  return { help: opts.help, dryRun: !opts.apply, cwd: opts.cwd };
+  return { help: opts.help, dryRun: !opts.apply, cwd: opts.cwd, readLane: opts.readLane };
 };
 
 export const main = (argv = process.argv.slice(2), deps = {}) => {
@@ -373,6 +557,11 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       log(USAGE);
       return EXIT_OK;
     }
+    if (args.readLane) {
+      const laneResult = writeReadLane({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), dryRun: args.dryRun }, deps);
+      log(formatReadLaneResult(laneResult));
+      return EXIT_OK;
+    }
     const result = writeGateHook({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), dryRun: args.dryRun }, deps);
     log(formatResult(result));
     return EXIT_OK;