@garygentry/feature-forge 0.1.4 → 0.2.0

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 {

package/dist/hash.d.ts

@@ -15,6 +15,11 @@
  *         for an already-located, integrity-checked bundle, caught at the operation boundary.
  */
 export declare function sha256File(filePath: string): string;
+/**
+ * SHA-256 of a UTF-8 string, hex-encoded. Used to fingerprint a managed-block region (A4b) so the
+ * planner can tell a clean prior block (recorded hash matches) from a user-edited one. Pure.
+ */
+export declare function sha256String(s: string): string;
 /**
  * Deterministic SHA-256 over a directory tree's file set (OQ-4). The digest is a function of the
  * set of `{ relativePosixPath, fileContentHash }` pairs ONLY — never of mtime, inode, or

package/dist/hash.js

@@ -21,6 +21,13 @@ export function sha256File(filePath) {
     const buf = fs.readFileSync(filePath);
     return createHash("sha256").update(buf).digest("hex");
 }
+/**
+ * SHA-256 of a UTF-8 string, hex-encoded. Used to fingerprint a managed-block region (A4b) so the
+ * planner can tell a clean prior block (recorded hash matches) from a user-edited one. Pure.
+ */
+export function sha256String(s) {
+    return createHash("sha256").update(Buffer.from(s, "utf8")).digest("hex");
+}
 /**
  * Deterministic SHA-256 over a directory tree's file set (OQ-4). The digest is a function of the
  * set of `{ relativePosixPath, fileContentHash }` pairs ONLY — never of mtime, inode, or

package/dist/manifest.d.ts

@@ -8,7 +8,7 @@
  * Zero runtime dependencies; only `node:` built-ins. Named exports only. Core functions return
  * `Result<T, E>` and never throw for expected errors; `JSON.parse` is wrapped in `try/catch`.
  */
-import { type AgentId, type InstallManifest, type ManifestFile, type Mode, type PlannedAction, type ResolveOpts, type Result, type Scope } from "./types.js";
+import { type AgentId, type InstallManifest, type ManifestFile, type Mode, type Placement, type PlannedAction, type ResolveOpts, type Result, type Scope } from "./types.js";
 /**
  * Inputs to {@link buildManifest}. The caller (apply.ts, spec 04) assembles this from the resolved
  * detection target, the chosen scope/mode, and the apply result's per-file inventory.
@@ -28,12 +28,14 @@ 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.7.0"); `null` when `--skip-rauf` (spec 06). */
+    /** Recorded pinned rauf coordinate (e.g. "@garygentry/rauf@0.8.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?: {
         readonly target: string;
     };
+    /** Secondary placement inventory written this run (A4b); omit/empty when the agent has none. */
+    readonly placements?: readonly Placement[];
     /** Prior manifest, if any. When present, its `installedAt` is preserved (this is an update). */
     readonly previous?: InstallManifest | null;
     /** Injectable clock for deterministic tests. Default: `() => new Date()`. */

package/dist/manifest.js

@@ -10,7 +10,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { AGENT_TARGETS, MANIFEST_PREFIX, SCHEMA_VERSION, ok, err, } from "./types.js";
+import { AGENT_TARGETS, MANIFEST_PREFIX, SCHEMA_VERSION, ok, err, READABLE_SCHEMA_VERSIONS, } from "./types.js";
 import { destinationFor } from "./agent-targets.js";
 /**
  * Assemble an {@link InstallManifest} from an apply result (REQ-SAFE-01/03). Pure — no I/O.
@@ -40,8 +40,18 @@ export function buildManifest(args) {
         skills,
         files,
         ...(args.link !== undefined ? { link: args.link } : {}),
+        ...(args.placements && args.placements.length > 0
+            ? { placements: args.placements.map(normalizePlacement) }
+            : {}),
     };
 }
+/** Canonicalize a placement for persistence: sort its file inventory by path (byte-wise). */
+function normalizePlacement(p) {
+    const files = [...p.files]
+        .map((f) => ({ path: f.path, ...(f.sha256 !== undefined ? { sha256: f.sha256 } : {}) }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return { kind: p.kind, root: p.root, destination: p.destination, files };
+}
 // ---------------------------------------------------------------------------
 // manifestPath
 // ---------------------------------------------------------------------------
@@ -142,7 +152,7 @@ function validateManifest(x) {
     if (typeof x !== "object" || x === null)
         return { ok: false, reason: "not an object" };
     const o = x;
-    if (o.schemaVersion !== SCHEMA_VERSION) {
+    if (!READABLE_SCHEMA_VERSIONS.includes(o.schemaVersion)) {
         return { ok: false, reason: `unsupported schemaVersion ${String(o.schemaVersion)}` };
     }
     if (typeof o.agent !== "string" || !AGENT_IDS_SET.has(o.agent)) {
@@ -196,8 +206,45 @@ function validateManifest(x) {
     if (o.mode === "copy" && o.link !== undefined) {
         return { ok: false, reason: "copy mode manifest must not carry link" };
     }
+    // Optional secondary placements (manifest v2, A4b). Absent on v1 and on agents without a rule.
+    if (o.placements !== undefined) {
+        if (!Array.isArray(o.placements))
+            return { ok: false, reason: "invalid placements[]" };
+        for (const p of o.placements) {
+            const reason = validatePlacement(p);
+            if (reason !== null)
+                return { ok: false, reason };
+        }
+    }
     return { ok: true, value: x };
 }
+/** Structural validation of one placement record; returns a reason string, or null if valid. */
+function validatePlacement(p) {
+    if (typeof p !== "object" || p === null)
+        return "placements[] entry not an object";
+    const o = p;
+    if (o.kind !== "mirror" && o.kind !== "managed-block") {
+        return `invalid placement kind ${String(o.kind)}`;
+    }
+    if (typeof o.root !== "string" || o.root.length === 0)
+        return "placement missing root";
+    if (typeof o.destination !== "string" || o.destination.length === 0) {
+        return "placement missing destination";
+    }
+    if (!Array.isArray(o.files))
+        return "invalid placement files[]";
+    for (const f of o.files) {
+        if (typeof f !== "object" || f === null)
+            return "invalid placement files[] entry";
+        const ff = f;
+        if (typeof ff.path !== "string")
+            return "placement files[].path not a string";
+        if (ff.sha256 !== undefined && typeof ff.sha256 !== "string") {
+            return "placement files[].sha256 not a string";
+        }
+    }
+    return null;
+}
 // ---------------------------------------------------------------------------
 // planUninstall — the uninstall removal POLICY
 // ---------------------------------------------------------------------------
@@ -212,11 +259,20 @@ export function planUninstall(manifest) {
     const files = isSymlink
         ? [{ relpath: ".", action: "remove" }]
         : manifest.files.map((f) => ({ relpath: f.path, action: "remove" }));
+    // Secondary placements (A4b) are removed too: a "mirror" deletes each recorded file; a
+    // "managed-block" strips only the sentinel region (apply interprets a "remove" action per kind).
+    const placements = (manifest.placements ?? []).map((p) => ({
+        kind: p.kind,
+        root: p.root,
+        destination: p.destination,
+        files: p.files.map((f) => ({ relpath: f.path, action: "remove" })),
+    }));
     return ok({
         agent: manifest.agent,
         scope: manifest.scope,
         mode: manifest.mode,
         destination: manifest.destination,
         files,
+        ...(placements.length > 0 ? { placements } : {}),
     });
 }

package/dist/placements.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Secondary install placements (A4b) — the second-root generalization the single-`destination`
+ * install model can't express. Two kinds (see {@link PlacementKind}):
+ *   - "mirror"        — codex copies the bundle's `agents/*.toml` FLAT into `.codex/agents/`, where
+ *                       Codex loads custom agents (it does NOT read them from `.agents/skills`).
+ *   - "managed-block" — copilot writes a sentinel-delimited pointer block into the (possibly
+ *                       user-owned) `.github/copilot-instructions.md`, preserving the rest of it.
+ *
+ * This module is PURE: it resolves declarative {@link PlacementSpec}s to absolute roots, selects the
+ * mirror source files, and provides the managed-block string transforms (render/upsert/remove/read).
+ * The planner (plan.ts) decides actions and the apply engine (apply.ts) executes them; neither knows
+ * the per-kind string mechanics — those live here. Zero runtime dependencies; only `node:` built-ins.
+ */
+import { type AgentTarget, type PlacementKind, type PlacementSpec, type ResolveOpts, type Scope } from "./types.js";
+import type { LocatedSource } from "./source.js";
+/** A {@link PlacementSpec} resolved to absolute paths under a scope. Pure derivation; nothing stored. */
+export interface ResolvedPlacement {
+    readonly kind: PlacementKind;
+    /** Absolute containment boundary (REQ-SEC-02): `<scopeRoot>/<spec.baseDir>`. */
+    readonly root: string;
+    /** Absolute destination: a DIR ("mirror") or a FILE ("managed-block"): `<root>/<spec.subpath>`. */
+    readonly destination: string;
+    readonly spec: PlacementSpec;
+}
+/**
+ * Resolve every secondary placement declared on `target` to absolute roots under `scope` (A4b).
+ * Returns `[]` for agents with no placements (claude/cursor/gemini). Pure; the single derivation
+ * point so a new rule stays one `AGENT_TARGETS` edit (REQ-SCALE-01).
+ */
+export declare function resolvePlacements(target: AgentTarget, scope: Scope, opts?: ResolveOpts): ResolvedPlacement[];
+/** One selected mirror source: the bundle-relative source and its FLAT destination basename. */
+export interface MirrorFile {
+    readonly srcRelpath: string;
+    readonly destRelpath: string;
+    readonly srcHash: string;
+}
+/**
+ * Select the bundle files a "mirror" placement copies (A4b): every `source.files` entry whose
+ * POSIX relpath starts with `spec.sourcePrefix`, copied FLAT (basename only) into the destination.
+ * Sorted by destination basename for deterministic plans. Pure.
+ */
+export declare function selectMirrorFiles(source: LocatedSource, spec: PlacementSpec): MirrorFile[];
+/**
+ * Render the managed-block BODY (without sentinels) for copilot (A4b). Points Copilot — which has no
+ * skills loader — at the staged bundle under `.github/feature-forge/` and lists the available skills.
+ * Deterministic given the bundle's skill ids. Pure.
+ */
+export declare function renderCopilotBlock(skills: readonly string[]): string;
+/** Wrap a rendered block body in the managed sentinels — the exact region written on disk. */
+export declare function wrapBlock(body: string): string;
+/**
+ * Extract the full managed region (sentinels INCLUDED) currently present in `content`, or `null` if
+ * no well-formed `start…end` region exists. The region is what `wrapBlock` produces, so its hash is
+ * directly comparable to a freshly rendered block. Pure.
+ */
+export declare function extractManagedRegion(content: string): string | null;
+/**
+ * Insert or replace the managed block in `existing`, preserving all user content outside the
+ * sentinels (A4b). If a region exists it is replaced in place; otherwise the block is appended after
+ * the existing content (separated by a blank line). `existing` is `""` for a not-yet-created file.
+ * The result always ends with a single trailing newline. Pure.
+ */
+export declare function upsertBlock(existing: string, body: string): string;
+/**
+ * Remove the managed block from `existing`, preserving the rest (A4b uninstall). Returns the
+ * remaining content (trailing whitespace trimmed to a single newline), or `""` if nothing but the
+ * block (and whitespace) remains — the caller deletes the file in that case. Pure.
+ */
+export declare function removeBlock(existing: string): string;