@garygentry/feature-forge 0.1.5 → 0.2.1

package/dist/types.d.ts

@@ -32,19 +32,76 @@ export declare const EXIT: {
     readonly USAGE: 2;
 };
 export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
-/** Manifest schema version; bumped only on a breaking manifest-shape change. */
-export declare const SCHEMA_VERSION: 1;
+/**
+ * Manifest schema version. v2 (A4b) adds the optional `placements[]` array for agents whose
+ * install spans a second filesystem root (codex `.codex/agents`, copilot `.github/copilot-
+ * instructions.md`). A v1 manifest (no `placements`) is still read verbatim by the back-compat
+ * reader — bumped only on a breaking manifest-shape change.
+ */
+export declare const SCHEMA_VERSION: 2;
+/** Versions of the manifest this installer can READ (write is always SCHEMA_VERSION). */
+export declare const READABLE_SCHEMA_VERSIONS: readonly [1, 2];
+/** A manifest schemaVersion this installer accepts on read (back-compat v1 + current v2). */
+export type ReadableSchemaVersion = (typeof READABLE_SCHEMA_VERSIONS)[number];
 /** The single namespace directory name written inside each agent's install location [D5]. */
 export declare const FEATURE_FORGE_NS: "feature-forge";
 /** Filename prefix for the hidden parent-sibling manifest, completed by the scope (§3, spec 05). */
 export declare const MANIFEST_PREFIX: ".feature-forge.";
+/**
+ * How honestly an agent's install paths track current vendor docs (Finding 6 / A4).
+ * - "confirmed"        — source-verified end-to-end (claude).
+ * - "verified-current" — matches the vendor's current docs, re-verified in A0 (2026-06-26).
+ * - "best-known"       — plausible but not doc-confirmed for this scope; install proceeds,
+ *                        labeled honestly in the report so users know it may not be loaded.
+ * - "unsupported"      — no usable install surface; not installed (reserved; none today).
+ */
+export type Confidence = "confirmed" | "verified-current" | "best-known" | "unsupported";
+/** How an agent consumes the bundle (documentation + future per-kind apply behavior). */
+export type InstallKind = "skills" | "extension" | "rules" | "instructions";
+/**
+ * Kind of a SECONDARY install placement (A4b). The primary bundle (the `feature-forge/` namespace
+ * dir) is always present and is never a placement; placements describe extra writes under a
+ * DIFFERENT filesystem root than the primary bundle:
+ * - "mirror"        — copy a subset of bundle files flat into a second dir (codex `.codex/agents/`,
+ *                     where Codex loads custom agents — it does not read them from `.agents/skills`).
+ * - "managed-block" — write/merge a sentinel-delimited block into a (possibly user-owned) instructions
+ *                     file (copilot `.github/copilot-instructions.md`), preserving the rest of the file.
+ */
+export type PlacementKind = "mirror" | "managed-block";
+/** HTML-comment sentinels delimiting a `managed-block` placement (mirrors rauf's convention). */
+export declare const MANAGED_BLOCK_START: "<!-- feature-forge:managed:start -->";
+export declare const MANAGED_BLOCK_END: "<!-- feature-forge:managed:end -->";
+/**
+ * Declarative descriptor of one secondary placement on an {@link AgentTarget} (A4b). Pure data, so a
+ * new agent (or a new second-root rule) stays one table edit (REQ-SCALE-01). The absolute root and
+ * destination are derived under a scope by {@link resolvePlacements}; nothing here is stored.
+ */
+export interface PlacementSpec {
+    readonly kind: PlacementKind;
+    /** Second-root dir under the scope root, e.g. ".codex" (mirror) or ".github" (managed-block). */
+    readonly baseDir: string;
+    /**
+     * Path under `baseDir`. For "mirror" this is the destination DIR (e.g. "agents"); for
+     * "managed-block" this is the target FILE (e.g. "copilot-instructions.md").
+     */
+    readonly subpath: string;
+    /**
+     * "mirror" only: bundle-relative prefix selecting which source files to copy (e.g. "agents/").
+     * Files matching the prefix are copied FLAT (basename only) into the placement destination.
+     */
+    readonly sourcePrefix?: string;
+}
 /**
  * One row of the static per-agent detection map (REQ-DET-01, REQ-DET-05). Adding a new
  * agent is exactly adding one entry to `AGENT_TARGETS` — no logic change (REQ-SCALE-01).
  *
  * The on-disk destination for an agent under a given scope is derived, not stored:
- *   <scopeRoot>/<configDirName>/<installSubdir>/<FEATURE_FORGE_NS>/
- * where scopeRoot is the resolved home (global) or cwd (project).
+ *   <scopeRoot>/<installBaseDir>/<installSubpath>/<FEATURE_FORGE_NS>/
+ * where scopeRoot is the resolved home (global) or cwd (project), and `installSubpath` may
+ * be "" (installed directly under `installBaseDir`). Detection (`configDirName`) is decoupled
+ * from the install location because some agents load content from a different tree than the
+ * dir that signals their presence (A4): codex detects ".codex" but loads skills from
+ * ".agents/skills"; copilot detects ".copilot" but instructions live under ".github".
  */
 export interface AgentTarget {
     /** Stable agent identifier. */
@@ -55,22 +112,36 @@ export interface AgentTarget {
      */
     readonly configDirName: string;
     /**
-     * Sub-path under the config dir that holds the namespaced install dir, e.g.
-     * "skills" (claude/codex/copilot), "rules" (cursor), "extensions" (gemini).
+     * Top-level dir under the scope root that holds the install AND is the containment boundary
+     * every write is checked against (REQ-SEC-02). Usually equals `configDirName`; decoupled for
+     * codex (".agents") and copilot (".github").
+     */
+    readonly installBaseDir: string;
+    /**
+     * Path under `installBaseDir` to the namespace parent, e.g. "skills" (claude/codex),
+     * "rules" (cursor), "extensions" (gemini), "" (copilot — directly under `.github`).
      */
-    readonly installSubdir: string;
+    readonly installSubpath: string;
+    /** How this agent consumes the bundle (REQ-SCALE-01; per-kind placement extended in A4b). */
+    readonly installKind: InstallKind;
     /**
-     * Informational: the skill-file form this agent's bundle uses — "SKILL.md" (claude),
-     * "<name>.md" (codex/copilot/gemini), "<name>.mdc" (cursor). The installer copies the
+     * Informational: the skill-file form this agent's bundle uses — "SKILL.md" (claude, codex),
+     * "<name>.md" (copilot/gemini), "<name>.mdc" (cursor). The installer copies the
      * bundle verbatim (REQ-SCALE-02) and does not parse skill files, so this is documentation.
      */
     readonly skillFileForm: string;
+    /** Confidence for the default (global) scope. */
+    readonly confidence: Confidence;
+    /** Optional scope-specific override for project scope (e.g. gemini project = best-known). */
+    readonly projectConfidence?: Confidence;
+    /** Current vendor/docs URL for this target's install convention (surfaced in reports). */
+    readonly docsUrl: string;
     /**
-     * Confidence in this row's paths. "confirmed" = source-verified (claude). "best-known"
-     * = the TQ-1 paths (codex/copilot/cursor/gemini) to re-verify against each agent's current
-     * docs at implementation (REQ-SCALE-01 — isolated, localized correction).
+     * Secondary install placements under a DIFFERENT root than the primary bundle (A4b). Absent for
+     * agents whose whole install is the single namespace dir (claude/cursor/gemini). Declarative data
+     * only — resolved to absolute roots by {@link resolvePlacements}; a new rule is one table edit.
      */
-    readonly confidence: "confirmed" | "best-known";
+    readonly placements?: readonly PlacementSpec[];
 }
 /** Options for path resolution, injectable so tests never touch the real `~` (spec 02, spec 08). */
 export interface ResolveOpts {
@@ -95,6 +166,10 @@ export interface DetectionResult {
     readonly cliOnPath?: boolean;
     /** Resolved absolute install destination for the active scope (the `feature-forge/` namespace dir). */
     readonly destination: string;
+    /** Effective confidence for the active scope (REQ-DET-05; honest dry-run/list labeling, A4). */
+    readonly confidence: Confidence;
+    /** Current vendor/docs URL for this target (REQ-DET-05). */
+    readonly docsUrl: string;
 }
 /** One file recorded in the manifest inventory (REQ-SAFE-01). */
 export interface ManifestFile {
@@ -103,13 +178,30 @@ export interface ManifestFile {
     /** SHA-256 of the written bytes. Omitted for symlink mode (no per-file copy exists). */
     readonly sha256?: string;
 }
+/**
+ * One persisted SECONDARY placement (manifest v2, A4b). Records the absolute second root + dest and
+ * an inventory of what we wrote there, so `update`/`uninstall` reconcile it exactly like the primary
+ * bundle but under its own containment boundary (`root`). For "managed-block", `files` holds a single
+ * entry whose `path` is the file basename and whose `sha256` fingerprints the block region we wrote
+ * (drift/clean detection); the rest of that file is user-owned and never recorded.
+ */
+export interface Placement {
+    readonly kind: PlacementKind;
+    /** Absolute containment boundary every write for this placement is checked against (REQ-SEC-02). */
+    readonly root: string;
+    /** Absolute destination: a DIR ("mirror") or a FILE ("managed-block"). */
+    readonly destination: string;
+    /** Per-file inventory written under this placement (paths relative to `destination`'s dir). */
+    readonly files: ManifestFile[];
+}
 /**
  * The persisted per-install manifest (REQ-SAFE-01/03), written as the hidden parent-sibling
  * `<installSubdir>/.feature-forge.<scope>.json` (spec 05). It is the sole record `list`/`update`/
  * `uninstall` use to tell installer-written content from user content and to detect drift.
  */
 export interface InstallManifest {
-    readonly schemaVersion: typeof SCHEMA_VERSION;
+    /** Always {@link SCHEMA_VERSION} when written; v1 is still accepted on read (back-compat). */
+    readonly schemaVersion: ReadableSchemaVersion;
     readonly agent: AgentId;
     readonly scope: Scope;
     readonly mode: Mode;
@@ -124,7 +216,7 @@ export interface InstallManifest {
     readonly featureForgeVersion: string | null;
     /** SHA-256 over the source bundle's canonical (sorted-path) file set — drift anchor (OQ-4, spec 03). */
     readonly sourceHash: string;
-    /** Pinned rauf coordinate recorded at install, e.g. "@garygentry/rauf@0.8.0"; `null` if `--skip-rauf` (spec 06). */
+    /** Pinned rauf coordinate recorded at install, e.g. "@garygentry/rauf@0.8.1"; `null` if `--skip-rauf` (spec 06). */
     readonly raufPin: string | null;
     /** ISO-8601 timestamps. */
     readonly installedAt: string;
@@ -137,6 +229,11 @@ export interface InstallManifest {
     readonly link?: {
         readonly target: string;
     };
+    /**
+     * Secondary placements written under a different root than the primary bundle (manifest v2, A4b).
+     * Absent on agents without a second-root rule (claude/cursor/gemini) and on legacy v1 manifests.
+     */
+    readonly placements?: Placement[];
 }
 /**
  * The per-file action the planner assigns by diffing source ⇆ destination ⇆ manifest (spec 04).
@@ -165,6 +262,36 @@ export interface PlannedAction {
     readonly files: FileAction[];
     /** Surfaced in the plan/report for visibility (spec 06); not a file action. */
     readonly raufPin?: string | null;
+    /**
+     * Resolved secondary-placement plans (A4b). Each carries its own absolute root + destination, the
+     * per-file diff actions, and (for "managed-block") the exact block content a real run will write —
+     * so dry-run shows, and `apply` performs, identical work. Absent when the agent has no placements.
+     */
+    readonly placements?: PlannedPlacement[];
+}
+/**
+ * One secondary placement's resolved plan (A4b): the dry-run = real-run unit for a second root. The
+ * planner fills `files` by diffing source ⇆ destination (same classifier as the primary bundle) and,
+ * for "managed-block", attaches the rendered `blockContent` the apply step writes between sentinels.
+ */
+export interface PlannedPlacement {
+    readonly kind: PlacementKind;
+    /** Absolute containment boundary (REQ-SEC-02). */
+    readonly root: string;
+    /** Absolute destination dir ("mirror") or file ("managed-block"). */
+    readonly destination: string;
+    /**
+     * Per-file diff actions. "mirror" entries carry `srcRelpath` (the bundle-relative source to copy);
+     * "managed-block" has a single entry whose `relpath` is the file basename (no `srcRelpath`).
+     */
+    readonly files: PlacementFileAction[];
+    /** "managed-block" only: the rendered block body (without sentinels) a create/overwrite writes. */
+    readonly blockContent?: string;
+}
+/** A placement file action: a {@link FileAction} plus the bundle-relative source for "mirror" copies. */
+export interface PlacementFileAction extends FileAction {
+    /** "mirror" only: bundle-relative source path to copy into `<destination>/<relpath>`. */
+    readonly srcRelpath?: string;
 }
 /** One agent's outcome in a run summary (REQ-OBS-01/03). */
 export interface AgentReport {
@@ -177,6 +304,10 @@ export interface AgentReport {
     /** Present iff `ok` is false. */
     readonly error?: InstallerError;
     readonly raufPin?: string | null;
+    /** Effective install-path confidence for the active scope (A4; honest report labeling). */
+    readonly confidence?: Confidence;
+    /** Vendor/docs URL for this target (A4; shown when confidence is not full). */
+    readonly docsUrl?: string;
 }
 /** The whole-run summary, rendered human-readable or as `--json` (REQ-OBS-01, REQ-DET-05). */
 export interface RunReport {
@@ -205,17 +336,30 @@ export interface RunReport {
  *
  * Verified ground truth: every bundle has `skills/` (11 skills), `references/`,
  * `scripts/forge-root.sh`, `agents/`; gemini adds a root `gemini-extension.json`,
- * codex adds `agents/openai.yaml`, cursor uses `.mdc` files.
+ * codex ships `skills/<name>/SKILL.md` + standalone `agents/<name>.toml` custom agents,
+ * cursor uses `.mdc` files.
+ *
+ * A4 per-agent reality check (A0 re-verified vendor docs, 2026-06-26):
+ *  - codex   — detects `.codex`, loads skills from `.agents/skills` (verified-current).
+ *              The `.codex/agents/*.toml` second placement is added in A4b.
+ *  - copilot — detects `.copilot`, but has no skills loader; the bundle is staged under
+ *              `.github/feature-forge` and the managed instructions block (.github/
+ *              copilot-instructions.md) is added in A4b (best-known).
+ *  - cursor  — `.cursor/rules/*.mdc` confirmed current (verified-current).
+ *  - gemini  — `~/.gemini/extensions/feature-forge` global confirmed; project scope is
+ *              best-known (project extension install is not clearly documented).
  */
 export declare const AGENT_TARGETS: Readonly<Record<AgentId, AgentTarget>>;
 /**
  * Minimal integrity check (REQ-OPS-06, spec 03): a located bundle is valid iff `skills/` is a
- * non-empty dir, `scripts/forge-root.sh` exists, and — for gemini only — `gemini-extension.json`
- * exists at the bundle root. Defined here as data so the check is a localized table read.
+ * non-empty dir, the neutral bundle sentinel `.feature-forge-bundle.json` exists, every runtime
+ * helper script a skill can invoke is present (so helper-backed skills run after install on ANY
+ * agent), and — for gemini only — `gemini-extension.json` exists at the bundle root. Defined here
+ * as data so the check is a localized table read.
  */
 export declare const BUNDLE_REQUIRED_PATHS: {
     /** Required of every agent bundle. */
-    readonly common: readonly ["skills", "scripts/forge-root.sh"];
+    readonly common: readonly ["skills", ".feature-forge-bundle.json", "scripts/forge-root.sh", "scripts/forge-init.sh", "scripts/epic-manifest.py", "scripts/validate-traceability.py", "scripts/forge-bootstrap.py"];
     /** Additional per-agent requirements. */
     readonly perAgent: Partial<Record<AgentId, readonly string[]>>;
 };

package/dist/types.js

@@ -15,12 +15,22 @@
 export const AGENT_IDS = ["claude", "codex", "copilot", "cursor", "gemini"];
 /** Process exit codes (REQ-OBS-01/03, spec 07). */
 export const EXIT = { SUCCESS: 0, FAILURE: 1, USAGE: 2 };
-/** Manifest schema version; bumped only on a breaking manifest-shape change. */
-export const SCHEMA_VERSION = 1;
+/**
+ * Manifest schema version. v2 (A4b) adds the optional `placements[]` array for agents whose
+ * install spans a second filesystem root (codex `.codex/agents`, copilot `.github/copilot-
+ * instructions.md`). A v1 manifest (no `placements`) is still read verbatim by the back-compat
+ * reader — bumped only on a breaking manifest-shape change.
+ */
+export const SCHEMA_VERSION = 2;
+/** Versions of the manifest this installer can READ (write is always SCHEMA_VERSION). */
+export const READABLE_SCHEMA_VERSIONS = [1, 2];
 /** The single namespace directory name written inside each agent's install location [D5]. */
 export const FEATURE_FORGE_NS = "feature-forge";
 /** Filename prefix for the hidden parent-sibling manifest, completed by the scope (§3, spec 05). */
 export const MANIFEST_PREFIX = ".feature-forge.";
+/** HTML-comment sentinels delimiting a `managed-block` placement (mirrors rauf's convention). */
+export const MANAGED_BLOCK_START = "<!-- feature-forge:managed:start -->";
+export const MANAGED_BLOCK_END = "<!-- feature-forge:managed:end -->";
 // ---------------------------------------------------------------------------
 // 6. Constants — the `AGENT_TARGETS` table
 // ---------------------------------------------------------------------------
@@ -31,23 +41,44 @@ export const MANIFEST_PREFIX = ".feature-forge.";
  *
  * Verified ground truth: every bundle has `skills/` (11 skills), `references/`,
  * `scripts/forge-root.sh`, `agents/`; gemini adds a root `gemini-extension.json`,
- * codex adds `agents/openai.yaml`, cursor uses `.mdc` files.
+ * codex ships `skills/<name>/SKILL.md` + standalone `agents/<name>.toml` custom agents,
+ * cursor uses `.mdc` files.
+ *
+ * A4 per-agent reality check (A0 re-verified vendor docs, 2026-06-26):
+ *  - codex   — detects `.codex`, loads skills from `.agents/skills` (verified-current).
+ *              The `.codex/agents/*.toml` second placement is added in A4b.
+ *  - copilot — detects `.copilot`, but has no skills loader; the bundle is staged under
+ *              `.github/feature-forge` and the managed instructions block (.github/
+ *              copilot-instructions.md) is added in A4b (best-known).
+ *  - cursor  — `.cursor/rules/*.mdc` confirmed current (verified-current).
+ *  - gemini  — `~/.gemini/extensions/feature-forge` global confirmed; project scope is
+ *              best-known (project extension install is not clearly documented).
  */
 export const AGENT_TARGETS = {
-    claude: { id: "claude", configDirName: ".claude", installSubdir: "skills", skillFileForm: "SKILL.md", confidence: "confirmed" },
-    codex: { id: "codex", configDirName: ".codex", installSubdir: "skills", skillFileForm: "<name>.md", confidence: "best-known" },
-    copilot: { id: "copilot", configDirName: ".copilot", installSubdir: "skills", skillFileForm: "<name>.md", confidence: "best-known" },
-    cursor: { id: "cursor", configDirName: ".cursor", installSubdir: "rules", skillFileForm: "<name>.mdc", confidence: "best-known" },
-    gemini: { id: "gemini", configDirName: ".gemini", installSubdir: "extensions", skillFileForm: "<name>.md", confidence: "best-known" },
+    claude: { id: "claude", configDirName: ".claude", installBaseDir: ".claude", installSubpath: "skills", installKind: "skills", skillFileForm: "SKILL.md", confidence: "confirmed", docsUrl: "https://docs.claude.com/en/docs/claude-code/skills" },
+    codex: { id: "codex", configDirName: ".codex", installBaseDir: ".agents", installSubpath: "skills", installKind: "skills", skillFileForm: "SKILL.md", confidence: "verified-current", docsUrl: "https://developers.openai.com/codex/skills", placements: [{ kind: "mirror", baseDir: ".codex", subpath: "agents", sourcePrefix: "agents/" }] },
+    copilot: { id: "copilot", configDirName: ".copilot", installBaseDir: ".github", installSubpath: "", installKind: "instructions", skillFileForm: "<name>.md", confidence: "best-known", docsUrl: "https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions", placements: [{ kind: "managed-block", baseDir: ".github", subpath: "copilot-instructions.md" }] },
+    cursor: { id: "cursor", configDirName: ".cursor", installBaseDir: ".cursor", installSubpath: "rules", installKind: "rules", skillFileForm: "<name>.mdc", confidence: "verified-current", docsUrl: "https://cursor.com/docs/context/rules" },
+    gemini: { id: "gemini", configDirName: ".gemini", installBaseDir: ".gemini", installSubpath: "extensions", installKind: "extension", skillFileForm: "<name>.md", confidence: "verified-current", projectConfidence: "best-known", docsUrl: "https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/index.md" },
 };
 /**
  * Minimal integrity check (REQ-OPS-06, spec 03): a located bundle is valid iff `skills/` is a
- * non-empty dir, `scripts/forge-root.sh` exists, and — for gemini only — `gemini-extension.json`
- * exists at the bundle root. Defined here as data so the check is a localized table read.
+ * non-empty dir, the neutral bundle sentinel `.feature-forge-bundle.json` exists, every runtime
+ * helper script a skill can invoke is present (so helper-backed skills run after install on ANY
+ * agent), and — for gemini only — `gemini-extension.json` exists at the bundle root. Defined here
+ * as data so the check is a localized table read.
  */
 export const BUNDLE_REQUIRED_PATHS = {
     /** Required of every agent bundle. */
-    common: ["skills", "scripts/forge-root.sh"],
+    common: [
+        "skills",
+        ".feature-forge-bundle.json",
+        "scripts/forge-root.sh",
+        "scripts/forge-init.sh",
+        "scripts/epic-manifest.py",
+        "scripts/validate-traceability.py",
+        "scripts/forge-bootstrap.py",
+    ],
     /** Additional per-agent requirements. */
     perAgent: { gemini: ["gemini-extension.json"] },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garygentry/feature-forge",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Cross-agent installer for the feature-forge skill suite — installs the canonical forge pipeline into Claude, Codex, Copilot, Cursor, or Gemini.",
   "license": "MIT",
   "type": "module",

package/adapters/codex/agents/openai.yaml

@@ -1,10 +0,0 @@
-_generated:
-  source: agents/
-  regenerate: python3 scripts/build-adapters.py
-agents:
-- name: forge-researcher
-  description: Explores the codebase to understand package structure, integration points, existing patterns, and conventions. Use during feature planning, especially when running /feature-forge:forge-2-tech. Returns a distilled integration report without polluting the main conversation's context window.
-- name: forge-spec-writer
-  description: Authors exactly one numbered implementation spec document for a forge feature, to the quality bar in forge-3-specs. Dispatched by forge-3-specs as one of several parallel writers, after the shared foundation docs (00-core-definitions, 01-architecture-layout) are already written. Writes only its single assigned file and returns a requirement-coverage manifest.
-- name: forge-verifier
-  description: Verifies feature forge pipeline artifacts for completeness, consistency, and quality. Delegates to this agent when running /feature-forge:forge-verify or when the user asks to check specs, backlog, or implementation for gaps. This agent has read-only tools and persistent memory — it cannot modify files, only analyze and report findings.