create-agentic-workspace 0.11.0 → 0.13.0

package/README.md

@@ -33,6 +33,11 @@ it does invoke `claude` (bounded by a closed allowlist — see its own README).
 - Scaffolds a seven-file, schema-valid workspace seed.
 - Re-running is a **reconcile with a drift report** — an edited managed file is reported
   `drifted` and left byte-identical, never overwritten. Never-clobber is unconditional.
+- `.gitignore` gets its own narrower reconcile on top of that: the file also carries a
+  `FOUNDRY-RUNTIME-GITIGNORE-BEGIN`/`-END` managed block, converged independently of the
+  whole-file compare above (so an adopter's own surrounding lines never block it from catching
+  up) — reported `[converged]`, `[unchanged]`, or, for a malformed sentinel state or a symlinked
+  `.gitignore`, `[refused]` and left untouched.
 
 ## Flags
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-workspace",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "The pre-session bootstrap wizard for an Agentic Foundry workspace: declares (never grants) the permission floor, absorbs foundry-bootstrap.sh's out-of-session identity wiring, and scaffolds a seven-file schema-valid workspace. Zero dependencies, no lifecycle scripts, no telemetry.",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,7 @@
     "marketplace_name": "agentic-foundry",
     "marketplace_repo": "lukasrepublic/agentic-foundry",
     "plugin_name": "foundry",
-    "plugin_version": "1.11.0",
+    "plugin_version": "1.13.0",
     "pins_researched": "2026-08-02"
   }
 }

package/permission-floor.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "plugin_root_glob": "~/.claude/plugins/cache/*/foundry/*",
-  "generated_for_plugin_version": "1.11.0",
+  "generated_for_plugin_version": "1.13.0",
   "entries": [
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-acceptance-contract-validate.py:*)",
@@ -103,6 +103,21 @@
       "tier": "allow",
       "rationale": "SessionStart injection directive over the native Tasks list; no external writes"
     },
+    {
+      "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-permissions-compile.py --check:*)",
+      "tier": "allow",
+      "rationale": "read-only drift check over .foundry/permissions.yaml vs .claude/settings.json; never writes"
+    },
+    {
+      "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-permissions-compile.py --write:*)",
+      "tier": "ask",
+      "rationale": "reconciles .claude/settings.json permissions.allow/ask from the operator-owned .foundry/permissions.yaml; a ceremony, not a self-grant"
+    },
+    {
+      "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-capability-preflight.py:*)",
+      "tier": "allow",
+      "rationale": "feat-foundry-authorization-capability-preflight-at-dispatch (AC-CPD-1): reads a contract/charter's requires_capabilities plus the effective settings.json/settings.local.json/user-scope settings and .foundry/permissions.yaml, prints one JSON verdict; never edits settings or the policy"
+    },
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-prepublication-leak-scan.py:*)",
       "tier": "allow",
@@ -158,6 +173,11 @@
       "tier": "allow",
       "rationale": "worktree wrapper, workspace-root-confined by construction; consumed by WorktreeCreate + dispatch"
     },
+    {
+      "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry_blocker_check.py:*)",
+      "tier": "allow",
+      "rationale": "deterministic blocker-shape lint (feat-foundry-blocker-requires-evidence): reads its --in argument, partitions candidate blockers against schema/blocker.schema.json, prints a JSON verdict; writes nothing"
+    },
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry_ceremony_tier.py:*)",
       "tier": "allow",
@@ -248,6 +268,11 @@
       "tier": "ask",
       "rationale": "pinned ceremony (AC-PFM-3): documented no-op today, but the flag is the shape a future auto-heal would reuse"
     },
+    {
+      "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-merge-when-green.py:*)",
+      "tier": "ask",
+      "rationale": "issues gh pr merge <pr> --squash once every check is green — a merge is a repo-state mutation, ask like foundry-authorize.py/foundry-amend.py, never a self-grant"
+    },
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-project-sync.py:*)",
       "tier": "ask",
@@ -325,6 +350,10 @@
     }
   ],
   "not_invoked": [
+    {
+      "script": "foundry_shell_scan.py",
+      "rationale": "library: no argparse/__main__; the stdlib shell tokenizer imported by the two PreToolUse(Bash) guards (guard-structured-observations)"
+    },
     {
       "script": "foundry_audit_ledger.py",
       "rationale": "library: no argparse/__main__; imported by foundry-audit-record.py for the ledger schema/writer"

package/src/gitignoreReconcile.mjs

@@ -0,0 +1,278 @@
+// gitignoreReconcile.mjs — feat-gitignore-block-reconcile (ER #177, AC-GBR-1..5).
+//
+// `.gitignore` is one of scaffold.mjs's six template-derived managed files, so it already goes
+// through the whole-file never-clobber plan in reconcile.mjs: absent -> `create`, byte-identical ->
+// `unchanged`, anything else -> `drifted` and NEVER WRITTEN. That is correct for a file an adopter
+// never touches, but `.gitignore` is NOT one of those — the template ships adopter-visible content
+// (Risk #5's local-settings comment) around a FOUNDRY-RUNTIME-GITIGNORE-BEGIN/END block that is
+// framework-owned. Once an adopter's `.gitignore` carries its own lines too, the whole-file compare
+// reports `drifted` forever and the sentinel block — the one piece ER #169 needed every existing
+// workspace to receive — never converges on an `--existing` reconcile or an upgrade run.
+//
+// This module is scoped to EXACTLY that block's INTERIOR, the same way floorReconcile.mjs is
+// scoped to the `permissions` key inside settings.json: converge the interior lines between the
+// sentinels, leave every other line byte-identical — INCLUDING the target's own BEGIN/END sentinel
+// lines, whatever their exact text — and never touch the file at all when the interior already
+// matches (AC-GBR-4). The sentinel lines themselves are deliberately never rewritten once a block
+// exists: `cli/templates/gitignore.tmpl` ships them BARE (no annotation) while the shipped bash
+// applier writes them ANNOTATED, and every bootstrapped workspace in practice carries the
+// annotated form (PR #179 review) — replacing whole lines including the sentinels made this
+// module and the bash applier flip a workspace's sentinel text back and forth on alternating
+// runs, never settling. See loadDesiredInterior's own comment.
+//
+// It deliberately does NOT port scripts/foundry-apply-runtime-gitignore.sh's Risk #9/#10
+// deviation-line relocation — that machinery answers "does an adopter rule silently defeat a
+// re-include", which is out of scope here (see the charter's Out of scope): this module only
+// answers "does the managed block's interior match the template", and reports converged either way.
+import fs from 'node:fs';
+import path from 'node:path';
+import { confinedJoin, RefusalError } from './util.mjs';
+
+export const BEGIN_TOKEN = 'FOUNDRY-RUNTIME-GITIGNORE-BEGIN';
+export const END_TOKEN = 'FOUNDRY-RUNTIME-GITIGNORE-END';
+
+// The shipped bash applier's OWN sentinel line text (scripts/foundry-apply-runtime-gitignore.sh's
+// `BEGIN_LINE`/`END_LINE`, copied verbatim) — used ONLY when APPENDING a brand-new block (no
+// sentinel found at all). `cli/templates/gitignore.tmpl` ships the BARE form (no annotation) for
+// the scaffold's own fresh-create path, so the two tools' sentinel LINE TEXT already disagrees by
+// design; `planGitignoreBlock` below never rewrites an EXISTING sentinel line for exactly that
+// reason (see its own comment) — but a freshly-appended block has no prior sentinel to preserve,
+// and writing the bash applier's own annotated form here is what lets both tools settle on the
+// SAME text from that point on, rather than each converting the other's form back to its own on
+// alternating runs.
+export const ANNOTATED_BEGIN_LINE = `# ${BEGIN_TOKEN} (managed by scripts/foundry-apply-runtime-gitignore.sh -- do not edit by hand)`;
+export const ANNOTATED_END_LINE = `# ${END_TOKEN} (re-run the applier to converge; do not edit by hand)`;
+
+/** Split raw file text into a line array with NO trailing empty element for a final newline (a
+ * file ending "a\nb\n" and one ending "a\nb" both split to ['a','b'] — the asymmetry is resolved on
+ * WRITE, not on read: see writeGitignoreAtomically, which always terminates every line, mirroring
+ * the shipped bash applier's own `write_output` (`printf '%s\n'` per line, unconditionally). A file
+ * this module never writes (the `unchanged` action) is never re-serialized at all, so an original
+ * file missing its final newline is left completely alone — this normalization only ever applies to
+ * bytes this module itself is already rewriting. */
+function splitLines(raw) {
+  if (raw === '') return [];
+  const body = raw.endsWith('\n') ? raw.slice(0, -1) : raw;
+  return body.split('\n');
+}
+
+/** Scan a line array for the sentinel pair, exactly mirroring the shipped applier's
+ * `scan_sentinels` malformed-state checks (AC-GBR-3), plus a stricter "at most one block" rule this
+ * atom's own charter adds (the bash applier tolerates several closed blocks; the JS reconcile
+ * refuses on the second one rather than silently acting on only the first). Returns
+ * `{ ok: true, blocks: [{ start, end }] }` (0 or 1 entries) or `{ ok: false, reason }`; never
+ * throws — callers decide whether a scan failure is a refusal or a bug (see loadDesiredBlock). */
+export function scanSentinels(lines) {
+  const blocks = [];
+  let open = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    const ln = lines[i];
+    const isBegin = ln.includes(BEGIN_TOKEN);
+    const isEnd = ln.includes(END_TOKEN);
+    if (isBegin && isEnd) {
+      return { ok: false, reason: `line ${i + 1} carries both the BEGIN and END tokens: ${ln}` };
+    }
+    if (isBegin) {
+      if (open >= 0) {
+        return {
+          ok: false,
+          reason: `BEGIN sentinel at line ${open + 1} has no matching END sentinel (another BEGIN found at line ${i + 1} first)`,
+        };
+      }
+      open = i;
+    } else if (isEnd) {
+      if (open < 0) {
+        return { ok: false, reason: `END sentinel at line ${i + 1} precedes the first BEGIN sentinel` };
+      }
+      blocks.push({ start: open, end: i });
+      open = -1;
+    }
+  }
+  if (open >= 0) {
+    return { ok: false, reason: `BEGIN sentinel at line ${open + 1} has no matching END sentinel` };
+  }
+  if (blocks.length > 1) {
+    return { ok: false, reason: `${blocks.length} managed blocks found; expected at most one` };
+  }
+  return { ok: true, blocks };
+}
+
+/** The desired block, read fresh from the shipped template every call — never a copy of its
+ * content vendored into this module, which is exactly the drift `cli/templates/gitignore.tmpl`
+ * being a denied path (this atom may read it, never edit it) is designed to prevent. Returns the
+ * BEGIN line through the END line, inclusive, exactly as `scaffold.mjs` writes them into a fresh
+ * `.gitignore` — no re-templating, no substitution (gitignore.tmpl carries none). A malformed
+ * shipped template is a packaging bug, not an adopter's data problem, so it throws a plain Error
+ * rather than a RefusalError (nothing here has offered a refusal-shaped report for the template
+ * itself to the CLI's caller). */
+export function loadDesiredBlock(templatesDir) {
+  const raw = fs.readFileSync(path.join(templatesDir, 'gitignore.tmpl'), 'utf-8');
+  const lines = splitLines(raw);
+  const scan = scanSentinels(lines);
+  if (!scan.ok || scan.blocks.length !== 1) {
+    throw new Error(
+      `cli/templates/gitignore.tmpl carries no single well-formed managed block: ${scan.ok ? 'no block found' : scan.reason}`,
+    );
+  }
+  const { start, end } = scan.blocks[0];
+  return Object.freeze(lines.slice(start, end + 1));
+}
+
+/** The desired INTERIOR only — the template's block with its own BEGIN/END lines stripped off.
+ * This, not `loadDesiredBlock`'s full block, is what `planGitignoreBlock` converges a target's
+ * block onto: PR #179 review — `cli/templates/gitignore.tmpl` ships BARE sentinel lines (no
+ * annotation) while `scripts/foundry-apply-runtime-gitignore.sh` writes ANNOTATED ones, and every
+ * bootstrapped workspace in practice carries the annotated form (the applier is what operators
+ * actually ran before this atom existed). Comparing/replacing WHOLE lines including the sentinels
+ * made the first `--existing`/upgrade run rewrite an annotated sentinel to bare, and a later bash
+ * applier run flip it back — the two tools never settled. Scoping this module to the interior only,
+ * and preserving whichever sentinel text the target already has verbatim, closes that oscillation:
+ * neither tool has an opinion on the other's sentinel line text once a block exists. */
+export function loadDesiredInterior(templatesDir) {
+  const block = loadDesiredBlock(templatesDir);
+  return Object.freeze(block.slice(1, -1));
+}
+
+/** Resolve `.gitignore` inside the physically-resolved target root, refusing (RefusalError) any
+ * resolution that escapes it — same confinement discipline as every other managed path. lstat, not
+ * stat: a symlinked `.gitignore` must be seen as such (AC-GBR-3's "a symlinked .gitignore is
+ * refused the same way"), not silently followed. */
+export function resolveGitignoreTarget(physicalRoot) {
+  const joined = confinedJoin(physicalRoot, '.gitignore');
+  if (joined === null) {
+    throw new RefusalError('refusing .gitignore: path escapes the target root', '.gitignore');
+  }
+  const st = fs.lstatSync(joined, { throwIfNoEntry: false });
+  if (!st) return { path: joined, present: false };
+  if (!st.isFile()) return { path: joined, present: true, notRegular: true };
+  return { path: joined, present: true };
+}
+
+/** Compute the reconcile action for an EXISTING, regular-file `.gitignore` WITHOUT touching the
+ * filesystem beyond the one read already implied by `targetPath` — this is what lets --dry-run
+ * report the same action a real run would take (AC-GBR-4). Returns one of:
+ *   { action: 'unchanged' }
+ *   { action: 'converged', nextLines }   -- a single block found, its INTERIOR differs
+ *   { action: 'appended',  nextLines }   -- no block found; a new block is appended
+ *   { action: 'refused',   reason }      -- a malformed sentinel state (AC-GBR-3)
+ * `desiredInterior` is the array `loadDesiredInterior` returns (the template's block with its own
+ * sentinel lines stripped).
+ *
+ * PR #179 review: this compares and replaces only the INTERIOR lines against the template's
+ * interior. When a block already exists, its own BEGIN/END lines are copied through byte-for-byte,
+ * whatever their text — this module never has an opinion on a sentinel line it FOUND, only on one
+ * it is WRITING for the first time (the append case, which uses the bash applier's own annotated
+ * form so the two tools agree on the text from that point on; see ANNOTATED_BEGIN_LINE/END_LINE). */
+export function planGitignoreBlock({ currentLines, desiredInterior }) {
+  const scan = scanSentinels(currentLines);
+  if (!scan.ok) {
+    return { action: 'refused', reason: scan.reason };
+  }
+  if (scan.blocks.length === 0) {
+    // AC-GBR-2: append, preceded by exactly one blank line. An empty (0-line) file has nothing to
+    // precede, so the block is written on its own rather than opening the file with a blank line.
+    const blockLines = [ANNOTATED_BEGIN_LINE, ...desiredInterior, ANNOTATED_END_LINE];
+    const nextLines = currentLines.length > 0
+      ? [...currentLines, '', ...blockLines]
+      : [...blockLines];
+    return { action: 'appended', nextLines };
+  }
+  const { start, end } = scan.blocks[0];
+  const currentInterior = currentLines.slice(start + 1, end);
+  const equal = currentInterior.length === desiredInterior.length
+    && currentInterior.every((ln, i) => ln === desiredInterior[i]);
+  if (equal) return { action: 'unchanged' };
+  // AC-GBR-1: replace EXACTLY the interior lines; the target's own BEGIN line (index `start`) and
+  // END line (index `end`) are carried through UNCHANGED — `slice(0, start + 1)` includes the
+  // BEGIN line itself, `slice(end)` includes the END line itself — and every line outside the
+  // block, on either side, is copied through untouched and in order.
+  const nextLines = [
+    ...currentLines.slice(0, start + 1),
+    ...desiredInterior,
+    ...currentLines.slice(end),
+  ];
+  return { action: 'converged', nextLines };
+}
+
+/** The whole read-plan step for a target known to be PRESENT: resolve, refuse a non-regular file
+ * the same way a malformed sentinel state is refused, read, scan, plan. Returns `null` only when
+ * the caller should not have invoked this at all (kept as a defensive assertion, not a normal
+ * path — `reconcileGitignore` below is what decides absence is the create path's business). */
+function planFromTarget(target, desiredInterior) {
+  if (target.notRegular) {
+    return { action: 'refused', reason: 'not a regular file (symlink or special file)', path: target.path };
+  }
+  const raw = fs.readFileSync(target.path, 'utf-8');
+  const currentLines = splitLines(raw);
+  const plan = planGitignoreBlock({ currentLines, desiredInterior });
+  return { ...plan, path: target.path };
+}
+
+/** The orchestration entry point run.mjs / update.mjs call: resolve + plan, WITHOUT writing
+ * anything (that is `applyGitignorePlan`'s job, called only after the same confirm/dry-run gate
+ * every other write in this CLI goes through). Returns `null` when `.gitignore` is absent — AC-GBR-2
+ * leaves that case to the existing managed-file create path untouched, so there is nothing for this
+ * module to plan or report; the caller must not print a row for a `null` result. */
+export function reconcileGitignorePlan({ physicalRoot, templatesDir }) {
+  const target = resolveGitignoreTarget(physicalRoot);
+  if (!target.present) return null;
+  const desiredInterior = loadDesiredInterior(templatesDir);
+  return planFromTarget(target, desiredInterior);
+}
+
+/** Install new `.gitignore` bytes by rename, same-directory temp opened O_EXCL then fsync then
+ * rename — the identical pattern floorReconcile.mjs's `writeTargetAtomically` uses for settings.json
+ * and for the identical reason: this is a rewrite of bytes belonging to an EXISTING regular file
+ * already lstat-verified not to be a symlink, so plain reconcile.mjs's create-only O_EXCL write
+ * (which requires the path NOT exist) cannot apply here — a same-dir rename is what makes the
+ * replace atomic (same filesystem) and closes the same interrupted-write / classify-to-write-race
+ * loss floorReconcile.mjs's own comment documents, without ever truncating the file in place. */
+export function writeGitignoreAtomically(targetPath, nextLines) {
+  const dir = path.dirname(targetPath);
+  const tmp = path.join(dir, `.gitignore.${process.pid}.tmp`);
+  const bytes = Buffer.from(nextLines.map((ln) => `${ln}\n`).join(''), 'utf-8');
+  const fd = fs.openSync(tmp, 'wx');
+  try {
+    fs.writeFileSync(fd, bytes);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    fs.renameSync(tmp, targetPath);
+  } catch (e) {
+    fs.rmSync(tmp, { force: true });
+    throw e;
+  }
+}
+
+/** Apply a plan computed by `reconcileGitignorePlan`. A no-op for every action except `converged`
+ * and `appended` — `unchanged` and `refused` both leave the file byte-for-byte as it was, which is
+ * what makes AC-GBR-4's no-write-when-already-converged guarantee hold: there is no code path from
+ * `unchanged` to a write syscall at all, not merely one that happens to produce identical bytes. */
+export function applyGitignorePlan(plan) {
+  if (!plan) return;
+  if (plan.action === 'converged' || plan.action === 'appended') {
+    writeGitignoreAtomically(plan.path, plan.nextLines);
+  }
+}
+
+/** Render the single report row for a plan, in the SAME `  [action] path (detail)` shape
+ * preview.mjs's own rows use. Returns `null` for a `null` plan (absent `.gitignore` — nothing to
+ * print; the generic managed-file row already covers that case). The four non-null strings are
+ * exactly AC-GBR-1/-2/-3's own report text. */
+export function renderGitignoreRow(plan) {
+  if (!plan) return null;
+  switch (plan.action) {
+    case 'converged':
+      return '  [converged] .gitignore (managed block)';
+    case 'appended':
+      return '  [converged] .gitignore (managed block appended)';
+    case 'unchanged':
+      return '  [unchanged] .gitignore (managed block)';
+    case 'refused':
+      return `  [refused] .gitignore (malformed managed block: ${plan.reason})`;
+    default:
+      throw new Error(`unknown gitignore reconcile action: ${plan.action}`);
+  }
+}

package/src/run.mjs

@@ -18,6 +18,7 @@ import {
   resolveTarget, readTarget, readTrackedRules, planAdditions, applyAdditions,
   writeTargetAtomically, renderPlan,
 } from './floorReconcile.mjs';
+import { reconcileGitignorePlan, applyGitignorePlan, renderGitignoreRow } from './gitignoreReconcile.mjs';
 
 export { DECLARED_PATH_SET };
 
@@ -168,6 +169,23 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
 
     print(renderPreview({ plan, machineScopeWrites, map }));
 
+    // gitignore-block-reconcile (ER #177, AC-GBR-1/-2/-3): the generic managed-file row above
+    // already covers `.gitignore` for the CREATE case (absent -> the full template lands verbatim,
+    // already converged) and for the byte-identical case, but once an adopter's `.gitignore` also
+    // carries its own lines it will never again match the template byte-for-byte, so that row reads
+    // `drifted` forever and the never-clobber plan never writes it — which is exactly why the
+    // sentinel-delimited block needs its OWN, narrower reconcile. Computed here (before the
+    // dry-run return) so --dry-run reports the same action a real run would take; `null` for an
+    // absent `.gitignore`, which is the CREATE path's business and prints nothing extra.
+    const gitignorePlan = reconcileGitignorePlan({
+      physicalRoot, templatesDir: path.join(pkgDir, 'templates'),
+    });
+    const gitignoreRow = renderGitignoreRow(gitignorePlan);
+    if (gitignoreRow) {
+      print('');
+      print(gitignoreRow);
+    }
+
     // Resolved HERE — before the write phase and before the dry-run return — because the reconcile
     // below must know what it would add in order to decide whether to write at all, and --dry-run
     // must be able to report those rules. That requirement is carried by the TRACKED classification
@@ -227,6 +245,12 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
     }
 
     applyPlan(plan);
+    // A `refused` gitignorePlan is a no-op here — applyGitignorePlan only writes on `converged` /
+    // `appended` — so a malformed managed block never blocks the rest of this run's writes; it is
+    // reported (the row above, and the exit code below) rather than escalated to a hard refusal,
+    // since it is a data-integrity issue local to one file, not the security-shaped case
+    // --reconcile-floor's pre-write refusal exists for.
+    applyGitignorePlan(gitignorePlan);
 
     if (floorPlan && floorPlan.total > 0) {
       writeTargetAtomically(floorTarget.path, applyAdditions(floorPlan.settingsObj, floorPlan, { map, pins }));
@@ -278,14 +302,27 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
     // on the path is the check that covers both — a directory-only test would tell a worktree user
     // to re-init a repository they already have.
     const isGitRepo = fs.existsSync(path.join(targetRoot, '.git'));
+    const gitignoreWrote = Boolean(
+      gitignorePlan && (gitignorePlan.action === 'converged' || gitignorePlan.action === 'appended'),
+    );
     print(TRUST_HANDOFF_TEXT(targetRoot, {
       isGitRepo,
       // only when a reconcile actually wrote — a dry run, a no-op second run, or a plain scaffold
-      // all keep the standard hand-off
-      reconciledExisting: Boolean(floorPlan && floorPlan.total > 0),
+      // all keep the standard hand-off. The gitignore-block-reconcile counts too: it is the SAME
+      // kind of write to an already-trusted workspace floorPlan's own comment describes, just to a
+      // different file.
+      reconciledExisting: Boolean(floorPlan && floorPlan.total > 0) || gitignoreWrote,
     }));
 
-    return { exitCode: exitCodeForPlan(plan), output: lines.join('\n') };
+    // A refused gitignore block joins the SAME non-zero bucket `drifted` files use (exit 2, "needs
+    // the operator's attention") rather than exit 1's hard-refusal bucket — the rest of the run's
+    // writes already landed, so "refused" here must not read as "nothing happened". exitCodeForPlan
+    // only ever returns 0 or 2, so a refusal simply forces 2 rather than deferring to it.
+    const gitignoreRefused = Boolean(gitignorePlan && gitignorePlan.action === 'refused');
+    return {
+      exitCode: gitignoreRefused ? 2 : exitCodeForPlan(plan),
+      output: lines.join('\n'),
+    };
   } catch (e) {
     if (e instanceof RefusalError) {
       print(`refused: ${e.message}`);

package/src/update.mjs

@@ -14,6 +14,7 @@ import { planManagedFiles, applyPlan } from './reconcile.mjs';
 import {
   resolveTarget, readTarget, readTrackedRules, planAdditions, applyAdditions, writeTargetAtomically,
 } from './floorReconcile.mjs';
+import { reconcileGitignorePlan, applyGitignorePlan, renderGitignoreRow } from './gitignoreReconcile.mjs';
 import {
   ALLOWED_CLAUDE_SUBCOMMANDS, resolveClaudeOnPath, runClaude,
   defaultScopes, snapshotScopes, classifyMigration, migrationActions, migrateScope,
@@ -161,6 +162,12 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
       })
       : null;
 
+    // gitignore-block-reconcile (ER #177, AC-GBR-1): PREVIEW-ONLY, same caveat as previewFloorPlan
+    // above — `.gitignore` is not a migration target, but Phase 4 recomputes fresh from disk anyway,
+    // for the same "never apply a stale pre-migration plan" reason.
+    const templatesDir = path.join(pkgDir, 'templates');
+    const previewGitignorePlan = reconcileGitignorePlan({ physicalRoot, templatesDir });
+
     // ── AC-UAW-7: the preview, before the first `claude` invocation and the first write ─────────
     const previewLines = ['The following claude invocations will be made:'];
     for (const { scopeSnap, trigger } of migrations) {
@@ -191,6 +198,8 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
     } else {
       previewLines.push('  [permission-floor] .claude/settings.json absent — left to the create path');
     }
+    const previewGitignoreRow = renderGitignoreRow(previewGitignorePlan);
+    if (previewGitignoreRow) previewLines.push(previewGitignoreRow);
     print(previewLines.join('\n'));
 
     const env = { ...spawnEnv, CLAUDE_CONFIG_DIR: configDir };
@@ -255,15 +264,41 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
         writeTargetAtomically(freshFloorTarget.path, applyAdditions(settingsObj, floorPlan, { map, pins }));
       }
     }
+    // Recomputed FRESH from disk, same reasoning as floorPlan just above: never apply a plan
+    // captured before Phases 1-3 ran, even though `.gitignore` is not itself a migration target.
+    // Skipped entirely when THIS run's own filePlan just CREATED `.gitignore` — AC-GBR-2 leaves the
+    // absent case to the create path, and re-planning immediately after applyPlan would otherwise
+    // find the just-written file already converged and print a redundant `[unchanged]` row for a
+    // file that never existed before this run.
+    const gitignoreFileAction = filePlan.find((f) => f.relPath === '.gitignore')?.action;
+    let freshGitignorePlan = null;
+    if (gitignoreFileAction !== 'create') {
+      freshGitignorePlan = reconcileGitignorePlan({ physicalRoot, templatesDir });
+      applyGitignorePlan(freshGitignorePlan);
+      const gitignoreRow = renderGitignoreRow(freshGitignorePlan);
+      if (gitignoreRow) print(gitignoreRow);
+    }
+
     const anyCreated = filePlan.some((f) => f.action === 'create');
     const anyFloorAdded = Boolean(floorPlan && floorPlan.total > 0);
-    phases.push({ name: 'reinitialization', verdict: anyCreated || anyFloorAdded ? 'changed' : 'already current' });
+    const anyGitignoreChanged = Boolean(
+      freshGitignorePlan && (freshGitignorePlan.action === 'converged' || freshGitignorePlan.action === 'appended'),
+    );
+    phases.push({
+      name: 'reinitialization',
+      verdict: anyCreated || anyFloorAdded || anyGitignoreChanged ? 'changed' : 'already current',
+    });
 
     print('');
     print(renderSummary(phases));
 
     const anyDrifted = filePlan.some((f) => f.action === 'drifted');
-    return { exitCode: anyDrifted ? 2 : 0, output: lines.join('\n') };
+    // Same bucket a `drifted` managed file uses (exit 2), not the hard-refusal exit 1 — Phases 1-4
+    // already ran and wrote what they could; a malformed gitignore block is reported, not escalated
+    // into "the update failed" for the whole run (run.mjs makes the identical choice; see its own
+    // comment on `gitignoreRefused`).
+    const gitignoreRefused = Boolean(freshGitignorePlan && freshGitignorePlan.action === 'refused');
+    return { exitCode: anyDrifted || gitignoreRefused ? 2 : 0, output: lines.join('\n') };
   } catch (e) {
     if (e instanceof RefusalError) {
       print(`refused: ${e.message}`);

package/templates/gitignore.tmpl

@@ -6,6 +6,11 @@
 !/.foundry/README.md
 !/.foundry/build-provenance.yaml
 !/.foundry/stack-profile.lock
+# The workspace's RECORD lives here too: programme manifests + charters + wave state, decision
+# records, and the operator's standing-grants policy (ER #169) -- committed, never runtime.
+!/.foundry/releases/
+!/.foundry/decisions/
+!/.foundry/permissions.yaml
 # FOUNDRY-RUNTIME-GITIGNORE-END
 
 # Local, UNGATED permission overrides — never commit them (PR #61 security review Risk 5).