@warpgogol/forge 4.0.0 → 4.1.2

package/AGENTS.md

@@ -27,13 +27,22 @@ Packet 000 will add the portable `forge/program@1` control plane under `os/progr
 | `forgeAdrModule` | `adr.list`, `adr.create`, `adr.validate`, `adr.archive`, `adr.implement.stamp` | `os/adr/` |
 | `forgePlanModule` | `plan.archive` | `os/plan/` |
 | `forgeAuditModule` | `audit.archive` | `os/audit/` |
-| `forgeSessionModule` | `session.save`, `session.archive`, `session.validate`, `session.list` | `os/session/` |
+| `forgeSessionModule` | `session.save`, `session.archive`, `session.validate`, `session.list`, `metrics.aggregate` | `os/session/` |
 | `forgeMissionModule` | `mission.archive` | `os/mission/` |
 | `forgeExplorationModule` | `exploration.list`, `exploration.show`, `exploration.archive` | `os/exploration/` |
 | `forgeNotesModule` | `note.link.validate`, `note.frontmatter.validate`, `note.orphan.detect` | `os/notes/` |
 | `forgeProgramModule` | `program.packet.validate`, `program.packet.seal`, `program.packet.lease`, `program.packet.complete` | `os/program/` |
 | `forgePluginModule` | `forge.plugin.validate`, `forge.plugin.discover` | `os/plugin/` |
 
+## RFC-1053: Skill effectiveness metrics
+
+`metrics.aggregate` (RFC-1053) queries and aggregates per-skill effectiveness metrics from `docs/metrics/` YAML files. Metrics are generated at two integration points:
+
+- `rfc.implement.stamp` — generates `docs/metrics/rfcs/<rfc-id>.metrics.yaml` after successful stamp (non-fatal on failure).
+- `session.save` — generates `docs/metrics/sessions/<session-id>.metrics.yaml` from parsed ATIF messages (non-fatal on failure).
+
+Both generators are best-effort: metrics failures log a warning and never block the primary operation. Agents MUST NOT manually edit `docs/metrics/` files — they are generated artifacts produced by `rfc.implement.stamp` and `session.save`.
+
 ## Compass contract extension points (RFC-0943)
 
 Skill packs MAY declare additional Compass contract blocks beyond the built-in `MODULE_CONTRACT` and `CHANGE_SUMMARY` via `forge.plugin.yaml` `extensionPoints.compass.contract.blocks[]`. Each block spec is declarative data:
@@ -50,6 +59,8 @@ Skill packs MAY declare additional Compass contract blocks beyond the built-in `
 - **Wrap `loadForgeConfig` in try/catch in handlers that run in test workspaces.** `loadForgeConfig` throws when `forge.yaml` does not exist at the workspace root. Handlers that may be called from test workspaces without a `forge.yaml` (e.g. `runCompassValidation`) must guard the call with try/catch and skip pack-dependent logic when config is unavailable.
 - **Register new top-level directories in `NAMING_CONVENTION_IGNORED_TOP_LEVEL`.** When a new top-level directory appears in the repo (e.g. `.adr-locks`, `.devin`, `.forge`, `.rfc-locks`, `patches`, `storage`), add it to `NAMING_CONVENTION_IGNORED_TOP_LEVEL` in `os/naming/naming-convention.ts`. Otherwise `naming.convention.lint` reports "unknown top-level directory" errors.
 - **Add tool-generated/imported/historical dirs to `NAMING_CONVENTION_EXEMPT_DIRS`.** Directories containing tool-generated files (e.g. `docs/performance` with timestamp-based names), imported specification documents (e.g. `docs/specs` with `01-PBP-System-Specification.md`), and archived RFCs (e.g. `docs/rfcs/archive`) should be added to `NAMING_CONVENTION_EXEMPT_DIRS` in `os/naming/naming-convention.ts` to avoid false-positive kebab-case violations on files whose naming is controlled by external tools or conventions.
+- **Use `%s` not `%B` for git log delimiter parsing.** When parsing `git log --format` output with `\x1f`-delimited fields, use `%s` (subject only) instead of `%B` (full body). `%B` includes newlines which break the per-line `split("\x1f")` parsing, causing all entries to be silently skipped. Discovered during RFC-1053 `metrics-rfc.ts` implementation.
+- **Chicken-and-egg with self-referential acceptance probes.** When an RFC's acceptance probe checks for a file that is created by `rfc.implement.stamp` itself (e.g. `docs/metrics/rfcs/<rfc-id>.metrics.yaml`), `rfc.verification.emit` will always report "fail" before stamping because the file doesn't exist yet. Solution: generate the file manually first (e.g. via a node script calling the generator function), re-emit evidence, then stamp. The stamp's `RFC-IMP-06` check requires evidence to be "pass" before proceeding. Discovered during RFC-1053 stamping.
 
 ## Program packet control plane (RFC-0856)
 
@@ -68,6 +79,8 @@ When archiving terminal artifacts, prefer the `docs.archive` umbrella command ov
 
 - **RFC-0711: `docs.archive` post-loop `spec.live.merge` step.** After archiving, `docs.archive` scans implemented RFCs with a `liveSpec` frontmatter field and calls `spec.live.merge` for each, creating or updating living feature specs under `docs/specs/live/<domain>.md`. Rejected RFCs with `liveSpec` are skipped. Merge failures are non-fatal — the archive step still completes. Use `--dry-run` to preview merges without writing.
 
+- **`rfc.validate --root <file>` does NOT scope validation to a single file.** It validates ALL RFCs in the repo regardless of the `--root` flag. To check specific RFCs, use `--json` with `2>/dev/null` (log lines go to stderr) and filter the `data.violations[]` array by `rfcId`. Discovered during RFC-1035–1038 gap analysis.
+- **`rfc.archive` does NOT accept `--id`.** It archives ALL terminal-status RFCs at once. Available flags: `--dry-run` (preview), `--status <status>` (filter by status). Use `--dry-run` first to verify which files will move. Discovered during RFC-1038 archiving.
 - **Post-rename cleanup for `fs.rename` on watched directories:** When an archive handler uses `fs.rename` to move a directory that an IDE or file watcher is tracking (e.g. mission workpiece with an open `.astro/` cache), the watcher may recreate stale cache at the source path after the rename completes. Always add a post-rename cleanup check using `trashPath` from `utils/fs-trash.ts`: `if (existsSync(sourcePath)) { await trashPath(sourcePath); }` after the `fs.rename` call. See `os/mission/handlers/archive.ts` `moveMissionDir` for the reference implementation.
 
 ## Pinned-files protection (RFC-0733)
@@ -86,11 +99,12 @@ The pinned-files protection system prevents accidental deletion, move, or modifi
 All Forge stack profiles include portable agent-safety scripts as embedded file content blocks. These scripts protect AI agents from destructive git operations and enforce session-end protocol.
 
 - **`scripts/git-guard.sh`** — shell function intercepting `git stash`, `git reset --hard`, `git checkout --`, `git checkout -f`, `git switch -f`, `git clean -f`, `git restore`. Override: `ALLOW_DESTRUCTIVE_GIT=1`. Uses `FORGE_GIT_GUARD` marker (not `WERKSTATT_GIT_GUARD`).
-- **`scripts/setup-git-guards.sh`** — installs git-guard.sh into `~/.zshenv`. Supports `install`, `--verify`, `--remove` modes.
+- **`scripts/setup-git-guards.sh`** — auto-detects shell (zsh → `~/.zshenv`, bash → `~/.bashrc`) and installs git-guard.sh source line. Supports `install`, `--verify`, `--remove` modes.
 - **`scripts/clean-stale-stashes.sh`** — detects and optionally drops stale git stash entries. Report mode (`--drop` to clean, `--drop-all` for all).
 - **`scripts/check-clean-trees.sh`** — universal dirty-tree checker. Finds all `.git` directories up to 3 levels deep and checks each for dirty state.
 - **`hooks/pre-user-prompt.sh`** — session-end protocol enforcement + stale-stash detection + git-guard verification. Requires `jq`. Exits with code 2 on session-end trigger phrases to inject protocol instructions.
-- **`.windsurf/hooks.json`** — Windsurf hook registration for `pre_user_prompt`.
+- **`hooks/pre-user-prompt-wrapper.mjs`** — Node.js cross-platform wrapper called by `.windsurf/hooks.json`. Detects bash availability, prints one-time warning if bash not found (Windows without Git Bash), then delegates to `hooks/pre-user-prompt.sh`.
+- **`.windsurf/hooks.json`** — Windsurf hook registration for `pre_user_prompt`, calls `node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs`.
 - **PREFERENCES.md** generated by `forge init` includes `formOfAddress` field and operational rules: plan confirmation vs implementation, skill invocation tracking, commit granularity, session-end protocol.
 
 ## Skills
@@ -174,6 +188,7 @@ RFC-0997 binds acceptance probes to criteria via the `criterion: "AC-N"` field a
 - **V-37**: checked criteria evidence SHALL resolve — `probe:AC-N` must reference a criterion with at least one bound probe; `test:<path>` and `<path>:<line>` must reference an existing file. **Evidence annotations MUST NOT contain em-dashes (—) or nested quotes** — the V-37 parser breaks on `test: path — "description"` and reports the file as non-existent. **The `<path>` token MUST be the file path only — no AC-N suffixes, no descriptions, no extra text after the path.** The parser treats everything after `test:` until end-of-parenthesis as the file path; `test: packages/forge/os/rfc/file.test.ts AC-1` is reported as non-existent because the parser looks for a file named `packages/forge/os/rfc/file.test.ts AC-1`. Use simple `(evidence: test:packages/forge/src/tests/file.test.ts)` without em-dashes, nested quotes, or AC-N suffixes. Discovered during RFC-0998 and RFC-0999.
 - **RFC-IMP-08**: `rfc.implement.stamp` blocks stamping for post-cutoff RFCs of kind `architecture`, `contract`, or `command` that declare zero acceptance probes. Policy and deprecation kinds are exempt.
 - **Coverage report**: `rfc.validate --json` and `rfc.acceptance.run` emit a non-blocking `coverage` block per post-cutoff RFC with `totalCriteria`, `probeBackedCriteria`, `coverageRatio`, `uncoveredCriteria`, `unboundProbes`.
+- **`file-contains` probe `pattern` is RegExp, not literal.** The `file-contains` acceptance probe compiles its `pattern` field via `new RegExp(pattern, "m")`. Parentheses, brackets, dots, and other regex metacharacters MUST be escaped (e.g. `\\(RFC-1023\\)` not `(RFC-1023)`). Unescaped parentheses silently fail to match and produce false "pattern not found" results. Discovered during RFC-1023 verification.
 
 ## RFC criteria content rules: phase separation, reject checklist, criterion versioning (RFC-1006)
 

package/bin/cli.ts

@@ -145,19 +145,26 @@ async function buildRegistry(): Promise<ForgeCliRegistry> {
   const registry = new ForgeCliRegistry();
 
   const modules: ForgeModule[] = [
-    await import("../os/core/core.module.ts").then((m) => m.forgeCoreModule),
-    await import("../os/rfc/rfc.module.ts").then((m) => m.forgeRfcModule),
-    await import("../os/workflow/workflow.module.ts").then((m) => m.forgeWorkflowModule),
-    await import("../os/naming/naming.module.ts").then((m) => m.forgeNamingModule),
+    await import("../os/core/core.module.ts").then((m) => m.createForgeCoreModule()),
+    await import("../os/rfc/rfc.module.ts").then((m) => m.createForgeRfcModule()),
+    await import("../os/workflow/workflow.module.ts").then((m) => m.createForgeWorkflowModule()),
+    await import("../os/naming/naming.module.ts").then((m) => m.createForgeNamingModule()),
     await import("../os/compass/compass.module.ts").then((m) => m.forgeCompassModule),
     await import("../os/werkstatt/werkstatt.module.ts").then((m) => m.forgeWerkstattModule),
-    await import("../os/session/session.module.ts").then((m) => m.forgeSessionModule),
-    await import("../os/exploration/exploration.module.ts").then((m) => m.forgeExplorationModule),
-    await import("../os/notes/notes.module.ts").then((m) => m.forgeNotesModule),
+    await import("../os/session/session.module.ts").then((m) => m.createForgeSessionModule()),
+    await import("../os/exploration/exploration.module.ts").then((m) =>
+      m.createForgeExplorationModule(),
+    ),
+    await import("../os/notes/notes.module.ts").then((m) => m.createForgeNotesModule()),
   ].filter((m): m is ForgeModule => m !== null);
 
   for (const mod of modules) {
-    await mod.register(registry);
+    for (const cmd of mod.commands) {
+      registry.registerCommand(cmd);
+    }
+    for (const pipe of mod.pipelines) {
+      registry.registerPipeline(pipe.name, pipe.steps);
+    }
   }
 
   return registry;

package/os/adr/adr.module.ts

@@ -14,18 +14,19 @@
 
 import type { ForgeModule } from "../../src/forge-module.ts";
 
-export const forgeAdrModule: ForgeModule = {
-  name: "forge-adr",
-  version: "0.1.0",
-  runtime: "autonomous",
-
-  async register(registry) {
-    const { runAdrList, runAdrCreate } = await import("./handlers/list-create.ts");
+export async function createForgeAdrModule(): Promise<ForgeModule> {
+const { runAdrList, runAdrCreate } = await import("./handlers/list-create.ts");
     const { runAdrValidate } = await import("./handlers/validate.ts");
     const { runAdrArchive } = await import("./handlers/archive.ts");
     const { runAdrImplementStamp } = await import("./handlers/implement-stamp.ts");
+  return {
+  name: "forge-adr",
+  version: "0.1.0",
+  runtime: "autonomous",
 
-    registry.registerCommand({
+    declarations: [],
+  commands: [
+    {
       name: "adr.list",
       description:
         "List all ADRs. Filter with --status, --scope, --decider flags. " +
@@ -45,9 +46,8 @@ export const forgeAdrModule: ForgeModule = {
       },
       reads: ["docs/adrs/**/*.md"],
       execute: runAdrList,
-    });
-
-    registry.registerCommand({
+    },
+    {
       name: "adr.create",
       description:
         "Create a new ADR draft from the template. " +
@@ -83,9 +83,8 @@ export const forgeAdrModule: ForgeModule = {
         },
       },
       execute: runAdrCreate,
-    });
-
-    registry.registerCommand({
+    },
+    {
       name: "adr.validate",
       contract: "adr",
       rules: [],
@@ -99,9 +98,8 @@ export const forgeAdrModule: ForgeModule = {
       },
       reads: ["docs/adrs/**/*.md"],
       execute: runAdrValidate,
-    });
-
-    registry.registerCommand({
+    },
+    {
       name: "adr.archive",
       description:
         "Move terminal-status ADR files (implemented, rejected, superseded) into " +
@@ -125,9 +123,8 @@ export const forgeAdrModule: ForgeModule = {
         },
       },
       execute: runAdrArchive,
-    });
-
-    registry.registerCommand({
+    },
+    {
       name: "adr.implement.stamp",
       description:
         "Atomically transition an ADR from accepted/proposed to implemented. " +
@@ -156,6 +153,10 @@ export const forgeAdrModule: ForgeModule = {
         },
       },
       execute: runAdrImplementStamp,
-    });
-  },
-};
+    }
+  ],
+  pipelines: [
+
+  ]};
+}
+;

package/os/adr/index.ts

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-export { forgeAdrModule } from "./adr.module.ts";
+export { createForgeAdrModule } from "./adr.module.ts";
 export { runAdrList, runAdrCreate } from "./handlers/list-create.ts";
 export { runAdrValidate } from "./handlers/validate.ts";
 export { runAdrArchive } from "./handlers/archive.ts";

package/os/audit/audit.module.ts

@@ -12,14 +12,15 @@
 
 import type { ForgeModule } from "../../src/forge-module.ts";
 
-export const forgeAuditModule: ForgeModule = {
+export async function createForgeAuditModule(): Promise<ForgeModule> {
+const { runAuditArchive } = await import("./handlers/archive.ts");
+  return {
   name: "forge-audit",
   version: "0.1.0",
   runtime: "autonomous",
-  async register(registry) {
-    const { runAuditArchive } = await import("./handlers/archive.ts");
-
-    registry.registerCommand({
+    declarations: [],
+  commands: [
+    {
       name: "audit.archive",
       description:
         "Move audit files whose parent RFC has terminal status " +
@@ -44,6 +45,10 @@ export const forgeAuditModule: ForgeModule = {
         },
       },
       execute: runAuditArchive,
-    });
-  },
-};
+    }
+  ],
+  pipelines: [
+
+  ]};
+}
+;

package/os/audit/index.ts

@@ -10,7 +10,7 @@
 </CHANGE_SUMMARY>
 */
 
-export { forgeAuditModule } from "./audit.module.ts";
+export { createForgeAuditModule } from "./audit.module.ts";
 export { runAuditArchive } from "./handlers/archive.ts";
 export {
   listAuditFiles,

package/os/compass/compass.module.ts

@@ -46,8 +46,9 @@ export const forgeCompassModule: ForgeModule = {
   name: "forge-compass",
   version: "0.1.0",
   runtime: "autonomous",
-  async register(registry) {
-    registry.registerCommand({
+    declarations: [],
+  commands: [
+    {
       name: "compass.inventory",
       description: "Generate the repository-wide Compass source inventory XML report.",
       scope: "workspace",
@@ -59,8 +60,8 @@ export const forgeCompassModule: ForgeModule = {
         "services/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
       ],
       execute: runCompassInventory,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "compass.validate",
       contract: "compass",
       rules: [],
@@ -76,8 +77,8 @@ export const forgeCompassModule: ForgeModule = {
         "docs/source-markup.xml",
       ],
       execute: runCompassValidation,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "compass.changesummary.validate",
       contract: "compass",
       rules: [],
@@ -92,8 +93,8 @@ export const forgeCompassModule: ForgeModule = {
         "services/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
       ],
       execute: runCompassChangeSummaryValidate,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "compass.summary.trim",
       description:
         "Deterministically trim CHANGE_SUMMARY blocks: remove boilerplate, cap total items to 30, preserve protected items (RFC-0538).",
@@ -113,8 +114,8 @@ export const forgeCompassModule: ForgeModule = {
       cacheable: false,
       flags: { ...compassScanFlags },
       execute: runCompassSummaryTrim,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "compass.audit.plan",
       description:
         "Emit a deterministic work-order of files whose revision has advanced past the threshold since their last Compass audit (RFC-0352). Read-only, no LLM.",
@@ -134,8 +135,8 @@ export const forgeCompassModule: ForgeModule = {
         "docs/compass-audit-ledger.generated.yaml",
       ],
       execute: runCompassAuditPlan,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "compass.audit.record",
       description:
         "Stamp a file's audit verdict and current revision into the compass-audit ledger (RFC-0352). Mutating.",
@@ -155,8 +156,8 @@ export const forgeCompassModule: ForgeModule = {
         agent: { kind: "string", description: "Agent identity to record in the ledger." },
       },
       execute: runCompassAuditRecord,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "compass.audit.baseline",
       description:
         "Seed the compass-audit ledger for every authored file at its current revision with verdict=baseline (RFC-0352). One-time bootstrap.",
@@ -172,8 +173,8 @@ export const forgeCompassModule: ForgeModule = {
       cacheable: false,
       flags: { ...compassScanFlags },
       execute: runCompassAuditBaseline,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "compass.audit.validate",
       contract: "compass",
       rules: [],
@@ -204,6 +205,8 @@ export const forgeCompassModule: ForgeModule = {
           description: "Warns by default, fails with --strict",
         },
       },
-    });
-  },
-};
+    }
+  ],
+  pipelines: [
+
+  ]};