forma-arch 0.8.0 → 0.10.0

package/README.md

@@ -8,8 +8,22 @@ them.
 Forma is the companion to `arbiter`: arbiter governs the process, Forma shows the system and
 guarantees the picture matches reality.
 
-**[▶ Live demo](https://LucaDominici.github.io/forma/)** — forma's own architecture, generated by
-forma from this repo on every push to `main`.
+**[▶ Live demo](https://LucaDominici.github.io/forma/)** — **not** this repo. It is `haben`, a
+private 53-package Go application, generated by forma at haben commit `b1bb318`: six domains over
+53 packages, 192 edges read from real `import` blocks, and box text quoted from that repo's own
+feature matrix. A tool proving itself on its own 28 nodes proves nothing you care about.
+
+What you are looking at is checked, not asserted: at that commit `node scripts/presentable.mjs`
+exits 0 on the model — every level under 24 boxes, every box carrying prose rather than a file
+count, every level with more than one box drawing at least one arrow — and `forma check` exits 0
+against haben's source at the same commit. The curation that turns 53 flat packages into six
+domains is one human decision, checked in at [`docs/demo/curate.mjs`](docs/demo/curate.mjs) with
+the commands to rebuild it.
+
+The one thing the demo does not do is regenerate itself: haben is private, so Pages publishes a
+snapshot committed from a local run rather than cloning it in CI. Nothing automated will notice
+if it goes stale. Forma's own model lives in `docs/architecture/` and *is* drift-checked on every
+push.
 
 ## Why
 

package/lib/docmap.mjs

@@ -147,16 +147,36 @@ export function indexByNode(rows, 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)
+    if (hit.length) idx.set(n.id, { rows: hit, cover: coverOf(n, byId, kids, hit, paths) })
   }
   return idx
 }
 
+// How much of a node the rows actually reach. `done / rows.length` answers "of the capabilities
+// somebody wrote down, how many are finished" — never "how much of this module is finished". A
+// container holding 8 files that a matrix names 3 of, all done, reads 100%: the other 5 are not
+// counted as unfinished, they are not counted at all. So the number ships with its own reach.
+// `whole` means a row names the module itself, i.e. the document IS talking about all of it.
+function coverOf(node, byId, kids, hit, paths) {
+  const own = (node.evidence || []).filter((e) => e.type === 'path').map((e) => normRef(e.ref))
+  const whole = hit.some((r) => r.refs.some((ref) => own.some((p) => ref === p || p.startsWith(ref + '/'))))
+  const leaves = (kids.get(node.id) || []).map((k) => byId.get(k)).filter((k) => k && k.kind === 'leaf')
+  const glob = (node.evidence || []).find((e) => e.type === 'glob')
+  // Units = the boxes below it, or — for a node whose children are internal detail (a Go package) —
+  // the file count its own drift anchor already carries.
+  const total = leaves.length || (glob && glob.count) || paths.length
+  if (whole) return { named: total, total, whole: true }
+  const named = new Set()
+  for (const r of hit) for (const ref of r.refs) if (own.some((p) => ref.startsWith(p + '/'))) named.add(ref)
+  return { named: Math.min(named.size, total), total, whole: false }
+}
+
 // 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
+  const e = idx.get(id)
+  return e && e.rows.length <= MAX_ROWS ? e.rows : null
 }
+export const coverageFor = (idx, id) => (idx.get(id) || {}).cover || 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),
@@ -165,9 +185,12 @@ 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
+  const c = coverageFor(idx, id)
   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)`,
+    // The citation says what it is: a repo document declaring itself finished, not a verification.
+    source: `${rows[0].from} (${done}/${rows.length} declared done)`,
+    ...(c ? { coverage: c } : {}),
   }
 }

package/lib/gen.mjs

@@ -165,7 +165,10 @@ for (const n of nodes) {
   const ds = !n.status2 && n.kind !== 'system' ? statusFor(docIndex, n.id) : null
   // `derived: true` is the marker `check` keys off to know this state must keep re-deriving. A
   // string match on the citation would break the moment anyone rewords it.
-  if (ds) { n.status2 = ds.status2; if (n.completion == null) n.completion = ds.completion; if (!n.verify) n.verify = { source: ds.source, derived: true } }
+  // `coverage` rides in `verify` (additionalProperties: true there, so no schema churn) and says how
+  // much of the node the citation actually reaches — the difference between "3 of 3 rows are done"
+  // and "this module is done".
+  if (ds) { n.status2 = ds.status2; if (n.completion == null) n.completion = ds.completion; if (!n.verify) n.verify = { source: ds.source, derived: true, ...(ds.coverage ? { coverage: ds.coverage } : {}) } }
   // 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
@@ -178,6 +181,14 @@ for (const n of nodes) {
   if (n.target == null) n.target = ''
 }
 
+// §33) the context actors `init` seeds are placeholders, and a placeholder nobody renamed is the
+// first screen a stakeholder sees. Not a failure — the model is valid and the rest of it is real —
+// but it must never pass unremarked, so the names are printed back verbatim. Matched on the `TODO:`
+// prefix, which is also what a human writing "TODO: the family" gets, and not on the seeded ids: an
+// actor that was renamed properly keeps its id and must stop being nagged about.
+const anon = nodes.filter((n) => /^TODO:/.test(String(n.name)))
+if (anon.length) console.error(`[gen-c4] note: ${anon.length} context box(es) still unnamed — ${anon.map((n) => `"${n.name}"`).join(', ')}. Rename them in the topology; nothing else derives them.`)
+
 // §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, docIndex })
@@ -301,6 +312,15 @@ if (ENRICH && ENRICHER === 'agent') {
 // 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)) {
+  // Grouping 53 packages into domains is the only cure for a wall of boxes, and the intuitive way
+  // to curate it — stamping `kind: "component"` on the grouped package — takes 189 edges to 13
+  // without a word: goEdges reads a package's directory off its `glob` evidence and skips anything
+  // that is not kind "container". The node still LOOKS right in the JSON. Say it out loud, because
+  // the only other symptom is arrows the reader never knew were supposed to be there.
+  const mute = nodes.filter((n) => n.kind !== 'container' && (n.evidence || []).some((e) => e.type === 'glob'))
+  if (mute.length) console.error(`[gen-c4] WARNING: ${mute.length} node(s) carry glob evidence but kind ≠ "container", so no import edge is derived from them: ` +
+    mute.slice(0, 5).map((n) => `${n.id} (kind "${n.kind}")`).join(', ') + (mute.length > 5 ? `, +${mute.length - 5} more` : '') +
+    '\n[gen-c4] to group packages, keep kind:"container" and move only level/parent.')
   const derived = goEdges({ repo: REPO, nodes, edges: topo.edges })
   topo.edges = [...(topo.edges || []), ...derived]
   console.log(`[gen-c4] auto-edges: +${derived.length} container edge(s) derived from Go import blocks`)

package/lib/init.mjs

@@ -29,6 +29,10 @@ if (existsSync(OUT) && !FORCE) { console.error(`[forma init] ${relative(REPO, OU
 // (build junk AND data/fixture/doc dirs): counting files that can never become a container is how
 // a repo full of Python fixtures gets detected as a Python repo and then finds no source dir.
 const counts = {}
+// ext → Map(repo-relative dir → file count). The walk already sees every stack in the repo; only the
+// dominant one used to survive it. Keeping the directories is what lets §34 below name the stacks
+// init does NOT seed instead of dropping them in silence.
+const extDirs = {}
 ;(function walk(dir, depth) {
   if (depth > 12) return
   let ents; try { ents = readdirSync(dir) } catch { return }
@@ -38,13 +42,29 @@ const counts = {}
     const p = join(dir, e)
     let st; try { st = statSync(p) } catch { continue }
     if (st.isDirectory()) walk(p, depth + 1)
-    else { const m = e.match(/\.([a-z0-9]+)$/i); if (m && EXT[m[1].toLowerCase()]) counts[m[1].toLowerCase()] = (counts[m[1].toLowerCase()] || 0) + 1 }
+    else {
+      const m = e.match(/\.([a-z0-9]+)$/i)
+      if (!m || !EXT[m[1].toLowerCase()]) continue
+      const x = m[1].toLowerCase()
+      counts[x] = (counts[x] || 0) + 1
+      const rel = relative(REPO, dir) || '.'
+      const seenDirs = extDirs[x] || (extDirs[x] = new Map())
+      seenDirs.set(rel, (seenDirs.get(rel) || 0) + 1)
+    }
   }
 })(REPO, 0)
-const ext = Object.entries(counts).sort((a, b) => b[1] - a[1])[0]
-if (!ext) { console.error('[forma init] no recognised source files found under ' + REPO); process.exit(1) }
-const lang = EXT[ext[0]]
-const matchRe = `\\.${ext[0]}$`
+const ext = Object.entries(counts).sort((a, b) => b[1] - a[1])[0] || null
+// A repo with no recognised source is not an error: init is best-effort, and since §33 it always has
+// something true to write — the context. Exiting 1 here left the caller with no file at all.
+if (!ext) console.error(`[forma init] no recognised source files under ${REPO} — seeding the context only, no containers.`)
+const lang = ext ? EXT[ext[0]] : null
+// One `match` per LANGUAGE, not per extension. A React repo where *.tsx outnumbers *.ts used to be
+// modelled from the .tsx half alone, with the .ts half neither seeded nor mentioned — and §34's
+// report would then hand back "TypeScript: not seeded" for the same directories it had just seeded,
+// so pasting it stacked a second container on top of the first.
+const extsOf = (name) => Object.keys(counts).filter((x) => EXT[x] === name).sort()
+const anyOf = (exts) => (exts.length === 1 ? `\\.${exts[0]}$` : `\\.(${exts.join('|')})$`)
+const matchRe = ext ? anyOf(extsOf(lang)) : null
 
 // 2) find the source root
 function javaBase() {
@@ -59,20 +79,40 @@ function javaBase() {
   return d
 }
 // 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 root = !ext ? REPO : ext[0] === 'java' ? (javaBase() || REPO) : ext[0] === 'go' ? REPO : (existsSync(join(REPO, 'src')) ? join(REPO, 'src') : REPO)
+const GO = !!ext && 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.` }]
+// §33 — the first screen a reader meets was ONE dashed box holding a generated sentence, and nothing
+// told them that curating it is mandatory rather than nice: "who touches this" is slide one of any
+// architecture talk. So init seeds the two roles every system has, EXPLICITLY anonymous. The `TODO:`
+// prefix is the whole point — a plausible invented actor ("End user") would be indistinguishable
+// from curated truth, and `gen` keys its reminder off exactly this prefix.
+const PERSON = 'todo_person', EXTERNAL = 'todo_external'
+const PLACEHOLDER = 'Placeholder seeded by `forma init` — rename it to the real one, or delete it.'
+const nodes = [
+  { id: sysId, level: 'context', kind: 'system', name: basename(REPO), ...(lang ? { tech: lang } : {}), description: `${basename(REPO)} — drill for containers.` },
+  { id: PERSON, level: 'context', kind: 'person', name: 'TODO: who uses it', description: PLACEHOLDER },
+  { id: EXTERNAL, level: 'context', kind: 'external', name: 'TODO: what it depends on', description: PLACEHOLDER },
+]
+// Seeded with the actors, not after them: a context screen of boxes with no arrows is a bulleted
+// list in rectangles (predicate 4 of scripts/presentable.mjs), and the arrows are what say which
+// side of the system each placeholder stands on — so renaming them is a fill-in, not a design job.
+const edges = [
+  { from: PERSON, to: sysId, label: 'uses' },
+  { from: sysId, to: EXTERNAL, label: 'depends on' },
+]
 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) && !(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()
+// The context ids are claimed up front: a directory named like the repo (or like a placeholder) would
+// otherwise mint a duplicate id that only `gen` finds, one command later.
+const seen = new Set([sysId, PERSON, EXTERNAL])
 const skipped = []
 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) => {
@@ -111,11 +151,77 @@ if (GO) {
     nodes.push({ id, level: 'container', kind: 'container', parent: sysId, name: rel, tech: lang })
     leafSources.push({ parent: id, dir: rel, match: matchRe, exclude: '_test\\.go$', evidenceOnly: true })
   }
-} else findContainers(root, 0)
+} else if (ext) 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, ...(GO ? { exclude: '_test\\.go$', evidenceOnly: true } : {}) }) }
+if (ext && 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$', evidenceOnly: true } : {}) }) }
 
-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) }
+// Nothing to seed is a fact to report, not a reason to exit: the context is written either way, and
+// `--include` is named for what it actually does — it un-skips a data/doc dir BY NAME (docs,
+// fixtures, testdata, …). It never took a path, so `--include frontend/src` was a promise the flag
+// could not keep; the stacks it was reached for are named by §34 below instead.
+if (ext && 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. Add leafSources by hand, or re-run with --include <name,...> to un-skip one of ${[...SKIP_DIRS].sort().join(', ')}.`)
+
+// §34 — name every stack init SAW and did not seed. One run models ONE language (the whole container
+// pass keys on a single `match`), and saying nothing about the rest is how a Go + React monorepo came
+// out as 53 Go packages with no trace of the application its users actually open.
+// Seeding them all instead was measured on that repo and rejected: the shallowest-dir rule stops at
+// `frontend/`, whose only direct sources are two build configs, so the 302-file app under
+// `frontend/src` would be modelled as `knip.config.ts` + `vite.config.ts` — a box that names the
+// frontend and contains none of it, which is the false green forma exists to kill. Reaching the real
+// app needs a per-stack root convention (src/, app/, frontend/src/) that has no honest general rule,
+// and even then the container level goes from 53 boxes to 69 with 16 more carrying no prose.
+// So the entries are built here — exactly as `gen` needs them, ids already de-duplicated against the
+// seeded ones — and parked in `_unseeded`, where moving them in is a cut-and-paste, not a rewrite.
+// Keyed on the DIRECTORIES that did not become a container, not on "every language but the dominant
+// one": sources the container pass never reached are unmodelled whatever language they are in, and a
+// directory already seeded must never come back as something to paste on top of itself. Covered is
+// per LANGUAGE, though — `scripts/` can be a Go package AND hold 160 unmodelled *.mjs.
+const covered = new Set(leafSources.map((s) => s.dir))
+const byLang = new Map()
+for (const [x, dirs] of Object.entries(extDirs)) {
+  for (const d of dirs.keys()) {
+    if (covered.has(d) && EXT[x] === lang) continue
+    const L = byLang.get(EXT[x]) || new Set()
+    L.add(d)
+    byLang.set(EXT[x], L)
+  }
+}
+// Counted the way `gen` walks a leafSource — same match, same exclusion — because the walk that fed
+// `extDirs` counts every file: six directories on a real Go repo hold nothing but `_test.go`, which
+// the Go adapter deliberately excludes from architecture. Offered as entries they would seed twenty
+// boxes of test files, or (with the exclusion) match zero and make `gen` exit 1 on a phantom node.
+const realFiles = (dir, re, ex) => {
+  let out = 0
+  try { for (const f of readdirSync(join(REPO, dir))) { if (!re.test(f) || (ex && ex.test(f))) continue; try { if (statSync(join(REPO, dir, f)).isFile()) out++ } catch {} } } catch {}
+  return out
+}
+const unseeded = []
+for (const [name, dirSet] of byLang) {
+  // Every extension of the language in ONE match, the same rule the seeded side follows: a pasted
+  // entry that under-matches models half a React app and reports it as whole.
+  const match = anyOf(extsOf(name))
+  const re = new RegExp(match), ex = name === 'Go' ? /_test\.go$/ : null
+  const dirs = [...dirSet].sort().map((d) => [d, realFiles(d, re, ex)]).filter(([, n]) => n > 0)
+  if (!dirs.length) continue
+  const entry = { stack: name, files: dirs.reduce((a, b) => a + b[1], 0), match, nodes: [], leafSources: [] }
+  for (const [d] of dirs) {
+    const id = claim(d === '.' ? `${name}_root` : d)
+    entry.nodes.push({ id, level: 'container', kind: 'container', parent: sysId, name: d === '.' ? `${name} (repo root)` : d, tech: name })
+    entry.leafSources.push({ parent: id, dir: d, match, ...(name === 'Go' ? { exclude: '_test\\.go$', evidenceOnly: true } : {}) })
+  }
+  // The biggest directory rides alongside the entry, never inside it: `_unseeded` is pasted into the
+  // topology by hand and every key in it has to be one `gen` understands.
+  unseeded.push([entry, [...dirs].sort((a, b) => b[1] - a[1])[0]])
+}
+unseeded.sort((a, b) => b[0].files - a[0].files)
+const unseededNotes = [] // printed after the file exists — the message points AT the file
+for (const [entry, big] of unseeded) {
+  const name = entry.stack
+  const bigSrc = entry.leafSources.find((s) => s.dir === big[0])
+  const bigNode = entry.nodes.find((n) => n.id === bigSrc.parent)
+  unseededNotes.push(`[forma init] ${name}: ${entry.files} file(s) in ${entry.leafSources.length} directory(ies) NOT seeded${name === lang ? ' — the container pass never reached them' : lang ? ` — init models one stack per run, and ${lang} won` : ''}. Largest: ${big[0]} (${big[1]} files).`)
+  unseededNotes.push(`[forma init]   the ${entry.leafSources.length} ready-made pair(s) are under "_unseeded" — move .nodes/.leafSources into the top-level arrays to model them. Largest: ${JSON.stringify(bigNode)} + ${JSON.stringify(bigSrc)}`)
+}
 
 // 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
@@ -146,21 +252,25 @@ const ghRepo = (() => {
 })()
 
 const topo = {
-  meta: { repo: basename(REPO), stack: lang, seededBy: 'forma init', ...(ghRepo ? { ghRepo } : {}) },
+  meta: { repo: basename(REPO), ...(lang ? { stack: lang } : {}), seededBy: 'forma init', ...(ghRepo ? { ghRepo } : {}) },
   docPath: 'docs/architecture/ARCHITECTURE.md',
   levels: ['context', 'container', 'component', 'leaf'],
   nodes,
   leafSources,
-  edges: [],
+  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,
+  ...(unseeded.length ? { _unseeded: unseeded.map(([e]) => e) } : {}),
 }
 // ensure output dir exists
 mkdirSync(join(OUT, '..'), { recursive: true })
 writeFileSync(OUT, JSON.stringify(topo, null, 2) + '\n')
-console.log(`[forma init] wrote ${relative(REPO, OUT)} — ${lang}, ${leafSources.length} container(s) seeded from ${relative(REPO, root) || '.'}/${skipped.length ? `, ${skipped.length} data/doc dir(s) skipped` : ''}`)
+console.log(`[forma init] wrote ${relative(REPO, OUT)} — ${lang || 'no stack'}, ${leafSources.length} container(s) seeded from ${relative(REPO, root) || '.'}/${skipped.length ? `, ${skipped.length} data/doc dir(s) skipped` : ''}`)
+for (const n of unseededNotes) console.error(n)
 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`.')
+// The context comes FIRST and alone on this line. It used to be the middle item of three, which read
+// as one improvement among many; it is the only one without which the first screen says nothing.
+console.log(`[forma init] NEXT: name the two "TODO:" actors in ${relative(REPO, OUT)} — that context screen is the first thing anyone sees. Then curate names/descriptions and run \`forma gen\`.`)

package/lib/viewer/c4-hologram.html

@@ -89,7 +89,7 @@ svg.dense .edge.hot{opacity:1;stroke-width:2.6}
 #etip{position:absolute;pointer-events:none;display:none;z-index:6;background:var(--detailbg);border:1px solid var(--border);
  color:var(--nm);font-size:10px;letter-spacing:.03em;padding:3px 8px;border-radius:5px;white-space:nowrap;box-shadow:0 3px 12px rgba(0,0,0,.45)}
 #legend{display:flex;gap:13px;font-size:9.5px;color:var(--sec);margin:10px 0 0;flex-wrap:wrap}
-#legend i{display:inline-block;width:8px;height:8px;border-radius:50%;margin-right:4px}
+#legend i{display:inline-block;width:8px;height:8px;border-radius:50%;margin-right:4px;box-sizing:border-box}
 .hint{color:var(--ter2)}
 #detail{margin-top:12px;border:1px solid var(--border);border-radius:10px;padding:13px;background:var(--detailbg);display:none}
 #detail h3{color:var(--cyan);font-size:12.5px;margin-bottom:8px;letter-spacing:.05em}
@@ -165,6 +165,10 @@ html[data-skin="blueprint"] button.on{text-shadow:none}
  <div id="stage"><div id="etip"></div><div id="err" style="display:none"></div></div>
  <div id="legend">
   <span><i style="background:#2fe08a"></i><span id="lg-done"></span></span>
+  <!-- Same colour, hollow: a green derived from a repo document saying it is finished is not the
+       same evidence as a green from a closed issue, and the legend is where a reader learns that
+       one mark means two things. -->
+  <span><i style="border:1.5px solid #2fe08a"></i><span id="lg-decl"></span></span>
   <span><i style="background:#ffc74d"></i><span id="lg-prog"></span></span>
   <span><i style="background:#3ee7ff"></i><span id="lg-next"></span></span>
   <span><i style="background:#2d5a72"></i><span id="lg-plan"></span></span>
@@ -185,8 +189,10 @@ var STRINGS={
   labels:"LABELS", labelsTitle:"arrow labels (auto-off above 14 arrows)",
   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",
+  legDone:"DONE (proven)", legDecl:"DONE (declared)", legProg:"IN PROGRESS", legNext:"NEXT", legPlan:"PLAN ONLY", legProb:"PROBLEM",
   legUnk:"UNKNOWN (no curated state)", stUnk:"?",
+  detDecl:"Declared in", detCover:"Coverage", coverWhole:"the document names this module itself",
+  coverPart:"{n} of {t} units named by the document",
   legHint:"— animated arrow = active flow · dashed = to build",
   crumbRoot:"Context", crumbLevel:"C4", lvlContext:"CONTEXT",
   lvlNames:{context:"Context",container:"Container",component:"Components",leaf:"Leaves"},
@@ -205,8 +211,10 @@ var STRINGS={
   labels:"ETICHETTE", labelsTitle:"etichette sugli archi (spente sopra i 14 archi)",
   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",
+  legDone:"FATTO (provato)", legDecl:"FATTO (dichiarato)", legProg:"IN CORSO", legNext:"PROSSIMO", legPlan:"SOLO PROGETTO", legProb:"PROBLEMA",
   legUnk:"IGNOTO (stato non curato)", stUnk:"?",
+  detDecl:"Dichiarato in", detCover:"Copertura", coverWhole:"il documento nomina il modulo stesso",
+  coverPart:"{n} unità su {t} nominate dal documento",
   legHint:"— freccia animata = flusso attivo · tratteggio = da costruire",
   crumbRoot:"Contesto", crumbLevel:"C4", lvlContext:"CONTESTO",
   lvlNames:{context:"Contesto",container:"Container",component:"Componenti",leaf:"Foglie"},
@@ -238,12 +246,34 @@ var STMAP={done:"done","in-progress":"prog",next:"next",planned:"plan",problem:"
 // reads first. Dividing by every child instead would be the mirror lie: a node with no verdict is
 // not 0% done, which is exactly why `gen` refuses to write a completion nobody curated. So the
 // percentage keeps its honest denominator and shows it.
-function tallyOf(kids){
- var cnt={},tot=0,sum=0,nc=0,st3,j;
- for(j=0;j<kids.length;j++){
-  st3=STMAP[kids[j].status2]||(kids[j].status==="planned"?"plan":"unk");
-  cnt[st3]=(cnt[st3]||0)+1;tot++;
-  if(kids[j].completion!=null){sum+=(+kids[j].completion||0);nc++;}
+//
+// It counts UNITS, not boxes: grouping is the only cure for a 53-box wall, and the invariant that
+// makes grouping safe is that it must not change this line. The same repo read 25/53 flat and 2/6
+// once six domains were curated over it — the act of drawing fewer boxes silently deleted 23
+// verdicts, in the number a stakeholder reads first.
+// So a box stands for its childless descendants, and it keeps its own voice in exactly one case:
+// nobody ruled on those descendants AND the box itself carries a verdict. Descending
+// unconditionally is the mirror mistake — this repo's own board curates a verdict on each
+// container and none on the files inside, and it went from `4/4 100%` to `0/19` with no
+// percentage at all, inventing grey where a human had written an answer. Falling back to the box
+// unconditionally is the third mistake, and the worst: a domain of 9 packages nobody ruled on
+// would contribute ONE unknown instead of nine, so 25/53 would print as 25/45 and the coverage
+// would read better than it is — which is the number this whole function exists to keep honest.
+// One consequence, deliberate: on a grouped level the dots count units (53), not boxes (6).
+function tallyOf(kids,kidsOf){
+ var cnt={},tot=0,sum=0,nc=0,st3,i,j,k,q,lv,use,n;
+ for(i=0;i<kids.length;i++){
+  lv=[];q=[kids[i]];
+  while(q.length){n=q.pop();k=kidsOf(n.id);if(k.length){for(j=0;j<k.length;j++)q.push(k[j]);}else lv.push(n);}
+  use=null;
+  for(j=0;j<lv.length;j++)if(lv[j].completion!=null){use=lv;break;} // a finer answer exists
+  if(!use)use=kids[i].completion!=null?[kids[i]]:lv;                // else the box speaks, if it can
+  for(j=0;j<use.length;j++){
+   n=use[j];
+   st3=STMAP[n.status2]||(n.status==="planned"?"plan":"unk");
+   cnt[st3]=(cnt[st3]||0)+1;tot++;
+   if(n.completion!=null){sum+=(+n.completion||0);nc++;}
+  }
  }
  return {cnt:cnt,tot:tot,ruled:nc,mean:nc?Math.round(sum/nc):null};
 }
@@ -368,12 +398,13 @@ function draw(animate){
  var kids=collapseCatalogs(pid,realKids);
  CATNODES={};for(var ci=0;ci<kids.length;ci++)if(kids[ci].__catalog)CATNODES[kids[ci].id]=kids[ci];
  var lay=layoutFor(kids),pos=lay.pos;
- var idset={},memberMap={};
- for(var z=0;z<kids.length;z++){idset[kids[z].id]=1;
-  if(kids[z].__catalog)for(var mm=0;mm<kids[z].members.length;mm++)memberMap[kids[z].members[mm].id]=kids[z].id;}
- function mapId(id){return memberMap[id]||id;}
- var edges=(M.edges||[]).map(function(e){return {from:mapId(e.from),to:mapId(e.to),label:e.label,estatus:e.estatus};})
-  .filter(function(e){return idset[e.from]&&idset[e.to]&&e.from!==e.to;});
+ // `vis` = which box stands for a node on THIS screen (itself, or the catalogue that swallowed it);
+ // everything else reaches the screen through an ancestor. See rollEdges.
+ var vis={},parent={},z,mm;
+ for(z=0;z<M.nodes.length;z++)parent[M.nodes[z].id]=M.nodes[z].parent||null;
+ for(z=0;z<kids.length;z++){vis[kids[z].id]=kids[z].id;
+  if(kids[z].__catalog)for(mm=0;mm<kids[z].members.length;mm++)vis[kids[z].members[mm].id]=kids[z].id;}
+ var edges=rollEdges(M.edges||[],vis,parent);
  // fixed arrow labels: on by default while the level stays readable, else hover-only (the tooltip
  // is always there). A level with 40 arrows would be unreadable with every label painted at once.
  var showLbl=(LABELS===null)?(edges.length<=LABEL_AUTO_MAX):LABELS;
@@ -461,8 +492,9 @@ function draw(animate){
  for(var w=0;w<chain.length;w++)cb+=" &rsaquo; "+(w===chain.length-1?"<b>"+esc(chain[w].name)+"</b>":"<a data-d='"+w+"'>"+esc(chain[w].name)+"</a>");
  // Per-level programme tally — the status-board essence in one glance. Counts use the real
  // children (a collapsed catalogue still counts its members), so the tally never changes when the
- // catalogue threshold does.
- var T=tallyOf(realKids);
+ // catalogue threshold does — nor when someone groups those children into domains, which is what
+ // `childrenOf` is doing here. See tallyOf.
+ var T=tallyOf(realKids,childrenOf);
  if(T.tot){
   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(T.cnt[ord[j]])agg+='<i style="background:'+DOT[ord[j]]+'"></i>'+T.cnt[ord[j]];
@@ -491,6 +523,13 @@ function echoesName(desc,name){
  for(i=0;i<w.length;i++){if(!w[i]||own[w[i]]||DESC_NOISE[w[i]]||/^\d+$/.test(w[i]))continue;return false;}
  return true;
 }
+// Pure, so it is testable without a DOM. Empty when nothing was derived — a curated or a
+// gh-verified state has no document reach to report.
+function coverText(n){
+ var c=n&&n.verify&&n.verify.coverage;if(!c)return "";
+ if(c.whole)return STR.coverWhole;
+ return STR.coverPart.replace("{n}",c.named).replace("{t}",c.total);
+}
 function wrapDesc(desc,cpl,max){
  if(max<1||cpl<2)return [];
  var words=String(desc==null?"":desc).split(" "),all=[],line="",i;
@@ -501,6 +540,34 @@ function wrapDesc(desc,cpl,max){
  for(i=0;i<out.length;i++)if(out[i].length>cpl)out[i]=out[i].slice(0,cpl-1)+"…";
  return out;
 }
+// Project every edge onto the boxes actually on screen, then merge the duplicates. `vis` maps a
+// node id to the id of the box that stands for it here (itself, or the catalogue that swallowed
+// it); `parent` maps every node id to its parent. An endpoint that is not on screen climbs to the
+// ancestor that is — which is the whole point: before this, an edge whose ends were one level
+// deeper simply was not drawn, so the domain level a stakeholder is shown had 189 relationships
+// underneath it and zero arrows on it. Grouping was the only cure for a 53-box wall and it cost
+// the entire graph.
+// An edge landing on the SAME box at both ends is internal detail, not a relationship — it is
+// drawn one level down, where both ends are boxes of their own.
+// The count is summed because the arrow now stands for many: `label` carries "N×" from the Go
+// adapter, so parse it and re-emit the total. A single contributing edge keeps its label VERBATIM,
+// or a curated "reads from" would turn into "1×" the moment this ran.
+// Pure, so it is testable without a DOM — and `scripts/presentable.mjs` grades the model by
+// evaluating this very function, so the instrument cannot drift from what the reader sees.
+function rollEdges(edges,vis,parent){
+ var out=[],ix={},i,e,f,t,c,k,cur,guard,g;
+ for(i=0;i<edges.length;i++){
+  e=edges[i];
+  f=null;cur=e.from;guard=0;while(cur!=null&&guard++<64){if(vis[cur]){f=vis[cur];break;}cur=parent[cur];}
+  t=null;cur=e.to;guard=0;while(cur!=null&&guard++<64){if(vis[cur]){t=vis[cur];break;}cur=parent[cur];}
+  if(!f||!t||f===t)continue;
+  c=parseInt(String(e.label),10);if(!(c>0))c=1;
+  k=f+"|"+t;
+  if(ix[k]==null){ix[k]=out.length;out.push({from:f,to:t,label:e.label,estatus:e.estatus,n:c});}
+  else{g=out[ix[k]];g.n+=c;g.label=g.n+"×";if(e.estatus!=="to-build")g.estatus=e.estatus;}
+ }
+ return out;
+}
 // Returns the path plus the point ON the curve at t=0.5 — the label anchor. (The quadratic's
 // control point sits at twice the bow, so anchoring a label there would float it off the arrow.)
 // Endpoints are trimmed at the true RECTANGLE border (not a radial guess): with wide boxes the
@@ -525,7 +592,12 @@ function showDetail(n){
   +(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>':'')
   +((n.target&&n.target!=="—")?'<div class="row"><span class="lbl">'+esc(STR.detTgt)+'</span><span class="tgt">'+esc(n.target)+'</span></div>':'')
-  +(showSrc?'<div class="row"><span class="lbl">'+esc(STR.detSrc)+'</span><span class="src">'+esc(src)+'</span></div>':'')
+  // A number DERIVED from a repo document is a declaration, not a verification: the label says which
+  // one, and the coverage says how much of this module the citation actually reaches. "3 of 3 rows
+  // declared done" and "this module is done" are not the same sentence when the module holds 22
+  // files and the document names 3 of them.
+  +(showSrc?'<div class="row"><span class="lbl">'+esc((n.verify&&n.verify.derived)?STR.detDecl:STR.detSrc)+'</span><span class="src">'+esc(src)+'</span></div>':'')
+  +(coverText(n)?'<div class="row"><span class="lbl">'+esc(STR.detCover)+'</span><span class="now">'+esc(coverText(n))+'</span></div>':'')
   +((n.issues&&n.issues.length)?'<div class="row"><span class="lbl">'+esc(STR.detIssue)+'</span><span class="now">'+esc(n.issues.join(", "))+'</span></div>':'');
  $("detail").style.display="block";
  var dc=$("dc");if(dc)dc.addEventListener("click",function(){$("detail").style.display="none";});
@@ -645,7 +717,7 @@ function applyStrings(){
  set("blbl",STR.labels);var bl=$("blbl");if(bl)bl.title=STR.labelsTitle;
  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-done",STR.legDone);set("lg-decl",STR.legDecl);set("lg-prog",STR.legProg);set("lg-next",STR.legNext);
  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) ----

package/package.json

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