@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/spec/acceptance-quality.d.ts

@@ -0,0 +1,81 @@
+import { Spec } from './spec-parser';
+/**
+ * Whether a requirement states what "satisfied" means.
+ *
+ * The validator checks that a Success Criteria section EXISTS; it never asked whether the section
+ * says anything checkable. Measured 2026-08-28 over this repository's 218 requirements: 29 have no
+ * section at all and 29 carry a single scaffold sentence, so **58 (27%) cannot answer "did we
+ * satisfy this?"** — and the scaffold sentence is what `spec_slice_init` itself writes, so the tool
+ * has been manufacturing unanswerable criteria and saying nothing about it.
+ *
+ * This module DETECTS. It does not repair specs and does not tighten approval: making the validator
+ * reject these would invalidate already-approved work, which is a governance decision and not a
+ * detector's to take.
+ */
+export type AcceptanceQuality = 'absent' | 'boilerplate' | 'stated';
+/**
+ * Phrases that look like a criterion and commit to nothing.
+ *
+ * Deliberately short and evidence-based: measured across the corpus, exactly ONE single-item
+ * boilerplate exists. Speculative additions would be patterns nobody has written, and a pattern that
+ * has never matched cannot be shown to work.
+ */
+export declare const ACCEPTANCE_BOILERPLATE: readonly RegExp[];
+export declare function acceptanceQuality(spec: Spec): AcceptanceQuality;
+/** Requirements whose criteria cannot be checked, in corpus order, with the reason. */
+export declare function unactionableRequirements(specs: readonly Spec[]): Array<{
+    req: string;
+    quality: Exclude<AcceptanceQuality, 'stated'>;
+}>;
+/** The four quadrants a T-SPEC's `coverage` frontmatter makes a claim about. */
+export declare const QUADRANTS: readonly ["normal", "corner", "negative", "boundary"];
+export type Quadrant = typeof QUADRANTS[number];
+/**
+ * What a quadrant actually contains.
+ *
+ * `absent` and `scaffold` are different facts and are kept apart: nothing written, versus a template
+ * left untouched while the frontmatter declares the quadrant covered. The second is worse — it
+ * passes structural validation and makes a positive claim.
+ */
+export declare function quadrantQuality(spec: Spec, quadrant: Quadrant): 'stated' | 'scaffold' | 'absent';
+/**
+ * Quadrants a T-SPEC declares covered without substantiating them. Not claiming coverage is not the
+ * same as claiming it falsely, so a `false` in the frontmatter is never reported here.
+ */
+export declare function unsubstantiatedCoverage(specs: readonly Spec[]): Array<{
+    spec: string;
+    quadrant: Quadrant;
+}>;
+/**
+ * What an H-SPEC's `## Non-Functional` actually contains — the third judgement of this shape, beside
+ * `acceptanceQuality` and `quadrantQuality`, and in the same file so the fourth has an obvious home.
+ */
+export declare function nonFunctionalQuality(spec: Spec): 'stated' | 'scaffold' | 'absent';
+/** H-SPECs whose non-functional section says nothing, with which of the two ways it says nothing. */
+export declare function unstatedNonFunctional(specs: readonly Spec[]): Array<{
+    spec: string;
+    quality: 'scaffold' | 'absent';
+}>;
+export interface SpecQualityReport {
+    /** REQs whose success criteria cannot be checked (A-SPEC-295). */
+    unactionableRequirements: ReturnType<typeof unactionableRequirements>;
+    /** T-SPEC quadrants declared covered and left as scaffold (A-SPEC-321). */
+    unsubstantiatedCoverage: ReturnType<typeof unsubstantiatedCoverage>;
+    /** H-SPECs whose non-functional section says nothing (A-SPEC-324). */
+    unstatedNonFunctional: ReturnType<typeof unstatedNonFunctional>;
+    /** How many findings in total. A COUNT, not a score — see below. */
+    total: number;
+}
+/**
+ * The three spec-quality judgements, together.
+ *
+ * Each was built and measured on its own, and nothing looked at all three — the same shape
+ * A-SPEC-312 found on the file axis, where six tuning verdicts had been reached against half the
+ * picture. This adds no judgement of its own; a fourth implementation would be a fourth truth.
+ *
+ * There is deliberately NO aggregate score. The three findings ask for three different actions —
+ * rewrite a criterion, write a test case, state an obligation — and one number would say none of
+ * them. `total` reports SCALE; the three lists report what to do. Four times in this work an
+ * undecomposed number sent the reasoning somewhere wrong before someone looked at the parts.
+ */
+export declare function specQualityReport(specs: readonly Spec[]): SpecQualityReport;

package/dist/holmes/spec/acceptance-quality.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUADRANTS = exports.ACCEPTANCE_BOILERPLATE = void 0;
+exports.acceptanceQuality = acceptanceQuality;
+exports.unactionableRequirements = unactionableRequirements;
+exports.quadrantQuality = quadrantQuality;
+exports.unsubstantiatedCoverage = unsubstantiatedCoverage;
+exports.nonFunctionalQuality = nonFunctionalQuality;
+exports.unstatedNonFunctional = unstatedNonFunctional;
+exports.specQualityReport = specQualityReport;
+/**
+ * Phrases that look like a criterion and commit to nothing.
+ *
+ * Deliberately short and evidence-based: measured across the corpus, exactly ONE single-item
+ * boilerplate exists. Speculative additions would be patterns nobody has written, and a pattern that
+ * has never matched cannot be shown to work.
+ */
+exports.ACCEPTANCE_BOILERPLATE = [
+    /^implementation completed and verified by tests\.?$/i,
+];
+function criteriaItems(spec) {
+    const body = spec.sections?.['Success Criteria'];
+    if (typeof body !== 'string')
+        return [];
+    return body.split('\n').map((line) => line.replace(/^\s*[-*]\s*/, '').trim()).filter(Boolean);
+}
+function acceptanceQuality(spec) {
+    const items = criteriaItems(spec);
+    if (items.length === 0)
+        return 'absent';
+    // One real criterion is enough: a scaffold line sitting next to a measurable one is noise, not a
+    // defect. Only a section that is ENTIRELY boilerplate says nothing.
+    const anyReal = items.some((item) => !exports.ACCEPTANCE_BOILERPLATE.some((p) => p.test(item)));
+    return anyReal ? 'stated' : 'boilerplate';
+}
+/** Requirements whose criteria cannot be checked, in corpus order, with the reason. */
+function unactionableRequirements(specs) {
+    return specs
+        .filter((spec) => spec.type === 'REQ')
+        .map((spec) => ({ req: spec.id, quality: acceptanceQuality(spec) }))
+        .filter((row) => row.quality !== 'stated');
+}
+// @implements A-SPEC-321
+/** The four quadrants a T-SPEC's `coverage` frontmatter makes a claim about. */
+exports.QUADRANTS = ['normal', 'corner', 'negative', 'boundary'];
+const QUADRANT_SECTION = {
+    normal: 'Normal Cases',
+    corner: 'Corner Cases',
+    negative: 'Negative Cases',
+    boundary: 'Boundary Cases',
+};
+/**
+ * The scaffold `spec_slice_init` writes. Evidence-based, exactly like ACCEPTANCE_BOILERPLATE above:
+ * these are the lines actually present in this corpus, not a guess at what filler might look like.
+ * Measured 2026-08-28 — 31 of 230 T-SPECs are approved, declare all four quadrants covered, and
+ * contain nothing but these.
+ */
+const QUADRANT_SCAFFOLD = [
+    /^\s*-?\s*Given valid inputs\s*$/i,
+    /^\s*-?\s*Given edge cases\s*$/i,
+    /^\s*-?\s*Given invalid inputs\s*$/i,
+    /^\s*-?\s*Given boundary conditions\s*$/i,
+    /^\s*When operation is performed\s*$/i,
+    /^\s*Then correct behavior is observed\s*$/i,
+    /^\s*Then system handles gracefully\s*$/i,
+    /^\s*Then appropriate error is returned\s*$/i,
+    /^\s*Then boundary limits are respected\s*$/i,
+];
+/**
+ * What a quadrant actually contains.
+ *
+ * `absent` and `scaffold` are different facts and are kept apart: nothing written, versus a template
+ * left untouched while the frontmatter declares the quadrant covered. The second is worse — it
+ * passes structural validation and makes a positive claim.
+ */
+function quadrantQuality(spec, quadrant) {
+    const body = spec.sections?.[QUADRANT_SECTION[quadrant]] ?? '';
+    const lines = body.split('\n').map((line) => line.trim()).filter((line) => line !== '');
+    if (lines.length === 0)
+        return 'absent';
+    // One real line is enough, exactly as one real acceptance criterion is enough above.
+    const substantive = lines.some((line) => !QUADRANT_SCAFFOLD.some((pattern) => pattern.test(line)));
+    return substantive ? 'stated' : 'scaffold';
+}
+/**
+ * Quadrants a T-SPEC declares covered without substantiating them. Not claiming coverage is not the
+ * same as claiming it falsely, so a `false` in the frontmatter is never reported here.
+ */
+function unsubstantiatedCoverage(specs) {
+    const out = [];
+    for (const spec of specs) {
+        if (spec.type !== 'T-SPEC')
+            continue;
+        const coverage = spec.frontmatter?.coverage;
+        if (!coverage)
+            continue;
+        for (const quadrant of exports.QUADRANTS) {
+            if (coverage[quadrant] !== true)
+                continue;
+            if (quadrantQuality(spec, quadrant) !== 'stated')
+                out.push({ spec: spec.id, quadrant });
+        }
+    }
+    return out;
+}
+// @implements A-SPEC-324
+/**
+ * The scaffold `spec_slice_init` writes into `## Non-Functional`. Kept deliberately SHORT.
+ *
+ * This list is the whole protection for prose. Measured 2026-08-28: 180 of 187 approved H-SPECs
+ * produce no parseable tagged obligation, and it would be easy to read that as a defect — but
+ * `nonfunctional.ts` states in its own documentation that untagged prose is out of scope on purpose,
+ * because "those are human judgements, and simulating them would recreate the documented-but-
+ * unenforced state this slice exists to remove". Widening these patterns would erase that judgement
+ * and call a person's sentence filler. 31 of the 180 carry this exact generated line; those are the
+ * ones nobody wrote.
+ */
+const NONFUNCTIONAL_SCAFFOLD = [
+    /^Performance and stability maintained\.?$/i,
+];
+/**
+ * What an H-SPEC's `## Non-Functional` actually contains — the third judgement of this shape, beside
+ * `acceptanceQuality` and `quadrantQuality`, and in the same file so the fourth has an obvious home.
+ */
+function nonFunctionalQuality(spec) {
+    const body = spec.sections?.['Non-Functional'] ?? '';
+    const lines = body.split('\n')
+        .map((line) => line.trim().replace(/^[-*]\s*/, '').trim())
+        .filter((line) => line !== '');
+    if (lines.length === 0)
+        return 'absent';
+    const substantive = lines.some((line) => !NONFUNCTIONAL_SCAFFOLD.some((pattern) => pattern.test(line)));
+    return substantive ? 'stated' : 'scaffold';
+}
+/** H-SPECs whose non-functional section says nothing, with which of the two ways it says nothing. */
+function unstatedNonFunctional(specs) {
+    const out = [];
+    for (const spec of specs) {
+        if (spec.type !== 'H-SPEC')
+            continue;
+        const quality = nonFunctionalQuality(spec);
+        if (quality !== 'stated')
+            out.push({ spec: spec.id, quality });
+    }
+    return out;
+}
+/**
+ * The three spec-quality judgements, together.
+ *
+ * Each was built and measured on its own, and nothing looked at all three — the same shape
+ * A-SPEC-312 found on the file axis, where six tuning verdicts had been reached against half the
+ * picture. This adds no judgement of its own; a fourth implementation would be a fourth truth.
+ *
+ * There is deliberately NO aggregate score. The three findings ask for three different actions —
+ * rewrite a criterion, write a test case, state an obligation — and one number would say none of
+ * them. `total` reports SCALE; the three lists report what to do. Four times in this work an
+ * undecomposed number sent the reasoning somewhere wrong before someone looked at the parts.
+ */
+function specQualityReport(specs) {
+    const requirements = unactionableRequirements(specs);
+    const coverage = unsubstantiatedCoverage(specs);
+    const nonFunctional = unstatedNonFunctional(specs);
+    return {
+        unactionableRequirements: requirements,
+        unsubstantiatedCoverage: coverage,
+        unstatedNonFunctional: nonFunctional,
+        total: requirements.length + coverage.length + nonFunctional.length,
+    };
+}

package/dist/holmes/spec/validator.js

@@ -9,6 +9,7 @@ const node_crypto_1 = require("node:crypto");
 const spec_types_1 = require("./spec-types");
 const spec_digest_1 = require("./spec-digest");
 const legacy_format_1 = require("./legacy-format");
+const acceptance_quality_1 = require("./acceptance-quality");
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
 /**
  * The canonical `rev` value for a citation: a content digest of the source as it was read.
@@ -272,8 +273,39 @@ function validateSpec(spec, resolve) {
             // between them (review F5 — the old unordered `given && when && then` passed bare keyword prose
             // like "given when then"). A trailing given/when clause still needs its consequent `then`.
             const hasGwt = /\bgiven\b.{2,}?\bwhen\b.{2,}?\bthen\b/is.test(section);
-            if (!hasGwt)
+            if (!hasGwt) {
                 err('empty-quadrant', `coverage.${q}=true but '## ${q[0].toUpperCase()}${q.slice(1)} Cases' has no Given/When/Then scenario`);
+                continue;
+            }
+            // @implements A-SPEC-322
+            // The check above is STRUCTURAL, and the scaffold `spec_slice_init` writes has the structure:
+            // "Given valid inputs / When operation is performed / Then correct behavior is observed" is a
+            // Given/When/Then scenario and says nothing. Measured 2026-08-28: 31 of 230 T-SPECs were
+            // approved carrying nothing but that template while declaring all four quadrants covered.
+            //
+            // A DIFFERENT code from `empty-quadrant` on purpose — "you wrote nothing" and "you left the
+            // template" ask the author for different things.
+            //
+            // Not retroactive: validation runs on an approval ATTEMPT, and nothing re-validates a sealed
+            // document, so the existing 31 stay valid. New ones cannot join them.
+            if ((0, acceptance_quality_1.quadrantQuality)(spec, q) === 'scaffold') {
+                // A WARNING, not an error, and the downgrade is itself a measured decision. As an error it
+                // broke two things at once:
+                //   - `constitution.ts` validates the WHOLE corpus, so the 31 already-approved scaffolds
+                //     became violations and the A-SPEC-146 guard ("the enforcement must not brick the
+                //     harness") fired — the premise that sealed documents are never re-validated was wrong;
+                //   - T-SPEC-203 pins `spec_slice_init` -> `spec_slice_approve` as a working sequence, and
+                //     a scaffold error makes that sequence impossible without editing the T-SPEC first.
+                //
+                // The second is a genuine conflict between two approved specs, not a bug to route around, so
+                // it is reported rather than decided here. A warning still travels with every approval
+                // result, which is what turns "31 silently" into "31 and you were told".
+                f.push({
+                    level: 'warn',
+                    code: 'scaffold-quadrant',
+                    message: `coverage.${q}=true but '## ${q[0].toUpperCase()}${q.slice(1)} Cases' still holds the generated scaffold — replace it with a real case`,
+                });
+            }
         }
     }
     return { ok: f.filter((x) => x.level === 'error').length === 0, findings: f };

package/dist/holmes/spec/yaml-scalar.d.ts

@@ -0,0 +1 @@
+export declare function yamlScalar(value: string, indent?: number): string;

package/dist/holmes/spec/yaml-scalar.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.yamlScalar = yamlScalar;
+// @implements A-SPEC-298
+/**
+ * Render a string so it can be pasted into YAML frontmatter and read back unchanged.
+ *
+ * This exists because `spec_slice_init` interpolated user text straight into frontmatter. A title or
+ * objective containing `": "` — unremarkable in ordinary prose — produced a document the spec store
+ * could not parse, so the freshly created requirement vanished from the store entirely.
+ *
+ * The safe set is an ALLOW-list. Enumerating dangerous characters means the one you forget is the
+ * next defect; requiring a value to prove it is boring is the direction that fails safe. An
+ * adversarial probe of the first version of this file found four holes it had missed, which is why
+ * that probe now lives beside it as a test.
+ */
+const PLAIN_SAFE = /^[A-Za-z0-9가-힣][A-Za-z0-9가-힣 _().,\/-]*$/u;
+/**
+ * Values YAML would read as something other than a string. `123` comes back as a number and `null`
+ * as null, so a title of "123" would reach callers as a number and break the first `.startsWith`
+ * it met. Type coercion is a silent corruption, not a parse error, which makes it worse.
+ */
+const YAML_TYPED = /^(?:[-+]?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?|0[xob][0-9a-fA-F]+|true|false|yes|no|on|off|null|~|)$/i;
+function yamlScalar(value, indent = 0) {
+    // A carriage return or other control character is normalised away by plain and single-quoted
+    // scalars — the value would come back CHANGED rather than failing. Only a double-quoted scalar
+    // preserves it, and JSON's escaping is a valid YAML double-quoted scalar.
+    if (/[\u0000-\u0008\u000B-\u001F\u007F\r]/.test(value))
+        return JSON.stringify(value);
+    if (value.includes('\n')) {
+        // A block scalar keeps the line breaks readable in the file instead of turning them into \n.
+        // A line with trailing whitespace cannot survive one, so those fall through to double quotes.
+        if (value.split('\n').some((line) => line !== line.replace(/\s+$/, '')))
+            return JSON.stringify(value);
+        const pad = ' '.repeat(indent + 2);
+        return `|-\n${value.split('\n').map((line) => `${pad}${line}`).join('\n')}`;
+    }
+    if (value !== '' && value === value.trim() && PLAIN_SAFE.test(value)
+        && !value.includes(': ') && !YAML_TYPED.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, "''")}'`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",