create-agentic-workspace 0.16.1 → 0.17.1

package/README.md

@@ -49,6 +49,14 @@ it does invoke `claude` (bounded by a closed allowlist — see its own README).
   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.
+- `.foundry/permissions.yaml` is a SEED, not a managed file: written once when absent (an empty,
+  commented starter for standing grants — see the plugin's `docs/how-to/standing-grants.md`),
+  then operator-owned — reported `[kept]`, never compared, never drifted, never written again.
+- The Amendments backfill: every `specs/**/feat-*.md` with a normative region and no
+  `## Amendments` section after it gets the empty section `/foundry:amend` requires, reported as
+  one row (`[amendments] backfilled N of M specs (K already present, J skipped: no normative
+  region)`). Outside the hashed region, so no `spec_sha256` moves; already-present, marker-less and
+  symlinked specs are never written; `--dry-run` prints the same row.
 
 ## Flags
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-workspace",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "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.16.1",
+    "plugin_version": "1.17.1",
     "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.16.1",
+  "generated_for_plugin_version": "1.17.1",
   "entries": [
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-acceptance-contract-validate.py:*)",

package/src/amendmentsBackfill.mjs

@@ -0,0 +1,162 @@
+// amendmentsBackfill.mjs — amendments-backfill (ER #214, AC-AMB-1..5).
+//
+// `/foundry:amend` (v1.11.0) refuses, by design and by test, when a spec has no `## Amendments`
+// heading after its LAST `<!-- /normative -->` marker (outside fenced code) — see
+// scripts/foundry-amend.py `amendments_section_ok`, whose rule this module mirrors byte for byte
+// (tests/test_amendments_backfill.py cross-checks the two over one fixture set). Nothing added that
+// section to a spec written before the verb existed, so on an upgraded corpus the verb never fires:
+// 0 of 204 specs on one adopter, 7 of 360 on the self-hosting workspace (2026-09-22/23).
+//
+// The section sits OUTSIDE the hashed normative region, so appending it moves no `spec_sha256`
+// and no authorization (AC-AMB-4 pins that with the real hashing function). This module therefore
+// runs on the `--existing` reconcile and the upgrader's Phase 4 like the gitignore block does:
+// idempotent, never-clobber in the only sense that matters (a spec that already has the section is
+// never written), atomic writes, and a plan/apply split so `--dry-run` prints the same row.
+import fs from 'node:fs';
+import path from 'node:path';
+import { confinedJoin } from './util.mjs';
+
+export const NORMATIVE_CLOSE = '<!-- /normative -->';
+export const AMENDMENTS_HEADING = '## Amendments';
+/** Exactly what is appended (AC-AMB-1); the leading blank line is added only when the file does
+ * not already end with one, so a spec ending "...\n" gets "\n## Amendments..." and one ending
+ * "...\n\n" gets the heading directly. Header columns are `foundry-amend.py`'s own row shape. */
+export const AMENDMENTS_BLOCK = `${AMENDMENTS_HEADING}\n\n| date | what changed | why reality required it | auth_seq |\n|---|---|---|---|\n`;
+
+// ER #223 (v1.17.1): EVERY `*.md` under specs/, not only `feat-*.md` — foundry-amend.py has no
+// filename rule (it classifies by the normative region), and an adopter's delivery atoms are named
+// `spec-*.md`. A README or template without a normative region lands in `skipped`, never written.
+const SPEC_BASENAME_RE = /\.md$/;
+const CODE_FENCE_RE = /```[\s\S]*?```/g;
+
+/** The verdict `foundry-amend.py`'s amendments_section_ok gives: `present` when a `## Amendments`
+ * heading appears after the LAST normative close marker and outside any fenced code block;
+ * `absent` when it does not; `no-marker` when the spec has no close marker at all (amend's own
+ * whole-body fallback applies there, and this module never writes such a file). Fenced blocks are
+ * masked with same-length filler so the heading's offset stays comparable to the marker's, exactly
+ * as the Python does; CRLF is tolerated because neither search depends on line structure. */
+export function classifySpec(text) {
+  const closeIdx = text.lastIndexOf(NORMATIVE_CLOSE);
+  if (closeIdx === -1) return 'no-marker';
+  const masked = text.replace(CODE_FENCE_RE, (m) => '\0'.repeat(m.length));
+  const idx = masked.indexOf(AMENDMENTS_HEADING);
+  if (idx !== -1 && idx > closeIdx) return 'present';
+  // A heading BEFORE the marker does not count for amend either — the section must follow the
+  // normative region — so it is `absent` and the block is appended at the end of the file.
+  return 'absent';
+}
+
+/** Every regular `*.md` under `<root>/specs` (any basename — ER #223), depth-first, with symlinked FILES reported
+ * separately (never followed, never written — AC-AMB-2) and symlinked DIRECTORIES not descended
+ * (the same confinement instinct as the scaffold's confinedJoin: nothing outside the workspace
+ * root is ever touched). Absent `specs/` yields an empty walk, not an error. */
+export function walkSpecs(physicalRoot) {
+  const files = [];
+  const symlinks = [];
+  // v1.17.1 security review Risk 1: the ROOT is confined like every entry under it — a `specs`
+  // that is itself a symlink (or resolves outside the workspace) is never descended, never written.
+  const specsRoot = confinedJoin(physicalRoot, 'specs');
+  if (!specsRoot) return { files, symlinks };
+  const rootStat = fs.lstatSync(specsRoot, { throwIfNoEntry: false });
+  if (!rootStat || rootStat.isSymbolicLink() || !rootStat.isDirectory()) return { files, symlinks };
+  const stack = [specsRoot];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of entries) {
+      const abs = path.join(dir, ent.name);
+      if (ent.isSymbolicLink()) {
+        if (SPEC_BASENAME_RE.test(ent.name)) symlinks.push(abs);
+        continue; // never descend a symlinked directory, never write a symlinked file
+      }
+      if (ent.isDirectory()) stack.push(abs);
+      else if (ent.isFile() && SPEC_BASENAME_RE.test(ent.name)) files.push(abs);
+    }
+  }
+  files.sort();
+  symlinks.sort();
+  return { files, symlinks };
+}
+
+/** Plan only — no write. `{ toAppend: [abs...], present, skipped, symlinks, total }` where `total`
+ * counts every regular spec seen (the "of <m>" in the row) and `skipped` is the no-marker count. */
+export function planAmendmentsBackfill({ physicalRoot }) {
+  const { files, symlinks } = walkSpecs(physicalRoot);
+  const toAppend = [];
+  let present = 0;
+  let skipped = 0;
+  for (const abs of files) {
+    let text;
+    try {
+      text = fs.readFileSync(abs, 'utf-8');
+    } catch {
+      skipped += 1;
+      continue;
+    }
+    const verdict = classifySpec(text);
+    if (verdict === 'present') present += 1;
+    else if (verdict === 'no-marker') skipped += 1;
+    else toAppend.push(abs);
+  }
+  return { toAppend, present, skipped, symlinks, total: files.length, applied: false };
+}
+
+/** The bytes to append for a given current text: the block, preceded by one newline when the text
+ * does not already end with a blank line, and by TWO when it does not end with a newline at all. */
+export function appendBytesFor(text) {
+  if (text === '' || text.endsWith('\n\n') || text.endsWith('\r\n\r\n')) return AMENDMENTS_BLOCK;
+  if (text.endsWith('\n')) return `\n${AMENDMENTS_BLOCK}`;
+  return `\n\n${AMENDMENTS_BLOCK}`;
+}
+
+/** Atomic append: read, compose, write a sibling temp file, rename over the original (the same
+ * discipline as gitignoreReconcile's writer). Re-classifies right before writing so a file that
+ * gained the section between plan and apply is left alone. Returns the count actually written. */
+export function applyAmendmentsBackfill(plan) {
+  let written = 0;
+  for (const abs of plan.toAppend) {
+    let text;
+    try {
+      text = fs.readFileSync(abs, 'utf-8');
+    } catch {
+      continue;
+    }
+    if (classifySpec(text) !== 'absent') continue;
+    const tmp = `${abs}.amendments-backfill.tmp`;
+    // v1.17.1 security review Risk 2: `wx` refuses to write through a planted sibling — a symlink
+    // or a leftover file at the temp path means this spec is skipped, never written elsewhere.
+    try {
+      fs.writeFileSync(tmp, text + appendBytesFor(text), { encoding: 'utf-8', flag: 'wx' });
+    } catch {
+      continue;
+    }
+    try {
+      fs.renameSync(tmp, abs);
+    } catch {
+      fs.rmSync(tmp, { force: true });
+      continue;
+    }
+    written += 1;
+  }
+  plan.applied = true;
+  plan.written = written;
+  return written;
+}
+
+/** The one row (AC-AMB-1). `null` when the workspace has no specs at all, so a fresh scaffold's
+ * output is unchanged. Under dry-run the count is what WOULD be backfilled; after apply it is what
+ * was. Symlinked spec files are named so the operator sees what was deliberately not touched. */
+export function renderAmendmentsRow(plan) {
+  if (!plan || (plan.total === 0 && plan.symlinks.length === 0)) return null;
+  const n = plan.applied ? plan.written : plan.toAppend.length;
+  let row = `  [amendments] backfilled ${n} of ${plan.total} specs (${plan.present} already present, ${plan.skipped} skipped: no normative region)`;
+  if (plan.symlinks.length > 0) {
+    row += `; ${plan.symlinks.length} symlinked spec file(s) not touched: ${plan.symlinks.map((p) => path.basename(p)).join(', ')}`;
+  }
+  return row;
+}

package/src/reconcile.mjs

@@ -12,6 +12,11 @@ export function planManagedFiles(managedFiles) {
     const { present, equal, notRegular } = fileBytesEqual(f.absPath, f.bytes);
     let action;
     if (!present) action = 'create';
+    // permissions-scaffold (ER #215, AC-PSC-2): a SEED entry is written once when absent and is
+    // operator-owned from then on — present means `kept`, whatever its bytes: never compared,
+    // never `drifted`, never written. Only `drifted` feeds exitCodeForPlan, so a seed never
+    // turns a converged run into exit 2.
+    else if (f.seed) action = 'kept';
     else if (notRegular) action = 'drifted';
     else action = equal ? 'unchanged' : 'drifted';
     return { ...f, action };

package/src/run.mjs

@@ -18,6 +18,8 @@ import {
   resolveTarget, readTarget, applyAdditions, planReconcile, writeTargetAtomically, renderPlan,
 } from './floorReconcile.mjs';
 import { reconcileGitignorePlan, applyGitignorePlan, renderGitignoreRow } from './gitignoreReconcile.mjs';
+import { planAmendmentsBackfill, applyAmendmentsBackfill, renderAmendmentsRow } from './amendmentsBackfill.mjs';
+import { planStatuslineWiring, applyStatuslineWiring, renderStatuslineRows } from './statuslineWiring.mjs';
 
 export { DECLARED_PATH_SET };
 
@@ -184,6 +186,28 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
       print('');
       print(gitignoreRow);
     }
+    // amendments-backfill (ER #214, AC-AMB-1): every `specs/**/feat-*.md` with a normative region
+    // and no `## Amendments` section after it gets the empty section `/foundry:amend` requires.
+    // Planned here for the same reason as the gitignore block — --dry-run reports the same row a
+    // real run would act on — and `null` when the workspace has no specs at all (a fresh scaffold).
+    const amendmentsPlan = planAmendmentsBackfill({ physicalRoot });
+    const amendmentsRow = renderAmendmentsRow(amendmentsPlan);
+    if (amendmentsRow) {
+      if (!gitignoreRow) print('');
+      print(amendmentsRow);
+    }
+    // statusline-wiring (v1.17.0, AC-SLW-1/-2): ONLY on --existing --reconcile-floor. A plain
+    // --existing run never touches .claude/settings.json (AC-BCL-9: an existing settings file is
+    // reported drifted, left byte-identical, never merged); --reconcile-floor is the one opt-in
+    // that already permits a narrow-key write to it, and this wiring is the same class of write.
+    // The greenfield create path never wires it — feat-foundry-bootstrap-cli AC-BCL-4(c) closes
+    // the pre-session key set, deliberately. planStatuslineWiring returns an empty plan when
+    // settings.json is absent. The upgrader (update.mjs) always reconciles the floor, so it
+    // always wires.
+    const statuslinePlan = answers.existing && answers.reconcileFloor
+      ? planStatuslineWiring({ physicalRoot, templatesDir: path.join(pkgDir, 'templates') })
+      : null;
+    for (const row of renderStatuslineRows(statuslinePlan)) print(row);
 
     // 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
@@ -259,6 +283,9 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
     // 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);
+    // Same never-clobber posture as the gitignore block: only a spec classified `absent` is ever
+    // written, and it is re-classified immediately before the atomic append (AC-AMB-2).
+    applyAmendmentsBackfill(amendmentsPlan);
 
     if (floorHasWork) {
       // floorPlan.settingsObj is ALREADY post-retirement (planReconcile derived it that way) —
@@ -270,6 +297,13 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
         applied: true, retirementPlan: floorRetirementPlan, mapEntryCount: map.entries.length,
       })) print(line);
     }
+    // AFTER the floor write above: that write serialises a settings object read before this
+    // point, so wiring the statusLine keys first would have been overwritten by it. The wiring
+    // re-reads settings.json itself and adds only the absent keys (AC-SLW-2).
+    // Re-planned FRESH here (review round 2): the plan above was computed before the interactive
+    // confirmation, and a wrapper that appeared during that window must classify as `kept`, not be
+    // renamed over — the same re-plan-before-write discipline update.mjs's Phase 4 uses.
+    if (statuslinePlan) applyStatuslineWiring(planStatuslineWiring({ physicalRoot, templatesDir: path.join(pkgDir, 'templates') }));
 
     if (slug) {
       ensureGitRepo(physicalRoot);
@@ -324,7 +358,8 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
       // 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,
+      reconciledExisting: Boolean(floorPlan && floorPlan.total > 0) || gitignoreWrote
+        || Boolean(amendmentsPlan && amendmentsPlan.applied && amendmentsPlan.written > 0),
     }));
 
     // A refused gitignore block joins the SAME non-zero bucket `drifted` files use (exit 2, "needs

package/src/scaffold.mjs

@@ -13,6 +13,11 @@ export const TEMPLATE_ENTRIES = Object.freeze([
   { template: 'specs-features-README.md', target: 'specs/features/README.md' },
   { template: 'specs-lifecycle-README.md', target: 'specs/lifecycle/README.md' },
   { template: 'foundry-README.md', target: '.foundry/README.md' },
+  // permissions-scaffold (ER #215, AC-PSC-2): a SEED, not a managed file. Written once when
+  // absent; once present it is operator-owned — never read for comparison, never reported
+  // drifted, never written again (reconcile.mjs reports it `kept`). The other entries are
+  // framework-owned text an adopter is not expected to edit; this one is the opposite.
+  { template: 'permissions.yaml.tmpl', target: '.foundry/permissions.yaml', seed: true },
 ]);
 
 /** Render a template's raw text with the CLAUDE.md substitutions (the only templated file). */
@@ -46,7 +51,10 @@ export function buildManagedFiles({
     }
     const raw = fs.readFileSync(path.join(templatesDir, entry.template), 'utf-8');
     const rendered = renderTemplate(entry.target, raw, { projectName, stageMode });
-    files.push({ relPath: entry.target, absPath: joined, bytes: Buffer.from(rendered, 'utf-8') });
+    files.push({
+      relPath: entry.target, absPath: joined, bytes: Buffer.from(rendered, 'utf-8'),
+      ...(entry.seed ? { seed: true } : {}),
+    });
   }
 
   const settingsJoined = confinedJoin(physicalRoot, '.claude/settings.json');
@@ -68,4 +76,5 @@ export const DECLARED_PATH_SET = Object.freeze([
   'specs/features/README.md',
   'specs/lifecycle/README.md',
   '.foundry/README.md',
+  '.foundry/permissions.yaml',
 ]);

package/src/statuslineWiring.mjs

@@ -0,0 +1,138 @@
+// statuslineWiring.mjs — statusline-wiring (v1.17.0, AC-SLW-1/-2).
+//
+// The token-budget status line (`⌂ <repo>:<branch> · tok ██████░░░░ 69% · ⚙️ factory`) is rendered
+// by the plugin's shipped `scripts/foundry-statusline.sh`, reached through a thin wrapper at
+// `.claude/hooks/foundry-statusline.sh` and a `statusLine` key in `.claude/settings.json`. Until
+// v1.17.0 nothing shipped that wiring: /foundry:init only verified it, and the wrapper printed
+// nothing when its one cache glob missed — on the operator's second machine the bar was simply
+// absent, with no line saying which piece was missing.
+//
+// This module is the WRITER, and it runs only post-trust — from `update-agentic-workspace` and from
+// `create-agentic-workspace --existing` on a workspace whose `.claude/settings.json` already exists.
+// The greenfield create path never calls it: feat-foundry-bootstrap-cli AC-BCL-4(c) (a frozen
+// security Block) closes the pre-session settings key set, and that reasoning stands.
+//
+// Two artifacts, two disciplines:
+//   * the wrappers are FRAMEWORK-OWNED: absent -> create; present with the framework marker ->
+//     converged onto the shipped bytes; present WITHOUT the marker -> kept (the operator wrote
+//     their own; it is never touched). Mode 0755.
+//   * the settings keys are ADDED ONLY WHEN ABSENT: an existing `statusLine`/`subagentStatusLine`
+//     value, whatever it points at, is never overwritten. Same narrow-key discipline as the floor.
+// Neither ever contributes to the exit-2 drift verdict.
+import fs from 'node:fs';
+import path from 'node:path';
+import { confinedJoin } from './util.mjs';
+import { resolveTarget, readTarget, writeTargetAtomically } from './floorReconcile.mjs';
+
+export const MARKER = 'feat-foundry-init-statusline-wrapper';
+export const WRAPPERS = Object.freeze([
+  { template: 'foundry-statusline.sh', rel: '.claude/hooks/foundry-statusline.sh', key: 'statusLine' },
+  { template: 'foundry-subagent-statusline.sh', rel: '.claude/hooks/foundry-subagent-statusline.sh', key: 'subagentStatusLine' },
+]);
+
+export function desiredSettingsValue(rel) {
+  return { type: 'command', command: `$CLAUDE_PROJECT_DIR/${rel}`, padding: 0 };
+}
+
+/** Plan only. `files[]` rows carry `{ rel, abs, action: create|converged|unchanged|kept|refused, bytes }`;
+ * `keys[]` rows carry `{ key, action: wired|already-wired }`; `settingsPresent` says whether the
+ * post-trust precondition held (when it did not, the plan is empty and renders nothing). */
+export function planStatuslineWiring({ physicalRoot, templatesDir }) {
+  const target = resolveTarget(physicalRoot);
+  const plan = { settingsPresent: target.present, settingsPath: target.path, files: [], keys: [], applied: false };
+  if (!target.present) return plan;
+  for (const w of WRAPPERS) {
+    const abs = confinedJoin(physicalRoot, w.rel);
+    const bytes = fs.readFileSync(path.join(templatesDir, w.template));
+    if (abs === null) { plan.files.push({ rel: w.rel, abs: null, action: 'refused', reason: 'path escapes the target root', bytes }); continue; }
+    const st = fs.lstatSync(abs, { throwIfNoEntry: false });
+    let action;
+    if (!st) action = 'create';
+    else if (!st.isFile()) action = 'refused';
+    else {
+      const cur = fs.readFileSync(abs);
+      if (cur.equals(bytes)) action = 'unchanged';
+      else if (cur.toString('utf-8').includes(MARKER)) action = 'converged';
+      else action = 'kept';
+    }
+    plan.files.push({ rel: w.rel, abs, action, bytes, ...(action === 'refused' && st ? { reason: 'not a regular file' } : {}) });
+  }
+  const settings = readTarget(target.path);
+  for (const w of WRAPPERS) {
+    const present = Object.prototype.hasOwnProperty.call(settings, w.key);
+    // Security review (Risk 2): never wire a key at a file this framework did not write or could
+    // not verify — a `kept` (no marker) or `refused` (not a regular file) wrapper leaves its key
+    // `not-wired`, the row says so, and the operator decides. Decided at PLAN time so the preview
+    // and a dry-run say exactly what apply will do.
+    const fileRow = plan.files.find((f) => f.rel === w.rel);
+    const unverifiable = fileRow && (fileRow.action === 'kept' || fileRow.action === 'refused');
+    plan.keys.push({ key: w.key, action: present ? 'already-wired' : (unverifiable ? 'not-wired' : 'wired') });
+  }
+  return plan;
+}
+
+/** Apply: write create/converged wrappers atomically with mode 0755; add absent keys in one
+ * atomic settings write, leaving every other key byte-for-byte as it was. */
+export function applyStatuslineWiring(plan) {
+  if (!plan.settingsPresent) return plan;
+  for (const f of plan.files) {
+    if (f.action !== 'create' && f.action !== 'converged') continue;
+    fs.mkdirSync(path.dirname(f.abs), { recursive: true });
+    // Security review (statusline-wiring, Block 1): the temp path is opened with 'wx' — O_EXCL,
+    // never following a planted symlink at that name — pid-suffixed against a concurrent run,
+    // fchmod'ed on the fd (no follow-up chmod that would follow a link), and removed if the
+    // rename fails. The same primitive floorReconcile.writeTargetAtomically uses (PR #61 Block 2).
+    const tmp = path.join(path.dirname(f.abs), `.${path.basename(f.abs)}.${process.pid}.tmp`);
+    const fd = fs.openSync(tmp, 'wx', 0o755);
+    try {
+      fs.writeFileSync(fd, f.bytes);
+      fs.fchmodSync(fd, 0o755);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    try {
+      fs.renameSync(tmp, f.abs);
+    } catch (e) {
+      fs.rmSync(tmp, { force: true });
+      throw e;
+    }
+  }
+  const toAdd = plan.keys.filter((k) => k.action === 'wired');
+  if (toAdd.length > 0) {
+    const settings = readTarget(plan.settingsPath);
+    for (const k of toAdd) {
+      if (Object.prototype.hasOwnProperty.call(settings, k.key)) continue; // raced in since plan
+      const w = WRAPPERS.find((x) => x.key === k.key);
+      settings[k.key] = desiredSettingsValue(w.rel);
+    }
+    writeTargetAtomically(plan.settingsPath, settings);
+  }
+  plan.applied = true;
+  return plan;
+}
+
+/** Rows for the preview / Phase 4 output. Empty when the post-trust precondition did not hold. */
+export function renderStatuslineRows(plan) {
+  if (!plan || !plan.settingsPresent) return [];
+  const rows = [];
+  for (const f of plan.files) {
+    const suffix = f.action === 'kept' ? ' (operator-owned, no framework marker — never reconciled)'
+      : f.action === 'refused' ? ` (refused: ${f.reason})` : '';
+    rows.push(`  [${f.action}] ${f.rel}${suffix}`);
+  }
+  const wired = plan.keys.filter((k) => k.action === 'wired').map((k) => k.key);
+  const already = plan.keys.filter((k) => k.action === 'already-wired').map((k) => k.key);
+  const notWired = plan.keys.filter((k) => k.action === 'not-wired').map((k) => k.key);
+  if (wired.length) rows.push(`  [statusline] wired ${wired.join(', ')} in .claude/settings.json`);
+  if (already.length) rows.push(`  [statusline] already wired: ${already.join(', ')} (existing value kept)`);
+  if (notWired.length) rows.push(`  [statusline] NOT wired: ${notWired.join(', ')} — the wrapper at that path is not one this framework wrote (kept or refused); verify it, then wire by hand`);
+  return rows;
+}
+
+export function statuslineChanged(plan) {
+  return Boolean(plan && plan.applied && (
+    plan.files.some((f) => f.action === 'create' || f.action === 'converged')
+    || plan.keys.some((k) => k.action === 'wired')
+  ));
+}

package/src/update.mjs

@@ -15,6 +15,9 @@ import {
   resolveTarget, readTarget, applyAdditions, planReconcile, writeTargetAtomically, renderPlan,
 } from './floorReconcile.mjs';
 import { reconcileGitignorePlan, applyGitignorePlan, renderGitignoreRow } from './gitignoreReconcile.mjs';
+import { planAmendmentsBackfill, applyAmendmentsBackfill, renderAmendmentsRow } from './amendmentsBackfill.mjs';
+import { buildUpgradeReport, writeUpgradeReport, installedVersionBefore, NEXT_LINE } from './upgradeReport.mjs';
+import { planStatuslineWiring, applyStatuslineWiring, renderStatuslineRows, statuslineChanged } from './statuslineWiring.mjs';
 import {
   ALLOWED_CLAUDE_SUBCOMMANDS, resolveClaudeOnPath, runClaude,
   defaultScopes, snapshotScopes, classifyMigration, migrationActions, migrateScope,
@@ -121,6 +124,8 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
 
     const registry = readInstalledPluginsRegistry(configDir);
     const isInstalled = isInstalledInScopeFactory(registry, pluginKey, cwd);
+    // ER #222: the report's `from` is what THIS workspace had installed, read before any mutation.
+    const installedBefore = installedVersionBefore(registry, pluginKey, cwd);
 
     const migrations = [];
     const indeterminateInstalledness = [];
@@ -207,6 +212,12 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
     }
     const previewGitignoreRow = renderGitignoreRow(previewGitignorePlan);
     if (previewGitignoreRow) previewLines.push(previewGitignoreRow);
+    // amendments-backfill (ER #214, AC-AMB-1): PREVIEW-ONLY like the two rows above; Phase 4
+    // re-plans fresh from disk before it writes.
+    const previewAmendmentsRow = renderAmendmentsRow(planAmendmentsBackfill({ physicalRoot }));
+    if (previewAmendmentsRow) previewLines.push(previewAmendmentsRow);
+    // statusline-wiring (AC-SLW-1/-2): PREVIEW-ONLY rows; Phase 4 re-plans fresh from disk.
+    previewLines.push(...renderStatuslineRows(planStatuslineWiring({ physicalRoot, templatesDir })));
     print(previewLines.join('\n'));
 
     const env = { ...spawnEnv, CLAUDE_CONFIG_DIR: configDir };
@@ -294,20 +305,52 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
       if (gitignoreRow) print(gitignoreRow);
     }
 
+    // amendments-backfill (ER #214, AC-AMB-1/-2): re-planned FRESH from disk like the two blocks
+    // above, applied with the module's own re-classify-before-append guard.
+    const amendmentsPlan = planAmendmentsBackfill({ physicalRoot });
+    applyAmendmentsBackfill(amendmentsPlan);
+    const amendmentsRow = renderAmendmentsRow(amendmentsPlan);
+    if (amendmentsRow) print(amendmentsRow);
+
     const anyCreated = filePlan.some((f) => f.action === 'create');
     const anyFloorAdded = Boolean(floorPlan && floorPlan.total > 0)
       || Boolean(floorRetirementPlan && floorRetirementPlan.total > 0);
     const anyGitignoreChanged = Boolean(
       freshGitignorePlan && (freshGitignorePlan.action === 'converged' || freshGitignorePlan.action === 'appended'),
     );
+    const anyAmendmentsBackfilled = amendmentsPlan.written > 0;
+    // statusline-wiring (v1.17.0, AC-SLW-1/-2): the updater is the post-trust writer of the
+    // wrapper files and the two settings keys (added only when absent). Planned fresh from disk
+    // here, after the floor write above, so the settings read is the current one.
+    const statuslinePlan = planStatuslineWiring({ physicalRoot, templatesDir });
+    applyStatuslineWiring(statuslinePlan);
+    for (const row of renderStatuslineRows(statuslinePlan)) print(row);
     phases.push({
       name: 'reinitialization',
-      verdict: anyCreated || anyFloorAdded || anyGitignoreChanged ? 'changed' : 'already current',
+      verdict: anyCreated || anyFloorAdded || anyGitignoreChanged || anyAmendmentsBackfilled
+        || statuslineChanged(statuslinePlan) ? 'changed' : 'already current',
     });
 
     print('');
     print(renderSummary(phases));
 
+    // post-upgrade-skill (AC-PUS-1): the hand-off to the judgement half. Written on every
+    // completed run (overwritten — a report, not a managed file; `.foundry/*` is gitignored), and
+    // named in the LAST line so the operator's next step is never a guess.
+    const report = buildUpgradeReport({
+      installedBefore, afterEntry, toPluginVersion: pins.plugin_version, phases, filePlan, amendmentsPlan,
+    });
+    const reportPath = writeUpgradeReport(physicalRoot, report);
+    print('');
+    if (reportPath === null) {
+      // PR #218 review round 2: never hand off to a report that was not written — a planted link
+      // at that path would otherwise be what the skill reads.
+      print('  [refused] .foundry/upgrade-report.json (.foundry is not a directory, or the report path is not a regular file — NOT written)');
+      print('next: make .foundry/upgrade-report.json a regular path and re-run — do not run /foundry:post-upgrade until this run writes its report');
+    } else {
+      print(NEXT_LINE);
+    }
+
     const anyDrifted = filePlan.some((f) => f.action === 'drifted');
     // 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

package/src/upgradeReport.mjs

@@ -0,0 +1,82 @@
+// upgradeReport.mjs — post-upgrade-skill (AC-PUS-1).
+//
+// An upgrade has two halves. The deterministic half is this package: file reconcile, the
+// Amendments backfill, the permissions seed. The judgement half — standing grants into policy,
+// `requires_capabilities` on unfrozen contracts, a truth pass over the adopter's own prose,
+// branch garbage collection — cannot honestly be a script and lives in the plugin's
+// `/foundry:post-upgrade` skill. The hand-off between the two is this report: written on every
+// completed run (always overwritten — it is a report, not a managed file), read by the skill, and
+// named in the updater's last output line. `.foundry/*` is gitignored by the runtime block, so the
+// report never lands in the adopter's repo.
+import fs from 'node:fs';
+import path from 'node:path';
+import { confinedJoin } from './util.mjs';
+import { scopeRecordsFor } from './pluginRefresh.mjs';
+
+export const REPORT_REL = '.foundry/upgrade-report.json';
+export const REPORT_SCHEMA_VERSION = 1;
+export const NEXT_LINE = `next: run /foundry:post-upgrade in your next session (report: ${REPORT_REL})`;
+
+/** The plugin version strings come from the marketplace manifest — remote content refreshed by
+ * `claude plugin marketplace update` — and land in a file an agent later reads and acts on. Only a
+ * version-shaped string is copied (PR #218 security review, Risk 3); anything else is `null`. */
+const VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]{1,40})?$/;
+export function versionOrNull(v) {
+  return typeof v === 'string' && v.length <= 64 && VERSION_RE.test(v) ? v : null;
+}
+
+/** Pure: assemble the report object. `installedBefore` is this workspace's installed version from
+ * `installedVersionBefore` (or null); `afterEntry` is the marketplace manifest's plugin entry after
+ * the refresh (or null); `filePlan` is the managed-file plan;
+ * `amendmentsPlan` is the applied backfill plan (or null); `phases` is what renderSummary got. */
+export function buildUpgradeReport({
+  installedBefore = null, afterEntry, toPluginVersion, phases, filePlan, amendmentsPlan, now = new Date(),
+}) {
+  const seedRow = (filePlan || []).find((f) => f.seed);
+  return {
+    schema_version: REPORT_SCHEMA_VERSION,
+    ran_at: now.toISOString(),
+    // ER #222 (v1.17.1): THIS workspace's installed version from installed_plugins.json, captured
+    // before any mutation — never the marketplace clone's advertised version, which is per machine
+    // and already moved by the time Phase 1 reads it. null (no record, unreadable registry, a
+    // first install) makes the skill list only the current version's CHANGELOG section.
+    from_plugin_version: versionOrNull(installedBefore),
+    to_plugin_version: (afterEntry && versionOrNull(afterEntry.version)) || versionOrNull(toPluginVersion),
+    phases: (phases || []).map((p) => ({ name: p.name, verdict: p.verdict, ...(p.reason ? { reason: p.reason } : {}) })),
+    amendments: amendmentsPlan
+      ? { backfilled: amendmentsPlan.written ?? 0, present: amendmentsPlan.present, skipped: amendmentsPlan.skipped }
+      : { backfilled: 0, present: 0, skipped: 0 },
+    permissions_policy: seedRow ? (seedRow.action === 'create' ? 'created' : 'kept') : 'absent',
+    drifted: (filePlan || []).filter((f) => f.action === 'drifted').map((f) => f.relPath),
+  };
+}
+
+/** The version THIS workspace had installed before the run (ER #222): the project-scope record
+ * whose `projectPath` is `cwd`, else the user-scope record (no `projectPath`), else null. Reads the
+ * registry object `readInstalledPluginsRegistry` returns; `ok: false` is null, never a guess. */
+export function installedVersionBefore(registry, pluginKey, cwd) {
+  if (!registry || !registry.ok) return null;
+  const records = scopeRecordsFor(registry.doc, pluginKey).filter((r) => r && typeof r === 'object');
+  const project = records.find((r) => r.projectPath && path.resolve(String(r.projectPath)) === path.resolve(cwd));
+  const user = records.find((r) => !r.projectPath);
+  const hit = project || user;
+  return hit ? versionOrNull(hit.version) : null;
+}
+
+/** Write the report under the workspace root, creating `.foundry/` if needed. Overwrites.
+ * Confined the way every other Phase-4 writer is (PR #218 security review, Risk 4): the target is
+ * joined through `confinedJoin`, a `.foundry` that is a symlink or a leaf that is not a regular
+ * file is REFUSED (returns null, nothing written) — the write can never land outside the
+ * physically-resolved root through a planted link. */
+export function writeUpgradeReport(physicalRoot, report) {
+  const abs = confinedJoin(physicalRoot, REPORT_REL);
+  if (abs === null) return null;
+  const dir = path.dirname(abs);
+  const dst = fs.lstatSync(dir, { throwIfNoEntry: false });
+  if (dst && !dst.isDirectory()) return null;          // `.foundry` is a symlink or a file
+  const lst = fs.lstatSync(abs, { throwIfNoEntry: false });
+  if (lst && !lst.isFile()) return null;               // the leaf is a symlink or special
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(abs, `${JSON.stringify(report, null, 2)}\n`, 'utf-8');
+  return abs;
+}

package/templates/foundry-statusline.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# foundry-statusline.sh — version-agnostic, fail-open self-resolving statusLine wrapper
+# (feat-foundry-init-statusline-wrapper, AC-SLW-1; statusline-wiring v1.17.0, AC-SLW-3).
+#
+# Installed into an adopter repo at .claude/hooks/foundry-statusline.sh by `npx update-agentic-workspace`
+# (and `create-agentic-workspace --existing` on a trusted workspace), which also sets
+# statusLine.command to "$CLAUDE_PROJECT_DIR/.claude/hooks/foundry-statusline.sh" — the EXPANDABLE
+# placeholder. (The plugin-root hook path-placeholder is HOOK-scoped and does NOT expand in a statusLine
+# command, so this wrapper references it NOWHERE.) The line above carrying the feature id is the
+# FRAMEWORK MARKER: the updater converges a wrapper that carries it and keeps one that does not.
+#
+# RESOLUTION ORDER (v1.17.0): the renderer the plugin ships is looked for
+#   1. via installed_plugins.json under ${CLAUDE_CONFIG_DIR:-$HOME/.claude} — the installPath Claude Code
+#      itself records for the plugin, so a non-default config root or cache layout still resolves;
+#   2. via the plugin cache under the same root, newest by the <version> PATH-SEGMENT (the dir between
+#      /foundry/ and /scripts/), never a whole-path `sort -V` — a whole-path sort ranks by the marketplace
+#      name first, so with foundry installed under >1 marketplace an OLDER version under a lexically-
+#      greater marketplace could win (the §8 fix this wrapper has always carried);
+#   3. via the self-hosting source checkout, ${CLAUDE_PROJECT_DIR:-$PWD}/agentic-foundry/scripts/.
+# When none resolves, the token bar is rendered HERE from the payload — `⌂ <dir>:<branch> · tok <bar> NN%`
+# — so a missing renderer is visible as a plainer line, never as an absent one. `/foundry:doctor`'s
+# `statusline:` advisory says which of the four pieces is missing.
+#
+# FAIL-OPEN is the only invariant: any error → print what could be built (possibly nothing) and `exit 0`.
+set +e
+
+PAYLOAD="$(cat 2>/dev/null || true)"
+CFG="${CLAUDE_CONFIG_DIR:-${HOME}/.claude}"
+RENDERER="foundry-statusline.sh"
+
+selected=""
+# 1. installed_plugins.json (jq when available; the file is small and the key shape is fixed)
+if [ -r "${CFG}/plugins/installed_plugins.json" ] && command -v jq >/dev/null 2>&1; then
+  ip="$(jq -r '(.plugins."foundry@agentic-foundry" // ."foundry@agentic-foundry" // []) | (if type=="array" then .[0] else . end) | (.installPath // empty)' "${CFG}/plugins/installed_plugins.json" 2>/dev/null)"
+  [ -n "$ip" ] && [ -r "${ip}/scripts/${RENDERER}" ] && selected="${ip}/scripts/${RENDERER}"
+fi
+# 2. the plugin cache, newest by version segment
+if [ -z "$selected" ]; then
+  selected="$(
+    for cand in "${CFG}/plugins/cache/"*/foundry/*/scripts/${RENDERER}; do
+      [ -f "$cand" ] || continue
+      ver="$(basename "$(dirname "$(dirname "$cand")")")"
+      printf '%s\t%s\n' "$ver" "$cand"
+    done | sort -V -k1,1 | tail -1 | cut -f2-
+  )"
+fi
+# 3. the self-hosting source checkout
+if [ -z "$selected" ] || [ ! -r "$selected" ]; then
+  src="${CLAUDE_PROJECT_DIR:-$PWD}/agentic-foundry/scripts/${RENDERER}"
+  [ -r "$src" ] && selected="$src"
+fi
+
+# The resolved file must be the shipped renderer, not merely a file at a plausible path (security
+# review, Risk 3): its own header line is required before it is run. A miss falls through to the
+# inline bar, and so does a renderer that exits non-zero — `exec` on the right of a pipe only
+# replaces the subshell, so the bar below is what "never silently absent" rests on.
+if [ -n "$selected" ] && [ -r "$selected" ] && grep -q '^# foundry-statusline.sh' "$selected" 2>/dev/null; then
+  if printf '%s' "$PAYLOAD" | bash "$selected" "$@"; then
+    exit 0
+  fi
+fi
+
+# 4. inline fallback — the bar itself, from the payload, so it is never silently absent
+jqr() { printf '%s' "$PAYLOAD" | jq -r "$1" 2>/dev/null || true; }
+DIR=""; REM=""
+if command -v jq >/dev/null 2>&1; then
+  DIR="$(jqr '(.workspace.current_dir // .workspace.project_dir // .cwd // empty)')"
+  REM="$(jqr '(.context_window.remaining_percentage // empty)')"
+fi
+[ -n "$DIR" ] || DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+LABEL="$(basename "$DIR" 2>/dev/null)"
+BRANCH="$(git -C "$DIR" symbolic-ref --short HEAD 2>/dev/null || true)"
+[ -n "$BRANCH" ] && LABEL="${LABEL}:${BRANCH}"
+OUT="⌂ ${LABEL}"
+case "$REM" in
+  ''|*[!0-9.]*) ;;
+  *)
+    USED="$(printf '%.0f' "$(printf '100 - %s\n' "$REM" | bc -l 2>/dev/null || echo 0)" 2>/dev/null)"
+    [ -n "$USED" ] || USED=0
+    [ "$USED" -lt 0 ] 2>/dev/null && USED=0
+    [ "$USED" -gt 100 ] 2>/dev/null && USED=100
+    FILLED=$(( USED / 10 )); BAR=""
+    i=0; while [ $i -lt 10 ]; do if [ $i -lt $FILLED ]; then BAR="${BAR}█"; else BAR="${BAR}░"; fi; i=$((i+1)); done
+    OUT="${OUT} · tok ${BAR} ${USED}%"
+    ;;
+esac
+printf '%s\n' "$OUT"
+exit 0

package/templates/foundry-subagent-statusline.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# foundry-subagent-statusline.sh — version-agnostic, fail-open self-resolving subagentStatusLine wrapper
+# (feat-foundry-init-statusline-wrapper, AC-SLW-1; statusline-wiring v1.17.0, AC-SLW-3).
+#
+# Installed at .claude/hooks/foundry-subagent-statusline.sh by `npx update-agentic-workspace`, which also
+# sets subagentStatusLine.command to "$CLAUDE_PROJECT_DIR/.claude/hooks/foundry-subagent-statusline.sh".
+# The line above carrying the feature id is the FRAMEWORK MARKER the updater converges on.
+#
+# Same three-step resolution as the main wrapper (installed_plugins.json under
+# ${CLAUDE_CONFIG_DIR:-$HOME/.claude}, then the cache newest by version segment, then the self-hosting
+# source). A sub-agent row has no inline fallback: with no renderer it prints nothing and exits 0.
+set +e
+
+PAYLOAD="$(cat 2>/dev/null || true)"
+CFG="${CLAUDE_CONFIG_DIR:-${HOME}/.claude}"
+RENDERER="foundry-subagent-statusline.sh"
+
+selected=""
+if [ -r "${CFG}/plugins/installed_plugins.json" ] && command -v jq >/dev/null 2>&1; then
+  ip="$(jq -r '(.plugins."foundry@agentic-foundry" // ."foundry@agentic-foundry" // []) | (if type=="array" then .[0] else . end) | (.installPath // empty)' "${CFG}/plugins/installed_plugins.json" 2>/dev/null)"
+  [ -n "$ip" ] && [ -r "${ip}/scripts/${RENDERER}" ] && selected="${ip}/scripts/${RENDERER}"
+fi
+if [ -z "$selected" ]; then
+  selected="$(
+    for cand in "${CFG}/plugins/cache/"*/foundry/*/scripts/${RENDERER}; do
+      [ -f "$cand" ] || continue
+      ver="$(basename "$(dirname "$(dirname "$cand")")")"
+      printf '%s\t%s\n' "$ver" "$cand"
+    done | sort -V -k1,1 | tail -1 | cut -f2-
+  )"
+fi
+if [ -z "$selected" ] || [ ! -r "$selected" ]; then
+  src="${CLAUDE_PROJECT_DIR:-$PWD}/agentic-foundry/scripts/${RENDERER}"
+  [ -r "$src" ] && selected="$src"
+fi
+
+[ -n "$selected" ] || exit 0
+[ -r "$selected" ] || exit 0
+# The resolved file must be the shipped renderer (its own header line), not merely a file at a
+# plausible path — security review, Risk 3.
+grep -q '^# foundry-subagent-statusline.sh' "$selected" 2>/dev/null || exit 0
+printf '%s' "$PAYLOAD" | bash "$selected" "$@"
+exit 0

package/templates/permissions.yaml.tmpl

@@ -0,0 +1,37 @@
+# .foundry/permissions.yaml — this workspace's STANDING GRANTS as policy.
+#
+# The operator edits this file; the agent never does (`Edit`/`Write` on it are refused by the
+# compiled floor). `foundry-permissions-compile.py --write` turns every grant into one native
+# Claude Code rule `<tool>(<pattern>)` in .claude/settings.json; `--check` reports drift; the
+# doctor's `permissions-policy` line says `policy in-sync (<n>)` when the two agree. A contract's
+# `requires_capabilities` is checked against these grants by the capability preflight before an
+# atom is dispatched, so a denial surfaces before the work starts, not in the middle of it.
+#
+# Seeded EMPTY by `npx update-agentic-workspace` / `create-agentic-workspace --existing` and never
+# reconciled again (operator-owned). Schema: <plugin>/schema/permissions.schema.json.
+#
+# Each grant:
+#   id             a slug; surfaced in report and blocker lines
+#   tool           Bash | Edit | Write | Read | WebFetch | Agent
+#   pattern        the native rule's parenthesised body — the compiled rule is exactly <tool>(<pattern>)
+#   mode           automatic         — proceed once every listed precondition has been verified by command
+#                  approval_required — one blocker line naming this grant's id; the operator decides
+#   preconditions  closed set: ci-green, security-reviewed-label, spec-authorized, charter-committed,
+#                  worktree-clean, branch-up-to-date
+#
+# Two worked examples (commented out — copy one under `grants:` and edit it):
+#
+#   # An atom PR may be merged by the agent once its checks are green and the branch is current.
+#   - id: merge-atom-pr-when-green
+#     tool: Bash
+#     pattern: "gh pr merge:*"
+#     mode: automatic
+#     preconditions: [ci-green, branch-up-to-date]
+#
+#   # Pushing a tag is always the operator's call.
+#   - id: push-release-tag
+#     tool: Bash
+#     pattern: "git push origin v*"
+#     mode: approval_required
+schema_version: 1
+grants: []