@holmes-lab/holmes-kit 0.1.9 → 0.1.10

package/dist/holmes/rtm/test-scope.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUPPORTED_TEST_FRAMEWORKS = void 0;
+exports.architectureGoverningFiles = architectureGoverningFiles;
 exports.accountChangedFiles = accountChangedFiles;
 exports.countTestCases = countTestCases;
 exports.extractAnchors = extractAnchors;
@@ -42,8 +43,50 @@ exports.computeTestScope = computeTestScope;
 // @implements A-SPEC-121.2
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const spec_types_1 = require("../spec/spec-types");
 const rtm_check_1 = require("./rtm-check");
 const DEFAULTS = { partialBlast: 3, fullBlast: 12 };
+/**
+ * Architecture-governing documents, picked out of a change set.
+ *
+ * @implements A-SPEC-233
+ * WHY THIS EXISTS. `assessRisk`'s architecture axis already returns `hard-hitl` for exactly these
+ * changes — "supersedes accepted ADR(s)" and "C-SPEC Forbidden Edges / Layer Rules changed". Nothing
+ * on the test side consumed that verdict. Measured 2026-08-22 on the built dist: a change impacting
+ * A-SPEC-224 (the structural-constraint slice itself) got tier `unit`, ONE test file, while
+ * `assessRisk` returned `hard-hitl`. The most dangerous change received the narrowest test run.
+ *
+ * WHY THIS PREDICATE IS COARSER THAN THE RISK AXIS, AND WHY THAT IS RIGHT. The risk axis asks "did
+ * the CONSTRAINTS change?" and answers precisely, via `cspecConstraintChanged(current, proposed)`.
+ * That needs before-and-after content, which is not available here: the change source is not always
+ * git — `change-source.ts` also diffs against a baseline hash tree, where no "before" exists to
+ * read. So this asks the weaker question it can actually answer: "was an architecture-governing
+ * document touched?" The two are allowed to differ because their cost asymmetries are opposite. A
+ * false positive on the risk axis interrupts a human for nothing; a false positive here runs more
+ * tests. Widening is this module's standing answer to uncertainty everywhere else, and it is the
+ * answer here too.
+ *
+ * WHAT IT DOES NOT SEE. Whether the edit changed a rule or only its prose. Deletions (`changedFiles`
+ * carries added/modified/renamed; `.ax/specs`/`.ax/decisions` deletion is gated separately). Any
+ * architecture decision recorded somewhere other than these two locations.
+ */
+function architectureGoverningFiles(changedFiles) {
+    if (!Array.isArray(changedFiles))
+        return [];
+    // The C-SPEC folder is READ from the type table, never spelled here. A second spelling of a
+    // location is a second thing to keep in step, and this repository has already paid for that
+    // (`isTestFile` drifted into two copies; `parseSpec`'s section split was restated and returned an
+    // empty section while the check that used it went green).
+    const cspecDir = `.ax/specs/${spec_types_1.SPEC_TYPES['C-SPEC'].folder}/`;
+    const out = new Set();
+    for (const f of changedFiles) {
+        if (typeof f !== 'string' || !f.endsWith('.md'))
+            continue;
+        if (f.startsWith('.ax/decisions/') || f.startsWith(cspecDir))
+            out.add(f);
+    }
+    return [...out].sort();
+}
 const stripSpecPrefix = (id) => (id.startsWith('SPEC:') ? id.slice('SPEC:'.length) : id);
 // "Is this a test file?" must be ONE predicate. Two copies had already drifted: the scanner excluded
 // JVM/.NET/Rust/C++ conventions from the production graph while this side still only recognized
@@ -279,15 +322,62 @@ function computeTestScope(impactedSpecsRaw, testAnchors, specs, coverageGaps = [
     // incomplete graph is not evidence of no impact — same epistemic state as C3 below, same answer.
     // Checked FIRST so a contradictory input (empty impact + unresolved present) resolves toward
     // full, never toward "nothing to re-test".
+    const architectureTouched = [...new Set(extras?.architectureTouched ?? [])].sort();
+    const obligationGaps = [...new Set(extras?.obligationGaps ?? [])].sort();
     if (unresolvedFiles.length > 0) {
         const shown = unresolvedFiles.slice(0, 5).join(', ');
         const suffix = unresolvedFiles.length > 5 ? ` (${unresolvedFiles.length} unresolved total)` : '';
         return {
             tier: 'full', impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius: 0,
-            hitsFoundational: false, coverageGaps: [...coverageGaps], unresolvedFiles,
+            hitsFoundational: false, coverageGaps: [...coverageGaps], unresolvedFiles, architectureTouched, obligationGaps,
             reason: `${unresolvedFiles.length} changed source file(s) resolved to no spec — cannot narrow safely, full regression: ${shown}${suffix}`,
         };
     }
+    // @implements A-SPEC-233
+    // This branch RETURNS. That, not its position, is what makes it beat the branches below, which
+    // only assign `tier`/`reason` and fall through to the shared return.
+    //
+    // The first cut of this comment claimed the placement was the contract, and gave a reason that is
+    // false: that below `impactedSpecs.length === 0` the signal would vanish. Measured — moving this
+    // block to just above the final return left all twelve cases green, because that branch does not
+    // return either. A comment asserting a guarantee the code does not make is the exact state this
+    // slice's own REQ exists to remove, so it is written as it actually is.
+    //
+    // The one real ordering relation is with the OTHER early return, `unresolvedFiles`. Both answer
+    // `full`, so the tier is never in question between them; what the order decides is which reason
+    // is reported, and `unresolvedFiles` wins because it names the files to anchor — an operator can
+    // act on that.
+    //
+    // What carries the weight instead of placement: an architecture document having changed is true
+    // regardless of blast, and true even when `impactedSpecs` is empty — the shape of a change that
+    // edits ONLY a C-SPEC, which resolves to no impacted spec at all.
+    if (architectureTouched.length > 0) {
+        const shown = architectureTouched.slice(0, 5).join(', ');
+        const suffix = architectureTouched.length > 5 ? ` (${architectureTouched.length} total)` : '';
+        return {
+            tier: 'full', impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius: 0,
+            hitsFoundational: false, coverageGaps: [...coverageGaps], unresolvedFiles: [], architectureTouched, obligationGaps,
+            reason: `architecture-governing document(s) changed — full regression: ${shown}${suffix}`,
+        };
+    }
+    // @implements A-SPEC-235
+    // Another early return, so it wins over the assigning branches below for the same reason the last
+    // one does. Its position among the OTHER early returns decides only which reason is reported —
+    // all three answer `full`. It comes last of the three because the two above signal larger
+    // uncertainty: a graph that cannot see a changed file, and an architecture document that moved.
+    //
+    // The reason names the TAG, not just the spec id. "coverage gap in A-SPEC-235" sends the reader
+    // to grep; "A-SPEC-235 [purity]" tells them the case to write.
+    if (obligationGaps.length > 0) {
+        const shown = obligationGaps.slice(0, 5).join(', ');
+        const suffix = obligationGaps.length > 5 ? ` (${obligationGaps.length} total)` : '';
+        return {
+            tier: 'full', impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius: 0,
+            hitsFoundational: false, coverageGaps: [...coverageGaps], unresolvedFiles: [],
+            architectureTouched, obligationGaps,
+            reason: `declared obligation(s) with no test — full regression: ${shown}${suffix}`,
+        };
+    }
     // Tier on the DIRECTLY-impacted A-SPECs (what the changed code implements), NOT the whole impacted
     // set — impactedBy always returns the ancestor chain up to the REQ root, so keying on it made every
     // change "reach a foundational REQ" → always full (verification H4). Downstream blast of the direct
@@ -332,5 +422,5 @@ function computeTestScope(impactedSpecsRaw, testAnchors, specs, coverageGaps = [
         tier = 'unit';
         reason = `localized impact (blast=${blastRadius}) — run the ${impactedTestFiles.length} impacted test file(s)`;
     }
-    return { tier, impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius, hitsFoundational, coverageGaps: [...coverageGaps], reason, unresolvedFiles: [] };
+    return { tier, impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius, hitsFoundational, coverageGaps: [...coverageGaps], reason, unresolvedFiles: [], architectureTouched, obligationGaps };
 }

package/dist/holmes/server/dashboard.d.ts

@@ -70,6 +70,28 @@ export interface PipelineRow {
     mutationScoreMeasured: false;
 }
 export declare function isCanonicalStatus(status: unknown): boolean;
+/**
+ * The kinds that are governed specs at all.
+ *
+ * @implements A-SPEC-219.1
+ * Held here rather than imported from SPEC_TYPES because REQ is a spec kind that SPEC_TYPES does
+ * list — the distinction this set draws is "document in the spec store that the pipeline governs"
+ * versus "document that lives there but never will", and JOB is the whole of the second group.
+ */
+export declare const SPEC_KINDS: Set<string>;
+/**
+ * Drop retired documents before anything reads the corpus.
+ *
+ * @implements A-SPEC-222.2
+ * A-SPEC-222.1 excluded `outdated` from `isGoverned` and claimed every other check would follow.
+ * `tspec-mirror.test.ts` refuted that, and the spec was corrected to name one known site. Measured
+ * 2026-08-22 it was three: /api/rtm exposed 132 retired ids, the heatmap 108, the graph 132 — a
+ * screen still pointing at documents retired the day before. Stated once here so the three sites
+ * cannot drift, with the suite enumerating the endpoints so a fourth cannot be added silently.
+ */
+export declare function activeSpecs<T extends {
+    status?: unknown;
+}>(specs: T[]): T[];
 /** `A-SPEC-219.1` -> `A-SPEC`, `REQ-021` -> `REQ`. */
 export declare function specKindOf(id: string): string;
 /**

package/dist/holmes/server/dashboard.js

@@ -33,12 +33,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPEC_KINDS = void 0;
 exports.startDashboardServer = startDashboardServer;
 exports.isCanonicalStatus = isCanonicalStatus;
+exports.activeSpecs = activeSpecs;
 exports.specKindOf = specKindOf;
 exports.buildPipelineRows = buildPipelineRows;
 // @implements A-SPEC-215
 // @implements A-SPEC-219
+// @implements A-SPEC-222.2
 const fs = __importStar(require("node:fs"));
 const http = __importStar(require("node:http"));
 const path = __importStar(require("node:path"));
@@ -77,7 +80,9 @@ async function startDashboardServer(options) {
         }
         if (parsedUrl === '/api/rtm') {
             try {
-                const specs = await store.list();
+                const allSpecs = await store.list();
+                const retiredSpecs = allSpecs.filter((s) => s.status === 'outdated');
+                const specs = activeSpecs(allSpecs);
                 const files = scanner.scan(root);
                 const implementedSpecIds = new Set();
                 for (const f of files) {
@@ -93,16 +98,29 @@ async function startDashboardServer(options) {
                 // anchored to it) answer different questions, and a spec whose status is outside the
                 // canonical vocabulary answers neither — it is excluded and counted separately instead of
                 // being silently scored 0, which read as "47 uncovered specs" when it meant "47 unmapped".
-                const canonical = enrichedSpecs.filter((s) => !s.legacyStatus);
+                const canonical = enrichedSpecs.filter((s) => !s.legacyStatus && exports.SPEC_KINDS.has(specKindOf(s.id)));
                 const approvedCount = canonical.filter((s) => s.status === 'approved').length;
                 const anchorable = enrichedSpecs.filter((s) => s.id.startsWith('A-SPEC') && !s.legacyStatus);
                 const anchoredCount = anchorable.filter((s) => s.covered).length;
-                const legacySpecs = enrichedSpecs.filter((s) => s.legacyStatus);
-                const legacyByKind = {};
-                for (const s of legacySpecs) {
-                    const kind = specKindOf(s.id);
-                    legacyByKind[kind] = (legacyByKind[kind] || 0) + 1;
-                }
+                // @implements A-SPEC-219.1
+                // Two populations sit outside the axes, and merging them into one number misleads: a reader
+                // of "legacy 49" concludes 49 documents need cleaning up, when 23 of them will never become
+                // specs no matter how long anyone waits. The population that prompted this split was
+                // `06_job/JOB-*`, work orders carrying an `assignee`; those were deleted under REQ-223
+                // once measurement showed all 23 pointed at retired REQs and at 46 source paths of which
+                // none still existed. The split stays because it is the guard: the next stray document
+                // lands here instead of in the cleanup backlog.
+                const outside = enrichedSpecs.filter((s) => s.legacyStatus || !exports.SPEC_KINDS.has(specKindOf(s.id)));
+                const unmappedSpecs = outside.filter((s) => exports.SPEC_KINDS.has(specKindOf(s.id)));
+                const nonSpecDocs = outside.filter((s) => !exports.SPEC_KINDS.has(specKindOf(s.id)));
+                const tally = (rows) => {
+                    const out = {};
+                    for (const s of rows) {
+                        const kind = specKindOf(s.id);
+                        out[kind] = (out[kind] || 0) + 1;
+                    }
+                    return out;
+                };
                 const approval = {
                     total: canonical.length,
                     approved: approvedCount,
@@ -113,7 +131,18 @@ async function startDashboardServer(options) {
                     anchored: anchoredCount,
                     pct: anchorable.length > 0 ? Math.round((anchoredCount / anchorable.length) * 100) : 0,
                 };
-                const legacy = { count: legacySpecs.length, byKind: legacyByKind };
+                // Reported, never silently dropped: without this the 132 excluded documents vanish and the
+                // screen cannot say where they went.
+                const retiredByKind = {};
+                for (const s of retiredSpecs) {
+                    const kind = specKindOf(s.id);
+                    retiredByKind[kind] = (retiredByKind[kind] || 0) + 1;
+                }
+                // Count and kinds only. Shipping the ids would put retired documents back into the very
+                // response this slice removes them from, and nothing on the screen renders them.
+                const retired = { count: retiredSpecs.length, byKind: retiredByKind };
+                const unmapped = { count: unmappedSpecs.length, byKind: tally(unmappedSpecs) };
+                const nonSpec = { count: nonSpecDocs.length, byKind: tally(nonSpecDocs) };
                 const coveredCount = enrichedSpecs.filter((s) => s.covered).length;
                 const totalCount = enrichedSpecs.length;
                 const body = JSON.stringify({
@@ -122,7 +151,9 @@ async function startDashboardServer(options) {
                     coveredCount,
                     approval,
                     implementation,
-                    legacy,
+                    unmapped,
+                    nonSpec,
+                    retired,
                     specs: enrichedSpecs,
                     files,
                 });
@@ -140,7 +171,8 @@ async function startDashboardServer(options) {
         // @implements A-SPEC-219
         if (parsedUrl === '/api/rtm/heatmap') {
             try {
-                const specs = await store.list();
+                // @implements A-SPEC-222.2 — retired documents never reach a rendered view.
+                const specs = activeSpecs(await store.list());
                 const files = scanner.scan(root);
                 // FindingsLedger.list() returns [] for a missing file, which is indistinguishable from a
                 // clean scan. The dashboard therefore asks the filesystem directly: an audit lens that
@@ -188,7 +220,8 @@ async function startDashboardServer(options) {
         // @implements A-SPEC-219
         if (parsedUrl === '/api/graph') {
             try {
-                const specs = await store.list();
+                // @implements A-SPEC-222.2 — retired documents never reach a rendered view.
+                const specs = activeSpecs(await store.list());
                 const files = scanner.scan(root);
                 const nodes = [];
                 const edges = [];
@@ -472,6 +505,8 @@ function renderDashboardHtml() {
     .axis-stat { display: inline-flex; align-items: center; gap: 6px; }
     .legacy-chip { cursor: pointer; border: 1px dashed #64748b; border-radius: 999px; padding: 4px 10px; }
     .legacy-chip:hover { border-color: #f59e0b; color: #f59e0b; }
+    .nonspec-chip { cursor: pointer; border: 1px solid #334155; border-radius: 999px; padding: 4px 10px; color: #64748b; }
+    .nonspec-chip:hover { border-color: #94a3b8; color: #94a3b8; }
     .scope-notice { font-size: 12px; color: #94a3b8; background: #0f172a; border: 1px solid #334155; border-radius: 8px; padding: 8px 12px; margin-bottom: 10px; }
     .scope-notice-truncated { color: #fbbf24; border-color: #b45309; border-style: dashed; }
     .stage-missing { color: #64748b; font-style: italic; cursor: default; background: repeating-linear-gradient(45deg, rgba(100,116,139,0.06) 0 6px, transparent 6px 12px); }
@@ -500,7 +535,8 @@ function renderDashboardHtml() {
     <div class="axis-stats">
       <span class="axis-stat" title="Specs signed off, over specs using the canonical status vocabulary">📋 Approval <span id="approvalStat" class="stat-badge">--%</span></span>
       <span class="axis-stat" title="A-SPECs with code anchored to them, over canonical A-SPECs">⚙️ Implementation <span id="implStat" class="stat-badge">--%</span></span>
-      <span class="axis-stat legacy-chip" id="legacyChip" title="Specs whose status is outside draft|review|approved|outdated — excluded from both axes, not scored zero" onclick="switchTab('legacy')">🏷️ <span id="legacyStat">--</span></span>
+      <span class="axis-stat legacy-chip" id="unmappedChip" title="Spec documents whose status is outside draft|review|approved|outdated — these are the cleanup backlog" onclick="switchTab('legacy')">🏷️ <span id="unmappedStat">--</span></span>
+      <span class="axis-stat nonspec-chip" id="nonSpecChip" title="Documents in the spec store that are not a governed spec kind — never a cleanup target" onclick="switchTab('legacy')">📋 <span id="nonSpecStat">--</span></span>
     </div>
   </div>
 
@@ -520,10 +556,17 @@ function renderDashboardHtml() {
   </div>
 
   <div id="legacyTab" style="display: none;">
-    <div class="ux-hint-banner" style="border-left-color: #64748b;">
-      <span>🏷️ <strong>Unmapped Specs:</strong> these documents use a status vocabulary outside <code>draft | review | approved | outdated</code>, so no governance gate has scored them. They are <strong>excluded</strong> from both headline axes — an unmapped vocabulary is not the same as an uncovered spec.</span>
+    <div class="ux-hint-banner" style="border-left-color: #f59e0b;">
+      <span>🏷️ <strong>Cleanup backlog:</strong> spec documents whose <code>status</code> falls outside <code>draft | review | approved | outdated</code>, so no governance gate has scored them. Each is waiting for <code>spec_upgrade</code> → <code>spec_retire</code>, or a rewrite into the current format. Excluded from both headline axes — an unmapped vocabulary is not an uncovered spec.</span>
+    </div>
+    <div id="unmappedGrid" class="rtm-container">Loading…</div>
+
+    <div id="nonSpecSection" style="display: none;">
+      <div class="ux-hint-banner" style="border-left-color: #334155; margin-top: 28px;">
+        <span>📋 <strong>Not specifications:</strong> documents that live in the spec store but are not a governed spec kind. They are <strong>not</strong> a cleanup target and never will be, and they have always sat outside both axes. Nothing should normally appear here — <code>spec-store-boundary.test.ts</code> fails the build when it does.</span>
+      </div>
+      <div id="nonSpecGrid" class="rtm-container"></div>
     </div>
-    <div id="legacyGrid" class="rtm-container">Loading unmapped specifications...</div>
   </div>
 
   <div id="heatmapTab" style="display: none;">
@@ -682,12 +725,32 @@ function renderDashboardHtml() {
 
     // Specs excluded from both axes get their own surface. Previously 47 documents were invisible
     // on every tab while still sitting in the headline denominator, which read as 0% coverage.
-    function renderLegacySpecGrid(specs) {
-      const container = document.getElementById('legacyGrid');
+    // @implements A-SPEC-219.1 — two populations, two destinations. Summing them is what misled:
+    // "49" read as "49 to clean up" while 23 of them will never become specs.
+    const SPEC_KINDS_UI = ['REQ', 'H-SPEC', 'A-SPEC', 'C-SPEC', 'T-SPEC'];
+    const kindOfId = (id) => (String(id).match(/^([A-Za-z-]+?)-\d/) || [null, 'UNKNOWN'])[1];
+
+    function renderUnmappedGrid(specs) {
+      const outside = specs.filter(s => s.legacyStatus || SPEC_KINDS_UI.indexOf(kindOfId(s.id)) === -1);
+      renderDocGroup(
+        document.getElementById('unmappedGrid'),
+        outside.filter(s => SPEC_KINDS_UI.indexOf(kindOfId(s.id)) !== -1),
+        'Every spec uses the canonical status vocabulary.',
+      );
+      // @implements A-SPEC-223 — an absent category is not explained. T-SPEC-219.1 asked for this
+      // as a boundary case and it was never implemented; the store is now empty of such documents,
+      // so the banner would describe something that does not exist.
+      const nonSpec = outside.filter(s => SPEC_KINDS_UI.indexOf(kindOfId(s.id)) === -1);
+      const section = document.getElementById('nonSpecSection');
+      if (section) section.style.display = nonSpec.length > 0 ? 'block' : 'none';
+      renderDocGroup(document.getElementById('nonSpecGrid'), nonSpec, '');
+    }
+
+    function renderDocGroup(container, rows, emptyMessage) {
       if (!container) return;
-      const legacy = specs.filter(s => s.legacyStatus);
+      const legacy = rows;
       if (legacy.length === 0) {
-        container.innerHTML = '<div style="color:#94a3b8; font-size:14px;">Every spec uses the canonical status vocabulary.</div>';
+        container.innerHTML = '<div style="color:#94a3b8; font-size:14px;">' + emptyMessage + '</div>';
         return;
       }
       const byKind = new Map();
@@ -744,12 +807,17 @@ function renderDashboardHtml() {
           allFiles = data.files || [];
           const ap = data.approval || { pct: 0, approved: 0, total: 0 };
           const im = data.implementation || { pct: 0, anchored: 0, total: 0 };
-          const lg = data.legacy || { count: 0, byKind: {} };
+          const um = data.unmapped || { count: 0, byKind: {} };
+          const ns = data.nonSpec || { count: 0, byKind: {} };
           document.getElementById('approvalStat').innerText = ap.pct + '% (' + ap.approved + '/' + ap.total + ')';
           document.getElementById('implStat').innerText = im.pct + '% (' + im.anchored + '/' + im.total + ')';
-          const kinds = Object.keys(lg.byKind || {}).map(k => k + ' ' + lg.byKind[k]).join(' · ');
-          document.getElementById('legacyStat').innerText = lg.count + ' unmapped' + (kinds ? ' (' + kinds + ')' : '');
-          renderLegacySpecGrid(data.specs || []);
+          const umKinds = Object.keys(um.byKind || {}).map(k => k + ' ' + um.byKind[k]).join(' · ');
+          const nsKinds = Object.keys(ns.byKind || {}).map(k => k + ' ' + ns.byKind[k]).join(' · ');
+          document.getElementById('unmappedStat').innerText = um.count + ' to clean up' + (umKinds ? ' (' + umKinds + ')' : '');
+          const nsChip = document.getElementById('nonSpecChip');
+          if (nsChip) nsChip.style.display = ns.count > 0 ? 'inline-flex' : 'none';
+          document.getElementById('nonSpecStat').innerText = ns.count + ' not specs' + (nsKinds ? ' (' + nsKinds + ')' : '');
+          renderUnmappedGrid(data.specs || []);
           renderReqQuantitativeGrid(allSpecs, allFiles);
         }
       } catch (err) {
@@ -2057,6 +2125,28 @@ const CANONICAL_STATUSES = new Set(['draft', 'review', 'approved', 'outdated']);
 function isCanonicalStatus(status) {
     return typeof status === 'string' && CANONICAL_STATUSES.has(status);
 }
+/**
+ * The kinds that are governed specs at all.
+ *
+ * @implements A-SPEC-219.1
+ * Held here rather than imported from SPEC_TYPES because REQ is a spec kind that SPEC_TYPES does
+ * list — the distinction this set draws is "document in the spec store that the pipeline governs"
+ * versus "document that lives there but never will", and JOB is the whole of the second group.
+ */
+exports.SPEC_KINDS = new Set(['REQ', 'H-SPEC', 'A-SPEC', 'C-SPEC', 'T-SPEC']);
+/**
+ * Drop retired documents before anything reads the corpus.
+ *
+ * @implements A-SPEC-222.2
+ * A-SPEC-222.1 excluded `outdated` from `isGoverned` and claimed every other check would follow.
+ * `tspec-mirror.test.ts` refuted that, and the spec was corrected to name one known site. Measured
+ * 2026-08-22 it was three: /api/rtm exposed 132 retired ids, the heatmap 108, the graph 132 — a
+ * screen still pointing at documents retired the day before. Stated once here so the three sites
+ * cannot drift, with the suite enumerating the endpoints so a fourth cannot be added silently.
+ */
+function activeSpecs(specs) {
+    return specs.filter((s) => s.status !== 'outdated');
+}
 /** `A-SPEC-219.1` -> `A-SPEC`, `REQ-021` -> `REQ`. */
 function specKindOf(id) {
     const m = /^([A-Za-z-]+?)-\d/.exec(String(id ?? ''));

package/dist/holmes/spec/approval-blockers.d.ts

@@ -2,12 +2,28 @@ import { Spec } from './spec-parser';
 /**
  * Sections that still hold nothing but a generated placeholder.
  *
- * Two generators plant placeholders and both are judged here:
- *  - `reverse_draft` writes `TODO — <prompt>` plus the INFERRED marker comment. Both are
- *    required together: 11 of this repository's 257 approved specs use the word "TODO" in
- *    legitimate prose ("남아 있는 TODO 주석을 제거한다"), and a word search refuses every one.
+ * Three shapes are judged, and the last two are a UNION rather than a replacement:
  *  - `spec_create` writes the bare literal `TODO` (`FIELD_PLACEHOLDER`) into each required section.
- *    That one is unambiguous on its own — an entire section equal to the string is never prose.
+ *    Unambiguous on its own — an entire section equal to that string is never prose.
+ *  - `reverse_draft` writes `TODO — <prompt>` plus the INFERRED marker. Requiring both together is
+ *    what lets a section that is FILLED with scan evidence and still carries a TODO count as
+ *    unfinished (`evidenceThenTodo`, the main brownfield shape REQ-181 created).
+ *  - A `TODO` line with nothing but furniture around it, marker or no marker.
+ *
+ * @implements A-SPEC-240
+ * WHY THE THIRD SHAPE EXISTS. Measured 2026-08-23 against the installed package: an H-SPEC whose
+ * eight prose sections all read `TODO — 사람이 쓸 것` — title and owner placeholders too — received
+ * `status: approved` and an `approved_digest`. The marker was absent, so nothing looked. `INFERRED`
+ * is an HTML comment: invisible when rendered, and easy to strip while editing the section around
+ * it. Keying the judgement on it means the protection can vanish silently.
+ *
+ * WHY IT IS A UNION AND NOT A REPLACEMENT. The first cut replaced the marker rule with the emptiness
+ * rule, and `evidenceThenTodo` walked through it — a file list reads as substance. Measured across
+ * 482 approved specs the two rules disagree on nothing, so the union costs no false refusals while
+ * each covers what the other cannot.
+ *
+ * The word "TODO" in ordinary prose is still safe: 37 approved sections use it that way
+ * ("남아 있는 TODO 주석을 제거한다"), and every one carries real content beside it.
  */
 export declare function placeholderSections(spec: Spec): string[];
 /**

package/dist/holmes/spec/approval-blockers.js

@@ -79,15 +79,56 @@ const stripFences = (s) => {
  * emptiness matters most.
  */
 const TODO_LINE = /^TODO\s*[—-]/m;
+/**
+ * Furniture a generator writes around the prose a human still owes.
+ *
+ * @implements A-SPEC-240
+ * Deliberately a closed, short list: an HTML comment (the markers), the reverse-engineering note,
+ * and the prompt line itself. Lengthening it widens what counts as "empty", which is a decision to
+ * refuse more documents — not one to make without measuring.
+ */
+const FURNITURE = [/^TODO\s*[—-]/, /^NOTE: this spec was REVERSE-ENGINEERED/];
+/**
+ * Is there anything left once the generator's furniture is removed?
+ *
+ * @implements A-SPEC-240
+ * A `TODO` line is the precondition for asking at all — see `placeholderSections`. What counts as
+ * adequate prose is a question a machine cannot answer, so a short but genuine section is left
+ * alone; only a section that is nothing BUT scaffolding is judged empty.
+ */
+function hasNoSubstance(text) {
+    const rest = stripFences(text)
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l !== '' && !FURNITURE.some((re) => re.test(l)));
+    return rest.length === 0;
+}
 /**
  * Sections that still hold nothing but a generated placeholder.
  *
- * Two generators plant placeholders and both are judged here:
- *  - `reverse_draft` writes `TODO — <prompt>` plus the INFERRED marker comment. Both are
- *    required together: 11 of this repository's 257 approved specs use the word "TODO" in
- *    legitimate prose ("남아 있는 TODO 주석을 제거한다"), and a word search refuses every one.
+ * Three shapes are judged, and the last two are a UNION rather than a replacement:
  *  - `spec_create` writes the bare literal `TODO` (`FIELD_PLACEHOLDER`) into each required section.
- *    That one is unambiguous on its own — an entire section equal to the string is never prose.
+ *    Unambiguous on its own — an entire section equal to that string is never prose.
+ *  - `reverse_draft` writes `TODO — <prompt>` plus the INFERRED marker. Requiring both together is
+ *    what lets a section that is FILLED with scan evidence and still carries a TODO count as
+ *    unfinished (`evidenceThenTodo`, the main brownfield shape REQ-181 created).
+ *  - A `TODO` line with nothing but furniture around it, marker or no marker.
+ *
+ * @implements A-SPEC-240
+ * WHY THE THIRD SHAPE EXISTS. Measured 2026-08-23 against the installed package: an H-SPEC whose
+ * eight prose sections all read `TODO — 사람이 쓸 것` — title and owner placeholders too — received
+ * `status: approved` and an `approved_digest`. The marker was absent, so nothing looked. `INFERRED`
+ * is an HTML comment: invisible when rendered, and easy to strip while editing the section around
+ * it. Keying the judgement on it means the protection can vanish silently.
+ *
+ * WHY IT IS A UNION AND NOT A REPLACEMENT. The first cut replaced the marker rule with the emptiness
+ * rule, and `evidenceThenTodo` walked through it — a file list reads as substance. Measured across
+ * 482 approved specs the two rules disagree on nothing, so the union costs no false refusals while
+ * each covers what the other cannot.
+ *
+ * The word "TODO" in ordinary prose is still safe: 37 approved sections use it that way
+ * ("남아 있는 TODO 주석을 제거한다"), and every one carries real content beside it.
  */
 function placeholderSections(spec) {
     const out = [];
@@ -98,7 +139,9 @@ function placeholderSections(spec) {
             continue;
         }
         const prose = stripFences(text);
-        if (TODO_LINE.test(prose) && prose.includes(draft_1.INFERRED))
+        if (!TODO_LINE.test(prose))
+            continue;
+        if (prose.includes(draft_1.INFERRED) || hasNoSubstance(text))
             out.push(name);
     }
     return out;

package/dist/holmes/spec/legacy-format.d.ts

@@ -35,6 +35,20 @@ export type FormatState =
 };
 /** Frontmatter key that preserves the pre-upgrade status. Named once so writer and reader agree. */
 export declare const LEGACY_STATUS_FIELD = "legacy_status";
+/**
+ * Where a legacy `depends_on` string is kept verbatim.
+ *
+ * @implements A-SPEC-221
+ * The old format wrote the parent as `REQ-001:<hash>`. The parser only understood arrays, so the
+ * whole value became `[]` — measured on H-SPEC-001, the upgrade destroyed the parent edge and then
+ * reported `orphan: H-SPEC requires a parent of type REQ` about the edge it had just removed.
+ *
+ * The digest is preserved rather than promoted. Writing it into `parent_digests` would assert that
+ * a `version_token`-era value is an approval digest, and there is no evidence the two are the same
+ * computation — asserting it anyway is the fabrication this repository keeps removing. Verbatim
+ * preservation leaves the judgement to a person who can actually make it.
+ */
+export declare const LEGACY_DEPENDS_FIELD = "legacy_depends_on";
 /**
  * Classify a document by FORMAT, not by validity.
  *

package/dist/holmes/spec/legacy-format.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LEGACY_STATUS_FIELD = void 0;
+exports.LEGACY_DEPENDS_FIELD = exports.LEGACY_STATUS_FIELD = void 0;
 exports.formatStateOf = formatStateOf;
 exports.legacyMessage = legacyMessage;
 exports.upgradePlan = upgradePlan;
@@ -8,6 +8,20 @@ exports.upgradedFrontmatter = upgradedFrontmatter;
 const spec_types_1 = require("./spec-types");
 /** Frontmatter key that preserves the pre-upgrade status. Named once so writer and reader agree. */
 exports.LEGACY_STATUS_FIELD = 'legacy_status';
+/**
+ * Where a legacy `depends_on` string is kept verbatim.
+ *
+ * @implements A-SPEC-221
+ * The old format wrote the parent as `REQ-001:<hash>`. The parser only understood arrays, so the
+ * whole value became `[]` — measured on H-SPEC-001, the upgrade destroyed the parent edge and then
+ * reported `orphan: H-SPEC requires a parent of type REQ` about the edge it had just removed.
+ *
+ * The digest is preserved rather than promoted. Writing it into `parent_digests` would assert that
+ * a `version_token`-era value is an approval digest, and there is no evidence the two are the same
+ * computation — asserting it anyway is the fabrication this repository keeps removing. Verbatim
+ * preservation leaves the judgement to a person who can actually make it.
+ */
+exports.LEGACY_DEPENDS_FIELD = 'legacy_depends_on';
 /**
  * Classify a document by FORMAT, not by validity.
  *

package/dist/holmes/spec/nonfunctional.d.ts

@@ -0,0 +1,70 @@
+/**
+ * One non-functional obligation, read from an H-SPEC's `## Non-Functional`.
+ *
+ * @implements A-SPEC-234
+ * WHY THIS EXISTS. `## Non-Functional` is a REQUIRED section — measured 2026-08-22, all 105 approved
+ * H-SPECs in this repository have one filled in. Nothing read it. The T-SPEC approval gate asks only
+ * for the four input quadrants (Normal/Corner/Negative/Boundary), which are an input-selection
+ * taxonomy: equivalence partitioning, boundary values, negative cases. Concurrency, resource
+ * exhaustion and partial failure are not kinds of INPUT but kinds of EXECUTION CONDITION, so they
+ * never belonged to that question and no gate ever asked about them.
+ *
+ * The cost is on record in this session: an H-SPEC declared a cost obligation, its T-SPEC was green
+ * on all four quadrants, and 10,558ms shipped for a 2KB file.
+ */
+export interface NonFunctionalObligation {
+    /** Author-chosen, lower-cased. The vocabulary is NOT fixed — see `parseNonFunctional`. */
+    tag: string;
+    /** The obligation as written, minus the tag. */
+    text: string;
+    /** The line as written, so a report can quote it. */
+    line: string;
+}
+/**
+ * Read the obligations out of a `## Non-Functional` section.
+ *
+ * @implements A-SPEC-234
+ * A malformed list item is RETURNED, never dropped. A typo that silently parses to nothing reads as
+ * "the rule passed" — the shape this repository has paid for in A-SPEC-191 §17, §29 and again in
+ * A-SPEC-222.2. Prose and blank lines are neither: a section is allowed to explain itself.
+ *
+ * THE TAG VOCABULARY IS NOT FIXED, AND THAT IS THE POINT. A closed set of allowed tags becomes a
+ * thing to maintain and then falls behind — the enumeration-chasing this repository already rejected
+ * for tool names (`write-target.ts`). Whatever the author writes IS the vocabulary; the machine
+ * judges CORRESPONDENCE between an H-SPEC tag and a T-SPEC tag, never meaning.
+ *
+ * WHAT THIS DOES NOT SEE. Whether the obligation is a good one. Whether the case tagged with it
+ * actually exercises it — a case reading `- [perf] Given nothing When nothing Then nothing` counts
+ * as met. Obligations written as prose without a tag (the other 105 documents). Those are human
+ * judgements, and simulating them would recreate the "documented but unenforced" state this slice
+ * exists to remove.
+ */
+export declare function parseNonFunctional(section: unknown): {
+    obligations: NonFunctionalObligation[];
+    malformed: string[];
+};
+/**
+ * The obligation tags a T-SPEC's CASES carry.
+ *
+ * @implements A-SPEC-234
+ * Only the four case sections count, and the section names are read from the type table rather than
+ * spelled here — a second spelling of a location is a second thing to keep in step, and this
+ * repository has already paid for that twice (`isTestFile` drifted into two copies; a restated
+ * section-splitting regex returned an empty section while the check using it went green).
+ *
+ * A tag anywhere else in the document states an INTENTION. Only a case is evidence that something
+ * was tested.
+ */
+export declare function caseObligationTags(sections: unknown): Set<string>;
+/**
+ * Obligations an H-SPEC declares that no child T-SPEC case answers.
+ *
+ * @implements A-SPEC-234
+ * Matching is EXACT after lower-casing. A prefix match would let `perf` be satisfied by
+ * `performance`, and a false "met" is a gate switched off that says nothing — the same asymmetry
+ * that made `call` targets exact in `forbidden-edges.ts`.
+ *
+ * `malformed` lines are NOT reported here. Flagging syntax errors and judging fulfilment are
+ * different questions; mixed together, one typo invents an obligation nobody declared.
+ */
+export declare function unmetObligations(nonFunctional: unknown, tspecSections: unknown[]): NonFunctionalObligation[];