forma-arch 0.5.0 → 0.7.0

package/README.md

@@ -17,6 +17,11 @@ A hand-drawn architecture diagram is stale the moment code changes. Forma walks
 real structure, infers relationships from cross-references to exported symbol names (heuristic, additive), and **fails a check** when the model
 and the code disagree. What you present is what actually exists.
 
+Where the language *declares* its architecture, forma reads the declaration instead of guessing. On
+**Go** the container and the leaf are the **package** (any directory with a non-test `.go`, however
+deeply nested), `_test.go` files are not architecture, and every edge comes from an `import` block —
+so the direction is right by construction. Every other stack uses the heuristic above.
+
 ## Install
 
 ```sh
@@ -36,6 +41,17 @@ npx forma-arch <command>        # or: npm i -D forma-arch
 
 **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).
 
+**Above the leaf, your feature matrix outranks the code.** A docstring is the right answer for one file and the wrong one for a whole container: a stakeholder does not ask which docstring the first file inside it has, they ask what that part of the product does for the user — and in a governed repo that sentence is already written in a capability table. `forma init` finds those tables and lists them under `docSources`; `gen` joins each row to the nodes its code references name, and quotes the row **verbatim** (`descSource: "docmap"`). Nothing is composed or paraphrased. A node named by more than three rows is not *described* by the matrix but merely *touched* by it, so it yields nothing and the code chain runs instead.
+
+```json
+"docSources": ["docs/FEATURE_MATRIX.md",
+               { "path": "docs/spec.md", "describe": "capability", "ref": "code_ref", "status": "status" }]
+```
+
+Column roles are detected by header name (`capability`/`feature`/`description`…, `code_ref`/`path`/`module`…, `status`/`state`) — name them explicitly when yours differ. Auto-detection additionally requires a status column, because "feature + file" is also the shape of a refactor plan and a task line does not belong in a stakeholder's box; a source you list by hand is trusted as written.
+
+**Progress can be generated, not only hand-written.** Where those rows carry a status, `gen` derives the node's `status2` and `completion` from them — one of two capabilities shipped is `in-progress` at 50%, and `verify.source` names the document and the tally. This is derived, so it is never trusted: `forma check` re-reads the document and **fails** if the committed model claims a number the document no longer supports, exactly as it re-walks `src/` for structure. A node no document names stays `unknown` — the honest blank, not a made-up zero.
+
 **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
@@ -45,6 +61,8 @@ npx forma-arch <command>        # or: npm i -D forma-arch
   "verify": { "source": "ADR-040 on main" }, "issues": ["#534"] } } }
 ```
 
+The overlay is the authority: every field it sets wins over anything derived, and `check` stops re-deriving that field. To describe one box by hand without a table, put the sentence in `descriptions`, keyed `"<containerId>/<node-name-without-extension>"` — `"core/alpha"` for the leaf `alpha.js` in container `core`, `"core/core"` for the container itself, since a container is its own container. It outranks every other source.
+
 **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:
@@ -52,10 +70,16 @@ npx forma-arch <command>        # or: npm i -D forma-arch
 | `--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 |
+| `anthropic` | 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 |
 
+`--enricher` has **no default**: `forma gen --enrich` on its own fails loud and lists what it
+accepts — the four above, plus `echo`, an offline stub the test suite uses and you should not. A
+default provider is a silent choice about your network and your API keys — and the old default
+(`anthropic`) meant that anyone without `ANTHROPIC_API_KEY` exported got a skip line, exit 0 and the
+same empty boxes they ran `--enrich` to fill.
+
 ## How it fits together
 
 ```
@@ -68,6 +92,10 @@ One source of truth (`c4-model.json`); two renderings (the interactive viewer an
 one deterministic check that keeps them honest. The file contract is
 [`lib/schema/c4-model.schema.json`](lib/schema/c4-model.schema.json).
 
+Working on forma itself? [`docs/ORIENTATION.md`](docs/ORIENTATION.md) walks what each pass of
+`gen`/`check` actually decides, with `path:line`, and audits which mechanisms nothing in the repo
+currently feeds.
+
 ## Model-agnostic by design
 
 The engine is plain Node — no LLM required. Structure is auto-walked, relationships are derived from

package/lib/check.mjs

@@ -9,6 +9,8 @@ import { fileURLToPath } from 'node:url'
 import { containerOf } from './cluster.mjs'
 import { renderBlock, extractBetween, norm } from './render.mjs'
 import { descInputHash } from './enrich.mjs'
+import { loadDocRows, indexByNode, statusFor } from './docmap.mjs'
+import { validateModel } from './validate.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 }
@@ -23,6 +25,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'))
+for (const err of validateModel(model)) errs.push('SCHEMA: ' + err)
 const byId = new Map((model.nodes || []).map((n) => [n.id, n]))
 
 // 1) schemaVersion present + basic shape
@@ -102,10 +105,28 @@ for (const docRel of governed) {
 
 // 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.
+let overlay = {}
 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.`)
+  if (ov) {
+    overlay = ov.nodes || {}
+    for (const id of Object.keys(overlay)) if (!byId.has(id)) fail(`status overlay: "${id}" is not a node in the model — ${src.statusPath} is stale.`)
+  }
+}
+
+// 8) doc-derived programme state is RE-DERIVED, never trusted. `gen` reads the repo's capability
+// tables and writes status2/completion from them; without this the document could flip a row to
+// BACKLOG while the committed model keeps showing a green box at 100% and no gate would notice —
+// the false green this command exists to kill. Same contract as assertion 2: recompute the truth.
+// Skipped per field where the curated overlay owns it, since there the overlay is the authority.
+const docIdx = indexByNode(loadDocRows(REPO, topo.docSources), model.nodes || [])
+for (const n of model.nodes || []) {
+  const want = statusFor(docIdx, n.id)
+  if (!want) continue
+  const owned = overlay[n.id] || {}
+  if (owned.status2 === undefined && n.status2 !== want.status2) fail(`DOC DRIFT: ${n.id} status2 is "${n.status2}" but ${want.source} derives "${want.status2}". Regenerate c4-model.json.`)
+  if (owned.completion === undefined && n.completion !== want.completion) fail(`DOC DRIFT: ${n.id} completion is ${n.completion} but ${want.source} derives ${want.completion}. Regenerate c4-model.json.`)
 }
 
 // SOFT: LLM-enriched prose whose inputs changed is only a reminder, never a gate failure (structure

package/lib/cluster.mjs

@@ -13,14 +13,17 @@ export function containerOf(node, byId) {
   return n ? n.id : null
 }
 
-// Group a flat container's leaves by common `foo_*` prefix. Deterministic: sorted group keys.
+// Group a flat container's leaves by common `foo<sep>*` prefix, where sep is any of - _ . — the
+// three conventions real repos use (kebab dominates JS/TS, snake Python, dot some Java/config
+// layouts). Splitting on `_` alone gave kebab and dot repos no component level at all.
+// 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('_')
+    const i = base.search(/[-_.]/)
     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, [])

package/lib/describe.mjs

@@ -2,15 +2,22 @@
 // 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 { readFileSync, existsSync, statSync } from 'node:fs'
 import { join, dirname } from 'node:path'
+import { describingRows } from './docmap.mjs'
 
 const norm = (s) => String(s).toLowerCase().trim()
+// A leaf's path evidence is usually a file — but a Go package leaf IS a directory, and its README
+// sits inside it, not one level up (dirname() would hand it the parent's README instead).
+const ownDir = (p) => { try { return statSync(p).isDirectory() ? p : dirname(p) } catch { return dirname(p) } }
 
 // First non-empty paragraph, markdown/whitespace stripped, capped to the viewer's ~2-line clamp.
+// A leading YAML front-matter block is metadata, not prose: without this every governed repo whose
+// READMEs open with `---\ntitle: …` put "--- title: 'haben — README' docversion: '2.1.0'" in a box.
 const firstPara = (text) => {
   let out = ''
-  for (const line of String(text).replace(/\r\n/g, '\n').split('\n')) {
+  const body = String(text).replace(/\r\n/g, '\n').replace(/^---\n[\s\S]*?\n---\n/, '')
+  for (const line of body.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)
@@ -60,31 +67,65 @@ function buildArc42Index(repo, docPath) {
   return idx
 }
 
-export function makeDescribeCtx({ repo, byId, descriptions, docPath, containerOf }) {
-  return { repo, byId, D: descriptions || {}, containerOf, readmeCache: new Map(), arc42: buildArc42Index(repo, docPath) }
+// Last resort for a node that HAS children: say what it measurably holds. Never the language —
+// a box reading "TypeScript" states the one thing the reader can already see in the header.
+function measuredFunc(node, ctx) {
+  const kids = [...ctx.byId.values()].filter((k) => k.parent === node.id)
+    .sort((a, b) => (String(a.name) < String(b.name) ? -1 : String(a.name) > String(b.name) ? 1 : 0))
+  if (!kids.length) return null
+  const count = (k) => kids.filter((x) => x.kind === k).length
+  const parts = [['container', count('container')], ['component', count('component')], ['file', count('leaf')]]
+    .filter((p) => p[1]).map((p) => `${p[1]} ${p[0]}${p[1] === 1 ? '' : 's'}`)
+  const names = kids.slice(0, 3).map((k) => k.name).join(', ')
+  return `${parts.join(' + ')}: ${names}${kids.length > 3 ? ', …' : '.'}`.slice(0, 240)
+}
+
+export function makeDescribeCtx({ repo, byId, descriptions, docPath, containerOf, docIndex }) {
+  return { repo, byId, D: descriptions || {}, containerOf, docIndex: docIndex || new Map(), readmeCache: new Map(), arc42: buildArc42Index(repo, docPath) }
+}
+
+// What the repo's own capability tables say about this node, quoted verbatim (§docmap).
+const fromDocs = (node, ctx) => {
+  const rows = describingRows(ctx.docIndex, node.id)
+  if (!rows) return null
+  return { func: rows.map((r) => r.text).join(' · ').slice(0, 240), descSource: 'docmap' }
 }
 
 // First hit wins. descSource records provenance for §7 enrichment + debugging.
+//
+// The chain is DOCUMENT-first above the leaf and CODE-first at the leaf, and that asymmetry is the
+// point: a stakeholder looking at a container asks what that part of the product does for the user
+// — a question the feature matrix answers and the docstring of the first file inside it does not.
+// One level down, at a single file, the docstring IS the better answer.
 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' }
+  if (node.kind !== 'leaf') { const d = fromDocs(node, ctx); if (d) return d }
   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)
+    const rd = readmeFirstPara(ownDir(abs), ctx.readmeCache)
+    if (rd) return { func: rd, descSource: 'readme' }
+  }
+  // A container's evidence is a GLOB over its own directory, never a `path` — which is why the
+  // README sitting in that very directory never reached it, and the box fell through to `tech`.
+  const glb = (node.evidence || []).find((e) => e.type === 'glob')
+  if (!pth && glb) {
+    const rd = readmeFirstPara(join(ctx.repo, glb.ref), ctx.readmeCache)
     if (rd) return { func: rd, descSource: 'readme' }
   }
+  const d = fromDocs(node, ctx) // leaves reach it here: after their own code, before the fallback
+  if (d) return d
   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' }
+  return { func: node.description || measuredFunc(node, ctx) || '', descSource: 'fallback' }
 }

package/lib/docmap.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// docmap.mjs — the DOCUMENTARY source of the description chain (§1a), and the only deterministic
+// producer of programme state. Pure parsing, NO network, NO invention.
+//
+// A governed repo already writes, in prose, what each part of it does for the user and whether it
+// is finished: a feature matrix, a capability table, a requirements sheet. Those rows carry code
+// references. This module joins those rows to model nodes by path, so a CONTAINER's box can read
+// "Account domain: bank/broker kinds, free-cash, IBAN, soft-archive" (a sentence a human wrote in a
+// repo document) instead of a docstring belonging to the first file inside it.
+//
+// Every sentence it yields is quoted from a document under `repo`; provenance is `descSource:
+// 'docmap'` plus `verify.source` naming the file. Nothing here composes, paraphrases or infers text.
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+// A node matching MORE rows than this is not DESCRIBED by the matrix — it is merely TOUCHED by
+// many features (on haben, `internal/store` is referenced by 12 rows and `internal/server` by 20).
+// Stitching those first sentences together would invent a claim no document makes, so past the cap
+// the node yields nothing and the rest of the chain runs. Same constant, same reason as the
+// component composition in gen.mjs: three sentences is the most a box can carry honestly.
+export const MAX_ROWS = 3
+
+// Column roles, by header name. Overridable per source; these defaults are conventions
+// (`capability`, `code_ref`, `status`), never one project's identifiers.
+const ROLES = {
+  describe: /^(capabilit(y|ies)|feature|description|what|summary|purpose)$/i,
+  ref: /^(code_?refs?|code|paths?|refs?|sources?|modules?|files?|impl(ementation)?)$/i,
+  status: /^(status|state|progress)$/i,
+}
+const DONE = /^(done|shipped|complete[d]?|ready|✅)\b/i
+// `./x` and `x/` are the same key as `x`; a bare `x` and `x/**` too.
+const normRef = (s) => String(s).trim().replace(/^\.\//, '').replace(/\/?\*+.*$/, '').replace(/\/+$/, '')
+// A ref is a path, not prose: `internal/account` or `deps.go`, never "2 kinds (bank/broker)".
+const looksLikePath = (s) => /^[\w.@~-]+([/\\][\w.@~ -]+)*$/.test(s) && (s.includes('/') || /\.\w+$/.test(s))
+
+const cells = (line) => line.split('|').slice(1, -1).map((c) => c.trim())
+const isRule = (line) => /^\|[\s:|-]+\|$/.test(line.trim())
+
+// Every pipe table in the text, as [header, ...rows] of equal width. A malformed row is dropped,
+// not repaired: a half-parsed row would put arbitrary text in a stakeholder's box.
+function tables(text) {
+  const out = []
+  let cur = null
+  for (const raw of String(text).replace(/\r\n/g, '\n').split('\n')) {
+    const line = raw.trim()
+    if (line.startsWith('|') && line.endsWith('|') && line.length > 2) {
+      if (isRule(line)) continue
+      const row = cells(line)
+      if (!cur) cur = { header: row, rows: [] }
+      else if (row.length === cur.header.length) cur.rows.push(row)
+    } else if (cur) { if (cur.rows.length) out.push(cur); cur = null }
+  }
+  if (cur && cur.rows.length) out.push(cur)
+  return out
+}
+
+const roleIndex = (header, role, override) => {
+  if (override) return header.findIndex((h) => h.toLowerCase() === String(override).toLowerCase())
+  return header.findIndex((h) => ROLES[role].test(h))
+}
+
+// Path tokens in a cell: backticked first (the markdown convention), else comma-separated.
+function refsIn(cell) {
+  const ticked = [...String(cell).matchAll(/`([^`]+)`/g)].map((m) => normRef(m[1]))
+  const raw = ticked.length ? ticked : String(cell).split(',').map(normRef)
+  return [...new Set(raw.filter(looksLikePath))]
+}
+
+/**
+ * Read every `docSources` entry into flat rows.
+ * @param inventoryOnly require a status column too. `forma init` sets it when AUTO-DETECTING a
+ *   source: "feature + file" is also the shape of a change plan ("C1 translator import |
+ *   decision/ChildTimeline.tsx"), and auto-adopting one of those would put a task line in a
+ *   stakeholder's box — inventing, which is the one thing this must never do. An inventory says
+ *   whether each capability is finished; a work plan does not. A source listed BY HAND is trusted
+ *   as-is, status column or not.
+ * @returns {{text:string, refs:string[], done:boolean|null, from:string}[]}
+ */
+export function loadDocRows(repo, docSources, inventoryOnly = false) {
+  const out = []
+  for (const entry of docSources || []) {
+    // Normalize FIRST: a bare-string source is not an options bag, and probing one for `.ref` or
+    // `.match` reaches String.prototype instead of undefined — a truthy "override" that silently
+    // matched no column and made every capability table parse to zero rows.
+    const src = typeof entry === 'string' ? { path: entry } : (entry || {})
+    const rel = src.path
+    if (!rel) continue
+    const abs = join(repo, rel)
+    if (!existsSync(abs)) continue
+    let text
+    try { text = readFileSync(abs, 'utf-8') } catch { continue }
+    for (const t of tables(text)) {
+      const iD = roleIndex(t.header, 'describe', src.describe)
+      const iM = roleIndex(t.header, 'ref', src.ref)
+      if (iD < 0 || iM < 0) continue // not a capability table — a changelog or a config table
+      const iS = roleIndex(t.header, 'status', src.status)
+      if (inventoryOnly && iS < 0) continue // see loadDocRows' third argument
+      for (const r of t.rows) {
+        const refs = refsIn(r[iM])
+        const txt = String(r[iD]).replace(/[*_`]+/g, '').replace(/\s+/g, ' ').trim()
+        if (!refs.length || !txt) continue
+        out.push({ text: txt.slice(0, 240), refs, done: iS < 0 ? null : DONE.test(String(r[iS]).replace(/[*_`]+/g, '').trim()), from: rel })
+      }
+    }
+  }
+  return out
+}
+
+// A row's ref points AT a node when it names the node's own file/dir, something inside it, or the
+// directory that contains it. `internal/store/account_repo.go` therefore reaches the `internal/store`
+// package and NOT `internal/account` — the join has to be specific or every row lands on every
+// ancestor.
+const touches = (ref, path) => ref === path || ref.startsWith(path + '/') || path.startsWith(ref + '/')
+
+/**
+ * Map every node id to the rows that name it, itself or through its descendants (a Go container's
+ * own evidence is a glob over its PARENT directory, so only its leaves carry the real path).
+ * @returns {Map<string, object[]>}
+ */
+export function indexByNode(rows, nodes) {
+  const byId = new Map(nodes.map((n) => [n.id, n]))
+  const kids = new Map()
+  for (const n of nodes) if (n.parent) kids.set(n.parent, [...(kids.get(n.parent) || []), n.id])
+  const ownPaths = (n) => (n.evidence || []).filter((e) => e.type === 'path').map((e) => normRef(e.ref))
+  const subtree = (id, seen = new Set()) => {
+    if (seen.has(id)) return [] // a malformed parent cycle must not hang gen
+    seen.add(id)
+    const out = [...ownPaths(byId.get(id) || {})]
+    for (const k of kids.get(id) || []) out.push(...subtree(k, seen))
+    return out
+  }
+  const idx = new Map()
+  for (const n of nodes) {
+    const paths = subtree(n.id)
+    if (!paths.length) continue
+    const hit = rows.filter((r) => r.refs.some((ref) => paths.some((p) => touches(ref, p))))
+    if (hit.length) idx.set(n.id, hit)
+  }
+  return idx
+}
+
+// The rows that DESCRIBE a node (past the cap it is only touched by them — see MAX_ROWS).
+export const describingRows = (idx, id) => {
+  const rows = idx.get(id)
+  return rows && rows.length <= MAX_ROWS ? rows : null
+}
+
+// Programme state a document states outright: how many of the capabilities living in this node are
+// finished. Derived, never curated — the c4-status.json overlay still overrides it (gen.mjs §WP-A1),
+// and `check` re-derives it from the same document rather than trusting the committed model.
+export function statusFor(idx, id) {
+  const rows = describingRows(idx, id)
+  if (!rows || rows.some((r) => r.done == null)) return null // no status column: describe only
+  const done = rows.filter((r) => r.done).length
+  return {
+    status2: done === rows.length ? 'done' : done === 0 ? 'planned' : 'in-progress',
+    completion: Math.round((done / rows.length) * 100),
+    source: `${rows[0].from} (${done}/${rows.length} done)`,
+  }
+}

package/lib/enrich.mjs

@@ -36,15 +36,21 @@ export function descInputHash(node, ctx) {
 
 function promptFor(node, ctx, opts = {}) {
   const { cont, siblings } = siblingsOf(node, ctx)
+  // A container is its OWN container: unguarded, the prompt tells the model that "auth" belongs to
+  // the container "auth" and calls its own children its siblings. Its filesystem pointer is a glob
+  // over its directory, not a path, so it also had nothing to read.
+  const self = cont === node.id
   const contName = (ctx.byId && ctx.byId.get(cont) || {}).name || cont || 'the system'
   const path = (node.evidence || []).find((e) => e.type === 'path')
+  const glob = !path && (node.evidence || []).find((e) => e.type === 'glob')
   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(', ')}.` : '',
+    `In ONE plain sentence (max 18 words), say what the software ${self ? 'module group' : 'module'} "${node.name}" does.`,
+    self ? '' : `It belongs to the container "${contName}".`,
+    siblings.length ? `${self ? 'The modules it holds' : '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.` : '',
+    (opts.canRead && glob) ? `Read the sources under ${glob.ref}/ if you need certainty.` : '',
     'Answer with the sentence only — no preamble, no quotes.',
   ].filter(Boolean).join('\n')
 }
@@ -103,8 +109,11 @@ export function mergeCache(nodes, cache) {
 }
 
 // The holes an enricher would fill: never-described nodes, plus llm prose whose inputs moved.
+// Containers count. They were excluded on the theory that the topology describes them — but on a
+// repo with no curated topology (i.e. anything `forma init` seeded) they are exactly the boxes
+// left on a measured fallback, and the biggest ones on screen.
 export function holesIn(nodes, ctx) {
-  return nodes.filter((n) => (n.kind === 'leaf' || n.kind === 'component') &&
+  return nodes.filter((n) => (n.kind === 'leaf' || n.kind === 'component' || n.kind === 'container') &&
     (n.descSource === 'fallback' || (n.descSource === 'llm' && n.descInputHash !== descInputHash(n, ctx))))
 }
 

package/lib/gen.mjs

@@ -7,18 +7,21 @@ 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 { isGo, goEdges } from './lang.mjs'
 import { makeDescribeCtx, resolveDescription } from './describe.mjs'
+import { loadDocRows, indexByNode, describingRows, statusFor } from './docmap.mjs'
 import { loadCache, mergeCache, enrich, agentPlan, applyFills } from './enrich.mjs'
+import { validateModel } from './validate.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.3.0'
+const SCHEMA_VERSION = '1.5.0' // +descSource:"docmap" (additive enum value → MINOR)
 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 ENRICHER = arg('--enricher', null)
 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')
@@ -31,6 +34,12 @@ const fail = (m) => { console.error('[gen-c4] FAIL: ' + m); process.exit(1) }
 // (`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)
+// §7 has no default provider ON PURPOSE. It used to be `anthropic`, i.e. the one path that needs
+// an API key most people have not exported — so `--enrich` "worked", printed a skip line, exited 0
+// and left every box empty: the defect this command exists to fix, reintroduced by its own default.
+// Flipping the default to `agent` would be just as silent the other way (a CI job with a key would
+// quietly stop filling boxes and start writing a plan file). So: choose, explicitly.
+if (ENRICH && !ENRICHER) fail('--enrich needs an explicit --enricher: `agent` (no key — an agent writes the prose, see --enrich-apply), `anthropic`/`openai` (REST, needs the API key in the environment), `ollama` (localhost), or `echo` (offline, testing).')
 
 function walk(spec) {
   const dir = rp(spec.dir)
@@ -69,7 +78,10 @@ for (const spec of topo.leafSources) {
       id: `${spec.parent}__${f.replace(/[^a-z0-9]+/gi, '_')}`,
       level: 'leaf', parent: spec.parent, kind: 'leaf',
       name: f.replace(/\.[a-z0-9]+$/i, ''), status: 'current',
-      evidence: [{ type: 'path', ref: `${spec.dir}/${f}` }],
+      // `dir: "."` (loose top-level sources, or a Go package at the module root) must not produce
+      // "./x": the ref is a repo-relative key, and the oracle caught the Go adapter failing to map
+      // "./migrations" back to the import path <module>/migrations.
+      evidence: [{ type: 'path', ref: spec.dir === '.' ? f : `${spec.dir}/${f}` }],
     })
   }
   // attach glob count to the parent (drift anchor)
@@ -114,12 +126,27 @@ if (CLUSTER) for (const cid of [...new Set(topo.leafSources.map((s) => s.parent)
   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
+// §docmap) join the repo's own capability tables to the nodes, ONCE: the same match feeds both the
+// description (§1a below) and the programme state derived just under here.
+const docRows = loadDocRows(REPO, topo.docSources)
+const docIndex = indexByNode(docRows, nodes)
+if (docRows.length) console.log(`[gen-c4] docSources: ${docRows.length} row(s) → ${docIndex.size} node(s) touched, ${nodes.filter((n) => describingRows(docIndex, n.id)).length} described`)
+
+// enrich: fill hologram defaults (category, 6-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
+  // Progress a DOCUMENT states outright — the only generated alternative to hand-writing the
+  // overlay. Derived, so it is re-derived by `check` rather than trusted; the curated overlay
+  // (§WP-A1, applied further down) still overrides every field of it.
+  const ds = !n.status2 ? statusFor(docIndex, n.id) : null
+  if (ds) { n.status2 = ds.status2; if (n.completion == null) n.completion = ds.completion; if (!n.verify) n.verify = { source: ds.source } }
+  // Code can prove a file EXISTS; it cannot prove the work behind it is finished. Marking every
+  // undecorated node done/100 turned a virgin repo into a board reading "10/10 complete" — the
+  // exact false green this tool exists to kill. No overlay (§WP-A1), no verdict: `unknown`, and
+  // no completion at all (a percentage nobody curated is a made-up number, including 0).
+  if (!n.status2) n.status2 = n.status === 'planned' ? 'planned' : 'unknown'
+  if (n.completion == null && n.status === 'planned') n.completion = 0
   // `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.
@@ -128,7 +155,7 @@ for (const n of nodes) {
 
 // §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 })
+const dctx = makeDescribeCtx({ repo: REPO, byId, descriptions: topo.descriptions || {}, docPath: topo.docPath, containerOf, docIndex })
 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
@@ -138,7 +165,7 @@ for (const n of nodes) { const r = resolveDescription(n, dctx); n.func = r.func;
 const firstSentence = (s) => (String(s).match(/^[^.!?]*[.!?]/) || [String(s)])[0].trim()
 for (const n of nodes) {
   if (n.kind !== 'component' || n.descSource !== 'fallback') continue
-  const kids = nodes.filter((k) => k.parent === n.id && ['curated', 'docstring', 'readme'].includes(k.descSource))
+  const kids = nodes.filter((k) => k.parent === n.id && ['curated', 'docmap', '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
@@ -208,7 +235,13 @@ if (ENRICH && ENRICHER === 'agent') {
 // code itself: for each container, count how many of ANOTHER container's exposed leaf names (class/
 // module names) appear as whole-word references in this container's files. count>0 ⇒ a real edge.
 // Language-agnostic (matches symbol names, not import syntax). Additive: never removes curated edges.
-if (!process.argv.includes('--no-auto-edges')) {
+// A language that DECLARES its dependencies gets its adapter instead (lib/lang.mjs): guessing from
+// names where an `import` block states the fact is strictly worse, and gets the direction wrong.
+if (!process.argv.includes('--no-auto-edges') && isGo(topo.meta && topo.meta.stack)) {
+  const derived = goEdges({ repo: REPO, nodes, byId, containerOf, edges: topo.edges })
+  topo.edges = [...(topo.edges || []), ...derived]
+  console.log(`[gen-c4] auto-edges: +${derived.length} container edge(s) derived from Go import blocks`)
+} else if (!process.argv.includes('--no-auto-edges')) {
   const STOP = new Set(['index', 'main', 'app', 'utils', 'util', 'types', 'model', 'base', 'core', 'const', 'style', 'theme'])
   const srcs = (topo.leafSources || []).filter((s) => byId.has(s.parent))
   const exposes = new Map(), text = new Map()
@@ -226,7 +259,11 @@ if (!process.argv.includes('--no-auto-edges')) {
     for (const to of exposes.keys()) {
       if (to === from || have.has(from + '|' + to)) continue
       let c = 0
-      for (const nm of exposes.get(to)) { if (new RegExp('\\b' + nm.replace(/[^\w]/g, '') + '\\b').test(t)) c++ }
+      // A module name is matched VERBATIM (metacharacters escaped, never deleted: stripping them
+      // turned "session-store" into /\bsessionstore\b/, which matches nothing — every kebab-case
+      // repo, i.e. most JS/TS ones, rendered edges=0). `-` and `.` are word separators here, so
+      // the boundary is spelled out instead of using \b (which sits INSIDE "session-store").
+      for (const nm of exposes.get(to)) { if (new RegExp('(^|[^\\w-])' + nm.replace(/[.*+?^${}()|[\]\\\/-]/g, '\\$&') + '([^\\w-]|$)').test(t)) c++ }
       if (c > 0) { derived.push({ from, to, label: c + '×', kind: 'import', estatus: 'active' }); have.add(from + '|' + to); have.add(to + '|' + from) }
     }
   }
@@ -283,6 +320,10 @@ if (process.argv.includes('--from-docs')) {
   } catch (e) { model.meta.verifyError = 'from-docs: ' + String((e && e.message) || e) }
 }
 writeFileSync(OUT, JSON.stringify(model, null, 2) + '\n')
+// topo.nodes are copied verbatim into the model (pass 1), so a bad curated kind used to leak in
+// and only fail later — this catches it immediately and keeps invalid artifacts from being written.
+const schemaErrors = validateModel(model)
+if (schemaErrors.length) fail('model does not validate against lib/schema/c4-model.schema.json:\n - ' + schemaErrors.join('\n - '))
 const counts = { total: nodes.length, leaves: nodes.filter((n) => n.kind === 'leaf').length, planned: nodes.filter((n) => n.status === 'planned').length }
 console.log(`[gen-c4] wrote ${OUT}`)
 console.log(`[gen-c4] nodes=${counts.total} leaves=${counts.leaves} planned=${counts.planned} edges=${model.edges.length} commit=${commit.slice(0,8)}`)

package/lib/init.mjs

@@ -5,6 +5,8 @@
 // existing topology unless --force.
 import { readdirSync, statSync, existsSync, writeFileSync, mkdirSync } from 'node:fs'
 import { join, relative, basename } from 'node:path'
+import { goPackages } from './lang.mjs'
+import { loadDocRows } from './docmap.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())
@@ -55,20 +57,24 @@ function javaBase() {
   }
   return d
 }
-const root = ext[0] === 'java' ? (javaBase() || REPO) : (existsSync(join(REPO, 'src')) ? join(REPO, 'src') : REPO)
+// Go modules are rooted at go.mod, never at src/ — an import path is relative to the module root.
+const root = ext[0] === 'java' ? (javaBase() || REPO) : ext[0] === 'go' ? REPO : (existsSync(join(REPO, 'src')) ? join(REPO, 'src') : REPO)
+const GO = ext[0] === 'go'
+const notSrc = GO ? /_test\.go$/ : null // a test file is not architecture (§Go adapter)
 
 // 3) build nodes + leafSources: one container per immediate subdir that holds source files directly
 const sysId = slug(basename(REPO))
 const nodes = [{ id: sysId, level: 'context', kind: 'system', name: basename(REPO), tech: lang, description: `${basename(REPO)} — drill for containers.` }]
 const leafSources = []
-const hasSrc = (dir) => { try { return readdirSync(dir).some((f) => { const p = join(dir, f); return statSync(p).isFile() && new RegExp(matchRe).test(f) }) } catch { return false } }
+const hasSrc = (dir) => { try { return readdirSync(dir).some((f) => { const p = join(dir, f); return statSync(p).isFile() && new RegExp(matchRe).test(f) && !(notSrc && notSrc.test(f)) }) } catch { return false } }
 
 // Recurse to the SHALLOWEST dirs that directly contain source files → each is a container.
 // (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) {
+const claim = (rel) => { let id = slug(rel.replace(/[\\/]+/g, '_')); if (seen.has(id)) id = slug(id + '_' + leafSources.length); seen.add(id); return id }
+const findContainers = (dir, depth) => {
   if (depth > 10) return
   let ents; try { ents = readdirSync(dir) } catch { return }
   for (const e of ents.filter((x) => !IGNORE.has(x) && !x.startsWith('.')).sort()) {
@@ -77,20 +83,55 @@ const skipped = []
     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, '_'))
-      if (seen.has(id)) id = slug(id + '_' + leafSources.length)
-      seen.add(id)
+      const id = claim(relative(root, p) || e)
       nodes.push({ id, level: 'container', kind: 'container', parent: sysId, name: e, tech: lang })
       leafSources.push({ parent: id, dir: relative(REPO, p), match: matchRe })
     } else findContainers(p, depth + 1)
   }
-})(root, 0)
+}
+const skipDir = (e) => IGNORE.has(e) || e.startsWith('.') || (SKIP_DIRS.has(e.toLowerCase()) && !KEEP.has(e.toLowerCase()))
+
+// Go: the container is the PACKAGE, not the shallowest directory that happens to hold code. Go
+// nests packages freely (internal/store, internal/server, …) and `internal/` itself is usually not
+// one — stopping at the first level collapses thirty units of architecture into a single box. The
+// leaf is the package too: the files inside it are internal organisation nobody presents, so the
+// leafSource points at the parent directory and matches the package directory by name (a leaf must
+// stay a real, re-derivable entry on disk — that is what the drift gate re-counts).
+if (GO) {
+  for (const rel of goPackages(root, skipDir)) {
+    // ponytail: a package at the module ROOT falls through to the loose-files branch below, which
+    // keeps the old file-per-leaf shape (there is no parent directory to match its name in). Its
+    // box is real but stays edge-less, since goEdges only follows directory leaves. Rare layout —
+    // give the root package its own directory (cmd/…) and it behaves like every other one.
+    if (!rel) continue
+    const cut = rel.lastIndexOf('/')
+    const id = claim(rel)
+    nodes.push({ id, level: 'container', kind: 'container', parent: sysId, name: rel, tech: lang })
+    leafSources.push({ parent: id, dir: cut < 0 ? '.' : rel.slice(0, cut), match: '^' + rel.slice(cut + 1).replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '$', filesOnly: false })
+  }
+} else findContainers(root, 0)
 // 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 (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, ...(GO ? { exclude: '_test\\.go$' } : {}) }) }
 
 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) }
 
+// 4) find the documents that already say, in prose, what each part of the product does and whether
+// it is finished — a feature matrix, a capability table, a requirements sheet. Detection is the
+// reader itself: a doc qualifies when `loadDocRows` gets capability rows out of it, so nothing here
+// can drift from what `gen` will actually parse, and no project's filenames are hardcoded.
+// Threshold 3: a two-row table in a runbook is a config note, not a capability inventory.
+const docSources = []
+;(function findDocs(dir, depth) {
+  if (depth > 4) return
+  let ents; try { ents = readdirSync(dir) } catch { return }
+  for (const e of ents.filter((x) => !IGNORE.has(x) && !x.startsWith('.')).sort()) {
+    const p = join(dir, e)
+    let st; try { st = statSync(p) } catch { continue }
+    if (st.isDirectory()) findDocs(p, depth + 1)
+    else if (/\.md$/i.test(e) && loadDocRows(REPO, [relative(REPO, p)], true).length >= 3) docSources.push(relative(REPO, p))
+  }
+})(join(REPO, 'docs'), 0)
+
 const topo = {
   meta: { repo: basename(REPO), stack: lang, seededBy: 'forma init' },
   docPath: 'docs/architecture/ARCHITECTURE.md',
@@ -98,6 +139,9 @@ const topo = {
   nodes,
   leafSources,
   edges: [],
+  // Capability tables: the box text and the progress for context/container come from HERE first,
+  // ahead of the code. Each entry is a path, or {path, describe, ref, status} to name the columns.
+  docSources,
   descriptions: {},
   _skipped: skipped,
 }
@@ -105,4 +149,5 @@ const topo = {
 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) || '.'}/${skipped.length ? `, ${skipped.length} data/doc dir(s) skipped` : ''}`)
+if (docSources.length) console.log(`[forma init] docSources: ${docSources.join(', ')} — capability rows will describe the containers they name.`)
 console.log('[forma init] NEXT: curate names/descriptions + add context externals + run `forma gen`.')

package/lib/lang.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// lang.mjs — per-language adapters for TOPOLOGY and EDGES. Pure, no side effects at import.
+//
+// The name-matching heuristic in gen.mjs is the fallback for stacks that never say what depends on
+// what. Some languages do say it, and guessing where a declaration exists is strictly worse. Go is
+// the first case: its unit of architecture is the PACKAGE (any directory holding non-test *.go),
+// and its dependency edge is the `import` block — both machine-readable, both unambiguous.
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+// `forma init` writes meta.stack = 'Go'; a hand-curated topology opts in the same way.
+export const isGo = (stack) => /^go\b/i.test(String(stack || ''))
+
+// ponytail: name-based, no build-constraint evaluation — a file carrying `//go:build ignore` (or a
+// tag not in the default build) still counts, so forma can see a package `go list` does not. The
+// import it declares is real source either way; upgrade to reading the constraint line if it bites.
+const isGoSrc = (f) => /\.go$/.test(f) && !/_test\.go$/.test(f)
+const posix = (p) => String(p).replace(/\\/g, '/')
+
+// Every directory under `root` holding at least one NON-TEST .go file is a package. Recurses past
+// packages (Go nests them freely) and returns repo-relative posix dirs, sorted, '' for the module
+// root. `skip(name)` filters directories (build junk, vendor/, data dirs) — the caller owns that
+// policy so init keeps one source of truth for it.
+export function goPackages(root, skip) {
+  const out = []
+  ;(function walk(dir, rel, depth) {
+    if (depth > 12) return
+    let ents; try { ents = readdirSync(dir).sort() } catch { return }
+    let src = false
+    const subs = []
+    for (const e of ents) {
+      let st; try { st = statSync(join(dir, e)) } catch { continue }
+      if (st.isDirectory()) { if (!skip(e)) subs.push(e) } else if (isGoSrc(e)) src = true
+    }
+    if (src) out.push(rel)
+    for (const s of subs) walk(join(dir, s), rel ? rel + '/' + s : s, depth + 1)
+  })(root, '', 0)
+  return out
+}
+
+// The import paths a package declares, one entry per (file, path) pair so the count is "how many
+// files import this". Handles `import "x"`, grouped `import ( … )`, aliases (`foo "x"`, `. "x"`,
+// `_ "x"`) and trailing comments. Test files are excluded, so are their imports.
+// ponytail: regex over gofmt'd source, no AST — an unformatted `import(` block on one line is missed.
+export function goImports(absDir) {
+  const out = []
+  let files; try { files = readdirSync(absDir).filter(isGoSrc).sort() } catch { return out }
+  for (const f of files) {
+    let src; try { src = readFileSync(join(absDir, f), 'utf-8') } catch { continue }
+    const here = new Set()
+    for (const m of src.matchAll(/^import\s*\(([\s\S]*?)^\)/gm)) {
+      for (const line of m[1].split('\n')) {
+        const q = line.replace(/\/\/.*$/, '').trim().match(/"([^"]+)"$/)
+        if (q) here.add(q[1])
+      }
+    }
+    for (const m of src.matchAll(/^import\s+(?:[\w.]+\s+)?"([^"]+)"/gm)) here.add(m[1])
+    out.push(...[...here].sort())
+  }
+  return out
+}
+
+const goModulePath = (repo) => {
+  try { return (readFileSync(join(repo, 'go.mod'), 'utf-8').match(/^module\s+(\S+)/m) || [])[1] || null } catch { return null }
+}
+
+// Container→container edges from the import blocks. A Go package leaf carries its own DIRECTORY as
+// path evidence, so the model itself says which directory each container is — no id convention to
+// keep in sync. Only intra-module imports become edges (the stdlib and third parties are outside
+// the model). Direction is right by construction: from = the importer.
+// Deliberately NOT the bidirectional dedup the heuristic pass uses — a declared import is a fact,
+// and a curated edge pointing the other way must not suppress it.
+export function goEdges({ repo, nodes, byId, containerOf, edges }) {
+  const mod = goModulePath(repo)
+  if (!mod) return []
+  const pkgs = []
+  for (const n of nodes) {
+    if (n.kind !== 'leaf') continue
+    const ev = (n.evidence || []).find((e) => e.type === 'path')
+    if (!ev) continue
+    try { if (!statSync(join(repo, ev.ref)).isDirectory()) continue } catch { continue }
+    pkgs.push({ dir: posix(ev.ref), container: containerOf(n, byId) })
+  }
+  const byImport = new Map(pkgs.map((p) => [p.dir === '.' ? mod : mod + '/' + p.dir, p.container]))
+  const have = new Set((edges || []).map((e) => e.from + '|' + e.to))
+  const out = []
+  for (const p of pkgs) {
+    const counts = new Map()
+    for (const imp of goImports(join(repo, p.dir))) {
+      const to = byImport.get(imp)
+      if (!to || to === p.container) continue
+      counts.set(to, (counts.get(to) || 0) + 1)
+    }
+    for (const [to, c] of [...counts].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+      const k = p.container + '|' + to
+      if (have.has(k)) continue
+      have.add(k)
+      out.push({ from: p.container, to, label: c + '×', kind: 'import', estatus: 'active' })
+    }
+  }
+  return out
+}

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

@@ -179,9 +179,10 @@
               "in-progress",
               "next",
               "planned",
-              "problem"
+              "problem",
+              "unknown"
             ],
-            "description": "Hologram completion status (colour)."
+            "description": "Hologram completion status (colour). `unknown` is the default for a node no curated overlay has ruled on — code proves existence, never completion."
           },
           "completion": {
             "type": "integer",
@@ -219,13 +220,14 @@
             "type": "string",
             "enum": [
               "curated",
+              "docmap",
               "docstring",
               "readme",
               "arc42",
               "fallback",
               "llm"
             ],
-            "description": "Provenance of func: how the description was resolved (§1a chain; 'llm' = optional enrichment)."
+            "description": "Provenance of func: how the description was resolved (§1a chain; 'docmap' = a capability row in a repo document; 'llm' = optional enrichment)."
           },
           "descInputHash": {
             "type": "string",

package/lib/validate.mjs

@@ -0,0 +1,66 @@
+// validate.mjs — hold the model to the schema it declares. Shared by `gen` (after write) and `check`.
+
+// Zero deps (ADR-0001), so the engine is a hand-written walker over the ONLY keywords the
+// shipped lib/schema/c4-model.schema.json uses:
+//   type (object|array|string|integer|number|boolean|null), required, properties,
+//   additionalProperties (enforced only where it is literally false), items (single schema, no
+//   tuple form), enum, minItems, minimum, maximum, pattern.
+// Annotation-only keywords are read and deliberately NOT enforced: $schema, $id, title,
+// description, default, format — `format: "date-time"`/`"uri"` are not checked, exactly as ajv
+// without ajv-formats treats them in draft-07.
+// This is NOT a general JSON Schema engine. A third-party schema using oneOf/allOf/$ref/
+// patternProperties/tuple items/dependencies would be silently UNDER-validated: the unknown
+// keyword is ignored, never an error. Widen this file before pointing it at another schema.
+import { readFileSync } from 'node:fs'
+
+const typeIsObject = (v) => v !== null && !Array.isArray(v) && typeof v === 'object'
+const jsType = (v) => v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v
+const typeOk = (value, type) => {
+  if (type === 'object') return typeIsObject(value)
+  if (type === 'array') return Array.isArray(value)
+  if (type === 'string') return typeof value === 'string'
+  if (type === 'integer') return Number.isInteger(value)
+  if (type === 'number') return typeof value === 'number'
+  if (type === 'boolean') return typeof value === 'boolean'
+  if (type === 'null') return value === null
+  return true
+}
+const formatTypeError = (path, expected, value) => path + ': expected ' + expected + ', got ' + jsType(value)
+const childPath = (path, key) => (path === '<root>' ? key : path + '.' + key)
+const enumText = (set) => set.map((v) => typeof v === 'string' ? v : String(v)).join(', ')
+const validateAgainstSchema = (value, schema, path, errs) => {
+  const declared = schema.type || null
+  if (declared && !typeOk(value, declared)) { errs.push(formatTypeError(path, declared, value)); return }
+  if (schema.required && typeIsObject(value)) {
+    for (const key of schema.required) if (!Object.prototype.hasOwnProperty.call(value, key)) errs.push(path + ': missing required property "' + key + '"')
+  }
+  if (schema.properties && typeIsObject(value)) {
+    for (const [k, s] of Object.entries(schema.properties)) {
+      if (!Object.prototype.hasOwnProperty.call(value, k)) continue
+      validateAgainstSchema(value[k], s, childPath(path, k), errs)
+    }
+  }
+  if (schema.additionalProperties === false && typeIsObject(value)) {
+    for (const key of Object.keys(value)) if (!schema.properties || !Object.prototype.hasOwnProperty.call(schema.properties, key)) errs.push(path + ': unexpected property "' + key + '" (additionalProperties: false)')
+  }
+  if (Array.isArray(value) && schema.items && typeof schema.items === 'object') {
+    value.forEach((item, i) => validateAgainstSchema(item, schema.items, path + '[' + i + ']', errs))
+  }
+  // outside the items branch on purpose: minItems constrains the array, not its element schema
+  if (schema.minItems != null && Array.isArray(value) && value.length < schema.minItems) errs.push(path + ': expected at least ' + schema.minItems + ' item, got ' + value.length)
+  if (schema.enum && schema.enum.includes(value) === false) {
+    const expected = enumText(schema.enum)
+    errs.push(path + ': ' + JSON.stringify(value) + ' is not one of [' + expected + ']')
+  }
+  if (schema.minimum != null && typeof value === 'number' && value < schema.minimum) errs.push(path + ': ' + value + ' is less than the minimum ' + schema.minimum)
+  if (schema.maximum != null && typeof value === 'number' && value > schema.maximum) errs.push(path + ': ' + value + ' is greater than the maximum ' + schema.maximum)
+  if (schema.pattern && typeof value === 'string' && !new RegExp(schema.pattern).test(value)) errs.push(path + ': ' + JSON.stringify(value) + ' does not match ' + schema.pattern)
+}
+
+export const validateModel = (model, schemaPath = new URL('./schema/c4-model.schema.json', import.meta.url)) => {
+  let schema
+  try { schema = JSON.parse(readFileSync(schemaPath, 'utf-8')) } catch (e) { return ['<root>: unable to read schema - ' + String((e && e.message) || e)] }
+  const errs = []
+  validateAgainstSchema(model, schema, '<root>', errs)
+  return errs
+}

package/lib/viewer/c4-hologram.html

@@ -9,7 +9,7 @@
  --bg:#050d14; --grid:rgba(62,231,255,.04); --halo:rgba(62,231,255,.10);
  --cyan:#3ee7ff; --sec:#6fa8bc; --ter:#4c7f94; --ter2:#41738a; --nm:#bfe9f7;
  --stagebg:rgba(4,12,19,.72); --stageborder:#143547; --nodebg:rgba(8,26,38,.92); --detailbg:rgba(6,20,30,.97);
- --border:#1e4a5e; --done:#2fe08a; --prog:#ffc74d; --next:#3ee7ff; --plan:#2d5a72; --planTxt:#7fb3c6; --prob:#ff5d5d;
+ --border:#1e4a5e; --done:#2fe08a; --prog:#ffc74d; --next:#3ee7ff; --plan:#2d5a72; --planTxt:#7fb3c6; --prob:#ff5d5d; --unk:#7d8f99;
  --edge:#2b6e8a; --edgeplan:#264d61; --elbl:#3d7f9c; --ddtxt:#7fb3c6; --now:#cfeefb; --tgt:#8fd8ec; --src:#4fbf8d;}
 *{box-sizing:border-box;margin:0;padding:0}
 body{font-family:"SF Mono",Menlo,Consolas,ui-monospace,monospace;background:var(--bg);color:var(--nm);overflow-x:hidden}
@@ -60,6 +60,8 @@ svg{width:100%;height:100%;display:block}
 .s-plan .tt,.s-plan .pp{fill:var(--planTxt)}
 .s-prob rect{stroke:var(--prob);filter:drop-shadow(0 0 8px rgba(255,93,93,.6))}
 .s-prob .tt,.s-prob .pp{fill:var(--prob)}
+.s-unk rect{stroke:var(--unk);stroke-dasharray:1 3}
+.s-unk .tt,.s-unk .pp{fill:var(--unk)}
 .mode-t .nd rect{stroke:var(--next)!important;stroke-dasharray:none!important;filter:drop-shadow(0 0 8px rgba(62,231,255,.5))!important}
 .mode-t .nd .tt,.mode-t .nd .pp{fill:var(--next)!important}
 .edge{stroke:var(--edge);stroke-width:1.3;fill:none;marker-end:url(#ar);cursor:help}
@@ -119,7 +121,7 @@ svg{width:100%;height:100%;display:block}
 html[data-skin="blueprint"]{--bg:#eef3f9;--grid:rgba(31,119,180,.10);--halo:rgba(31,119,180,.08);
  --cyan:#1f77b4;--sec:#5a6b7d;--ter:#6b7b8c;--ter2:#5a6b7d;--nm:#16273a;
  --stagebg:#ffffff;--stageborder:rgba(31,119,180,.25);--nodebg:#ffffff;--detailbg:#ffffff;--border:rgba(31,119,180,.35);
- --done:#1f9d57;--prog:#c07a12;--next:#1f77b4;--plan:#8592a3;--planTxt:#5a6b7d;--prob:#d1453b;
+ --done:#1f9d57;--prog:#c07a12;--next:#1f77b4;--plan:#8592a3;--planTxt:#5a6b7d;--prob:#d1453b;--unk:#8a97a3;
  --edge:#8aa0b4;--edgeplan:#b9c6d3;--elbl:#5a6b7d;--ddtxt:#40536a;--now:#16273a;--tgt:#1f5f8a;--src:#1f9d57}
 html[data-skin="blueprint"] h1{text-shadow:none}
 html[data-skin="blueprint"] .s-done rect,html[data-skin="blueprint"] .s-prog rect,html[data-skin="blueprint"] .s-next rect,html[data-skin="blueprint"] .s-prob rect{filter:none}
@@ -160,6 +162,7 @@ html[data-skin="blueprint"] button.on{text-shadow:none}
   <span><i style="background:#3ee7ff"></i><span id="lg-next"></span></span>
   <span><i style="background:#2d5a72"></i><span id="lg-plan"></span></span>
   <span><i style="background:#ff5d5d"></i><span id="lg-prob"></span></span>
+  <span><i style="background:#7d8f99"></i><span id="lg-unk"></span></span>
   <span class="hint" id="lg-hint"></span>
  </div>
  <div id="detail"></div>
@@ -176,6 +179,7 @@ var STRINGS={
   resetLayout:"RESET LAYOUT", resetLayoutTitle:"re-arrange",
   printExport:"PRINT / EXPORT", exportSvg:"Export SVG", exportPng:"Export PNG", exportLayout:"Export layout JSON", print:"Print",
   legDone:"DONE (proven)", legProg:"IN PROGRESS", legNext:"NEXT", legPlan:"PLAN ONLY", legProb:"PROBLEM",
+  legUnk:"UNKNOWN (no curated state)", stUnk:"?",
   legHint:"— animated arrow = active flow · dashed = to build",
   crumbRoot:"Context", crumbLevel:"C4", lvlContext:"CONTEXT",
   lvlNames:{context:"Context",container:"Container",component:"Components",leaf:"Leaves"},
@@ -195,6 +199,7 @@ var STRINGS={
   resetLayout:"RESET LAYOUT", resetLayoutTitle:"ridisponi",
   printExport:"STAMPA / ESPORTA", exportSvg:"Esporta SVG", exportPng:"Esporta PNG", exportLayout:"Esporta layout JSON", print:"Stampa",
   legDone:"FATTO (provato)", legProg:"IN CORSO", legNext:"PROSSIMO", legPlan:"SOLO PROGETTO", legProb:"PROBLEMA",
+  legUnk:"IGNOTO (stato non curato)", stUnk:"?",
   legHint:"— freccia animata = flusso attivo · tratteggio = da costruire",
   crumbRoot:"Contesto", crumbLevel:"C4", lvlContext:"CONTESTO",
   lvlNames:{context:"Contesto",container:"Container",component:"Componenti",leaf:"Foglie"},
@@ -219,7 +224,7 @@ var CATALOG_THRESHOLD=24; // group of same-category siblings above this collapse
 var LABEL_AUTO_MAX=14;    // above this many arrows in the current level, fixed labels would knot the view
 var LABELS=null;          // null = auto (by arrow count); true/false = user override for this session
 var SKINS=[["holo","◆ holo"],["blueprint","▭ blueprint"]], SKIN_IDS=["holo","blueprint"];
-var STMAP={done:"done","in-progress":"prog",next:"next",planned:"plan",problem:"prob"};
+var STMAP={done:"done","in-progress":"prog",next:"next",planned:"plan",problem:"prob",unknown:"unk"};
 var M=null, stack=[null], mode="now", POS={}, drag=null, justDragged=false, CATNODES={}, FETCHED=false
 var VBOX={}; // last fitted viewBox per level — frozen while dragging so the canvas does not rescale
 function $(i){return document.getElementById(i)}
@@ -258,9 +263,9 @@ function collapseCatalogs(pid,kids){
 }
 function makeCatalogNode(pid,g){
  // Aggregate status: worst-of-a-few heuristic — problem > next > in-progress > planned > done.
- var rank={problem:5,next:4,"in-progress":3,planned:2,done:1},best=0,bestKey="done",done=0,tot=g.members.length;
+ var rank={problem:5,next:4,"in-progress":3,planned:2,unknown:1.5,done:1},best=0,bestKey="unknown",done=0,tot=g.members.length;
  for(var i=0;i<g.members.length;i++){
-  var s2=g.members[i].status2||(g.members[i].status==="planned"?"planned":"done");
+  var s2=g.members[i].status2||(g.members[i].status==="planned"?"planned":"unknown");
   if((rank[s2]||0)>best){best=rank[s2]||0;bestKey=s2;}
   if(s2==="done")done++;
  }
@@ -371,11 +376,11 @@ function draw(animate){
  }
  for(var j=0;j<kids.length;j++){
   var n=kids[j],p=pos[n.id];
-  var st=STMAP[n.status2]||(n.status==="planned"?"plan":"done");
+  var st=STMAP[n.status2]||(n.status==="planned"?"plan":"unk");
   var pulse=(st==="next"||st==="prog")&&mode!=="target"&&!n.__catalog;
   var isCat=!!n.__catalog,dr=!isCat&&hasKids(n.id),cls="nd s-"+st+(dr?" drill":"")+(isCat?" cat":"")+(pulse?" pulse":"");
-  var desc=isCat?(n.count+" "+STR.rosterCount):(mode==="target"?(n.target||n.func||""):(n.current||n.func||n.tech||""));
-  var badge=isCat?String(n.count):(mode==="target"?STR.detTarget:(n.statusWord||(n.completion!=null?n.completion+"%":(n.tech||""))));
+  var desc=isCat?(n.count+" "+STR.rosterCount):(mode==="target"?(n.target||n.func||""):(n.current||n.func||""));
+  var badge=isCat?String(n.count):(mode==="target"?STR.detTarget:(n.statusWord||(n.completion!=null?n.completion+"%":STR.stUnk)));
   // the title runs until the badge, so reserve the badge's actual width (9px text ≈ 5.4px/char)
   // instead of a flat 70px — a fixed reserve clipped names that had all the room they needed
   var tmax=Math.floor((p.w-34-String(badge).length*5.4)/6.7),tt=n.name;
@@ -414,12 +419,12 @@ function draw(animate){
  // its members), so the tally never changes when the catalogue threshold does.
  var cnt={},tot=0,sum=0,nc=0,st3;
  for(j=0;j<realKids.length;j++){
-  st3=STMAP[realKids[j].status2]||(realKids[j].status==="planned"?"plan":"done");
+  st3=STMAP[realKids[j].status2]||(realKids[j].status==="planned"?"plan":"unk");
   cnt[st3]=(cnt[st3]||0)+1;tot++;
   if(realKids[j].completion!=null){sum+=(+realKids[j].completion||0);nc++;}
  }
  if(tot){
-  var DOT={done:"#2fe08a",prog:"#ffc74d",next:"#3ee7ff",plan:"#2d5a72",prob:"#ff5d5d"},ord=["done","prog","next","plan","prob"],agg="";
+  var DOT={done:"#2fe08a",prog:"#ffc74d",next:"#3ee7ff",plan:"#2d5a72",prob:"#ff5d5d",unk:"#7d8f99"},ord=["done","prog","next","plan","prob","unk"],agg="";
   for(j=0;j<ord.length;j++)if(cnt[ord[j]])agg+='<i style="background:'+DOT[ord[j]]+'"></i>'+cnt[ord[j]];
   if(nc)agg+=' &nbsp;'+esc(STR.aggProgress)+' <b>'+Math.round(sum/nc)+'%</b>';
   cb='<span class="agg">'+agg+'</span>'+cb;
@@ -461,7 +466,7 @@ function cssv(v){try{return getComputedStyle(document.documentElement).getProper
 
 function showDetail(n){
  if(n&&n.__catalog)return showRoster(n);
- var src=srcOf(n),cur=n.current||n.func||n.tech||"",showSrc=src&&String(cur).indexOf(src)<0;
+ var src=srcOf(n),cur=n.current||n.func||"",showSrc=src&&String(cur).indexOf(src)<0;
  $("detail").innerHTML='<span class="cl" id="dc">'+esc(STR.detClose)+'</span><h3>'+esc(n.name)+' <span class="cat">· '+esc(n.category||n.kind||"")+(n.tech?" · "+esc(n.tech):"")+'</span></h3>'
   +(n.func?'<div class="row"><span class="lbl">'+esc(STR.detFunc)+'</span><span class="func">'+esc(n.func)+'</span></div>':'')
   +(cur&&cur!==n.func?'<div class="row"><span class="lbl">'+esc(STR.detNow)+'</span><span class="now">'+esc(cur)+'</span></div>':'')
@@ -482,7 +487,7 @@ function showRoster(cat){
  $("detail").innerHTML=head;$("detail").style.display="block";
  var dc=$("dc");if(dc)dc.addEventListener("click",function(){$("detail").style.display="none";});
  function rowHtml(m){
-  var d=m.current||m.func||m.tech||"";
+  var d=m.current||m.func||"";
   var pct=m.completion!=null?(m.completion+"%"):(m.statusWord||"");
   return '<span class="ritem">'+(pct?'<span class="rp">'+esc(pct)+'</span>':'')
    +'<span class="rn">'+esc(m.name)+'</span>'
@@ -587,7 +592,7 @@ function applyStrings(){
  set("pexp",STR.printExport);set("pexpSvg",STR.exportSvg);set("pexpPng",STR.exportPng);
  set("pexpLayout",STR.exportLayout);set("pexpPrint",STR.print);
  set("lg-done",STR.legDone);set("lg-prog",STR.legProg);set("lg-next",STR.legNext);
- set("lg-plan",STR.legPlan);set("lg-prob",STR.legProb);set("lg-hint",STR.legHint);
+ set("lg-plan",STR.legPlan);set("lg-prob",STR.legProb);set("lg-unk",STR.legUnk);set("lg-hint",STR.legHint);
 }
 // ---- FEATURE #2: PRINT / EXPORT (all client-side, offline) ----
 function exportBaseName(){
@@ -604,7 +609,7 @@ function collectSvgCss(){
   if(!rules)continue;
   for(j=0;j<rules.length;j++){var r=rules[j],t=r.cssText||"";
    // keep rules that target svg-internal classes/elements + the color vars on :root/html
-   if(/\.(nd|edge|edgehit|elbl|s-done|s-prog|s-next|s-plan|s-prob|mode-t|tt|kk|dd|pp|plus|cat)\b/.test(t)
+   if(/\.(nd|edge|edgehit|elbl|s-done|s-prog|s-next|s-plan|s-prob|s-unk|mode-t|tt|kk|dd|pp|plus|cat)\b/.test(t)
       ||/(^|[\s,])svg\b/.test(t)||/:root|html\[data-skin/.test(t)){
     // drop animations for a static export (keepdefs stable)
     out.push(t);
@@ -617,7 +622,7 @@ function collectSvgCss(){
 // with the on-screen palette. Returns a "--k:v;--k:v" inline-style string.
 var SVG_VARS=["--bg","--grid","--halo","--cyan","--sec","--ter","--ter2","--nm",
  "--stagebg","--stageborder","--nodebg","--detailbg","--border","--done","--prog",
- "--next","--plan","--planTxt","--prob","--edge","--edgeplan","--elbl","--ddtxt",
+ "--next","--plan","--planTxt","--prob","--unk","--edge","--edgeplan","--elbl","--ddtxt",
  "--now","--tgt","--src"];
 function resolvedVars(){
  var cs;try{cs=getComputedStyle(document.documentElement);}catch(e){return "";}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-arch",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Forma — present your architecture instead of slides. An interactive, stack-agnostic C4 explorer (context → container → component → leaf) generated from your code and kept true to it by a deterministic drift check.",
   "keywords": [
     "architecture",