@sabaiway/agent-workflow-kit 1.43.0 → 1.45.0

package/tools/commands.mjs

@@ -28,7 +28,7 @@ const invocationOf = (token) => `${BARE_INVOCATION}${token ? ` ${token}` : ''}`;
 // ── kinds ────────────────────────────────────────────────────────────────────────
 // read-only    — never writes, never commits, never runs a subscription CLI.
 // writer       — writes files (a project deployment or a settings/skill placement).
-// guarded      — a destructive teardown gated behind a mandatory dry-run-first + explicit consent.
+// guarded      — consent-gated destructive/privileged actions (dry-run-first + explicit consent).
 // project-exec — the kit itself writes nothing, but the mode RUNS the project's own declared
 //                commands with the caller's privileges (the `gates` runner) — honest-tagged so a
 //                user never reads "read-only" on a surface that executes their gate matrix.
@@ -98,6 +98,13 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'List every command, grouped, marking each as read-only or as one that makes changes.',
   },
+  {
+    key: 'recommendations',
+    invocation: invocationOf('recommendations'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'See what in this deployment is configured sub-optimally — each item with a one-line benefit and the exact consent-gated command that applies it; renders even when everything is optimal.',
+  },
   {
     key: 'gates',
     invocation: invocationOf('gates'),
@@ -140,6 +147,20 @@ const CATALOG = [
     kind: GUARDED,
     oneLine: 'Read or change the host-level bridge settings (e.g. the codex Fast tier) — a KEY=VALUE file that survives kit upgrades; previews first, and the Fast tier carries its extra-cost caveat.',
   },
+  {
+    key: 'autonomy-doctor',
+    invocation: invocationOf('autonomy-doctor'),
+    group: 'Configure',
+    kind: GUARDED,
+    oneLine: 'Check whether this machine can run the Claude sandbox and, only with your explicit consent, install what is missing — privileged, preview-first, consent-per-run; it never auto-runs and never commits.',
+  },
+  {
+    key: 'sandbox-masks',
+    invocation: invocationOf('sandbox-masks'),
+    group: 'Configure',
+    kind: GUARDED,
+    oneLine: 'Hide the sandbox’s injected device masks from git status via one managed block in the repo’s local exclude file — probe-derived (never a frozen list), preview first, full-block replace on your yes; reviews already ignore the masks by construction.',
+  },
   {
     key: 'recipes',
     invocation: invocationOf('recipes'),
@@ -180,7 +201,7 @@ const CATALOG = [
     invocation: invocationOf('grounding'),
     group: 'Orchestrate',
     kind: WRITER,
-    oneLine: 'Assemble the verified-facts payload a grounded review runs against — the entry-point Hard Constraints plus a plan’s decision sections; prints it, or writes ONE scratch file with --out.',
+    oneLine: 'Assemble the verified-facts payload a grounded review runs against — the entry-point Hard Constraints, the effective autonomy policy, plus a plan’s decision sections; prints it, or writes ONE scratch file with --out.',
   },
   {
     key: 'review-ledger',
@@ -274,7 +295,7 @@ export const formatHelp = () => {
   const lines = [
     `${SKILL_NAME} — command index (this list is read-only)`,
     '',
-    'Each command is tagged read-only · writer (makes changes) · guarded (destructive, previews first) · runs project cmds (executes your own declared commands).',
+    'Each command is tagged read-only · writer (makes changes) · guarded (consent-gated destructive/privileged actions, previews first) · runs project cmds (executes your own declared commands).',
   ];
   for (const group of GROUP_ORDER) {
     const inGroup = COMMANDS.filter((c) => c.group === group);

package/tools/delegation.mjs

@@ -27,6 +27,10 @@ export const EXPECTED_MEMORY_NAME = 'agent-workflow-memory';
 // DOES seed orchestration.json (Mode: upgrade step 3). This closes the stale-memory trap that the
 // read-only family-registry note (MEMORY_ORCH_TEMPLATE_REL) only INFORMS about — the gate ACTS. The
 // two key on the same asset; a cross-tool parity test pins them in lockstep.
+// The autonomy seed (AD-044 Plan 4) is deliberately NOT here: the Plan-3 decision stands — no
+// detectMemory autonomy-marker gate. A memory too old to ship references/templates/autonomy.json
+// stays delegable; the kit-side upgrade ensure seeds the policy from the kit's own template twin,
+// and the family-registry caveat INFORMS about the stale memory (inform, never gate).
 export const REQUIRED_MEMORY_ASSETS = [
   { path: 'references/templates', type: 'dir' },
   { path: 'references/templates/orchestration.json', type: 'file' },
@@ -85,7 +89,7 @@ export const handoffPlan = (delegate) =>
         memoryWrites: ['docs/ai/', 'AGENTS.md', 'docs/ai/.memory-version'],
         // The lens region runs AFTER the substrate deploy (its own precondition: the file exists)
         // — it converges a stale-memory seed to the installed engine's canon (AD-041).
-        kitWrites: ['AGENTS.md methodology slot', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
+        kitWrites: ['AGENTS.md pointer slots (methodology / orchestration / autonomy)', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
         stampsPresent: ['.memory-version', '.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',
@@ -93,11 +97,11 @@ export const handoffPlan = (delegate) =>
     : {
         mode: 'fallback',
         memoryWrites: [],
-        // Fallback now ships the kit's OWN AGENTS.md carrying the EMPTY methodology slot (Plan 2);
-        // the kit reconciles it (ensure-slot + inject-because-empty) exactly like the delegate
-        // path — so both paths end with a FILLED slot, not inline methodology. The lens region
+        // Fallback now ships the kit's OWN AGENTS.md carrying the EMPTY pointer slots (Plan 2);
+        // the kit reconciles them (ensure-slot + inject-because-empty) exactly like the delegate
+        // path — so both paths end with FILLED slots, not inline methodology. The lens region
         // runs after the fallback-template copy of docs/ai (same reconcile, both paths — AD-041).
-        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md methodology slot', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
+        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md pointer slots (methodology / orchestration / autonomy)', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
         stampsPresent: ['.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',

package/tools/detect-backends.mjs

@@ -88,7 +88,7 @@ const RAW_BACKENDS = [
         ],
         grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
         continue: [],
-        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); a write failure warns, never fails the review',
+        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); a write failure warns, never fails the review',
       },
     },
     bin: 'codex',
@@ -121,7 +121,7 @@ const RAW_BACKENDS = [
           'agy-review --continue [--decided @f] [--focus "…"]',
           'agy-review --conversation <id> [--decided @f] [--focus "…"]',
         ],
-        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); a write failure warns, never fails the review",
+        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); a write failure warns, never fails the review",
       },
     },
     bin: 'agy',

package/tools/doc-parity.mjs

@@ -26,11 +26,16 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { SCHEMA_VERSION, REVIEW_CAP, V4_CLASSES, V4_OVERRIDE_SCOPES } from './review-ledger.mjs';
 import { HARD_MAX, DEFAULT_DIFF_CAP } from './review-ledger-write.mjs';
 import { RESULT_SCHEMA_VERSION } from './fold-completeness.mjs';
+import { EXIT as DOCTOR_EXIT, STATUS as DOCTOR_STATUS, TRUSTED_DIRS as DOCTOR_TRUSTED_DIRS } from './autonomy-doctor.mjs';
+import { RECOMMENDATIONS_SECTION_HEADER, RECOMMENDATIONS_EMPTY_LINE } from './recommendations.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
 const REVIEW_LEDGER_DOC = 'references/modes/review-ledger.md';
 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';
 
 // 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 });
@@ -45,6 +50,19 @@ const valueBinding = (constant, value, phrase, files) => ({ constant, value, tok
 // so the closed set can never disagree with the code. Every word must appear in the ledger contract.
 const LEDGER_VOCAB = [...V4_CLASSES, ...V4_OVERRIDE_SCOPES, 'gate-run'];
 
+// The autonomy-doctor D7 contract (AD-044 Plan 2): the live EXIT table + every status token must
+// render into the mode's contract doc. `usage` is skipped as a bare-word token (trivially present
+// everywhere) — its exit-code phrase below pins that outcome instead.
+const DOCTOR_EXIT_PHRASES = [
+  ['ready', `\`${DOCTOR_EXIT.ready}\` ready`],
+  ['stop', `\`${DOCTOR_EXIT.stop}\` precondition STOP`],
+  ['usage', `\`${DOCTOR_EXIT.usage}\` usage`],
+  ['notReady', `\`${DOCTOR_EXIT.notReady}\` not-ready diagnosis`],
+  ['installFailed', `\`${DOCTOR_EXIT.installFailed}\` install failed`],
+  ['verifyFailed', `\`${DOCTOR_EXIT.verifyFailed}\` verify failed`],
+  ['unsupported', `\`${DOCTOR_EXIT.unsupported}\` unsupported / untrusted`],
+];
+
 export const BINDINGS = Object.freeze([
   valueBinding('SCHEMA_VERSION', SCHEMA_VERSION, `schema v${SCHEMA_VERSION}`, [REVIEW_LEDGER_DOC]),
   valueBinding('HARD_MAX', HARD_MAX, `hard-max ceiling of ${HARD_MAX}`, [REVIEW_LEDGER_DOC]),
@@ -52,6 +70,16 @@ export const BINDINGS = Object.freeze([
   valueBinding('REVIEW_CAP', REVIEW_CAP, `cap ≤${REVIEW_CAP}`, [REVIEW_LEDGER_DOC]),
   valueBinding('RESULT_SCHEMA_VERSION', RESULT_SCHEMA_VERSION, `schema v${RESULT_SCHEMA_VERSION}`, [FOLD_DOC]),
   ...LEDGER_VOCAB.map((word) => valueBinding(`vocab:${word}`, word, word, [REVIEW_LEDGER_DOC])),
+  ...DOCTOR_EXIT_PHRASES.map(([key, phrase]) => valueBinding(`doctor-exit:${key}`, DOCTOR_EXIT[key], phrase, [AUTONOMY_DOCTOR_DOC])),
+  ...Object.values(DOCTOR_STATUS)
+    .filter((token) => token !== DOCTOR_STATUS.usage)
+    .map((token) => valueBinding(`doctor-status:${token}`, token, token, [AUTONOMY_DOCTOR_DOC])),
+  valueBinding('doctor-trusted-dirs', DOCTOR_TRUSTED_DIRS.join(':'), DOCTOR_TRUSTED_DIRS.join(':'), [AUTONOMY_DOCTOR_DOC]),
+  // The upgrade Recommendations section contract (AD-044 Plan 4): the section header and the
+  // exact empty-state line must render in BOTH the mode doc and upgrade.md (both exits reference
+  // them) — a reworded doc would silently break the paste-verbatim contract.
+  valueBinding('recommendations-header', RECOMMENDATIONS_SECTION_HEADER, RECOMMENDATIONS_SECTION_HEADER, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
+  valueBinding('recommendations-empty-line', RECOMMENDATIONS_EMPTY_LINE, RECOMMENDATIONS_EMPTY_LINE, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -96,8 +124,9 @@ Usage:
   node doc-parity.mjs [--check | --json]
 
 A CLOSED, exported registry binds each live code constant (review-ledger SCHEMA_VERSION / REVIEW_CAP,
-review-ledger-write HARD_MAX / DEFAULT_DIFF_CAP, fold-completeness RESULT_SCHEMA_VERSION) and the
-ledger vocabulary (V4_CLASSES / V4_OVERRIDE_SCOPES + gate-run) to the exact token its
+review-ledger-write HARD_MAX / DEFAULT_DIFF_CAP, fold-completeness RESULT_SCHEMA_VERSION), the
+ledger vocabulary (V4_CLASSES / V4_OVERRIDE_SCOPES + gate-run), and the autonomy-doctor contract
+(the EXIT table, the status tokens, the trusted-dir allowlist) to the exact token its
 references/modes/*.md contract must carry, and asserts the CURRENT value renders into every bound
 file. A drifted doc, an unreadable bound file, or an absent token FAILS CLOSED.
 

package/tools/engine-source.mjs

@@ -31,6 +31,12 @@ export const ORCHESTRATION_FRAGMENT_REL = 'references/orchestration-slot.md';
 // CLI fail loudly on — an engine too old to ship it. readEngineFragment accepts an arbitrary `rel`
 // (no whitelist), so no further plumbing is needed beyond this constant.
 export const PROCEDURES_FRAGMENT_REL = 'references/procedures.md';
+// The autonomy-policy slot fragment — the THIRD bounded fragment the kit injects (AD-044 Plan 3),
+// the cross-agent read contract for docs/ai/autonomy.json. An engine released before it does not
+// ship it; detectEngine({ rel }) lets the chained reconcile soft-skip that too-old engine (and
+// `status` caveat it) instead of discarding the methodology/orchestration fills. readEngineFragment
+// accepts an arbitrary `rel`, so no further plumbing is needed beyond this constant.
+export const AUTONOMY_FRAGMENT_REL = 'references/autonomy-slot.md';
 // The agent-rules lens pair — the canonical lens block + its append-only prior store (engine
 // >= 1.13.0; an older engine ships neither). The kit's lens-region reconcile live-reads BOTH via
 // readEngineFragment({ rel }); detectEngine({ rel }) lets it soft-skip a too-old engine (and

package/tools/family-registry.mjs

@@ -26,7 +26,7 @@ import { resolveDir, detectBackends, findOnPath } from './detect-backends.mjs';
 import { parseSemver, compareSemver } from './semver-lite.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { START_MARKER, excludePath, inferVisibility } from './hide-footprint.mjs';
-import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL, LENS_FRAGMENT_REL, LENS_PRIORS_REL } from './engine-source.mjs';
+import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL, AUTONOMY_FRAGMENT_REL, LENS_FRAGMENT_REL, LENS_PRIORS_REL } from './engine-source.mjs';
 import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
 // The config reader lives in orchestration-config.mjs (the single config contract). The read-only status
 // settings-survey reuses THIS reader (one strict-JSON + loud-on-malformed contract), not a second copy.
@@ -182,6 +182,7 @@ export const classifyMember = (member, deps = {}) => {
 // caveat keys on both — an engine missing only the prior store must never report healthy.
 const ENGINE_FRAGMENT_CAVEATS = [
   { rels: [ORCHESTRATION_FRAGMENT_REL], caveat: 'engine present but does not supply the recipes pointer (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
+  { rels: [AUTONOMY_FRAGMENT_REL], caveat: 'engine present but does not supply the autonomy pointer (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
   { rels: [PROCEDURES_FRAGMENT_REL], caveat: 'engine present but does not ship the activity-procedures canon (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
   { rels: [LENS_FRAGMENT_REL, LENS_PRIORS_REL], caveat: 'engine present but does not ship the agent-rules lens canon (the fragment + its prior store; too old / incomplete — engine >= 1.13.0) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
 ];
@@ -192,10 +193,16 @@ const ENGINE_FRAGMENT_CAVEATS = [
 // adds a parity drift-guard tying this path to that required-asset set, so the note and the gate can
 // never key on different files (until then they are kept in lockstep by review).
 export const MEMORY_ORCH_TEMPLATE_REL = 'references/templates/orchestration.json';
+// The autonomy-policy seed (AD-044 Plan 4) gets the SAME inform-never-gate treatment: the
+// delegation gate deliberately does NOT key on it (the Plan-3 decision), so this caveat is the
+// discovery mechanism — the recommendations advisor surfaces it via surveyFamily.
+export const MEMORY_AUTONOMY_TEMPLATE_REL = 'references/templates/autonomy.json';
 // Worded as an honest OBSERVATION, not a diagnosis (absence can mean old OR incomplete), and it makes
 // NO claim about an orchestration.json seeding outcome (that depends on delegate-vs-fallback).
 const MEMORY_BEHIND_NOTE =
   "the memory installed here doesn't include the current orchestration template — refresh it with `npx @sabaiway/agent-workflow-memory@latest init`, then restart the session.";
+const MEMORY_AUTONOMY_BEHIND_NOTE =
+  "the memory installed here doesn't include the current autonomy-policy template — refresh it with `npx @sabaiway/agent-workflow-memory@latest init`, then restart the session.";
 
 // ── the bridge freshness probe (deterministic-first — INV-A / INV-B) ─────────────
 // The bridges are not npm packages: their ONLY delivery channel is the copy bundled inside this kit
@@ -261,12 +268,19 @@ export const surveyFamily = (deps = {}) =>
     // Only attach when it is provably ABSENT (a non-ENOENT probe error → 'unknown' → skip, never a
     // false "missing" claim). Mirrors the engine-caveat SHAPE; keyed on the Step-2.4 required asset.
     if (row.kind === 'memory-substrate' && row.manifestState === OK && row.skillDir) {
-      const templateProbe = probeMarker(join(row.skillDir, MEMORY_ORCH_TEMPLATE_REL), deps);
-      if (templateProbe === 'absent') {
-        row.caveats = [...(row.caveats ?? []), MEMORY_BEHIND_NOTE];
-      } else if (templateProbe === 'unknown') {
-        // Could not verify → this row must not be counted "checked, current" by the verdict (INV-B).
-        row.freshness = FRESH_UNKNOWN;
+      // Two required-template probes, same shape: orchestration (Step 2.4) + autonomy (AD-044
+      // Plan 4 — inform, never gate). Each attaches its own caveat on provable absence only.
+      for (const [rel, note] of [
+        [MEMORY_ORCH_TEMPLATE_REL, MEMORY_BEHIND_NOTE],
+        [MEMORY_AUTONOMY_TEMPLATE_REL, MEMORY_AUTONOMY_BEHIND_NOTE],
+      ]) {
+        const templateProbe = probeMarker(join(row.skillDir, rel), deps);
+        if (templateProbe === 'absent') {
+          row.caveats = [...(row.caveats ?? []), note];
+        } else if (templateProbe === 'unknown') {
+          // Could not verify → this row must not be counted "checked, current" by the verdict (INV-B).
+          row.freshness = FRESH_UNKNOWN;
+        }
       }
     }
     // Bridge freshness probe (INV-A / INV-B): only for a provably-OURS placed bridge (manifestState

package/tools/fold-completeness-run.mjs

@@ -1029,6 +1029,11 @@ loud advisory failure) but leaves --check unaffected.
 
 The read-only gate is a SEPARATE tool: node fold-completeness.mjs --check / --status / --json.
 
+Sandbox-safe: the RUNNER itself needs no network and writes only repo-local state (the D4 sandbox
+lane). The spawned suite/bound commands are COMMAND-SHAPE dependent — --suite / AW_FOLD_SUITE_CMD /
+AW_FOLD_BOUND_CMD / the verification profile can name project-defined commands; the default
+(node --test on stdout TAP) is plain and no-network — keep overrides sandbox-safe by shape.
+
 Exit codes: 0 written / advisory printed; 1 a typed STOP (loop derivation / suite discovery / a --red
 or --reattest refusal / a malformed SARIF on --findings / malformed record / fs error); 2 usage.`;
 

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 };