peaks-loop 4.0.49 → 4.0.51

package/dist/services/audit/backing-detector.js

@@ -2,9 +2,16 @@
  * Backing detector — classifies each red line as `cli-backed`, `partial`,
  * or `prose-only`. The classifier already sets the backing for catalog hits
  * (cli-backed when an enforcer file path is present). This module exists to
- * handle the post-classification nuance: heuristics for the "partial" tier
- * (a gate exists but the LLM can bypass it) and verification that the
- * enforcer file actually exists on disk.
+ * handle the post-classification nuances: heuristics for the "partial" tier
+ * (a gate exists but the LLM can bypass it), verification that the enforcer
+ * file exists on disk, and — since A9 of the 2026-09-15 diagnosis —
+ * verification that the enforcer is actually reachable from a call site.
+ *
+ * `cli-backed` means "a CLI surface runs this rule". A file that exists but
+ * that nothing imports runs nothing, so it is `prose-only` with the same
+ * weight as an unwritten rule. Callers pass the live set from
+ * `enforcer-liveness.ts`; `null` means "liveness undecidable for this
+ * project" (no `src/` tree), in which case the existing file is trusted.
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -23,37 +30,46 @@ function detectPartial(context) {
 }
 /**
  * Re-classify a single RedLineEntry. Returns a new entry with the
- * `backing` field updated and `enforcerRef` possibly nulled if the
- * referenced file does not exist on disk.
+ * `backing` field updated; `enforcerRef` is preserved even when the
+ * backing is downgraded, because the dead reference is the triage
+ * information the report needs.
  */
-export function classifyBacking(entry, projectRoot) {
+export function classifyBacking(entry, projectRoot, liveEnforcers) {
+    const enforcerPath = entry.enforcerRef === null ? null : resolve(projectRoot, entry.enforcerRef);
+    const exists = enforcerPath !== null && existsSync(enforcerPath);
+    const dead = entry.enforcerRef !== null && exists && liveEnforcers !== null && !liveEnforcers.has(entry.enforcerRef);
     if (detectPartial(entry.source.context)) {
         return {
             entry: { ...entry, backing: 'partial' },
-            enforcerExists: entry.enforcerRef !== null && existsSync(resolve(projectRoot, entry.enforcerRef)),
+            enforcerExists: exists,
+            enforcerDead: dead,
         };
     }
     if (entry.enforcerRef === null) {
-        return { entry, enforcerExists: false };
+        return { entry, enforcerExists: false, enforcerDead: false };
     }
-    const enforcerPath = resolve(projectRoot, entry.enforcerRef);
-    const exists = existsSync(enforcerPath);
+    const backed = exists && !dead;
     return {
-        entry: { ...entry, backing: exists ? 'cli-backed' : 'prose-only' },
+        entry: { ...entry, backing: backed ? 'cli-backed' : 'prose-only' },
         enforcerExists: exists,
+        enforcerDead: dead,
     };
 }
-export function classifyBackingBatch(entries, projectRoot) {
+export function classifyBackingBatch(entries, projectRoot, liveEnforcers) {
     const updated = [];
     const warnings = [];
+    const dead = new Set();
     for (const entry of entries) {
-        const { entry: reclassified, enforcerExists } = classifyBacking(entry, projectRoot);
-        updated.push(reclassified);
-        if (reclassified.backing === 'cli-backed' && !enforcerExists) {
+        const result = classifyBacking(entry, projectRoot, liveEnforcers);
+        updated.push(result.entry);
+        if (result.enforcerDead && result.entry.enforcerRef !== null) {
+            dead.add(result.entry.enforcerRef);
+        }
+        if (result.entry.backing === 'cli-backed' && !result.enforcerExists) {
             // Defensive: should not happen because classifyBacking downgrades to
             // prose-only, but keep the assertion in case of future drift.
-            warnings.push(`enforcer ref "${reclassified.enforcerRef}" missing on disk for ${reclassified.id}`);
+            warnings.push(`enforcer ref "${result.entry.enforcerRef}" missing on disk for ${result.entry.id}`);
         }
     }
-    return { entries: updated, warnings };
+    return { entries: updated, warnings, deadEnforcers: [...dead].sort() };
 }

package/dist/services/audit/enforcer-liveness.d.ts

@@ -0,0 +1,12 @@
+export interface LiveEnforcerScan {
+    /** Refs proven imported from a call site. Empty when `unknown` is true. */
+    readonly live: ReadonlySet<string>;
+    /** True when the project has no `src/` tree, so liveness is undecidable. */
+    readonly unknown: boolean;
+    readonly warnings: readonly string[];
+}
+/**
+ * Scan `projectRoot/src` for relative imports that name one of `enforcerRefs`.
+ * Returns the subset of refs with a call site outside the enforcers directory.
+ */
+export declare function computeLiveEnforcers(projectRoot: string, enforcerRefs: readonly string[]): LiveEnforcerScan;

package/dist/services/audit/enforcer-liveness.js

@@ -0,0 +1,100 @@
+/**
+ * Enforcer liveness — A9 of `docs/diagnosis-2026-09-15-peaks-loop-state.md`.
+ *
+ * `cli-backed` used to mean "the `enforcerRef` path exists on disk"
+ * (`backing-detector.ts`). It did not mean "the enforcer runs". Ten catalog
+ * enforcerRefs name a file no module imports — `lint-rd-handoff-coverage.ts`
+ * among them — so the audit reported 108/152 red lines as CLI-enforced while
+ * a quarter of those had no caller at all.
+ *
+ * This module answers the narrower, checkable question: is the enforcer
+ * module imported by some file OUTSIDE the enforcers directory? A relative
+ * import is cheap proof that a call site exists — production code cannot
+ * invoke the module without one.
+ *
+ * Deliberate limits, stated rather than hidden:
+ *   - An import is not a call. A module can be imported and never invoked.
+ *     This check is necessary, not sufficient: it eliminates the "no caller
+ *     exists at all" class and nothing beyond it.
+ *   - Imports written inside `src/…/audit/enforcers/` do not count. A dead
+ *     enforcer that imports another dead enforcer must not resurrect it.
+ *   - A project with no `src/` tree yields `unknown: true`, never an empty
+ *     live-set: peaks-loop audits consumer projects, and "cannot tell" must
+ *     not read as "dead".
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+const SOURCE_FILE = /\.(ts|tsx|mts|cts)$/;
+const ENFORCER_DIR_FRAGMENT = '/services/audit/enforcers/';
+/** Matches `from './x.js'`, `import('./x.js')` and `export … from './x.js'`. */
+const RELATIVE_JS_IMPORT = /(?:from|import)\s*\(?\s*['"](\.\.?\/[^'"]+\.js)['"]/g;
+function toPosix(value) {
+    return value.split('\\').join('/');
+}
+function* walkSourceFiles(root, warnings) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            continue;
+        let dirents;
+        try {
+            dirents = readdirSync(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            warnings.push(`enforcer-liveness: cannot read ${toPosix(dir)} (${String(error)})`);
+            continue;
+        }
+        for (const dirent of dirents) {
+            const full = join(dir, dirent.name);
+            if (dirent.isDirectory()) {
+                if (dirent.name === 'node_modules' || dirent.name === 'dist' || dirent.name.startsWith('.'))
+                    continue;
+                stack.push(full);
+            }
+            else if (dirent.isFile() && SOURCE_FILE.test(dirent.name)) {
+                yield full;
+            }
+        }
+    }
+}
+/**
+ * Scan `projectRoot/src` for relative imports that name one of `enforcerRefs`.
+ * Returns the subset of refs with a call site outside the enforcers directory.
+ */
+export function computeLiveEnforcers(projectRoot, enforcerRefs) {
+    const srcRoot = join(projectRoot, 'src');
+    const warnings = [];
+    const live = new Set();
+    const wanted = new Set(enforcerRefs);
+    let sawAnySource = false;
+    for (const absFile of walkSourceFiles(srcRoot, warnings)) {
+        sawAnySource = true;
+        const relFile = toPosix(relative(projectRoot, absFile));
+        // An import written inside the enforcers directory proves nothing.
+        if (relFile.includes(ENFORCER_DIR_FRAGMENT))
+            continue;
+        let source;
+        try {
+            source = readFileSync(absFile, 'utf8');
+        }
+        catch (error) {
+            warnings.push(`enforcer-liveness: cannot read ${relFile} (${String(error)})`);
+            continue;
+        }
+        RELATIVE_JS_IMPORT.lastIndex = 0;
+        let match = RELATIVE_JS_IMPORT.exec(source);
+        while (match !== null) {
+            const specifier = match[1] ?? '';
+            const resolved = toPosix(relative(projectRoot, resolve(dirname(absFile), specifier)));
+            const asTs = resolved.replace(/\.js$/, '.ts');
+            if (wanted.has(asTs))
+                live.add(asTs);
+            match = RELATIVE_JS_IMPORT.exec(source);
+        }
+    }
+    if (!sawAnySource) {
+        return { live, unknown: true, warnings };
+    }
+    return { live, unknown: false, warnings };
+}

package/dist/services/audit/enforcers/lint-catalog-governance.d.ts

@@ -3,11 +3,24 @@
  *
  * Two enforcers: catalog size must grow to ≥ 40 (the P2-a target),
  * and the prose-only ratio must stay ≤ 7% (per spec §10.2 L2
- * acceptance; tightened from the pre-v2.12.1 5% target to reflect
- * the catalog governance reform — see `.peaks/memory/2026-06-27-
- * prose-only-catalog-followup.md` for the full rationale and the
- * per-entry backlog triage). Both fire on the catalog's static
- * state — no file scan, just the catalog itself.
+ * acceptance). Both fire on the state the classifier produced — no
+ * extra file scan beyond what the audit already did.
+ *
+ * C6 of the 2026-09-15 diagnosis: this gate and
+ * `prose-ratio-calculator.computeProseRatio` (behind
+ * `peaks audit prose-ratio`) are the two "prose-only ratio" gates, and
+ * they used to disagree. The calculator excluded `informational` rows
+ * from its numerator; this one excluded `informational` rows from *its*
+ * numerator by a different route (red-lines-service passed it a
+ * `proseOnlyCount` that had already been filtered). Both now measure the
+ * same quantity, identically defined:
+ *
+ *   numerator   = rows classified `backing === 'prose-only'`, all of them
+ *   denominator = every classified row (`entries.length`)
+ *
+ * They still carry different *thresholds* — 7% here, 5% as the
+ * `peaks audit prose-ratio` default — which is a policy difference, not
+ * an accounting one. Nothing redefines what is being counted.
  */
 import type { LintHit } from './lint-style.js';
 export declare const CATALOG_SIZE_TARGET = 40;
@@ -22,11 +35,10 @@ export interface CatalogProseOnlyRatio {
 }
 export declare function lintCatalogSize(actualSize: number): readonly LintHit[];
 /**
- * Prose-only ratio: count catalog entries whose `enforcerRef` is
- * null (i.e. not backed by a CLI surface) divided by the total
- * catalog size. Per spec §10.2, the L2 acceptance is ≤ 10% at
- * P2-a; v2.12.1 catalog governance tightened the gate to ≤ 7%
- * after the discovered-prose-only reform (see
- * `.peaks/memory/2026-06-27-prose-only-catalog-followup.md`).
+ * Prose-only ratio: rows the classifier tagged `prose-only`, divided by
+ * every row the classifier produced. `catalogSize` is a slight misnomer
+ * — it is `entries.length`, the count of classified rows, not the size of
+ * the hand-maintained catalog. Same numerator and denominator as
+ * `computeProseRatio`; see the module docstring above.
  */
 export declare function lintCatalogProseOnlyRatio(catalogSize: number, proseOnlyCount: number): readonly LintHit[];

package/dist/services/audit/enforcers/lint-catalog-governance.js

@@ -1,12 +1,9 @@
 export const CATALOG_SIZE_TARGET = 40;
-// v2.12.1 catalog governance: 5% was unreachable without demoting the
-// 80 discovered prose-only entries (which are advisory SKILL.md
-// phrases, not actionable red lines). After the v2.12.1 reform the
-// ratio dropped from 60.1% (89/148) to 6.1% (9/148); the remaining
-// 9 entries are the real backlog (5 unique catalog ids: prototype-
-// fidelity-001/002, mock-placement-001, resume-detection-001,
-// pre-rd-scan-001, design-draft-confirm-001). Bumping the target to
-// 7% acknowledges the reform while keeping the gate active.
+// The v2.12.1 reform left this at 7% by demoting discovered advisory
+// rows out of the numerator. S3 of the 2026-09-15 diagnosis-remediation
+// job removed that demotion, so the observed ratio is 66% (101/153) —
+// the gate now fires, which is the intended outcome: the number was
+// always this bad, it was just being reported as 0%.
 export const PROSE_ONLY_RATIO_TARGET = 0.07;
 function syntheticHit(catalogId, rule, matched) {
     // No specific file to point at — return a synthetic hit against
@@ -31,12 +28,11 @@ export function lintCatalogSize(actualSize) {
     return [syntheticHit('rl-catalog-total-001', 'Catalog governance: catalog size must grow to ≥ 40 (L2.3 P2-a target)', `(catalog size ${actualSize} < target ${CATALOG_SIZE_TARGET})`)];
 }
 /**
- * Prose-only ratio: count catalog entries whose `enforcerRef` is
- * null (i.e. not backed by a CLI surface) divided by the total
- * catalog size. Per spec §10.2, the L2 acceptance is ≤ 10% at
- * P2-a; v2.12.1 catalog governance tightened the gate to ≤ 7%
- * after the discovered-prose-only reform (see
- * `.peaks/memory/2026-06-27-prose-only-catalog-followup.md`).
+ * Prose-only ratio: rows the classifier tagged `prose-only`, divided by
+ * every row the classifier produced. `catalogSize` is a slight misnomer
+ * — it is `entries.length`, the count of classified rows, not the size of
+ * the hand-maintained catalog. Same numerator and denominator as
+ * `computeProseRatio`; see the module docstring above.
  */
 export function lintCatalogProseOnlyRatio(catalogSize, proseOnlyCount) {
     if (catalogSize === 0)

package/dist/services/audit/enforcers/lint-rd-handoff-coverage.d.ts

@@ -1,18 +1,8 @@
+import type { LintHit, SkillFile } from './lint-style.js';
 /**
- * P2-b sweep 005 — peaks-rd handoff + coverage enforcers.
- *
- * Closes three peaks-rd discovered lines:
- *  - md-121 : "do not hand off to QA without [tech-doc.md]" (BLOCKING)
- *  - md-127 : "do not hand off to QA without a perf-baseline" (BLOCKING)
- *  - md-162 : "100% coverage target on testable files is meaningful"
- *
- * Two enforcers (handoff + coverage). The handoff enforcer
- * checks for both 'tech-doc' and 'perf-baseline' handoff
- * markers; the coverage enforcer checks for the 100%-target
- * phrasing + the no-coverage-padding rule.
- *
- * scope: peaks-rd only.
+ * peaks-rd must not hand off to QA without a reviewable RD artifact. The
+ * check reads `.peaks/_runtime/<sessionId>/rd/requests/*.md`; it does not
+ * read the SKILL.md sentence that promises one.
  */
-import type { LintHit, SkillFile } from './lint-style.js';
-export declare function lintRdHandoffContract(skill: SkillFile): ReadonlyArray<LintHit>;
+export declare function lintRdHandoffContract(skill: SkillFile, projectRoot: string): ReadonlyArray<LintHit>;
 export declare function lintRdCoverageDiscipline(skill: SkillFile): ReadonlyArray<LintHit>;

package/dist/services/audit/enforcers/lint-rd-handoff-coverage.js

@@ -1,17 +1,85 @@
-const TECH_DOC_HANDOFF = /do not hand off to qa without[^\n]*tech-doc/im;
-const PERF_BASELINE_HANDOFF = /do not hand off to qa without[^\n]*perf-baseline/im;
+/**
+ * P2-b sweep 005 — peaks-rd handoff + coverage enforcers.
+ *
+ * Closes three peaks-rd discovered lines:
+ *  - md-121 : "do not hand off to QA without [the RD artifact]" (BLOCKING)
+ *  - md-127 : "do not hand off to QA without a perf-baseline" (BLOCKING)
+ *  - md-162 : "100% coverage target on testable files is meaningful"
+ *
+ * A10 of the 2026-09-15 diagnosis — `lintRdHandoffContract` used to regex
+ * the peaks-rd SKILL.md prose for the sentence *"do not hand off to QA
+ * without this file"* and call that enforcement. It never opened a file
+ * under `.peaks/_runtime/`. The gate was verifying a sentence about the
+ * artifact instead of the artifact: the exact failure the 4.0.49 release
+ * note named, found alive inside the enforcer layer.
+ *
+ * It now reads `.peaks/_runtime/<sessionId>/rd/requests/*.md` — the
+ * artifact the sentence is about (contract:
+ * `skills/bee/peaks-rd/references/artifact-per-request.md`) — and reports
+ * when nothing is there. When no session binding can be resolved it
+ * reports nothing, matching the soft-pass convention of its sibling
+ * enforcers (`pre-rd-scan.ts`, `lint-audit-regression.ts`).
+ *
+ * `lintRdCoverageDiscipline` still reads the skill doc, because its rule
+ * *is* about what the skill doc declares. It is not a handoff gate.
+ *
+ * scope: peaks-rd only.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 const COVERAGE_TARGET = /100%\s*coverage target[^\n]*testable files/i;
 const NO_PADDING = /must not write coverage-padding tests/i;
-function findHandoffContract(lines) {
-    let techDoc = false;
-    let perfBaseline = false;
-    for (const line of lines) {
-        if (TECH_DOC_HANDOFF.test(line))
-            techDoc = true;
-        if (PERF_BASELINE_HANDOFF.test(line))
-            perfBaseline = true;
+/** The artifact whose absence makes an RD→QA handoff invalid. */
+const RD_ARTIFACT_RELATIVE = '.peaks/_runtime';
+/**
+ * Resolve the bound session id from `.peaks/_runtime/session.json`. Both
+ * key spellings are accepted: the file has shipped as `peakSessionId` and
+ * as `sessionId`, and reading only one silently disables the check.
+ */
+function resolveSessionBinding(projectRoot) {
+    const sessionJsonPath = join(projectRoot, '.peaks', '_runtime', 'session.json');
+    if (!existsSync(sessionJsonPath)) {
+        return { sessionId: null, reason: 'no .peaks/_runtime/session.json' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(sessionJsonPath, 'utf8'));
+    }
+    catch (error) {
+        return { sessionId: null, reason: `session.json is not readable JSON (${String(error)})` };
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return { sessionId: null, reason: 'session.json is not an object' };
+    }
+    const record = parsed;
+    for (const key of ['sessionId', 'peakSessionId']) {
+        const value = record[key];
+        if (typeof value === 'string' && value.length > 0) {
+            return { sessionId: value, reason: `bound via session.json:${key}` };
+        }
+    }
+    return { sessionId: null, reason: 'session.json carries no session id' };
+}
+/** Count non-empty `*.md` files in `dir`. A missing dir counts as zero. */
+function countNonEmptyArtifacts(dir) {
+    let names;
+    try {
+        names = readdirSync(dir).filter((name) => name.endsWith('.md'));
+    }
+    catch {
+        return 0;
     }
-    return { techDoc, perfBaseline };
+    let count = 0;
+    for (const name of names) {
+        try {
+            if (statSync(join(dir, name)).size > 0)
+                count += 1;
+        }
+        catch {
+            continue;
+        }
+    }
+    return count;
 }
 function findCoverageContract(lines) {
     let target = false;
@@ -24,26 +92,27 @@ function findCoverageContract(lines) {
     }
     return { target, noPadding };
 }
-export function lintRdHandoffContract(skill) {
+/**
+ * peaks-rd must not hand off to QA without a reviewable RD artifact. The
+ * check reads `.peaks/_runtime/<sessionId>/rd/requests/*.md`; it does not
+ * read the SKILL.md sentence that promises one.
+ */
+export function lintRdHandoffContract(skill, projectRoot) {
     if (skill.name !== 'peaks-rd')
         return [];
-    const lines = skill.lines.length > 0
-        ? skill.lines
-        : skill.body.split(/\r?\n/);
-    const { techDoc, perfBaseline } = findHandoffContract(lines);
-    if (techDoc && perfBaseline)
+    const binding = resolveSessionBinding(projectRoot);
+    if (binding.sessionId === null)
+        return [];
+    const requestsDir = join(projectRoot, RD_ARTIFACT_RELATIVE, binding.sessionId, 'rd', 'requests');
+    const artifactCount = countNonEmptyArtifacts(requestsDir);
+    if (artifactCount > 0)
         return [];
-    const missing = [];
-    if (!techDoc)
-        missing.push('tech-doc handoff BLOCKING');
-    if (!perfBaseline)
-        missing.push('perf-baseline handoff BLOCKING');
     return [{
             catalogId: 'rl-rd-handoff-contract-001',
-            rule: 'peaks-rd SKILL.md must declare the QA-handoff BLOCKING contract (tech-doc + perf-baseline)',
-            file: skill.path,
+            rule: 'peaks-rd must not hand off to QA without a non-empty RD artifact under rd/requests/',
+            file: requestsDir,
             line: 1,
-            matchedText: `missing markers: ${missing.join(', ')}`
+            matchedText: `no non-empty .md artifact under ${requestsDir} (${binding.reason})`,
         }];
 }
 export function lintRdCoverageDiscipline(skill) {

package/dist/services/audit/enforcers/lint-style.d.ts

@@ -14,7 +14,15 @@ export interface SkillFile {
 export declare function readSkillFiles(skillsRoot: string, names: readonly string[]): readonly SkillFile[];
 /** Theme A — section structure. Returns lint hits (positive = rule
  *  satisfied, so a missing heading fires the lint hit; downstream
- *  audit service decides whether to WARN or pass). */
+ *  audit service decides whether to WARN or pass).
+ *
+ *  A11 of the 2026-09-15 diagnosis: the `Hard contracts` rule used to
+ *  match the *heading text* and stop there. `peaks-perf-audit/SKILL.md`
+ *  carries `## Hard contracts (BLOCKING)` — the word BLOCKING is in the
+ *  heading — while every bullet beneath it is unmarked prose, so the
+ *  audit counted a BLOCKING red line with no contract behind it. The
+ *  rule now also requires at least one marker line inside the section
+ *  body, which is what makes a contract visible to the classifier. */
 export declare function lintSectionShape(skill: SkillFile): readonly LintHit[];
 /**
  * ASCII wireframe section-order check (spec §5.4 line 647).

package/dist/services/audit/enforcers/lint-style.js

@@ -45,13 +45,36 @@ function matchedText(lines, line) {
         return '';
     return (lines[line - 1] ?? '').trim();
 }
+/** A red-line marker that makes a contract line machine-visible. */
+const CONTRACT_MARKER = /\b(MANDATORY|BLOCKING|MUST NOT|RED LINE)\b/;
+/**
+ * Collect the body of the section that starts at `headingLine` (1-based):
+ * every line up to the next `## ` heading.
+ */
+function sectionBody(lines, headingLine) {
+    const body = [];
+    for (let i = headingLine; i < lines.length; i += 1) {
+        if (/^##\s/.test(lines[i] ?? ''))
+            break;
+        body.push(lines[i] ?? '');
+    }
+    return body;
+}
 /** Theme A — section structure. Returns lint hits (positive = rule
  *  satisfied, so a missing heading fires the lint hit; downstream
- *  audit service decides whether to WARN or pass). */
+ *  audit service decides whether to WARN or pass).
+ *
+ *  A11 of the 2026-09-15 diagnosis: the `Hard contracts` rule used to
+ *  match the *heading text* and stop there. `peaks-perf-audit/SKILL.md`
+ *  carries `## Hard contracts (BLOCKING)` — the word BLOCKING is in the
+ *  heading — while every bullet beneath it is unmarked prose, so the
+ *  audit counted a BLOCKING red line with no contract behind it. The
+ *  rule now also requires at least one marker line inside the section
+ *  body, which is what makes a contract visible to the classifier. */
 export function lintSectionShape(skill) {
     const hits = [];
     const rules = [
-        { id: 'rl-section-hard-contracts-001', rule: 'Hard contracts for browser/IO surface', pattern: SECTION_HARD_CONTRACTS_HEADING },
+        { id: 'rl-section-hard-contracts-001', rule: 'Hard contracts for browser/IO surface', pattern: SECTION_HARD_CONTRACTS_HEADING, requiresBodyMarker: true },
         { id: 'rl-section-mandatory-artifact-001', rule: 'Mandatory per-request artifact', pattern: SECTION_MANDATORY_HEADING },
         { id: 'rl-section-default-runbook-001', rule: 'Default runbook pointer', pattern: SECTION_DEFAULT_RUNBOOK_HEADING },
         { id: 'rl-section-gate-index-001', rule: 'Gate index', pattern: SECTION_GATE_INDEX_HEADING },
@@ -67,6 +90,19 @@ export function lintSectionShape(skill) {
                 line: 1,
                 matchedText: '(missing section)'
             });
+            continue;
+        }
+        if (r.requiresBodyMarker === true) {
+            const declared = sectionBody(skill.lines, line).some((l) => CONTRACT_MARKER.test(l));
+            if (!declared) {
+                hits.push({
+                    catalogId: r.id,
+                    rule: r.rule,
+                    file: skill.path,
+                    line,
+                    matchedText: `(heading at line ${line} but no BLOCKING/MANDATORY/MUST NOT/RED LINE line inside the section)`
+                });
+            }
         }
     }
     return hits;

package/dist/services/audit/prose-ratio-calculator.d.ts

@@ -1,33 +1,44 @@
 /**
- * Prose-only ratio calculator — Slice C Group G3 (v2.14.0).
+ * Prose-only ratio calculator — Slice C Group G3 (v2.14.0),
+ * corrected in S3 of the 2026-09-15 diagnosis-remediation job.
  *
- * Computes the prose-only ratio for a set of red-line entries. Per
- * spec §10.2 + the v2.12.1 reform (`.peaks/memory/2026-06-27-
- * prose-only-catalog-followup.md`), an entry counts as prose-only
- * only when BOTH:
- *   1. `backing === 'prose-only'`
- *   2. `informational !== true`
+ * An entry counts as prose-only when `backing === 'prose-only'`.
+ * Full stop. There is no second condition.
  *
- * The 80 discovered advisory SKILL.md phrases (auto-marked
- * `informational=true` by `classifier.ts:141`) are excluded from
- * the ratio so the gate (≤ 5% per slice C AC A3.1) reflects the
- * actionable backlog.
+ * The pre-S3 version also required `informational !== true`, on the
+ * reasoning that auto-discovered advisory SKILL.md phrases are "not
+ * actionable red lines". Whatever the merits of that reading, the effect
+ * was to move 44 of 152 rows — 29% of the catalog — out of the
+ * denominator, so the gate reported `proseOnly: 0` while the same JSON
+ * carried 44 rows with `"backing": "prose-only"`. A metric whose
+ * denominator can be redefined by the code it measures is not a metric.
  *
- * Karpathy §2 simplicity: one exported function plus a thin
- * calculator interface; no I/O. The pure form makes the ≥8
- * test cases in prose-ratio-calculator.test.ts trivial.
+ * `informational` survives as a triage label — `discoveredProseOnly`
+ * below counts those rows — but it no longer moves any number that the
+ * ratio is computed from. Expect the ratio to look much worse than it
+ * did; that is this correction working.
+ *
+ * Karpathy §2 simplicity: one exported function plus a thin calculator
+ * interface; no I/O.
  */
 import type { RedLineEntry } from './types.js';
 export interface ProseRatioResult {
-    /** Total catalog size (entries.length). */
+    /** Total entries considered (entries.length) — the denominator, always. */
     readonly totalRedLines: number;
     /** Count of entries with backing === 'cli-backed'. */
     readonly cliBacked: number;
     /** Count of entries with backing === 'partial'. */
     readonly partial: number;
-    /** Count of entries with backing === 'prose-only' AND informational !== true. */
+    /** Count of entries with backing === 'prose-only'. THE numerator. */
     readonly proseOnly: number;
-    /** Count of entries with informational === true (excluded from ratio). */
+    /**
+     * Breakdown only — the subset of `proseOnly` that carries
+     * `informational: true` (auto-discovered advisory phrases with no
+     * catalog template). Included in `proseOnly`; changing it changes
+     * nothing about `proseOnly` or `ratio`.
+     */
+    readonly discoveredProseOnly: number;
+    /** Count of entries with informational === true, whatever their backing. */
     readonly informational: number;
     /** proseOnly / totalRedLines. Returns 0 when totalRedLines === 0. */
     readonly ratio: number;