forma-arch 0.6.0 → 0.7.1

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. You do not have to hand-edit that JSON — `forma gen --status-apply <file>` merges `{"nodes":{"<id>":{…}}}` into it, validating every patch **before** it touches disk, so a rejected fill leaves the committed overlay untouched. It is the state counterpart of `--enrich-apply`, for the fields no document can supply. 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:
@@ -56,7 +74,8 @@ npx forma-arch <command>        # or: npm i -D forma-arch
 | `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 the four. A
+`--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.
@@ -73,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/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)
@@ -73,23 +80,36 @@ function measuredFunc(node, ctx) {
   return `${parts.join(' + ')}: ${names}${kids.length > 3 ? ', …' : '.'}`.slice(0, 240)
 }
 
-export function makeDescribeCtx({ repo, byId, descriptions, docPath, containerOf }) {
-  return { repo, byId, D: descriptions || {}, containerOf, readmeCache: new Map(), arc42: buildArc42Index(repo, docPath) }
+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
@@ -99,6 +119,8 @@ export function resolveDescription(node, ctx) {
     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') {

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/gen.mjs

@@ -2,20 +2,23 @@
 // gen-c4-model.mjs — emit docs/architecture/c4-model.json from real code + curated topology.
 // Leaves are walked LIVE from src/ (always current). Topology/context/runtime-edges are curated.
 // Usage: node gen-c4-model.mjs [--repo <path>] [--topology <path>] [--out <path>]
-import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from 'node:fs'
+import { readFileSync, writeFileSync, readdirSync, existsSync, statSync, mkdirSync } from 'node:fs'
 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.4.0' // +status2:"unknown" (additive enum value → MINOR)
+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', null)
@@ -23,6 +26,7 @@ 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 STATUS_APPLY = arg('--status-apply', null)   // §WP-A7: programme STATE written by that agent
 
 const topo = JSON.parse(readFileSync(TOPO, 'utf-8'))
 const rp = (p) => join(REPO, p)
@@ -75,7 +79,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)
@@ -120,10 +127,25 @@ 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)`)
 }
 
+// §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
+  // A leaf's category is the CONTAINER it belongs to, not its parent's category. Inheriting the
+  // parent's handed every leaf in the repo the literal string "container", and the viewer's
+  // catalogue collapse groups childless siblings BY CATEGORY — so a repo's leaves collapsed into a
+  // single box labelled "container" (53 of them on the Go repo this was measured on). With the real
+  // container they group the way that feature was written for, or stay apart when they belong apart.
+  if (!n.category) n.category = n.kind === 'leaf' ? (byId.get(containerOf(n, byId)) || {}).name || 'leaf' : n.kind
+  // 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
@@ -138,7 +160,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
@@ -148,7 +170,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
@@ -160,6 +182,53 @@ for (const n of nodes) {
 // 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'])
+// One validator, two callers: the overlay FILE below, and --status-apply just above it. A writer
+// that validated differently from the reader would commit a c4-status.json the very next `gen`
+// rejects. Returns the complaints; the caller decides whether that is a fail or a refusal to write.
+function statusPatchErrors(id, patch, known) {
+  const out = []
+  if (!known(id)) out.push(`unknown node id "${id}" — it is not in the model (stale overlay?)`)
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return [...out, `"${id}" must map to an object of state fields`]
+  for (const [k, v] of Object.entries(patch)) {
+    if (k.startsWith('$')) continue // $comment and friends
+    if (!STATUS_FIELDS.has(k)) { out.push(`"${id}" has field "${k}"; allowed: ${[...STATUS_FIELDS].join(', ')}${k === 'func' ? ' (func comes from the docs, not the overlay)' : ''}`); continue }
+    if (k === 'status2' && !STATUS2.has(v)) out.push(`"${id}" status2 "${v}" — expected one of ${[...STATUS2].join('|')}`)
+    if (k === 'completion' && !(Number.isInteger(v) && v >= 0 && v <= 100)) out.push(`"${id}" completion must be an integer 0-100, got ${JSON.stringify(v)}`)
+    if (k === 'issues') {
+      if (!Array.isArray(v)) out.push(`"${id}" issues must be an array`)
+      else for (const is of v) if (!/^#?\d+$/.test(String(is))) out.push(`"${id}" issue ${JSON.stringify(is)} — expected "#123"`)
+    }
+  }
+  return out
+}
+
+// §WP-A7) --status-apply: the WRITER the overlay never had. `c4-status.json` is the authority —
+// every field it sets outranks anything §17 derives from a document — and nothing in the repo has
+// ever written one, so on a fresh repo the authority channel was reachable only by hand-editing
+// JSON. This is the state counterpart of `--enrich-apply`: an agent or a human hands in the fields
+// a document cannot supply, and they land in the curated file, reviewed in the diff like any other.
+if (STATUS_APPLY) {
+  if (!existsSync(STATUS_APPLY)) fail(`--status-apply: file missing: ${STATUS_APPLY}`)
+  let incoming
+  try { incoming = JSON.parse(readFileSync(STATUS_APPLY, 'utf-8')).nodes } catch (e) { fail(`--status-apply: ${STATUS_APPLY} is not valid JSON: ${(e && e.message) || e}`) }
+  if (!incoming || typeof incoming !== 'object' || Array.isArray(incoming)) fail(`--status-apply: ${STATUS_APPLY} must contain {"nodes":{"<id>":{…}}}`)
+  // Validate EVERYTHING before touching disk. A half-written overlay is a file the next `gen`
+  // refuses to read, in a repo where that file is committed.
+  const errs = Object.entries(incoming).flatMap(([id, patch]) => statusPatchErrors(id, patch, (x) => byId.has(x)))
+  if (errs.length) fail(`--status-apply: ${STATUS_APPLY} rejected, ${relative(REPO, STATUS)} left untouched:\n - ` + errs.join('\n - '))
+  let base = { nodes: {} }
+  if (existsSync(STATUS)) {
+    try { base = JSON.parse(readFileSync(STATUS, 'utf-8')) } catch (e) { fail(`--status-apply: existing ${relative(REPO, STATUS)} is not valid JSON: ${(e && e.message) || e}`) }
+    base.nodes = base.nodes || {}
+  }
+  for (const [id, patch] of Object.entries(incoming)) base.nodes[id] = { ...(base.nodes[id] || {}), ...patch }
+  // The first apply on a repo IS the one that creates the overlay, and a repo that has never run
+  // `forma doc` has no docs/architecture/ to create it in.
+  mkdirSync(dirname(STATUS), { recursive: true })
+  writeFileSync(STATUS, JSON.stringify(base, null, 2) + '\n')
+  console.log(`[gen-c4] --status-apply: ${Object.keys(incoming).length} node(s) merged into ${relative(REPO, STATUS)}`)
+}
+
 let statusPath = null
 if (existsSync(STATUS) || STATUS_SET) {
   if (!existsSync(STATUS)) fail(`--status: file missing: ${STATUS}`)
@@ -167,19 +236,10 @@ if (existsSync(STATUS) || STATUS_SET) {
   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 errs = statusPatchErrors(id, patch, (x) => byId.has(x))
+    if (errs.length) fail('status overlay: ' + errs.join('\n[gen-c4] FAIL: status overlay: '))
     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
-    }
+    for (const [k, v] of Object.entries(patch)) { if (!k.startsWith('$')) target[k] = v }
     decorated++
   }
   statusPath = relative(REPO, STATUS)
@@ -218,7 +278,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()
@@ -297,6 +363,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,9 @@
 // existing topology unless --force.
 import { readdirSync, statSync, existsSync, writeFileSync, mkdirSync } from 'node:fs'
 import { join, relative, basename } from 'node:path'
+import { execFileSync } from 'node:child_process'
+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 +58,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,27 +84,76 @@ 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)
+
+// `forma verify` is the one command that derives progress from something other than a claim in a
+// document — the live state of a GitHub issue — and it needs `meta.ghRepo` to know where to look.
+// `init` never wrote it, so on a freshly seeded repo verify had nowhere to point and exited. The
+// remote already says it. Handles scp-style (git@host:owner/repo.git) and URL remotes alike.
+const ghRepo = (() => {
+  let url
+  try { url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: REPO, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() } catch { return null }
+  const m = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(url)
+  return m ? m[1] : null
+})()
+
 const topo = {
-  meta: { repo: basename(REPO), stack: lang, seededBy: 'forma init' },
+  meta: { repo: basename(REPO), stack: lang, seededBy: 'forma init', ...(ghRepo ? { ghRepo } : {}) },
   docPath: 'docs/architecture/ARCHITECTURE.md',
   levels: ['context', 'container', 'component', 'leaf'],
   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 +161,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

@@ -220,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-arch",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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",