@warpgogol/forge 0.3.1

package/dist/os/session/session.module.js

@@ -0,0 +1,113 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register the session documentation domain commands with the forge kernel registry.</purpose>
+<non-goals>
+  <item>Do not implement handler logic here — delegate to handlers/*.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0537: initial forgeSessionModule registering session.save, session.archive, session.validate, session.list commands.</item>
+</CHANGE_SUMMARY>
+*/
+export const forgeSessionModule = {
+    name: "forge-session",
+    version: "0.1.0",
+    async register(registry) {
+        const { runSessionSave } = await import("./handlers/save.js");
+        const { runSessionArchive } = await import("./handlers/archive.js");
+        const { runSessionValidate } = await import("./handlers/validate.js");
+        const { runSessionList } = await import("./handlers/list.js");
+        registry.registerCommand({
+            name: "session.save",
+            description: "Convert raw ATIF files from docs/sessions/.raw/ to structured markdown " +
+                "in docs/sessions/ with auto-extracted metadata. Idempotent — same raw " +
+                "file always produces the same output filename. Deletes raw file after " +
+                "conversion unless --keep-raw. Use --raw-file to process a specific file.",
+            scope: "workspace",
+            mutatesState: true,
+            writes: ["docs/sessions/*.md"],
+            reads: ["docs/sessions/.raw/*"],
+            cacheable: false,
+            flags: {
+                "raw-file": {
+                    kind: "string",
+                    description: "Process a specific raw file instead of scanning .raw/.",
+                },
+                "keep-raw": {
+                    kind: "boolean",
+                    description: "Do not delete raw file after conversion.",
+                },
+                "dry-run": {
+                    kind: "boolean",
+                    description: "Preview without writing files.",
+                },
+            },
+            execute: runSessionSave,
+        });
+        registry.registerCommand({
+            name: "session.archive",
+            description: "Move session files older than --max-age-days (default 7) from " +
+                "docs/sessions/ to docs/sessions/archive/. Bidirectional: files in " +
+                "archive/ younger than threshold are moved back to docs/sessions/. " +
+                "Use --dry-run to preview. Age is computed from frontmatter date, " +
+                "not filesystem mtime. Prefer the docs.archive umbrella command " +
+                "unless you need to archive only sessions.",
+            scope: "workspace",
+            mutatesState: true,
+            writes: ["docs/sessions/*.md", "docs/sessions/archive/**"],
+            reads: ["docs/sessions/**/*.md"],
+            cacheable: false,
+            flags: {
+                "max-age-days": {
+                    kind: "string",
+                    description: "Age threshold in days (default 7).",
+                },
+                "dry-run": {
+                    kind: "boolean",
+                    description: "Preview what would be moved without touching the filesystem.",
+                },
+            },
+            execute: runSessionArchive,
+        });
+        registry.registerCommand({
+            name: "session.validate",
+            description: "Validate session frontmatter schema (SES-01), id-filename match (SES-02), " +
+                "RFC-id existence (SES-03), raw file hygiene (SES-04), and non-markdown " +
+                "file detection (SES-05). Pass a session id to validate a single file, " +
+                "or run without arguments for all. On-demand only — not integrated into " +
+                "build.check.",
+            scope: "workspace",
+            flags: {},
+            reads: ["docs/sessions/**/*.md", "docs/rfcs/**/*.md"],
+            execute: runSessionValidate,
+        });
+        registry.registerCommand({
+            name: "session.list",
+            description: "List all sessions. Filter with --date-from, --date-to, --rfc, --type flags. " +
+                "Use --json for machine-readable output. Parses frontmatter on the fly. " +
+                "Includes archived sessions (marked with archived: true).",
+            scope: "workspace",
+            flags: {
+                "date-from": {
+                    kind: "string",
+                    description: "Filter sessions from this date (YYYY-MM-DD, inclusive).",
+                },
+                "date-to": {
+                    kind: "string",
+                    description: "Filter sessions up to this date (YYYY-MM-DD, inclusive).",
+                },
+                rfc: {
+                    kind: "string",
+                    description: "Filter by related RFC id (e.g. RFC-0537).",
+                },
+                type: {
+                    kind: "string",
+                    description: "Filter by session type (mission, grilling, implementation, review, fix, freeform).",
+                },
+            },
+            reads: ["docs/sessions/**/*.md"],
+            execute: runSessionList,
+        });
+    },
+};
+//# sourceMappingURL=session.module.js.map

package/dist/os/session/session.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.module.js","sourceRoot":"","sources":["../../../os/session/session.module.ts"],"names":[],"mappings":"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"}

package/dist/os/session/types.d.ts

@@ -0,0 +1,101 @@
+export declare const SESSION_DIR = "docs/sessions";
+export declare const SESSION_RAW_SUBDIR = ".raw";
+export declare const SESSION_ARCHIVE_SUBDIR = "archive";
+export declare const SESSION_ID_PATTERN: RegExp;
+export declare const SESSION_FILE_PATTERN: RegExp;
+export declare const SESSION_TYPES: readonly ["mission", "grilling", "implementation", "review", "fix", "freeform"];
+export type SessionType = (typeof SESSION_TYPES)[number];
+export declare const SESSION_KNOWN_KEYS: readonly ["id", "date", "duration", "types", "summary", "relatedRfcs", "relatedArtifacts", "decisions", "commits", "files", "commands"];
+export declare const SESSION_REQUIRED_KEYS: readonly ["id", "date", "types"];
+export declare const SESSION_REQUIRED_SECTIONS: readonly ["## Transcript"];
+export declare const SES_RULES: {
+    readonly SES_01: "SES-01";
+    readonly SES_02: "SES-02";
+    readonly SES_03: "SES-03";
+    readonly SES_04: "SES-04";
+    readonly SES_05: "SES-05";
+};
+export type SesRule = (typeof SES_RULES)[keyof typeof SES_RULES];
+export interface SessionFrontmatter {
+    id: string;
+    date: string;
+    duration: string | null;
+    types: SessionType[];
+    summary: string;
+    relatedRfcs: string[];
+    relatedArtifacts: string[];
+    decisions: string[];
+    commits: string[];
+    files: string[];
+    commands: string[];
+}
+export interface SessionSaveResult {
+    command: "session.save";
+    status: "ok";
+    file: string;
+    rawFile: string;
+    rawDeleted: boolean;
+    id: string;
+    types: SessionType[];
+    extractedMetadata: {
+        relatedRfcs: string[];
+        relatedArtifacts: string[];
+        commits: string[];
+        files: string[];
+        commands: string[];
+    };
+    dryRun: boolean;
+}
+export interface SessionSaveSkip {
+    rawFile: string;
+    reason: string;
+}
+export interface SessionArchiveMove {
+    id: string;
+    file: string;
+    from: string;
+    to: string;
+    ageDays: number;
+    direction: "into-archive" | "out-of-archive";
+}
+export interface SessionArchiveSkip {
+    id: string;
+    file: string;
+    reason: string;
+}
+export interface SessionArchiveResult {
+    command: "session.archive";
+    status: "ok";
+    moved: SessionArchiveMove[];
+    skipped: SessionArchiveSkip[];
+    maxAgeDays: number;
+    dryRun: boolean;
+}
+export interface SessionValidationViolation {
+    rule: SesRule;
+    file: string;
+    message: string;
+    severity: "error" | "warning";
+}
+export interface SessionValidationResult {
+    command: "session.validate";
+    status: "pass" | "fail";
+    violations: SessionValidationViolation[];
+    checked: number;
+}
+export interface SessionListEntry {
+    id: string;
+    date: string;
+    types: SessionType[];
+    summary: string;
+    relatedRfcs: string[];
+    file: string;
+    archived: boolean;
+}
+export interface SessionListResult {
+    command: "session.list";
+    status: "ok";
+    sessions: SessionListEntry[];
+    count: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/os/session/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../os/session/types.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,WAAW,kBAAkB,CAAC;AAC3C,eAAO,MAAM,kBAAkB,SAAS,CAAC;AACzC,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAChD,eAAO,MAAM,kBAAkB,QAAsD,CAAC;AACtF,eAAO,MAAM,oBAAoB,QAA0D,CAAC;AAE5F,eAAO,MAAM,aAAa,iFAOhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAO,MAAM,kBAAkB,yIAYrB,CAAC;AAEX,eAAO,MAAM,qBAAqB,kCAAmC,CAAC;AAEtE,eAAO,MAAM,yBAAyB,4BAA6B,CAAC;AAGpE,eAAO,MAAM,SAAS;;;;;;CAMZ,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAIjE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,IAAI,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,iBAAiB,EAAE;QACjB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,cAAc,GAAG,gBAAgB,CAAC;CAC9C;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB;AAID,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,UAAU,EAAE,0BAA0B,EAAE,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,IAAI,CAAC;IACb,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/os/session/types.js

@@ -0,0 +1,52 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Type definitions and constants for the session documentation domain —
+session frontmatter, list/archive/validate/save result shapes, and SES
+validation rule identifiers.
+</purpose>
+<non-goals>
+  <item>Do not define handler logic here — that lives in handlers/*.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0537: initial session domain types, constants, and SES rule identifiers.</item>
+</CHANGE_SUMMARY>
+*/
+export const SESSION_DIR = "docs/sessions";
+export const SESSION_RAW_SUBDIR = ".raw";
+export const SESSION_ARCHIVE_SUBDIR = "archive";
+export const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}-[0-9a-f]{6}$/;
+export const SESSION_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}-[0-9a-f]{6}\.md$/;
+export const SESSION_TYPES = [
+    "mission",
+    "grilling",
+    "implementation",
+    "review",
+    "fix",
+    "freeform",
+];
+export const SESSION_KNOWN_KEYS = [
+    "id",
+    "date",
+    "duration",
+    "types",
+    "summary",
+    "relatedRfcs",
+    "relatedArtifacts",
+    "decisions",
+    "commits",
+    "files",
+    "commands",
+];
+export const SESSION_REQUIRED_KEYS = ["id", "date", "types"];
+export const SESSION_REQUIRED_SECTIONS = ["## Transcript"];
+// SES validation rules
+export const SES_RULES = {
+    SES_01: "SES-01",
+    SES_02: "SES-02",
+    SES_03: "SES-03",
+    SES_04: "SES-04",
+    SES_05: "SES-05",
+};
+//# sourceMappingURL=types.js.map

package/dist/os/session/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../os/session/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;EAcE;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAC;AAC3C,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AACzC,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC;AAChD,MAAM,CAAC,MAAM,kBAAkB,GAAG,mDAAmD,CAAC;AACtF,MAAM,CAAC,MAAM,oBAAoB,GAAG,uDAAuD,CAAC;AAE5F,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,SAAS;IACT,UAAU;IACV,gBAAgB;IAChB,QAAQ;IACR,KAAK;IACL,UAAU;CACF,CAAC;AAIX,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,IAAI;IACJ,MAAM;IACN,UAAU;IACV,OAAO;IACP,SAAS;IACT,aAAa;IACb,kBAAkB;IAClB,WAAW;IACX,SAAS;IACT,OAAO;IACP,UAAU;CACF,CAAC;AAEX,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAEtE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,eAAe,CAAU,CAAC;AAEpE,uBAAuB;AACvB,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;CACR,CAAC"}

package/dist/os/spec/spec-materialize.d.ts

@@ -0,0 +1,21 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../src/types.ts";
+interface MaterializedNode {
+    node: string;
+    rfc: string;
+    file: string;
+}
+interface SkippedNode {
+    node: string;
+    reason: string;
+}
+interface SpecMaterializeResult {
+    command: "spec.materialize";
+    status: "pass" | "fail";
+    spec: string;
+    created: MaterializedNode[];
+    skipped: SkippedNode[];
+    front: string[];
+}
+export declare function runSpecMaterialize(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<SpecMaterializeResult>>;
+export {};
+//# sourceMappingURL=spec-materialize.d.ts.map

package/dist/os/spec/spec-materialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-materialize.d.ts","sourceRoot":"","sources":["../../../os/spec/spec-materialize.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAe5B,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,qBAAqB;IAC7B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAuBD,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,CAAC,CAwTpD"}

package/dist/os/spec/spec-materialize.js

@@ -0,0 +1,342 @@
+/*
+<MODULE_CONTRACT>
+<purpose>spec.materialize handler — scaffolds RFC files for front nodes of a spec roadmap (RFC-0396).</purpose>
+<non-goals>
+  <item>Do not fill RFC content — the agent fills sections during the fo pipeline.</item>
+  <item>Do not bulk-materialize past the front or above the --next cap.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0396: initial spec.materialize handler — front computation, scaffold via rfc.create, materializedAs write-back.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { toKebabCase } from "../../src/utils/string-utils.js";
+import { loadForgeConfig, resolveForgeRoot } from "../../src/config/forge-config.js";
+import { forgeSpecSchema, specAmendmentSchema, resolveAmendedNode, } from "./spec-schema.js";
+import { listRfcFiles } from "../rfc/frontmatter-io.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function readYaml(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf8");
+        return parseYaml(content);
+    }
+    catch {
+        return null;
+    }
+}
+function toIsoDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+// ---------------------------------------------------------------------------
+// Main handler
+// ---------------------------------------------------------------------------
+export async function runSpecMaterialize(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const specId = input.flags["spec"];
+    if (!specId) {
+        return {
+            data: {
+                command: "spec.materialize",
+                status: "fail",
+                spec: "",
+                created: [],
+                skipped: [],
+                front: [],
+            },
+            exitCode: 1,
+            summary: "spec.materialize: --spec=<id> is required",
+        };
+    }
+    let specsDir = "docs/specs";
+    try {
+        const config = loadForgeConfig(workspaceRoot);
+        specsDir = config.paths.specsDir;
+    }
+    catch {
+        // Use default
+    }
+    const specDir = path.join(workspaceRoot, specsDir, specId);
+    const forgeSpecPath = path.join(specDir, "forge-spec.yaml");
+    const rawSpec = await readYaml(forgeSpecPath);
+    if (!rawSpec) {
+        return {
+            data: {
+                command: "spec.materialize",
+                status: "fail",
+                spec: specId,
+                created: [],
+                skipped: [],
+                front: [],
+            },
+            exitCode: 1,
+            summary: `spec.materialize: forge-spec.yaml not found for spec '${specId}'`,
+        };
+    }
+    const parsed = forgeSpecSchema.safeParse(rawSpec);
+    if (!parsed.success) {
+        return {
+            data: {
+                command: "spec.materialize",
+                status: "fail",
+                spec: specId,
+                created: [],
+                skipped: [],
+                front: [],
+            },
+            exitCode: 1,
+            summary: `spec.materialize: forge-spec.yaml schema violation for spec '${specId}'`,
+        };
+    }
+    const spec = parsed.data;
+    if (spec.status !== "accepted") {
+        return {
+            data: {
+                command: "spec.materialize",
+                status: "fail",
+                spec: specId,
+                created: [],
+                skipped: [],
+                front: [],
+            },
+            exitCode: 1,
+            summary: `spec.materialize: spec '${specId}' is not accepted (status: ${spec.status}). Run /fo-spec-ingest to complete acceptance.`,
+        };
+    }
+    // Load amendments (RFC-0397)
+    const amendmentsDir = path.join(specDir, "amendments");
+    const amendments = [];
+    if (existsSync(amendmentsDir)) {
+        const amdEntries = await fs.readdir(amendmentsDir);
+        for (const entry of amdEntries) {
+            if (!entry.endsWith(".md"))
+                continue;
+            try {
+                const content = await fs.readFile(path.join(amendmentsDir, entry), "utf8");
+                const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+                if (!fmMatch)
+                    continue;
+                const raw = parseYaml(fmMatch[1]);
+                const amdParsed = specAmendmentSchema.safeParse(raw);
+                if (amdParsed.success) {
+                    amendments.push(amdParsed.data);
+                }
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    const proposedAmendmentNodes = new Set();
+    for (const amendment of amendments) {
+        if (amendment.status === "proposed") {
+            for (const target of amendment.targets) {
+                if (target.kind === "node")
+                    proposedAmendmentNodes.add(target.id);
+            }
+        }
+    }
+    const rfcDir = path.join(workspaceRoot, "docs", "rfcs");
+    const rfcFiles = await listRfcFiles(rfcDir);
+    // Load RFC statuses
+    const rfcStatuses = new Map();
+    for (const file of rfcFiles) {
+        try {
+            const content = await fs.readFile(path.join(rfcDir, file), "utf8");
+            const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+            if (!fmMatch)
+                continue;
+            const fm = parseYaml(fmMatch[1]);
+            const id = String(fm["id"] ?? "");
+            const status = String(fm["status"] ?? "");
+            if (id && status)
+                rfcStatuses.set(id, status);
+        }
+        catch {
+            // skip
+        }
+    }
+    // Compute node states
+    const nodeState = new Map();
+    for (const node of spec.rfcs) {
+        if (node.materializedAs) {
+            const status = rfcStatuses.get(node.materializedAs);
+            nodeState.set(node.id, status === "implemented" ? "implemented" : "unmaterialized");
+        }
+        else {
+            nodeState.set(node.id, "unmaterialized");
+        }
+    }
+    // Compute front: unmaterialized nodes whose deps are all implemented
+    function isFront(node) {
+        if (node.materializedAs)
+            return false;
+        return node.dependsOn.every((dep) => nodeState.get(dep) === "implemented");
+    }
+    const frontNodes = spec.rfcs.filter(isFront);
+    // Determine which nodes to materialize
+    const explicitNodes = input.flags["nodes"];
+    let toMaterialize;
+    if (explicitNodes) {
+        const requested = explicitNodes.split(",").map((s) => s.trim()).filter(Boolean);
+        toMaterialize = [];
+        const skipped = [];
+        for (const nodeId of requested) {
+            const node = spec.rfcs.find((n) => n.id === nodeId);
+            if (!node) {
+                skipped.push({ node: nodeId, reason: "node not found in spec" });
+            }
+            else if (!isFront(node)) {
+                const blockers = node.dependsOn.filter((d) => nodeState.get(d) !== "implemented");
+                skipped.push({ node: nodeId, reason: `blocked by ${blockers.join(", ")}` });
+            }
+            else {
+                toMaterialize.push(node);
+            }
+        }
+        if (skipped.length > 0 && toMaterialize.length === 0) {
+            return {
+                data: {
+                    command: "spec.materialize",
+                    status: "fail",
+                    spec: specId,
+                    created: [],
+                    skipped,
+                    front: frontNodes.map((n) => n.id),
+                },
+                exitCode: 1,
+                summary: `spec.materialize: all requested nodes blocked or not found`,
+            };
+        }
+    }
+    else {
+        const nextStr = input.flags["next"];
+        let next = nextStr ? parseInt(nextStr, 10) : 8;
+        if (isNaN(next) || next < 1)
+            next = 8;
+        if (next > 12)
+            next = 12;
+        toMaterialize = frontNodes.slice(0, next);
+    }
+    // Find max RFC number
+    let maxId = 0;
+    for (const file of rfcFiles) {
+        const match = path.basename(file).match(/^rfc-(\d{4})/);
+        if (match) {
+            const num = parseInt(match[1], 10);
+            if (num > maxId)
+                maxId = num;
+        }
+    }
+    // Load template from forge root (ships inside the package at os/rfc/)
+    let templatePath;
+    try {
+        const forgeRoot = resolveForgeRoot(workspaceRoot);
+        templatePath = path.join(forgeRoot, "os", "rfc", "rfc-0000-template.md");
+    }
+    catch {
+        templatePath = path.join(workspaceRoot, "os", "rfc", "rfc-0000-template.md");
+    }
+    let templateContent;
+    try {
+        templateContent = await fs.readFile(templatePath, "utf-8");
+    }
+    catch {
+        return {
+            data: {
+                command: "spec.materialize",
+                status: "fail",
+                spec: specId,
+                created: [],
+                skipped: [],
+                front: frontNodes.map((n) => n.id),
+            },
+            exitCode: 1,
+            summary: `spec.materialize: RFC template not found at ${templatePath}`,
+        };
+    }
+    const today = toIsoDate(new Date());
+    const created = [];
+    const skipped = [];
+    for (const node of toMaterialize) {
+        // Use amended node if amendments exist (RFC-0397)
+        const effectiveNode = resolveAmendedNode(spec, node.id, amendments);
+        const nextNum = maxId + 1;
+        const paddedNum = String(nextNum).padStart(4, "0");
+        const nextRfcId = `RFC-${paddedNum}`;
+        const kebabTitle = toKebabCase(effectiveNode.title);
+        const fileName = `rfc-${paddedNum}-${kebabTitle}.md`;
+        // Warn if node has a proposed amendment (RFC-0397)
+        if (proposedAmendmentNodes.has(node.id)) {
+            logger.warn(`Warning: node ${node.id} has a proposed amendment — node knowledge may be about to change`);
+        }
+        let content = templateContent;
+        content = content.replace(/^id: RFC-0000$/m, `id: ${nextRfcId}`);
+        content = content.replace(/^title: ".*"$/m, `title: "${effectiveNode.title}"`);
+        content = content.replace(/^status: draft$/m, `status: draft`);
+        content = content.replace(/^kind: \w+$/m, `kind: contract`);
+        content = content.replace(/^createdAt: YYYY-MM-DD$/m, `createdAt: ${today}`);
+        content = content.replace(/^updatedAt: YYYY-MM-DD$/m, `updatedAt: ${today}`);
+        content = content.replace(/^# specRef:$/m, `specRef: "${specId}/${node.id}"`);
+        content = content.replace(/^# RFC-0000: .+$/m, `# ${nextRfcId}: ${effectiveNode.title}`);
+        // Add normative source references in the body
+        const sourceRefs = effectiveNode.sources.length > 0
+            ? effectiveNode.sources.map((s) => `- ${s}`).join("\n")
+            : "(none)";
+        const designSection = `\n## Design\n\n**Normative source references:**\n${sourceRefs}\n\n_Fill in the implementation design for this repository. Reference vendored snapshot sections — do not copy model content._\n`;
+        content = content.replace(/^---\n\n# /m, `---\n${designSection}\n# `);
+        const targetPath = path.join(rfcDir, fileName);
+        await fs.writeFile(targetPath, content, "utf-8");
+        maxId = nextNum;
+        created.push({
+            node: node.id,
+            rfc: nextRfcId,
+            file: path.join("docs", "rfcs", fileName),
+        });
+    }
+    // Write back materializedAs into forge-spec.yaml
+    if (created.length > 0) {
+        const updatedSpec = {
+            ...spec,
+            rfcs: spec.rfcs.map((node) => {
+                const created_entry = created.find((c) => c.node === node.id);
+                return created_entry ? { ...node, materializedAs: created_entry.rfc } : node;
+            }),
+        };
+        const yamlContent = stringifyYaml(updatedSpec);
+        await fs.writeFile(forgeSpecPath, yamlContent, "utf-8");
+    }
+    // Report skipped front nodes (beyond the materialized batch)
+    const remainingFront = frontNodes
+        .filter((n) => !created.some((c) => c.node === n.id))
+        .map((n) => n.id);
+    if (outputFormat === "pretty") {
+        for (const c of created) {
+            logger.success(`Materialized ${c.node} → ${c.rfc} (${c.file})`);
+        }
+        for (const s of skipped) {
+            logger.warn(`Skipped ${s.node}: ${s.reason}`);
+        }
+        if (remainingFront.length > 0) {
+            logger.info(`Remaining front: ${remainingFront.join(", ")}`);
+        }
+    }
+    return {
+        data: {
+            command: "spec.materialize",
+            status: "pass",
+            spec: specId,
+            created,
+            skipped,
+            front: remainingFront,
+        },
+        exitCode: 0,
+        summary: `spec.materialize: created ${created.length} RFC(s) from spec '${specId}'`,
+    };
+}
+//# sourceMappingURL=spec-materialize.js.map