@holmes-lab/holmes-kit 0.1.9 → 0.1.11

package/dist/holmes/mcp/handlers.js

@@ -41,6 +41,7 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const crypto = __importStar(require("node:crypto"));
 const node_child_process_1 = require("node:child_process");
+const spec_parser_1 = require("../spec/spec-parser");
 const validator_1 = require("../spec/validator");
 const rtm_check_1 = require("../rtm/rtm-check");
 const test_scope_1 = require("../rtm/test-scope");
@@ -106,6 +107,7 @@ const ledger_store_1 = require("../governance/ledger-store");
 const provenance_chain_1 = require("../governance/provenance-chain");
 const ledger_lock_1 = require("../governance/ledger-lock");
 const decision_ledger_1 = require("../guardrail/decision-ledger");
+const cspec_change_1 = require("../guardrail/cspec-change");
 /**
  * @implements A-SPEC-189 §7 (round 10)
  * A DELIBERATE refusal, distinguished by construction rather than by class.
@@ -428,6 +430,45 @@ function basisFor(root, withDisk = false) {
 }
 function makeRawHandlers(store) {
     const resolver = (specs) => (id) => specs.find((s) => s.id === id) ?? null;
+    /**
+     * Where the audit record for a governance act belongs — resolved BEFORE the act writes anything.
+     *
+     * @implements A-SPEC-222
+     * Extracted verbatim from spec_approve so retirement cannot drift from approval on the one rule
+     * A-SPEC-188 paid for twice: a bad root once left a standing seal with no ledger entry while the
+     * caller was told it failed, and a foreign root filed the only audit record in another project's
+     * ledger. Two copies of that rule would be two chances to lose it again.
+     */
+    const resolveLedgerRoot = (root) => {
+        if (store instanceof spec_store_1.LocalMarkdownRepository) {
+            const derived = projectRootOf(store.specsRoot);
+            const derivationFoundMarker = fs.existsSync(path.join(derived, '.ax'));
+            if (derivationFoundMarker) {
+                if (typeof root === 'string' && root !== '') {
+                    const askedProject = (0, write_target_1.resolveTarget)(projectRootOf(root), '.');
+                    const boundProject = (0, write_target_1.resolveTarget)(derived, '.');
+                    if (askedProject !== boundProject) {
+                        return {
+                            ok: false,
+                            reason: `이 서버는 ${boundProject} 프로젝트에 바인딩되어 있습니다 — 요청한 root ${root}는 ${askedProject} 프로젝트를 가리킵니다.`
+                                + ' 다른 프로젝트의 원장에 기록하지 않기 위해 쓰기 전에 거부합니다.',
+                        };
+                    }
+                }
+                return { ok: true, root: derived };
+            }
+            if (typeof root === 'string' && root !== '')
+                return { ok: true, root: projectRootOf(root) };
+            return {
+                ok: false,
+                reason: '스토어 위치에서 프로젝트를 파생할 수 없습니다(.ax 상위 디렉터리 없음) — 원장을 어디에 둘지 알 수 없어 쓰기 전에 거부합니다. root를 지정하십시오.',
+            };
+        }
+        if (typeof root !== 'string' || root === '') {
+            return { ok: false, reason: 'root가 없고 스토어에서 원장 위치를 파생할 수도 없습니다 — 쓰기 전에 거부합니다. root를 지정하십시오.' };
+        }
+        return { ok: true, root: projectRootOf(root) };
+    };
     return {
         async spec_create(a) {
             // @implements A-SPEC-169
@@ -674,6 +715,114 @@ function makeRawHandlers(store) {
             const remaining = (0, validator_1.validateSpec)(upgraded, resolver(after)).findings.filter((f) => f.level === 'error');
             return { ok: true, upgraded: true, type: plan.type, legacyStatus: plan.legacyStatus, remaining };
         },
+        /**
+         * Move a document to `outdated` — the only path there.
+         *
+         * @implements A-SPEC-222
+         * `outdated` was in SPEC_STATUSES with no code writing it and no document carrying it: a
+         * declared state nothing could reach. That mattered the moment 23 deprecated REQs needed
+         * cleaning up, because the only transition tool sends everything to `draft`, and calling a
+         * retired document "draft" is a worse lie than the non-canonical word it replaced.
+         *
+         * Retirement withdraws authority rather than granting it, so it does NOT need the approval key
+         * by default. Two cases invert that, and the threshold follows the RISK rather than the name of
+         * the act:
+         *
+         *  - A sealed document. The code gate demands an approved T-SPEC naming the target A-SPEC;
+         *    retiring that T-SPEC removes the demand. Unguarded, retirement is an approval bypass.
+         *  - A document an APPROVED spec depends on. That chain is holding something up right now.
+         */
+        async spec_retire(a) {
+            const all = await store.list();
+            if (all.filter((s) => s.id === a.id).length > 1) {
+                return {
+                    ok: false,
+                    reason: `${a.id}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본이 진본인지 도구가 고를 수 없어 폐기 전에 거부합니다.`,
+                };
+            }
+            const cur = await store.read(a.id);
+            if (!cur)
+                return { ok: false, reason: `spec ${a.id} not found` };
+            const spec = cur.spec;
+            // @implements A-SPEC-222 — a document with no `type:` cannot be filed: the store derives its
+            // folder from the kind, and there is none. Refuse rather than infer, because a wrongly
+            // inferred kind MOVES the document into another folder. Measured 2026-08-21: without this the
+            // store threw `Cannot read properties of undefined (reading 'folder')` on the first of the 23
+            // legacy documents this tool was built for — every unit fixture carried `type:`, which is how
+            // it got through. Declaring the kind is `spec_upgrade`'s job, so the refusal names it.
+            if (!spec.type) {
+                return {
+                    ok: false,
+                    reason: `${a.id}에는 \`type:\` 선언이 없습니다(구형식 문서) — 어느 폴더에 속하는지 알 수 없어 폐기할 수 없습니다.`
+                        + ' 종류를 추론하지 않는 이유는 잘못 추론한 종류가 문서를 다른 폴더로 옮기기 때문입니다.'
+                        + ` 먼저 spec_upgrade({ id: "${a.id}" })로 형식을 올린 뒤 다시 폐기하십시오 — 그 도구가 이전 status를 legacy_status로 보존합니다.`,
+                };
+            }
+            // Idempotent, and it writes NOTHING on the second call: overwriting the first retirement's
+            // reason would make the record graffiti rather than history.
+            if (spec.status === 'outdated') {
+                return { ok: true, retired: false, id: a.id, dependents: [], reason: `${a.id}은(는) 이미 outdated 입니다` };
+            }
+            const approvalRaw = process.env.HOLMES_APPROVAL;
+            let approval;
+            try {
+                approval = approvalRaw ? JSON.parse(approvalRaw) : undefined;
+            }
+            catch {
+                approval = undefined;
+            }
+            const covered = (0, risk_gate_1.approvalCovers)(approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString());
+            const sealed = typeof spec.frontmatter.approved_digest === 'string';
+            if (sealed && !covered) {
+                return {
+                    ok: false,
+                    reason: `${a.id}은(는) 봉인된 문서입니다 — 폐기는 이 행위를 덮는 유효한 대역외 HOLMES_APPROVAL 이 필요합니다.`
+                        + ' 코드 게이트를 막고 있는 approved T-SPEC 을 폐기하면 그 게이트가 열리므로, 폐기가 승인 우회 경로가 되지 않도록 fail-closed 로 막습니다.'
+                        + ' (범위를 쓰면 kind "spec-approve")',
+                };
+            }
+            const dependents = all.filter((s) => s.id !== a.id && s.dependsOn.includes(a.id));
+            const blocking = dependents.filter((s) => s.status === 'approved').map((s) => s.id);
+            if (blocking.length > 0) {
+                return {
+                    ok: false,
+                    reason: `${a.id}을(를) 폐기하면 approved 문서 ${blocking.join(', ')}의 사슬이 끊깁니다 — 지금 무언가를 지탱하고 있는 사슬이므로 거부합니다.`
+                        + ' 해당 문서를 먼저 폐기하거나 부모를 다른 문서로 옮기십시오.',
+                };
+            }
+            // Destination BEFORE the write, the order A-SPEC-188 fixed for spec_approve: a resolution
+            // failure must leave nothing behind.
+            const dest = resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            const ledgerRoot = dest.root;
+            const fm = { ...spec.frontmatter };
+            // Blank is omitted, never written: `retired_reason: ""` asserts a ground that does not exist,
+            // the same rule `legacy_status` follows. A document already carrying `superseded_by` has
+            // answered "why" already and is not asked twice.
+            const reason = typeof a.reason === 'string' ? a.reason.trim() : '';
+            if (reason && fm.superseded_by === undefined)
+                fm.retired_reason = reason;
+            try {
+                await store.write({ ...spec, status: 'outdated', frontmatter: fm }, { expectedVersion: cur.version });
+            }
+            catch (e) {
+                if (e instanceof spec_store_2.SpecVersionConflictError) {
+                    return { ok: false, reason: `폐기 진행 중 ${a.id}이(가) 바뀌었습니다 — 확인 후 다시 시도하십시오. 이번 폐기는 아무것도 쓰지 않았습니다.` };
+                }
+                throw e;
+            }
+            new ledger_store_1.FileLedgerStore(path.join(ledgerRoot, '.ax', 'ledger')).append({
+                ts: new Date().toISOString(),
+                actor: approval?.actor ?? 'unattributed',
+                kind: 'spec-retired',
+                summary: `retired ${a.id}${reason ? ` — ${reason}` : ''}`,
+                inputs: [a.id],
+                rationale: reason || (approval?.rationale ?? 'retired'),
+                ...(approval ? { authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token) } : {}),
+            });
+            return { ok: true, retired: true, id: a.id, dependents: dependents.map((s) => s.id) };
+        },
         async spec_approve(a) {
             const approvalRaw = process.env.HOLMES_APPROVAL;
             let approval;
@@ -1164,7 +1313,7 @@ function makeRawHandlers(store) {
         async test_run(a) {
             // Closes the decision->execution loop: scope -> run -> durable per-A-SPEC EXECUTION evidence
             // (what the constitution's ART-4 prefers over the syntactic count).
-            const { root, specs, scanned, changedSymbols, changeSource, scopeFallback, anchorImpactedSpecs, changedTestFiles, unresolvedFiles } = await deriveChangedContext(store, a.root, a, 'test_run');
+            const { root, specs, scanned, changedFiles, changedSymbols, changeSource, scopeFallback, anchorImpactedSpecs, changedTestFiles, unresolvedFiles } = await deriveChangedContext(store, a.root, a, 'test_run');
             const g = new rtm_graph_1.RtmGraph();
             let testScope;
             try {
@@ -1175,7 +1324,11 @@ function makeRawHandlers(store) {
                 // and the unresolved remainder ride in through extras. A nonempty change set can end in a
                 // scoped run or a full run — never in "nothing to do".
                 const widenedImpacted = [...new Set([...scope.impactedSpecs, ...anchorImpactedSpecs])];
-                testScope = (0, test_scope_1.computeTestScope)(widenedImpacted, (0, test_scope_1.scanTestAnchors)(root), specs, scope.coverageGaps, undefined, { changedTestFiles, unresolvedFiles });
+                // @implements A-SPEC-233 — the architecture axis of `assessRisk` already calls these changes
+                // `hard-hitl`; until now nothing on the test side consumed that verdict, so the most
+                // dangerous change could receive the narrowest run (measured 2026-08-22: tier `unit`, one
+                // test file, against `hard-hitl`).
+                testScope = (0, test_scope_1.computeTestScope)(widenedImpacted, (0, test_scope_1.scanTestAnchors)(root), specs, scope.coverageGaps, undefined, { changedTestFiles, unresolvedFiles, architectureTouched: (0, test_scope_1.architectureGoverningFiles)(changedFiles), obligationGaps: scope.obligationGaps });
                 // @implements A-SPEC-128
                 // No change set means no basis for narrowing. Widening is the same fail-safe direction
                 // computeTestScope already takes when no anchored test resolves — never a silently narrow run.
@@ -1343,7 +1496,7 @@ function makeRawHandlers(store) {
                 // @implements A-SPEC-130 — the same widened set as test_run, so review packaging and test
                 // scoping cannot disagree about what a change touches.
                 const widenedImpacted = [...new Set([...scope.impactedSpecs, ...anchorImpactedSpecs])];
-                const testScope = (0, test_scope_1.computeTestScope)(widenedImpacted, (0, test_scope_1.scanTestAnchors)(root), specs, scope.coverageGaps, undefined, { changedTestFiles, unresolvedFiles });
+                const testScope = (0, test_scope_1.computeTestScope)(widenedImpacted, (0, test_scope_1.scanTestAnchors)(root), specs, scope.coverageGaps, undefined, { changedTestFiles, unresolvedFiles, architectureTouched: (0, test_scope_1.architectureGoverningFiles)(changedFiles), obligationGaps: scope.obligationGaps });
                 // Honest signal (REQ-124 gate 2a): which changed files the CpgScanner
                 // did NOT ingest (e.g. non-.ts files), computed from the same
                 // changedFiles/scanned already derived above — no new git/scan calls.
@@ -1575,6 +1728,23 @@ function makeRawHandlers(store) {
                     g.close(); // release native SQLite handle even if build/query throws
                 }
             }
+            // @implements A-SPEC-225 — the flag that raises this action's risk is COMPUTED here, not
+            // taken from the party being judged. Measured 2026-08-22: nothing in the repository ever set
+            // `cspecConstraintChange`, so the hard-hitl branch guarding C-SPEC constraints could only fire
+            // if the actor changing them volunteered that they had. The precedent is one field away —
+            // `blastRadius` above is derived from the store rather than accepted from the caller — and the
+            // principle is the one `findings.ts` states for `basis`: a judge that stamps its own evidence
+            // turns the field into self-report.
+            //
+            // OR, never assignment: a caller may raise its own risk (that is their business) but may not
+            // lower the server's verdict.
+            const cspecId = (0, cspec_change_1.cspecTargetId)(typeof action.target === 'string' ? action.target : '');
+            if (cspecId !== null) {
+                const stored = (await store.list()).find((sp) => sp.id === cspecId);
+                const current = stored ? (0, spec_parser_1.serializeSpec)(stored) : null;
+                const proposed = typeof action.stagedContent === 'string' ? action.stagedContent : null;
+                action.cspecConstraintChange = (0, cspec_change_1.cspecConstraintChanged)(current, proposed) || action.cspecConstraintChange === true;
+            }
             const assessment = (0, risk_classifier_1.assessRisk)(action);
             // @implements A-SPEC-133 — coverage (scope + expiry), not mere well-formedness, decides whether
             // this approval authorizes THIS action. An out-of-scope or expired token no longer unblocks.

package/dist/holmes/mcp/tool-schemas.js

@@ -85,6 +85,18 @@ exports.TOOL_SCHEMAS = {
             required: ['id'],
         },
     },
+    spec_retire: {
+        description: "Move ONE named spec to `status: outdated` — the only path to that state. Retirement WITHDRAWS authority, so it needs no approval key by default; two cases invert that, because there the withdrawal opens a gate. A SEALED spec requires the same out-of-band HOLMES_APPROVAL as spec_approve, fail-closed: retiring the approved T-SPEC that blocks the code gate would remove the demand, making retirement an approval bypass. And a spec that an APPROVED spec depends on is refused outright, with the dependents named — that chain is holding something up right now. Records `spec-retired` in the provenance ledger, writes the reason into `retired_reason` (omitted when blank, or when `superseded_by` already answers why), and is idempotent: retiring an already-outdated spec writes nothing rather than overwriting the first retirement's reason.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: str('Id of the spec to retire.'),
+                reason: str('Why it is being retired. Omitted from the document when blank; not required when the spec already carries superseded_by.'),
+                root: str('Optional when the server is bound to a file store — the ledger location is derived from the store itself; if supplied it must resolve to the SAME project.'),
+            },
+            required: ['id'],
+        },
+    },
     spec_approve: {
         description: 'Approve a spec as a sealing ACT: confirm the ledger destination BEFORE sealing → validate (zero errors) → record approved_digest + parent_digests snapshots → status: approved (written only at the version this act read; a concurrent edit wins and the approval is refused for retry) → append spec-approved to the provenance ledger. Requires a valid out-of-band HOLMES_APPROVAL in the SERVER environment (fail-closed; nothing in the request can substitute). Refuses an unsealed approved parent — seal parents first.',
         inputSchema: {

package/dist/holmes/project/dependencies.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The names of every directly declared runtime dependency.
+ *
+ * @implements A-SPEC-236
+ * Takes a PARSED object, never a path. Real `package.json` files leave three of the four surfaces
+ * empty, so a function that read the file itself could not be exercised against the cases that
+ * matter — the ones this exists to close.
+ *
+ * WHAT THIS DOES NOT SEE. Transitive dependencies: the lockfile is not read, so a direct dependency
+ * pulling in a hundred new packages passes. That is a different claim of a different size, and the
+ * 27 prose statements this check repays ("신규 의존성 0", "No new dependency") all mean the direct
+ * ones. Versions are not compared either — they move legitimately, and a rule that reddens on every
+ * upgrade gets switched off, and a rule switched off guards nothing.
+ */
+export declare function declaredRuntimeDependencies(pkg: unknown): string[];

package/dist/holmes/project/dependencies.js

@@ -0,0 +1,58 @@
+"use strict";
+// @implements A-SPEC-236
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.declaredRuntimeDependencies = declaredRuntimeDependencies;
+/**
+ * Every declaration surface a runtime dependency can enter through.
+ *
+ * @implements A-SPEC-236
+ * Checking only `dependencies` would let a package arrive via `optionalDependencies` and pass — and
+ * a pass reads as "there is none". That is the shape this repository has already refused twice: in
+ * `write-target.ts`, where enumerating write tools let an unlisted one through, and in
+ * `risk-classifier.ts`, where enumerating write verbs let `sed -i` through. The surface is judged
+ * whole rather than the forbidden entries counted.
+ *
+ * `bundledDependencies` is an ARRAY of names while the other three are objects. `Object.keys` over
+ * an array yields `"0"`, `"1"`, … — a silently wrong set that still looks like an answer.
+ */
+const OBJECT_SURFACES = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+const ARRAY_SURFACES = ['bundledDependencies', 'bundleDependencies'];
+/**
+ * The names of every directly declared runtime dependency.
+ *
+ * @implements A-SPEC-236
+ * Takes a PARSED object, never a path. Real `package.json` files leave three of the four surfaces
+ * empty, so a function that read the file itself could not be exercised against the cases that
+ * matter — the ones this exists to close.
+ *
+ * WHAT THIS DOES NOT SEE. Transitive dependencies: the lockfile is not read, so a direct dependency
+ * pulling in a hundred new packages passes. That is a different claim of a different size, and the
+ * 27 prose statements this check repays ("신규 의존성 0", "No new dependency") all mean the direct
+ * ones. Versions are not compared either — they move legitimately, and a rule that reddens on every
+ * upgrade gets switched off, and a rule switched off guards nothing.
+ */
+function declaredRuntimeDependencies(pkg) {
+    const names = new Set();
+    if (!pkg || typeof pkg !== 'object' || Array.isArray(pkg))
+        return [];
+    const p = pkg;
+    for (const surface of OBJECT_SURFACES) {
+        const v = p[surface];
+        // A surface holding the wrong shape is skipped rather than thrown on: this reports what a
+        // package.json declares, and a malformed field is npm's error to raise, not this function's.
+        if (!v || typeof v !== 'object' || Array.isArray(v))
+            continue;
+        for (const name of Object.keys(v))
+            if (name)
+                names.add(name);
+    }
+    for (const surface of ARRAY_SURFACES) {
+        const v = p[surface];
+        if (!Array.isArray(v))
+            continue;
+        for (const name of v)
+            if (typeof name === 'string' && name)
+                names.add(name);
+    }
+    return [...names].sort();
+}

package/dist/holmes/project/json-state.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Is a parsed JSON value usable as a state record?
+ *
+ * @implements A-SPEC-237
+ * WHY THIS EXISTS AS A NAMED, SHARED FUNCTION. Every state reader in this repository guards itself
+ * with `try { JSON.parse(…) } catch { default }`, and that guard sees only a parse FAILURE. `null`,
+ * `42`, `"x"`, `true` and `[1,2]` are all valid JSON: the parse succeeds and the failure lands later,
+ * at the first property access, as a TypeError.
+ *
+ * Measured 2026-08-23, end to end: a project whose Stop hook answered `{"decision":"block"}` with
+ * eight article violations produced NO OUTPUT and exit 0 once `.ax/ledger/stop-guard.json` contained
+ * the four characters `null`. That file is gitignored and written by the hook itself, so one `echo`
+ * disabled governance leaving no trace. `HashCache` had the same shape with a milder consequence,
+ * while its own comment promised a damaged cache "must never block a reindex".
+ *
+ * Two call sites, ONE definition. This repository has twice paid for the alternative: `isTestFile`
+ * drifted into two copies until a Python file was excluded from the graph as a test AND gated as
+ * production at the same time, and a restated section-splitting regex returned an empty section
+ * while the check using it went green.
+ *
+ * `null` is `typeof "object"` and an array is too, which is exactly why the check cannot be a
+ * `typeof` test alone — the two forms that read as objects are the two that break.
+ */
+export declare function isJsonStateObject(value: unknown): boolean;

package/dist/holmes/project/json-state.js

@@ -0,0 +1,30 @@
+"use strict";
+// @implements A-SPEC-237
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isJsonStateObject = isJsonStateObject;
+/**
+ * Is a parsed JSON value usable as a state record?
+ *
+ * @implements A-SPEC-237
+ * WHY THIS EXISTS AS A NAMED, SHARED FUNCTION. Every state reader in this repository guards itself
+ * with `try { JSON.parse(…) } catch { default }`, and that guard sees only a parse FAILURE. `null`,
+ * `42`, `"x"`, `true` and `[1,2]` are all valid JSON: the parse succeeds and the failure lands later,
+ * at the first property access, as a TypeError.
+ *
+ * Measured 2026-08-23, end to end: a project whose Stop hook answered `{"decision":"block"}` with
+ * eight article violations produced NO OUTPUT and exit 0 once `.ax/ledger/stop-guard.json` contained
+ * the four characters `null`. That file is gitignored and written by the hook itself, so one `echo`
+ * disabled governance leaving no trace. `HashCache` had the same shape with a milder consequence,
+ * while its own comment promised a damaged cache "must never block a reindex".
+ *
+ * Two call sites, ONE definition. This repository has twice paid for the alternative: `isTestFile`
+ * drifted into two copies until a Python file was excluded from the graph as a test AND gated as
+ * production at the same time, and a restated section-splitting regex returned an empty section
+ * while the check using it went green.
+ *
+ * `null` is `typeof "object"` and an array is too, which is exactly why the check cannot be a
+ * `typeof` test alone — the two forms that read as objects are the two that break.
+ */
+function isJsonStateObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/holmes/reverse/scan.js

@@ -105,8 +105,15 @@ function candidates(root, scan) {
         : all.filter((f) => !ignore.isIgnored(f.sourcePath));
     // Tests come from the tracked list rather than from the scan, which excludes them by design. An
     // untracked test is dropped for the same reason untracked code is: it is not part of the system.
+    //
+    // @implements A-SPEC-241
+    // Coming from the tracked list means they arrive WITHOUT the directory exclusions `scan()` applies
+    // to the source candidates above, and being tracked does not answer whether a file is vendor code:
+    // adopting holmes-kit runs `npm install`, and one `git add -A` commits the tree it created.
+    // Measured on a real Python codebase — 254 of 340 discovered tests were dependencies' own, and
+    // three were attributed to project clusters as coverage.
     const testFiles = (tracked ? [...tracked].filter((p) => SCANNABLE_RE.test(p)) : walkTestFiles(root))
-        .filter((p) => (0, test_files_1.isTestFile)(p) && !ignore?.isIgnored(p))
+        .filter((p) => (0, test_files_1.isTestFile)(p) && !(0, cpg_scanner_1.isUnderSkippedDir)(p) && !ignore?.isIgnored(p))
         .sort(cmp);
     return {
         files, testFiles, scanned: all.length, droppedUntracked: all.length - files.length,

package/dist/holmes/review/scope.d.ts

@@ -9,5 +9,34 @@ export interface ReviewScope {
     }>;
     unrequestedSymbols: string[];
     coverageGaps: string[];
+    /**
+     * Declared non-functional obligations no child T-SPEC answers, as `"<A-SPEC id> [<tag>]"`.
+     *
+     * @implements A-SPEC-235
+     * Kept BESIDE `coverageGaps`, never merged into it. Merged, the tier's reason reads
+     * "coverage gaps (3)" and cannot say whether a T-SPEC is missing or an obligation is unanswered —
+     * and the operator's next action differs: write a T-SPEC, versus tag one case.
+     */
+    obligationGaps: string[];
 }
+/**
+ * Obligations declared by the parent H-SPEC of an impacted A-SPEC that no child T-SPEC answers.
+ *
+ * @implements A-SPEC-235
+ * WHY THIS EXISTS. `coverageGaps` already forces full regression, but it asks only whether a
+ * T-SPEC DOCUMENT exists. A T-SPEC that exists and does not test the obligation its H-SPEC declared
+ * is not a gap under that definition, and measured by keyword over the corpus, 14 of the 24 H-SPECs
+ * declaring an obligation are in exactly that state.
+ *
+ * Fulfilment is judged by `unmetObligations` and nowhere else. A second judgement path drifts from
+ * the first; this repository has paid for that with `isTestFile` (two copies, and a Python file was
+ * excluded from the graph as a test AND gated as production at the same time) and with a restated
+ * section-splitting regex that returned an empty section while the check using it went green.
+ *
+ * WHAT IT DOES NOT SEE. Obligations written as prose rather than with the tag grammar — the other
+ * 105 approved documents. That is opt-in by design: introducing the rule and repairing the corpus in
+ * one slice makes it impossible to tell which half failed. Nor whether a case tagged `[perf]`
+ * exercises anything; correspondence is checked, meaning is not.
+ */
+export declare function obligationGapsFor(specs: Spec[], impactedSpecIds: string[]): string[];
 export declare function computeReviewScope(graph: RtmGraph, specs: Spec[], changedSymbols: string[]): ReviewScope;

package/dist/holmes/review/scope.js

@@ -1,7 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.obligationGapsFor = obligationGapsFor;
 exports.computeReviewScope = computeReviewScope;
 const rtm_builder_1 = require("../rtm/rtm-builder");
+const nonfunctional_1 = require("../spec/nonfunctional");
+/**
+ * Obligations declared by the parent H-SPEC of an impacted A-SPEC that no child T-SPEC answers.
+ *
+ * @implements A-SPEC-235
+ * WHY THIS EXISTS. `coverageGaps` already forces full regression, but it asks only whether a
+ * T-SPEC DOCUMENT exists. A T-SPEC that exists and does not test the obligation its H-SPEC declared
+ * is not a gap under that definition, and measured by keyword over the corpus, 14 of the 24 H-SPECs
+ * declaring an obligation are in exactly that state.
+ *
+ * Fulfilment is judged by `unmetObligations` and nowhere else. A second judgement path drifts from
+ * the first; this repository has paid for that with `isTestFile` (two copies, and a Python file was
+ * excluded from the graph as a test AND gated as production at the same time) and with a restated
+ * section-splitting regex that returned an empty section while the check using it went green.
+ *
+ * WHAT IT DOES NOT SEE. Obligations written as prose rather than with the tag grammar — the other
+ * 105 approved documents. That is opt-in by design: introducing the rule and repairing the corpus in
+ * one slice makes it impossible to tell which half failed. Nor whether a case tagged `[perf]`
+ * exercises anything; correspondence is checked, meaning is not.
+ */
+function obligationGapsFor(specs, impactedSpecIds) {
+    if (!Array.isArray(specs) || !Array.isArray(impactedSpecIds))
+        return [];
+    const impacted = new Set(impactedSpecIds.map(stripSpecPrefix));
+    const out = [];
+    for (const a of specs) {
+        if (a?.type !== 'A-SPEC' || !impacted.has(a.id))
+            continue;
+        // A-SPEC's parent is an H-SPEC by the type table. A broken chain is ART-2's finding; reporting
+        // it here too would give one defect two names.
+        const parent = specs.find((s) => s.type === 'H-SPEC' && (a.dependsOn ?? []).includes(s.id));
+        if (!parent)
+            continue;
+        const tspecs = specs.filter((s) => s.type === 'T-SPEC' && (s.dependsOn ?? []).includes(a.id));
+        for (const o of (0, nonfunctional_1.unmetObligations)(parent.sections?.['Non-Functional'] ?? '', tspecs.map((t) => t.sections ?? {}))) {
+            out.push(`${a.id} [${o.tag}]`);
+        }
+    }
+    return [...new Set(out)].sort();
+}
 const ACCEPTANCE_SECTION_BY_TYPE = {
     'A-SPEC': 'Done When',
     'H-SPEC': 'Acceptance Criteria',
@@ -47,11 +88,14 @@ function computeReviewScope(graph, specs, changedSymbols) {
         }
     }
     coverageGaps.sort();
+    // @implements A-SPEC-235
+    const obligationGaps = obligationGapsFor(specs, impactedSpecs);
     return {
         changedSymbols: dedupedChangedSymbols,
         impactedSpecs,
         acceptanceCriteria,
         unrequestedSymbols,
         coverageGaps,
+        obligationGaps,
     };
 }

package/dist/holmes/rtm/test-scope.d.ts

@@ -35,6 +35,10 @@ export interface TestScope {
     reason: string;
     /** Changed source files that resolved into NO lane (A-SPEC-130) — nonempty forces `full`. */
     unresolvedFiles: string[];
+    /** Architecture-governing documents in the change set (A-SPEC-233) — nonempty forces `full`. */
+    architectureTouched: string[];
+    /** Declared obligations no test answers (A-SPEC-235) — nonempty forces `full`. */
+    obligationGaps: string[];
 }
 /**
  * @implements A-SPEC-130
@@ -46,7 +50,47 @@ export interface TestScopeExtras {
     changedTestFiles?: string[];
     /** Changed scannable sources no lane resolved: tier becomes `full`, reason names them. */
     unresolvedFiles?: string[];
+    /**
+     * Architecture-governing documents in the change set: tier becomes `full`, reason names them.
+     *
+     * @implements A-SPEC-233
+     * Computed by the CALLER, exactly as `coverageGaps` is. That is what keeps this function pure and
+     * therefore checkable against both synthetic fixtures and the real repository.
+     */
+    architectureTouched?: string[];
+    /**
+     * Declared non-functional obligations no child T-SPEC answers, from `obligationGapsFor`.
+     *
+     * @implements A-SPEC-235
+     * Computed by the caller, like every other signal here — that is what keeps this function pure.
+     */
+    obligationGaps?: string[];
 }
+/**
+ * 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.
+ */
+export declare function architectureGoverningFiles(changedFiles: string[]): string[];
 /**
  * @implements A-SPEC-130
  * Three-lane resolution for changed files. Impact propagation is symbol-keyed, so three classes of