@warpgogol/forge 5.2.3 → 5.3.0

package/os/rfc/rfc.module.ts

@@ -15,416 +15,455 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — werkstatt-engine clean
 
 Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+  <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
 </CHANGE_SUMMARY>
 */
 
 import type { ForgeModule } from "../../src/forge-module.ts";
 
 export async function createForgeRfcModule(): Promise<ForgeModule> {
-const {
-      runRfcList,
-      runRfcCreate,
-      runRfcNextId,
-      runRfcValidate,
-      runRfcCommandLifecycleValidate,
-      runRfcCheck,
-      runRfcIndexGenerate,
-      runRfcIndexValidate,
-      runRfcGraph,
-    } = await import("./handlers.ts");
-    const { runRfcAcceptanceRun } = await import("./acceptance.ts");
-    const { runRfcVerificationEmit } = await import("./verification-evidence.ts");
-    const { runRfcVerificationRefresh } = await import("./verification-refresh.ts");
-    const { runRfcDnaTraceValidate, runRfcDnaTraceGenerate } = await import("./dna-trace.ts");
-    const { runRfcDecisionLogGenerate } = await import("./decision-log.ts");
-    const { runRfcSupersedePropose } = await import("./handlers/supersede-propose.ts");
-    const { runRfcArchive } = await import("./handlers/archive.ts");
-    const { runRfcPipelineStatus } = await import("./handlers/pipeline-status.ts");
-    const { runRfcImplementStamp } = await import("./handlers/implement-stamp.ts");
-    // ── rfc.list ─────────────────────────────────────────────────────────────;
+  const {
+    runRfcList,
+    runRfcCreate,
+    runRfcNextId,
+    runRfcValidate,
+    runRfcCommandLifecycleValidate,
+    runRfcCheck,
+    runRfcIndexGenerate,
+    runRfcIndexValidate,
+    runRfcGraph,
+  } = await import("./handlers.ts");
+  const { runRfcAcceptanceRun } = await import("./acceptance.ts");
+  const { runRfcVerificationEmit } = await import("./verification-evidence.ts");
+  const { runRfcVerificationRefresh } = await import("./verification-refresh.ts");
+  const { runRfcDnaTraceValidate, runRfcDnaTraceGenerate } = await import("./dna-trace.ts");
+  const { runRfcDecisionLogGenerate } = await import("./decision-log.ts");
+  const { runRfcSupersedePropose } = await import("./handlers/supersede-propose.ts");
+  const { runRfcArchive } = await import("./handlers/archive.ts");
+  const { runRfcPipelineStatus } = await import("./handlers/pipeline-status.ts");
+  const { runRfcImplementStamp } = await import("./handlers/implement-stamp.ts");
+  // ── rfc.list ─────────────────────────────────────────────────────────────;
   return {
-  name: "rfc",
-  version: "0.1.0",
-  runtime: "autonomous",
+    name: "rfc",
+    version: "0.1.0",
+    runtime: "autonomous",
 
     declarations: [],
-  commands: [
-    {
-      name: "rfc.list",
-      description:
-        "List all RFCs. Filter with --status, --kind, --owner flags. " +
-        "Use --json for machine-readable output. " +
-        "Parses frontmatter on the fly — no index file needed.",
-      scope: "workspace",
-      // RFC-0260: typed flag schema.
-      flags: {
-        status: {
-          kind: "string",
-          description: "Filter by RFC status (e.g. draft, accepted, implemented).",
-        },
-        kind: {
-          kind: "string",
-          description: "Filter by RFC kind (e.g. architecture, contract, command).",
-        },
-        owner: { kind: "string", description: "Filter by an owner string." },
-        batch: {
-          kind: "string",
-          description: "Filter by batch slug (e.g. engine-consolidation).",
+    commands: [
+      {
+        name: "rfc.list",
+        mutatesState: false,
+        description:
+          "List all RFCs. Filter with --status, --kind, --owner flags. " +
+          "Use --json for machine-readable output. " +
+          "Parses frontmatter on the fly — no index file needed.",
+        scope: "workspace",
+        // RFC-0260: typed flag schema.
+        flags: {
+          status: {
+            kind: "string",
+            description: "Filter by RFC status (e.g. draft, accepted, implemented).",
+          },
+          kind: {
+            kind: "string",
+            description: "Filter by RFC kind (e.g. architecture, contract, command).",
+          },
+          owner: { kind: "string", description: "Filter by an owner string." },
+          batch: {
+            kind: "string",
+            description: "Filter by batch slug (e.g. engine-consolidation).",
+          },
         },
+        reads: ["docs/rfcs/**/*.md"],
+        execute: runRfcList,
       },
-      reads: ["docs/rfcs/**/*.md"],
-      execute: runRfcList,
-    },
-    {
-      name: "rfc.create",
-      description:
-        "Create a new RFC draft from the template. " +
-        'Pass --title "Short title" (required). ' +
-        "Optional: --kind, --scope, --satisfies DNA-N,DNA-M. " +
-        "Always creates status: draft. " +
-        "AI agents are allowed to use this command.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/rfcs/RFC-*.md"],
-      reads: ["docs/rfcs/**/*.md"],
-      cacheable: false,
-      // RFC-0260: typed flag schema.
-      flags: {
-        title: { kind: "string", required: true, description: "Short imperative RFC title." },
-        kind: {
-          kind: "string",
-          default: "architecture",
-          description: "RFC kind: architecture | contract | command | policy | deprecation.",
+      {
+        name: "rfc.create",
+        description:
+          "Create a new RFC draft from the template. " +
+          'Pass --title "Short title" (required). ' +
+          "Optional: --kind, --scope, --satisfies DNA-N,DNA-M. " +
+          "Always creates status: draft. " +
+          "AI agents are allowed to use this command.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/rfcs/RFC-*.md"],
+        generates: [],
+        reads: ["docs/rfcs/**/*.md"],
+        cacheable: false,
+        // RFC-0260: typed flag schema.
+        flags: {
+          title: { kind: "string", required: true, description: "Short imperative RFC title." },
+          kind: {
+            kind: "string",
+            default: "architecture",
+            description: "RFC kind: architecture | contract | command | policy | deprecation.",
+          },
+          scope: {
+            kind: "string",
+            default: "workspace",
+            description: "RFC scope: app | workspace.",
+          },
+          satisfies: {
+            kind: "string",
+            description:
+              "Comma-separated DNA ids this RFC satisfies. Required for architecture/contract RFCs.",
+          },
         },
-        scope: { kind: "string", default: "workspace", description: "RFC scope: app | workspace." },
-        satisfies: {
-          kind: "string",
-          description:
-            "Comma-separated DNA ids this RFC satisfies. Required for architecture/contract RFCs.",
-        },
-      },
-      execute: runRfcCreate,
-    },
-    {
-      name: "rfc.next-id",
-      description:
-        "Return the next free RFC number (max existing + 1) by scanning docs/rfcs/ recursively including archive/.",
-      scope: "workspace",
-      flags: {},
-      reads: ["docs/rfcs/**/*.md"],
-      execute: runRfcNextId,
-    },
-    {
-      name: "rfc.validate",
-      contract: "rfc",
-      rules: [],
-      description:
-        "Validate RFC frontmatter schema, required markdown sections, " +
-        "referential integrity (supersedes/supersededBy), date consistency, " +
-        "and RFC command lifecycle metadata (RFC-CMD-*). " +
-        "Pass --id to validate a single file, or run without arguments for all.",
-      scope: "workspace",
-      flags: {
-        id: { kind: "string", description: "Target a single RFC by id (e.g. RFC-0609)." },
+        execute: runRfcCreate,
       },
-      reads: ["docs/rfcs/**/*.md"],
-      execute: runRfcValidate,
-    },
-    {
-      name: "rfc.command-lifecycle.validate",
-      contract: "rfc",
-      rules: [],
-      description:
-        "Validate RFC commands.proposed/added/changed/removed lifecycle metadata " +
-        "against live registered commands. Emits RFC-CMD-* diagnostics.",
-      scope: "workspace",
-      flags: {
-        id: { kind: "string", description: "Target a single RFC by id (e.g. RFC-0609)." },
+      {
+        name: "rfc.next-id",
+        mutatesState: false,
+        description:
+          "Return the next free RFC number (max existing + 1) by scanning docs/rfcs/ recursively including archive/.",
+        scope: "workspace",
+        flags: {},
+        reads: ["docs/rfcs/**/*.md"],
+        execute: runRfcNextId,
       },
-      reads: ["docs/rfcs/**/*.md"],
-      cacheable: false,
-      execute: runRfcCommandLifecycleValidate,
-    },
-    {
-      name: "rfc.check",
-      contract: "rfc",
-      rules: [],
-      description:
-        "Validate that artifacts declared by accepted/implemented RFCs exist on disk. " +
-        "Checks files from 'File system responsibilities' tables and feature flag references. " +
-        "Use --status to override which RFC statuses to check.",
-      scope: "workspace",
-      // RFC-0260: typed flag schema.
-      flags: {
-        status: {
-          kind: "string[]",
-          description: "Override which RFC statuses to check (default: accepted, implemented).",
+      {
+        name: "rfc.validate",
+        mutatesState: false,
+        contract: "rfc",
+        rules: [],
+        description:
+          "Validate RFC frontmatter schema, required markdown sections, " +
+          "referential integrity (supersedes/supersededBy), date consistency, " +
+          "and RFC command lifecycle metadata (RFC-CMD-*). " +
+          "Pass --id to validate a single file, or run without arguments for all.",
+        scope: "workspace",
+        flags: {
+          id: { kind: "string", description: "Target a single RFC by id (e.g. RFC-0609)." },
         },
+        reads: ["docs/rfcs/**/*.md"],
+        execute: runRfcValidate,
       },
-      reads: ["docs/rfcs/**/*.md"],
-      execute: runRfcCheck,
-    },
-    {
-      name: "rfc.index.generate",
-      description:
-        "Emit a machine-readable relationship index of all RFCs (id, status, dates, " +
-        "supersedes/supersededBy/amends/amendedBy/related). Use --json, or --write to " +
-        "persist docs/rfcs/index.yaml.",
-      scope: "workspace",
-      // RFC-0260: typed flag schema.
-      flags: {
-        write: {
-          kind: "boolean",
-          description: "Persist the generated index to docs/rfcs/index.yaml.",
+      {
+        name: "rfc.command-lifecycle.validate",
+        mutatesState: false,
+        contract: "rfc",
+        rules: [],
+        description:
+          "Validate RFC commands.proposed/added/changed/removed lifecycle metadata " +
+          "against live registered commands. Emits RFC-CMD-* diagnostics.",
+        scope: "workspace",
+        flags: {
+          id: { kind: "string", description: "Target a single RFC by id (e.g. RFC-0609)." },
         },
+        reads: ["docs/rfcs/**/*.md"],
+        cacheable: false,
+        execute: runRfcCommandLifecycleValidate,
       },
-      reads: ["docs/rfcs/**/*.md"],
-      cacheable: false,
-      execute: runRfcIndexGenerate,
-    },
-    {
-      name: "rfc.index.validate",
-      contract: "rfc",
-      rules: [],
-      description:
-        "Validate that docs/rfcs/index.yaml exists, is parseable, and its entry count " +
-        "matches the number of RFC files on disk. Reports RFC-IDX-01 (missing), " +
-        "RFC-IDX-02 (unparseable), RFC-IDX-03 (count mismatch).",
-      scope: "workspace",
-      flags: {},
-      reads: ["docs/rfcs/**/*.md", "docs/rfcs/index.yaml"],
-      execute: runRfcIndexValidate,
-    },
-    {
-      name: "rfc.graph",
-      description:
-        "Print one RFC's relationship neighbours (supersedes/supersededBy/amends/" +
-        "amendedBy/related). Pass --id RFC-0152.",
-      scope: "workspace",
-      flags: {
-        id: { kind: "string", description: "Target a single RFC by id (e.g. RFC-0152)." },
-      },
-      reads: ["docs/rfcs/**/*.md"],
-      execute: runRfcGraph,
-    },
-    {
-      name: "rfc.acceptance.run",
-      description:
-        "RFC-0268: execute the acceptance: probes declared in an RFC's frontmatter and report " +
-        "pass/fail per probe (RFC-ACC-01 failed probe, RFC-ACC-02 accepted/implemented RFC with " +
-        "zero probes). Requires --id <rfc-id> or --status <status>; never runs automatically inside " +
-        "build pipelines.",
-      scope: "workspace",
-      flags: {
-        id: { kind: "string", description: "Target a single RFC by id (e.g. rfc-0268)." },
-        status: {
-          kind: "string",
-          description: "Target every RFC with this status (e.g. accepted).",
+      {
+        name: "rfc.check",
+        mutatesState: false,
+        contract: "rfc",
+        rules: [],
+        description:
+          "Validate that artifacts declared by accepted/implemented RFCs exist on disk. " +
+          "Checks files from 'File system responsibilities' tables and feature flag references. " +
+          "Use --status to override which RFC statuses to check.",
+        scope: "workspace",
+        // RFC-0260: typed flag schema.
+        flags: {
+          status: {
+            kind: "string[]",
+            description: "Override which RFC statuses to check (default: accepted, implemented).",
+          },
         },
+        reads: ["docs/rfcs/**/*.md"],
+        execute: runRfcCheck,
       },
-      reads: ["docs/rfcs/**/*.md"],
-      cacheable: false,
-      execute: runRfcAcceptanceRun,
-    },
-    {
-      name: "rfc.verification.emit",
-      description:
-        "RFC-0330: execute acceptance probes for target RFC(s) and write per-RFC verification " +
-        "evidence artifacts to docs/rfcs/verification/*.generated.yaml. Requires --id <rfc-id> " +
-        "or --status <status>. Reuses runProbe from RFC-0268. Writes via writeFileAtomic.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/rfcs/verification/*.generated.yaml"],
-      reads: ["docs/rfcs/**/*.md"],
-      cacheable: false,
-      flags: {
-        id: { kind: "string", description: "Target a single RFC by id (e.g. rfc-0330)." },
-        status: {
-          kind: "string",
-          description: "Target every RFC with this status (e.g. implemented).",
+      {
+        name: "rfc.index.generate",
+        mutatesState: true,
+        description:
+          "Emit a machine-readable relationship index of all RFCs (id, status, dates, " +
+          "supersedes/supersededBy/amends/amendedBy/related). Use --json, or --write to " +
+          "persist docs/rfcs/index.yaml.",
+        scope: "workspace",
+        // RFC-0260: typed flag schema.
+        flags: {
+          write: {
+            kind: "boolean",
+            description: "Persist the generated index to docs/rfcs/index.yaml.",
+          },
         },
+        reads: ["docs/rfcs/**/*.md"],
+        writes: ["docs/rfcs/index.yaml"],
+        generates: [],
+        cacheable: false,
+        execute: runRfcIndexGenerate,
       },
-      execute: runRfcVerificationEmit,
-    },
-    {
-      name: "rfc.verification.refresh",
-      description:
-        "RFC-0999: re-run acceptance probes for implemented RFC(s) and update verification " +
-        "evidence envelopes in-place. Preserves emittedAt, adds lastRefreshedAt, replaces " +
-        "probes[] with fresh results. Requires --id <rfc-id> or --all. Use --dry-run to " +
-        "run probes without writing envelope files.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/rfcs/verification/*.generated.yaml"],
-      reads: ["docs/rfcs/**/*.md", "docs/rfcs/verification/*.generated.yaml"],
-      cacheable: false,
-      flags: {
-        id: { kind: "string", description: "Target a single RFC by id (e.g. rfc-0330)." },
-        all: {
-          kind: "boolean",
-          description: "Refresh all implemented RFCs with existing evidence envelopes.",
-        },
-        "dry-run": {
-          kind: "boolean",
-          description: "Run probes and report results without writing envelope files.",
-        },
+      {
+        name: "rfc.index.validate",
+        mutatesState: false,
+        contract: "rfc",
+        rules: [],
+        description:
+          "Validate that docs/rfcs/index.yaml exists, is parseable, and its entry count " +
+          "matches the number of RFC files on disk. Reports RFC-IDX-01 (missing), " +
+          "RFC-IDX-02 (unparseable), RFC-IDX-03 (count mismatch).",
+        scope: "workspace",
+        flags: {},
+        reads: ["docs/rfcs/**/*.md", "docs/rfcs/index.yaml"],
+        execute: runRfcIndexValidate,
       },
-      execute: runRfcVerificationRefresh,
-    },
-    {
-      name: "rfc.dna.trace.validate",
-      contract: "rfc",
-      rules: [],
-      description:
-        "RFC-0331: validate the bidirectional DNA-trace matrix — which RFCs satisfy each DNA " +
-        "invariant and which invariants each RFC claims to satisfy. Reports DNA-TRACE-01 " +
-        "(nonexistent id), DNA-TRACE-02 (uncovered invariant), DNA-TRACE-03 (rejected claim).",
-      scope: "workspace",
-      flags: {
-        dna: {
-          kind: "string",
-          description: "Filter output to a single DNA invariant (e.g. DNA-35).",
+      {
+        name: "rfc.graph",
+        mutatesState: false,
+        description:
+          "Print one RFC's relationship neighbours (supersedes/supersededBy/amends/" +
+          "amendedBy/related). Pass --id RFC-0152.",
+        scope: "workspace",
+        flags: {
+          id: { kind: "string", description: "Target a single RFC by id (e.g. RFC-0152)." },
         },
+        reads: ["docs/rfcs/**/*.md"],
+        execute: runRfcGraph,
       },
-      reads: ["docs/rfcs/**/*.md", "docs/architecture-dna.md"],
-      execute: runRfcDnaTraceValidate,
-    },
-    {
-      name: "rfc.dna.trace.generate",
-      description:
-        "RFC-0331: generate docs/rfcs/dna-trace.generated.yaml — the machine-readable " +
-        "requirements-traceability matrix of DNA invariants and satisfying RFCs.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/rfcs/dna-trace.generated.yaml"],
-      reads: ["docs/rfcs/**/*.md", "docs/architecture-dna.md"],
-      cacheable: false,
-      flags: {},
-      execute: runRfcDnaTraceGenerate,
-    },
-    {
-      name: "rfc.decision-log.generate",
-      description:
-        "RFC-0329: generate docs/rfcs/decision-log.generated.yaml and .md aggregating every " +
-        "rejected/superseded RFC and every non-empty Alternatives considered section. " +
-        "Use --check to verify projections are up to date without writing.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/rfcs/decision-log.generated.yaml", "docs/rfcs/decision-log.generated.md"],
-      reads: ["docs/rfcs/**/*.md"],
-      cacheable: false,
-      flags: {
-        check: {
-          kind: "boolean",
-          description: "Drift check only — no writes, exit 1 if projections differ.",
+      {
+        name: "rfc.acceptance.run",
+        mutatesState: true,
+        description:
+          "RFC-0268: execute the acceptance: probes declared in an RFC's frontmatter and report " +
+          "pass/fail per probe (RFC-ACC-01 failed probe, RFC-ACC-02 accepted/implemented RFC with " +
+          "zero probes). Requires --id <rfc-id> or --status <status>; never runs automatically inside " +
+          "build pipelines.",
+        scope: "workspace",
+        flags: {
+          id: { kind: "string", description: "Target a single RFC by id (e.g. rfc-0268)." },
+          status: {
+            kind: "string",
+            description: "Target every RFC with this status (e.g. accepted).",
+          },
         },
+        reads: ["docs/rfcs/**/*.md"],
+        cacheable: false,
+        execute: runRfcAcceptanceRun,
       },
-      execute: runRfcDecisionLogGenerate,
-    },
-    {
-      name: "rfc.supersede.propose",
-      description:
-        "RFC-0334: escalate a blocked implementation by creating a draft superseding RFC " +
-        "with the conflict stated and TODO sections for the proposed alternative.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/rfcs/RFC-*.md"],
-      reads: ["docs/rfcs/**/*.md"],
-      cacheable: false,
-      flags: {
-        id: {
-          kind: "string",
-          description: "Target RFC id to supersede (e.g. RFC-0322).",
-        },
-        reason: {
-          kind: "string",
-          description: "Why the accepted design is unimplementable.",
+      {
+        name: "rfc.verification.emit",
+        modulePath: "packages/forge/os/rfc/rfc.module.ts",
+        description:
+          "RFC-0330: execute acceptance probes for target RFC(s) and write per-RFC verification " +
+          "evidence artifacts to docs/rfcs/verification/*.generated.yaml. Requires --id <rfc-id> " +
+          "or --status <status>. Reuses runProbe from RFC-0268. Writes via writeFileAtomic.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/rfcs/verification/*.generated.yaml"],
+        generates: [{ path: "docs/rfcs/verification/*.generated.yaml", phase: "on-demand" }],
+        reads: ["docs/rfcs/**/*.md"],
+        cacheable: false,
+        flags: {
+          id: { kind: "string", description: "Target a single RFC by id (e.g. rfc-0330)." },
+          status: {
+            kind: "string",
+            description: "Target every RFC with this status (e.g. implemented).",
+          },
         },
-        invariant: {
-          kind: "string",
-          description: "Comma-separated invariant ids (DNA-N or RFC-XXXX) that conflict.",
-        },
-        title: {
-          kind: "string",
-          description: "Optional replacement title for the new draft.",
+        execute: runRfcVerificationEmit,
+      },
+      {
+        name: "rfc.verification.refresh",
+        modulePath: "packages/forge/os/rfc/rfc.module.ts",
+        description:
+          "RFC-0999: re-run acceptance probes for implemented RFC(s) and update verification " +
+          "evidence envelopes in-place. Preserves emittedAt, adds lastRefreshedAt, replaces " +
+          "probes[] with fresh results. Requires --id <rfc-id> or --all. Use --dry-run to " +
+          "run probes without writing envelope files.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/rfcs/verification/*.generated.yaml"],
+        // Secondary writer — rfc.verification.emit owns these envelopes;
+        // conditional keeps OWN-DUP-01 from flagging the shared glob.
+        generates: [
+          {
+            path: "docs/rfcs/verification/*.generated.yaml",
+            phase: "on-demand",
+            conditional: true,
+          },
+        ],
+        reads: ["docs/rfcs/**/*.md", "docs/rfcs/verification/*.generated.yaml"],
+        cacheable: false,
+        flags: {
+          id: { kind: "string", description: "Target a single RFC by id (e.g. rfc-0330)." },
+          all: {
+            kind: "boolean",
+            description: "Refresh all implemented RFCs with existing evidence envelopes.",
+          },
+          "dry-run": {
+            kind: "boolean",
+            description: "Run probes and report results without writing envelope files.",
+          },
         },
+        execute: runRfcVerificationRefresh,
       },
-      execute: runRfcSupersedePropose,
-    },
-    {
-      name: "rfc.archive",
-      description:
-        "Move terminal-status RFC files (implemented, rejected, superseded) into " +
-        "docs/rfcs/archive/<status>/ subdirectories. Bidirectional: moves non-terminal " +
-        "files found in subdirectories back to root. Use --dry-run to preview. " +
-        "Use --status to filter to a single terminal status. " +
-        "Prefer the docs.archive umbrella command unless you need to archive only RFCs.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/rfcs/*.md", "docs/rfcs/archive/**"],
-      reads: ["docs/rfcs/**/*.md"],
-      cacheable: false,
-      flags: {
-        "dry-run": {
-          kind: "boolean",
-          description: "Preview what would be moved without touching the filesystem.",
+      {
+        name: "rfc.dna.trace.validate",
+        mutatesState: false,
+        contract: "rfc",
+        rules: [],
+        description:
+          "RFC-0331: validate the bidirectional DNA-trace matrix — which RFCs satisfy each DNA " +
+          "invariant and which invariants each RFC claims to satisfy. Reports DNA-TRACE-01 " +
+          "(nonexistent id), DNA-TRACE-02 (uncovered invariant), DNA-TRACE-03 (rejected claim).",
+        scope: "workspace",
+        flags: {
+          dna: {
+            kind: "string",
+            description: "Filter output to a single DNA invariant (e.g. DNA-35).",
+          },
         },
-        status: {
-          kind: "string",
-          description: "Filter to a single terminal status (implemented, rejected, superseded).",
+        reads: ["docs/rfcs/**/*.md", "docs/architecture-dna.md"],
+        execute: runRfcDnaTraceValidate,
+      },
+      {
+        name: "rfc.dna.trace.generate",
+        modulePath: "packages/forge/os/rfc/rfc.module.ts",
+        description:
+          "RFC-0331: generate docs/rfcs/dna-trace.generated.yaml — the machine-readable " +
+          "requirements-traceability matrix of DNA invariants and satisfying RFCs.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/rfcs/dna-trace.generated.yaml"],
+        generates: [{ path: "docs/rfcs/dna-trace.generated.yaml", phase: "on-demand" }],
+        reads: ["docs/rfcs/**/*.md", "docs/architecture-dna.md"],
+        cacheable: false,
+        flags: {},
+        execute: runRfcDnaTraceGenerate,
+      },
+      {
+        name: "rfc.decision-log.generate",
+        modulePath: "packages/forge/os/rfc/rfc.module.ts",
+        description:
+          "RFC-0329: generate docs/rfcs/decision-log.generated.yaml and .md aggregating every " +
+          "rejected/superseded RFC and every non-empty Alternatives considered section. " +
+          "Use --check to verify projections are up to date without writing.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/rfcs/decision-log.generated.yaml", "docs/rfcs/decision-log.generated.md"],
+        generates: [
+          { path: "docs/rfcs/decision-log.generated.yaml", phase: "on-demand" },
+          { path: "docs/rfcs/decision-log.generated.md", phase: "on-demand" },
+        ],
+        reads: ["docs/rfcs/**/*.md"],
+        cacheable: false,
+        flags: {
+          check: {
+            kind: "boolean",
+            description: "Drift check only — no writes, exit 1 if projections differ.",
+          },
         },
+        execute: runRfcDecisionLogGenerate,
       },
-      execute: runRfcArchive,
-    },
-    {
-      name: "rfc.pipeline.status",
-      description:
-        "Report the pipeline status of RFCs — which steps (audit, enhance, plan, implement) " +
-        "are complete or missing. Pass --id to check a single file, or run without " +
-        "arguments for all. Read-only — does not mutate files. Skills keep their own " +
-        "prerequisite checks; this command is for agents and humans to inspect pipeline state.",
-      scope: "workspace",
-      flags: {
-        id: { kind: "string", description: "Target a single RFC by id (e.g. RFC-0609)." },
+      {
+        name: "rfc.supersede.propose",
+        description:
+          "RFC-0334: escalate a blocked implementation by creating a draft superseding RFC " +
+          "with the conflict stated and TODO sections for the proposed alternative.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/rfcs/RFC-*.md"],
+        generates: [],
+        reads: ["docs/rfcs/**/*.md"],
+        cacheable: false,
+        flags: {
+          id: {
+            kind: "string",
+            description: "Target RFC id to supersede (e.g. RFC-0322).",
+          },
+          reason: {
+            kind: "string",
+            description: "Why the accepted design is unimplementable.",
+          },
+          invariant: {
+            kind: "string",
+            description: "Comma-separated invariant ids (DNA-N or RFC-XXXX) that conflict.",
+          },
+          title: {
+            kind: "string",
+            description: "Optional replacement title for the new draft.",
+          },
+        },
+        execute: runRfcSupersedePropose,
       },
-      reads: ["docs/rfcs/**/*.md"],
-      execute: runRfcPipelineStatus,
-    },
-    {
-      name: "rfc.implement.stamp",
-      description:
-        "RFC-0476: the exclusive atomic path for accepted → implemented transitions. " +
-        "Verifies preconditions (accepted status, checked+evidenced criteria, clean tree, " +
-        "reachable RFC-referencing commit, passing probe evidence) then atomically sets " +
-        "status: implemented, implementedAt, and updatedAt. Use --dry-run to preview. Required flags: `--id`.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/rfcs/**/*.md"],
-      reads: ["docs/rfcs/**/*.md", "docs/rfcs/verification/*.generated.yaml"],
-      cacheable: false,
-      flags: {
-        id: {
-          kind: "string",
-          required: true,
-          description: "Target RFC id to stamp (e.g. RFC-0476).",
+      {
+        name: "rfc.archive",
+        description:
+          "Move terminal-status RFC files (implemented, rejected, superseded) into " +
+          "docs/rfcs/archive/<status>/ subdirectories. Bidirectional: moves non-terminal " +
+          "files found in subdirectories back to root. Use --dry-run to preview. " +
+          "Use --status to filter to a single terminal status. " +
+          "Prefer the docs.archive umbrella command unless you need to archive only RFCs.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/rfcs/*.md", "docs/rfcs/archive/**"],
+        generates: [],
+        reads: ["docs/rfcs/**/*.md"],
+        cacheable: false,
+        flags: {
+          "dry-run": {
+            kind: "boolean",
+            description: "Preview what would be moved without touching the filesystem.",
+          },
+          status: {
+            kind: "string",
+            description: "Filter to a single terminal status (implemented, rejected, superseded).",
+          },
         },
-        "implementation-commit": {
-          kind: "string",
-          required: false,
-          description:
-            "SHA of the implementation commit (must be reachable from HEAD and reference the RFC id). " +
-            "When omitted, the command auto-detects the commit via git log --grep=<RFC-ID> (RFC-0756).",
+        execute: runRfcArchive,
+      },
+      {
+        name: "rfc.pipeline.status",
+        mutatesState: false,
+        description:
+          "Report the pipeline status of RFCs — which steps (audit, enhance, plan, implement) " +
+          "are complete or missing. Pass --id to check a single file, or run without " +
+          "arguments for all. Read-only — does not mutate files. Skills keep their own " +
+          "prerequisite checks; this command is for agents and humans to inspect pipeline state.",
+        scope: "workspace",
+        flags: {
+          id: { kind: "string", description: "Target a single RFC by id (e.g. RFC-0609)." },
         },
-        "dry-run": {
-          kind: "boolean",
-          description: "Perform all checks without mutating the RFC file or emitting evidence.",
+        reads: ["docs/rfcs/**/*.md"],
+        execute: runRfcPipelineStatus,
+      },
+      {
+        name: "rfc.implement.stamp",
+        description:
+          "RFC-0476: the exclusive atomic path for accepted → implemented transitions. " +
+          "Verifies preconditions (accepted status, checked+evidenced criteria, clean tree, " +
+          "reachable RFC-referencing commit, passing probe evidence) then atomically sets " +
+          "status: implemented, implementedAt, and updatedAt. Use --dry-run to preview. Required flags: `--id`.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/rfcs/**/*.md"],
+        generates: [],
+        reads: ["docs/rfcs/**/*.md", "docs/rfcs/verification/*.generated.yaml"],
+        cacheable: false,
+        flags: {
+          id: {
+            kind: "string",
+            required: true,
+            description: "Target RFC id to stamp (e.g. RFC-0476).",
+          },
+          "implementation-commit": {
+            kind: "string",
+            required: false,
+            description:
+              "SHA of the implementation commit (must be reachable from HEAD and reference the RFC id). " +
+              "When omitted, the command auto-detects the commit via git log --grep=<RFC-ID> (RFC-0756).",
+          },
+          "dry-run": {
+            kind: "boolean",
+            description: "Perform all checks without mutating the RFC file or emitting evidence.",
+          },
         },
+        execute: runRfcImplementStamp,
       },
-      execute: runRfcImplementStamp,
-    }
-  ],
-  pipelines: [
-
-  ]};
+    ],
+    pipelines: [],
+  };
 }
-;