@warpgogol/forge 0.3.1

package/dist/os/rfc/handlers/implement-stamp.js

@@ -0,0 +1,334 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0476: rfc.implement.stamp — the exclusive atomic path for every
+accepted → implemented RFC transition. Validates preconditions, records
+verification evidence, and atomically mutates RFC frontmatter.
+</purpose>
+<non-goals>
+  <item>Does not transition non-accepted RFCs.</item>
+  <item>Does not bypass V-26/V-27 criterion semantics — reuses evaluateAcceptanceCriteria.</item>
+  <item>Does not call the GitHub API or require network access.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0476: initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+import { execFile } from "node:child_process";
+import { readFile, unlink, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { writeFileAtomic } from "../../../src/utils/fs-atomic.js";
+import { parse as yamlParse } from "yaml";
+import { listRfcFiles, readAndParseRfc, rfcFileMatchesId } from "../frontmatter-io.js";
+import { evaluateAcceptanceCriteria } from "./validate-rules.js";
+import { toIsoDate } from "./shared.js";
+import { RFC_DIR, RFC_METADATA_CUTOFF } from "../types.js";
+const VERIFICATION_DIR = join(RFC_DIR, "verification");
+// ─── Git helpers ─────────────────────────────────────────────────────────────
+function execGit(workspaceRoot, args) {
+    return new Promise((resolve) => {
+        execFile("git", args, { cwd: workspaceRoot, timeout: 10000 }, (err, stdout) => {
+            if (err) {
+                resolve("");
+                return;
+            }
+            resolve(stdout.trim());
+        });
+    });
+}
+async function isCleanWorkingTree(workspaceRoot) {
+    const status = await execGit(workspaceRoot, ["status", "--porcelain"]);
+    return status.length === 0;
+}
+async function commitReachableFromHead(workspaceRoot, commitSha) {
+    const result = await execGit(workspaceRoot, ["merge-base", "--is-ancestor", commitSha, "HEAD"]);
+    // merge-base --is-ancestor exits 0 if ancestor, 1 if not, >1 on error
+    // execGit returns "" on error (non-zero exit), trimmed stdout on success
+    // So we need a different approach: check exit code directly
+    return new Promise((resolve) => {
+        execFile("git", ["merge-base", "--is-ancestor", commitSha, "HEAD"], { cwd: workspaceRoot, timeout: 10000 }, (err) => {
+            resolve(!err);
+        });
+    });
+}
+async function commitReferencesRfc(workspaceRoot, commitSha, rfcId) {
+    // Check the commit message and the diff for the RFC ID
+    const commitMsg = await execGit(workspaceRoot, ["log", "-1", "--format=%B", commitSha]);
+    if (commitMsg.includes(rfcId))
+        return true;
+    // Also check if the commit touched a file whose name contains the RFC id
+    const changedFiles = await execGit(workspaceRoot, [
+        "show",
+        "--name-only",
+        "--format=",
+        commitSha,
+    ]);
+    const slug = rfcId.toLowerCase();
+    if (changedFiles.toLowerCase().includes(slug))
+        return true;
+    return false;
+}
+// ─── RFC-specific exclusive lock ─────────────────────────────────────────────
+function lockFilePath(workspaceRoot, rfcId) {
+    const slug = rfcId.toLowerCase();
+    return join(workspaceRoot, ".rfc-locks", `${slug}.lock`);
+}
+async function acquireRfcLock(workspaceRoot, rfcId) {
+    const lockPath = lockFilePath(workspaceRoot, rfcId);
+    const lockDir = dirname(lockPath);
+    await mkdir(lockDir, { recursive: true });
+    // Atomic lock acquisition via O_EXCL file creation
+    const { open } = await import("node:fs/promises");
+    try {
+        const handle = await open(lockPath, "wx");
+        await handle.writeFile(JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() }));
+        await handle.close();
+        return { acquired: true, lockPath };
+    }
+    catch {
+        return { acquired: false, lockPath };
+    }
+}
+async function releaseRfcLock(lockPath) {
+    try {
+        await unlink(lockPath);
+    }
+    catch {
+        // Lock file already removed — safe
+    }
+}
+// ─── Evidence helpers ────────────────────────────────────────────────────────
+async function checkExistingEvidence(workspaceRoot, rfcId) {
+    const slug = rfcId.toLowerCase();
+    const evidencePath = join(workspaceRoot, VERIFICATION_DIR, `${slug}.generated.yaml`);
+    try {
+        const content = await readFile(evidencePath, "utf-8");
+        const evidence = yamlParse(content);
+        return { exists: true, overall: String(evidence.overall ?? "") };
+    }
+    catch {
+        return { exists: false, overall: "missing" };
+    }
+}
+// ─── Frontmatter mutation ────────────────────────────────────────────────────
+function mutateFrontmatter(source, status, implementedAt, updatedAt) {
+    let content = source;
+    // Replace status
+    content = content.replace(/^status: \w+$/m, `status: ${status}`);
+    // Replace implementedAt (may be empty or already set)
+    if (/^implementedAt:.*$/m.test(content)) {
+        content = content.replace(/^implementedAt:.*$/m, `implementedAt: ${implementedAt}`);
+    }
+    else {
+        // Insert after updatedAt
+        content = content.replace(/^updatedAt: .*$/m, `updatedAt: ${updatedAt}\nimplementedAt: ${implementedAt}`);
+    }
+    // Replace updatedAt
+    content = content.replace(/^updatedAt: .*$/m, `updatedAt: ${updatedAt}`);
+    return content;
+}
+// ─── Main handler ────────────────────────────────────────────────────────────
+export async function runRfcImplementStamp(input, context) {
+    const { workspaceRoot, logger, outputFormat, dryRun } = context;
+    const rfcDirPath = join(workspaceRoot, RFC_DIR);
+    const targetId = input.flags["id"];
+    const implementationCommit = input.flags["implementation-commit"];
+    // ── Flag validation ───────────────────────────────────────────────────────
+    if (!targetId) {
+        throw new Error("rfc.implement.stamp requires --id flag (e.g. --id RFC-0476).");
+    }
+    if (!implementationCommit) {
+        throw new Error("rfc.implement.stamp requires --implementation-commit flag (the SHA of the implementation commit).");
+    }
+    const violations = [];
+    const isDryRun = dryRun || input.flags["dry-run"] === true;
+    // ── Find the target RFC ───────────────────────────────────────────────────
+    const files = await listRfcFiles(rfcDirPath);
+    const targetFile = files.find((f) => rfcFileMatchesId(f, targetId));
+    if (!targetFile) {
+        violations.push({
+            rule: "RFC-IMP-01",
+            message: `RFC ${targetId} not found in ${RFC_DIR}.`,
+        });
+        return stampFailResult(violations, isDryRun, outputFormat, logger);
+    }
+    const targetParsed = await readAndParseRfc(rfcDirPath, targetFile);
+    if (!targetParsed) {
+        violations.push({
+            rule: "RFC-IMP-01",
+            message: `Could not parse target RFC ${targetId}.`,
+        });
+        return stampFailResult(violations, isDryRun, outputFormat, logger);
+    }
+    const fm = targetParsed.parsed.frontmatter;
+    const body = targetParsed.parsed.body;
+    const currentStatus = String(fm["status"] ?? "");
+    // ── RFC-IMP-01: must be in accepted status ────────────────────────────────
+    if (currentStatus !== "accepted") {
+        violations.push({
+            rule: "RFC-IMP-01",
+            message: `RFC ${targetId} has status "${currentStatus}" — only "accepted" RFCs can be stamped to "implemented".`,
+        });
+        return stampFailResult(violations, isDryRun, outputFormat, logger);
+    }
+    // ── RFC-IMP-02: criterion checks (V-26/V-27 semantics) ────────────────────
+    const criteriaEval = evaluateAcceptanceCriteria(body);
+    if (criteriaEval.totalUnchecked > 0) {
+        violations.push({
+            rule: "RFC-IMP-02",
+            message: `${criteriaEval.totalUnchecked} acceptance criteria are unchecked. All criteria must be checked before stamping: ${criteriaEval.uncheckedLines.join("; ")}`,
+        });
+    }
+    if (criteriaEval.checkedWithoutEvidence.length > 0) {
+        violations.push({
+            rule: "RFC-IMP-02",
+            message: `${criteriaEval.checkedWithoutEvidence.length} checked criteria lack inline (evidence: ...) annotation: ${criteriaEval.checkedWithoutEvidence.join("; ")}`,
+        });
+    }
+    // ── RFC-IMP-04: clean working tree ────────────────────────────────────────
+    const cleanTree = await isCleanWorkingTree(workspaceRoot);
+    if (!cleanTree) {
+        violations.push({
+            rule: "RFC-IMP-04",
+            message: "Working tree is dirty. Commit all implementation changes before stamping.",
+        });
+    }
+    // ── RFC-IMP-03: implementation commit validation ──────────────────────────
+    const reachable = await commitReachableFromHead(workspaceRoot, implementationCommit);
+    if (!reachable) {
+        violations.push({
+            rule: "RFC-IMP-03",
+            message: `Implementation commit ${implementationCommit} is not reachable from HEAD. The commit must be an ancestor of the current HEAD.`,
+        });
+    }
+    else {
+        const referencesRfc = await commitReferencesRfc(workspaceRoot, implementationCommit, targetId);
+        if (!referencesRfc) {
+            violations.push({
+                rule: "RFC-IMP-03",
+                message: `Implementation commit ${implementationCommit} does not reference ${targetId} in its message or changed files.`,
+            });
+        }
+    }
+    // ── RFC-IMP-06: probe-bearing RFCs require passing evidence ───────────────
+    const acceptance = fm["acceptance"];
+    const hasProbes = Array.isArray(acceptance) && acceptance.length > 0;
+    const createdAtStr = String(fm["createdAt"] ?? "");
+    const requiresEvidence = createdAtStr >= RFC_METADATA_CUTOFF && hasProbes;
+    let evidenceRelPath;
+    if (requiresEvidence) {
+        const evidenceCheck = await checkExistingEvidence(workspaceRoot, targetId);
+        if (!evidenceCheck.exists || evidenceCheck.overall !== "pass") {
+            violations.push({
+                rule: "RFC-IMP-06",
+                message: `RFC ${targetId} declares acceptance probes but evidence file is missing or overall is not "pass" (got "${evidenceCheck.overall}"). Run: site-kernel run rfc.verification.emit --id ${targetId}`,
+            });
+        }
+        else {
+            const slug = targetId.toLowerCase();
+            evidenceRelPath = join(VERIFICATION_DIR, `${slug}.generated.yaml`);
+        }
+    }
+    // If any violations found, return without mutation
+    if (violations.length > 0) {
+        return stampFailResult(violations, isDryRun, outputFormat, logger);
+    }
+    // ── RFC-IMP-05: acquire RFC-specific exclusive lock ───────────────────────
+    const { acquired, lockPath } = await acquireRfcLock(workspaceRoot, targetId);
+    if (!acquired) {
+        violations.push({
+            rule: "RFC-IMP-05",
+            message: `A concurrent stamp operation is in progress for ${targetId}. Wait for it to complete and retry.`,
+        });
+        return stampFailResult(violations, isDryRun, outputFormat, logger);
+    }
+    try {
+        // ── Atomic mutation ──────────────────────────────────────────────────────
+        const rfcFilePath = join(rfcDirPath, targetFile);
+        const rfcSource = await readFile(rfcFilePath, "utf-8");
+        const today = toIsoDate(new Date());
+        const stampedAt = new Date().toISOString();
+        const mutatedSource = mutateFrontmatter(rfcSource, "implemented", today, today);
+        if (isDryRun) {
+            if (outputFormat === "pretty") {
+                logger.success(`[dry-run] ${targetId} would be stamped as implemented`);
+                logger.info(`  implementation commit: ${implementationCommit}`);
+                logger.info(`  criteria checked: ${criteriaEval.totalChecked}`);
+                if (evidenceRelPath) {
+                    logger.info(`  evidence: ${evidenceRelPath}`);
+                }
+            }
+            return {
+                data: {
+                    command: "rfc.implement.stamp",
+                    status: "pass",
+                    data: {
+                        rfcId: targetId,
+                        implementationCommit,
+                        stampedAt,
+                        criteriaChecked: criteriaEval.totalChecked,
+                        ...(evidenceRelPath ? { evidencePath: evidenceRelPath } : {}),
+                    },
+                    violations: [],
+                },
+                exitCode: 0,
+                summary: `rfc.implement.stamp: dry-run — ${targetId} would be stamped`,
+            };
+        }
+        // Write the mutated RFC file atomically
+        await writeFileAtomic(rfcFilePath, mutatedSource);
+        // ── Re-emit evidence if probes exist (to update with new status) ─────────
+        if (hasProbes && requiresEvidence && evidenceRelPath) {
+            // Evidence already exists and passed — no need to re-emit on stamp
+            // The evidence was generated before stamping; the status change is
+            // recorded in the RFC frontmatter, not in the evidence file.
+        }
+        if (outputFormat === "pretty") {
+            logger.success(`${targetId} stamped as implemented`);
+            logger.info(`  implementation commit: ${implementationCommit}`);
+            logger.info(`  criteria checked: ${criteriaEval.totalChecked}`);
+            if (evidenceRelPath) {
+                logger.info(`  evidence: ${evidenceRelPath}`);
+            }
+            logger.info(`  stamped at: ${stampedAt}`);
+        }
+        return {
+            data: {
+                command: "rfc.implement.stamp",
+                status: "pass",
+                data: {
+                    rfcId: targetId,
+                    implementationCommit,
+                    stampedAt,
+                    criteriaChecked: criteriaEval.totalChecked,
+                    ...(evidenceRelPath ? { evidencePath: evidenceRelPath } : {}),
+                },
+                violations: [],
+            },
+            exitCode: 0,
+            summary: `rfc.implement.stamp: ${targetId} stamped as implemented`,
+        };
+    }
+    finally {
+        await releaseRfcLock(lockPath);
+    }
+}
+function stampFailResult(violations, isDryRun, outputFormat, logger) {
+    const prefix = isDryRun ? "[dry-run] " : "";
+    if (outputFormat === "pretty") {
+        for (const v of violations) {
+            logger.warn(`${prefix}${v.rule}: ${v.message}`);
+        }
+    }
+    return {
+        data: {
+            command: "rfc.implement.stamp",
+            status: "fail",
+            violations,
+        },
+        exitCode: 1,
+        summary: `${prefix}rfc.implement.stamp: ${violations.length} violation(s)`,
+    };
+}
+//# sourceMappingURL=implement-stamp.js.map

package/dist/os/rfc/handlers/implement-stamp.js.map

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

package/dist/os/rfc/handlers/index-graph.d.ts

@@ -0,0 +1,13 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import type { RfcIndexResult, RfcGraphResult } from "../types.ts";
+export declare function runRfcIndexGenerate(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<RfcIndexResult>>;
+export declare function runRfcGraph(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<RfcGraphResult>>;
+export declare function runRfcIndexValidate(_input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<{
+    command: string;
+    status: string;
+    violations: {
+        rule: string;
+        message: string;
+    }[];
+}>>;
+//# sourceMappingURL=index-graph.d.ts.map

package/dist/os/rfc/handlers/index-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-graph.d.ts","sourceRoot":"","sources":["../../../../os/rfc/handlers/index-graph.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAIV,cAAc,EACd,cAAc,EACf,MAAM,aAAa,CAAC;AAIrB,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAC,CAuD7C;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAC,CA2C7C;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CACR,kBAAkB,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjD,CAAC,CACH,CAmFA"}

package/dist/os/rfc/handlers/index-graph.js

@@ -0,0 +1,189 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/os/site-kernel/src/rfc/handlers/index-graph.ts as an authored site-kernel authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0303: extracted index and graph handlers from handlers.ts into handlers/index-graph.ts.</item>
+  <item>Post-refactor hardening: rfc.graph resolves archived RFC files by basename id.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { listRfcFiles, readAndParseRfc, rfcFileMatchesId } from "../frontmatter-io.js";
+import { RFC_DIR } from "../types.js";
+import { toIsoDate } from "./shared.js";
+export async function runRfcIndexGenerate(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+    const files = await listRfcFiles(rfcDirPath);
+    const entries = [];
+    for (const fileName of files) {
+        const result = await readAndParseRfc(rfcDirPath, fileName);
+        if (!result)
+            continue;
+        const fm = result.parsed.frontmatter;
+        const arr = (k) => Array.isArray(fm[k]) ? fm[k].map(String) : [];
+        entries.push({
+            id: String(fm["id"] ?? ""),
+            title: String(fm["title"] ?? ""),
+            status: String(fm["status"] ?? ""),
+            kind: String(fm["kind"] ?? ""),
+            createdAt: String(fm["createdAt"] ?? ""),
+            implementedAt: String(fm["implementedAt"] ?? ""),
+            closedAt: String(fm["closedAt"] ?? ""),
+            supersedes: arr("supersedes"),
+            supersededBy: String(fm["supersededBy"] ?? ""),
+            amends: arr("amends"),
+            amendedBy: arr("amendedBy"),
+            related: arr("related"),
+            file: path.join(RFC_DIR, fileName),
+        });
+    }
+    entries.sort((a, b) => a.id.localeCompare(b.id));
+    let written;
+    if (input.flags["write"] === true) {
+        const outRel = path.join(RFC_DIR, "index.yaml");
+        const payload = {
+            command: "rfc.index.generate",
+            generatedAt: toIsoDate(new Date()),
+            count: entries.length,
+            entries,
+        };
+        await fs.writeFile(path.join(workspaceRoot, outRel), `${yamlStringify(payload)}`, "utf-8");
+        written = outRel;
+    }
+    if (outputFormat === "pretty") {
+        logger.section(`RFC index (${entries.length} RFC(s))`);
+        if (written)
+            logger.success(`Wrote ${written}`);
+        else
+            logger.info("Use --json for the index, or --write to persist docs/rfcs/index.yaml.");
+    }
+    return {
+        data: { command: "rfc.index.generate", status: "ok", count: entries.length, entries, written },
+        summary: written
+            ? `Wrote ${written} (${entries.length} RFCs)`
+            : `Indexed ${entries.length} RFC(s)`,
+    };
+}
+export async function runRfcGraph(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+    const targetId = input.args[0];
+    if (!targetId) {
+        throw new Error("rfc.graph requires an RFC id, e.g. site-kernel run rfc.graph -- RFC-0152");
+    }
+    const files = await listRfcFiles(rfcDirPath);
+    const fileName = files.find((f) => rfcFileMatchesId(f, targetId));
+    if (!fileName) {
+        throw new Error(`No RFC file found for id ${targetId} in ${RFC_DIR}/`);
+    }
+    const result = await readAndParseRfc(rfcDirPath, fileName);
+    const fm = result.parsed.frontmatter;
+    const arr = (k) => Array.isArray(fm[k]) ? fm[k].map(String) : [];
+    const data = {
+        command: "rfc.graph",
+        status: "ok",
+        id: targetId,
+        supersedes: arr("supersedes"),
+        supersededBy: String(fm["supersededBy"] ?? ""),
+        amends: arr("amends"),
+        amendedBy: arr("amendedBy"),
+        related: arr("related"),
+    };
+    if (outputFormat === "pretty") {
+        logger.section(`${targetId} relationships`);
+        logger.info(`supersedes:   ${data.supersedes.join(", ") || "—"}`);
+        logger.info(`supersededBy: ${data.supersededBy || "—"}`);
+        logger.info(`amends:       ${data.amends.join(", ") || "—"}`);
+        logger.info(`amendedBy:    ${data.amendedBy.join(", ") || "—"}`);
+        logger.info(`related:      ${data.related.join(", ") || "—"}`);
+    }
+    return {
+        data,
+        summary: `${targetId}: ${data.supersedes.length} supersedes, ${data.amends.length} amends, ${data.related.length} related`,
+    };
+}
+export async function runRfcIndexValidate(_input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+    const indexPath = path.join(rfcDirPath, "index.yaml");
+    const violations = [];
+    // RFC-IDX-01: missing index file
+    let indexContent;
+    try {
+        indexContent = await fs.readFile(indexPath, "utf-8");
+    }
+    catch {
+        violations.push({
+            rule: "RFC-IDX-01",
+            message: "docs/rfcs/index.yaml not found. Run `pnpm exec site-kernel run rfc.index.generate --write` to generate it.",
+        });
+        const result = { command: "rfc.index.validate", status: "fail", violations };
+        if (outputFormat === "pretty") {
+            logger.error("RFC-IDX-01: docs/rfcs/index.yaml not found.");
+        }
+        return {
+            data: result,
+            exitCode: 1,
+            summary: "1 error(s) found",
+        };
+    }
+    // RFC-IDX-02: unparseable YAML
+    let parsed;
+    try {
+        parsed = yamlParse(indexContent);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        violations.push({
+            rule: "RFC-IDX-02",
+            message: `Failed to parse docs/rfcs/index.yaml: ${msg}`,
+        });
+        const result = { command: "rfc.index.validate", status: "fail", violations };
+        if (outputFormat === "pretty") {
+            logger.error(`RFC-IDX-02: Failed to parse index.yaml: ${msg}`);
+        }
+        return {
+            data: result,
+            exitCode: 1,
+            summary: "1 error(s) found",
+        };
+    }
+    // RFC-IDX-03: count mismatch
+    const indexCount = Array.isArray(parsed?.entries) ? parsed.entries.length : 0;
+    const allFiles = await listRfcFiles(rfcDirPath);
+    const fileCount = allFiles.length;
+    if (indexCount !== fileCount) {
+        violations.push({
+            rule: "RFC-IDX-03",
+            message: `Index entry count (${indexCount}) does not match RFC file count (${fileCount}). Run \`pnpm exec site-kernel run rfc.index.generate --write\` to refresh.`,
+        });
+    }
+    const hasErrors = violations.length > 0;
+    const resultStatus = hasErrors ? "fail" : "pass";
+    const result = { command: "rfc.index.validate", status: resultStatus, violations };
+    if (outputFormat === "pretty") {
+        if (hasErrors) {
+            for (const v of violations) {
+                logger.error(`[${v.rule}] ${v.message}`);
+            }
+            logger.error(`${violations.length} error(s) found`);
+        }
+        else {
+            logger.success(`Index valid — ${indexCount} entries match ${fileCount} RFC files.`);
+        }
+    }
+    return {
+        data: result,
+        exitCode: hasErrors ? 1 : 0,
+        summary: hasErrors
+            ? `${violations.length} error(s) found`
+            : `Index valid — ${indexCount} entries match ${fileCount} RFC files`,
+    };
+}
+//# sourceMappingURL=index-graph.js.map

package/dist/os/rfc/handlers/index-graph.js.map

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

package/dist/os/rfc/handlers/lifecycle.d.ts

@@ -0,0 +1,13 @@
+import type { CommandRegistry } from "../../../src/types.ts";
+import { type ParsedRfc } from "../frontmatter-io.ts";
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import type { RfcCommandLifecycleViolation, RfcCommandLifecycleValidationResult } from "../types.ts";
+export declare function collectRfcCommandLifecycleViolations(workspaceRoot: string, filesToValidate?: string[], preParsed?: Map<string, {
+    fileName: string;
+    parsed: ParsedRfc;
+}>, commandRegistry?: CommandRegistry): Promise<{
+    checkedCount: number;
+    violations: RfcCommandLifecycleViolation[];
+}>;
+export declare function runRfcCommandLifecycleValidate(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<RfcCommandLifecycleValidationResult>>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/os/rfc/handlers/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../os/rfc/handlers/lifecycle.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAEV,4BAA4B,EAC5B,mCAAmC,EACpC,MAAM,aAAa,CAAC;AAerB,wBAAsB,oCAAoC,CACxD,aAAa,EAAE,MAAM,EACrB,eAAe,CAAC,EAAE,MAAM,EAAE,EAC1B,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC,EAChE,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,4BAA4B,EAAE,CAAA;CAAE,CAAC,CA8H/E;AAED,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,mCAAmC,CAAC,CAAC,CAyDlE"}