forgecraft-mcp 1.7.0 → 1.8.0

package/dist/tools/gate-genesis.js.map

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

package/dist/tools/learning-graph.d.ts

@@ -0,0 +1,31 @@
+/**
+ * learning-graph.csv emission — the harness as a literal Compact Knowledge Graph.
+ *
+ * Serializes the project's knowledge structure as a learning graph per
+ * Yarmoluk & McCreary's Definition 1: G = (C, E, T, τ) in the 4-column CSV
+ * schema `ConceptID,ConceptLabel,Dependencies,TaxonomyID` (Dependencies =
+ * pipe-delimited prerequisite ConceptIDs; the pair (C,E) must be a DAG).
+ *
+ * Concepts are the harness artifacts; edges encode reading order ("understand
+ * X before Y"): the routing table, the doc obligation table, and @gs-links.
+ * Empirical basis: the KX experiment (experiments/kx) measured CNT-routed
+ * retrieval at RDS 1.7–5.6× over dump/search baselines — the CKG economics.
+ *
+ * This is a DERIVED artifact (Living Documentation): regenerated on every
+ * setup/refresh, never hand-edited. It is machine data, not session prose —
+ * it is not part of the routed CNT and does not count against the harness budget.
+ */
+export interface LearningGraphResult {
+    readonly written: boolean;
+    readonly concepts: number;
+    readonly edges: number;
+}
+/**
+ * Emit docs/learning-graph.csv from the project's harness artifacts.
+ * Always regenerates (derived artifact). Returns counts for reporting.
+ *
+ * @param projectDir - Project root
+ * @returns written flag + concept/edge counts (written=false when no harness)
+ */
+export declare function emitLearningGraph(projectDir: string): LearningGraphResult;
+//# sourceMappingURL=learning-graph.d.ts.map

package/dist/tools/learning-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-graph.d.ts","sourceRoot":"","sources":["../../src/tools/learning-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAsBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,CAmOzE"}

package/dist/tools/learning-graph.js

@@ -0,0 +1,266 @@
+/**
+ * learning-graph.csv emission — the harness as a literal Compact Knowledge Graph.
+ *
+ * Serializes the project's knowledge structure as a learning graph per
+ * Yarmoluk & McCreary's Definition 1: G = (C, E, T, τ) in the 4-column CSV
+ * schema `ConceptID,ConceptLabel,Dependencies,TaxonomyID` (Dependencies =
+ * pipe-delimited prerequisite ConceptIDs; the pair (C,E) must be a DAG).
+ *
+ * Concepts are the harness artifacts; edges encode reading order ("understand
+ * X before Y"): the routing table, the doc obligation table, and @gs-links.
+ * Empirical basis: the KX experiment (experiments/kx) measured CNT-routed
+ * retrieval at RDS 1.7–5.6× over dump/search baselines — the CKG economics.
+ *
+ * This is a DERIVED artifact (Living Documentation): regenerated on every
+ * setup/refresh, never hand-edited. It is machine data, not session prose —
+ * it is not part of the routed CNT and does not count against the harness budget.
+ */
+import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
+import { join, relative } from "path";
+/** Taxonomy categories (τ): coarse artifact classes, per LG convention (≤16). */
+const TAXONOMY = {
+    CNT: "CNT", // navigation tree branches
+    DOC: "DOC", // core documents (PRD, TechSpec, status, manifest)
+    ARCH: "ARCH", // architecture branch docs
+    ADR: "ADR", // decision records
+    UC: "UC", // use cases
+    SPEC: "SPEC", // spec decision records
+    GATE: "GATE", // quality gates
+    STD: "STD", // domain standards
+    CODE: "CODE", // source files carrying @gs-links
+};
+/**
+ * Emit docs/learning-graph.csv from the project's harness artifacts.
+ * Always regenerates (derived artifact). Returns counts for reporting.
+ *
+ * @param projectDir - Project root
+ * @returns written flag + concept/edge counts (written=false when no harness)
+ */
+export function emitLearningGraph(projectDir) {
+    const rootMd = join(projectDir, "CLAUDE.md");
+    if (!existsSync(rootMd))
+        return { written: false, concepts: 0, edges: 0 };
+    const nodes = [];
+    const byLabel = new Map();
+    let nextId = 1;
+    const addNode = (label, taxonomy) => {
+        const clean = sanitizeLabel(label);
+        const existing = byLabel.get(clean);
+        if (existing)
+            return existing;
+        const node = {
+            id: nextId++,
+            label: clean,
+            taxonomy,
+            deps: new Set(),
+        };
+        nodes.push(node);
+        byLabel.set(clean, node);
+        return node;
+    };
+    const addEdge = (from, prerequisite) => {
+        // Self-references and forward cycles are excluded by construction:
+        // prerequisites are always added before their dependents, and we never
+        // point a node at itself.
+        if (from.id !== prerequisite.id)
+            from.deps.add(prerequisite.id);
+    };
+    // ── Foundational layer: CNT root + always-load ──────────────────────
+    const root = addNode("CLAUDE.md (CNT root)", TAXONOMY.CNT);
+    const constitution = maybeNode(projectDir, ".claude/constitution.md", "Constitution", TAXONOMY.CNT, addNode);
+    const corrections = maybeNode(projectDir, ".claude/corrections.md", "Corrections Log", TAXONOMY.CNT, addNode);
+    for (const n of [constitution, corrections])
+        if (n)
+            addEdge(n, root);
+    // CNT branches depend on the root (read root first, then descend)
+    const lifecycle = maybeNode(projectDir, ".claude/lifecycle.md", "Lifecycle", TAXONOMY.CNT, addNode);
+    const routesCode = maybeNode(projectDir, ".claude/routes/code.md", "Code Routes", TAXONOMY.CNT, addNode);
+    const routesDocs = maybeNode(projectDir, ".claude/routes/docs.md", "Docs Routes", TAXONOMY.CNT, addNode);
+    for (const n of [lifecycle, routesCode, routesDocs])
+        if (n)
+            addEdge(n, root);
+    // ── Core documents ───────────────────────────────────────────────────
+    const prd = maybeNode(projectDir, "docs/PRD.md", "PRD", TAXONOMY.DOC, addNode);
+    const techSpec = maybeNode(projectDir, "docs/TechSpec.md", "TechSpec", TAXONOMY.DOC, addNode);
+    const status = maybeNode(projectDir, "docs/status.md", "Status", TAXONOMY.DOC, addNode);
+    const manifest = maybeNode(projectDir, "docs/manifest.yaml", "Docs Manifest", TAXONOMY.DOC, addNode);
+    if (techSpec && prd)
+        addEdge(techSpec, prd); // architecture derives from spec
+    if (status && root)
+        addEdge(status, root);
+    if (manifest && root)
+        addEdge(manifest, root);
+    // ── Architecture branch docs (depend on TechSpec when present) ──────
+    const archDir = join(projectDir, "docs", "architecture");
+    if (existsSync(archDir)) {
+        for (const f of readdirSync(archDir).filter((x) => x.endsWith(".md"))) {
+            const n = addNode(`Architecture: ${f.replace(/\.md$/, "")}`, TAXONOMY.ARCH);
+            if (techSpec)
+                addEdge(n, techSpec);
+            else if (prd)
+                addEdge(n, prd);
+        }
+    }
+    // ── ADRs (decisions derive from the spec context) ───────────────────
+    const adrNodesByFile = new Map();
+    for (const adrDir of ["docs/adrs/active", "docs/adrs"]) {
+        const dir = join(projectDir, ...adrDir.split("/"));
+        if (!existsSync(dir))
+            continue;
+        for (const f of readdirSync(dir).filter((x) => /^ADR-.*\.md$/i.test(x) || /^\d{4}-.*\.md$/.test(x))) {
+            const label = `ADR: ${f.replace(/\.md$/, "")}`;
+            if (byLabel.has(sanitizeLabel(label)))
+                continue;
+            const n = addNode(label, TAXONOMY.ADR);
+            adrNodesByFile.set(`${adrDir}/${f}`.replace("docs/adrs/active", "docs/adrs"), n);
+            adrNodesByFile.set(`docs/adrs/${f}`, n);
+            if (prd)
+                addEdge(n, prd);
+        }
+    }
+    // ── Use cases (behavioral contracts derive from the PRD) ────────────
+    const ucNodesById = new Map();
+    const ucFile = join(projectDir, "docs", "use-cases.md");
+    if (existsSync(ucFile)) {
+        for (const line of readFileSync(ucFile, "utf-8").split("\n")) {
+            const m = /^## (UC-\d+):\s*(.+)$/.exec(line.trim());
+            if (!m)
+                continue;
+            const n = addNode(`${m[1]}: ${m[2]}`, TAXONOMY.UC);
+            ucNodesById.set(m[1], n);
+            if (prd)
+                addEdge(n, prd);
+        }
+    }
+    // ── Spec decision records (derive from PRD + their use cases) ───────
+    const specNodesByFile = new Map();
+    const specsDir = join(projectDir, "docs", "specs");
+    if (existsSync(specsDir)) {
+        for (const f of readdirSync(specsDir).filter((x) => x.endsWith(".md") && x !== "README.md")) {
+            const n = addNode(`Spec: ${f.replace(/\.md$/, "")}`, TAXONOMY.SPEC);
+            specNodesByFile.set(`docs/specs/${f}`, n);
+            if (prd)
+                addEdge(n, prd);
+        }
+    }
+    // ── Quality gates (mandated by the constitution) ────────────────────
+    for (const gatesSub of ["active", "registry"]) {
+        const base = join(projectDir, ".forgecraft", "gates", gatesSub);
+        if (!existsSync(base))
+            continue;
+        walkYaml(base, (full) => {
+            const rel = relative(base, full).split("\\").join("/");
+            const id = rel
+                .replace(/\.ya?ml$/, "")
+                .split("/")
+                .pop();
+            const label = `Gate: ${id}`;
+            if (byLabel.has(sanitizeLabel(label)))
+                return;
+            const n = addNode(label, TAXONOMY.GATE);
+            if (constitution)
+                addEdge(n, constitution);
+            else
+                addEdge(n, root);
+        });
+    }
+    // ── Standards (expand the constitution per domain) ──────────────────
+    const stdDir = join(projectDir, ".claude", "standards");
+    if (existsSync(stdDir)) {
+        for (const f of readdirSync(stdDir).filter((x) => x.endsWith(".md"))) {
+            const n = addNode(`Standards: ${f.replace(/\.md$/, "")}`, TAXONOMY.STD);
+            if (constitution)
+                addEdge(n, constitution);
+            else
+                addEdge(n, root);
+        }
+    }
+    // ── @gs-links: code nodes depend on their governing documents ───────
+    const srcDir = join(projectDir, "src");
+    if (existsSync(srcDir)) {
+        walkSource(srcDir, (full) => {
+            const head = readFileSync(full, "utf-8").slice(0, 2000);
+            const m = /@gs-links:\s*(.+)/.exec(head);
+            if (!m)
+                return;
+            const rel = relative(projectDir, full).split("\\").join("/");
+            const codeNode = addNode(`Code: ${rel}`, TAXONOMY.CODE);
+            for (const linkRaw of m[1].split(",")) {
+                const link = linkRaw
+                    .trim()
+                    .replace(/\*\/?\s*$/, "")
+                    .trim();
+                const target = specNodesByFile.get(link) ??
+                    adrNodesByFile.get(link) ??
+                    resolveLooseLink(link, ucNodesById, byLabel);
+                if (target)
+                    addEdge(codeNode, target);
+            }
+            if (codeNode.deps.size === 0 && routesCode)
+                addEdge(codeNode, routesCode);
+        });
+    }
+    // ── Serialize (4-column CSV per Definition 1) ────────────────────────
+    const lines = ["ConceptID,ConceptLabel,Dependencies,TaxonomyID"];
+    let edgeCount = 0;
+    for (const n of nodes) {
+        const deps = [...n.deps].sort((a, b) => a - b).join("|");
+        edgeCount += n.deps.size;
+        lines.push(`${n.id},${csvField(n.label)},${deps},${n.taxonomy}`);
+    }
+    const outPath = join(projectDir, "docs", "learning-graph.csv");
+    writeFileSync(outPath, lines.join("\n") + "\n", "utf-8");
+    return { written: true, concepts: nodes.length, edges: edgeCount };
+}
+// ── Helpers ───────────────────────────────────────────────────────────
+function maybeNode(projectDir, rel, label, taxonomy, addNode) {
+    return existsSync(join(projectDir, ...rel.split("/")))
+        ? addNode(label, taxonomy)
+        : null;
+}
+function walkYaml(dir, visit) {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, e.name);
+        if (e.isDirectory())
+            walkYaml(full, visit);
+        else if (/\.ya?ml$/.test(e.name))
+            visit(full);
+    }
+}
+function walkSource(dir, visit) {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, e.name);
+        if (e.isDirectory())
+            walkSource(full, visit);
+        else if (/\.(ts|tsx|js|py)$/.test(e.name) &&
+            !/\.test\.|\.spec\./.test(e.name))
+            visit(full);
+    }
+}
+function resolveLooseLink(link, ucNodesById, byLabel) {
+    const uc = /UC-\d+/.exec(link);
+    if (uc)
+        return ucNodesById.get(uc[0]);
+    if (/use-cases\.md/.test(link)) {
+        // generic use-cases link → first UC node if any (closest stable anchor)
+        return ucNodesById.values().next().value;
+    }
+    const adr = /ADR-[\w-]+/.exec(link);
+    if (adr) {
+        for (const [label, node] of byLabel) {
+            if (label.includes(adr[0]))
+                return node;
+        }
+    }
+    return undefined;
+}
+function sanitizeLabel(label) {
+    return label
+        .replace(/[,\r\n"]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function csvField(s) {
+    return /[,"]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+//# sourceMappingURL=learning-graph.js.map

package/dist/tools/learning-graph.js.map

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

package/dist/tools/setup-artifact-writers.d.ts

@@ -40,7 +40,7 @@ export declare function initGitRepo(projectDir: string): string;
  * @param brownfield - Whether this is a brownfield project
  * @returns True if the file was written or updated
  */
-export declare function writeForgeYaml(projectDir: string, projectName: string, tags: string[], decisions: CascadeDecision[], sensitiveData?: boolean, brownfield?: boolean): boolean;
+export declare function writeForgeYaml(projectDir: string, projectName: string, tags: string[], decisions: CascadeDecision[], sensitiveData?: boolean, brownfield?: boolean, language?: string): boolean;
 /**
  * If forgecraft.yaml has an experiment block with an id but no group,
  * sets experiment.group = 'gs'.
@@ -69,15 +69,17 @@ export interface UseCaseInput {
 }
 /**
  * Write docs/PRD.md using AI-extracted fields when available.
+ * When AI fields are absent but a raw spec exists (CLI-only path, no AI in
+ * the loop), the source spec is embedded so its content is never lost.
  * Never overwrites an existing PRD.
  *
  * @param projectDir - Project root
  * @param projectName - Project name for the PRD title
  * @param aiFields - AI-extracted problem, users, criteria
- * @param _specContent - Raw spec text (reserved for future use)
+ * @param specContent - Raw spec text — embedded when AI fields are absent
  * @returns True if a new PRD was written
  */
-export declare function writePrd(projectDir: string, projectName: string, aiFields: AiExtractedFields, _specContent: string | null): boolean;
+export declare function writePrd(projectDir: string, projectName: string, aiFields: AiExtractedFields, specContent: string | null): boolean;
 /**
  * Write docs/use-cases.md from structured spec-derived use cases when available,
  * or from AI-extracted fields as a fallback. Never overwrites an existing use-cases.md.
@@ -155,6 +157,16 @@ export declare function writeProjectManifest(projectDir: string, projectName: st
  * @returns True if the file was written
  */
 export declare function writeStatusMd(projectDir: string, projectName: string): boolean;
+/**
+ * Write docs/architecture/ CNT branch stubs — four scoped nodes for
+ * layers, modules, data-model, and integrations.
+ * Never overwrites existing files.
+ *
+ * @param projectDir - Project root
+ * @param projectName - Project name
+ * @returns Array of relative paths written
+ */
+export declare function writeArchitectureCntStubs(projectDir: string, projectName: string): string[];
 /**
  * Load cascade decisions from forgecraft.yaml (convenience re-used in writers).
  */

package/dist/tools/setup-artifact-writers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-artifact-writers.d.ts","sourceRoot":"","sources":["../../src/tools/setup-artifact-writers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setup-artifact-writers.d.ts","sourceRoot":"","sources":["../../src/tools/setup-artifact-writers.ts"],"names":[],"mappings":"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"}

package/dist/tools/setup-artifact-writers.js

@@ -69,7 +69,7 @@ export function initGitRepo(projectDir) {
  * @param brownfield - Whether this is a brownfield project
  * @returns True if the file was written or updated
  */
-export function writeForgeYaml(projectDir, projectName, tags, decisions, sensitiveData, brownfield) {
+export function writeForgeYaml(projectDir, projectName, tags, decisions, sensitiveData, brownfield, language) {
     const yamlPath = join(projectDir, "forgecraft.yaml");
     let config;
     if (existsSync(yamlPath)) {
@@ -82,6 +82,8 @@ export function writeForgeYaml(projectDir, projectName, tags, decisions, sensiti
     }
     else {
         config = { projectName, tags: tags.length > 0 ? tags : ["UNIVERSAL"] };
+        if (language && language !== "typescript")
+            config["language"] = language;
         if (sensitiveData !== undefined)
             config["sensitiveData"] = sensitiveData;
         if (brownfield === true)
@@ -127,23 +129,25 @@ export function setExperimentGroupIfMissing(projectDir) {
 }
 /**
  * Write docs/PRD.md using AI-extracted fields when available.
+ * When AI fields are absent but a raw spec exists (CLI-only path, no AI in
+ * the loop), the source spec is embedded so its content is never lost.
  * Never overwrites an existing PRD.
  *
  * @param projectDir - Project root
  * @param projectName - Project name for the PRD title
  * @param aiFields - AI-extracted problem, users, criteria
- * @param _specContent - Raw spec text (reserved for future use)
+ * @param specContent - Raw spec text — embedded when AI fields are absent
  * @returns True if a new PRD was written
  */
-export function writePrd(projectDir, projectName, aiFields, _specContent) {
+export function writePrd(projectDir, projectName, aiFields, specContent) {
     const prdPath = join(projectDir, "docs", "PRD.md");
     if (existsSync(prdPath))
         return false;
     mkdirSync(join(projectDir, "docs"), { recursive: true });
-    writeFileSync(prdPath, buildPrdContent(projectName, aiFields), "utf-8");
+    writeFileSync(prdPath, buildPrdContent(projectName, aiFields, specContent), "utf-8");
     return true;
 }
-function buildPrdContent(projectName, aiFields) {
+function buildPrdContent(projectName, aiFields, specContent) {
     const fill = (placeholder) => `<!-- FILL: ${placeholder} -->`;
     const listOrFill = (csv, placeholder) => csv
         ? csv
@@ -151,14 +155,24 @@ function buildPrdContent(projectName, aiFields) {
             .map((s) => `- ${s.trim()}`)
             .join("\n")
         : fill(placeholder);
-    return [
+    const sections = [
         `# ${projectName}\n`,
         `## Problem\n\n${aiFields.problemStatement ?? fill("describe the problem this project solves")}\n`,
         `## Users\n\n${listOrFill(aiFields.primaryUsers, "list the target users or personas")}\n`,
         `## Success Criteria\n\n${listOrFill(aiFields.successCriteria, "define measurable success criteria")}\n`,
         `## Components\n\n${fill("list the major components or modules")}\n`,
         `## External Systems\n\n${fill("list external APIs, services, or integrations")}\n`,
-    ].join("\n");
+    ];
+    // No AI extraction happened but the user provided a spec — preserve it.
+    // The sections above stay as FILL markers; the source is the ground truth
+    // the AI (or human) extracts from on the next pass.
+    const noAiFields = !aiFields.problemStatement &&
+        !aiFields.primaryUsers &&
+        !aiFields.successCriteria;
+    if (noAiFields && specContent?.trim()) {
+        sections.push(`## Source Specification\n`, `> Original spec provided at setup. Extract the sections above from this`, `> content, then remove this section once the PRD is fully derived.\n`, specContent.trim(), ``);
+    }
+    return sections.join("\n");
 }
 /**
  * Write docs/use-cases.md from structured spec-derived use cases when available,
@@ -933,9 +947,9 @@ export function writeStatusMd(projectDir, projectName) {
         `> Update this file at the end of each session. The Session Loop Invariant in CLAUDE.md`,
         `> references this file for any unresolved items.`,
         ``,
-        `## Current State`,
+        `## Completed (this session)`,
         ``,
-        `<!-- FILL: brief 1-2 sentence description of the current project state -->`,
+        `<!-- FILL: what was finished in the most recent session -->`,
         ``,
         `## In Progress`,
         ``,
@@ -945,17 +959,139 @@ export function writeStatusMd(projectDir, projectName) {
         ``,
         `<!-- FILL: first roadmap item or pending task — be specific enough to resume without re-reading everything -->`,
         ``,
-        `## Open Issues / Blockers`,
+        `## Decisions Made (this session)`,
         ``,
-        `<!-- FILL: known issues, blockers, or technical debt that need resolution -->`,
+        `<!-- FILL: key decisions made — link to ADRs where they exist -->`,
         ``,
-        `## Recent Decisions`,
+        `## Blockers / Dependencies`,
         ``,
-        `<!-- FILL: key decisions made recently — link to ADRs where they exist -->`,
+        `<!-- FILL: known blockers, open questions, or external dependencies -->`,
     ].join("\n");
     writeFileSync(statusPath, content, "utf-8");
     return true;
 }
+// ── Architecture CNT stub writer ─────────────────────────────────────
+/**
+ * Write docs/architecture/ CNT branch stubs — four scoped nodes for
+ * layers, modules, data-model, and integrations.
+ * Never overwrites existing files.
+ *
+ * @param projectDir - Project root
+ * @param projectName - Project name
+ * @returns Array of relative paths written
+ */
+export function writeArchitectureCntStubs(projectDir, projectName) {
+    const archDir = join(projectDir, "docs", "architecture");
+    mkdirSync(archDir, { recursive: true });
+    const written = [];
+    const stubs = [
+        {
+            file: "layers.md",
+            content: [
+                `# Architecture: Layer Diagram & Boundary Rules`,
+                ``,
+                `> CNT node — read when: changing or reviewing layer structure, adding a new module, or diagnosing layer violations.`,
+                ``,
+                `## Layers`,
+                ``,
+                `<!-- FILL: document the layer stack (e.g. Entry → Dispatch → Handlers → Domain → Adapters) -->`,
+                ``,
+                `## Boundary Rules`,
+                ``,
+                `| From | To | Allowed | Rule |`,
+                `|---|---|---|---|`,
+                `| <!-- FILL --> | <!-- FILL --> | ✅/❌ | <!-- FILL --> |`,
+                ``,
+                `## Key Invariants`,
+                ``,
+                `<!-- FILL: list the non-negotiable structural invariants (e.g. "no circular imports", "domain has zero external imports") -->`,
+            ].join("\n"),
+        },
+        {
+            file: "modules.md",
+            content: [
+                `# Architecture: Module Registry`,
+                ``,
+                `> CNT node — read when: adding a new module, understanding file ownership, or debugging an unexpected dependency.`,
+                ``,
+                `## Core Modules`,
+                ``,
+                `| Module | File | Owns | Does NOT own |`,
+                `|---|---|---|---|`,
+                `| <!-- FILL: module name --> | <!-- FILL: path --> | <!-- FILL: responsibility --> | <!-- FILL: what it delegates --> |`,
+                ``,
+                `## Shared Utilities`,
+                ``,
+                `<!-- FILL: list shared utility modules and their purpose -->`,
+                ``,
+                `## Addition Protocol`,
+                ``,
+                `When adding a new module: <!-- FILL: define the decision tree for where new code goes -->`,
+            ].join("\n"),
+        },
+        {
+            file: "data-model.md",
+            content: [
+                `# Architecture: Data Model & Schema`,
+                ``,
+                `> CNT node — read when: changing the data model, adding entities, modifying schema, or updating the ERD.`,
+                ``,
+                `## Core Entities`,
+                ``,
+                `<!-- FILL: describe primary entities with their fields and invariants -->`,
+                ``,
+                `## Entity Relationships`,
+                ``,
+                `\`\`\`mermaid`,
+                `erDiagram`,
+                `    %% FILL: replace with actual entities and relationships`,
+                `    ENTITY_A ||--o{ ENTITY_B : "has"`,
+                `\`\`\``,
+                ``,
+                `## Schema Notes`,
+                ``,
+                `<!-- FILL: naming conventions, migration strategy, DB / persistence approach -->`,
+                ``,
+                `## DB / State`,
+                ``,
+                `<!-- FILL: where does state live? (DB, file system, in-memory, external service) -->`,
+                `<!-- If using a DB: describe the migration strategy and any ORM/query builder choices -->`,
+            ].join("\n"),
+        },
+        {
+            file: "integrations.md",
+            content: [
+                `# Architecture: External Integrations`,
+                ``,
+                `> CNT node — read when: adding a new external dependency, changing a protocol, or understanding network access.`,
+                ``,
+                `## Integration Map`,
+                ``,
+                `| Integration | Direction | When | Protocol |`,
+                `|---|---|---|---|`,
+                `| <!-- FILL: name --> | Inbound/Outbound | <!-- FILL: when --> | <!-- FILL: HTTP/gRPC/stdio/etc --> |`,
+                ``,
+                `## File System Contract`,
+                ``,
+                `<!-- FILL: what paths does this project read/write? what is out of bounds? -->`,
+                ``,
+                `## Network Policy`,
+                ``,
+                `<!-- FILL: which operations require network access? which must work offline? -->`,
+            ].join("\n"),
+        },
+    ];
+    for (const stub of stubs) {
+        const filePath = join(archDir, stub.file);
+        if (!existsSync(filePath)) {
+            writeFileSync(filePath, stub.content, "utf-8");
+            written.push(`docs/architecture/${stub.file}`);
+        }
+    }
+    // Suppress unused variable warning
+    void projectName;
+    return written;
+}
 // ── Load cascade decisions ────────────────────────────────────────────
 /**
  * Load cascade decisions from forgecraft.yaml (convenience re-used in writers).