@sabaiway/agent-workflow-kit 1.44.0 → 1.45.1

package/tools/grounding.mjs

@@ -19,14 +19,15 @@
 // in-band marker + stderr report (never a silent cut).
 //
 // Catalog honesty: this is a WRITER — `--out <path>` writes a file. Invariant: `--out` accepts
-// only gitignored / out-of-repo scratch destinations and REFUSES a tracked path AND an in-repo
+// only system-temp destinations or a FRESH gitignored in-repo path and REFUSES a tracked/in-repo
 // not-ignored path (a new untracked file would itself move the review fingerprint the facts are
 // about to ground). stdout is the default. It never commits and never runs a subscription CLI.
 //
 // Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, writeFileSync, lstatSync, realpathSync } from 'node:fs';
-import { resolve, join, relative, isAbsolute, dirname, basename } from 'node:path';
+import { resolve, join, relative, isAbsolute, dirname, basename, sep } from 'node:path';
+import { tmpdir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { fail } from './orchestration-config.mjs';
@@ -35,6 +36,9 @@ import { fail } from './orchestration-config.mjs';
 // computeTelemetry give the counts; the segment filter gives the scope.
 import { ORIGINS, computeTelemetry, filterSegmentRecords, readLedger, resolveLedgerPath, resolveBase } from './review-ledger.mjs';
 import { plansInFlight } from './review-state.mjs';
+// (f) --autonomy (AD-044 Plan 3): the effective per-project autonomy policy for the facts payload.
+// READ core only — never autonomy-write.mjs (the import-split invariant).
+import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, isSparseSeedConfig } from './autonomy-config.mjs';
 
 const PLAN_EXECUTION = 'plan-execution';
 
@@ -82,11 +86,15 @@ export const sliceSection = (text, heading, { optional = false, label = 'documen
 
 // ── assembly ───────────────────────────────────────────────────────────────────────
 
-export const assembleGrounding = ({ constraintsText = null, planText = null, planLabel = 'plan' } = {}) => {
+export const assembleGrounding = ({ constraintsText = null, autonomyText = null, planText = null, planLabel = 'plan' } = {}) => {
   const parts = [];
   if (constraintsText != null) {
     parts.push(sliceSection(constraintsText, CONSTRAINTS_HEADING, { label: 'AGENTS.md' }));
   }
+  // The autonomy block is COMPUTED (resolveAutonomy over the policy file), not sliced — it rides
+  // between the constraints and the plan sections: the natural read order (what always binds →
+  // how autonomous this session is → what this plan decides).
+  if (autonomyText != null) parts.push(autonomyText);
   if (planText != null) {
     for (const { heading, optional } of PLAN_SECTIONS) {
       const section = sliceSection(planText, heading, { optional, label: planLabel });
@@ -178,6 +186,38 @@ export const resolveLedgerSummary = ({ cwd, env }) => {
   return renderLedgerSummary(records, { loop, base });
 };
 
+// ── (f) --autonomy: the effective autonomy policy as a computed facts block (AD-044 Plan 3) ─────
+// The ONE shared resolver (resolveAutonomy) renders the FULL effective policy — every red-line and
+// every activity resolved, no key undefined — with a stated source line. The policy file resolves
+// from the GIT TOP of cwd (the --ledger-summary gitTop precedent): a cwd-relative read from a
+// subdir would silently emit computed defaults for a policy-carrying repo, the exact silent failure
+// grounding exists to kill. Malformed/unreadable policy fails CLOSED (loadAutonomy throws exit 1);
+// an ABSENT file is NOT an error — the computed defaults ARE the effective policy (deliberately
+// diverging from `velocity-profile --autonomy`'s refuse-on-absent: that surface WRITES settings and
+// demands a declared policy; this one emits informational facts). Enforcement honesty: these facts
+// INFORM a review; enforcement stays the OS sandbox + the orchestrator process (AD-044 D1).
+
+export const renderAutonomyFacts = (config, source) => {
+  const resolved = resolveAutonomy(config);
+  // The STRUCTURAL seed (_README only) reads as computed defaults; an EXPLICIT declared-defaults
+  // policy reads as a declared policy (the shared predicate — same contract on every surface).
+  const defaultsEquivalent = source !== 'none' && isSparseSeedConfig(config);
+  const head =
+    source === 'none'
+      ? `## Autonomy policy — ${AUTONOMY_REL} absent; the computed defaults ARE the effective policy`
+      : defaultsEquivalent
+        ? `## Autonomy policy — ${AUTONOMY_REL} present but defaults-equivalent (the sparse seed); the computed defaults ARE the effective policy`
+        : `## Autonomy policy — ${AUTONOMY_REL}`;
+  const redlines = Object.entries(resolved.redlines).map(([k, v]) => `${k}:${v}`).join(' ');
+  const activities = Object.entries(resolved.activities).map(([a, v]) => `${a}:${v.autonomy}`).join(' ');
+  return `${head}\n\nred-lines — ${redlines}\nactivities — ${activities}\n`;
+};
+
+const resolveAutonomyFacts = ({ cwd }) => {
+  const { config, source } = loadAutonomy(gitTop(cwd));
+  return renderAutonomyFacts(config, source);
+};
+
 // ── the --out destination guard (gitignored / out-of-repo scratch ONLY) ────────────────
 
 const gitLine = (args, cwd) => {
@@ -185,24 +225,35 @@ const gitLine = (args, cwd) => {
   return r.error || r.status == null ? null : { status: r.status, stdout: r.stdout ?? '' };
 };
 
-// STOP unless `outPath` is a safe scratch destination: outside any git work tree, or gitignored
-// inside one. A TRACKED path and an in-repo NOT-ignored path are both refused (a facts file must
-// never enter the tree it grounds — it would move the fingerprint and could be committed). The
-// check runs on the REAL destination, never the lexical path (codex R1 finding): a symlink leaf is
-// refused outright, and the parent directory is realpath-resolved first, so a gitignored or
-// out-of-repo symlink can never route the write onto a tracked/in-repo file. Returns the resolved
-// real path the caller must write to.
+// STOP unless `outPath` is a safe scratch destination — the CLOSED surface (this writer is
+// bridge-tier auto-allowable): (a) under a SYSTEM TEMP root outside the repo ($TMPDIR /
+// os.tmpdir() / /tmp — rewritable), or (b) a FRESH gitignored in-repo path (create-only; an
+// EXISTING in-repo file, even gitignored, is a project file — the .env clobber class). Refused:
+// tracked paths, in-repo not-ignored paths (a new untracked file would move the fingerprint),
+// every other outside-repo destination, symlink and existing non-regular leaves, and any
+// unverifiable lstat. The check runs on the REAL destination, never the lexical path (codex R1):
+// the parent directory is realpath-resolved first, so a symlink can never route the write onto a
+// tracked/in-repo file. Returns { path, kind: 'temp' | 'repo-fresh' } — a repo-fresh caller MUST
+// write with the exclusive flag ('wx'), sealing the guard→write race (codex R11).
 export const assertScratchDestination = (outPath, cwd) => {
   const lexical = isAbsolute(outPath) ? outPath : resolve(cwd, outPath);
   let leaf = null;
   try {
     leaf = lstatSync(lexical);
-  } catch {
+  } catch (err) {
+    // ONLY an absent leaf is a fresh file; any other lstat failure fails CLOSED (codex R9 — this
+    // writer is bridge-tier auto-allowable, so an unverifiable leaf must never be written).
+    if (err?.code !== 'ENOENT') {
+      throw fail(1, `--out cannot inspect the destination (${outPath}: ${err?.code ?? err?.message ?? err}) — refusing to write an unverifiable leaf`);
+    }
     leaf = null; // absent → a fresh file; the parent still gets realpath-checked below
   }
   if (leaf?.isSymbolicLink()) {
     throw fail(1, `--out refuses a symlink destination (${outPath}) — the write would follow it onto another file; name the real scratch path`);
   }
+  if (leaf != null && !leaf.isFile()) {
+    throw fail(1, `--out refuses an existing non-regular destination (${outPath}) — a FIFO/device/directory write would hang or land on a non-file (codex R9); name a fresh or regular scratch path`);
+  }
   let realParent;
   try {
     realParent = realpathSync(dirname(lexical));
@@ -210,11 +261,31 @@ export const assertScratchDestination = (outPath, cwd) => {
     throw fail(1, `--out parent directory does not exist (${dirname(lexical)}) — create the scratch dir first`);
   }
   const full = join(realParent, basename(lexical));
+  // An out-of-repo (or no-repo) destination is scratch ONLY under a system temp root (codex R8
+  // blocker): the bridge tier auto-allows this tool with an args wildcard, so "anything outside
+  // the repo is scratch" would let an unattended run overwrite e.g. ~/.bashrc promptless.
+  // $TMPDIR / os.tmpdir() / /tmp are the scratch surface; everything else refuses loudly.
+  const assertTempScratch = () => {
+    const tempRoots = [...new Set([tmpdir(), process.env.TMPDIR, '/tmp'].filter(Boolean).map((p) => {
+      try {
+        return realpathSync(p);
+      } catch {
+        return null;
+      }
+    }).filter(Boolean))];
+    if (!tempRoots.some((t) => full === t || full.startsWith(`${t}${sep}`))) {
+      throw fail(1, `--out refuses an outside-repo destination that is not under a system temp root (${full}) — grounding output is scratch: use $TMPDIR//tmp, or a fresh gitignored in-repo path (temp roots checked: ${tempRoots.join(', ')})`);
+    }
+    return { path: full, kind: 'temp' };
+  };
   const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
-  if (top == null || top.status !== 0) return full; // no git tree → plain scratch, fine
+  if (top == null || top.status !== 0) return { path: assertTempScratch().path, kind: 'temp' }; // no git tree → temp-only scratch
   const root = top.stdout.replace(/\r?\n$/, '');
   const rel = relative(root, full);
-  if (rel.startsWith('..') || isAbsolute(rel)) return full; // really outside the work tree → scratch
+  // Segment-safe outside test (the Issue-004 class, codex R5): an in-repo file literally named
+  // `..facts` has rel `..facts` — `startsWith('..')` would misread it as outside and BYPASS the
+  // tracked/ignored refusals below. Only `..` exactly or a `..${sep}`-prefixed rel is outside.
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return { path: assertTempScratch().path, kind: 'temp' };
   const tracked = gitLine(['ls-files', '--error-unmatch', '--', rel], root);
   if (tracked != null && tracked.status === 0) {
     throw fail(1, `--out refuses a TRACKED path (${rel}) — grounding output is scratch; write it to a gitignored path or outside the repo`);
@@ -223,7 +294,15 @@ export const assertScratchDestination = (outPath, cwd) => {
   if (ignored == null || ignored.status !== 0) {
     throw fail(1, `--out refuses an in-repo path that is not gitignored (${rel}) — a new untracked file would move the review fingerprint; use a gitignored path or a location outside the repo`);
   }
-  return full;
+  // An in-repo destination must be a FRESH file (codex R10): even a gitignored existing file is a
+  // project file (.env is the canonical victim) — an auto-allowable writer must never clobber one.
+  // The rewritable scratch surface is the system temp; in-repo gitignored writes are create-only —
+  // the CALLER must open with the exclusive flag ('wx'): the kind seals the pre-check against the
+  // guard→write race (codex R11).
+  if (leaf != null) {
+    throw fail(1, `--out refuses to OVERWRITE an existing in-repo file (${rel}) — even gitignored, it is a project file (the .env class); write rewritable scratch under $TMPDIR//tmp, or remove the file first`);
+  }
+  return { path: full, kind: 'repo-fresh' };
 };
 
 // ── CLI ────────────────────────────────────────────────────────────────────────────
@@ -231,10 +310,15 @@ export const assertScratchDestination = (outPath, cwd) => {
 const HELP = `grounding — grounded-review facts assembler for the agent-workflow family (AD-038).
 
 Usage:
-  node grounding.mjs [--constraints] [--plan <path>] [--ledger-summary] [--reserve-bytes <n>] [--out <path>]
+  node grounding.mjs [--constraints] [--autonomy] [--plan <path>] [--ledger-summary] [--reserve-bytes <n>] [--out <path>]
 
   --constraints        slice the root AGENTS.md "Hard Constraints" section verbatim
                        (exactly one matching heading, else a loud STOP)
+  --autonomy           append the COMPUTED effective autonomy policy (resolveAutonomy over the
+                       git-top docs/ai/autonomy.json): every red-line + per-activity level, with a
+                       stated source line; absent file → the computed defaults ARE the policy
+                       (exit 0); malformed/unreadable → fail-closed STOP (exit 1); informational —
+                       enforcement stays the sandbox + the orchestrator
   --plan <path>        extract the plan's decision-bearing sections verbatim + whole:
                        "## Approach" + "## Verification" (REQUIRED — STOP if missing),
                        "## Decisions (locked)" when present; a duplicate heading is a STOP
@@ -244,7 +328,8 @@ Usage:
                        loud STOP unless exactly one plan is in flight
   --reserve-bytes <n>  the artifact share agy-review will add around these facts — the output
                        budget becomes AGY_MAX_PROMPT_BYTES − n (loud tail-trim on overflow)
-  --out <path>         write instead of stdout — gitignored / out-of-repo scratch ONLY
+  --out <path>         write instead of stdout — system-temp scratch (rewritable), or a FRESH
+                       gitignored in-repo path (create-only); everything else refuses
                        (a tracked or in-repo not-ignored path is refused)
 
 Feed the output to the review wrapper: agy-review code --facts @<out>. AGY_MAX_PROMPT_BYTES
@@ -256,6 +341,7 @@ Exit codes: 0 success; 2 usage; 1 STOP (missing/duplicate section, unreadable fi
 
 const parseArgs = (argv) => {
   let constraints = false;
+  let autonomy = false;
   let plan = null;
   let out = null;
   let reserve = 0;
@@ -263,6 +349,7 @@ const parseArgs = (argv) => {
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--constraints') constraints = true;
+    else if (a === '--autonomy') autonomy = true;
     else if (a === '--ledger-summary') ledgerSummary = true;
     else if (a === '--plan') {
       plan = argv[i + 1];
@@ -279,8 +366,10 @@ const parseArgs = (argv) => {
       i += 1;
     } else throw fail(2, `unknown argument: ${a}`);
   }
-  if (!constraints && plan == null && !ledgerSummary) throw fail(2, 'nothing to assemble — pass --constraints, --plan <path>, and/or --ledger-summary');
-  return { constraints, plan, out, reserve, ledgerSummary };
+  if (!constraints && !autonomy && plan == null && !ledgerSummary) {
+    throw fail(2, 'nothing to assemble — pass --constraints, --autonomy, --plan <path>, and/or --ledger-summary');
+  }
+  return { constraints, autonomy, plan, out, reserve, ledgerSummary };
 };
 
 const resolveBudget = (env, reserve) => {
@@ -300,7 +389,7 @@ export const main = (argv, ctx = {}) => {
   const env = ctx.env ?? process.env;
   try {
     if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
-    const { constraints, plan, out, reserve, ledgerSummary } = parseArgs(argv);
+    const { constraints, autonomy, plan, out, reserve, ledgerSummary } = parseArgs(argv);
     const budget = resolveBudget(env, reserve);
 
     const readOrStop = (path, label) => {
@@ -311,10 +400,29 @@ export const main = (argv, ctx = {}) => {
       }
     };
     const constraintsText = constraints ? readOrStop('AGENTS.md', 'root AGENTS.md') : null;
+    const autonomyText = autonomy ? resolveAutonomyFacts({ cwd }) : null;
+    // --plan is CONFINED to the git work tree (codex R4): the bridge tier auto-allows this tool
+    // with an args wildcard, so an unattended invocation could otherwise point --plan at ANY
+    // readable file and ship it into the facts payload. Plans are in-repo by contract
+    // (docs/plans); an outside-tree path is a loud refusal, never a silent read.
+    if (plan != null) {
+      const top = gitTop(cwd);
+      const planReal = (() => {
+        try {
+          return realpathSync(resolve(cwd, plan));
+        } catch (err) {
+          throw fail(1, `plan file '${plan}' is unreadable (${(err && err.code) || err}) — STOP`);
+        }
+      })();
+      const topReal = realpathSync(top);
+      if (planReal !== topReal && !planReal.startsWith(`${topReal}${sep}`)) {
+        throw fail(1, `--plan '${plan}' resolves outside the git work tree (${planReal}) — plans live in-repo (docs/plans); refusing to read outside-tree content into the facts payload`);
+      }
+    }
     const planText = plan != null ? readOrStop(plan, 'plan file') : null;
 
     const parts = [];
-    const assembled = assembleGrounding({ constraintsText, planText, planLabel: plan ?? 'plan' });
+    const assembled = assembleGrounding({ constraintsText, autonomyText, planText, planLabel: plan ?? 'plan' });
     if (assembled) parts.push(assembled);
     if (ledgerSummary) {
       const summary = resolveLedgerSummary({ cwd, env });
@@ -327,8 +435,17 @@ export const main = (argv, ctx = {}) => {
       : '';
 
     if (out != null) {
-      const realOut = assertScratchDestination(out, cwd);
-      writeFileSync(realOut, text);
+      const dest = assertScratchDestination(out, cwd);
+      // repo-fresh writes are EXCLUSIVE ('wx'): the create-only pre-check would otherwise race a
+      // file created between the guard and this write (codex R11); temp scratch stays rewritable.
+      // ctx.writeFile is a TEST seam (the EEXIST race arm is not constructible without it).
+      const writeFile = ctx.writeFile ?? writeFileSync;
+      try {
+        writeFile(dest.path, text, dest.kind === 'repo-fresh' ? { flag: 'wx' } : {});
+      } catch (err) {
+        if (err?.code === 'EEXIST') throw fail(1, `--out lost the create-only race: ${out} appeared between the guard and the write — an in-repo destination is never overwritten; re-run with a fresh path or temp scratch`);
+        throw err;
+      }
       return { code: 0, stdout: `[grounding] wrote ${Buffer.byteLength(text, 'utf8')} bytes to ${out} — pass it as: agy-review code --facts @${out}`, stderr };
     }
     return { code: 0, stdout: text, stderr };

package/tools/inject-methodology.mjs

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 // Marker-slot injection + reconciliation — the composition root's only mutation of a deployed
-// AGENTS.md. A deployed entry point carries TWO reconciled marker slots, each filled LIVE from the
+// AGENTS.md. A deployed entry point carries THREE reconciled marker slots, each filled LIVE from the
 // installed agent-workflow-engine (the family's one source of truth, no bundled mirror):
 //   1. workflow:methodology  — the plan→execute→review pointer (references/methodology-slot.md).
 //   2. workflow:orchestration — the recipe-vocabulary pointer  (references/orchestration-slot.md).
+//   3. workflow:autonomy     — the autonomy-policy read contract (references/autonomy-slot.md).
 //
-// Both share ONE generic marker engine (a slot DESCRIPTOR parameterizes the markers / anchor /
+// All share ONE generic marker engine (a slot DESCRIPTOR parameterizes the markers / anchor /
 // empty-slot / leading-blank). The methodology exports (findSlot / injectMethodology / ensureSlot /
 // reconcileSlot / slotNeedsFill / extractSlot) delegate to it byte-for-byte, so the methodology
-// contract is unchanged; the orchestration slot is the SAME engine with a different descriptor.
+// contract is unchanged; the later slots are the SAME engine with different descriptors.
 //
 // Contract per slot, strictly enforced:
 //   exactly one ordered start→end pair → replace only the bytes between them;
@@ -31,6 +32,8 @@ export const START_MARKER = '<!-- workflow:methodology:start -->';
 export const END_MARKER = '<!-- workflow:methodology:end -->';
 export const ORCH_START_MARKER = '<!-- workflow:orchestration:start -->';
 export const ORCH_END_MARKER = '<!-- workflow:orchestration:end -->';
+export const AUTONOMY_START_MARKER = '<!-- workflow:autonomy:start -->';
+export const AUTONOMY_END_MARKER = '<!-- workflow:autonomy:end -->';
 export const AGENTS_MD_CAP = 100; // the deployed AGENTS.md line budget (its own footer rule)
 
 const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -59,11 +62,16 @@ export const METHODOLOGY_ANCHOR = /^.*Read it before any code change\..*$/m;
 // The orchestration pair lands right BELOW the methodology end marker — so its anchor is that line.
 // A well-formed entry point carries exactly one methodology end marker → exactly one anchor.
 export const ORCH_ANCHOR = new RegExp(`^.*${escapeRegExp(END_MARKER)}.*$`, 'm');
+// The autonomy pair chains right below the orchestration pair — its anchor is the orchestration end
+// marker line. The anchor can legitimately be ABSENT (a legacy file whose orchestration pair was
+// itself skipped) — the chained CLI classifies that as a soft skip, never a hard STOP (D4).
+export const AUTONOMY_ANCHOR = new RegExp(`^.*${escapeRegExp(ORCH_END_MARKER)}.*$`, 'm');
 
 // The canonical empty slots (an ordered start→end pair, nothing between) — what a fresh template
 // ships and what ensureSlot inserts. LF form; ensureSlot rewrites the newline to match the document.
 export const EMPTY_SLOT = `${START_MARKER}\n${END_MARKER}`;
 export const ORCH_EMPTY_SLOT = `${ORCH_START_MARKER}\n${ORCH_END_MARKER}`;
+export const AUTONOMY_EMPTY_SLOT = `${AUTONOMY_START_MARKER}\n${AUTONOMY_END_MARKER}`;
 
 // ── known-prior canonical fragments (drift-guarded, APPEND-ONLY per slot) ───────
 // The EXACT content a PREVIOUS release's engine fragment shipped (what a filled slot would carry today).
@@ -113,6 +121,21 @@ export const ORCHESTRATION_DESCRIPTOR = {
   upgradeAdvice:
     'the orchestration-recipes pointer predates the read-at-start clause — add "read `docs/ai/orchestration.json` at session start; set it with /agent-workflow-kit set-recipe", or set your preference now with /agent-workflow-kit set-recipe.',
 };
+// The autonomy-policy slot (AD-044 Plan 3) — first canon, so no known priors yet: any future
+// fragment change must append the outgoing content to a KNOWN_PRIOR_AUTONOMY_SLOT store first.
+export const AUTONOMY_DESCRIPTOR = {
+  startMarker: AUTONOMY_START_MARKER,
+  endMarker: AUTONOMY_END_MARKER,
+  anchor: AUTONOMY_ANCHOR,
+  emptySlot: AUTONOMY_EMPTY_SLOT,
+  leadingBlank: false,
+  markerName: 'autonomy',
+  anchorLabel: 'autonomy anchor (the orchestration end-marker line)',
+  knownPriorCanonicals: [],
+  upgradeSignature: 'docs/ai/autonomy.json',
+  upgradeAdvice:
+    'the autonomy pointer does not name the per-project policy file — add "read `docs/ai/autonomy.json` at session start; set it with /agent-workflow-kit set-autonomy", or refresh the slot to the current canon.',
+};
 
 // ── generic marker-slot engine (descriptor-parameterized) ──────────────────────
 
@@ -283,15 +306,22 @@ export const markerSlotUpgradeHint = (text, descriptor) => {
 // stable "(cap N)" substring both cap messages carry, so the dual-slot reconcile can skip the
 // orchestration pointer (loud) while keeping the methodology fill, instead of aborting both.
 const isCapRefusal = (errorMessage) => typeof errorMessage === 'string' && errorMessage.includes('(cap ');
+// The autonomy lane distinguishes the TWO cap messages "(cap " conflates (D4 cap-lane honesty):
+// only a FILL-overflow from an in-cap input (injectIntoSlot's "injection would push …") is the soft
+// skip — the pointer was genuinely withheld. An ALREADY-over-cap custom file (reconcileMarkerSlot's
+// "AGENTS.md is N lines … trim the file") keeps its distinct over-cap report as a hard refusal,
+// never a mislabeled "skipped". Exported so the split is pinned against the real messages.
+export const isFillCapRefusal = (errorMessage) =>
+  isCapRefusal(errorMessage) && errorMessage.includes('injection would push');
 
 const main = async (argv) => {
   const { readFile, writeFile, rename, rm } = await import('node:fs/promises');
   const { dirname, basename, join, resolve } = await import('node:path');
   const { homedir } = await import('node:os');
-  const { resolveEngineDir, readEngineFragment, detectEngine, ENGINE_FRAGMENT_REL, ORCHESTRATION_FRAGMENT_REL } = await import('./engine-source.mjs');
+  const { resolveEngineDir, readEngineFragment, detectEngine, ENGINE_FRAGMENT_REL, ORCHESTRATION_FRAGMENT_REL, AUTONOMY_FRAGMENT_REL } = await import('./engine-source.mjs');
 
   // `reconcile <AGENTS.md> [fragment.md]` = ensure-slot + inject-if-empty + cap (bootstrap/upgrade) for
-  // BOTH slots; `<AGENTS.md> [fragment.md]` = the legacy inject-into-existing-(methodology)-slot mode.
+  // ALL THREE slots; `<AGENTS.md> [fragment.md]` = the legacy inject-into-existing-(methodology)-slot mode.
   const mode = argv[0] === 'reconcile' ? 'reconcile' : 'inject';
   const rest = mode === 'reconcile' ? argv.slice(1) : argv;
   const agentsPath = rest[0];
@@ -323,36 +353,32 @@ const main = async (argv) => {
     }
   };
 
-  // The orchestration fragment is the SECOND (less-critical) pointer. Source it lazily, but DISTINGUISH
-  // two failures keyed off the engine's own detection (not message text): an engine that is VALID but
-  // simply TOO OLD to ship `orchestration-slot.md` (e.g. <1.2.0) is a SOFT skip — the methodology fill
-  // is kept and the recipes pointer is reported as withheld (parallel to the cap-skip); only a FULLY
-  // absent/invalid engine (it cannot supply EITHER pointer) is a hard STOP. Returns
-  // { fragment } on success, { skip } for the soft case, or process.exit(1) for the hard STOP.
-  const sourceOrchestrationFragment = async () => {
+  // The orchestration + autonomy fragments are the CHAINED (less-critical) pointers. Source each
+  // lazily, but DISTINGUISH two failures keyed off the engine's own detection (not message text): an
+  // engine that is VALID but simply TOO OLD to ship the requested fragment is a SOFT skip — the prior
+  // fills are kept and the pointer is reported as withheld (parallel to the cap-skip); only a FULLY
+  // absent/invalid engine (it cannot supply ANY pointer) is a hard STOP. A read error on a PRESENT
+  // fragment is a real corruption STOP, NEVER a "too old" skip (don't mislabel a current engine with
+  // an unreadable fragment). Returns { fragment } on success, { skip } for the soft case, or
+  // process.exit(1) for the hard STOP.
+  const sourceChainedFragment = async (rel) => {
     const { dir, source } = resolveEngineDir({ env: process.env, home: homedir() });
     const stop = (err) => {
       console.error(`[inject-methodology] reconcile STOP — ${err.message}`);
       process.exit(1);
     };
-    // The orchestration fragment FILE is present + the engine is valid → read it. A read error on a
-    // PRESENT fragment is a real corruption STOP, NEVER a "too old" skip (don't mislabel a current
-    // engine with an unreadable fragment).
-    if (detectEngine(dir, { source, rel: ORCHESTRATION_FRAGMENT_REL }).ok) {
+    if (detectEngine(dir, { source, rel }).ok) {
       try {
-        return { fragment: readEngineFragment(dir, { source, rel: ORCHESTRATION_FRAGMENT_REL }) };
+        return { fragment: readEngineFragment(dir, { source, rel }) };
       } catch (err) {
         stop(err);
       }
     }
-    // The orchestration fragment is NOT a usable file. SOFT-skip ONLY when the engine is otherwise
-    // valid (it can still supply the methodology fragment) — a genuine too-old (<1.2.0) engine. A
-    // fully absent/invalid engine cannot supply EITHER fragment → hard STOP with the install command.
     if (detectEngine(dir, { source }).ok) {
       return { skip: 'the installed engine is too old to supply it — refresh with `npx @sabaiway/agent-workflow-engine@latest init`' };
     }
     try {
-      readEngineFragment(dir, { source, rel: ORCHESTRATION_FRAGMENT_REL }); // throws the canonical install-me error
+      readEngineFragment(dir, { source, rel }); // throws the canonical install-me error
     } catch (err) {
       stop(err);
     }
@@ -398,7 +424,7 @@ const main = async (argv) => {
       for (const n of notes) console.log(`[inject-methodology] note: ${n}`);
     };
 
-    // ── Explicit [fragment.md] binds methodology ONLY → skip the orchestration reconcile ──
+    // ── Explicit [fragment.md] binds methodology ONLY → skip the orchestration + autonomy reconciles ──
     if (explicitFragmentArg) {
       if (afterMeth === text) {
         console.log('[inject-methodology] methodology slot already present and filled — nothing to do (zero-diff).');
@@ -416,7 +442,7 @@ const main = async (argv) => {
     let orchSkipped = false;
 
     const orchSource = markerSlotNeedsFill(afterMeth, ORCHESTRATION_DESCRIPTOR)
-      ? await sourceOrchestrationFragment()
+      ? await sourceChainedFragment(ORCHESTRATION_FRAGMENT_REL)
       : { fragment: '' };
     if (orchSource.skip) {
       // Engine too old to supply the recipes pointer → SOFT skip, parallel to the cap-skip: the
@@ -453,16 +479,79 @@ const main = async (argv) => {
       }
     }
 
-    // ── One atomic write of the final (both-slot) text ──
+    // ── Slot 3: autonomy, chained on the orchestration-reconciled text (same combined ≤100 guard).
+    //    D4 invariant: every failure lane SPECIFIC to this slot is a LOUD soft skip that preserves
+    //    the prior fills and exits 0 — (i) a too-old engine (no autonomy fragment), (ii) a
+    //    fill-overflow cap refusal, (iii) an ABSENT anchor (the orchestration pair is absent or was
+    //    itself skipped above — a 0-anchors ensure error must not discard the methodology fill).
+    //    Malformed autonomy markers, an already-over-cap custom file, a present-but-unreadable
+    //    fragment, and a fully absent/invalid engine stay hard STOPs. ──
+    let describeAut;
+    let autSkipped = false;
+    const autSlot = findMarkerSlot(finalText, AUTONOMY_DESCRIPTOR);
+    if (autSlot.state === 'malformed') {
+      // Malformed markers are a hard STOP on EVERY lane — validated before the soft-skip
+      // short-circuits so a duplicate/reversed autonomy pair can never ride out as a "skip"
+      // alongside a partial (methodology) write.
+      console.error(`[inject-methodology] reconcile refused (autonomy) — ${autSlot.reason}`);
+      process.exit(1);
+    }
+    if (orchSkipped) {
+      // The chain is CAUSAL, not merely positional: a pointer never lands in a run that withheld
+      // the pointer it chains below (cap or too-old) — otherwise a partially-shipped engine could
+      // fill autonomy under an unfilled recipes pointer, and a near-cap file could spend its last
+      // lines on the less-critical pointer. LOUD soft skip. This branch also subsumes the D4 (iii)
+      // anchor-absent lane: after a non-skipped orchestration reconcile the orchestration pair —
+      // the autonomy anchor — is present by construction, so orchSkipped is the ONLY route to a
+      // missing anchor (a separate anchor check would be dead code; coverage proved it).
+      autSkipped = true;
+      describeAut =
+        'autonomy pointer skipped — chained below the orchestration pointer, which was itself skipped this run; re-run once it lands';
+    } else {
+      const autSource = markerSlotNeedsFill(finalText, AUTONOMY_DESCRIPTOR)
+        ? await sourceChainedFragment(AUTONOMY_FRAGMENT_REL)
+        : { fragment: '' };
+      if (autSource.skip) {
+        autSkipped = true;
+        describeAut = `autonomy pointer skipped — ${autSource.skip}`;
+      } else {
+        const autResult = reconcileMarkerSlot(finalText, AUTONOMY_DESCRIPTOR, autSource.fragment, { maxLines: AGENTS_MD_CAP });
+        if (autResult.status === 'error') {
+          if (isFillCapRefusal(autResult.error)) {
+            // SOFT skip — only the genuine fill-overflow withholds the pointer; an already-over-cap
+            // custom file keeps its distinct over-cap report via the hard-STOP branch below.
+            autSkipped = true;
+            describeAut = `autonomy pointer skipped — ${autResult.error}`;
+          } else {
+            console.error(`[inject-methodology] reconcile refused (autonomy) — ${autResult.error}`);
+            process.exit(1);
+          }
+        } else {
+          finalText = autResult.text;
+          describeAut = {
+            'reconciled-inserted': 'inserted the autonomy pointer below it and filled it',
+            'reconciled-filled': 'filled the empty autonomy pointer',
+            'reconciled-refreshed': 'refreshed the autonomy pointer to the current canon',
+            'present-filled': 'autonomy pointer already present',
+          }[autResult.status];
+          if (autResult.status === 'present-filled') {
+            const u = markerSlotUpgradeHint(finalText, AUTONOMY_DESCRIPTOR);
+            if (u) notes.push(u);
+          }
+        }
+      }
+    }
+
+    // ── One atomic write of the final (three-slot) text ──
     if (finalText === text) {
-      // Byte-unchanged. Still report a cap-skip (it is not "nothing to do" — a pointer was withheld).
-      if (orchSkipped) console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}.`);
-      else console.log('[inject-methodology] reconcile: both pointers already present and filled — nothing to do (zero-diff).');
+      // Byte-unchanged. Still report a skip (it is not "nothing to do" — a pointer was withheld).
+      if (orchSkipped || autSkipped) console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}; ${describeAut}.`);
+      else console.log('[inject-methodology] reconcile: all three pointers already present and filled — nothing to do (zero-diff).');
       reportNotes();
       return;
     }
     await writeAtomic(finalText);
-    console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}.`);
+    console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}; ${describeAut}.`);
     reportNotes();
     return;
   }

package/tools/manifest/schema.md

@@ -18,6 +18,7 @@ expansion), never via the shell. The validator is [`validate.mjs`](./validate.mj
 | `roles` | object | yes | keys ⊆ `provides`; see *Roles* |
 | `detect` | object | no | `installed` (skill on the machine) + `deployed` (substrate set up in cwd) |
 | `settings` | array | no | the bridge's **settings-file surface** (typed; see *Settings*). Unlike `contract`, a malformed entry **fails** `--strict`. |
+| `networkHosts` | string[] | no | the backend CLI's **observed egress host families** (see *Network hosts*). A malformed list **fails** `--strict`. |
 | `install` / `uninstall` | object | no | `install.npm` is a package name, not a path |
 | `cost` / `quota` / `provenance` | misc | no | informational |
 | `available` | boolean | no | `false` = a declared-but-not-installed stub; skips fs/version checks |
@@ -85,6 +86,25 @@ Wrappers never parse JSON at run time: each carries its own shell registry/valid
 drift-guarded set-equal to this block by the bridge `bin/*.test.mjs` suites (help section keys,
 `aw_settings_known` registry, `AW_SETTINGS_APPLIED` subset, `aw_settings_valid` typed arms).
 
+## Network hosts (AD-044 Plan 4, consult-locked)
+
+`networkHosts` declares the hosts the backend CLI is **observed** to contact (synthetic examples:
+`*.api.backend.example`, `accounts.backend.example`; the real observed lists live in each bridge's
+`capability.json`) — the **single documentation
+source** for a hand-applied sandbox/network allowlist (session sandbox config, or a hand-pasted
+`sandbox.network.allowedDomains` entry). Rules:
+
+- Each entry is a bare dotted hostname or a `*.family` wildcard — never a scheme/path/port.
+  Entries must be unique. A malformed list **fails** `--strict` (the entries are pasted verbatim
+  into allowlist lines by the Recommendations advisor).
+- **The kit never seeds these into settings** (bridge council 2026-07-11, both backends concur):
+  a network pre-allow widens egress for **every** sandboxed command, so running the wrappers
+  **outside** the sandbox (`sandbox.excludedCommands`, the `--bridge-tier` wiring) stays the
+  primary lane; the hosts list exists for the **hand-apply** fallback under harness-managed
+  sandboxes where settings-level exclusions are inert.
+- Observed-minimal, honestly incomplete: a blocked host names itself at run time — extend the
+  hand-applied list by hand; the manifest list records what was actually observed.
+
 ## Path-field rules (Windows-safe, traversal-safe)
 
 - **No absolute paths**, **no `..` traversal**, **no unresolved placeholders** (`{{…}}` / `${…}`)

package/tools/manifest/validate.mjs

@@ -63,6 +63,10 @@ export const settingValueValid = (entry, value) => {
 const hasTraversal = (p) => p.split(/[\\/]/).includes('..');
 const isUnresolved = (s) => /\{\{|\}\}|\$\{/.test(s);
 
+// A `networkHosts` entry: a bare dotted hostname, optionally a `*.` family wildcard — never a
+// scheme, a path, a port, or whitespace (the entry is pasted verbatim into an allowlist line).
+export const NETWORK_HOST_RE = /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i;
+
 // Cross-platform "absolute-like": POSIX root (/x), Windows drive (C:\ or C:/), UNC (\\host),
 // or a leading backslash. node:path.isAbsolute() alone is platform-dependent, so a Windows path
 // would slip through unchecked on a POSIX CI runner — Windows-safety requires rejecting both.
@@ -313,6 +317,28 @@ export const validateManifest = (skillDir) => {
     }
   }
 
+  // `networkHosts` (AD-044 Plan 4, consult-locked): the backend CLI's OBSERVED egress host
+  // families — a DOCUMENTATION source for hand-applied sandbox/network allowlists. The kit never
+  // seeds these into settings (exclusion stays primary; a network pre-allow widens egress for
+  // EVERY sandboxed command), but a malformed list FAILS --strict like `settings`: the
+  // Recommendations advisor renders it verbatim, so a bad entry would corrupt a pasted line.
+  const networkHosts = manifest.networkHosts;
+  if (networkHosts != null) {
+    if (!Array.isArray(networkHosts) || networkHosts.length === 0) {
+      errors.push('`networkHosts` must be a non-empty array of host strings');
+    } else {
+      const seenHosts = new Set();
+      networkHosts.forEach((host, i) => {
+        if (typeof host !== 'string' || !NETWORK_HOST_RE.test(host)) {
+          errors.push(`\`networkHosts[${i}]\` must be a bare hostname or a *.family wildcard (${JSON.stringify(host)})`);
+          return;
+        }
+        if (seenHosts.has(host)) errors.push(`duplicate networkHosts entry "${host}" (\`networkHosts[${i}]\`)`);
+        else seenHosts.add(host);
+      });
+    }
+  }
+
   if (!isStub) {
     const auth = readAuthoritativeVersion(skillDir);
     if (auth.version == null) errors.push(`could not resolve an authoritative version (${auth.from})`);