@garygentry/feature-forge 0.2.3 → 0.2.4

package/adapters/gemini/skills/forge-guide/forge-guide.md

@@ -0,0 +1,188 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-guide/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-guide
+description: Explain what feature-forge is, when to use it, how to configure it, and its best practices — advisory guidance, not stage execution. Use when the user or another agent asks what feature-forge is, whether/when to adopt it, how the pipeline works conceptually, how to set up or configure forge.config.json, or for usage tips and best practices. Do NOT trigger to RUN a pipeline stage (use forge-1-prd … forge-6-docs), to show a specific feature's status (use forge), or for general software questions unrelated to feature-forge.
+---
+
+# Feature Forge — Usage & Best-Practices Guide
+
+You are the **guide** for feature-forge: an advisor, not an operator. Your job is to
+explain *what* forge is, *when* to use it, *how* to configure it, and *what the best
+practices are* — in plain language, grounded in the repo's own docs. You do **not**
+run pipeline stages; when the user is ready to act, point them at the right skill.
+
+## How to answer
+
+1. Identify the topic (the argument, or infer from the question).
+2. **Ground yourself in the canonical source before answering** — read the mapped
+   reference file(s) below rather than answering from memory. These are the source
+   of truth and stay current as the pipeline evolves.
+3. Answer concisely, then end with the concrete next command (`/feature-forge:forge-*`)
+   or doc pointer the user should go to.
+
+| Topic | Read first |
+|-------|-----------|
+| Pipeline architecture, stage-by-stage flow | `references/process-overview.md` |
+| Cross-stage conventions (naming, state, git, branch, epic injection) | `references/shared-conventions.md` |
+| Config keys + defaults | `references/forge-config-schema.json` |
+| Stack detection / language profiles | `references/stack-resolution.md`, `references/stacks/*.md` |
+| Loop runner interface, signals & version gate | `references/ralph-loop-contract.md` |
+| Deep dives, glossary, troubleshooting | `references/process-overview.md`, `references/shared-conventions.md` |
+
+Those `references/` files are the guaranteed grounding path — they ship in every install.
+The project's `README.md`, `COMPATIBILITY.md`, and the hosted docs site are richer but are
+**not** part of an installed bundle, so treat them as optional enrichment (offer the docs-site
+URL to a human) and never block an answer on opening them — fall back to the `references/`
+files and your own knowledge.
+
+Do NOT actually invoke stage skills or write files — this skill only explains and directs.
+
+## What feature-forge is
+
+A **feature development pipeline** that refines a vague idea into shipped code through
+discrete, auditable stages — like a compiler for features. Each stage narrows scope and
+adds structure, reading the previous stage's artifacts as standalone contracts:
+
+- **PRD** — *what* to build (requirements only, no technology).
+- **Tech spec** — *how* to build it (design, grounded in the codebase).
+- **Implementation specs** — build-ready detail (types, signatures, contracts, tests).
+- **Backlog** — self-contained work items for autonomous execution.
+- **Loop** — a fresh-context runner implements each item, tests, and commits.
+- **Docs** — architecture reference generated from the real implementation.
+
+`REQ-XXX-NN` requirement IDs form a traceability spine from PRD through implementation.
+**Verification gates** are available after any stage and run clean-room in a fresh subagent.
+
+## When to use it — and when not
+
+**Use forge when:** you have a well-defined feature or small epic to ship; you want
+requirements captured cleanly before coding; you value traceability, thorough spec
+verification, and autonomous loop execution with fresh context per item; you want
+reproducible, auditable artifacts.
+
+**Skip forge when:** the work is an exploratory spike with still-fluid requirements
+(though Stage 1's interview can help clarify them); it's a one-line bug fix or trivial
+patch where pipeline overhead isn't justified; or you're only extending mature code
+along established patterns, where new specs become noise.
+
+**Anti-patterns to warn against:** skipping the PRD and jumping to tech spec (the value
+comes from separating *what* from *how*); treating specs as living contracts (they're
+pre-implementation — drop an `AGENTS.md`/`CLAUDE.md` in the specs dir telling agents to
+ignore drift); forcing an epic for a single feature; relying on conversation memory to
+carry context across stages instead of reading upstream artifacts.
+
+## The pipeline at a glance
+
+| Stage | Skill | Produces |
+|-------|-------|----------|
+| 0 (optional) | `forge-0-epic` | `epic-manifest.json` + `EPIC.md` (members, deps, `exposes`/`consumes` contracts) |
+| 1 | `forge-1-prd` | `PRD.md` with `REQ-*` IDs |
+| 2 | `forge-2-tech` | `tech-spec.md`; detects stack + test/typecheck commands |
+| 3 | `forge-3-specs` | numbered spec suite + `TRACEABILITY.md` |
+| 4 | `forge-4-backlog` | `backlog.json` (self-contained items) |
+| 5 | `forge-5-loop` | implemented code, tested + committed per item |
+| 6 | `forge-6-docs` | architecture docs from the real code |
+| any | `forge-verify` → `forge-fix` | findings report → applied fixes |
+| any | `forge` | status dashboard / navigator |
+
+Drive the whole thing with the **navigator**: `/feature-forge:forge <feature>` shows the
+current stage and offers the next; with `autoInvokeNextStage` it launches it directly.
+
+## Setup & configuration
+
+**First-time setup:** `/feature-forge:forge-init` (existing repo) creates `forge.config.json`
+with defaults. `/feature-forge:forge-bootstrap` scaffolds a *greenfield* (empty) repo to a
+green baseline. On non-Claude agents, install via `npx @garygentry/feature-forge install`.
+
+**Key `forge.config.json` knobs** (authoritative list: `references/forge-config-schema.json`):
+
+- **Paths** — `specsDir` (`./specs`), `docsDir` (`./docs/architecture`), `backlogDir`.
+- **Git** — `gitCommitAfterStage` (true), `commitPrefix` (`forge`); commits use a two-commit
+  protocol so the stage's commit hash is recorded in state without `--amend`.
+- **Branch** — `branchPerFeature` (true), `branchPrefix` (`forge/`): isolate each feature.
+- **Stack** — `stack`, `typeCheckCommand`, `testCommand`: null until Stage 2 auto-detects them.
+- **Context** — `contextWindowTokens`, `contextWarnThreshold` (0.7): the navigator warns to
+  clear your session / start a fresh session past this fullness. On 1M-context models set `contextWindowTokens` explicitly.
+- **Verification** — `autoVerify` (false), `autoVerifyStages`, `autoFix` (false).
+- **Stage flow** — `autoInvokeNextStage` (true on Claude, print-only elsewhere).
+- **Loop** — `loopRunner` block (binary, command templates, version gate, agent selection);
+  defaults to **rauf** when absent. `workspaces` supports monorepos.
+
+## Verification gates
+
+`forge-verify <feature>` dispatches the read-only `forge-verifier` subagent to find gaps,
+inconsistencies, and quality issues; it writes a findings doc, and `forge-fix` applies them.
+Because verification runs in a **fresh subagent**, it's clean-room by construction — it never
+needs a clear your session / start a fresh session, and it's safe to automate with `autoVerify: true` (fixing stays human-gated
+unless `autoFix: true`). **Always verify before Stage 5 (the loop)** — catching errors in
+specs/backlog is far cheaper than mid-loop. Verifying after PRD and after backlog is also
+recommended. A findings pass is fresh only while the artifact `version` matches what was
+verified; revise upstream and downstream re-verifies.
+
+## Context management
+
+Each stage reads upstream artifacts as standalone contracts, so you can (and usually should)
+clear your session / start a fresh session between them:
+
+- **Clear** between PRD → tech, tech → specs, specs → backlog, backlog → loop.
+- **Stay warm** mid-interview (PRD, tech spec) — the interview needs a continuous thread.
+- **No clear needed** for any → verify (runs in a fresh subagent).
+
+The navigator warns when the session passes `contextWarnThreshold` (default 70% full).
+
+## Epics (large changes)
+
+Use Stage 0 only when a change naturally splits into **several interdependent features** that
+must agree on interfaces. `forge-0-epic` produces `epic-manifest.json` + `EPIC.md` with a
+per-member charter, `exposes`/`consumes` contracts, and `dependsOn` edges. Each member then
+runs the normal pipeline with epic context injected. At Stage 5 a **dependency gate** warns if
+a member's dependencies are unmet. Epic support is purely additive — single-feature flows are
+unchanged. Re-run `forge-0-epic` on an existing epic to enter edit mode.
+
+## The loop
+
+Stage 5 runs a configurable runner (**rauf** by default) that gives each backlog item a fresh
+agent session — implement → run the verification command → commit on pass. This is why items
+must be truly **self-contained**; context bleed breaks the model. Per-item signals:
+
+- `RAUF_DONE` — item passed; loop continues.
+- `RAUF_BLOCKED` — missing dependency / unclear requirement; set aside, loop continues others.
+- `RAUF_NEEDS_HUMAN` — decision or secret needed; set aside, loop continues.
+
+The loop doesn't pause on blocked items. Supply what's missing, then `rauf resume <path>` to
+retry set-aside items. The runner refuses to start with a **dirty working tree** and enforces
+a minimum runner version (the version gate is described in `references/ralph-loop-contract.md`).
+
+## Best practices & gotchas
+
+- Feature name is **required** for every stage command — never guess or infer it.
+- Verify **before the loop**; a bad spec is cheap to fix now, expensive mid-loop.
+- Keep backlog items self-contained — the loop has zero memory across items.
+- Let stages commit for you; don't hand-edit `.pipeline-state.json` or backlog status.
+- Re-running an upstream stage marks downstream stages **stale** — re-run them rather than
+  reaching for `--force`, which skips prerequisite checks and should be rare.
+- Specs are pre-implementation artifacts, not living docs — don't cite them from generated code.
+- Use the navigator (`/feature-forge:forge <feature>`) to orient; use `forge-verify` to inspect.
+
+## Troubleshooting starters
+
+- **Stage 5 won't start:** backlog exists and is verified? runner installed and ≥ min version?
+  working tree clean? See `references/ralph-loop-contract.md` for the runner contract and version gate.
+- **Loop stopped mid-run:** check the signal — `BLOCKED`/`NEEDS_HUMAN` items are set aside, not
+  failures; the loop keeps going.
+- **Downstream flagged stale:** an upstream stage was revised; re-run the downstream stage.
+- **Where am I?** `/feature-forge:forge <feature>` renders the full pipeline status.
+
+For anything deeper, ground yourself in `references/process-overview.md` and
+`references/shared-conventions.md`, and point the *user* at the hosted docs site —
+<https://garygentry.github.io/feature-forge/> — for the full guides and glossary.
+
+---
+
+## Host execution notes
+
+This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". Use your runtime's equivalent for each — and if your runtime has no such tool:
+
+- **User input:** ask the question directly and wait for the answer before proceeding. Do not skip a required question or assume an answer.
+- **Subagents:** if your host cannot dispatch the named custom agent, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground (or your host's background facility) and report progress as it arrives.

package/adapters/gemini/skills/forge-init/forge-init.md

@@ -9,7 +9,7 @@ description: Initialize feature-forge configuration in the current project. Use
 Run the initialization script to create `forge.config.json` with default settings:
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+R="$(bash -c 'for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 bash "$R/scripts/forge-init.sh"
 ```
@@ -26,9 +26,36 @@ After initialization, the config file will contain defaults for:
 - `autoInvokeNextStage`: `true` (the navigator auto-starts the next stage after you confirm; set `false` to only print the command)
 - `contextWindowTokens`: `null` (the navigator infers the context window; set to your model's window, e.g. `1000000` for a 1M-context model, for accurate context-usage advice)
 - `contextWarnThreshold`: `0.7` (fraction of the window past which the navigator suggests a clean session)
+- `autoVerify`: `false` (set `true` to run `forge-verify` automatically after each stage completes)
+- `autoVerifyStages`: `{}` (per-stage overrides for `autoVerify`)
+- `autoFix`: `false` (set `true` to chain `forge-fix` after an auto-verify finds issues)
 
 If `forge.config.json` already exists, the script will not overwrite it.
 
+## Offer auto-verify
+
+The template writes `autoVerify: false`. After the config is created (and only when the script
+actually created it — skip this if it reported the file already exists), offer to turn
+auto-verify on, then write the choice back into `forge.config.json`.
+
+If the host's question mechanism is available, ask exactly one question:
+
+> **Enable auto-verify?** Verification runs in a clean-room subagent after each stage
+> completes — it never needs a clear your session / start a fresh session and only returns a compact digest to your session.
+> **Recommended: on.** (Change later by editing `autoVerify` in `forge.config.json`.)
+
+Options: **Enable (recommended)** / **Leave off**.
+
+- On **Enable**: patch `"autoVerify": false` → `"autoVerify": true` in the generated
+  `forge.config.json` in place, preserving formatting and every other key.
+- On **Leave off**: leave the config as written (`autoVerify: false`).
+
+If the host lacks a structured question tool but can still prompt the user (e.g. Codex asks in
+plain text), use that — ask the one question directly and wait for the reply; it is the same
+choice, just rendered differently. Only when the host has **no** way to ask at all (a fully
+non-interactive / headless run) do you skip the prompt: leave `autoVerify: false` and print the
+one-line note `Set "autoVerify": true in forge.config.json to verify automatically after each stage.`
+
 After initialization, start the pipeline with `/feature-forge:forge-1-prd <feature-name>`.
 
 ---

package/adapters/gemini/skills/forge-verify/forge-verify.md

@@ -47,7 +47,7 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
 
 The verifier(s) are read-only — they return findings as their response; **you** (the
 parent) assemble and write the single document to
-`{specsDir}/{feature}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`. When you fanned out:
+`{resolvedFeatureDir}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`. When you fanned out:
 1. Concatenate all instances' findings and **renumber `V-NNN` IDs uniquely** across the
    merged set.
 2. **Dedup** overlaps — when two instances flag the same file+location+issue (e.g. a
@@ -72,15 +72,39 @@ without subagents), fall back to running verification inline in the current sess
 
 **Inline execution guidance:** If running inline (not as subagent), process verification checklists one category at a time to manage context pressure. Load only the artifacts needed for each category, verify, summarize findings, then move to the next category.
 
+### Require-clean (`auto`) mode — unattended auto-verify
+
+When the navigator auto-invokes this skill (its `autoVerify` path), it passes a
+**require-clean** signal (e.g. args include `--require-clean`, or the invocation is
+described as auto-verify). In this mode the clean-room guarantee is load-bearing: the
+whole reason auto-verify is safe to run without a clear your session / start a fresh session is that the `forge-verifier`
+subagent inherits none of the dispatching session's context. Running inline would break
+that — it would consume the dispatching session's context and invalidate the no-clear
+justification.
+
+So in require-clean mode, **do NOT fall back to inline execution**. If the host's subagent mechanism
+or `forge-verifier` subagent is not dispatchable, return a **sentinel** instead of doing
+any work:
+
+> `CLEAN_ROOM_UNAVAILABLE: forge-verifier subagent not dispatchable — verify not run.`
+
+Do not analyze artifacts, do not write a findings document, and do not touch pipeline
+state. The navigator detects this sentinel and degrades to its manual verify gate (Tier
+2/3), so verify state stays outstanding and the stage is never marked verified on false
+assurance. **Manual / interactive invocation** (the normal `/feature-forge:forge-verify`
+path, no require-clean signal) keeps the inline fallback above unchanged.
+
 ## Prerequisites
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
 
+Resolve the feature directory via the **Feature Directory Resolution** block in `references/shared-conventions.md` (so a standalone feature resolves to its flat `{specsDir}/{feature}/` path exactly as today, and an epic member resolves to its nested `{specsDir}/{epic}/{feature}/` path). Use the resulting `{resolvedFeatureDir}` everywhere this skill reads or writes a per-feature artifact or state file — the `{specsDir}/{feature}/…` forms below are shorthand for the resolved path, not a literal flat layout. This does not apply to **epic mode**, whose paths are epic-scoped (`{specsDir}/{epic}/…`) by design.
+
 **Turn structure reminder:** Output analysis/context as text, then route ALL questions through the host's question mechanism. Never embed questions in text output — the user will not be prompted and the session will stall.
 
 ## Step 1: Read Configuration and Determine Mode
 
-Read `{specsDir}/{feature}/.pipeline-state.json` to understand current pipeline state.
+Read `{resolvedFeatureDir}/.pipeline-state.json` to understand current pipeline state.
 
 ### Mode Selection
 
@@ -100,16 +124,16 @@ If ambiguous, use the host's question mechanism to ask which stage to verify.
 Load into context ALL artifacts for this feature based on mode:
 
 **For prd mode:**
-- `{specsDir}/{feature}/PRD.md`
+- `{resolvedFeatureDir}/PRD.md`
 
 **For tech mode:**
-- `{specsDir}/{feature}/PRD.md`
-- `{specsDir}/{feature}/tech-spec.md`
+- `{resolvedFeatureDir}/PRD.md`
+- `{resolvedFeatureDir}/tech-spec.md`
 
 **For specs mode:**
-- `{specsDir}/{feature}/PRD.md`
-- `{specsDir}/{feature}/tech-spec.md`
-- `{specsDir}/{feature}/##-*.md` (all implementation specs)
+- `{resolvedFeatureDir}/PRD.md`
+- `{resolvedFeatureDir}/tech-spec.md`
+- `{resolvedFeatureDir}/##-*.md` (all implementation specs)
 
 **For backlog mode:**
 - All of the above, PLUS
@@ -150,7 +174,7 @@ Every finding must include:
 
 ## Step 4: Write Findings Document
 
-Ensure the `.verification/` subdirectory exists, then write findings to `{specsDir}/{feature}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`.
+Ensure the `.verification/` subdirectory exists, then write findings to `{resolvedFeatureDir}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`.
 
 **For epic mode**, the target is `{specsDir}/{epic}/.verification/VERIFY-epic-{YYYY-MM-DD}.md` (the same format, with `{mode}=epic`).
 
@@ -186,9 +210,16 @@ Do NOT embed this question in your text output.
 
 Write pipeline state conforming to `references/pipeline-state-schema.json`.
 
-Update `{specsDir}/{feature}/.pipeline-state.json`:
-- Set the relevant verify entry status to `findings-reported`
+Update `{resolvedFeatureDir}/.pipeline-state.json`:
+- Set the relevant verify entry status to `findings-reported` (or `passed` when there
+  are zero findings)
 - Record `findingsFile`, `findingsCount`, `verifiedAt`
+- Record `verifiedStageVersion` = the current `version` of the production stage entry
+  this verify covers (e.g. verifying `tech` → `stages["forge-2-tech"].version`). This
+  feeds the navigator's freshness ledger: a later revision to that artifact bumps its
+  `version`, so the recorded value no longer matches and auto-verify re-fires. Omitting
+  this leaves the verify looking stale (safe: the navigator re-verifies rather than
+  skips).
 
 Do NOT mark as `findings-applied` — that happens after the fix pass.
 
@@ -213,13 +244,13 @@ Do NOT mark as `findings-applied` — that happens after the fix pass.
 - Don't verify things that are intentionally left open (check the PRD's "Open Questions" section).
 - If you find zero issues, say so honestly. Don't manufacture findings to seem thorough. But zero findings on a complex feature is suspicious — double-check.
 - The findings document must be self-contained. A fresh agent reading it should be able to apply every fix without needing conversational context from this session.
-- For backlog verification, also run the loop runner's validate command (resolve `loopRunner` from `forge.config.json`, default rauf: `rauf backlog validate . --backlog {backlogDir} --specs-dir {specsDir}/{feature} --json`). Include any findings it reports (exit 1) as verification findings; if the runner isn't installed yet (command missing), note that backlog validation was skipped rather than failing.
+- For backlog verification, also run the loop runner's validate command (resolve `loopRunner` from `forge.config.json`, default rauf: `rauf backlog validate . --backlog {backlogDir} --specs-dir {resolvedFeatureDir} --json`). Include any findings it reports (exit 1) as verification findings; if the runner isn't installed yet (command missing), note that backlog validation was skipped rather than failing.
 - For specs verification, also run the deterministic traceability validator to supplement agent-driven traceability checks. Include any uncovered requirements or orphaned references as findings:
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+R="$(bash -c 'for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
-python3 "$R/scripts/validate-traceability.py" {specsDir}/{feature}/PRD.md {specsDir}/{feature}/ --json
+python3 "$R/scripts/validate-traceability.py" {resolvedFeatureDir}/PRD.md {resolvedFeatureDir}/ --json
 ```
 
 ---

package/adapters/gemini/skills/forge-verify/references/verification-checklists.md

@@ -192,7 +192,7 @@ findings to E01/E02/E03/E08. Then perform the judgment checks E04–E07 by readi
 manifest, EPIC.md, and completed members' specs.
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+R="$(bash -c 'for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}" --json
 ```

package/dist/apply.js

@@ -91,8 +91,9 @@ async function applyCopyInstall(planned, ctx) {
     if (!placementResult.ok)
         return fail(ctx, planned, placementResult.error);
     // No-op short-circuit (REQ-IDEM-01): every action — primary AND placement — unchanged ⇒ zero
-    // writes, manifest untouched.
-    if (allUnchanged(planned)) {
+    // writes, manifest untouched — UNLESS manifest metadata (raufPin) drifted, which must persist
+    // even with no file change (F1) so report / on-disk manifest / a later `list` agree.
+    if (allUnchanged(planned) && !manifestNeedsRewrite(ctx)) {
         return success(ctx, planned);
     }
     const manifest = buildManifest({
@@ -113,6 +114,18 @@ async function applyCopyInstall(planned, ctx) {
         return fail(ctx, planned, wrote.error);
     return success(ctx, planned);
 }
+/**
+ * True when manifest metadata diverges from the prior manifest, so the manifest must be rewritten
+ * even when every file action is "unchanged" (F1). Today the only such field is `raufPin`; a null
+ * prior manifest also counts (there is nothing recorded yet). `updatedAt` is deliberately NOT a
+ * trigger — it is a consequence of writing, so keying on it would defeat the idempotency short-circuit.
+ */
+function manifestNeedsRewrite(ctx) {
+    const prior = ctx.priorManifest;
+    if (prior === null)
+        return true;
+    return prior.raufPin !== ctx.raufPin;
+}
 /** True iff every planned action — primary files and all placement files — is "unchanged". */
 function allUnchanged(planned) {
     return (planned.files.every((f) => f.action === "unchanged") &&
@@ -164,8 +177,8 @@ async function applySymlinkInstall(planned, ctx) {
     const primary = planned.files;
     const primaryUntouched = primary.every((f) => f.action === "unchanged") ||
         primary.every((f) => f.action === "skip-modified");
-    // Nothing changed anywhere ⇒ zero writes, manifest untouched.
-    if (allUnchanged(planned)) {
+    // Nothing changed anywhere ⇒ zero writes, manifest untouched — unless raufPin drifted (F1).
+    if (allUnchanged(planned) && !manifestNeedsRewrite(ctx)) {
         return success(ctx, planned);
     }
     // The recorded mode/link reflect the primary namespace dir: only (re)link when it actually changed
@@ -285,12 +298,25 @@ async function applyMirror(pl, ctx, source, prior) {
             case "skip-modified": {
                 // Carry the prior record forward; if none exists (e.g. a v1→v2 manifest migration where the
                 // file is already on disk), reconstruct it by hashing the destination so the inventory stays
-                // faithful rather than silently dropping an unrecorded-but-present file.
+                // faithful rather than silently dropping an unrecorded-but-present file. Guard the hash: a
+                // TOCTOU vanish (file removed after planning) must yield an err Result, never throw ENOENT
+                // out of apply (REQ-OBS-03 — a throw would abort every sibling agent at the CLI boundary).
                 const p = priorByPath.get(fa.relpath);
-                if (p !== undefined)
+                if (p !== undefined) {
                     inventory.push(p);
-                else
-                    inventory.push({ path: fa.relpath, sha256: sha256File(destAbs) });
+                }
+                else {
+                    try {
+                        inventory.push({ path: fa.relpath, sha256: sha256File(destAbs) });
+                    }
+                    catch {
+                        return err({
+                            code: "UNEXPECTED",
+                            agent: ctx.agent,
+                            message: `mirror file "${fa.relpath}" vanished before it could be recorded (${destAbs})`,
+                        });
+                    }
+                }
                 break;
             }
         }

package/dist/cli.js

@@ -23,7 +23,8 @@ import { plan, resolveMode } from "./plan.js"; // 04
 import { apply } from "./apply.js"; // 04
 import { manifestPath, readManifest, planUninstall } from "./manifest.js"; // 05
 import { preflightRauf, RAUF_PIN } from "./rauf.js"; // 06
-import { sha256File } from "./hash.js"; // 03 (list destination-drift hashing)
+import { sha256File, sha256String } from "./hash.js"; // 03 (list destination-drift hashing)
+import { extractManagedRegion } from "./placements.js"; // A4b managed-block drift
 import { renderReport } from "./report.js"; // 09
 /** Canonical subcommand table (REQ-DIST-03, §1.2). */
 export const SUBCOMMANDS = [
@@ -424,12 +425,18 @@ function listOneAgent(agent, detection, flags, scope, env) {
 /**
  * Return `"true"` if any manifest-recorded file's on-disk bytes differ from its recorded sha256
  * (a locally-modified destination, REQ-SAFE-03), `"false"` if every recorded file matches, or
- * `"n/a(symlink)"` for a symlink-mode install (no per-file sha256 to compare). A missing recorded
- * file also counts as drift. Pure read of the manifest's per-file sha256 against a fresh local
- * hash — no network, no source bundle needed (REQ-PERF-01). Hash errors are swallowed as drift
+ * `"n/a(symlink)"` for a symlink-mode primary install (no per-file sha256 to compare). A missing
+ * recorded file also counts as drift. Pure read of the manifest's per-file sha256 against a fresh
+ * local hash — no network, no source bundle needed (REQ-PERF-01). Hash errors are swallowed as drift
  * (an unreadable recorded file is itself a deviation from the clean install).
+ *
+ * Secondary placements (A4b) are checked in EVERY mode — they are always copy-written with a recorded
+ * hash even when the primary namespace is a symlink, so ignoring them (the prior behavior) left codex
+ * `.toml` mirrors and copilot managed blocks unwatched for drift.
  */
 function detectDestinationDrift(manifest) {
+    if (detectPlacementDrift(manifest))
+        return "true";
     if (manifest.mode === "symlink")
         return "n/a(symlink)";
     for (const f of manifest.files) {
@@ -445,6 +452,35 @@ function detectDestinationDrift(manifest) {
     }
     return "false";
 }
+/**
+ * True iff any secondary placement diverges from its recorded hash. A "mirror" file drifts when its
+ * on-disk bytes differ from the recorded sha256 (destination is a DIR, paths relative to it). A
+ * "managed-block" drifts when the sentinel region extracted from the (user-owned) target FILE no
+ * longer hashes to the recorded region hash — or the region is gone entirely. Read errors count as
+ * drift, matching the primary check.
+ */
+function detectPlacementDrift(manifest) {
+    for (const p of manifest.placements ?? []) {
+        for (const f of p.files) {
+            if (f.sha256 === undefined)
+                continue;
+            try {
+                if (p.kind === "managed-block") {
+                    const region = extractManagedRegion(readFileSync(p.destination, "utf8"));
+                    if (region === null || sha256String(region) !== f.sha256)
+                        return true;
+                }
+                else if (sha256File(path.join(p.destination, f.path)) !== f.sha256) {
+                    return true;
+                }
+            }
+            catch {
+                return true; // unreadable/absent recorded placement ⇒ drift
+            }
+        }
+    }
+    return false;
+}
 // ---------------------------------------------------------------------------
 // 7. helpText and --version (§3.4)
 // ---------------------------------------------------------------------------

package/dist/fsutil.d.ts

@@ -1,16 +1,4 @@
 import type { Result } from "./types.js";
-/**
- * Resolve `segs` against `root` and assert the result lies WITHIN `root` (REQ-SEC-02). Returns the
- * resolved absolute path on success, or a PATH_ESCAPE InstallerError if a `..` segment or a
- * malformed agent id would escape the agent config root. MUST be called before ANY write/delete.
- *
- * Uses `path.relative` + the `..` prefix test (the robust boundary check — a bare string startsWith
- * would false-pass `/root-evil`).
- *
- * @param root - the containment boundary (the agent config root, e.g. <home>/.claude)
- * @param segs - path segments to join under root (destination, then a bundle-relative path)
- * @returns ok(absolutePath) if inside; err(PATH_ESCAPE) otherwise.
- */
 export declare function resolveWithin(root: string, ...segs: string[]): Result<string>;
 /**
  * Recursively copy `src` → `dest` (copy mode). The CALLER is responsible for having

package/dist/fsutil.js

@@ -19,6 +19,12 @@ import { ok, err } from "./types.js";
  * @param segs - path segments to join under root (destination, then a bundle-relative path)
  * @returns ok(absolutePath) if inside; err(PATH_ESCAPE) otherwise.
  */
+/** True iff `child` is strictly within `parent` (path.relative + `..`-prefix test, never a bare
+ *  `startsWith`). Shares the boundary logic of {@link resolveWithin} for a plain boolean check. */
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
 export function resolveWithin(root, ...segs) {
     const base = path.resolve(root);
     const target = path.resolve(base, ...segs);
@@ -125,7 +131,10 @@ export async function removeEmptyDirsWithin(startDir, stopRoot) {
         return contained;
     const stop = path.resolve(stopRoot);
     let cur = contained.value;
-    while (cur !== stop && cur.startsWith(stop)) {
+    // Robust boundary test (path.relative + `..` prefix), not a bare `cur.startsWith(stop)` — the
+    // exact anti-pattern this module warns against at the top: `startsWith` false-passes a sibling
+    // like `<stop>-evil`. Safe here by the ancestor invariant today, but don't rely on it.
+    while (cur !== stop && isWithin(stop, cur)) {
         let entries;
         try {
             entries = await fsp.readdir(cur);

package/dist/manifest.d.ts

@@ -28,7 +28,7 @@ export interface BuildManifestArgs {
     readonly skills: readonly string[];
     /** SHA-256 over the source bundle's canonical (sorted-path) file set — drift anchor (spec 03). */
     readonly sourceHash: string;
-    /** Recorded pinned rauf coordinate (e.g. "@garygentry/rauf@0.11.0"); `null` when `--skip-rauf` (spec 06). */
+    /** Recorded pinned rauf coordinate (e.g. "@garygentry/rauf@0.12.0"); `null` when `--skip-rauf` (spec 06). */
     readonly raufPin: string | null;
     /** Symlink mode only: the source bundle the namespace dir links to (REQ-SAFE-02). */
     readonly link?: {

package/dist/plan.js

@@ -220,8 +220,16 @@ function planSymlink(ctx) {
     const source = ctx.source;
     const prior = ctx.priorManifest;
     const priorExists = prior !== null;
-    const priorIsLiveSymlinkToSameTarget = priorExists && prior.link?.target === source.root;
-    const action = priorIsLiveSymlinkToSameTarget
+    const manifestSaysLive = priorExists && prior.link?.target === source.root;
+    // The manifest can claim a live symlink that no longer exists on disk (deleted, or clobbered by a
+    // regular file/dir). Copy mode self-heals via per-file hashing; symlink mode had no on-disk check
+    // and would classify a broken link "unchanged" forever. lstat the link and force a relink when the
+    // manifest says live but the link is absent/not-a-symlink (F2) — never "skip-modified", which apply
+    // treats as untouched and would leave the install broken.
+    if (manifestSaysLive && !isLiveSymlink(ctx.destination)) {
+        return [{ relpath: ".", action: "create" }];
+    }
+    const action = manifestSaysLive
         ? "unchanged"
         : priorExists
             ? ctx.force
@@ -230,6 +238,18 @@ function planSymlink(ctx) {
             : "create";
     return [{ relpath: ".", action }];
 }
+/**
+ * True iff `absPath` exists and is currently a symbolic link. `lstat`, not `readlink` — we only need
+ * the node type to decide whether a manifest-recorded symlink is still live (F2). Absent ⇒ false.
+ */
+function isLiveSymlink(absPath) {
+    try {
+        return fs.lstatSync(absPath).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
 /** Paths in the prior manifest that the current source no longer contains → `remove` (row 6). */
 function orphanRemovals(priorFiles, sourceFiles) {
     const inSource = new Set(sourceFiles.map((f) => f.relpath));

package/dist/rauf.d.ts

@@ -19,13 +19,13 @@ import { type Result } from "./types.js";
  *
  * Shape: `<name>@<version>` — the SCOPED package `@garygentry/rauf` (the unscoped `rauf` name is
  * blocked by npm's similarity filter). Advanced on each feature-forge release to a new
- * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.11.0.
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.12.0.
  *
- * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.11.0` resolves from the npm registry, so the
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.12.0` resolves from the npm registry, so the
  * preflight below passes by default. (Historically this pin pointed at an unpublished package and
  * the preflight was a designed-to-fail check — see the `--skip-rauf` escape hatch.)
  */
-export declare const RAUF_PIN = "@garygentry/rauf@0.11.0";
+export declare const RAUF_PIN = "@garygentry/rauf@0.12.0";
 /**
  * An injectable, READ-ONLY registry query (D1). Given a coordinate `name@version`, returns the
  * resolved version string on success, or an `InstallerError` if it is not resolvable.
@@ -37,7 +37,7 @@ export declare const RAUF_PIN = "@garygentry/rauf@0.11.0";
  * Contract: the query MUST be read-only — it MUST NOT install, MUST NOT mutate global npm
  * state, and MUST NOT execute rauf. `npm view` satisfies this (it only reads registry metadata).
  *
- * @param coordinate - the `name@version` to resolve, e.g. "@garygentry/rauf@0.11.0"
+ * @param coordinate - the `name@version` to resolve, e.g. "@garygentry/rauf@0.12.0"
  * @returns Result<string> — the resolved version on success; RAUF_UNRESOLVABLE on failure.
  */
 export type RegistryQuery = (coordinate: string) => Result<string>;

package/dist/rauf.js

@@ -20,13 +20,13 @@ import { err, ok } from "./types.js";
  *
  * Shape: `<name>@<version>` — the SCOPED package `@garygentry/rauf` (the unscoped `rauf` name is
  * blocked by npm's similarity filter). Advanced on each feature-forge release to a new
- * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.11.0.
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.12.0.
  *
- * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.11.0` resolves from the npm registry, so the
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.12.0` resolves from the npm registry, so the
  * preflight below passes by default. (Historically this pin pointed at an unpublished package and
  * the preflight was a designed-to-fail check — see the `--skip-rauf` escape hatch.)
  */
-export const RAUF_PIN = "@garygentry/rauf@0.11.0";
+export const RAUF_PIN = "@garygentry/rauf@0.12.0";
 /**
  * Resolvability preflight for the pinned default loop runner (D1; REQ-RAUF-01/02/03, OQ-1).
  *