forma-arch 0.9.0 → 0.10.1

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

@@ -181,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 })
@@ -304,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

@@ -191,7 +191,7 @@ var STRINGS={
   printExport:"PRINT / EXPORT", exportSvg:"Export SVG", exportPng:"Export PNG", exportLayout:"Export layout JSON", print:"Print",
   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",
+  detDecl:"Declared in", detCover:"Coverage", detRoll:"Rolled up from", rollPart:"mean of the {n} of {t} parts inside that anyone ruled on", 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",
@@ -213,7 +213,7 @@ var STRINGS={
   printExport:"STAMPA / ESPORTA", exportSvg:"Esporta SVG", exportPng:"Esporta PNG", exportLayout:"Esporta layout JSON", print:"Stampa",
   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",
+  detDecl:"Dichiarato in", detCover:"Copertura", detRoll:"Somma dal basso", rollPart:"media delle {n} parti su {t} qui dentro su cui qualcuno si e pronunciato", 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",
@@ -246,12 +246,58 @@ 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).
+// What a box that GROUPS others can honestly say about itself. Nobody ruled on a domain — `gen`
+// refuses to derive a verdict, everywhere, on purpose — so its badge read `?` while the 22 packages
+// inside it carried 14 verdicts. Four of six domains showed `?` on the one screen a stakeholder is
+// shown, and the board looked less finished than the repo was.
+// The way out is not to invent a verdict but to report a FACT: the mean of the descendants somebody
+// did rule on, and how many that was. `100%` alone would be the invented green this tool exists to
+// kill — 14 of 14 ruled done says nothing about the other 8 — so the coverage is not optional
+// decoration, it is half the claim. Same shape as the level tally and the docmap coverage.
+// Returns null when the box has its own verdict (it speaks for itself) or when nothing below it
+// was ruled (there is no fact to report).
+function rollStatus(node,kidsOf){
+ if(node.completion!=null||node.statusWord)return null;
+ var lv=[],q=[node],n,k,i,guard=0;
+ while(q.length&&guard++<4096){n=q.pop();k=kidsOf(n.id);if(k.length){for(i=0;i<k.length;i++)q.push(k[i]);}else if(n!==node)lv.push(n);}
+ if(!lv.length)return null;
+ var sum=0,nc=0,rank={problem:5,next:4,"in-progress":3,planned:2,unknown:1.5,done:1},best=0,key="unknown",s2;
+ for(i=0;i<lv.length;i++){
+  if(lv[i].completion!=null){sum+=(+lv[i].completion||0);nc++;}
+  s2=lv[i].status2||(lv[i].status==="planned"?"planned":"unknown");
+  if((rank[s2]||0)>best){best=rank[s2]||0;key=s2;}
+ }
+ if(!nc)return null;
+ return {status2:key,mean:Math.round(sum/nc),ruled:nc,total:lv.length};
+}
+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};
 }
@@ -376,12 +422,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;
@@ -424,7 +471,10 @@ function draw(animate){
  }
  for(var j=0;j<kids.length;j++){
   var n=kids[j],p=pos[n.id];
-  var st=STMAP[n.status2]||(n.status==="planned"?"plan":"unk");
+  // A grouping box borrows its children's colour and badge — see rollStatus. The MODEL keeps saying
+  // `unknown` for it; this is the viewer reporting what is underneath, not gen inventing a verdict.
+  var roll=(n.__catalog||mode==="target")?null:rollStatus(n,childrenOf);
+  var st=STMAP[(roll?roll.status2:n.status2)]||(n.status==="planned"?"plan":"unk");
   var pulse=(st==="next"||st==="prog")&&mode!=="target"&&!n.__catalog;
   var isCat=!!n.__catalog,dr=!isCat&&hasKids(n.id),cls="nd s-"+st+(dr?" drill":"")+(isCat?" cat":"")+(pulse?" pulse":"");
   var desc=isCat?(n.count+" "+STR.rosterCount):(mode==="target"?(n.target||n.func||""):(n.current||n.func||""));
@@ -433,7 +483,9 @@ function draw(animate){
   // breathe. The measured fallback text is the generator's honest last resort, not a lie — it just
   // does not belong on screen when it says nothing the header has not already said.
   if(!isCat&&echoesName(desc,n.name))desc="";
-  var badge=isCat?String(n.count):(mode==="target"?STR.detTarget:(n.statusWord||(n.completion!=null?n.completion+"%":STR.stUnk)));
+  // The coverage rides WITH the mean, never without it: `100%` on a domain where 14 of 22 packages
+  // were ruled is the invented green, and this is the badge a stakeholder reads first.
+  var badge=isCat?String(n.count):(mode==="target"?STR.detTarget:(n.statusWord||(n.completion!=null?n.completion+"%":(roll?roll.mean+"% "+roll.ruled+"/"+roll.total:STR.stUnk))));
   // the title runs until the badge, so reserve the badge's actual width (9px text ≈ 5.4px/char)
   // instead of a flat 70px — a fixed reserve clipped names that had all the room they needed
   var tmax=Math.floor((p.w-34-String(badge).length*5.4)/6.7),tt=n.name;
@@ -469,8 +521,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]];
@@ -516,6 +569,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
@@ -545,6 +626,8 @@ function showDetail(n){
   // 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>':'')
+  // A badge the viewer rolled up must say so, or it reads as a verdict somebody wrote about the box.
+  +((function(){var r=rollStatus(n,childrenOf);return r?'<div class="row"><span class="lbl">'+esc(STR.detRoll)+'</span><span class="now">'+esc(STR.rollPart.replace("{n}",r.ruled).replace("{t}",r.total))+'</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";

package/package.json

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