forma-arch 0.7.2 → 0.9.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 })
       }
     }
   }
@@ -134,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),
@@ -152,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

@@ -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,18 @@ 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.
+  // `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
@@ -281,7 +304,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}
@@ -82,7 +89,7 @@ svg{width:100%;height:100%;display:block}
 #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}
@@ -158,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>
@@ -178,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"},
@@ -198,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"},
@@ -260,7 +275,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);
@@ -296,6 +314,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){
@@ -324,12 +350,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));
@@ -379,7 +412,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++){
@@ -395,6 +428,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
@@ -448,6 +486,26 @@ 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;
+}
+// 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;
@@ -482,7 +540,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";});
@@ -602,7 +665,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.7.2",
+  "version": "0.9.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",