@cspeach/cli 1.1.29 → 1.1.30

package/dist/projects/save-command.js

@@ -7,6 +7,7 @@ import { extractUpgradeScan, extractUpgradeProgress, extractUpgradeReport } from
 import { extractCcaAssessment } from './extract-cca.js';
 import { extractModernizeResult } from './extract-modernize.js';
 import { extractTestCoverage } from './extract-test-coverage.js';
+import { extractCleanCoreDecision } from './extract-clean-core.js';
 import { extractPlan, laneConflictsWithPrior, LANE_NEW_FAMILY } from './extract-plan.js';
 import { buildEnvelope } from './build.js';
 import { buildPlanRevision } from './plan-run.js';
@@ -103,6 +104,14 @@ const SKILL_REGISTRY = {
         itemNoun: 'phases',
         manifestMarker: 'plan-manifest',
     },
+    'abap-clean-core': {
+        // 2026-10-06 (clean-core mission control): a triage table. The rows become
+        // team project decisions only after one Yes per row (clean-core-confirm.ts).
+        artefactType: 'clean-core-decision',
+        extract: (md) => extractCleanCoreDecision(md),
+        itemNoun: 'decisions',
+        manifestMarker: 'clean-core-manifest',
+    },
 };
 /**
  * C1 (2026-06-11, defect D22) — map an inline artifact-manifest block in the
@@ -128,6 +137,8 @@ export function detectArtifactSkill(markdown) {
         return 'abap-modernize';
     if (/<!--\s*(?:csforge|cspeach):test-coverage-manifest\b/.test(markdown))
         return 'abap-test';
+    if (/<!--\s*(?:csforge|cspeach):clean-core-manifest\b/.test(markdown))
+        return 'abap-clean-core';
     const up = /<!--\s*(?:csforge|cspeach):upgrade-manifest\s*\n([\s\S]*?)\n\s*-->/.exec(markdown);
     if (up) {
         const art = /(?:^|\n)\s*artefact:\s*(\S+)/.exec(up[1] ?? '');
@@ -360,22 +371,33 @@ export async function runSaveCommand(args) {
     }
     // C1 review fix — name the revision target BEFORE the confirm so the user
     // knows what a 'y' will do. Log line only, deliberately NOT a second
-    // question: the B5 headless contract (below) allows at most one prompt.
+    // question: the B5 headless contract (below) allows one `prompt` question.
     if (planExtract && prior) {
         const priorFilename = prior.path.split(/[\\\/]/).pop();
         args.log(`[save] this will save as v${prior.envelope.version + 1} of existing plan '${prior.envelope.title}' (${priorFilename})`);
     }
-    // CONTRACT (B5): runSaveCommand may ask the user at most ONE question —
-    // this save confirm. The headless path in loop.ts (maybeOfferSave) installs
-    // a prompt that blanket-answers 'y' to WHATEVER it is asked; any second
-    // question added here would silently receive 'y' too. If you need another
-    // prompt, give maybeOfferSave's headless prompt a question-aware answer
-    // first.
+    // CONTRACT (B5): runSaveCommand asks 1+N cards — this save confirm, then
+    // (clean-core decisions only) one card per row. Only the save confirm may
+    // fall back to `prompt`: the headless path in loop.ts (maybeOfferSave)
+    // installs a prompt that blanket-answers 'y' to WHATEVER it is asked, so
+    // the row cards go through `confirm` only (never `prompt`), and a headless
+    // run confirms no row. Any further question routed through `prompt` would
+    // silently receive 'y' too: give maybeOfferSave's headless prompt a
+    // question-aware answer first.
     const answer = await askYesNo({ question: 'Save as project file?', confirm: args.confirm, prompt: args.prompt });
     if (!isYes(answer)) {
         args.onNotSaved?.('declined');
         return null;
     }
+    // 2026-10-06 — a clean-core triage becomes team project decisions only row by
+    // row, each on its own Yes. Without a joined team project nothing is asked.
+    if (spec.artefactType === 'clean-core-decision') {
+        const { confirmCleanCoreRows } = await import('./clean-core-confirm.js');
+        const { activeProject } = await import('../register/store.js');
+        extract = await confirmCleanCoreRows(extract, {
+            ...(args.confirm ? { confirm: args.confirm } : {}), log: args.log, joined: activeProject() !== null,
+        });
+    }
     let env;
     if (planExtract && prior) {
         // C1 (D30) — the 49dd duplicate: the generic save used to mint a fresh
@@ -438,9 +460,16 @@ export async function runSaveCommand(args) {
         const joined = activeProject();
         if (joined) {
             const { recordFromEnvelope } = await import('../register/records.js');
-            const res = recordFromEnvelope(env, path, joined, { name: args.author.name }, args.cwd);
+            const res = recordFromEnvelope(env, path, joined, { name: joined.name ?? args.author.name }, args.cwd);
             if (res?.file)
-                args.log(`Recorded for team project ${joined.projectId}: ${res.written} objects → ${res.file}`);
+                args.log(`Recorded for team project ${joined.projectId}: ${res.written} objects → ${basename(res.file)}`);
+            if (res?.file) {
+                const { regenerateWorkingList } = await import('../register/workbooks.js');
+                // The name the team project knows this laptop by (init --lead), as the team verbs use.
+                const sheet = regenerateWorkingList(joined, joined.name ?? args.author.name);
+                if (sheet.line)
+                    args.log(sheet.line.trimStart());
+            }
             if (res?.refused.length) {
                 args.log(`Not recorded (${res.refused.length} not in the team project's object list): ${res.refused.slice(0, 5).join(', ')}${res.refused.length > 5 ? ', …' : ''}`);
             }

package/dist/projects/validate.js

@@ -5,7 +5,7 @@ const KNOWN_ARTEFACT_TYPES = [
     'upgrade-scan', 'upgrade-progress', 'upgrade-report',
     'cca-assessment',
     'modernize-result', 'test-coverage',
-    'plan',
+    'plan', 'clean-core-decision',
 ];
 const STATUS_BY_TYPE = {
     'spec-gap': ['open', 'answered', 'deferred', 'n-a'],
@@ -20,6 +20,7 @@ const STATUS_BY_TYPE = {
     'modernize-result': ['applied', 'skipped', 'failed', 'pending'],
     'test-coverage': ['generated', 'skipped', 'failed', 'pending'],
     'plan': ['todo', 'designing', 'building', 'verifying', 'validated', 'validated-with-waiver', 'blocked'],
+    'clean-core-decision': ['proposed', 'confirmed', 'declined'],
 };
 const REQUIRED_TOP_LEVEL = [
     'schemaVersion', 'artefactType', 'id', 'title',

package/dist/projects/workspace.js

@@ -27,6 +27,7 @@ import { dirname, join, isAbsolute } from 'node:path';
 import os from 'node:os';
 import toml from '@iarna/toml';
 import { loadConfig } from '../config/loader.js';
+import { configFile } from '../config/paths.js';
 /**
  * Walk up the directory tree from `startDir` looking for a `.git` entry
  * (file or directory — submodules use a file). Returns the directory
@@ -152,7 +153,7 @@ export async function ensureWorkspace() {
 export function ensureWorkspaceSync() {
     let target = defaultWorkspaceFor(process.cwd());
     try {
-        const cfgPath = join(os.homedir(), '.cspeach', 'config.toml');
+        const cfgPath = configFile();
         if (existsSync(cfgPath)) {
             const raw = readFileSync(cfgPath, 'utf-8');
             const parsed = toml.parse(raw);

package/dist/register/atc-file.js

@@ -254,6 +254,14 @@ const quoteNeverClosed = (line) => `A quotation mark in line ${line} is never cl
  * binary on one line — none of which may reach a person through CSPeach.
  */
 export function shown(text) {
+    return shownUpTo(text, 60);
+}
+/**
+ * The same cleaning as `shown()`, with a longer cap: for text a person wrote on
+ * purpose (a decision's reason), which is read whole, not glanced at in a list.
+ * Kept to `max` characters, then "…".
+ */
+export function shownUpTo(text, max) {
     const flat = String(text)
         // An OSC sequence runs to BEL or ESC-backslash and can retitle the window.
         .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)?/g, ' ')
@@ -268,7 +276,7 @@ export function shown(text) {
         .replace(/[\x00-\x1f\x7f-\x9f]+/g, ' ')
         .replace(/\s+/g, ' ')
         .trim();
-    return flat.length > 60 ? `${flat.slice(0, 60)}…` : flat;
+    return flat.length > max ? `${flat.slice(0, max)}…` : flat;
 }
 /** Five names and the count of the rest: a list nobody can read is a list nobody acts on. */
 export const upToFive = (items) => (items.length > 5 ? `${items.slice(0, 5).join(', ')} and ${items.length - 5} more` : items.join(', '));

package/dist/register/findings.js

@@ -0,0 +1,79 @@
+/**
+ * Rule by rule, what the runs found in each object — the detail the register
+ * itself keeps only as counts. Read from the same measurement records, with the
+ * register's own two rules: only the team project's check variant counts, and
+ * live evidence outranks file evidence, per object.
+ *
+ * Used by `cspeach team fixed` (which rules are open now) and by the read-only
+ * team_findings tool (what a triage proposes from). No source code is in here:
+ * a record carries a rule id and a message title, nothing more.
+ */
+import { normalizeKey, normalizeRuleId, UNNAMED_FINDING } from '@cspeach/register-core';
+import { shown } from './atc-file.js';
+import { collectRecords, readProjectFile } from './store.js';
+/** Re-exported for the read-only team_findings tool: the one cleaning, a longer cap. */
+export { shownUpTo } from './atc-file.js';
+const variantKey = (v) => (typeof v === 'string' ? v.trim().toUpperCase() : '');
+const basisOf = (v) => {
+    if (v === undefined || v === null)
+        return 'system';
+    const w = String(v).trim().toLowerCase();
+    return w === '' || w === 'system' ? 'system' : 'file';
+};
+export function findingsByObject(projectDir, outboxDir) {
+    const project = readProjectFile(projectDir);
+    const ours = variantKey(project.atcVariant);
+    const records = [
+        ...collectRecords(projectDir).records,
+        ...(outboxDir && outboxDir !== projectDir ? collectRecords(outboxDir).records : []),
+    ];
+    const runs = records
+        .filter((r) => r?.kind === 'record' && r.recordType === 'measurement' && r.projectId === project.projectId
+        && typeof r.recordId === 'string' && Number.isFinite(Date.parse(r.at)) && Array.isArray(r.rows))
+        .filter((r) => { const theirs = variantKey(r.atcVariant); return !(theirs && ours && theirs !== ours); })
+        .map((r) => ({ ...r, at: new Date(r.at).toISOString() }))
+        .sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : a.recordId < b.recordId ? -1 : a.recordId > b.recordId ? 1 : 0));
+    const seenIds = new Set();
+    const byKey = new Map();
+    for (const r of runs) {
+        if (seenIds.has(r.recordId))
+            continue; // a sync tool's "(1)" copy
+        seenIds.add(r.recordId);
+        for (const row of r.rows) {
+            if (typeof row?.key !== 'string' || !Array.isArray(row.findings))
+                continue;
+            const key = normalizeKey(row.key);
+            const list = byKey.get(key) ?? [];
+            let seen = list.find((s) => s.recordId === r.recordId);
+            if (!seen) {
+                seen = { at: r.at, recordId: r.recordId, basis: basisOf(r.basis), rules: new Map() };
+                list.push(seen);
+            }
+            for (const f of row.findings) {
+                const named = !!f && typeof f === 'object';
+                const rule = (named ? normalizeRuleId(f.rule) : typeof f === 'string' ? normalizeRuleId(f) : '') || UNNAMED_FINDING;
+                // `shown()`: the title was written on another laptop or came out of a
+                // handed-over file, and it goes to a terminal and to the model's tools.
+                const message = named && typeof f.message === 'string' ? shown(f.message) : '';
+                const had = seen.rules.get(rule);
+                if (had) {
+                    had.count += 1;
+                    if (!had.message && message)
+                        had.message = message;
+                }
+                else
+                    seen.rules.set(rule, { rule, message, count: 1 });
+            }
+            byKey.set(key, list);
+        }
+    }
+    const out = new Map();
+    for (const [key, list] of byKey) {
+        const driving = list.some((s) => s.basis === 'system') ? list.filter((s) => s.basis === 'system') : list;
+        const first = driving[0] ?? null;
+        const last = driving[driving.length - 1] ?? null;
+        const rules = (s) => (s ? [...s.rules.values()].sort((a, b) => (a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0)) : []);
+        out.set(key, { key, baselineAt: first?.at ?? null, baseline: rules(first), latestAt: last?.at ?? null, latest: rules(last) });
+    }
+    return out;
+}

package/dist/register/measure.js

@@ -39,6 +39,8 @@ import { writeRecord } from './records.js';
  * row they get says so.
  */
 export const ABSENT_MEANS_CLEAN = false;
+/** R-1: how many silent objects one measurement checks again, one run each. */
+export const MAX_SECOND_PASS = 200;
 export function scopeLabel(scope) {
     if (scope.kind === 'lane')
         return `lane:${scope.id.trim()}`;
@@ -257,6 +259,7 @@ function readOutcome(answer) {
     return o;
 }
 export async function measure(input) {
+    const started = Date.now();
     const label = scopeLabel(input.scope);
     // One object, one row, however often the baseline names it: a case-twin would
     // otherwise be asked for twice and counted twice.
@@ -326,6 +329,60 @@ export async function measure(input) {
         if (!(said === 'absent' && evidenceOf.get(key) === 'listed'))
             evidenceOf.set(key, said);
     }
+    // ── R-1: the objects the run did not list, each checked again on its own ──
+    let secondPass;
+    let notChecked = new Set();
+    let ownFindings = [];
+    if (input.confirmAbsent && !absentMeansClean && !outcome.stopped && !input.signal?.aborted) {
+        const silent = inScope.filter((o) => buckets.get(objectKey(o.type, o.name)) === 'absent');
+        if (silent.length) {
+            const toRun = silent.slice(0, Math.max(0, input.secondPassCap ?? MAX_SECOND_PASS));
+            const skipped = silent.slice(toRun.length).map((o) => objectKey(o.type, o.name));
+            const left = input.maxTotalMs ? input.maxTotalMs - (Date.now() - started) : undefined;
+            if (toRun.length && (left === undefined || left > 0)) {
+                const again = readOutcome(await input.atc.runSet(toRun.map((o) => ({ type: o.type, name: o.name })), variant, {
+                    chunkSize: 1, maxSingleRuns: 0,
+                    ...(input.signal ? { signal: input.signal } : {}),
+                    ...(left !== undefined ? { maxTotalMs: left } : {}),
+                    ...(input.onProgress ? { onProgress: input.onProgress } : {}),
+                }));
+                const asked = new Set(toRun.map((o) => objectKey(o.type, o.name)));
+                // Only a run that LISTED the object counts. A refused or cut-short own run
+                // leaves it exactly where the first run left it: absent, no row.
+                const seen = new Set(again.measured.filter((m) => m?.evidence === 'listed').map(refKey).filter((k) => asked.has(k)));
+                for (const key of seen) {
+                    claims.get(key)?.delete('absent');
+                    claim(key, 'measured');
+                    buckets.set(key, 'measured');
+                    evidenceOf.set(key, 'listed');
+                }
+                ownFindings = again.findings.filter((f) => typeof f?.key === 'string' && seen.has(normalizeKey(f.key)));
+                // An own run that FINISHED and still did not list the object is the
+                // variant's silence, said twice. Anything else — refused, never reached —
+                // was not checked again, and nothing may be said about why.
+                const didNotFinish = new Set([
+                    ...again.failed.map(refKey),
+                    ...again.chunks.filter((c) => c?.status === 'refused' && !c.superseded).flatMap((c) => list(c.asked).map(refKey)),
+                ]);
+                const silentAgain = new Set(again.measured.filter((m) => m?.evidence !== 'listed').map(refKey)
+                    .filter((k) => asked.has(k) && !seen.has(k) && !didNotFinish.has(k)));
+                const unreached = [...asked].filter((k) => !seen.has(k) && !silentAgain.has(k));
+                const stopped = STOPPED_BY.has(again.stopped) ? again.stopped
+                    : input.signal?.aborted ? 'aborted' : undefined;
+                notChecked = new Set([...unreached, ...skipped]);
+                secondPass = {
+                    asked: toRun.length, listed: seen.size, skipped: skipped.length,
+                    ...(skipped.length ? { skippedBy: 'cap' } : {}),
+                    ...(unreached.length ? { notChecked: unreached.length } : {}),
+                    ...(stopped ? { stopped } : {}),
+                };
+            }
+            else {
+                notChecked = new Set(silent.map((o) => objectKey(o.type, o.name)));
+                secondPass = { asked: 0, listed: 0, skipped: silent.length, skippedBy: toRun.length ? 'time' : 'cap' };
+            }
+        }
+    }
     // Row order follows the scope, so two runs of the same lane read the same way.
     const rowRefs = inScope.filter((o) => buckets.get(objectKey(o.type, o.name)) === 'measured')
         .map((o) => ({ type: o.type, name: o.name, ...(evidenceOf.get(objectKey(o.type, o.name)) ? { evidence: evidenceOf.get(objectKey(o.type, o.name)) } : {}) }));
@@ -347,10 +404,11 @@ export async function measure(input) {
         ...coverage, unsupportedNames, absentNames, scope: label, refusedChunks,
         ...(duplicates ? { duplicateFindingsMerged: duplicates } : {}),
         ...(stoppedBy ? { stoppedBy } : {}),
+        ...(secondPass ? { secondPass, notCheckedNames: keysInScope.filter((k) => notChecked.has(k)).slice(0, MAX_ABSENT_NAMES) } : {}),
     };
     if (!rowRefs.length)
         return { ...counts, file: null, withFindings: 0, refusedRows };
-    const rows = findingsToRows(rowRefs, outcome.findings, input.project.type);
+    const rows = findingsToRows(rowRefs, [...outcome.findings, ...ownFindings], input.project.type);
     const res = writeRecord(input.joined, 'measurement', rows, input.by, {
         ...(input.now ? { now: input.now } : {}), ...(input.dir ? { dir: input.dir } : {}),
         ...(input.fileName ? { fileName: input.fileName } : {}), ...(input.rand ? { rand: input.rand } : {}),
@@ -361,6 +419,7 @@ export async function measure(input) {
         // below are recomputed after the refusal and are the ones a caller prints.
         extra: {
             atcVariant: variant, scope: label, basis: 'system', coverage,
+            ...(secondPass ? { secondPass } : {}),
             ...(duplicates ? { duplicateFindingsMerged: duplicates } : {}),
         },
     });

package/dist/register/offer.js

@@ -0,0 +1,33 @@
+/**
+ * The one line CSPeach prints after it activated, and verified, an object of
+ * the team project this laptop has joined (spec §4.3). It records nothing:
+ * "CSPeach activated it" and "the developer says it is fixed" are two different
+ * sentences, and only the second is a claim.
+ */
+import { objectKey } from '@cspeach/register-core';
+import { activeProject, readBaseline } from './store.js';
+export function teamFixOffers(objects) {
+    try {
+        const joined = activeProject();
+        if (!joined)
+            return [];
+        const baseline = readBaseline(joined.projectDir);
+        const byKey = new Map(baseline.map((o) => [objectKey(o.type, o.name), o]));
+        const byName = new Map();
+        for (const o of baseline)
+            byName.set(o.name.toUpperCase(), [...(byName.get(o.name.toUpperCase()) ?? []), o]);
+        const lines = [];
+        for (const o of objects) {
+            const type = String(o?.type ?? '').split('/')[0].trim().toUpperCase();
+            const name = String(o?.name ?? '').trim().toUpperCase();
+            const same = byName.get(name) ?? [];
+            const hit = byKey.get(objectKey(type, name)) ?? (same.length === 1 ? same[0] : undefined);
+            if (hit)
+                lines.push(`This object is in your team project. Mark it fixed? cspeach team fixed ${hit.type.toUpperCase()} ${hit.name.toUpperCase()}`);
+        }
+        return [...new Set(lines)];
+    }
+    catch {
+        return []; // a folder halfway through a sync must never touch an activation
+    }
+}

package/dist/register/picture.js

@@ -0,0 +1,21 @@
+import path from 'node:path';
+import { buildRegister, narrowedLanes } from '@cspeach/register-core';
+import { collectRecords, readBaseline, readLanes, readProjectFile } from './store.js';
+export function registerFor(projectDir, outboxDir) {
+    const project = readProjectFile(projectDir);
+    const collected = collectRecords(projectDir);
+    // This laptop's own outbox counts too, so a developer sees their work before
+    // handing it in. It is also the one way this picture can legitimately differ
+    // from the team project page's, so `status` says out loud when it counted them.
+    const own = outboxDir && path.resolve(outboxDir) !== path.resolve(projectDir) ? collectRecords(outboxDir) : { records: [], unreadable: 0, files: 0 };
+    const baseline = readBaseline(projectDir);
+    const lanes = readLanes(projectDir);
+    const register = buildRegister({ project, baseline, lanes, records: [...collected.records, ...own.records] });
+    return {
+        register, files: collected.files + own.files,
+        unreadable: collected.unreadable + own.unreadable, ownFiles: own.files,
+        // F2: a lanes.json written before names began to narrow packages holds
+        // fewer objects now. The lead is told, not left to work it out from a count.
+        narrowed: narrowedLanes(lanes, baseline),
+    };
+}

package/dist/register/records.js

@@ -137,6 +137,34 @@ export function fixRowsFromUpgradeProgress(content, baseline) {
     }
     return { rows, ambiguous };
 }
+/**
+ * Decision rows from a saved clean-core triage — CONFIRMED rows only (one Yes
+ * per row, clean-core-confirm.ts). The five words map onto the four
+ * classifications (spec §4.2); a fix or a rebuild with no target reaches A.
+ */
+export function decisionRowsFromCleanCore(content) {
+    const rows = [];
+    for (const r of content.adjudications ?? []) {
+        if (r?.confirmed !== true)
+            continue;
+        const moves = r.disposition === 'fix' || r.disposition === 'rebuild';
+        const base = r.disposition === 'keep' ? { classification: 'keep' }
+            : r.disposition === 'exception' ? { classification: 'keep', exception: true }
+                : r.disposition === 'fix' ? { classification: 'fix' }
+                    : r.disposition === 'rebuild' ? { classification: 'redesign' }
+                        : r.disposition === 'retire' ? { classification: 'retire' } : null;
+        if (!base)
+            continue;
+        const reason = typeof r.reason === 'string' ? r.reason.trim().slice(0, 300) : '';
+        rows.push({
+            key: objectKey(r.objectType, r.objectName), ...base,
+            ...(r.level ? { level: r.level } : {}),
+            ...(moves ? { targetLevel: r.targetLevel ?? 'A' } : {}),
+            ...(reason ? { reason } : {}),
+        });
+    }
+    return rows;
+}
 /**
  * Called after every successful envelope save. Does nothing unless this laptop
  * has joined a project; never throws (a record is a by-product, a save is not).
@@ -160,5 +188,9 @@ opts = {}) {
         const res = writeRecord(joined, 'fix', rows, by, { source, ...opts });
         return { ...res, refused: [...res.refused, ...ambiguous.map((n) => `${n} (name matches more than one object type)`)] };
     }
+    if (env.artefactType === 'clean-core-decision') {
+        const rows = decisionRowsFromCleanCore(env.content);
+        return writeRecord(joined, 'decision', rows, by, { source, ...opts });
+    }
     return null;
 }

package/dist/register/status-file/register-map.js

@@ -0,0 +1,213 @@
+// @ts-nocheck
+// GENERATED COPY — do not edit here. Edit viewer/src/lib/register-map.js,
+// then run `npx tsx scripts/sync-status-file.ts` (prebuild runs it too).
+// src/register/__tests__/status-file-pin.test.ts fails when this copy drifts.
+/**
+ * The map: one block per package, one cell per object, colour = state.
+ *
+ * Strings, not DOM, for two reasons: the status file is a document with no
+ * script in it and needs the same picture as text; and 20,000 cells arrive in
+ * one innerHTML assignment rather than 20,000 createElement calls.
+ *
+ * Colour is a CSS class (`s-verified`), never a style attribute: the page's
+ * Content-Security-Policy forbids inline styles, and the status file and the
+ * page then share one stylesheet.
+ */
+import { STATE_ORDER, STATE_LABEL, FROM_FILE, NOT_MENTIONED, NOT_REPORTED } from './register-model.js';
+const ENTITIES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+/**
+ * The one escaping function for the whole page. Object, package, lane and
+ * person names all come from a shared folder and are untrusted text.
+ * The two quote characters are written as `\x22` and `\x27`. They are the same
+ * characters, and a quote inside a regex literal blinds the word scanner that
+ * reads these files (`team-words.test.js`): it knows strings and comments but
+ * not regexes, so one `"` here flips text and code around for the rest of the
+ * file and the guard goes quiet. Leave them escaped.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function esc(value) {
+    return value == null ? '' : String(value).replace(/[&<>\x22\x27]/g, (c) => ENTITIES[c]);
+}
+/**
+ * The class for a state. The states are a closed set: an unknown or hostile
+ * state becomes `s-unknown`, never a raw value, because `class` is
+ * space-separated and escaping does not neutralise a space — a state of
+ * "clean hidden" would otherwise add the class `hidden` and hide the cell.
+ * @param {unknown} state
+ * @returns {string}
+ */
+export function stateClass(state) {
+    return `s-${Object.hasOwn(STATE_LABEL, state) ? state : 'unknown'}`;
+}
+/**
+ * The words for a state, from the same closed set: an unknown state — or an
+ * inherited property name like "constructor" — reads "Unknown".
+ * @param {unknown} state
+ * @returns {string}
+ */
+export function stateLabel(state) {
+    return Object.hasOwn(STATE_LABEL, state) ? STATE_LABEL[state] : 'Unknown';
+}
+/**
+ * The newest measurement this object's colour was actually read from.
+ *
+ * `counted` is register-core's own answer to "did this run move the state", so
+ * the view never works that rule out a second time. Walking backwards stops at
+ * the first counted one, which on a real object is the last entry.
+ */
+function drivingNewest(o) {
+    const all = o?.measurements;
+    if (!Array.isArray(all))
+        return null;
+    for (let i = all.length - 1; i >= 0; i -= 1)
+        if (all[i]?.counted)
+            return all[i];
+    return null;
+}
+/**
+ * The words for an object's colour, with what that colour rests on.
+ *
+ * Three strengths, and only the two PROVEN states can carry the weaker two —
+ * "Did not hold, measured from a file" would be labelling a problem with how it
+ * was found. A colour read from a system run says nothing extra; one read from
+ * a file says so; and one that rests on SILENCE — nothing mentioned the object
+ * and it was counted clean anyway — says that instead, because nothing measured
+ * it at all.
+ *
+ * Whose silence it was follows the BASIS the state was read from: a file that
+ * did not mention it, or a check run that did not report it. Saying "in a file"
+ * of a live run would send a manager looking for an export that does not exist.
+ *
+ * It lives here, beside `stateLabel`, because the map's cells need it too: the
+ * `<title>` is the only thing a hover, a screen reader on the roving cell, and
+ * the status file's picture ever say about an object, and a file-backed "Clean"
+ * there would be the one place the label went missing.
+ *
+ * @param {{ state: string, measuredBasis?: string|null, measurements?: object[] }} o
+ * @returns {string}
+ */
+export function stateWord(o) {
+    const label = stateLabel(o?.state);
+    if (o?.state !== 'verified' && o?.state !== 'clean')
+        return label;
+    const fromFile = o.measuredBasis === 'file';
+    if (drivingNewest(o)?.evidence === 'absent')
+        return `${label} — ${fromFile ? NOT_MENTIONED : NOT_REPORTED}`;
+    return fromFile ? `${label} — ${FROM_FILE}` : label;
+}
+/**
+ * Wider than tall (reads like a block of text), and bounded so one huge
+ * package cannot run off the page. Nonsense in (NaN, negative) gives the
+ * smallest map rather than a NaN-sized picture.
+ * @param {number} count
+ * @returns {number}
+ */
+export function mapColumns(count) {
+    return Math.max(8, Math.min(60, Math.ceil(Math.sqrt(Math.max(0, count || 0)) * 1.6)));
+}
+/** The four clean-core levels. Anything else (absent, or a word this build does not know) is "not decided". */
+const LEVEL_SET = new Set(['A', 'B', 'C', 'D']);
+/** The five level buckets, in order, and their words: one table for the map, the legend and the bars. */
+export const LEVEL_BUCKETS = ['A', 'B', 'C', 'D', 'none'];
+export const LEVEL_WORD = { A: 'A', B: 'B', C: 'C', D: 'D', none: 'not decided' };
+/**
+ * The class for a level, from a closed set like the states: a hostile
+ * `levelNow` can never write a second class into the cell.
+ * @param {unknown} l
+ * @returns {string}
+ */
+export const levelClass = (l) => `l-${LEVEL_SET.has(l) ? l : 'none'}`;
+/** The only two roles a block may carry, so `role` can never be written into. */
+const BLOCK_ROLES = new Set(['group', 'img']);
+/**
+ * One package block as a single `<svg>` string.
+ * @param {{ package: string, objects: Array<{ key: string, type: string, name: string, state: string }> }} block
+ * `colourBy: 'level'` colours each cell by the level it stands at now
+ * (`levelNow`) instead of its state, and the title names that level. The state
+ * stays in the title either way.
+ * @param {{ cell?: number, gap?: number, role?: 'group'|'img', colourBy?: 'state'|'level' }} [opts]
+ * @returns {string}
+ */
+export function blockSvg(block, { cell = 10, gap = 2, role = 'group', colourBy = 'state' } = {}) {
+    // `group` by default: an image's children are presentational, and the page
+    // makes each cell something a reader can land on and open. `img` would hide
+    // every one of them from a screen reader.
+    //
+    // The status file asks for `img`, and is right to: it carries no script, so
+    // nothing there can open a cell, and a screen reader would otherwise be
+    // handed tens of thousands of shapes that do nothing. The set is closed, like
+    // the states — `role` is an attribute, and a caller must not be able to write
+    // a second one after it.
+    const safeRole = BLOCK_ROLES.has(role) ? role : 'group';
+    const n = block.objects.length;
+    const cols = mapColumns(n);
+    const rows = Math.max(1, Math.ceil(n / cols));
+    const step = cell + gap;
+    const width = cols * step - gap;
+    const height = rows * step - gap;
+    // `data-key` is how the page finds the object behind a cell that was clicked.
+    // A picture has no clicks, so in `img` mode it is 30 dead bytes per cell — on
+    // a 20,000-object project, most of a megabyte in a file somebody has to mail.
+    // The per-cell `<title>` stays either way: hovering a cell to read the name is
+    // worth its bytes in a document nobody can search any other way.
+    const keyed = safeRole !== 'img';
+    const byLevel = colourBy === 'level';
+    const rects = block.objects.map((o, i) => {
+        const x = (i % cols) * step;
+        const y = Math.floor(i / cols) * step;
+        // A retired object keeps its state colour in level mode: the level counts
+        // leave retired objects out, and a cell painted C that no count includes
+        // would show a manager two numbers for one folder.
+        const asLevel = byLevel && o.state !== 'retired';
+        return `<rect class="cell ${asLevel ? levelClass(o.levelNow) : stateClass(o.state)}"${keyed ? ` data-key="${esc(o.key)}"` : ''} x="${x}" y="${y}" width="${cell}" height="${cell}" rx="2">`
+            + `<title>${esc(o.name)} · ${esc(o.type)}${asLevel ? ` · level ${esc(LEVEL_WORD[LEVEL_SET.has(o.levelNow) ? o.levelNow : 'none'])}` : ''} · ${esc(stateWord(o))}</title></rect>`;
+    }).join('');
+    const label = `${block.package}: ${n.toLocaleString('en-US')} ${n === 1 ? 'object' : 'objects'}`;
+    return `<svg class="block-map" role="${safeRole}" aria-label="${esc(label)}" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">${rects}</svg>`;
+}
+/**
+ * The key to the colours: only the states that occur, worst first, with counts.
+ *
+ * `unknown` is the tenth colour, and it is not a state. A cell drawn in it
+ * holds something this build has no word for, and it is meant to look wrong —
+ * so the legend names it and counts it rather than leaving a mark on the map
+ * that nothing in the key accounts for.
+ *
+ * @param {Record<string, number>} byState
+ * @param {{ unknown?: number }} [opts]
+ * @returns {string}
+ */
+export function legendHtml(byState, { unknown = 0 } = {}) {
+    const entry = (cls, label, count) => `<li><span class="swatch ${cls}"></span>${esc(label)} <b>${esc(count.toLocaleString('en-US'))}</b></li>`;
+    const items = STATE_ORDER.filter((s) => (byState[s] ?? 0) > 0)
+        .map((s) => entry(stateClass(s), stateLabel(s), byState[s]));
+    if (unknown > 0)
+        items.push(entry(stateClass('unknown'), stateLabel('unknown'), unknown));
+    return `<ul class="legend">${items.join('')}</ul>`;
+}
+/**
+ * The key to the level colours: always all five, D included, with counts —
+ * or, for a folder from an older build with no level counts, one line saying so.
+ *
+ * The counts are register-core's own (`totals.byLevel.now`), never recounted
+ * here, so the legend and the "Levels now" bar are one number. Retired objects
+ * are outside those counts and drawn in their state colour, so they get their
+ * own entry when there are any.
+ *
+ * @param {Record<string, number>} counts  `totals.byLevel.now`
+ * @param {{ retired?: number }} [opts]
+ * @returns {string}
+ */
+export function levelLegendHtml(counts, { retired = 0 } = {}) {
+    const entry = (cls, label, count) => `<li><span class="swatch ${cls}"></span>${esc(label)} <b>${esc((count ?? 0).toLocaleString('en-US'))}</b></li>`;
+    // A folder from an older build has no level counts: say so, as the level bars
+    // do, rather than print five zeros that read as "measured, nothing there".
+    const items = counts
+        ? LEVEL_BUCKETS.map((l) => entry(`l-${l}`, LEVEL_WORD[l], counts[l]))
+        : ['<li>No levels recorded yet.</li>'];
+    if (retired > 0)
+        items.push(entry(stateClass('retired'), 'retired', retired));
+    return `<ul class="legend">${items.join('')}</ul>`;
+}