@garygentry/feature-forge 0.1.5 → 0.2.1

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.8.0"); `null` when `--skip-rauf` (spec 06). */
+    /** Recorded pinned rauf coordinate (e.g. "@garygentry/rauf@0.8.1"); `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;

package/dist/placements.js

@@ -0,0 +1,116 @@
+/**
+ * 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 * as path from "node:path";
+import { MANAGED_BLOCK_END, MANAGED_BLOCK_START, } from "./types.js";
+import { resolveRoots } from "./agent-targets.js";
+/**
+ * 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 function resolvePlacements(target, scope, opts) {
+    const roots = resolveRoots(opts);
+    const scopeRoot = scope === "global" ? roots.home : roots.cwd;
+    return (target.placements ?? []).map((spec) => {
+        const root = path.resolve(scopeRoot, spec.baseDir);
+        return { kind: spec.kind, root, destination: path.resolve(root, spec.subpath), spec };
+    });
+}
+/**
+ * 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 function selectMirrorFiles(source, spec) {
+    const prefix = spec.sourcePrefix ?? "";
+    return source.files
+        .filter((f) => f.relpath.startsWith(prefix))
+        .map((f) => ({ srcRelpath: f.relpath, destRelpath: path.posix.basename(f.relpath), srcHash: f.sha256 }))
+        .sort((a, b) => (a.destRelpath < b.destRelpath ? -1 : a.destRelpath > b.destRelpath ? 1 : 0));
+}
+// ---------------------------------------------------------------------------
+// Managed-block string transforms (pure)
+// ---------------------------------------------------------------------------
+/**
+ * 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 function renderCopilotBlock(skills) {
+    const lines = [
+        "# feature-forge",
+        "",
+        "The feature-forge skill suite is installed in this repository under",
+        "`.github/feature-forge/`. GitHub Copilot has no skills loader, so consult those files",
+        "directly when a feature-forge workflow is requested.",
+        "",
+        "Each skill lives at `.github/feature-forge/skills/<name>/SKILL.md`. Available skills:",
+        "",
+        ...[...skills].sort().map((s) => `- ${s}`),
+        "",
+        "Shared references are under `.github/feature-forge/references/`; helper scripts under",
+        "`.github/feature-forge/scripts/`.",
+    ];
+    return lines.join("\n");
+}
+/** Wrap a rendered block body in the managed sentinels — the exact region written on disk. */
+export function wrapBlock(body) {
+    return `${MANAGED_BLOCK_START}\n${body}\n${MANAGED_BLOCK_END}`;
+}
+/**
+ * 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 function extractManagedRegion(content) {
+    const startIdx = content.indexOf(MANAGED_BLOCK_START);
+    if (startIdx === -1)
+        return null;
+    const endIdx = content.indexOf(MANAGED_BLOCK_END, startIdx + MANAGED_BLOCK_START.length);
+    if (endIdx === -1)
+        return null;
+    return content.slice(startIdx, endIdx + MANAGED_BLOCK_END.length);
+}
+/**
+ * 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 function upsertBlock(existing, body) {
+    const region = wrapBlock(body);
+    const current = extractManagedRegion(existing);
+    if (current !== null) {
+        return ensureTrailingNewline(existing.replace(current, region));
+    }
+    if (existing.trim() === "")
+        return ensureTrailingNewline(region);
+    return ensureTrailingNewline(`${existing.replace(/\n+$/, "")}\n\n${region}`);
+}
+/**
+ * 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 function removeBlock(existing) {
+    const region = extractManagedRegion(existing);
+    if (region === null)
+        return existing;
+    const without = existing.replace(region, "").replace(/\n{3,}/g, "\n\n").trim();
+    return without === "" ? "" : `${without}\n`;
+}
+/** Ensure exactly one trailing newline. */
+function ensureTrailingNewline(s) {
+    return `${s.replace(/\n+$/, "")}\n`;
+}

package/dist/plan.d.ts

@@ -9,6 +9,7 @@
  */
 import type { AgentId, FileActionKind, Mode, PlannedAction, Result, Scope, InstallManifest } from "./types.js";
 import { type LocatedSource } from "./source.js";
+import { type ResolvedPlacement } from "./placements.js";
 /**
  * Everything the pure planner needs to diff source ⇆ destination ⇆ manifest for ONE agent
  * (spec 04 §4). Built by cli.ts (07); the planner reads these and writes nothing.
@@ -30,6 +31,12 @@ export interface PlanContext {
     readonly force: boolean;
     /** The pinned rauf coordinate to surface on the plan (06); the planner only echoes it. */
     readonly raufPin?: string | null;
+    /**
+     * Resolved secondary placements for this agent (A4b), or absent/empty when it has none. Supplied by
+     * cli.ts (which holds the scope roots); the planner diffs each against its destination and the prior
+     * manifest's matching placement inventory.
+     */
+    readonly placements?: ResolvedPlacement[];
 }
 /**
  * Classify one bundle-relative path (spec 04 §6 table). PURE: hashes are read, nothing is written.

package/dist/plan.js

@@ -10,7 +10,8 @@
 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 { selectMirrorFiles, renderCopilotBlock, wrapBlock, extractManagedRegion, } from "./placements.js";
 import { planUninstall } from "./manifest.js";
 import { isWindows } from "./fsutil.js";
 /**
@@ -98,15 +99,100 @@ function buildPlan(ctx, withOrphans) {
     const files = ctx.mode === "symlink"
         ? planSymlink(ctx)
         : planCopy(ctx, withOrphans);
+    // Secondary placements (A4b) are always copy-style regardless of the primary mode: a mirror is a
+    // few flat files and a managed-block is a merge, neither of which a whole-dir symlink expresses.
+    const placements = planPlacements(ctx, withOrphans);
     const action = {
         agent: ctx.agent,
         scope: ctx.scope,
         mode: ctx.mode,
         files,
         ...(ctx.raufPin !== undefined ? { raufPin: ctx.raufPin } : {}),
+        ...(placements.length > 0 ? { placements } : {}),
     };
     return ok(action);
 }
+// ---------------------------------------------------------------------------
+// Secondary placements (A4b)
+// ---------------------------------------------------------------------------
+/** Plan every resolved secondary placement (A4b). `ctx.source` is non-null here. */
+function planPlacements(ctx, withOrphans) {
+    const resolved = ctx.placements ?? [];
+    if (resolved.length === 0)
+        return [];
+    const source = ctx.source;
+    const priorByDest = priorPlacementIndex(ctx.priorManifest);
+    return resolved.map((rp) => rp.kind === "mirror"
+        ? planMirror(ctx, rp, source, priorByDest.get(rp.destination) ?? null, withOrphans)
+        : planManagedBlock(ctx, rp, source, priorByDest.get(rp.destination) ?? null));
+}
+/** Index prior-manifest placements by their absolute destination, for clean/orphan reconciliation. */
+function priorPlacementIndex(prior) {
+    const m = new Map();
+    for (const p of prior?.placements ?? [])
+        m.set(p.destination, p);
+    return m;
+}
+/** Diff a "mirror" placement: each selected bundle file vs its flat destination + recorded hash. */
+function planMirror(ctx, rp, source, prior, withOrphans) {
+    const recorded = new Map();
+    for (const f of prior?.files ?? [])
+        recorded.set(f.path, f);
+    const mirror = selectMirrorFiles(source, rp.spec);
+    const files = mirror.map((mf) => {
+        const destAbs = path.join(rp.destination, mf.destRelpath);
+        const destHash = hashIfExists(destAbs);
+        const manifestHash = recorded.get(mf.destRelpath)?.sha256;
+        const action = classifyFile(mf.destRelpath, mf.srcHash, destHash, manifestHash, ctx.force);
+        return { relpath: mf.destRelpath, action, srcRelpath: mf.srcRelpath };
+    });
+    if (withOrphans && prior !== null) {
+        const live = new Set(mirror.map((mf) => mf.destRelpath));
+        for (const f of prior.files) {
+            if (!live.has(f.path))
+                files.push({ relpath: f.path, action: "remove" });
+        }
+    }
+    return { kind: "mirror", root: rp.root, destination: rp.destination, files };
+}
+/** Diff a "managed-block" placement: render the block, compare its region to the on-disk region. */
+function planManagedBlock(ctx, rp, source, prior) {
+    const blockContent = renderCopilotBlock(source.skills);
+    const newHash = sha256String(wrapBlock(blockContent));
+    const basename = path.basename(rp.destination);
+    const current = readManagedRegionHash(rp.destination);
+    const recordedHash = prior?.files.find((f) => f.path === basename)?.sha256;
+    let action;
+    if (current === undefined) {
+        action = "create"; // no managed region present yet
+    }
+    else if (current === newHash) {
+        action = "unchanged";
+    }
+    else {
+        const clean = recordedHash !== undefined && current === recordedHash;
+        action = clean ? "overwrite" : ctx.force ? "overwrite" : "skip-modified";
+    }
+    return {
+        kind: "managed-block",
+        root: rp.root,
+        destination: rp.destination,
+        files: [{ relpath: basename, action }],
+        blockContent,
+    };
+}
+/** Hash of the managed region currently in the target file, or undefined if absent/unreadable. */
+function readManagedRegionHash(file) {
+    let content;
+    try {
+        content = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const region = extractManagedRegion(content);
+    return region === null ? undefined : sha256String(region);
+}
 /** Copy-mode per-file diff (spec 04 §6). `ctx.source` is non-null here. */
 function planCopy(ctx, withOrphans) {
     const source = ctx.source;

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.8.0.
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.8.1.
  *
- * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.8.0` resolves from the npm registry, so the
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.8.1` 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.8.0";
+export declare const RAUF_PIN = "@garygentry/rauf@0.8.1";
 /**
  * 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.8.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.8.0"
+ * @param coordinate - the `name@version` to resolve, e.g. "@garygentry/rauf@0.8.1"
  * @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.8.0.
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.8.1.
  *
- * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.8.0` resolves from the npm registry, so the
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.8.1` 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.8.0";
+export const RAUF_PIN = "@garygentry/rauf@0.8.1";
 /**
  * Resolvability preflight for the pinned default loop runner (D1; REQ-RAUF-01/02/03, OQ-1).
  *

package/dist/report.js

@@ -47,6 +47,9 @@ function renderAgent(subcommand, a) {
         // Decode the synthetic status rows (§3.3) into one human line.
         const status = a.actions.map((f) => f.relpath).join("  ");
         lines.push(`${a.agent}: ${a.detected ? "detected" : "not detected"}  ${status}`);
+        const note = confidenceNote(a);
+        if (note)
+            lines.push(`  ${note}`);
         return lines;
     }
     if (!a.ok && a.error) {
@@ -58,10 +61,28 @@ function renderAgent(subcommand, a) {
     for (const f of a.actions) {
         lines.push(`  ${actionVerb(f.action)} ${f.relpath}`);
     }
+    const note = confidenceNote(a);
+    if (note)
+        lines.push(`  ${note}`);
     if (a.raufPin)
         lines.push(`  rauf default runner pinned: ${a.raufPin}`);
     return lines;
 }
+/**
+ * Honest per-agent confidence note (A4 / Finding 6): silent for fully-trusted targets
+ * (`confirmed`/`verified-current`), explicit for `best-known`/`unsupported` so a user knows
+ * an install path may not be auto-loaded by that agent and where to check current docs. Pure.
+ */
+function confidenceNote(a) {
+    if (!a.confidence || a.confidence === "confirmed" || a.confidence === "verified-current") {
+        return null;
+    }
+    const where = a.docsUrl ? ` — see ${a.docsUrl}` : "";
+    if (a.confidence === "unsupported") {
+        return `note: ${a.agent} has no confirmed install surface (unsupported)${where}`;
+    }
+    return `note: ${a.agent} install path is best-known, not vendor-confirmed${where}`;
+}
 /** Map a FileActionKind to its human verb (REQ-OBS-01 vocabulary). */
 export function actionVerb(kind) {
     switch (kind) {

package/dist/source.d.ts

@@ -44,9 +44,10 @@ export interface LocatedSource {
 export declare function locateBundle(agent: AgentId, opts?: LocateBundleOpts): Result<string>;
 /**
  * Minimal integrity check for a located bundle (REQ-OPS-06). Valid iff the `BUNDLE_REQUIRED_PATHS`
- * are present: `skills/` is a non-empty dir, `scripts/forge-root.sh` exists, and (gemini)
- * `gemini-extension.json` exists. Does NOT require `.claude-plugin/plugin.json` or
- * `epic-manifest.py` (IR-1 / OQ-A).
+ * are present: `skills/` is a non-empty dir, the neutral `.feature-forge-bundle.json` sentinel and
+ * every bundled runtime helper (`forge-root.sh`, `forge-init.sh`, `epic-manifest.py`,
+ * `validate-traceability.py`, `forge-bootstrap.py`) exist, and (gemini) `gemini-extension.json`
+ * exists. Keys on the neutral sentinel, NOT the Claude-only `.claude-plugin/plugin.json`.
  *
  * @returns ok(undefined) when every required path is present; err(SOURCE_INVALID) naming the
  *          first missing/invalid required path otherwise.

package/dist/source.js

@@ -38,9 +38,10 @@ export function locateBundle(agent, opts = {}) {
 }
 /**
  * Minimal integrity check for a located bundle (REQ-OPS-06). Valid iff the `BUNDLE_REQUIRED_PATHS`
- * are present: `skills/` is a non-empty dir, `scripts/forge-root.sh` exists, and (gemini)
- * `gemini-extension.json` exists. Does NOT require `.claude-plugin/plugin.json` or
- * `epic-manifest.py` (IR-1 / OQ-A).
+ * are present: `skills/` is a non-empty dir, the neutral `.feature-forge-bundle.json` sentinel and
+ * every bundled runtime helper (`forge-root.sh`, `forge-init.sh`, `epic-manifest.py`,
+ * `validate-traceability.py`, `forge-bootstrap.py`) exist, and (gemini) `gemini-extension.json`
+ * exists. Keys on the neutral sentinel, NOT the Claude-only `.claude-plugin/plugin.json`.
  *
  * @returns ok(undefined) when every required path is present; err(SOURCE_INVALID) naming the
  *          first missing/invalid required path otherwise.