forma-arch 0.7.1 → 0.8.0

package/lib/check.mjs

@@ -9,7 +9,7 @@ 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 { loadDocRows, indexByNode, describingRows, statusFor } from './docmap.mjs'
 import { validateModel } from './validate.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
@@ -43,7 +43,13 @@ function walk(spec) {
 }
 for (const spec of topo.leafSources) {
   const live = walk(spec).length
-  const inModel = model.nodes.filter((n) => n.kind === 'leaf' && n.status === 'current' && containerOf(n, byId) === spec.parent).length
+  // An `evidenceOnly` source produces no leaves — the count IS the assertion, carried on the
+  // container's glob evidence. Comparing leaves for those would compare 0 to 0 forever: that is
+  // exactly how the Go gate went vacuous, passing while a .go file was added or deleted.
+  // A model with no glob evidence predates the count; report 0 so it drifts loud, not `undefined`.
+  const inModel = spec.evidenceOnly
+    ? (((byId.get(spec.parent) || {}).evidence || []).find((e) => e.type === 'glob') || {}).count ?? 0
+    : model.nodes.filter((n) => n.kind === 'leaf' && n.status === 'current' && containerOf(n, byId) === spec.parent).length
   if (live === 0) fail(`phantom parent "${spec.parent}": src glob ${spec.dir} matches 0 files`)
   if (live !== inModel) fail(`DRIFT: ${spec.parent} — src has ${live} files, model has ${inModel}. Regenerate c4-model.json.`)
 }
@@ -120,14 +126,37 @@ if (src.statusPath && existsSync(rp(src.statusPath))) {
 // 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 || [])
+const docPaths = (topo.docSources || []).map((e) => (typeof e === 'string' ? e : (e || {}).path)).filter(Boolean)
+// A listed source that is GONE derives nothing — and "derives nothing" used to read as "no drift",
+// so the committed model kept citing a file that no longer existed and the gate said OK.
+for (const rel of docPaths) if (!existsSync(rp(rel))) fail(`DOC SOURCE: ${rel} is listed in docSources but the file is gone — every state derived from it is unverifiable.`)
+const docRows = loadDocRows(REPO, topo.docSources)
+for (const r of docRows.filter((x) => x.dead.length)) fail(`DOC REF: ${r.from} row "${r.text.slice(0, 60)}" cites ${r.dead.join(', ')}, which does not exist — the row silently stops counting.`)
+const docIdx = indexByNode(docRows, model.nodes || [])
 for (const n of model.nodes || []) {
   const want = statusFor(docIdx, n.id)
-  if (!want) continue
   const owned = overlay[n.id] || {}
+  if (!want) {
+    // A state DERIVED from a document must keep deriving. The document can lose the row (a renamed
+    // code_ref) or GROW past MAX_ROWS — either way the derivation falls silent while the committed
+    // green box and its "(N/N done)" citation keep shipping. Trusting that silence IS the false green.
+    if ((n.verify || {}).derived === true && owned.status2 === undefined && owned.completion === undefined && owned.verify === undefined) {
+      fail(`DOC DRIFT: ${n.id} still claims "${n.verify.source}" (${n.status2}/${n.completion}) but no row in ${docPaths.join(', ')} derives a state for it any more. Regenerate c4-model.json.`)
+    }
+    continue
+  }
   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.`)
 }
+// The BOX TEXT is quoted from those same rows, and nothing re-derived it: edit the sentence, delete
+// the document, or push the node past MAX_ROWS, and the quote keeps shipping with `descSource:
+// "docmap"` vouching for a document that no longer says it.
+for (const n of model.nodes || []) {
+  if (n.descSource !== 'docmap') continue
+  const rows = describingRows(docIdx, n.id)
+  const txt = rows ? rows.map((r) => r.text).join(' · ').slice(0, 240) : null
+  if (n.func !== txt) fail(`DOC DRIFT: ${n.id} quotes "${String(n.func).slice(0, 60)}" as coming from ${docPaths.join(', ')}, which no longer says it. Regenerate c4-model.json.`)
+}
 
 // SOFT: LLM-enriched prose whose inputs changed is only a reminder, never a gate failure (structure
 // is the gate; enrichment freshness is advisory). check never calls the LLM — it recomputes the hash.

package/lib/describe.mjs

@@ -72,7 +72,13 @@ function buildArc42Index(repo, docPath) {
 function measuredFunc(node, ctx) {
   const kids = [...ctx.byId.values()].filter((k) => k.parent === node.id)
     .sort((a, b) => (String(a.name) < String(b.name) ? -1 : String(a.name) > String(b.name) ? 1 : 0))
-  if (!kids.length) return null
+  // A node with no children still measures: its glob evidence carries the file count the drift gate
+  // re-walks. Without this a Go package — one node, files as internal detail — fell through to an
+  // EMPTY box, where the old duplicate leaf at least said "1 file".
+  if (!kids.length) {
+    const g = (node.evidence || []).find((e) => e.type === 'glob')
+    return g && g.count ? `${g.count} source file${g.count === 1 ? '' : 's'}.` : null
+  }
   const count = (k) => kids.filter((x) => x.kind === k).length
   const parts = [['container', count('container')], ['component', count('component')], ['file', count('leaf')]]
     .filter((p) => p[1]).map((p) => `${p[1]} ${p[0]}${p[1] === 1 ? '' : 's'}`)

package/lib/docmap.mjs

@@ -10,8 +10,8 @@
 //
 // 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'
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { join, dirname, basename } 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).
@@ -74,8 +74,20 @@ function refsIn(cell) {
  *   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}[]}
+ * @returns {{text:string, refs:string[], dead:string[], done:boolean|null, from:string}[]}
  */
+// A ref is the row's EVIDENCE: the code it claims implements the capability. If nothing on disk
+// answers to it, the claim is unfalsifiable — and worse, the row silently stops touching the node
+// it used to describe, so an unfinished capability drops OUT of the completion denominator and the
+// box turns green with a freshly re-derived "(1/1 done)". Measured: renaming one `code_ref` cell
+// took a container from in-progress/50 to done/100, and `check` confirmed the new number.
+// ponytail: prefix match, so a truncated ref (`src/billing/dunn`) still reads as alive — the price
+// of supporting glob stems like `internal/imports/statement*.go`. Upgrade path: keep the raw cell
+// and relax the rule only for refs that actually carried a `*`.
+const alive = (repo, ref) => {
+  if (existsSync(join(repo, ref))) return true
+  try { return readdirSync(join(repo, dirname(ref))).some((e) => e.startsWith(basename(ref))) } catch { return false }
+}
 export function loadDocRows(repo, docSources, inventoryOnly = false) {
   const out = []
   for (const entry of docSources || []) {
@@ -99,7 +111,8 @@ export function loadDocRows(repo, docSources, inventoryOnly = false) {
         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 })
+        out.push({ text: txt.slice(0, 240), refs, dead: refs.filter((x) => !alive(repo, x)),
+                   done: iS < 0 ? null : DONE.test(String(r[iS]).replace(/[*_`]+/g, '').trim()), from: rel })
       }
     }
   }

package/lib/gen.mjs

@@ -74,7 +74,11 @@ for (const spec of topo.leafSources) {
   if (!byId.has(spec.parent)) fail('leafSource parent unknown: ' + spec.parent)
   const files = walk(spec)
   if (files.length === 0) fail(`leafSource matched 0 files (phantom node?): ${spec.dir}`)
-  for (const f of files) {
+  // `evidenceOnly`: the files are re-walked for the gate but never become boxes — the unit of
+  // architecture is the container itself (a Go package). Its own `path` evidence is what joins it
+  // to a capability table (docmap matches on `path`), points describe's README lookup at its own
+  // directory rather than its parent's, and gives `check` an evidence path to assert exists.
+  if (!spec.evidenceOnly) for (const f of files) {
     add({
       id: `${spec.parent}__${f.replace(/[^a-z0-9]+/gi, '_')}`,
       level: 'leaf', parent: spec.parent, kind: 'leaf',
@@ -87,7 +91,8 @@ for (const spec of topo.leafSources) {
   }
   // attach glob count to the parent (drift anchor)
   const parent = byId.get(spec.parent)
-  parent.evidence = [...(parent.evidence || []), { type: 'glob', ref: spec.dir, count: files.length }]
+  parent.evidence = [...(parent.evidence || []), { type: 'glob', ref: spec.dir, count: files.length },
+                     ...(spec.evidenceOnly ? [{ type: 'path', ref: spec.dir }] : [])]
 }
 
 // 3) curated leaves (mixed-location, with optional computed counts)
@@ -130,6 +135,14 @@ if (CLUSTER) for (const cid of [...new Set(topo.leafSources.map((s) => s.parent)
 // §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)
+// A row whose code_ref resolves to nothing does not merely go unverified: it stops TOUCHING its
+// node, so the capability it describes leaves the completion denominator and the box goes green.
+// Renaming one cell took a container from in-progress/50 to done/100 with a fresh "(1/1 done)"
+// citation, and `check` re-derived and confirmed the new number. Fail on it.
+const deadRows = docRows.filter((r) => r.dead.length)
+if (deadRows.length) fail('docSources cite code that does not exist:\n - ' +
+  deadRows.map((r) => `${r.from}: "${r.text.slice(0, 60)}" → ${r.dead.join(', ')}`).join('\n - ') +
+  '\n[gen-c4] a row whose code_ref resolves to nothing silently stops counting: its capability drops out of the denominator and the box turns green. Fix the ref, or the path.')
 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`)
 
@@ -144,8 +157,15 @@ for (const n of nodes) {
   // 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 } }
+  // NOT the system node. Its subtree is the whole repo, so EVERY row in the document touches it and
+  // its denominator is "the rows somebody wrote", never "the repo". A three-row all-done matrix
+  // rendered the whole product as done/100 on the first screen anyone opens, with a container the
+  // document never mentions sitting right underneath at `unknown`. The whole-product verdict is
+  // exactly what the curated overlay is for.
+  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 } }
   // 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
@@ -281,7 +301,7 @@ 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)) {
-  const derived = goEdges({ repo: REPO, nodes, byId, containerOf, edges: topo.edges })
+  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`)
 } else if (!process.argv.includes('--no-auto-edges')) {

package/lib/init.mjs

@@ -95,24 +95,25 @@ const skipDir = (e) => IGNORE.has(e) || e.startsWith('.') || (SKIP_DIRS.has(e.to
 // 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).
+// package is ONE node. It used to be a container AND a leaf matching that same directory, so
+// drilling into a package showed the package again — 53 of 53 on a real Go repo, a level drawn
+// twice. Per #17 the leaf level stops at the package and the files inside stay internal detail, so
+// the leafSource is `evidenceOnly`: the gate still re-walks the real *.go files, but they become a
+// COUNT on the container instead of boxes. That count is also what the old shape could never see —
+// it matched one fixed directory name, so adding or deleting a .go file passed the gate untouched.
 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.
+    // A package at the module ROOT is handled by the loose-files branch below (there is no parent
+    // directory to name it from here). It is `evidenceOnly` too, and goEdges now keys on the
+    // container's own glob evidence, so `dir: "."` maps to the bare module path and it gets edges.
     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 })
+    leafSources.push({ parent: id, dir: rel, match: matchRe, exclude: '_test\\.go$', evidenceOnly: true })
   }
 } 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, ...(GO ? { exclude: '_test\\.go$' } : {}) }) }
+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 (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) }
 

package/lib/lang.mjs

@@ -64,22 +64,23 @@ 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.
+// Container→container edges from the import blocks. A Go package container carries its own
+// DIRECTORY as glob 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 }) {
+// Keyed on the container's OWN id, not on containerOf(): a package is now one node, and keying on
+// the ancestor would collapse every edge inside a future `internal` grouping into a self-loop.
+export function goEdges({ repo, nodes, 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 (n.kind !== 'container') continue
+    const ev = (n.evidence || []).find((e) => e.type === 'glob')
     if (!ev) continue
-    try { if (!statSync(join(repo, ev.ref)).isDirectory()) continue } catch { continue }
-    pkgs.push({ dir: posix(ev.ref), container: containerOf(n, byId) })
+    pkgs.push({ dir: posix(ev.ref), container: n.id })
   }
   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))

package/lib/viewer/c4-hologram.html

@@ -68,6 +68,13 @@ svg{width:100%;height:100%;display:block}
 .edge.flow{stroke-dasharray:5 7;animation:dash 1.1s linear infinite}
 .edge.plan{stroke:var(--edgeplan);stroke-dasharray:3 6;opacity:.6;marker-end:url(#arp)}
 .edge.hot{stroke:var(--cyan);stroke-width:2.6;opacity:1}
+/* A level past the label threshold is a hairball, and no layout saves it: on a real Go repo 172 of
+   189 arrows cross a box that is not one of their endpoints, and that stays 85-91% at EVERY grid
+   shape tried. Only drawing less helps. They stop competing with the names — structure survives as
+   texture — and hover still brings one arrow back to full strength, which is where its label is. */
+svg.dense .edge{stroke-width:.9;opacity:.26}
+svg.dense .edge.flow{animation:none;stroke-dasharray:none}
+svg.dense .edge.hot{opacity:1;stroke-width:2.6}
 .edgehit{stroke:transparent;stroke-width:14;fill:none;cursor:help}
 .elbl{font-size:8.2px;fill:var(--elbl);letter-spacing:.04em;pointer-events:none;
  paint-order:stroke;stroke:var(--stagebg);stroke-width:3px;stroke-linejoin:round}
@@ -225,6 +232,21 @@ var LABEL_AUTO_MAX=14;    // above this many arrows in the current level, fixed
 var LABELS=null;          // null = auto (by arrow count); true/false = user override for this session
 var SKINS=[["holo","◆ holo"],["blueprint","▭ blueprint"]], SKIN_IDS=["holo","blueprint"];
 var STMAP={done:"done","in-progress":"prog",next:"next",planned:"plan",problem:"prob",unknown:"unk"};
+// The per-level tally. The mean is over the nodes that CARRY a completion, and it reports how many
+// those were: on a real Go repo, 25 containers at 100% next to 28 nobody has ruled on rendered as
+// "progress 100%" — the invented green this tool exists to kill, in the one number a stakeholder
+// 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++;}
+ }
+ return {cnt:cnt,tot:tot,ruled:nc,mean:nc?Math.round(sum/nc):null};
+}
 var M=null, stack=[null], mode="now", POS={}, drag=null, justDragged=false, CATNODES={}, FETCHED=false
 var VBOX={}; // last fitted viewBox per level — frozen while dragging so the canvas does not rescale
 function $(i){return document.getElementById(i)}
@@ -245,7 +267,10 @@ function collapseCatalogs(pid,kids){
  for(i=0;i<kids.length;i++){
   var n=kids[i];
   // only leaf-like, non-drillable nodes with a category are collapse candidates
-  var collapsible=!hasKids(n.id)&&(n.category!=null&&n.category!=="");
+  // A category that is merely the node's own kind — "container" for every container, since gen
+  // falls back to n.kind — is not a grouping. Collapsing on it folds a whole level into one box
+  // named after the level, which is what a repo of 53 childless containers would do.
+  var collapsible=!hasKids(n.id)&&(n.category!=null&&n.category!==""&&n.category!==n.kind);
   var key=collapsible?("cat:"+n.category):("solo:"+i);
   if(!groups[key]){groups[key]={key:key,cat:n.category,members:[],collapsible:collapsible};order.push(key);}
   groups[key].members.push(n);
@@ -281,6 +306,14 @@ function srcOf(n){if(n.verify){if(typeof n.verify==="string")return n.verify;if(
  var ev=(n.evidence||[]).filter(function(e){return e.type==="doc"||e.type==="path";})[0];return ev?ev.ref:((M.meta&&M.meta.verifyMethod)||"");}
 
 var NW=228,NH=118; // NH fits 3 description lines without hitting the [+] DRILL
+// Past DENSE_MIN siblings a full-size card cannot stay legible: the fit-to-content viewBox scales
+// the canvas down to the stage, so 53 cards at 228x118 render 64x33 css px with a 3.24px title.
+// The compact card keeps the one thing that has to survive a projector — the name — near 11px.
+// No other edit is needed: draw() reads w/h from the pos map, never NW/NH, and at h=58 the
+// description's own line budget already falls below one line, so wrapDesc returns nothing.
+// ponytail: holds the 9px floor to ~60 siblings; past that the answer is a real grouping level,
+// not a smaller card.
+var DENSE_MIN=20,DW=168,DH=58,STAGE_ASPECT=2.1; // STAGE_ASPECT: #stage is full-width by 74vh
 // Curated coordinates from meta.layout win; everything else keeps the automatic arrangement,
 // placed BELOW the pinned block so a partial hint set can never overlap generated nodes.
 function seedLayout(kids,hints){
@@ -309,12 +342,19 @@ function autoLayout(kids){
    pos[others[i].id]={x:cx+rx*Math.cos(a)-NW/2,y:cy+ry*Math.sin(a)-NH/2,w:NW,h:NH};}
   return {W:W,H:H,pos:pos};
  }
- var n=kids.length,cols=n<=3?Math.max(n,1):Math.ceil(Math.sqrt(n));if(cols>4)cols=4;
- var rows=Math.ceil(n/cols),gx=96,gy=82,px=64,py=58;
- var blockW=cols*NW+(cols-1)*gx,W=Math.max(1020,blockW+px*2),H=Math.max(560,py*2+rows*NH+(rows-1)*gy);
+ var n=kids.length,dense=n>DENSE_MIN;
+ var bw=dense?DW:NW,bh=dense?DH:NH,gx=dense?44:96,gy=dense?38:82,px=64,py=58;
+ // Columns follow the STAGE's shape instead of a fixed cap of 4. That cap turned a real Go repo's
+ // 53 containers into a 1328x2834 ribbon inside a stage twice as wide as tall: the fit-to-content
+ // viewBox then did its job and scaled everything to 0.28, i.e. a 3.24px title. Nothing on that
+ // screen was readable, and 80% of the width was empty.
+ var cols=n<=3?Math.max(n,1):Math.round(Math.sqrt(n*STAGE_ASPECT*(bh+gy)/(bw+gx)));
+ if(cols<1)cols=1;if(cols>n)cols=n;
+ var rows=Math.ceil(n/cols);
+ var blockW=cols*bw+(cols-1)*gx,W=Math.max(1020,blockW+px*2),H=Math.max(560,py*2+rows*bh+(rows-1)*gy);
  var offx=(W-blockW)/2;
  for(i=0;i<n;i++){var c=i%cols,r=Math.floor(i/cols);
-  pos[kids[i].id]={x:offx+c*(NW+gx),y:py+r*(NH+gy),w:NW,h:NH};}
+  pos[kids[i].id]={x:offx+c*(bw+gx),y:py+r*(bh+gy),w:bw,h:bh};}
  return {W:W,H:H,pos:pos};
 }
 function layoutFor(kids){var k=keyOf();if(!POS[k])POS[k]=seedLayout(kids,hintsFor(k));
@@ -364,7 +404,7 @@ function draw(animate){
  var vbk=keyOf();
  if(drag&&VBOX[vbk]){vx=VBOX[vbk][0];vy=VBOX[vbk][1];vw=VBOX[vbk][2];vh=VBOX[vbk][3];}
  else VBOX[vbk]=[vx,vy,vw,vh];
- var s='<svg viewBox="'+vx.toFixed(1)+' '+vy.toFixed(1)+' '+vw.toFixed(1)+' '+vh.toFixed(1)+'" preserveAspectRatio="xMidYMid meet" class="'+(mode==="target"?"mode-t":"")+'">'
+ var s='<svg viewBox="'+vx.toFixed(1)+' '+vy.toFixed(1)+' '+vw.toFixed(1)+' '+vh.toFixed(1)+'" preserveAspectRatio="xMidYMid meet" class="'+(mode==="target"?"mode-t ":"")+(edges.length>LABEL_AUTO_MAX?"dense":"")+'">'
   +'<defs><marker id="ar" markerWidth="9" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,9 3.5,0 7" fill="'+cssv("--edge")+'"/></marker>'
   +'<marker id="arp" markerWidth="9" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,9 3.5,0 7" fill="'+cssv("--edgeplan")+'"/></marker></defs>';
  for(j=0;j<geo.length;j++){
@@ -380,6 +420,11 @@ function draw(animate){
   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||""));
+  // 26 of a real repo's 53 boxes printed "1 file: advisor." under a box titled "internal/advisor".
+  // A description that only restates the title is ink, not information: drop it and let the box
+  // 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 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
@@ -414,19 +459,15 @@ function draw(animate){
  var lvlIdx=((M.levels||[]).indexOf(lvlKey));
  var cb=(lvlIdx>-1?STR.crumbLevel+"-L"+(lvlIdx+1):STR.crumbLevel)+" · "+lvl.toUpperCase()+"  &nbsp;&nbsp; <a data-d='-1'>"+esc(STR.crumbRoot)+"</a>";
  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: the status mix of THIS
- // view plus mean completion. Counts use the real children (a collapsed catalogue still counts
- // its members), so the tally never changes when the catalogue threshold does.
- var cnt={},tot=0,sum=0,nc=0,st3;
- for(j=0;j<realKids.length;j++){
-  st3=STMAP[realKids[j].status2]||(realKids[j].status==="planned"?"plan":"unk");
-  cnt[st3]=(cnt[st3]||0)+1;tot++;
-  if(realKids[j].completion!=null){sum+=(+realKids[j].completion||0);nc++;}
- }
- if(tot){
+ // 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);
+ 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(cnt[ord[j]])agg+='<i style="background:'+DOT[ord[j]]+'"></i>'+cnt[ord[j]];
-  if(nc)agg+=' &nbsp;'+esc(STR.aggProgress)+' <b>'+Math.round(sum/nc)+'%</b>';
+  for(j=0;j<ord.length;j++)if(T.cnt[ord[j]])agg+='<i style="background:'+DOT[ord[j]]+'"></i>'+T.cnt[ord[j]];
+  // The coverage rides WITH the percentage, never without it. See tallyOf.
+  if(T.ruled)agg+=' &nbsp;'+esc(STR.aggProgress)+' <b>'+T.mean+'%</b> '+T.ruled+'/'+T.tot;
   cb='<span class="agg">'+agg+'</span>'+cb;
  }
  $("crumb").innerHTML=cb;
@@ -437,6 +478,19 @@ function draw(animate){
 // cpl — an unbreakable token (a long class name, a URL) would otherwise paint outside the box, and
 // there is no clip-path on the node. The last line carries the ellipsis when text was dropped,
 // rather than spending a whole line on it (on a short curated box that was half the visible text).
+// True when a description carries no word the title does not already carry. Pure, so it is testable
+// without a DOM. The stop-list is the vocabulary of the generator's own measured fallback
+// ("1 file: advisor.", "3 packages: a, b, c."), never of real prose.
+var DESC_NOISE={file:1,files:1,package:1,packages:1,module:1,modules:1,dir:1,directory:1,folder:1,component:1,components:1,of:1,and:1,the:1};
+function echoesName(desc,name){
+ var norm=function(s){return String(s==null?"":s).toLowerCase().replace(/[^a-z0-9]+/g," ").trim();};
+ var d=norm(desc);if(!d)return false;
+ var own={},nw=norm(name).split(" "),i;
+ for(i=0;i<nw.length;i++)if(nw[i])own[nw[i]]=1;
+ var w=d.split(" ");
+ 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;
+}
 function wrapDesc(desc,cpl,max){
  if(max<1||cpl<2)return [];
  var words=String(desc==null?"":desc).split(" "),all=[],line="",i;

package/package.json

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