forma-arch 0.2.0 → 0.4.0

package/lib/gen.mjs

@@ -6,17 +6,31 @@ import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from '
 import { join, dirname, basename, relative } from 'node:path'
 import { execSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
+import { containerOf, componentsFor } from './cluster.mjs'
+import { makeDescribeCtx, resolveDescription } from './describe.mjs'
+import { loadCache, mergeCache, enrich, agentPlan, applyFills } 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 }
 const REPO = arg('--repo', process.cwd())
 const TOPO = arg('--topology', join(REPO, 'docs/architecture/c4-topology.json'))
 const OUT = arg('--out', join(REPO, 'docs/architecture/c4-model.json'))
-const SCHEMA_VERSION = '1.1.0'
+const SCHEMA_VERSION = '1.3.0'
+const CLUSTER = !process.argv.includes('--no-cluster') // §2: auto-cluster flat containers; --no-cluster to disable
+const ENRICH = process.argv.includes('--enrich')       // §7: opt-in LLM prose for description holes
+const ENRICHER = arg('--enricher', 'anthropic')
+const ENRICH_MODEL = arg('--enrich-model', null)
+const STATUS = arg('--status', join(REPO, 'docs/architecture/c4-status.json')) // curated programme state, optional
+const STATUS_SET = process.argv.includes('--status')
+const APPLY = arg('--enrich-apply', null)          // prose written by the agent driving forma
 
 const topo = JSON.parse(readFileSync(TOPO, 'utf-8'))
 const rp = (p) => join(REPO, p)
 const fail = (m) => { console.error('[gen-c4] FAIL: ' + m); process.exit(1) }
+// §2 thresholds, overridable. Guarded: a non-integer would silently disable clustering
+// (`length >= NaN` is false for every group), so a bad value fails loud instead.
+const posInt = (flag, dflt) => { const v = Number(arg(flag, dflt)); if (!Number.isInteger(v) || v < 1) fail(`${flag}: expected a positive integer, got "${arg(flag, dflt)}"`); return v }
+const CLUSTER_MIN = posInt('--cluster-min', 8), GROUP_MIN = posInt('--group-min', 3)
 
 function walk(spec) {
   const dir = rp(spec.dir)
@@ -86,21 +100,107 @@ for (const p of topo.plannedLeaves || []) {
         evidence: [{ type: 'doc', ref: p.sourceRef }] })
 }
 
+// §2) synthesize a component layer for flat containers (auto; --no-cluster to disable).
+// Runs BEFORE the enrich/func loops so components inherit category/status/func. Leaves that
+// join a component are re-parented to it; containerOf() keeps edge/check logic container-scoped.
+if (CLUSTER) for (const cid of [...new Set(topo.leafSources.map((s) => s.parent))]) {
+  const container = byId.get(cid); if (!container) continue
+  const leaves = nodes.filter((n) => n.kind === 'leaf' && n.parent === cid) // pre-reparent: plain filter valid here
+  if (leaves.length <= CLUSTER_MIN) continue
+  const { components, reparent } = componentsFor(container, leaves, { groupMin: GROUP_MIN })
+  if (!components.length) { console.log(`[gen-c4] container ${cid}: ${leaves.length} leaf non-clusterable (flat)`); continue }
+  for (const c of components) add(c)
+  for (const n of leaves) { const to = reparent.get(n.id); if (to) n.parent = to }
+  console.log(`[gen-c4] container ${cid}: clustered ${leaves.length} leaves into ${components.length} component(s)`)
+}
+
 // enrich: fill hologram defaults (category, 5-status, completion, current/target) where absent
 for (const n of nodes) {
   const par = n.parent ? byId.get(n.parent) : null
   if (!n.category) n.category = n.kind === 'leaf' ? (par && par.category) || 'leaf' : n.kind
   if (!n.status2) n.status2 = n.status === 'planned' ? 'planned' : 'done'
   if (n.completion == null) n.completion = n.status === 'planned' ? 0 : 100
-  if (!n.current) { const pth = (n.evidence || []).find((e) => e.type === 'path'); n.current = pth ? `Exists: ${pth.ref}` : (n.tech || '') }
+  // `current` is left EMPTY unless curated (topology or status overlay): the viewer falls back to
+  // `func`, which since §1a carries the module's real documentation. The old "Exists: <path>"
+  // filler restated the evidence path in the one field meant for programme facts.
   if (n.target == null) n.target = ''
 }
 
-// func: plain-language "what it does" (non-dev). Leaves from the descriptions map; else the description.
-const D = topo.descriptions || {}
+// §1a) func: plain-language "what it does" resolved from existing docs (curated → docstring → README
+// → arc42 → generated fallback), with provenance in descSource. No LLM here — pure parsing.
+const dctx = makeDescribeCtx({ repo: REPO, byId, descriptions: topo.descriptions || {}, docPath: topo.docPath, containerOf })
+for (const n of nodes) { const r = resolveDescription(n, dctx); n.func = r.func; n.descSource = r.descSource }
+
+// §1a-bis) a synthesized component has no doc of its own: before settling for "Groups related
+// files under X", compose its box from its children's docs (first sentence of up to 3, ordered by
+// name — deterministic). descSource stays 'fallback': this is a heuristic, and --enrich may still
+// improve it. Separate pass so it does not depend on components being added after their leaves.
+const firstSentence = (s) => (String(s).match(/^[^.!?]*[.!?]/) || [String(s)])[0].trim()
 for (const n of nodes) {
-  const key = n.parent ? `${n.parent}/${String(n.name).replace(/\.\w+$/, '').replace(/ .*/, '')}` : null
-  n.func = (key && D[key]) || n.description || (n.kind === 'leaf' ? `Component of module ${(byId.get(n.parent) || {}).name || n.parent}.` : '')
+  if (n.kind !== 'component' || n.descSource !== 'fallback') continue
+  const kids = nodes.filter((k) => k.parent === n.id && ['curated', 'docstring', 'readme'].includes(k.descSource))
+    .sort((a, b) => (String(a.name) < String(b.name) ? -1 : String(a.name) > String(b.name) ? 1 : 0)).slice(0, 3)
+  const txt = kids.map((k) => firstSentence(k.func)).filter(Boolean).join(' ')
+  if (txt) n.func = txt.length > 200 ? txt.slice(0, 199) + '…' : txt
+}
+
+// §WP-A1) programme-status overlay: the one channel for curated STATE (what is true now, where it
+// must land, what proves it). Code can't know it, so a human/agent writes it in c4-status.json and
+// gen validates only its FORM — ids resolve, fields are known, enums/ranges hold. Never `func`:
+// what a module DOES comes from its docs (§1a), what it's WORTH is programme state.
+const STATUS_FIELDS = new Set(['status2', 'completion', 'statusWord', 'current', 'target', 'verify', 'issues'])
+const STATUS2 = new Set(['done', 'in-progress', 'next', 'planned', 'problem'])
+let statusPath = null
+if (existsSync(STATUS) || STATUS_SET) {
+  if (!existsSync(STATUS)) fail(`--status: file missing: ${STATUS}`)
+  let ov
+  try { ov = JSON.parse(readFileSync(STATUS, 'utf-8')) } catch (e) { fail(`--status: ${STATUS} is not valid JSON: ${(e && e.message) || e}`) }
+  let decorated = 0
+  for (const [id, patch] of Object.entries(ov.nodes || {})) {
+    const target = byId.get(id)
+    if (!target) fail(`status overlay: unknown node id "${id}" — it is not in the model (stale overlay?)`)
+    for (const [k, v] of Object.entries(patch)) {
+      if (k.startsWith('$')) continue // $comment and friends
+      if (!STATUS_FIELDS.has(k)) fail(`status overlay: "${id}" has field "${k}"; allowed: ${[...STATUS_FIELDS].join(', ')}${k === 'func' ? ' (func comes from the docs, not the overlay)' : ''}`)
+      if (k === 'status2' && !STATUS2.has(v)) fail(`status overlay: "${id}" status2 "${v}" — expected one of ${[...STATUS2].join('|')}`)
+      if (k === 'completion' && !(Number.isInteger(v) && v >= 0 && v <= 100)) fail(`status overlay: "${id}" completion must be an integer 0-100, got ${JSON.stringify(v)}`)
+      if (k === 'issues') {
+        if (!Array.isArray(v)) fail(`status overlay: "${id}" issues must be an array`)
+        for (const is of v) if (!/^#?\d+$/.test(String(is))) fail(`status overlay: "${id}" issue ${JSON.stringify(is)} — expected "#123"`)
+      }
+      target[k] = v
+    }
+    decorated++
+  }
+  statusPath = relative(REPO, STATUS)
+  console.log(`[gen-c4] status overlay: ${decorated} node(s) decorated from ${statusPath}`)
+}
+
+// §7) enrichment (prose only, never structure/gate). Cache-merge ALWAYS: preserve prior LLM prose
+// whose inputs are unchanged, so a plain regen doesn't discard it. --enrich additionally fills the
+// remaining holes over the network (best-effort — a failure keeps the deterministic fallback).
+const ectx = { repo: REPO, byId, containerOf }
+mergeCache(nodes, loadCache(OUT))
+// --enrich-apply: prose written by the agent that drives forma (see --enricher agent below).
+// Independent of --enrich, and applied first — an explicit fill outranks anything generated.
+if (APPLY) {
+  if (!existsSync(APPLY)) fail(`--enrich-apply: file missing: ${APPLY}`)
+  let fills
+  try { fills = JSON.parse(readFileSync(APPLY, 'utf-8')).fills } catch (e) { fail(`--enrich-apply: ${APPLY} is not valid JSON: ${(e && e.message) || e}`) }
+  if (!Array.isArray(fills)) fail(`--enrich-apply: ${APPLY} must contain {"fills":[{"id","func"}]}`)
+  try { console.log(`[gen-c4] --enrich-apply: ${applyFills(nodes, ectx, fills)} fill(s) applied`) }
+  catch (e) { fail(String((e && e.message) || e)) }
+}
+if (ENRICH && ENRICHER === 'agent') {
+  // No network: emit the work for the agent already in the session, keep the deterministic model.
+  const plan = agentPlan(nodes, ectx)
+  const planPath = join(dirname(OUT), 'enrich-plan.json')
+  writeFileSync(planPath, JSON.stringify({ entries: plan }, null, 2) + '\n')
+  console.log(`[gen-c4] --enricher agent: ${plan.length} hole(s) → ${relative(REPO, planPath)} — write the prose yourself, then:`)
+  console.log(`[gen-c4]   forma gen --enrich-apply ${relative(REPO, join(dirname(OUT), 'enrich-fill.json'))}`)
+} else if (ENRICH) {
+  try { const r = await enrich(nodes, ectx, { provider: ENRICHER, model: ENRICH_MODEL }); console.log(`[gen-c4] --enrich (${ENRICHER}): filled ${r.filled}/${r.holes} description hole(s)`) }
+  catch (e) { console.error('[gen-c4] --enrich skipped: ' + String((e && e.message) || e)) }
 }
 
 // 4b) derive container↔container edges from REAL code references (deterministic, additive).
@@ -113,7 +213,7 @@ if (!process.argv.includes('--no-auto-edges')) {
   const srcs = (topo.leafSources || []).filter((s) => byId.has(s.parent))
   const exposes = new Map(), text = new Map()
   for (const s of srcs) {
-    exposes.set(s.parent, [...new Set(nodes.filter((n) => n.parent === s.parent && n.kind === 'leaf')
+    exposes.set(s.parent, [...new Set(nodes.filter((n) => n.kind === 'leaf' && containerOf(n, byId) === s.parent)
       .map((n) => String(n.name)).filter((nm) => nm.length >= 5 && !STOP.has(nm.toLowerCase())))])
     let t = ''; const dir = rp(s.dir)
     try { for (const f of readdirSync(dir)) { const fp = join(dir, f); if (statSync(fp).isFile()) t += '\n' + readFileSync(fp, 'utf-8') } } catch {}
@@ -143,11 +243,26 @@ const gitOpts = { cwd: REPO, stdio: ['ignore', 'pipe', 'ignore'] }
 try { commit = execSync('git rev-parse HEAD', gitOpts).toString().trim() } catch {}
 try { branch = execSync('git rev-parse --abbrev-ref HEAD', gitOpts).toString().trim() } catch {}
 
+// §1b) carry the attach registry forward from the prior model — `forma doc --attach` writes it
+// there, and without this a plain regen would drop it and un-govern the attached docs.
+// The registry lives ONLY in the generated model, so that model has to be committed (or at least
+// kept) for the gate to keep governing. If a prior model is there but unreadable, say so rather
+// than silently ungoverning every attached doc.
+let attachedDocs = []
+if (existsSync(OUT)) {
+  try { attachedDocs = JSON.parse(readFileSync(OUT, 'utf-8')).source.attachedDocs || [] }
+  catch (e) { console.error(`[gen-c4] WARNING: ${OUT} is unreadable (${(e && e.message) || e}) — any source.attachedDocs registry in it is lost; re-run \`forma doc --attach\` for each attached doc.`) }
+}
+
+// generatedAt is the ONE per-run volatile field (a plain `gen` x2 must diff on nothing else).
+// meta.verifiedAt is reserved for `forma verify` (network, opt-in) — gen never writes it.
 const model = {
   schemaVersion: SCHEMA_VERSION,
   generatedAt: new Date().toISOString(),
-  source: { repo: topo.meta.repo, commit, branch, docPath: topo.docPath, generator: 'gen-c4-model@' + SCHEMA_VERSION },
-  meta: { ...topo.meta, verifiedAt: new Date().toISOString(), verifyMethod: 'code+topology (gh re-verify optional)' },
+  source: { repo: topo.meta.repo, commit, branch, docPath: topo.docPath, generator: 'gen-c4-model@' + SCHEMA_VERSION, ...(attachedDocs.length ? { attachedDocs } : {}), ...(statusPath ? { statusPath } : {}) },
+  // topo.layout (optional curated coordinates, keyed by parent id) rides along verbatim: the
+  // viewer pins those nodes and auto-arranges the rest. `meta` is the model's free-form area.
+  meta: { ...topo.meta, ...(topo.layout ? { layout: topo.layout } : {}), verifyMethod: 'code+topology (gh re-verify optional)' },
   levels: topo.levels,
   nodes,
   edges: topo.edges.map((e) => ({ status: 'current', estatus: e.estatus || 'active', ...e })),

package/lib/init.mjs

@@ -11,18 +11,27 @@ const REPO = arg('--repo', process.cwd())
 const OUT = arg('--out', join(REPO, 'docs/architecture/c4-topology.json'))
 const FORCE = process.argv.includes('--force')
 const IGNORE = new Set(['node_modules', '.git', 'dist', 'build', 'target', 'out', 'vendor', 'coverage', '.next', '.gradle', 'bin', 'obj'])
+// A real directory that holds files but is not an architecture container (data/fixtures/docs).
+// Kept separate from IGNORE (which is build/VCS junk, invisible even to language detection).
+const DATA_DIRS = new Set(['docs', 'fixtures', 'testdata', 'demo', 'corpus', 'assets', 'examples'])
+const SKIP_TESTS = process.argv.includes('--skip-tests') // test/ is real code by default; opt in to skip it
+const KEEP = new Set((arg('--include', '') || '').split(',').map((s) => s.trim().toLowerCase()).filter(Boolean))
+const SKIP_DIRS = new Set([...DATA_DIRS, ...(SKIP_TESTS ? ['test', 'tests'] : [])])
 const EXT = { ts: 'TypeScript', tsx: 'TypeScript', js: 'JavaScript', jsx: 'JavaScript', mjs: 'JavaScript', cjs: 'JavaScript', mts: 'TypeScript', cts: 'TypeScript', py: 'Python', go: 'Go', java: 'Java', rs: 'Rust', rb: 'Ruby', php: 'PHP', cs: 'C#', kt: 'Kotlin', swift: 'Swift', cpp: 'C++', c: 'C' }
 const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '') || 'x'
 
 if (existsSync(OUT) && !FORCE) { console.error(`[forma init] ${relative(REPO, OUT)} already exists — use --force to reseed.`); process.exit(1) }
 
-// 1) detect dominant language by extension count (skipping ignored dirs)
+// 1) detect dominant language by extension count. Skips the SAME dirs the container pass skips
+// (build junk AND data/fixture/doc dirs): counting files that can never become a container is how
+// a repo full of Python fixtures gets detected as a Python repo and then finds no source dir.
 const counts = {}
 ;(function walk(dir, depth) {
   if (depth > 12) return
   let ents; try { ents = readdirSync(dir) } catch { return }
   for (const e of ents) {
     if (IGNORE.has(e) || e.startsWith('.')) continue
+    if (SKIP_DIRS.has(e.toLowerCase()) && !KEEP.has(e.toLowerCase())) continue
     const p = join(dir, e)
     let st; try { st = statSync(p) } catch { continue }
     if (st.isDirectory()) walk(p, depth + 1)
@@ -58,6 +67,7 @@ const hasSrc = (dir) => { try { return readdirSync(dir).some((f) => { const p =
 // (A dir with direct sources is a container; a dir with none is descended into. Works for nested
 // layouts like src/app/routes/*.ts or Python packages, not just one level.)
 const seen = new Set()
+const skipped = []
 ;(function findContainers(dir, depth) {
   if (depth > 10) return
   let ents; try { ents = readdirSync(dir) } catch { return }
@@ -65,6 +75,7 @@ const seen = new Set()
     const p = join(dir, e)
     let st; try { st = statSync(p) } catch { continue }
     if (!st.isDirectory()) continue
+    if (SKIP_DIRS.has(e.toLowerCase()) && !KEEP.has(e.toLowerCase())) { skipped.push({ dir: relative(REPO, p), reason: 'data/fixtures/docs dir (name match) — curate if wrong' }); continue }
     if (hasSrc(p)) {
       const rel = relative(root, p) || e
       let id = slug(rel.replace(/[\\/]+/g, '_'))
@@ -78,7 +89,7 @@ const seen = new Set()
 // loose files directly in root → an entry container
 if (hasSrc(root)) { nodes.push({ id: 'app', level: 'container', kind: 'container', parent: sysId, name: 'app', tech: lang, description: 'Entry point / loose top-level sources.' }); leafSources.push({ parent: 'app', dir: relative(REPO, root) || '.', match: matchRe }) }
 
-if (leafSources.length === 0) { console.error('[forma init] found a source root but no directory with source files directly in it. Add leafSources manually.'); process.exit(1) }
+if (leafSources.length === 0) { console.error(`[forma init] detected ${lang} (*.${ext[0]}) as the dominant language, but no directory under ${relative(REPO, root) || '.'}/ holds *.${ext[0]} files directly. Pass --include <dir,...> if the sources live in a skipped dir, or add leafSources manually.`); process.exit(1) }
 
 const topo = {
   meta: { repo: basename(REPO), stack: lang, seededBy: 'forma init' },
@@ -88,9 +99,10 @@ const topo = {
   leafSources,
   edges: [],
   descriptions: {},
+  _skipped: skipped,
 }
 // ensure output dir exists
 mkdirSync(join(OUT, '..'), { recursive: true })
 writeFileSync(OUT, JSON.stringify(topo, null, 2) + '\n')
-console.log(`[forma init] wrote ${relative(REPO, OUT)} — ${lang}, ${leafSources.length} container(s) seeded from ${relative(REPO, root) || '.'}/`)
+console.log(`[forma init] wrote ${relative(REPO, OUT)} — ${lang}, ${leafSources.length} container(s) seeded from ${relative(REPO, root) || '.'}/${skipped.length ? `, ${skipped.length} data/doc dir(s) skipped` : ''}`)
 console.log('[forma init] NEXT: curate names/descriptions + add context externals + run `forma gen`.')

package/lib/render.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// render.mjs — pure, side-effect-free renderers for the arc42 projection.
+// Shared by `forma doc` (writer) and `forma check` (attach-mode freshness gate) so both render the
+// governed block identically. NO writeFileSync / console / process at module scope.
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { containerOf } from './cluster.mjs'
+
+export const BEGIN = '<!-- forma:begin (generated — do not edit) -->'
+export const END = '<!-- forma:end -->'
+
+// The deterministic, model-derived parts (never the TODO judgment prose, never volatile fields).
+export function renderParts(model, opts = {}) {
+  const repo = opts.repo || process.cwd()
+  const m = model
+  const byId = new Map(m.nodes.map((n) => [n.id, n]))
+  const sid = (s) => String(s).replace(/[^A-Za-z0-9_]/g, '_')
+  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')
+
+  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\`\`\``
+
+  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.kind === 'leaf' && containerOf(n, byId) === id).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._'
+
+  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'
+  return { contextDiagram, containerTable, containerDiagram, adrs, stack, sys, containers }
+}
+
+// The governed region injected between the sentinel markers (deterministic subset only).
+export function renderBlock(model, opts = {}) {
+  const p = renderParts(model, opts)
+  return [
+    '### Context', '', p.contextDiagram, '',
+    '### Building blocks', '', p.containerTable, '', p.containerDiagram, '',
+    '### Architecture decisions', '', p.adrs,
+  ].join('\n')
+}
+
+// Comparison normalizer: CRLF→LF, strip trailing whitespace, trim surrounding blank lines.
+export const norm = (s) => String(s).replace(/\r\n/g, '\n').replace(/[ \t]+$/gm, '').replace(/^\n+|\n+$/g, '')
+
+// Inner content between markers, or null unless BOTH are present and ordered.
+export function extractBetween(text) {
+  const b = text.indexOf(BEGIN), e = text.indexOf(END)
+  if (b === -1 || e === -1 || e < b) return null
+  return text.slice(b + BEGIN.length, e)
+}
+
+// Splice the block between markers; append at EOF (creating them) if absent; throw if exactly one present.
+export function replaceBetween(text, block) {
+  const b = text.indexOf(BEGIN), e = text.indexOf(END)
+  const body = `${BEGIN}\n\n${block}\n\n${END}`
+  if (b !== -1 && e !== -1 && e > b) return text.slice(0, b) + body + text.slice(e + END.length)
+  if (b !== -1 || e !== -1) throw new Error('malformed forma markers')
+  const sep = text && !text.endsWith('\n') ? '\n\n' : (text ? '\n' : '')
+  return text + sep + body + '\n'
+}

package/lib/schema/c4-model.schema.json

@@ -45,6 +45,17 @@
           "type": "string",
           "description": "The arc42 architecture doc this model derives from."
         },
+        "statusPath": {
+          "type": "string",
+          "description": "Repo-relative curated programme-status overlay applied by `forma gen` (c4-status.json). The gate fails if it decorates a node id the model no longer has."
+        },
+        "attachedDocs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Repo-relative docs carrying an injected forma block (written by `forma doc --attach`). The drift gate governs every one of them, not just docPath."
+        },
         "generator": {
           "type": "string"
         }
@@ -203,6 +214,22 @@
           "func": {
             "type": "string",
             "description": "Plain-language 'what it does' for non-developers."
+          },
+          "descSource": {
+            "type": "string",
+            "enum": [
+              "curated",
+              "docstring",
+              "readme",
+              "arc42",
+              "fallback",
+              "llm"
+            ],
+            "description": "Provenance of func: how the description was resolved (§1a chain; 'llm' = optional enrichment)."
+          },
+          "descInputHash": {
+            "type": "string",
+            "description": "sha256 of the inputs that produced an LLM-enriched func; check recomputes it to flag stale prose."
           }
         }
       }

package/lib/verify.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// forma verify — refresh programme status from LIVE GitHub issues, through the user's `gh` CLI.
+// This is the ONLY command that touches the network, and it is opt-in: `gen` and `check` stay
+// deterministic and offline forever (that is the product). It never touches structure — no nodes,
+// no edges, no func — only the state fields of nodes that reference an issue.
+// Usage: node verify.mjs [--repo <path>] [--model <path>] [--gh-repo <owner/repo>] [--gh-cmd <cmd>]
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { join } from 'node:path'
+
+const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
+const REPO = arg('--repo', process.cwd())
+const MODEL = arg('--model', join(REPO, 'docs/architecture/c4-model.json'))
+const GH_CMD = arg('--gh-cmd', 'gh') // split on whitespace; the tests point it at a stub
+const LIMIT = arg('--limit', '250')
+const fail = (m) => { console.error('[forma verify] ' + m); process.exit(1) }
+
+if (!existsSync(MODEL)) fail(`model missing: ${MODEL} — run \`forma gen\` first.`)
+const model = JSON.parse(readFileSync(MODEL, 'utf-8'))
+const GH_REPO = arg('--gh-repo', (model.meta && model.meta.ghRepo) || null)
+if (!GH_REPO) fail('no target repo: pass --gh-repo <owner/repo>, or set meta.ghRepo in the topology.')
+
+// Which nodes claim which issue — from issues[] and from verify.issue.
+const num = (v) => { const m = /^#?(\d+)$/.exec(String(v)); return m ? Number(m[1]) : null }
+const refs = new Map()
+for (const n of model.nodes || []) {
+  const claimed = [...(n.issues || []), ...(n.verify && n.verify.issue != null ? [n.verify.issue] : [])]
+  for (const raw of claimed) {
+    const i = num(raw); if (!i) continue
+    if (!refs.has(i)) refs.set(i, [])
+    refs.get(i).push(n)
+  }
+}
+if (!refs.size) { console.log('[forma verify] no issue references in the model — nothing to verify (add issues[] via the status overlay).'); process.exit(0) }
+
+// ONE call for every issue: state for the whole repo, then match locally.
+const parts = String(GH_CMD).split(/\s+/).filter(Boolean)
+let raw
+try {
+  raw = execFileSync(parts[0], [...parts.slice(1), 'issue', 'list', '--repo', GH_REPO, '--state', 'all', '--limit', String(LIMIT), '--json', 'number,state'],
+    { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] })
+} catch (e) {
+  const why = (e && e.code === 'ENOENT') ? `\`${parts[0]}\` not found — install the GitHub CLI or pass --gh-cmd` : String((e && (e.stderr || e.message)) || e).trim()
+  console.error(`[forma verify] ${why}`)
+  fail('model left untouched.')
+}
+let issues
+try { issues = JSON.parse(raw) } catch { fail(`unexpected output from \`${parts[0]}\` (wanted JSON): ${String(raw).slice(0, 160)}`) }
+if (!Array.isArray(issues)) fail('unexpected output: expected a JSON array of {number,state}.')
+
+const ts = new Date().toISOString()
+const seen = new Set()
+let closed = 0, decorated = 0
+for (const it of issues) {
+  const n = Number(it.number); seen.add(n)
+  if (String(it.state || '').toUpperCase() !== 'CLOSED') continue
+  const nodes = refs.get(n); if (!nodes) continue
+  closed++
+  for (const node of nodes) {
+    node.status2 = 'done'; node.completion = 100
+    // The badge shows statusWord when there is one, so a curated "NEXT"/"50%" would survive the
+    // node turning green — a box claiming both at once. Marking done owns the badge too.
+    if (node.statusWord) node.statusWord = '100%'
+    const mark = `(#${n} CLOSED` // re-running must not stack prefixes
+    if (!String(node.current || '').includes(mark)) {
+      node.current = `Closed with evidence ${mark}, gh ${ts}). ${String(node.current || '').trim()}`.trim()
+      decorated++
+    }
+  }
+}
+const unknown = [...refs.keys()].filter((n) => !seen.has(n))
+
+model.meta = model.meta || {}
+model.meta.verifiedAt = ts // the ONE field only verify writes — gen must stay single-volatile (R2)
+model.meta.verifyMethod = 'gh live'
+writeFileSync(MODEL, JSON.stringify(model, null, 2) + '\n')
+console.log(`[forma verify] ${GH_REPO}: ${refs.size} referenced issue(s), ${closed} closed → ${decorated} node(s) marked done`)
+if (unknown.length) console.log(`[forma verify] not returned by gh (closed long ago, wrong repo, or beyond --limit ${LIMIT}): ${unknown.map((n) => '#' + n).join(', ')}`)
+console.log(`[forma verify] fact base stamped ${ts} — structure untouched, \`forma check\` unaffected.`)