@sabaiway/agent-workflow-kit 1.34.0 → 1.35.0

package/bridges/codex-cli-bridge/bin/codex-review.test.mjs

@@ -679,7 +679,7 @@ describe('codex-review.sh — source-level reverse guard (parser arms ⟷ manife
 // The normative fixture (docs: the AD-038 plan Decisions — copied verbatim; field VALUES with
 // dynamic content are asserted by shape):
 const RECEIPT_FIXTURE = JSON.parse(
-  '{"schema":1,"artifact":"code","fresh":true,"fingerprint":"<sha256hex>","backend":"codex","verdict":"revise","grounded":true,"factsHash":null,"wrapperVersion":"2.2.0","timestamp":"2026-07-03T12:00:00Z"}',
+  '{"schema":1,"artifact":"code","fresh":true,"fingerprint":"<sha256hex>","backend":"codex","verdict":"revise","grounded":true,"factsHash":null,"wrapperVersion":"2.3.0","timestamp":"2026-07-03T12:00:00Z"}',
 );
 const RECEIPTS_REL = join('.git', 'agent-workflow-review-receipts.jsonl');
 const readReceipts = (repo) => {
@@ -799,3 +799,231 @@ describe('codex-review.sh — review receipts (AD-038)', () => {
     assert.equal(receipts.length, 0, 'no review ran — no receipt');
   });
 });
+
+// ── bridge settings file + service tier knob (bridges 2.3.0) ─────────────────────
+// Same contract as codex-exec.test.mjs: KEY=VALUE lines under
+// ${XDG_CONFIG_HOME:-$HOME/.config}/agent-workflow/bridge-settings.conf, parsed never
+// sourced; explicit env (even empty) > file > built-in default. HOME is the sandbox
+// repo, so the default settings path is hermetic per test.
+
+const writeSettings = (sb, text) => {
+  const dir = join(sb.repo, '.config', 'agent-workflow');
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, 'bridge-settings.conf');
+  writeFileSync(file, text);
+  return file;
+};
+const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+
+describe('codex-review.sh — service tier knob (bridges 2.3.0)', () => {
+  it('default: no env, no file → NO service_tier flag in codex argv', () => {
+    const sb = makeSandbox();
+    const r = run(sb);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.argv, /service_tier/, 'default OFF: the flag must be absent');
+    assert.doesNotMatch(r.stderr, /bridge settings/, 'no file → no settings chatter');
+  });
+
+  it('env CODEX_SERVICE_TIER=priority → -c service_tier=priority reaches codex argv', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_SERVICE_TIER: 'priority' } });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.argv, /(^|\n)service_tier=priority(\n|$)/);
+  });
+
+  it('a file-set tier lands (file wins over the built-in default)', () => {
+    const sb = makeSandbox();
+    writeSettings(sb, 'CODEX_SERVICE_TIER=priority\n');
+    const r = run(sb);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.argv, /(^|\n)service_tier=priority(\n|$)/);
+  });
+
+  it('an EXPLICITLY EMPTY env (CODEX_SERVICE_TIER=) disables a file-set tier for one run', () => {
+    const sb = makeSandbox();
+    writeSettings(sb, 'CODEX_SERVICE_TIER=priority\n');
+    const r = run(sb, { env: { CODEX_SERVICE_TIER: '' } });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.argv, /service_tier/, 'env wins over file — empty means knob off');
+  });
+
+  it('an invalid env tier warns and reviews on the standard tier (never passed to codex)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_SERVICE_TIER: 'turbo' } });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /not a supported service tier/);
+    assert.doesNotMatch(r.argv, /service_tier/, 'an unvalidated value must never reach codex');
+  });
+});
+
+describe('codex-review.sh — bridge settings file semantics (bridges 2.3.0)', () => {
+  it('a file-set CODEX_REVIEW_MAX_TOTAL_BYTES is effective (switches to the temp-file path)', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, 'big.txt'), 'B'.repeat(5000));
+    writeSettings(sb, 'CODEX_REVIEW_MAX_TOTAL_BYTES=100\n');
+    const r = run(sb);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.capStdin, /codex-review-diff\./, 'the tiny file cap must force the temp-file path');
+    assert.doesNotMatch(r.capStdin, /ASSEMBLED CHANGE SET:/, 'the payload must not ALSO ride inline');
+  });
+
+  it('env overrides file: a large env cap keeps the payload inline', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, 'big.txt'), 'B'.repeat(5000));
+    writeSettings(sb, 'CODEX_REVIEW_MAX_TOTAL_BYTES=100\n');
+    const r = run(sb, { env: { CODEX_REVIEW_MAX_TOTAL_BYTES: '5000000' } });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.capStdin, /ASSEMBLED CHANGE SET:/, 'the env cap (large) must win over the file cap (100)');
+    assert.doesNotMatch(r.capStdin, /codex-review-diff\./);
+  });
+
+  it('duplicate key → the LAST occurrence wins (100 then 5000000 → inline)', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, 'big.txt'), 'B'.repeat(5000));
+    writeSettings(sb, 'CODEX_REVIEW_MAX_TOTAL_BYTES=100\nCODEX_REVIEW_MAX_TOTAL_BYTES=5000000\n');
+    const r = run(sb);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.capStdin, /ASSEMBLED CHANGE SET:/);
+  });
+
+  it("another wrapper's / another bridge's valid key is skipped silently", () => {
+    const sb = makeSandbox();
+    writeSettings(sb, 'AGY_HARD_TIMEOUT=30m\nAGY_REVIEW_ALLOW_ADDDIR=1\n');
+    const r = run(sb);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.stderr, /bridge settings/, 'a recognized non-applied key earns NO warning');
+  });
+
+  it('a truly unknown key warns ONCE naming the file; the review is unaffected', () => {
+    const sb = makeSandbox();
+    writeSettings(sb, 'TOTALLY_UNKNOWN=1\nTOTALLY_UNKNOWN=2\n');
+    const r = run(sb);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    const warns = r.stderr.match(/unknown key 'TOTALLY_UNKNOWN'/g) ?? [];
+    assert.equal(warns.length, 1, `exactly one warning per unknown key, got ${warns.length}`);
+    assert.match(r.stderr, /bridge-settings\.conf/, 'the warning must name the settings file');
+  });
+
+  it('malformed lines warn and are ignored; comments and blank lines are silent', () => {
+    const sb = makeSandbox();
+    writeSettings(sb, '# a comment\n\nNOT A KEY VALUE LINE\nCODEX_SERVICE_TIER=priority\n');
+    const r = run(sb);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    const malformed = r.stderr.match(/malformed line/g) ?? [];
+    assert.equal(malformed.length, 1, 'comments/blank lines must NOT count as malformed');
+    assert.match(r.argv, /(^|\n)service_tier=priority(\n|$)/, 'valid lines still apply');
+  });
+
+  it('an existing-but-unreadable file warns loudly and falls back to built-ins', { skip: isRoot }, () => {
+    // The settings file goes OUTSIDE the repo (XDG_CONFIG_HOME): an unreadable file INSIDE the
+    // work tree would fail the review-payload assembly itself (untracked contents are cat'ed),
+    // which is pre-existing behaviour unrelated to the settings reader.
+    const sb = makeSandbox();
+    const xdg = join(sb.root, 'xdg');
+    mkdirSync(join(xdg, 'agent-workflow'), { recursive: true });
+    const file = join(xdg, 'agent-workflow', 'bridge-settings.conf');
+    writeFileSync(file, 'CODEX_SERVICE_TIER=priority\n');
+    chmodSync(file, 0o000);
+    const r = run(sb, { env: { XDG_CONFIG_HOME: xdg } });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /unreadable/);
+    assert.doesNotMatch(r.argv, /service_tier/, 'an unreadable file must yield built-in defaults');
+  });
+
+  it('a settings line can NEVER execute code (command-substitution payload inert)', () => {
+    const sb = makeSandbox();
+    const pwned = join(sb.repo, 'pwned');
+    const pwned2 = join(sb.repo, 'pwned2');
+    writeSettings(
+      sb,
+      `CODEX_SERVICE_TIER=$(touch ${pwned})\nEVIL_KEY=\`touch ${pwned2}\`\n`,
+    );
+    const r = run(sb);
+    const executed = existsSync(pwned) || existsSync(pwned2);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(executed, false, 'file content must be parsed, never evaluated');
+    assert.doesNotMatch(r.argv, /service_tier/, 'the payload value must fail validation');
+  });
+
+  it('a DIRECTORY at the settings path warns loudly and falls back to built-ins (no crash)', () => {
+    // Outside the repo (XDG) — an unreadable path INSIDE the work tree would fail the
+    // review-payload assembly itself (pre-existing behaviour, unrelated to the reader).
+    const sb = makeSandbox();
+    const xdg = join(sb.root, 'xdg');
+    mkdirSync(join(xdg, 'agent-workflow', 'bridge-settings.conf'), { recursive: true });
+    const r = run(sb, { env: { XDG_CONFIG_HOME: xdg } });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, `a directory must degrade honestly, not kill the run: ${r.stderr}`);
+    assert.match(r.stderr, /unreadable or not a regular file/);
+    assert.doesNotMatch(r.stderr, /Is a directory/, 'no raw bash error may leak');
+  });
+});
+
+// ── settings surface ⟷ manifest (drift guard, D6) — same contract as codex-exec ──
+const SETTINGS_HEADER = 'Settings file (KEY=VALUE, parsed never sourced; env wins over file, file wins over built-in default):';
+const SIBLING_MANIFEST = JSON.parse(readFileSync(join(HERE, '..', '..', 'antigravity-cli-bridge', 'capability.json'), 'utf8'));
+const ALL_SETTINGS = [...(MANIFEST.settings ?? []), ...(SIBLING_MANIFEST.settings ?? [])];
+const SETTINGS_CMD = 'codex-review';
+
+describe('codex-review.sh — settings surface ⟷ manifest (D6, manifest-pinned)', () => {
+  it('--help Settings section keys set-EQUAL the manifest appliesTo subset', () => {
+    const help = runHelp('--help').stdout;
+    const section = helpSection(help, SETTINGS_HEADER);
+    const got = section.filter((l) => /^[A-Z][A-Z0-9_]+ —/.test(l)).map((l) => l.split(' ')[0]);
+    const want = (MANIFEST.settings ?? []).filter((s) => s.appliesTo.includes(SETTINGS_CMD)).map((s) => s.key);
+    assert.ok(want.length > 0, 'the manifest must declare settings for this wrapper');
+    setEq(got, want, 'help Settings keys ⟷ manifest settings.appliesTo');
+    assert.ok(section.some((l) => l.includes('agent-workflow/bridge-settings.conf')), 'the section names the settings file');
+  });
+
+  const source = readFileSync(WRAPPER, 'utf8');
+
+  it('aw_settings_known carries exactly the UNION of both bridges settings keys', () => {
+    const m = source.match(/aw_settings_known\(\) \{\n  case " ([^"]+) " in/);
+    assert.ok(m, 'aw_settings_known registry case not found');
+    assert.ok(ALL_SETTINGS.length >= 5, 'both manifests must contribute settings');
+    setEq(m[1].trim().split(/\s+/), ALL_SETTINGS.map((s) => s.key), 'shell registry ⟷ manifest union');
+  });
+
+  it('AW_SETTINGS_APPLIED equals the manifest appliesTo subset for this wrapper', () => {
+    const m = source.match(/^AW_SETTINGS_APPLIED="([^"]*)"$/m);
+    assert.ok(m, 'AW_SETTINGS_APPLIED not found');
+    const want = ALL_SETTINGS.filter((s) => s.appliesTo.includes(SETTINGS_CMD)).map((s) => s.key);
+    assert.ok(want.length > 0);
+    setEq(m[1].trim().split(/\s+/), want, 'applied subset ⟷ manifest appliesTo');
+  });
+
+  it('aw_settings_valid arms carry the manifest typed constants per key', () => {
+    const body = source.match(/aw_settings_valid\(\) \{[\s\S]*?\n\}/);
+    assert.ok(body, 'aw_settings_valid not found');
+    const armKeys = [...body[0].matchAll(/^    ([A-Z][A-Z0-9_]*)\)/gm)].map((x) => x[1]);
+    setEq(armKeys, ALL_SETTINGS.map((s) => s.key), 'validation arms ⟷ manifest keys');
+    for (const s of ALL_SETTINGS) {
+      const arm = body[0].match(new RegExp(`^    ${s.key}\\) (.*) ;;$`, 'm'));
+      assert.ok(arm, `no validation arm for ${s.key}`);
+      if (s.kind === 'enum') for (const v of s.values) assert.ok(arm[1].includes(`"${v}"`), `${s.key}: enum value '${v}' not pinned`);
+      if (s.kind === 'integer') {
+        assert.match(arm[1], new RegExp(`>= ${s.min}\\b`), `${s.key}: min ${s.min} not pinned`);
+        assert.match(arm[1], new RegExp(`<= ${s.max}\\b`), `${s.key}: max ${s.max} not pinned`);
+      }
+      if (s.kind === 'boolean') assert.ok(arm[1].includes('"0"') && arm[1].includes('"1"'), `${s.key}: boolean 0/1 not pinned`);
+      if (s.kind === 'duration') {
+        assert.ok(arm[1].includes('$dur_re'), `${s.key}: duration grammar not pinned`);
+        assert.ok(arm[1].includes('$zero_re'), `${s.key}: zero-duration rejection not pinned (timeout 0 disables the cap)`);
+      }
+    }
+  });
+});

package/bridges/codex-cli-bridge/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "codex-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "provides": ["execute", "review"],
   "roles": {
     "execute": {
@@ -43,6 +43,34 @@
       }
     }
   },
+  "settings": [
+    {
+      "key": "CODEX_SERVICE_TIER",
+      "kind": "enum",
+      "values": ["priority"],
+      "default": null,
+      "appliesTo": ["codex-exec", "codex-review"],
+      "effect": "codex service tier; 'priority' (catalog display name Fast) = ~1.5x token speed at a 2.5x credit rate on gpt-5.5 — quality-neutral (same model), live-probed 2026-07-05. Unset/empty ⇒ no service_tier flag (standard tier). SPEND KNOB: enabling it is a consented per-host act, never a default. codex itself accepts any -c service_tier string silently, so the wrapper validates the value."
+    },
+    {
+      "key": "CODEX_HARD_TIMEOUT",
+      "kind": "integer",
+      "min": 1,
+      "max": 86400,
+      "default": null,
+      "appliesTo": ["codex-exec", "codex-review"],
+      "effect": "hard wall-clock cap in seconds via timeout(1); built-in default 3600 (codex-exec) / 1800 (codex-review)."
+    },
+    {
+      "key": "CODEX_REVIEW_MAX_TOTAL_BYTES",
+      "kind": "integer",
+      "min": 1,
+      "max": 100000000,
+      "default": "1500000",
+      "appliesTo": ["codex-review"],
+      "effect": "codex-review code: above this assembled-payload size (bytes) the diff rides via a git-dir temp file instead of inline — never truncated."
+    }
+  ],
   "detect": {
     "installed": {
       "env": "CODEX_CLI_BRIDGE_DIR",

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/bridge-settings.md

@@ -0,0 +1,29 @@
+### Mode: bridge-settings
+
+The reader + consent-gated **writer** for the **host-level** bridge settings file — the answer to *"turn on the codex Fast tier (or another bridge knob) once, predictably, so it survives kit upgrades."* The four bridge wrappers read `${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf` (`KEY=VALUE` lines, **parsed never sourced**); this is the ONLY writer for it. The file lives **outside every kit-managed tree**, so a kit refresh never writes or clobbers it — upgrade-survival is structural (D2). It **previews by default**; `--apply` writes. Hand-editing the file stays fully supported — this is an offered convenience, never a lock.
+
+**The knobs are the bundled bridges' own `settings` blocks** (manifest-as-source, D6) — the tool never invents a key or a value rule, and what it writes always passes the wrappers' own validation. Model/effort are **NOT** settable here (the wrappers' quality-first guard is untouched, D4). Run **`node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs`** to see the live list; today:
+
+| key | bridge | values | note |
+|---|---|---|---|
+| `CODEX_SERVICE_TIER` | codex | `priority` | **SPEND KNOB** — the "Fast" tier: ~1.5× token speed at a **2.5× credit rate** on gpt-5.5, quality-neutral (same model). Default unset ⇒ standard tier. |
+| `CODEX_HARD_TIMEOUT` | codex | integer `1..86400` | hard wall-clock cap (seconds) via `timeout(1)`. |
+| `CODEX_REVIEW_MAX_TOTAL_BYTES` | codex | integer `1..100000000` | codex-review payload size above which the diff rides a temp file (never truncated). |
+| `AGY_HARD_TIMEOUT` | agy | duration `5m`/`30m`/`90s` (unit required, nonzero) | hard wall-clock cap via `timeout(1)`. |
+| `AGY_REVIEW_ALLOW_ADDDIR` | agy | `0` \| `1` | `1` re-enables the oversized-review `--add-dir` offload (Issue-001 stall risk, bounded by the timeout). |
+
+**Invocations:**
+
+1. **Read** — `node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs [--json]` prints every knob's **effective value + source** (`env` / `file` / `default`) and flags any unknown/duplicate/malformed lines. Read-only.
+2. **Preview a change** — `--set KEY=VALUE` (or `--unset KEY`) prints `before → after` and writes **nothing**. Re-run with **`--apply`** to write. Multiple `--set`/`--unset` ops apply in one atomic write.
+3. **`--apply`** writes via the hardened out-of-tree atomic writer (creates the dir + file on first use; symlink/parent/TOCTOU-safe; last-writer-wins). It touches **only** the `KEY=` line it owns — every comment / blank / other line is preserved verbatim.
+
+**Precedence at run time:** explicit env (even empty — `KEY=` disables the knob for one run) **>** this file **>** the wrapper's built-in default. So an operator can always override one run without editing the file; the reader shows which source wins.
+
+**Refusals (the guarded contract):** an **unknown key** or an **invalid / out-of-range value** → exit `2` (nothing read of the file, nothing written). A file that already carries **duplicate keys** → exit `1`, named and left **byte-untouched** (fix the duplicates by hand first — the writer never edits blindly around them). A **symlinked / non-regular / unreadable** settings file → exit `1` (refuses to write through it). `--apply` with `--dry-run`, a duplicate op for one key, or a malformed `--set` → usage exit `2`.
+
+**Spend consent (D4):** enabling `CODEX_SERVICE_TIER=priority` costs a **2.5× credit rate** — a per-host, consented act, never a default. The preview shows the caveat (from the manifest `effect`); confirm with the user before `--apply`. The tool also warns when an env var currently shadows the key you are writing (the env value wins for that session until unset).
+
+Output is **English/structured** — **localize it to the user's conversational language** when you narrate.
+
+**Invariants:** writer (writes only the host settings file — outside any project/kit tree) · never commits · never runs a subscription CLI · previews by default · allowlist + value rules from the bundled manifests · model/effort never settable · the host file survives every kit refresh.

package/references/modes/upgrade.md

@@ -45,12 +45,18 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    file's line cap — refused** (trim the file, re-run). The section is found by its heading — no
    markers; a renamed heading is preserved + noted. A fully absent/invalid engine is the same hard
    STOP as (c). Exit 0 covers every soft outcome; only the STOP is non-zero.
+
+   **Bridge settings reconcile — stamp-independent, same gate, BEFORE the equal-head short-circuit.**
+   Run `node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs --reconcile` and **paste its outcome line
+   verbatim**: it validates the deployed host settings file's keys against the bundled manifests and
+   **NEVER writes** it (the file lives outside every kit tree — D2), so an unknown/retired key is
+   flagged + preserved, never edited. Runs on **every** upgrade; exit 0 covers every outcome.
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the stamp-independent reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
-   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); whether the `docs/ai/gates.json` gate declaration was *seeded* or was *already present* (preserved byte-for-byte); whether the enforcement-script ensure *added* the `archive-decisions` pair to `scripts/` or found it *already present*; the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / *could not refresh* + recovery); the **agent-rules lens** outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
+   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); whether the `docs/ai/gates.json` gate declaration was *seeded* or was *already present* (preserved byte-for-byte); whether the enforcement-script ensure *added* the `archive-decisions` pair to `scripts/` or found it *already present*; the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / *could not refresh* + recovery); the **agent-rules lens** outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*); the **bridge-settings reconcile** outcome (paste the tool's line verbatim); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
    - **Never surface the structure number on this exit.** Whatever step 3 did, do **not** recite the `docs/ai` structure version, the internal versioning vocabulary, or the two-axes note here — the number is inert on an equal-head exit; it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md` (shown at the never-downgrade STOP, the explicit status view, or on an explicit ask). Frame the success itself per the final bullet: if step 3 changed anything, say **what changed** in plain human terms; only a pure zero-diff no-op is *settings already current — no update needed*.
    - **Print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity` / `agents` / `hook`).
    - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, give the plain **settings already current — no update needed** message (the *Success state* contract in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`) and still print the read-only version block (installed package versions) + backend line — but **no `docs/ai` structure version and no two-axes note** (nothing changed, so the number is inert here).
 5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
 6. **Collect the migration answers FIRST, then apply.** If `AGENTS.md` is missing BOTH the *Communication language* and *Attribution* blocks — i.e. both blocks are missing (a pre-1.1.0 deployment) — ask the two questions as ONE structured multi-question prompt; record each answer individually, write nothing until ALL are answered, and carry the answers into the migrations below: a migration whose answer was already collected never re-asks (its own "Ask the user" step is the standalone fallback); a single missing block keeps its single ask (step 7). Then apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
 7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`. (An answer already collected by the step-6 batched prompt is carried in — never re-asked here.)
-8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 **placed-bridge refresh** lines (pasted verbatim) and the step-3 **agent-rules lens** outcome (same outcome set as step 4) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, on demand only). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing**.
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 **placed-bridge refresh** lines (pasted verbatim), the step-3 **agent-rules lens** outcome (same outcome set as step 4), and the step-3 **bridge-settings reconcile** outcome — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, on demand only). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing**.

package/tools/atomic-write.mjs

@@ -1,15 +1,19 @@
-// atomic-write.mjs — the family's ONE hardened atomic-write core for kit writers that target a
-// file under a project's docs/ai/. Extracted from orchestration-write.mjs (the only full
-// implementation of the discipline, AD-042) and parameterized by (rel, body, stop identity) so
-// BOTH consumers run the same guarded flow with zero drift:
-//   • orchestration-write.mjs — docs/ai/orchestration.json (public API unchanged);
-//   • seed-gates.mjs          — docs/ai/gates.json (the consent-gated seeder).
+// atomic-write.mjs — the family's ONE hardened atomic-write core for kit writers. Extracted from
+// orchestration-write.mjs (the only full implementation of the discipline, AD-042) and parameterized
+// by (containment ROOT, absolute target, body, stop identity) so every consumer runs the same guarded
+// flow with zero drift:
+//   • writeDocsAiFileAtomic  — a file under a project's docs/ai/ (deployment-gated to cwd):
+//       orchestration-write.mjs → docs/ai/orchestration.json; seed-gates.mjs → docs/ai/gates.json.
+//   • writeHostConfigFileAtomic — a file under a host config dir OUTSIDE any project tree
+//       (bridges 2.3.0, D6): ${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf. The
+//       host dir is CREATED if absent (a host config SHOULD materialize), unlike the docs/ai gate
+//       which REFUSES an absent deployment.
 //
-// The discipline (verbatim from the source implementation):
-//   - DEPLOYMENT GATE first: refuse to scatter a file into a repo with no docs/ai/ — STOP loud.
+// The discipline (verbatim from the source implementation) — writeContainedFileAtomic(root, dst, …):
+//   - a per-consumer GATE runs first (deployment gate for docs/ai; create+verify for the host dir).
 //   - refuse a SYMLINKED leaf — a rename would silently replace the link target.
 //   - guard the dst + the tmp sibling with assertContainedRealPath (fs-safe) — refuses a symlinked
-//     docs/ or docs/ai/ PARENT, not just the leaf, and refuses any escape outside cwd.
+//     PARENT component inside `root`, not just the leaf, and refuses any escape outside `root`.
 //   - atomic: write a UNIQUE *.<rand>.tmp opened EXCLUSIVE-CREATE (wx), then rename over the dst.
 //   - RE-CHECK the parent chain + the leaf immediately before the rename (TOCTOU).
 //   - tmp cleaned up on any failure after its creation.
@@ -18,7 +22,7 @@
 // Dependency-free, Node >= 18. Every fs primitive is injectable (deps.*) so the guards are
 // unit-testable. NEVER imported by a read-only module (procedures.mjs — pinned by an import guard).
 
-import { lstatSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { lstatSync, writeFileSync, renameSync, rmSync, mkdirSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { join } from 'node:path';
 import { assertContainedRealPath } from './fs-safe.mjs';
@@ -61,28 +65,42 @@ export const assertDocsAiDeployment = (cwd, deps = {}, opts = {}) => {
   }
 };
 
-// writeDocsAiFileAtomic(cwd, rel, body, deps, opts) → { writtenPath: rel } on success; THROWS the
-// caller's typed STOP (via opts.stop) or a native fs error otherwise. `body` arrives pre-serialized
-// (each consumer owns its canonical serialization).
-export const writeDocsAiFileAtomic = (cwd, rel, body, deps = {}, opts = {}) => {
+// Host config dir gate — CREATE the dir if absent (a host config SHOULD materialize on first write,
+// the opposite of the docs/ai deployment gate), then refuse a symlinked / non-directory dir we would
+// write THROUGH (a rename into a symlinked dir would land outside where the user thinks). `noun` names
+// what the caller writes so each consumer's STOP message stays exactly as its own tests pinned it.
+export const assertHostConfigDirSafe = (dir, deps = {}, opts = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const mkdir = deps.mkdir ?? ((p) => mkdirSync(p, { recursive: true }));
+  const stop = opts.stop ?? defaultStop;
+  const noun = opts.noun ?? 'a host config file';
+  mkdir(dir);
+  const st = lstatNoFollow(dir, lstat);
+  if (st === null) throw stop(`could not create the host config dir: ${dir}`);
+  if (st.isSymbolicLink()) throw stop(`${dir} is a symlink — refusing to write ${noun} through it`);
+  if (!st.isDirectory()) throw stop(`${dir} exists but is not a directory — refusing to write ${noun}`);
+};
+
+// The hardened atomic flow, parameterized by containment ROOT + an already-passed gate. `dst` is the
+// ABSOLUTE target under `root`; `opts.label` names it in a symlink-refusal message. Returns
+// { writtenPath: dst }. THROWS the caller's typed STOP (opts.stop) or a native fs error.
+export const writeContainedFileAtomic = (root, dst, body, deps = {}, opts = {}) => {
   const lstat = deps.lstat ?? lstatSync;
   const writeFile = deps.writeFile ?? writeFileSync;
   const rename = deps.rename ?? renameSync;
   const rm = deps.rm ?? ((p) => rmSync(p, { force: true }));
   const rand = deps.rand ?? (() => randomBytes(6).toString('hex'));
   const stop = opts.stop ?? defaultStop;
-  const guard = (target) => assertContainedRealPath(cwd, target, { lstat });
+  const label = opts.label ?? dst;
+  const guard = (target) => assertContainedRealPath(root, target, { lstat });
 
-  assertDocsAiDeployment(cwd, deps, { ...opts, rel });
-
-  const dst = join(cwd, rel);
   // Refuse a symlinked leaf with a CLEAR message before the generic traversal guard fires (a rename
   // would silently replace the link rather than the file the user thinks they are editing).
   const leaf = lstatNoFollow(dst, lstat);
   if (leaf && leaf.isSymbolicLink()) {
-    throw stop(`${rel} is a symlink — refusing to replace it (a write would clobber the link target)`);
+    throw stop(`${label} is a symlink — refusing to replace it (a write would clobber the link target)`);
   }
-  // Guard the dst + a unique tmp SIBLING: refuses a symlinked docs/ or docs/ai/ parent, and any escape.
+  // Guard the dst + a unique tmp SIBLING: refuses a symlinked parent component inside root, and any escape.
   guard(dst);
   const tmp = `${dst}.${rand()}.tmp`;
   guard(tmp);
@@ -95,12 +113,32 @@ export const writeDocsAiFileAtomic = (cwd, rel, body, deps = {}, opts = {}) => {
     guard(dst);
     const leafAgain = lstatNoFollow(dst, lstat);
     if (leafAgain && leafAgain.isSymbolicLink()) {
-      throw stop(`${rel} became a symlink — refusing to replace it`);
+      throw stop(`${label} became a symlink — refusing to replace it`);
     }
     rename(tmp, dst);
   } catch (err) {
     rm(tmp); // never leave a temp file behind on failure
     throw err;
   }
+  return { writtenPath: dst };
+};
+
+// writeDocsAiFileAtomic(cwd, rel, body, deps, opts) → { writtenPath: rel } on success; THROWS the
+// caller's typed STOP (via opts.stop) or a native fs error otherwise. `body` arrives pre-serialized
+// (each consumer owns its canonical serialization). Thin wrapper over the core: gate = deployment
+// gate, root = cwd, target = cwd/rel; the label + return stay `rel` so its public API is unchanged.
+export const writeDocsAiFileAtomic = (cwd, rel, body, deps = {}, opts = {}) => {
+  assertDocsAiDeployment(cwd, deps, { ...opts, rel });
+  const dst = join(cwd, rel);
+  writeContainedFileAtomic(cwd, dst, body, deps, { ...opts, label: rel });
   return { writtenPath: rel };
 };
+
+// writeHostConfigFileAtomic(dir, filename, body, deps, opts) → { writtenPath: dir/filename }. Gate =
+// create+verify the host dir; root = that dir; target = dir/filename. For the out-of-tree host config
+// surface (bridge-settings.conf) that no project deployment owns.
+export const writeHostConfigFileAtomic = (dir, filename, body, deps = {}, opts = {}) => {
+  assertHostConfigDirSafe(dir, deps, opts);
+  const dst = join(dir, filename);
+  return writeContainedFileAtomic(dir, dst, body, deps, { ...opts, label: opts.label ?? dst });
+};