@garygentry/feature-forge 0.1.5 → 0.2.1

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

@@ -12,7 +12,7 @@ Apply fixes from the most recent forge-verify findings document, with step-level
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
 
-**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+**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: Locate Findings Document
 
@@ -29,7 +29,7 @@ Read and follow `references/shared-conventions.md` for feature name validation,
 ## Step 3: Handle User Decisions
 
 If the "User Decisions Required" section has unresolved items:
-1. Present each decision to the user with the context from the findings, using `AskUserQuestion` for each decision point. Only recommend a specific option if the findings provide clear evidence for it; otherwise present options neutrally.
+1. Present each decision to the user with the context from the findings, using the host's question mechanism for each decision point. Follow the **Decision Support** protocol in `references/shared-conventions.md`: lead with a recommended option and put the trade-off in each option's description. When the findings provide clear evidence, recommend with confidence and cite it. When they don't, still offer a sensible default with the trade-offs, but flag it plainly as a judgment call rather than going neutral — a defaulted recommendation beats an unguided option dump.
 2. Wait for answers before proceeding
 3. Record decisions in the findings document under the "User Decisions Required" section (mark each as resolved)
 
@@ -62,3 +62,13 @@ Tell the user:
 "Fixes applied. Next steps:
   - Run `/feature-forge:forge-verify {feature}` again to confirm all issues are resolved
   - Or `/feature-forge:forge {feature}` to see pipeline status"
+
+---
+
+## 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; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+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)"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 bash "$R/scripts/forge-init.sh"
 ```
@@ -27,3 +27,13 @@ After initialization, the config file will contain defaults for:
 If `forge.config.json` already exists, the script will not overwrite it.
 
 After initialization, start the pipeline with `/feature-forge:forge-1-prd <feature-name>`.
+
+---
+
+## 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-verify/forge-verify.md

@@ -10,7 +10,7 @@ Analyze feature artifacts for completeness, consistency, and quality. Produce st
 
 ## Subagent Delegation
 
-This skill is delegated to the `forge-verifier` subagent via the Agent tool. The verifier subagent has:
+This skill is delegated to the `forge-verifier` subagent via the host's subagent mechanism. The verifier subagent has:
 - **Read-only tools** (Read, Glob, Grep, Bash) — it cannot accidentally modify specs
 - **Persistent memory** — it accumulates knowledge about this project's recurring issues and patterns across sessions
 - **The forge-verify skill pre-loaded** — so it has all verification checklists and guidance at startup
@@ -19,12 +19,12 @@ This skill is delegated to the `forge-verifier` subagent via the Agent tool. The
 
 Pick based on how many checks the mode carries (see the per-mode totals in Step 3):
 
-- **Small modes (prd ~15, tech ~15): single verifier.** Use the Agent tool once with
-  `subagent_type="forge-verifier"`, passing the feature name and mode. It runs all
+- **Small modes (prd ~15, tech ~15): single verifier.** Use the host's subagent mechanism once with
+  `the forge-verifier custom agent`, passing the feature name and mode. It runs all
   checks and returns findings.
 - **Large modes (specs ~38, backlog ~25, impl ~20): parallel dimensioned fan-out.**
   Split the mode's checklist into **dimension groups** and dispatch **one
-  `forge-verifier` per group, in parallel — a single message with multiple Agent
+  `forge-verifier` per group, in parallel — a single message with multiple subagent
   calls** (the `superpowers:dispatching-parallel-agents` pattern). Each instance owns a
   disjoint slice of CHECK-IDs, so it verifies deeper over a narrower scope and they all
   run concurrently. Suggested groups (map to the category clusters in
@@ -76,7 +76,7 @@ without subagents), fall back to running verification inline in the current sess
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
 
-**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+**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
 
@@ -93,7 +93,7 @@ If a stage is specified as a second argument (e.g., `/feature-forge:forge-verify
 - **backlog mode**: If `forge-4-backlog` is complete but `forge-verify-backlog` is not `passed` or `findings-applied`
 - **impl mode**: If user explicitly requests or if implementation code exists for this feature
 
-If ambiguous, use `AskUserQuestion` to ask which stage to verify.
+If ambiguous, use the host's question mechanism to ask which stage to verify.
 
 ## Step 2: Load All Relevant Artifacts
 
@@ -132,7 +132,7 @@ Read `references/verification-checklists.md` for the detailed checklists per mod
 
 Each check in `verification-checklists.md` has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: ~15 checks, tech: ~15 checks, specs: ~38 checks, backlog: ~25 checks, impl: ~20 checks, epic: ~8 checks), you likely skipped checks — go back and complete them.
 
-**Epic mode dispatch.** Epic mode is a small (~8-check) checklist, so per the single-vs-parallel rule above, dispatch a **single `forge-verifier`** via the Agent tool, passing the epic name and `mode=epic`. The verifier runs CHECK-E01..E08 from the `## Epic Mode Checklist` in `references/verification-checklists.md` (E01/E02/E03/E08 are delegated to `epic-manifest.py validate`/`check-name`; E04–E07 are verifier judgment) and returns its findings.
+**Epic mode dispatch.** Epic mode is a small (~8-check) checklist, so per the single-vs-parallel rule above, dispatch a **single `forge-verifier`** via the host's subagent mechanism, passing the epic name and `mode=epic`. The verifier runs CHECK-E01..E08 from the `## Epic Mode Checklist` in `references/verification-checklists.md` (E01/E02/E03/E08 are delegated to `epic-manifest.py validate`/`check-name`; E04–E07 are verifier judgment) and returns its findings.
 
 ### Important: Be Specific, Not General
 
@@ -175,7 +175,12 @@ When building the Fix Execution Plan:
 **If not in plan mode:** Output the following as text:
 "Findings and fix plan written to `{findings-file}`."
 
-Then use `AskUserQuestion` to ask: "Would you like to: (a) Review the findings first, (b) Run `/feature-forge:forge-fix {feature}` to apply fixes now, or (c) Enter plan mode and re-run `/feature-forge:forge-verify {feature}` for plan-mode workflow?" Do NOT embed this question in your text output.
+Then use the host's question mechanism to ask how to proceed. Follow the **Decision Support** protocol in `references/shared-conventions.md`: recommend a path based on the findings and give each option a one-line trade-off. Let the severity and volume of findings drive the recommendation — e.g. recommend (b) **Apply fixes now** when findings are clear-cut and mechanical; recommend (a) **Review first** when findings involve design judgment or you flagged low-confidence items; recommend (c) **plan-mode workflow** when the fixes are large or interdependent enough to warrant a reviewed plan. Present:
+- **(a) Review the findings first** — read `{findings-file}` and decide per-finding; safest, but you act on nothing until you return.
+- **(b) Run `/feature-forge:forge-fix {feature}` now** — applies the fix plan immediately; fastest, best when findings are unambiguous.
+- **(c) Enter plan mode and re-run `/feature-forge:forge-verify {feature}`** — produces a reviewable plan before any edits; best for large or risky fix sets.
+
+Do NOT embed this question in your text output.
 
 ## Step 6: Update Pipeline State
 
@@ -212,7 +217,17 @@ Do NOT mark as `findings-applied` — that happens after the fix pass.
 - 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; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+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)"
 [ -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
 ```
+
+---
+
+## 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-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; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+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)"
 [ -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/agent-targets.d.ts

@@ -10,7 +10,7 @@
  * one table row (REQ-SCALE-01) with no edit here. Read-only and total: nothing writes, spawns
  * an agent, or creates a directory. Zero runtime dependencies; only `node:` built-ins.
  */
-import { type AgentId, type AgentTarget, type DetectionResult, type ResolveOpts, type Scope } from "./types.js";
+import { type AgentId, type AgentTarget, type Confidence, type DetectionResult, type ResolveOpts, type Scope } from "./types.js";
 export { AGENT_TARGETS } from "./types.js";
 /**
  * Resolve the two filesystem roots all destinations derive from, applying defaults. This is
@@ -30,15 +30,31 @@ export declare function resolveRoots(opts?: ResolveOpts): {
  * Derive the absolute install destination for one agent under a given scope (REQ-DET-01,
  * REQ-FLAG-02):
  *
- *     <scopeRoot>/<configDirName>/<installSubdir>/<FEATURE_FORGE_NS>/
+ *     <scopeRoot>/<installBaseDir>/<installSubpath>/<FEATURE_FORGE_NS>/
  *
- * where `scopeRoot` is the home dir for `"global"` and the cwd for `"project"`. The path is
- * derived, never stored, so a new agent is one `AGENT_TARGETS` row (REQ-SCALE-01). Pure.
+ * where `scopeRoot` is the home dir for `"global"` and the cwd for `"project"`, and an empty
+ * `installSubpath` is skipped (the namespace dir sits directly under `installBaseDir`). The path
+ * is derived, never stored, so a new agent is one `AGENT_TARGETS` row (REQ-SCALE-01). Pure.
  *
  * @example destinationFor(AGENT_TARGETS.claude, "global", { home: "/h" })
  *   // → "/h/.claude/skills/feature-forge"
+ * @example destinationFor(AGENT_TARGETS.codex, "project", { cwd: "/p" })
+ *   // → "/p/.agents/skills/feature-forge"
  */
 export declare function destinationFor(target: AgentTarget, scope: Scope, opts?: ResolveOpts): string;
+/**
+ * The filesystem containment boundary every write for `target` is checked against (REQ-SEC-02):
+ *     <scopeRoot>/<installBaseDir>
+ * Decoupled from the detection dir so codex (installs under `.agents`) and copilot (`.github`)
+ * contain correctly even though they detect on `.codex`/`.copilot`. Pure.
+ */
+export declare function agentRootFor(target: AgentTarget, scope: Scope, opts?: ResolveOpts): string;
+/**
+ * The effective confidence for `target` under `scope` (A4): the per-row `projectConfidence`
+ * override applies only to project scope (e.g. gemini project = best-known); otherwise the
+ * row's `confidence`. Pure — surfaced in the report so install honesty is scope-accurate.
+ */
+export declare function confidenceFor(target: AgentTarget, scope: Scope): Confidence;
 /**
  * Detect a single agent on the host (REQ-DET-02). Detection is decided solely by the presence
  * of the agent's config dir under the active scope root (a `stat`, never an agent subprocess).

package/dist/agent-targets.js

@@ -44,18 +44,41 @@ function scopeRootFor(scope, roots) {
  * Derive the absolute install destination for one agent under a given scope (REQ-DET-01,
  * REQ-FLAG-02):
  *
- *     <scopeRoot>/<configDirName>/<installSubdir>/<FEATURE_FORGE_NS>/
+ *     <scopeRoot>/<installBaseDir>/<installSubpath>/<FEATURE_FORGE_NS>/
  *
- * where `scopeRoot` is the home dir for `"global"` and the cwd for `"project"`. The path is
- * derived, never stored, so a new agent is one `AGENT_TARGETS` row (REQ-SCALE-01). Pure.
+ * where `scopeRoot` is the home dir for `"global"` and the cwd for `"project"`, and an empty
+ * `installSubpath` is skipped (the namespace dir sits directly under `installBaseDir`). The path
+ * is derived, never stored, so a new agent is one `AGENT_TARGETS` row (REQ-SCALE-01). Pure.
  *
  * @example destinationFor(AGENT_TARGETS.claude, "global", { home: "/h" })
  *   // → "/h/.claude/skills/feature-forge"
+ * @example destinationFor(AGENT_TARGETS.codex, "project", { cwd: "/p" })
+ *   // → "/p/.agents/skills/feature-forge"
  */
 export function destinationFor(target, scope, opts) {
     const roots = resolveRoots(opts);
     const root = scopeRootFor(scope, roots);
-    return path.resolve(root, target.configDirName, target.installSubdir, FEATURE_FORGE_NS);
+    return path.resolve(root, target.installBaseDir, ...(target.installSubpath ? [target.installSubpath] : []), FEATURE_FORGE_NS);
+}
+/**
+ * The filesystem containment boundary every write for `target` is checked against (REQ-SEC-02):
+ *     <scopeRoot>/<installBaseDir>
+ * Decoupled from the detection dir so codex (installs under `.agents`) and copilot (`.github`)
+ * contain correctly even though they detect on `.codex`/`.copilot`. Pure.
+ */
+export function agentRootFor(target, scope, opts) {
+    const roots = resolveRoots(opts);
+    return path.resolve(scopeRootFor(scope, roots), target.installBaseDir);
+}
+/**
+ * The effective confidence for `target` under `scope` (A4): the per-row `projectConfidence`
+ * override applies only to project scope (e.g. gemini project = best-known); otherwise the
+ * row's `confidence`. Pure — surfaced in the report so install honesty is scope-accurate.
+ */
+export function confidenceFor(target, scope) {
+    return scope === "project" && target.projectConfidence
+        ? target.projectConfidence
+        : target.confidence;
 }
 /**
  * Detect a single agent on the host (REQ-DET-02). Detection is decided solely by the presence
@@ -79,6 +102,8 @@ export function detectAgent(id, opts) {
         detected,
         configDirsProbed: [configDir],
         destination: destinationFor(target, scope, opts),
+        confidence: confidenceFor(target, scope),
+        docsUrl: target.docsUrl,
         cliOnPath: cliOnPath(id), // advisory only; never gates `detected`
     };
 }

package/dist/apply.js

@@ -12,11 +12,13 @@
  * Zero runtime dependencies; only `node:` built-ins.
  */
 import * as fsp from "node:fs/promises";
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { ok, err } from "./types.js";
-import { sha256File } from "./hash.js";
+import { sha256File, sha256String } from "./hash.js";
 import { resolveWithin, symlinkDir, removePath, removeEmptyDirsWithin, } from "./fsutil.js";
 import { buildManifest, writeManifest } from "./manifest.js";
+import { wrapBlock, upsertBlock, removeBlock } from "./placements.js";
 /**
  * Execute one agent's `PlannedAction` against the filesystem, then write/delete the manifest.
  * Returns an `AgentReport` instead of throwing (REQ-OBS-03). See spec 04 §5.
@@ -84,8 +86,13 @@ async function applyCopyInstall(planned, ctx) {
             }
         }
     }
-    // No-op short-circuit (REQ-IDEM-01): every action unchanged ⇒ zero writes, manifest untouched.
-    if (planned.files.every((f) => f.action === "unchanged")) {
+    // Secondary placements (A4b) execute regardless of the primary mode; collect their inventory.
+    const placementResult = await applyPlacements(planned.placements ?? [], ctx, source);
+    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)) {
         return success(ctx, planned);
     }
     const manifest = buildManifest({
@@ -97,6 +104,7 @@ async function applyCopyInstall(planned, ctx) {
         skills: source.skills,
         sourceHash: source.sourceHash,
         raufPin: ctx.raufPin,
+        placements: placementResult.value,
         previous: ctx.priorManifest,
         now: () => new Date(ctx.now),
     });
@@ -105,6 +113,11 @@ async function applyCopyInstall(planned, ctx) {
         return fail(ctx, planned, wrote.error);
     return success(ctx, planned);
 }
+/** True iff every planned action — primary files and all placement files — is "unchanged". */
+function allUnchanged(planned) {
+    return (planned.files.every((f) => f.action === "unchanged") &&
+        (planned.placements ?? []).every((p) => p.files.every((f) => f.action === "unchanged")));
+}
 /** §5.3 copy-mode uninstall: remove recorded files, prune empty dirs, delete the manifest LAST. */
 async function applyCopyUninstall(planned, ctx) {
     for (const fa of planned.files) {
@@ -118,6 +131,9 @@ async function applyCopyUninstall(planned, ctx) {
     const pruned = await removeEmptyDirsWithin(ctx.destination, ctx.agentRoot);
     if (!pruned.ok)
         return fail(ctx, planned, pruned.error);
+    const placementsRemoved = await removePlacements(planned.placements ?? []);
+    if (!placementsRemoved.ok)
+        return fail(ctx, planned, placementsRemoved.error);
     const deleted = await deleteManifest(ctx);
     if (!deleted.ok)
         return fail(ctx, planned, deleted.error);
@@ -140,23 +156,35 @@ async function applySymlinkInstall(planned, ctx) {
     if (!resolved.ok)
         return fail(ctx, planned, resolved.error);
     const linkPath = resolved.value;
-    // Unchanged (live link already points at the same target) ⇒ zero writes, manifest untouched.
-    if (planned.files.every((f) => f.action === "unchanged")) {
+    // Secondary placements (A4b) apply even in symlink mode — they live under a different root than the
+    // symlinked namespace dir. Run them first so a placement-only change still rewrites the manifest.
+    const placementResult = await applyPlacements(planned.placements ?? [], ctx, source);
+    if (!placementResult.ok)
+        return fail(ctx, planned, placementResult.error);
+    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)) {
         return success(ctx, planned);
     }
-    // skip-modified (prior exists, no --force) ⇒ leave it; report, write nothing.
-    if (planned.files.every((f) => f.action === "skip-modified")) {
-        return success(ctx, planned);
+    // The recorded mode/link reflect the primary namespace dir: only (re)link when it actually changed
+    // (a placement-only change leaves a live link and its prior manifest mode/link intact).
+    let effectiveMode = ctx.priorManifest?.mode ?? "symlink";
+    let linkTarget = ctx.priorManifest?.link?.target ?? (effectiveMode === "symlink" ? source.root : undefined);
+    let files = ctx.priorManifest?.files ?? source.files.map((f) => ({ path: f.relpath }));
+    if (!primaryUntouched) {
+        const removed = await removePath(linkPath);
+        if (!removed.ok)
+            return fail(ctx, planned, removed.error);
+        const linked = await symlinkDir(source.root, linkPath);
+        if (!linked.ok)
+            return fail(ctx, planned, linked.error);
+        effectiveMode = linked.value.mode;
+        linkTarget = effectiveMode === "symlink" ? source.root : undefined;
+        // files[] lists the bundle-relative paths with sha256 OMITTED (no per-file copy exists, 00 §3).
+        files = source.files.map((f) => ({ path: f.relpath }));
     }
-    const removed = await removePath(linkPath);
-    if (!removed.ok)
-        return fail(ctx, planned, removed.error);
-    const linked = await symlinkDir(source.root, linkPath);
-    if (!linked.ok)
-        return fail(ctx, planned, linked.error);
-    const effectiveMode = linked.value.mode;
-    // files[] lists the bundle-relative paths with sha256 OMITTED (no per-file copy exists, 00 §3).
-    const files = source.files.map((f) => ({ path: f.relpath }));
     const manifest = buildManifest({
         agent: ctx.agent,
         scope: ctx.scope,
@@ -166,8 +194,9 @@ async function applySymlinkInstall(planned, ctx) {
         skills: source.skills,
         sourceHash: source.sourceHash,
         raufPin: ctx.raufPin,
+        placements: placementResult.value,
         // Truthful record: a copy fallback must NOT carry link (copy-mode manifest invariant, 05).
-        ...(effectiveMode === "symlink" ? { link: { target: source.root } } : {}),
+        ...(linkTarget !== undefined ? { link: { target: linkTarget } } : {}),
         previous: ctx.priorManifest,
         now: () => new Date(ctx.now),
     });
@@ -184,12 +213,210 @@ async function applySymlinkUninstall(planned, ctx) {
     const removed = await removePath(resolved.value);
     if (!removed.ok)
         return fail(ctx, planned, removed.error);
+    const placementsRemoved = await removePlacements(planned.placements ?? []);
+    if (!placementsRemoved.ok)
+        return fail(ctx, planned, placementsRemoved.error);
     const deleted = await deleteManifest(ctx);
     if (!deleted.ok)
         return fail(ctx, planned, deleted.error);
     return success(ctx, planned);
 }
 // ---------------------------------------------------------------------------
+// Secondary placements (A4b)
+// ---------------------------------------------------------------------------
+/**
+ * Execute every secondary placement for an install/update and return the inventory to record in the
+ * manifest. Each placement is contained to ITS OWN root (`resolveWithin(placement.root, …)`), so a
+ * mirror under `.codex` and a managed block under `.github` never escape their boundary (REQ-SEC-02).
+ * Unchanged/skip-modified entries carry their prior recorded hash forward so the manifest stays
+ * faithful. Never throws for expected errors.
+ */
+async function applyPlacements(placements, ctx, source) {
+    const priorByDest = new Map();
+    for (const p of ctx.priorManifest?.placements ?? [])
+        priorByDest.set(p.destination, p);
+    const out = [];
+    for (const pl of placements) {
+        const prior = priorByDest.get(pl.destination) ?? null;
+        const res = pl.kind === "mirror"
+            ? await applyMirror(pl, ctx, source, prior)
+            : await applyManagedBlock(pl, prior);
+        if (!res.ok)
+            return res;
+        out.push(res.value);
+    }
+    return ok(out);
+}
+/** §A4b mirror: copy/refresh/remove flat files under the second root; record per-file sha256. */
+async function applyMirror(pl, ctx, source, prior) {
+    const priorByPath = new Map();
+    for (const f of prior?.files ?? [])
+        priorByPath.set(f.path, f);
+    const writeFile = ctx.writeFileSeam ?? defaultCopyFile;
+    const inventory = [];
+    for (const fa of pl.files) {
+        const resolved = resolveWithin(pl.root, pl.destination, fa.relpath);
+        if (!resolved.ok)
+            return resolved;
+        const destAbs = resolved.value;
+        switch (fa.action) {
+            case "create":
+            case "overwrite": {
+                if (fa.srcRelpath === undefined) {
+                    return err({
+                        code: "UNEXPECTED",
+                        agent: ctx.agent,
+                        message: `mirror action for "${fa.relpath}" is missing its source path`,
+                    });
+                }
+                const wrote = await writeFile(path.join(source.root, fa.srcRelpath), destAbs);
+                if (!wrote.ok)
+                    return wrote;
+                inventory.push({ path: fa.relpath, sha256: sha256File(destAbs) });
+                break;
+            }
+            case "remove": {
+                const removed = await removePath(destAbs);
+                if (!removed.ok)
+                    return removed;
+                break;
+            }
+            case "unchanged":
+            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.
+                const p = priorByPath.get(fa.relpath);
+                if (p !== undefined)
+                    inventory.push(p);
+                else
+                    inventory.push({ path: fa.relpath, sha256: sha256File(destAbs) });
+                break;
+            }
+        }
+    }
+    return ok({ kind: "mirror", root: pl.root, destination: pl.destination, files: inventory });
+}
+/**
+ * §A4b managed-block: merge/refresh the sentinel block into the (possibly user-owned) target file,
+ * preserving everything outside the sentinels. Records a single inventory entry whose sha256 is the
+ * written region's hash. skip-modified/unchanged carry the prior record forward (no write).
+ */
+async function applyManagedBlock(pl, prior) {
+    const fa = pl.files[0];
+    const basename = fa?.relpath ?? path.basename(pl.destination);
+    const resolved = resolveWithin(pl.root, pl.destination);
+    if (!resolved.ok)
+        return resolved;
+    const fileAbs = resolved.value;
+    const carry = () => {
+        const p = prior?.files.find((f) => f.path === basename);
+        return {
+            kind: "managed-block",
+            root: pl.root,
+            destination: pl.destination,
+            files: p !== undefined ? [p] : [],
+        };
+    };
+    if (fa === undefined || fa.action === "unchanged" || fa.action === "skip-modified") {
+        return ok(carry());
+    }
+    if (fa.action === "remove") {
+        // Uninstall is handled by removePlacements; an install-plan never yields "remove" here.
+        return ok(carry());
+    }
+    // create | overwrite — read existing (or treat as empty), upsert the block, write back.
+    const body = pl.blockContent ?? "";
+    let existing = "";
+    try {
+        existing = fs.readFileSync(fileAbs, "utf8");
+    }
+    catch {
+        existing = "";
+    }
+    const next = upsertBlock(existing, body);
+    const wrote = await writeText(fileAbs, next);
+    if (!wrote.ok)
+        return wrote;
+    return ok({
+        kind: "managed-block",
+        root: pl.root,
+        destination: pl.destination,
+        files: [{ path: basename, sha256: sha256String(wrapBlock(body)) }],
+    });
+}
+/**
+ * Remove every secondary placement during uninstall (A4b): a "mirror" deletes each recorded file
+ * (and prunes its now-empty dir); a "managed-block" strips ONLY the sentinel region, deleting the
+ * file only if nothing else remains. User content outside the block is always preserved.
+ */
+async function removePlacements(placements) {
+    for (const pl of placements) {
+        if (pl.kind === "managed-block") {
+            const resolved = resolveWithin(pl.root, pl.destination);
+            if (!resolved.ok)
+                return resolved;
+            const fileAbs = resolved.value;
+            let existing;
+            try {
+                existing = fs.readFileSync(fileAbs, "utf8");
+            }
+            catch {
+                continue; // already gone — nothing to strip
+            }
+            const stripped = removeBlock(existing);
+            if (stripped === "") {
+                const removed = await removePath(fileAbs);
+                if (!removed.ok)
+                    return removed;
+            }
+            else {
+                const wrote = await writeText(fileAbs, stripped);
+                if (!wrote.ok)
+                    return wrote;
+            }
+            continue;
+        }
+        // mirror: remove each recorded file, then prune the now-empty destination dir.
+        for (const fa of pl.files) {
+            const resolved = resolveWithin(pl.root, pl.destination, fa.relpath);
+            if (!resolved.ok)
+                return resolved;
+            const removed = await removePath(resolved.value);
+            if (!removed.ok)
+                return removed;
+        }
+        const pruned = await removeEmptyDirsWithin(pl.destination, pl.root);
+        if (!pruned.ok)
+            return pruned;
+    }
+    return ok(undefined);
+}
+/** Write text content to `destAbs`, creating the parent dir; maps EACCES/EPERM to WRITE_DENIED. */
+async function writeText(destAbs, content) {
+    try {
+        await fsp.mkdir(path.dirname(destAbs), { recursive: true });
+        await fsp.writeFile(destAbs, content, "utf8");
+        return ok(undefined);
+    }
+    catch (e) {
+        const code = e?.code;
+        if (code === "EACCES" || code === "EPERM") {
+            return err({
+                code: "WRITE_DENIED",
+                message: `no write permission to ${destAbs}`,
+                path: destAbs,
+                remedy: "check directory permissions, or choose a different scope (--global vs project)",
+            });
+        }
+        return err({
+            code: "UNEXPECTED",
+            message: `filesystem error at ${destAbs}: ${e?.message ?? String(e)}`,
+            path: destAbs,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
 /** Default per-file write seam: ensure the parent dir, then copy the source bytes. */

package/dist/cli.js

@@ -16,7 +16,8 @@ import { readFileSync, realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import * as path from "node:path";
 import { AGENT_IDS, AGENT_TARGETS, EXIT, err, ok, } from "./types.js";
-import { detectAgent, detectAgents, resolveRoots } from "./agent-targets.js"; // 02
+import { detectAgent, detectAgents, agentRootFor } from "./agent-targets.js"; // 02
+import { resolvePlacements } from "./placements.js"; // 02 (A4b second-root placements)
 import { locateSource } from "./source.js"; // 03
 import { plan, resolveMode } from "./plan.js"; // 04
 import { apply } from "./apply.js"; // 04
@@ -254,7 +255,8 @@ async function runMutation(subcommand, flags, env) {
     for (const agent of targets) {
         const detection = detectAgent(agent, ropts);
         const r = await runOneAgent(subcommand, agent, detection, flags, scope, mode, raufPin, env);
-        agentReports.push(r);
+        // Carry the scope-effective confidence + docs URL onto the report for honest labeling (A4).
+        agentReports.push({ ...r, confidence: detection.confidence, docsUrl: detection.docsUrl });
     }
     const anyAgentFailed = agentReports.some((r) => !r.ok);
     const exitCode = anyAgentFailed || raufError !== undefined ? EXIT.FAILURE : EXIT.SUCCESS;
@@ -274,9 +276,9 @@ async function runMutation(subcommand, flags, env) {
 /** Run the pipeline for a single agent, returning its AgentReport (catches every expected error). */
 async function runOneAgent(subcommand, agent, detection, flags, scope, mode, raufPin, env) {
     const mpath = manifestPath(agent, scope, { home: env.home, cwd: env.cwd });
-    const roots = resolveRoots({ home: env.home, cwd: env.cwd, scope });
-    const scopeRoot = scope === "global" ? roots.home : roots.cwd;
-    const agentRoot = path.join(scopeRoot, AGENT_TARGETS[agent].configDirName);
+    // Containment boundary = the agent's install base dir (A4: decoupled from the detection dir,
+    // so codex contains under `.agents` and copilot under `.github`).
+    const agentRoot = agentRootFor(AGENT_TARGETS[agent], scope, { home: env.home, cwd: env.cwd });
     // uninstall path: manifest → planUninstall → apply.
     if (subcommand === "uninstall") {
         const m = readManifest(mpath);
@@ -319,6 +321,9 @@ async function runOneAgent(subcommand, agent, detection, flags, scope, mode, rau
         priorManifest: prior.value,
         force: flags.force,
         raufPin,
+        // A4b: resolve any second-root placements for this agent under the active scope (codex
+        // `.codex/agents`, copilot `.github/copilot-instructions.md`); empty for the rest.
+        placements: resolvePlacements(AGENT_TARGETS[agent], scope, { home: env.home, cwd: env.cwd }),
     };
     const planned = plan(subcommand, planCtx);
     if (!planned.ok)
@@ -367,7 +372,8 @@ async function runList(flags, env) {
     const agentReports = [];
     for (const agent of targets) {
         const detection = detectAgent(agent, ropts);
-        agentReports.push(listOneAgent(agent, detection, flags, scope, env));
+        const base = listOneAgent(agent, detection, flags, scope, env);
+        agentReports.push({ ...base, confidence: detection.confidence, docsUrl: detection.docsUrl });
     }
     const anyFailed = agentReports.some((r) => !r.ok);
     return {