forma-arch 0.2.0 → 0.4.0

package/README.md

@@ -25,10 +25,33 @@ npx forma-arch <command>        # or: npm i -D forma-arch
 | Command | What it does |
 |---|---|
 | `forma init` | Seed `docs/architecture/c4-topology.json` from your source dirs (best-effort; then curate) |
-| `forma gen` | Walk `src/` leaves + derive container edges from cross-references to exported symbol names → `c4-model.json` |
+| `forma gen` | Walk `src/` leaves + derive container edges from cross-references; fill box text from docstrings/READMEs; group flat containers into components → `c4-model.json` |
 | `forma check` | Deterministic drift check — **fails if the model no longer matches the code** |
-| `forma doc` | Project the arc42 scaffold (`ARCHITECTURE.scaffold.md`) from the model |
+| `forma doc` | Project the arc42 scaffold (`ARCHITECTURE.scaffold.md`), or `--attach <file>` to inject a governed block into an existing doc |
 | `forma serve` | Open the live explorer at `http://localhost:4173` |
+| `forma verify` | Refresh status from live GitHub issues through your `gh` CLI — the **only** networked command |
+
+**Box text comes from your docs.** `gen` fills each box with the module's docstring (Python `"""…"""`, JS/TS leading block), else the directory `README.md`, else a mapped arc42 section — so the explorer shows meaning, not a list of symbols. On a flat directory of many `foo_*` files it also synthesizes a **component** layer, described from its children's docs (`--no-cluster` to disable; `--cluster-min <n>` = leaves before a container is clustered, default 8; `--group-min <n>` = files sharing a prefix before they become a component, default 3).
+
+**Programme state is curated, not guessed.** Code shows what exists, never how far along it is. Drop a `docs/architecture/c4-status.json` (`--status <path>` to move it) and `gen` decorates nodes by id with `status2`, `completion`, `statusWord`, `current`, `target`, `verify`, `issues` — never `func`, which belongs to the docs. `gen` validates the *form* (ids resolve, fields known, enums and issue numbers well-shaped) and never the prose; `forma check` fails if the overlay decorates a node the model no longer has.
+
+```json
+{ "nodes": { "engine": { "status2": "in-progress", "completion": 60, "statusWord": "v2 in progress",
+  "current": "Live on ACA: RAG + citations. Hardening this week.",
+  "target": "Multi-surface substrate with client-ready output.",
+  "verify": { "source": "ADR-040 on main" }, "issues": ["#534"] } } }
+```
+
+**Curated state, verified against reality.** `forma verify` asks your `gh` CLI for the state of every issue the model references (`--gh-repo owner/repo`, or `meta.ghRepo` in the topology), marks the nodes whose issues are closed as done, and prefixes their `current` with dated evidence. It touches state, never structure, and re-running it never stacks the evidence. It is opt-in and separate on purpose: `gen` and `check` never open a socket. In the served viewer, **RE-VERIFY** re-reads the model without losing your level, layout or mode.
+
+**One source of truth.** `forma doc --attach docs/architecture/arc42.md` injects the generated diagrams/tables between `<!-- forma:begin -->` / `<!-- forma:end -->` markers in your existing doc; your prose lives outside them, and `forma check` fails if that block drifts. Attached files are recorded in `source.attachedDocs`, so the gate governs **every** doc you attach — not just the model's `docPath`; deleting the markers (or the file) from a registered doc fails the check rather than quietly un-governing it. That registry lives in `c4-model.json`, so **commit the model** — a lost model takes the registry with it. Where a repo lacks docs, `forma gen --enrich` can fill the remaining box holes with an LLM — opt-in, cached, never on the deterministic gate:
+
+| `--enricher` | Use it when | Network |
+|---|---|---|
+| `agent` | **An agent is driving forma.** Writes `enrich-plan.json` with the holes; the agent writes the sentences (reading the sources if it wants) and `gen --enrich-apply <file>` applies them with the same cache and provenance. | none |
+| `anthropic` (default) | Headless / CI, with `ANTHROPIC_API_KEY`. | REST |
+| `openai` | Same, with `OPENAI_API_KEY`. | REST |
+| `ollama` | Sensitive repos: a local model, nothing leaves the machine. | localhost |
 
 ## How it fits together
 
@@ -55,9 +78,10 @@ The viewer is a live C4 map, not a static picture:
 
 - **Click any box** to read its explanation — what it does, current state, target, verification source — at *every* level, from context down to a leaf.
 - **Double-click a box** (or its `[+] DRILL`) to descend into it; **BACK**, the breadcrumb, or `ESC` climb back out.
-- **Drag boxes** to lay out the view your way; **RESET LAYOUT** restores the auto-arrangement.
-- **Hover an arrow** to reveal its relationship label.
-- **PRINT / EXPORT** to SVG or PNG for docs and slides.
+- **Drag boxes** to lay out the view your way; **RESET LAYOUT** restores the arrangement (your curated hints if the topology has them, the automatic one otherwise). To keep a layout, drag it, pick **Export layout JSON**, and paste the result under `"layout"` in the topology — `gen` carries it into `meta.layout` and the viewer pins those boxes, auto-arranging everything else clear of them.
+- **Arrow labels** are painted on the diagram while the level stays readable (≤14 arrows) and turn off above that; **LABELS** forces them on or off, and hovering an arrow always reveals its label.
+- **PRINT / EXPORT** to SVG or PNG for docs and slides — exported arrows carry their labels.
+- The breadcrumb names the C4 level you are on (`C4-L1 · CONTEXT` → `C4-L3 · COMPONENTS`).
 
 ## Skins
 

package/bin/forma.mjs

@@ -12,7 +12,7 @@ const LIB = join(HERE, '..', 'lib')
 const cmd = process.argv[2]
 const rest = process.argv.slice(3)
 
-const MAP = { init: 'init.mjs', gen: 'gen.mjs', check: 'check.mjs', doc: 'doc.mjs', serve: 'serve.mjs' }
+const MAP = { init: 'init.mjs', gen: 'gen.mjs', check: 'check.mjs', doc: 'doc.mjs', serve: 'serve.mjs', verify: 'verify.mjs' }
 
 if (cmd === '-v' || cmd === '--version') {
   const pkg = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf-8'))
@@ -28,6 +28,7 @@ Usage: forma <command> [--repo <path>]
   check   deterministic drift check — fails if the model no longer matches the code
   doc     project the arc42 scaffold (ARCHITECTURE.scaffold.md) from the model
   serve   open the live explorer at http://localhost:4173
+  verify  refresh status from live GitHub issues via your gh CLI (the only networked command)
 
 The file contract is lib/schema/c4-model.schema.json. Enrichment (curate the topology, write the
 arc42 prose) is model-agnostic — any agent edits the same JSON/Markdown.`)

package/lib/check.mjs

@@ -6,6 +6,9 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { containerOf } from './cluster.mjs'
+import { renderBlock, extractBetween, norm } from './render.mjs'
+import { descInputHash } from './enrich.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
@@ -20,6 +23,7 @@ if (!existsSync(MODEL)) { console.error('[check-c4] FAIL: model missing (no SKIP
 if (!existsSync(TOPO)) { console.error('[check-c4] FAIL: topology missing: ' + TOPO); process.exit(1) }
 const model = JSON.parse(readFileSync(MODEL, 'utf-8'))
 const topo = JSON.parse(readFileSync(TOPO, 'utf-8'))
+const byId = new Map((model.nodes || []).map((n) => [n.id, n]))
 
 // 1) schemaVersion present + basic shape
 if (!/^\d+\.\d+\.\d+$/.test(model.schemaVersion || '')) fail('missing/invalid schemaVersion')
@@ -36,7 +40,7 @@ function walk(spec) {
 }
 for (const spec of topo.leafSources) {
   const live = walk(spec).length
-  const inModel = model.nodes.filter((n) => n.parent === spec.parent && n.kind === 'leaf' && n.status === 'current').length
+  const inModel = model.nodes.filter((n) => n.kind === 'leaf' && n.status === 'current' && containerOf(n, byId) === spec.parent).length
   if (live === 0) fail(`phantom parent "${spec.parent}": src glob ${spec.dir} matches 0 files`)
   if (live !== inModel) fail(`DRIFT: ${spec.parent} — src has ${live} files, model has ${inModel}. Regenerate c4-model.json.`)
 }
@@ -69,5 +73,48 @@ for (const p of topo.plannedLeaves || []) if (p.sourceMustContain) {
   if (!existsSync(f) || !readFileSync(f, 'utf-8').includes(p.sourceMustContain)) fail(`planned "${p.name}" premise broken in ${p.sourceRef}`)
 }
 
+// 6) attach-mode doc-block freshness — if docPath carries forma markers, the region between them
+// must equal a freshly rendered block. Opt-in: no markers → nothing runs. No LLM, no network.
+// Governs docPath AND every doc registered by `forma doc --attach` (source.attachedDocs): a block
+// injected into a file no gate looks at is the false-green this whole command exists to kill.
+const src = model.source || {}
+const registered = new Set(src.attachedDocs || []) // registry membership PROVES a block was injected
+const governed = [...new Set([src.docPath, ...registered].filter(Boolean))]
+const deregister = 'remove it from source.attachedDocs if the block is gone for good'
+for (const docRel of governed) {
+  if (!existsSync(rp(docRel))) {
+    // docPath may simply never have been attached; a REGISTERED doc that vanished is drift.
+    if (registered.has(docRel)) fail(`DOC BLOCK: ${docRel} is registered in source.attachedDocs but the file is gone — ${deregister}.`)
+    continue
+  }
+  const text = readFileSync(rp(docRel), 'utf-8')
+  const inner = extractBetween(text)
+  if (inner != null) {
+    if (norm(inner) !== norm(renderBlock(model, { repo: REPO }))) fail(`DOC BLOCK DRIFT: ${docRel} forma block is stale — run \`forma doc --attach\`.`)
+  } else if (text.includes('<!-- forma:begin') || text.includes('<!-- forma:end')) {
+    fail(`DOC BLOCK: malformed forma markers in ${docRel} (begin/end mismatch).`)
+  } else if (registered.has(docRel)) {
+    // Both markers deleted: the generated block stopped being governed while its (now frozen)
+    // text keeps shipping to readers. Exactly the false green attachedDocs exists to prevent.
+    fail(`DOC BLOCK: ${docRel} is registered in source.attachedDocs but has no forma markers — re-run \`forma doc --attach\`, or ${deregister}.`)
+  }
+}
+
+// 7) the status overlay decorates nodes by id: an id that no longer resolves is drift (the node was
+// renamed or deleted and the curated state was left behind). Form only — never the prose itself.
+if (src.statusPath && existsSync(rp(src.statusPath))) {
+  let ov = null
+  try { ov = JSON.parse(readFileSync(rp(src.statusPath), 'utf-8')) } catch (e) { fail(`status overlay: ${src.statusPath} is not valid JSON: ${(e && e.message) || e}`) }
+  if (ov) for (const id of Object.keys(ov.nodes || {})) if (!byId.has(id)) fail(`status overlay: "${id}" is not a node in the model — ${src.statusPath} is stale.`)
+}
+
+// SOFT: LLM-enriched prose whose inputs changed is only a reminder, never a gate failure (structure
+// is the gate; enrichment freshness is advisory). check never calls the LLM — it recomputes the hash.
+for (const n of model.nodes || []) {
+  if (n.descSource === 'llm' && n.descInputHash && n.descInputHash !== descInputHash(n, { repo: REPO, byId, containerOf })) {
+    console.warn(`[check-c4] note: enrichment stale for ${n.id} — run \`forma gen --enrich\` to refresh (non-blocking).`)
+  }
+}
+
 if (errs.length) { console.error('[check-c4] FAIL (' + errs.length + '):\n - ' + errs.join('\n - ')); process.exit(1) }
 console.log('[check-c4] OK — model is adherent to src/ (leaves, table count, evidence, planned premises all verified)')

package/lib/cluster.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// cluster.mjs — shared structural helpers for the C4 model. Pure, no side effects at import.
+// containerOf: climb the parent chain to the enclosing CONTAINER. Leaves may be re-parented under
+//   synthetic component nodes (§2), so "the container" is no longer simply node.parent.
+// componentsFor: deterministic prefix-cluster synthesis for flat containers (§2).
+
+const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '') || 'x'
+
+// The id of the nearest container-kind ancestor (or self). byId = Map(id → node).
+export function containerOf(node, byId) {
+  let n = node, guard = 0
+  while (n && n.kind !== 'container' && n.parent && guard++ < 64) n = byId.get(n.parent)
+  return n ? n.id : null
+}
+
+// Group a flat container's leaves by common `foo_*` prefix. Deterministic: sorted group keys.
+// Returns { components: Node[], reparent: Map(leafId → componentId) }. Leftovers stay under the container.
+export function componentsFor(container, leaves, opts = {}) {
+  const groupMin = opts.groupMin || 3
+  const groups = new Map()
+  for (const l of leaves) {
+    const base = String(l.name)
+    const i = base.indexOf('_')
+    if (i <= 0) continue // no prefix (e.g. "health", "version") → stays flat
+    const prefix = base.slice(0, i)
+    if (!groups.has(prefix)) groups.set(prefix, [])
+    groups.get(prefix).push(l)
+  }
+  const keys = [...groups.keys()].filter((k) => groups.get(k).length >= groupMin).sort()
+  if (keys.length === 0) return { components: [], reparent: new Map() }
+  // no structural gain if a single surviving group swallows every leaf
+  const covered = keys.reduce((s, k) => s + groups.get(k).length, 0)
+  if (keys.length === 1 && covered === leaves.length) return { components: [], reparent: new Map() }
+  const components = [], reparent = new Map()
+  for (const k of keys) {
+    const cid = `${container.id}__grp__${slug(k)}`
+    components.push({
+      id: cid, level: 'component', kind: 'component', parent: container.id, name: k,
+      status: 'current', category: container.category || 'container',
+    })
+    for (const l of groups.get(k)) reparent.set(l.id, cid)
+  }
+  return { components, reparent }
+}

package/lib/describe.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// describe.mjs — deterministic description resolver (§1a). Pure parsing, NO network.
+// Fills a node's plain-language `func` from EXISTING docs (curated → docstring → README → arc42),
+// so boxes show MEANING, not a bare filename. A generated string is only the last resort.
+import { readFileSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+
+const norm = (s) => String(s).toLowerCase().trim()
+
+// First non-empty paragraph, markdown/whitespace stripped, capped to the viewer's ~2-line clamp.
+const firstPara = (text) => {
+  let out = ''
+  for (const line of String(text).replace(/\r\n/g, '\n').split('\n')) {
+    const l = line.trim()
+    if (/^#{1,6}\s/.test(l)) continue // skip markdown headings
+    if (!l) { if (out) break; else continue } // blank ends the paragraph (once started)
+    out += (out ? ' ' : '') + l
+  }
+  out = out.replace(/[*_`>]+/g, '').replace(/\s+/g, ' ').trim()
+  return out ? out.slice(0, 240) : null
+}
+
+// ponytail: leading-block heuristic, no AST — a docstring placed AFTER code is missed.
+function moduleDocstring(absPath) {
+  let src; try { src = readFileSync(absPath, 'utf-8') } catch { return null }
+  const body = src.replace(/^/, '').replace(/^#![^\n]*\n/, '')
+  if (/\.py$/i.test(absPath)) {
+    const m = body.match(/^\s*(?:#[^\n]*\n\s*)*(?:r|u|b)?("""|''')([\s\S]*?)\1/i)
+    return m ? firstPara(m[2]) : null
+  }
+  if (/\.(mjs|cjs|js|jsx|ts|tsx|mts|cts)$/i.test(absPath)) {
+    const block = body.match(/^\s*\/\*\*?([\s\S]*?)\*\//)
+    if (block) return firstPara(block[1].replace(/^\s*\*\s?/gm, '').replace(/@\w+/g, ''))
+    const cmt = []
+    for (const l of body.replace(/^\s+/, '').split('\n')) { const t = l.trim(); if (t.startsWith('//')) cmt.push(t.replace(/^\/\/+\s?/, '')); else break }
+    return cmt.length ? firstPara(cmt.join(' ')) : null
+  }
+  return null
+}
+
+function readmeFirstPara(dir, cache) {
+  if (cache.has(dir)) return cache.get(dir)
+  let out = null
+  try { const p = join(dir, 'README.md'); if (existsSync(p)) out = firstPara(readFileSync(p, 'utf-8')) } catch {}
+  cache.set(dir, out)
+  return out
+}
+
+// Map(normalizedHeading → lead paragraph) from the mapped arc42 doc, read once. ponytail: exact
+// normalized-heading match, no fuzzy mapping.
+function buildArc42Index(repo, docPath) {
+  const idx = new Map()
+  if (!docPath) return idx
+  let text; try { text = readFileSync(join(repo, docPath), 'utf-8') } catch { return idx }
+  const parts = text.split(/^#{1,6}\s+(.+)$/m) // [pre, heading, body, heading, body, ...]
+  for (let i = 1; i < parts.length; i += 2) {
+    const lead = firstPara(parts[i + 1] || '')
+    if (parts[i] && lead) idx.set(norm(parts[i]), lead)
+  }
+  return idx
+}
+
+export function makeDescribeCtx({ repo, byId, descriptions, docPath, containerOf }) {
+  return { repo, byId, D: descriptions || {}, containerOf, readmeCache: new Map(), arc42: buildArc42Index(repo, docPath) }
+}
+
+// First hit wins. descSource records provenance for §7 enrichment + debugging.
+export function resolveDescription(node, ctx) {
+  const cont = ctx.containerOf(node, ctx.byId)
+  const stem = String(node.name).replace(/\.\w+$/, '').replace(/ .*/, '')
+  const key = cont ? `${cont}/${stem}` : null
+  if (key && ctx.D[key]) return { func: ctx.D[key], descSource: 'curated' }
+  if (node.description) return { func: node.description, descSource: 'curated' }
+  const pth = (node.evidence || []).find((e) => e.type === 'path')
+  if (pth) {
+    const abs = join(ctx.repo, pth.ref)
+    const ds = moduleDocstring(abs)
+    if (ds) return { func: ds, descSource: 'docstring' }
+    const rd = readmeFirstPara(dirname(abs), ctx.readmeCache)
+    if (rd) return { func: rd, descSource: 'readme' }
+  }
+  const a = ctx.arc42.get(norm(node.name)) || ctx.arc42.get(norm(node.id))
+  if (a) return { func: a, descSource: 'arc42' }
+  if (node.kind === 'leaf') {
+    const cn = (ctx.byId.get(cont) || {}).name || cont || node.parent
+    return { func: `Component of module ${cn}.`, descSource: 'fallback' }
+  }
+  if (node.kind === 'component') return { func: `Groups related files under ${node.name}.`, descSource: 'fallback' }
+  return { func: node.description || '', descSource: 'fallback' }
+}

package/lib/doc.mjs

@@ -4,8 +4,9 @@
 // are filled from the model — so they can never drift from it. The JUDGMENT sections (goals,
 // strategy, decisions, risks) are stubbed with TODO(forma) for a human/agent to write.
 // Output: docs/architecture/ARCHITECTURE.scaffold.md (never overwrites a real ARCHITECTURE.md).
-import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs'
-import { join, relative } from 'node:path'
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { join, relative, isAbsolute } from 'node:path'
+import { renderParts, renderBlock, replaceBetween } from './render.mjs'
 
 const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
 const REPO = arg('--repo', process.cwd())
@@ -13,38 +14,9 @@ const MODEL = arg('--model', join(REPO, 'docs/architecture/c4-model.json'))
 const OUT = arg('--out', join(REPO, 'docs/architecture/ARCHITECTURE.scaffold.md'))
 if (!existsSync(MODEL)) { console.error('[forma doc] model missing: ' + MODEL + ' — run `forma gen` first.'); process.exit(1) }
 const m = JSON.parse(readFileSync(MODEL, 'utf-8'))
-const byId = new Map(m.nodes.map((n) => [n.id, n]))
-const sid = (s) => String(s).replace(/[^A-Za-z0-9_]/g, '_')
-const name = (id) => (byId.get(id) || { name: id }).name
-const C4 = { person: 'Person', system: 'System', external: 'System_Ext', container: 'Container', component: 'Component', store: 'ContainerDb', boundary: 'Container_Boundary', leaf: 'Component' }
-const q = (s) => String(s == null ? '' : s).replace(/"/g, '')
-const el = (n) => `${C4[n.kind] || 'Container'}(${sid(n.id)}, "${q(n.name)}"${n.tech ? `, "${q(n.tech)}"` : ''})`
-const rels = (ids) => m.edges.filter((e) => ids.has(e.from) && ids.has(e.to)).map((e) => `  Rel(${sid(e.from)}, ${sid(e.to)}, "${(e.label || '').replace(/"/g, '')}")`).join('\n')
-
-// context = nodes with no parent
-const ctx = m.nodes.filter((n) => !n.parent)
-const ctxIds = new Set(ctx.map((n) => n.id))
-const contextDiagram = `\`\`\`mermaid\nC4Context\n  title System Context\n${ctx.map((n) => '  ' + el(n)).join('\n')}\n${rels(ctxIds)}\n\`\`\``
-
-// containers = children of the system node
-const sys = ctx.find((n) => n.kind === 'system') || ctx[0]
-const containers = m.nodes.filter((n) => n.parent === (sys && sys.id))
-const contIds = new Set(containers.map((n) => n.id))
-const containerDiagram = containers.length ? `\`\`\`mermaid\nC4Container\n  title Container view — ${sys.name}\n${containers.map((n) => '  ' + el(n)).join('\n')}\n${rels(contIds)}\n\`\`\`` : '_No containers in the model yet._'
-const leafCount = (id) => m.nodes.filter((n) => n.parent === id && n.kind === 'leaf').length
-const containerTable = containers.length
-  ? ['| Container | Tech | Leaves | What it does |', '|---|---|---|---|', ...containers.map((n) => `| ${n.name} | ${n.tech || '—'} | ${leafCount(n.id)} | ${(n.func || n.description || 'TODO(forma): describe').replace(/\n/g, ' ')} |`)].join('\n')
-  : '_No containers yet._'
-
-// ADR index if present
-const adrDir = join(REPO, 'docs/adr')
-let adrs = '_No `docs/adr/` found — record decisions as ADRs._'
-if (existsSync(adrDir)) {
-  const files = readdirSync(adrDir).filter((f) => /\.md$/.test(f) && !/readme|template/i.test(f)).sort()
-  if (files.length) adrs = files.map((f) => { const t = (readFileSync(join(adrDir, f), 'utf-8').match(/^#\s+(.+)/m) || [, f])[1]; return `- [${t}](../adr/${f})`; }).join('\n')
-}
-
-const stack = (m.meta && m.meta.stack) || (sys && sys.tech) || 'TODO'
+// Deterministic, model-derived sections come from the shared side-effect-free renderer, so
+// `forma doc` (writer) and `forma check` (attach freshness gate) render the block identically.
+const { contextDiagram, containerTable, containerDiagram, adrs, stack, sys, containers } = renderParts(m, { repo: REPO })
 const TODO = (s) => `> TODO(forma): ${s}`
 const md = `<!-- forma: arc42 scaffold projected from c4-model.json. Deterministic sections are generated;
      do not edit them by hand — re-run \`forma doc\`. Fill the TODO(forma) prose, then promote to ARCHITECTURE.md. -->
@@ -96,6 +68,35 @@ ${TODO('known risks and debt, with links to any register.')}
 ## 12. Glossary
 ${TODO('domain and project terms.')}
 `
+// --attach <file>: inject the deterministic block between sentinel markers in an EXISTING doc
+// (default: model.source.docPath), leaving human prose outside the markers untouched. `forma check`
+// then governs that block. Default (no --attach) writes the standalone scaffold, exactly as before.
+const attachIdx = process.argv.indexOf('--attach')
+if (attachIdx > -1) {
+  const next = process.argv[attachIdx + 1]
+  let target = (next && !next.startsWith('--')) ? next : (m.source && m.source.docPath)
+  if (!target) { console.error('[forma doc] --attach: no target (pass a file or set docPath in the model)'); process.exit(1) }
+  target = isAbsolute(target) ? target : join(REPO, target)
+  const prior = existsSync(target) ? readFileSync(target, 'utf-8') : ''
+  let out
+  try { out = replaceBetween(prior, renderBlock(m, { repo: REPO })) }
+  catch { console.error('[forma doc] --attach: malformed forma markers in ' + relative(REPO, target) + ' — fix by hand'); process.exit(1) }
+  mkdirSync(join(target, '..'), { recursive: true })
+  writeFileSync(target, out)
+  const rel = relative(REPO, target)
+  console.log(`[forma doc] spliced generated block into ${rel} — ${containers.length} container(s); prose outside the markers untouched.`)
+  // Register the target so `forma check` governs THIS file too, not just source.docPath — an
+  // injected block nobody gates is exactly the false-green forma exists to kill. `gen` carries
+  // the registry forward across regens.
+  const known = m.source.attachedDocs || []
+  if (rel !== m.source.docPath && !known.includes(rel)) {
+    m.source.attachedDocs = [...known, rel].sort()
+    writeFileSync(MODEL, JSON.stringify(m, null, 2) + '\n')
+    console.log(`[forma doc] registered ${rel} in ${relative(REPO, MODEL)} — \`forma check\` now governs its block.`)
+    console.log('[forma doc] commit the model: the registry lives in it, and a lost model un-governs the doc.')
+  }
+  process.exit(0)
+}
 writeFileSync(OUT, md)
 console.log(`[forma doc] wrote ${relative(REPO, OUT)} — ${containers.length} container(s), context + container diagrams from the model.`)
 console.log('[forma doc] deterministic sections filled; write the TODO(forma) prose, then promote to ARCHITECTURE.md.')

package/lib/enrich.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// enrich.mjs — OPTIONAL LLM prose enrichment for description holes (§7). OFF by default.
+// Contract: fills ONLY nodes whose deterministic descSource is 'fallback'; never structure, never
+// the gate. Output is cached+committed in c4-model.json with descInputHash; `check` recomputes the
+// hash (no network) and warns softly if stale. Providers hit their REST API via global fetch (zero-dep).
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+
+const DEFAULT_MODEL = { anthropic: 'claude-haiku-4-5', openai: 'gpt-4o-mini', ollama: 'llama3.2', echo: 'echo' }
+
+// Sibling leaves of the same container — the "neighbors" context for a hole.
+function siblingsOf(node, ctx) {
+  const cont = ctx.containerOf ? ctx.containerOf(node, ctx.byId) : node.parent
+  const out = []
+  if (ctx.byId) for (const n of ctx.byId.values()) {
+    if (n.id !== node.id && n.kind === 'leaf' && (ctx.containerOf ? ctx.containerOf(n, ctx.byId) : n.parent) === cont) out.push(String(n.name))
+  }
+  return { cont, siblings: out.sort() }
+}
+
+// Stable inputs that define a node's description → hash. Change them and cached prose is stale.
+// Pure, no network — check.mjs imports THIS (not the providers) to flag staleness.
+export function descInputHash(node, ctx) {
+  const { cont, siblings } = siblingsOf(node, ctx)
+  const contName = (ctx.byId && ctx.byId.get(cont) || {}).name || cont || ''
+  const parts = [contName, node.name, node.kind, siblings.join(',')]
+  // A component's description is composed from its CHILDREN's docs, so their prose is one of its
+  // inputs. Without this, a child gaining a docstring leaves the hash unchanged: the cached LLM
+  // sentence is restored over the fresh documentation, `--enrich` sees no hole and `check` stays
+  // quiet — the box frozen with no way back short of hand-editing the model.
+  if (node.kind === 'component' && ctx.byId) {
+    parts.push([...ctx.byId.values()].filter((n) => n.parent === node.id).map((n) => String(n.func || '')).sort().join('|'))
+  }
+  return createHash('sha256').update(parts.join(' ')).digest('hex')
+}
+
+function promptFor(node, ctx, opts = {}) {
+  const { cont, siblings } = siblingsOf(node, ctx)
+  const contName = (ctx.byId && ctx.byId.get(cont) || {}).name || cont || 'the system'
+  const path = (node.evidence || []).find((e) => e.type === 'path')
+  return [
+    `In ONE plain sentence (max 18 words), say what the software module "${node.name}" does.`,
+    `It belongs to the container "${contName}".`,
+    siblings.length ? `Sibling modules: ${siblings.slice(0, 40).join(', ')}.` : '',
+    // Only the agent enricher can act on this: a REST provider has no filesystem. That asymmetry
+    // IS the point of the agent mode — the model driving forma can read the source it describes.
+    (opts.canRead && path) ? `Read the file at ${path.ref} if you need certainty.` : '',
+    'Answer with the sentence only — no preamble, no quotes.',
+  ].filter(Boolean).join('\n')
+}
+
+async function callAnthropic(prompt, { model, apiKey }) {
+  const r = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' },
+    body: JSON.stringify({ model, max_tokens: 120, messages: [{ role: 'user', content: prompt }] }),
+  })
+  if (!r.ok) throw new Error(`anthropic ${r.status}: ${(await r.text()).slice(0, 160)}`)
+  const j = await r.json()
+  return (j.content || []).map((c) => c.text || '').join('').trim()
+}
+async function callOpenAI(prompt, { model, apiKey }) {
+  const r = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify({ model, max_tokens: 120, messages: [{ role: 'user', content: prompt }] }),
+  })
+  if (!r.ok) throw new Error(`openai ${r.status}: ${(await r.text()).slice(0, 160)}`)
+  const j = await r.json()
+  return (((j.choices || [])[0] || {}).message || {}).content?.trim() || ''
+}
+async function callOllama(prompt, { model }) {
+  const host = process.env.OLLAMA_HOST || 'http://localhost:11434'
+  const r = await fetch(`${host}/api/generate`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ model, prompt, stream: false }),
+  })
+  if (!r.ok) throw new Error(`ollama ${r.status}`)
+  return String((await r.json()).response || '').trim()
+}
+async function callEcho() { return 'Auto-described (test enricher).' } // deterministic, no network — used by tests
+
+const PROVIDERS = { anthropic: callAnthropic, openai: callOpenAI, ollama: callOllama, echo: callEcho }
+
+// Cache: prior committed model → Map(id → node). mergeCache restores llm prose on unchanged inputs
+// (runs ALWAYS, even without --enrich, so a plain regen doesn't destroy valid enrichment). Pure.
+export function loadCache(priorModelPath) {
+  try { return new Map((JSON.parse(readFileSync(priorModelPath, 'utf-8')).nodes || []).map((n) => [n.id, n])) } catch { return new Map() }
+}
+// Stale prose (inputs changed) is restored TOO, keeping its old hash: a network outage must never
+// make a box worse than it was. `check` keeps warning about it and the next --enrich refills it
+// (see the hole selection below, which admits llm nodes whose hash no longer matches).
+export function mergeCache(nodes, cache) {
+  let restored = 0
+  for (const n of nodes) {
+    if (n.descSource !== 'fallback') continue
+    const prev = cache.get(n.id)
+    if (prev && prev.descSource === 'llm' && prev.descInputHash && prev.func) {
+      n.func = prev.func; n.descSource = 'llm'; n.descInputHash = prev.descInputHash; restored++
+    }
+  }
+  return restored
+}
+
+// The holes an enricher would fill: never-described nodes, plus llm prose whose inputs moved.
+export function holesIn(nodes, ctx) {
+  return nodes.filter((n) => (n.kind === 'leaf' || n.kind === 'component') &&
+    (n.descSource === 'fallback' || (n.descSource === 'llm' && n.descInputHash !== descInputHash(n, ctx))))
+}
+
+// --enricher agent: no network, no API key. When an AGENT drives forma the LLM is already in the
+// room — asking it to call a REST API with a key it doesn't have is the one thing that made
+// ollama look like a default. Emit the work instead, and let the agent write the prose.
+export function agentPlan(nodes, ctx) {
+  return holesIn(nodes, ctx).map((n) => ({ id: n.id, prompt: promptFor(n, ctx, { canRead: true }), descInputHash: descInputHash(n, ctx) }))
+}
+
+// Apply prose an agent (or a human) wrote for those holes. Enrichment NEVER overwrites a real
+// document: a fill aimed at a curated/docstring/readme/arc42 node is an error, not a silent skip.
+export function applyFills(nodes, ctx, fills) {
+  const byId = new Map(nodes.map((n) => [n.id, n]))
+  let applied = 0
+  for (const f of fills) {
+    const n = byId.get(f && f.id)
+    if (!n) throw new Error(`--enrich-apply: unknown node id "${f && f.id}"`)
+    if (!f.func || !String(f.func).trim()) throw new Error(`--enrich-apply: "${f.id}" has no func text`)
+    if (n.descSource !== 'fallback' && n.descSource !== 'llm') throw new Error(`--enrich-apply: "${f.id}" is described by its ${n.descSource} — enrichment never overwrites documentation`)
+    n.func = String(f.func).trim(); n.descSource = 'llm'; n.descInputHash = descInputHash(n, ctx); applied++
+  }
+  return applied
+}
+
+// --enrich only: fill still-empty holes via the network. Best-effort: a provider error stops the
+// pass (returns partial) rather than aborting gen — the caller keeps the deterministic fallback.
+export async function enrich(nodes, ctx, opts = {}) {
+  const provider = opts.provider || 'anthropic'
+  const call = PROVIDERS[provider]
+  if (!call) throw new Error(`unknown enricher "${provider}" (anthropic|openai|ollama)`)
+  const model = opts.model || DEFAULT_MODEL[provider]
+  const apiKey = provider === 'anthropic' ? process.env.ANTHROPIC_API_KEY : provider === 'openai' ? process.env.OPENAI_API_KEY : ''
+  if ((provider === 'anthropic' || provider === 'openai') && !apiKey) throw new Error(`--enrich: ${provider} needs ${provider === 'anthropic' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY'} in the environment`)
+  const holes = holesIn(nodes, ctx)
+  let filled = 0
+  for (const n of holes) {
+    const text = await call(promptFor(n, ctx), { model, apiKey })
+    if (text) { n.func = text; n.descSource = 'llm'; n.descInputHash = descInputHash(n, ctx); filled++ }
+  }
+  return { filled, holes: holes.length }
+}