@encore-os/eos-spec 0.3.1

package/dist/lib/frontmatter.d.ts

@@ -0,0 +1,112 @@
+import type { AcEntry } from './ac-response-parser.js';
+export type { AcEntry } from './ac-response-parser.js';
+/** Raw frontmatter shape — only the fields the pipeline navigator cares about. */
+export type SpecFrontmatter = {
+    id?: string;
+    core?: string;
+    /** Human-readable spec title — preferred over the body `# …` heading when present. */
+    title?: string;
+    status?: string;
+    /** The id of the spec that supersedes this one. Present ⇒ terminal (C2/C3). */
+    superseded_by?: string;
+    pipeline_status?: string;
+    research_appendix?: string;
+    acceptance_criteria?: unknown[];
+    user_stories?: unknown[];
+    /** Typed functional requirements (FR-*) — consumed by `verify-acs` alongside AC/US. */
+    requirements?: unknown[];
+    e2e_tests?: unknown[];
+    /** Globs/paths the spec expects to touch — used to detect UI-bearing specs. */
+    affected_files?: unknown[];
+    tags?: unknown[];
+    /** Canonical machine-readable cross-spec blockers (list of spec IDs). May be null/dirty. */
+    blocked_by?: unknown;
+    /** Human-authored "builds on / related" list — historically dirty (prose + emoji). */
+    dependencies?: unknown;
+};
+/**
+ * Surgically set `pipeline_status` inside the leading frontmatter block without
+ * reformatting the rest of the YAML. Replaces the existing line, or appends one.
+ * Returns the text unchanged when there is no frontmatter block.
+ */
+export declare function setPipelineStatus(text: string, status: string): string;
+/**
+ * Idempotently set `artifacts.tasks: <rel>` inside the leading frontmatter block.
+ * Replaces an existing `tasks:` child under `artifacts:`, inserts one under an
+ * existing `artifacts:` block, or appends a fresh `artifacts:` block. Returns the
+ * text unchanged when already correct or when there is no frontmatter block.
+ *
+ * Closes the `pipeline/missing-tasks-artifact` validator gap: `reconcile`
+ * materializes `pipeline_status: tasks_generated` from the on-disk TASKS file, so
+ * it must also record `artifacts.tasks` (which the pipeline-status validator
+ * requires) rather than leaving it to be hand-added.
+ */
+export declare function setTasksArtifact(text: string, rel: string): string;
+/**
+ * Decide which relative path `reconcile` should write into `artifacts.tasks`, or
+ * `null` to mean "leave the frontmatter untouched".
+ *
+ * Non-destructive of valid pointers: many real specs use a non-canonical TASKS
+ * filename (e.g. `HR-02-credentialing-compliance-TASKS.md`,
+ * `<id>-PHASE-2-3-TASKS.md`). The earlier behavior unconditionally normalized
+ * `artifacts.tasks` to the canonical `<id>-TASKS.md` guess, rewriting a VALID
+ * pointer to a NON-EXISTENT path and tripping `pipeline/missing-tasks-artifact`.
+ *
+ * Rules (`fileExists(rel)` resolves a repo-relative path against repoRoot):
+ * - No frontmatter block → `null` (nothing to do).
+ * - Existing pointer whose target EXISTS → `null` (preserve — canonical or not).
+ * - Pointer ABSENT and the canonical file EXISTS → return the canonical path.
+ * - Pointer STALE (target missing) and the canonical file EXISTS → return the
+ *   canonical path (heal the dangling pointer).
+ * - Otherwise (no pointer + no canonical file, or stale pointer + no canonical
+ *   file) → `null`; the gate, not reconcile, surfaces the genuine gap.
+ */
+export declare function resolveTasksArtifact(text: string, canonicalRel: string, fileExists: (rel: string) => boolean): string | null;
+/** Kinds of artifact-derived sign-off markers the navigator detects.
+ *  `compliance` is file-based (a `{ID}-COMPLIANCE-SIGNOFF.md`), not a body comment. */
+export type SignoffType = 'validated' | 'spec-reviewed' | 'ux-reviewed' | 'heal-verified' | 'docshots' | 'ui-gate-waived' | 'submit-e2e-waived' | 'compliance';
+/**
+ * Insert an HTML-comment sign-off marker (e.g. `<!-- validated: 2026-05-28 -->`)
+ * immediately after the spec's frontmatter block, or at the start of the file when
+ * none exists. Idempotent: when a marker of the same type already exists, returns
+ * the text unchanged and `inserted: false`.
+ */
+export declare function insertSignoffMarker(text: string, type: SignoffType, date: string): {
+    text: string;
+    inserted: boolean;
+};
+/**
+ * Parse the leading YAML frontmatter block of a spec markdown string.
+ * Returns `{}` when absent or malformed — never throws.
+ */
+export declare function readFrontmatter(text: string): SpecFrontmatter;
+/**
+ * Remove the leading YAML frontmatter block (when present) so body-only regexes
+ * (the `# Title` heading, `**Status:**` prose) cannot match lines inside the
+ * frontmatter — a YAML comment like `# Replace placeholder values when
+ * authoring.` (SPEC_TEMPLATE.md line 2) is indistinguishable from an H1 by
+ * line shape alone.
+ */
+export declare function stripFrontmatter(text: string): string;
+/**
+ * Append AC entries to the frontmatter's `acceptance_criteria:` array. Preserves
+ * other frontmatter via a slice → re-serialize-only-the-AC-list strategy. Returns
+ * the input unchanged when there is no frontmatter block.
+ */
+export declare function appendAcceptanceCriteria(text: string, entries: AcEntry[]): string;
+/**
+ * Within the leading frontmatter block, flip the `status:` of one list item
+ * (under `acceptance_criteria:` / `user_stories:` / `requirements:`) identified
+ * by its `- id: <id>` line. Line-scoped so all other lines — comments, ordering,
+ * sibling items — are preserved byte-for-byte. Returns the text unchanged when
+ * there is no frontmatter, the section/id is absent, or the status already matches.
+ * Used by `verify-acs` to auto-promote planned -> verified on a real test pass.
+ */
+export declare function setRequirementStatus(text: string, section: 'acceptance_criteria' | 'user_stories' | 'requirements', id: string, status: 'planned' | 'verified'): string;
+/**
+ * Idempotently add `rel` to the `e2e_tests:` list inside the leading frontmatter block.
+ * Appends a fresh `e2e_tests:` block when absent. Returns the text unchanged when
+ * the path is already listed or there is no frontmatter block. Used by `gen-tests
+ * --update-frontmatter`.
+ */
+export declare function setE2eTests(text: string, rel: string): string;

package/dist/lib/frontmatter.js

@@ -0,0 +1,261 @@
+import { parse, stringify as yamlStringify } from 'yaml';
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+/**
+ * Surgically set `pipeline_status` inside the leading frontmatter block without
+ * reformatting the rest of the YAML. Replaces the existing line, or appends one.
+ * Returns the text unchanged when there is no frontmatter block.
+ */
+export function setPipelineStatus(text, status) {
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match)
+        return text;
+    const block = match[1];
+    const line = `pipeline_status: ${status}`;
+    const newBlock = /^pipeline_status:.*$/m.test(block)
+        ? block.replace(/^pipeline_status:.*$/m, line)
+        : `${block}\n${line}`;
+    // function replacer avoids `$` in newBlock being treated as a backreference
+    return text.replace(FRONTMATTER_RE, () => `---\n${newBlock}\n---`);
+}
+/**
+ * Idempotently set `artifacts.tasks: <rel>` inside the leading frontmatter block.
+ * Replaces an existing `tasks:` child under `artifacts:`, inserts one under an
+ * existing `artifacts:` block, or appends a fresh `artifacts:` block. Returns the
+ * text unchanged when already correct or when there is no frontmatter block.
+ *
+ * Closes the `pipeline/missing-tasks-artifact` validator gap: `reconcile`
+ * materializes `pipeline_status: tasks_generated` from the on-disk TASKS file, so
+ * it must also record `artifacts.tasks` (which the pipeline-status validator
+ * requires) rather than leaving it to be hand-added.
+ */
+export function setTasksArtifact(text, rel) {
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match)
+        return text;
+    const block = match[1];
+    const lines = block.split('\n');
+    const artIdx = lines.findIndex((l) => /^artifacts:\s*$/.test(l));
+    let newLines;
+    if (artIdx === -1) {
+        newLines = [...lines, 'artifacts:', `  tasks: ${rel}`];
+    }
+    else {
+        // Span of contiguous indented children directly under `artifacts:`.
+        let end = artIdx + 1;
+        while (end < lines.length && /^[ \t]+\S/.test(lines[end]))
+            end++;
+        const indent = lines[artIdx + 1]?.match(/^([ \t]+)/)?.[1] ?? '  ';
+        const childOffset = lines.slice(artIdx + 1, end).findIndex((l) => /^[ \t]+tasks:/.test(l));
+        if (childOffset === -1) {
+            newLines = [...lines.slice(0, artIdx + 1), `${indent}tasks: ${rel}`, ...lines.slice(artIdx + 1)];
+        }
+        else {
+            const absIdx = artIdx + 1 + childOffset;
+            const curIndent = lines[absIdx].match(/^([ \t]+)/)?.[1] ?? indent;
+            newLines = [...lines];
+            newLines[absIdx] = `${curIndent}tasks: ${rel}`;
+        }
+    }
+    const newBlock = newLines.join('\n');
+    if (newBlock === block)
+        return text;
+    return text.replace(FRONTMATTER_RE, () => `---\n${newBlock}\n---`);
+}
+/**
+ * Decide which relative path `reconcile` should write into `artifacts.tasks`, or
+ * `null` to mean "leave the frontmatter untouched".
+ *
+ * Non-destructive of valid pointers: many real specs use a non-canonical TASKS
+ * filename (e.g. `HR-02-credentialing-compliance-TASKS.md`,
+ * `<id>-PHASE-2-3-TASKS.md`). The earlier behavior unconditionally normalized
+ * `artifacts.tasks` to the canonical `<id>-TASKS.md` guess, rewriting a VALID
+ * pointer to a NON-EXISTENT path and tripping `pipeline/missing-tasks-artifact`.
+ *
+ * Rules (`fileExists(rel)` resolves a repo-relative path against repoRoot):
+ * - No frontmatter block → `null` (nothing to do).
+ * - Existing pointer whose target EXISTS → `null` (preserve — canonical or not).
+ * - Pointer ABSENT and the canonical file EXISTS → return the canonical path.
+ * - Pointer STALE (target missing) and the canonical file EXISTS → return the
+ *   canonical path (heal the dangling pointer).
+ * - Otherwise (no pointer + no canonical file, or stale pointer + no canonical
+ *   file) → `null`; the gate, not reconcile, surfaces the genuine gap.
+ */
+export function resolveTasksArtifact(text, canonicalRel, fileExists) {
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match)
+        return null;
+    const fm = readFrontmatter(text);
+    const artifacts = fm && typeof fm === 'object' ? fm.artifacts : undefined;
+    const existing = artifacts && typeof artifacts === 'object' ? artifacts.tasks : undefined;
+    const current = typeof existing === 'string' && existing.trim() !== '' ? existing.trim() : undefined;
+    // Existing pointer that resolves to a real file: preserve it (canonical or not).
+    if (current && fileExists(current))
+        return null;
+    // Absent or stale pointer: only adopt the canonical guess if it actually exists.
+    if (fileExists(canonicalRel))
+        return canonicalRel;
+    // No valid target anywhere — leave the gate to flag the genuine gap.
+    return null;
+}
+/**
+ * Insert an HTML-comment sign-off marker (e.g. `<!-- validated: 2026-05-28 -->`)
+ * immediately after the spec's frontmatter block, or at the start of the file when
+ * none exists. Idempotent: when a marker of the same type already exists, returns
+ * the text unchanged and `inserted: false`.
+ */
+export function insertSignoffMarker(text, type, date) {
+    const markerRe = new RegExp(`<!--\\s*${type}:`, 'i');
+    if (markerRe.test(text))
+        return { text, inserted: false };
+    const marker = `<!-- ${type}: ${date} -->`;
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match) {
+        return { text: `${marker}\n${text}`, inserted: true };
+    }
+    const blockEnd = match.index + match[0].length;
+    const before = text.slice(0, blockEnd);
+    const after = text.slice(blockEnd);
+    const sep = after.startsWith('\n') ? '' : '\n';
+    return { text: `${before}${sep}\n${marker}\n${after.replace(/^\n+/, '')}`, inserted: true };
+}
+/**
+ * Parse the leading YAML frontmatter block of a spec markdown string.
+ * Returns `{}` when absent or malformed — never throws.
+ */
+export function readFrontmatter(text) {
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match)
+        return {};
+    try {
+        const parsed = parse(match[1]);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Remove the leading YAML frontmatter block (when present) so body-only regexes
+ * (the `# Title` heading, `**Status:**` prose) cannot match lines inside the
+ * frontmatter — a YAML comment like `# Replace placeholder values when
+ * authoring.` (SPEC_TEMPLATE.md line 2) is indistinguishable from an H1 by
+ * line shape alone.
+ */
+export function stripFrontmatter(text) {
+    return text.replace(FRONTMATTER_RE, '');
+}
+/**
+ * Append AC entries to the frontmatter's `acceptance_criteria:` array. Preserves
+ * other frontmatter via a slice → re-serialize-only-the-AC-list strategy. Returns
+ * the input unchanged when there is no frontmatter block.
+ */
+export function appendAcceptanceCriteria(text, entries) {
+    if (entries.length === 0)
+        return text;
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match)
+        return text;
+    const block = match[1];
+    const hasKey = /^acceptance_criteria\s*:/m.test(block);
+    let newBlock;
+    if (hasKey) {
+        const parsed = readFrontmatter(text);
+        const existing = Array.isArray(parsed.acceptance_criteria) ? parsed.acceptance_criteria : [];
+        const merged = yamlStringify({ acceptance_criteria: [...existing, ...entries] }).trimEnd();
+        // Replace the `acceptance_criteria:` block: from that line through the next
+        // top-level key OR the end of the frontmatter block.
+        newBlock = block.replace(/^acceptance_criteria\s*:[\s\S]*?(?=^[A-Za-z_][A-Za-z0-9_]*\s*:|\s*$)/m, `${merged}\n`);
+    }
+    else {
+        newBlock = `${block}\n${yamlStringify({ acceptance_criteria: entries }).trimEnd()}`;
+    }
+    return text.replace(FRONTMATTER_RE, () => `---\n${newBlock}\n---`);
+}
+/**
+ * Within the leading frontmatter block, flip the `status:` of one list item
+ * (under `acceptance_criteria:` / `user_stories:` / `requirements:`) identified
+ * by its `- id: <id>` line. Line-scoped so all other lines — comments, ordering,
+ * sibling items — are preserved byte-for-byte. Returns the text unchanged when
+ * there is no frontmatter, the section/id is absent, or the status already matches.
+ * Used by `verify-acs` to auto-promote planned -> verified on a real test pass.
+ */
+export function setRequirementStatus(text, section, id, status) {
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match)
+        return text;
+    const lines = match[1].split('\n');
+    const sectionIdx = lines.findIndex((l) => new RegExp(`^${section}:\\s*$`).test(l));
+    if (sectionIdx === -1)
+        return text;
+    const escId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const idRe = new RegExp(`^\\s*-\\s+id:\\s*["']?${escId}["']?\\s*$`);
+    let itemIdx = -1;
+    for (let i = sectionIdx + 1; i < lines.length; i++) {
+        if (/^\S/.test(lines[i]))
+            break; // next column-0 key ends the section
+        if (idRe.test(lines[i])) {
+            itemIdx = i;
+            break;
+        }
+    }
+    if (itemIdx === -1)
+        return text;
+    let statusIdx = -1;
+    for (let i = itemIdx + 1; i < lines.length; i++) {
+        if (/^\S/.test(lines[i]) || /^\s*-\s+id:/.test(lines[i]))
+            break; // next item or section end
+        if (/^\s*status:\s*/.test(lines[i])) {
+            statusIdx = i;
+            break;
+        }
+    }
+    const indent = lines[itemIdx].match(/^(\s*)-\s/)?.[1] ?? '  ';
+    const statusLine = `${indent}  status: ${status}`;
+    let newLines;
+    if (statusIdx !== -1) {
+        if (lines[statusIdx].trim() === `status: ${status}`)
+            return text;
+        newLines = [...lines];
+        newLines[statusIdx] = statusLine;
+    }
+    else {
+        newLines = [...lines.slice(0, itemIdx + 1), statusLine, ...lines.slice(itemIdx + 1)];
+    }
+    const newBlock = newLines.join('\n');
+    if (newBlock === match[1])
+        return text;
+    return text.replace(FRONTMATTER_RE, () => `---\n${newBlock}\n---`);
+}
+/**
+ * Idempotently add `rel` to the `e2e_tests:` list inside the leading frontmatter block.
+ * Appends a fresh `e2e_tests:` block when absent. Returns the text unchanged when
+ * the path is already listed or there is no frontmatter block. Used by `gen-tests
+ * --update-frontmatter`.
+ */
+export function setE2eTests(text, rel) {
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match)
+        return text;
+    const block = match[1];
+    const lines = block.split('\n');
+    const keyIdx = lines.findIndex((l) => /^e2e_tests:\s*$/.test(l));
+    let newLines;
+    if (keyIdx === -1) {
+        newLines = [...lines, 'e2e_tests:', `  - ${rel}`];
+    }
+    else {
+        let end = keyIdx + 1;
+        while (end < lines.length && /^[ \t]+-\s/.test(lines[end]))
+            end++;
+        if (lines.slice(keyIdx + 1, end).some((l) => l.trim() === `- ${rel}`))
+            return text;
+        newLines = [...lines.slice(0, end), `  - ${rel}`, ...lines.slice(end)];
+    }
+    const newBlock = newLines.join('\n');
+    if (newBlock === block)
+        return text;
+    return text.replace(FRONTMATTER_RE, () => `---\n${newBlock}\n---`);
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/lib/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/lib/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AA8BzD,MAAM,cAAc,GAAG,6BAA6B,CAAC;AAErD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,MAAc;IAC5D,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IACxB,MAAM,IAAI,GAAG,oBAAoB,MAAM,EAAE,CAAC;IAC1C,MAAM,QAAQ,GAAG,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC;QAClD,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,uBAAuB,EAAE,IAAI,CAAC;QAC9C,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,EAAE,CAAC;IACxB,4EAA4E;IAC5E,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,QAAQ,QAAQ,OAAO,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,GAAW;IACxD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IACxB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAEjE,IAAI,QAAkB,CAAC;IACvB,IAAI,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAClB,QAAQ,GAAG,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,YAAY,GAAG,EAAE,CAAC,CAAC;IACzD,CAAC;SAAM,CAAC;QACN,oEAAoE;QACpE,IAAI,GAAG,GAAG,MAAM,GAAG,CAAC,CAAC;QACrB,OAAO,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAE,CAAC;YAAE,GAAG,EAAE,CAAC;QAClE,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QAClE,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3F,IAAI,WAAW,KAAK,CAAC,CAAC,EAAE,CAAC;YACvB,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,GAAG,MAAM,UAAU,GAAG,EAAE,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QACnG,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,WAAW,CAAC;YACxC,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAE,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;YACnE,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;YACtB,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,SAAS,UAAU,GAAG,EAAE,CAAC;QACjD,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,QAAQ,QAAQ,OAAO,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,YAAoB,EACpB,UAAoC;IAEpC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,SAAS,GAAG,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAE,EAA8B,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACvG,MAAM,QAAQ,GAAG,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAE,SAAiC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACnH,MAAM,OAAO,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAErG,iFAAiF;IACjF,IAAI,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,iFAAiF;IACjF,IAAI,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,YAAY,CAAC;IAClD,qEAAqE;IACrE,OAAO,IAAI,CAAC;AACd,CAAC;AAcD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,IAAiB,EACjB,IAAY;IAEZ,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,WAAW,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC;IACrD,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC1D,MAAM,MAAM,GAAG,QAAQ,IAAI,KAAK,IAAI,MAAM,CAAC;IAC3C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,KAAK,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACxD,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,GAAG,GAAG,KAAK,MAAM,KAAK,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC9F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAE,CAAY,CAAC;QAC3C,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,MAAyB,CAAC;QAC3E,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY,EAAE,OAAkB;IACvE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IACxB,MAAM,MAAM,GAAG,2BAA2B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvD,IAAI,QAAgB,CAAC;IACrB,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAE,MAAM,CAAC,mBAAiC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5G,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,mBAAmB,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QAC3F,4EAA4E;QAC5E,qDAAqD;QACrD,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,uEAAuE,EAAE,GAAG,MAAM,IAAI,CAAC,CAAC;IACnH,CAAC;SAAM,CAAC;QACN,QAAQ,GAAG,GAAG,KAAK,KAAK,aAAa,CAAC,EAAE,mBAAmB,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;IACtF,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,QAAQ,QAAQ,OAAO,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,OAAgE,EAChE,EAAU,EACV,MAA8B;IAE9B,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEpC,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,OAAO,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACnF,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,MAAM,KAAK,GAAG,EAAE,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,IAAI,MAAM,CAAC,yBAAyB,KAAK,YAAY,CAAC,CAAC;IACpE,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,UAAU,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnD,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;YAAE,MAAM,CAAC,qCAAqC;QACvE,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;YACzB,OAAO,GAAG,CAAC,CAAC;YACZ,MAAM;QACR,CAAC;IACH,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAEhC,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,OAAO,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChD,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;YAAE,MAAM,CAAC,2BAA2B;QAC9F,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;YACrC,SAAS,GAAG,CAAC,CAAC;YACd,MAAM;QACR,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAE,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAC/D,MAAM,UAAU,GAAG,GAAG,MAAM,aAAa,MAAM,EAAE,CAAC;IAElD,IAAI,QAAkB,CAAC;IACvB,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;QACrB,IAAI,KAAK,CAAC,SAAS,CAAE,CAAC,IAAI,EAAE,KAAK,WAAW,MAAM,EAAE;YAAE,OAAO,IAAI,CAAC;QAClE,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;QACtB,QAAQ,CAAC,SAAS,CAAC,GAAG,UAAU,CAAC;IACnC,CAAC;SAAM,CAAC;QACN,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,QAAQ,QAAQ,OAAO,CAAC,CAAC;AACrE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,GAAW;IACnD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IACxB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,IAAI,QAAkB,CAAC;IACvB,IAAI,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAClB,QAAQ,GAAG,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,OAAO,GAAG,EAAE,CAAC,CAAC;IACpD,CAAC;SAAM,CAAC;QACN,IAAI,GAAG,GAAG,MAAM,GAAG,CAAC,CAAC;QACrB,OAAO,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAE,CAAC;YAAE,GAAG,EAAE,CAAC;QACnE,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,GAAG,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QACnF,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,EAAE,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,QAAQ,QAAQ,OAAO,CAAC,CAAC;AACrE,CAAC"}

package/dist/lib/funnel.d.ts

@@ -0,0 +1,22 @@
+import type { SpecFile } from './specs.js';
+export type FunnelInput = {
+    specs: SpecFile[];
+    /** Map spec.path → last-modified epoch-ms (from git). Missing entry = treat as fresh. */
+    mtimeBySpecPath: Record<string, number>;
+    stallDays: number;
+    /** Override of Date.now() for testability. */
+    now?: number;
+};
+export type FunnelReport = {
+    total: number;
+    byStage: Record<string, number>;
+    withStories: number;
+    withACs: number;
+    storiedButNoACs: number;
+    /** Advisory (canonical seed-fixture Phase 3): specs that declare a Lane-4 seed fixture. */
+    withSeedFixtures: number;
+    /** Specs with ACs but no declared seed fixture — the "ships rows, no fixture" gap signal. */
+    acsButNoSeedFixture: number;
+    stalls: number;
+};
+export declare function computeFunnel(input: FunnelInput): FunnelReport;

package/dist/lib/funnel.js

@@ -0,0 +1,41 @@
+import { computeStage } from './pipeline-map.js';
+/** Treat tasks_generated as terminal for stall purposes. */
+const TERMINAL_STAGES = new Set(['tasks_generated']);
+export function computeFunnel(input) {
+    const now = input.now ?? Date.now();
+    const cutoff = now - input.stallDays * 24 * 60 * 60 * 1000;
+    const byStage = {};
+    let withStories = 0, withACs = 0, storied = 0, withSeedFixtures = 0, acsButNoSeedFixture = 0, stalls = 0;
+    for (const s of input.specs) {
+        const stage = computeStage(s);
+        byStage[stage] = (byStage[stage] ?? 0) + 1;
+        if (s.signals.hasUserStories)
+            withStories++;
+        if (s.signals.hasAcceptanceCriteria)
+            withACs++;
+        if (s.signals.hasUserStories && !s.signals.hasAcceptanceCriteria)
+            storied++;
+        if (s.signals.hasSeedFixture)
+            withSeedFixtures++;
+        // "Ships rows, no fixture" proxy: a spec mature enough to have ACs but with no
+        // declared seed fixture — its surfaces likely render empty in E2E/docs.
+        if (s.signals.hasAcceptanceCriteria && !s.signals.hasSeedFixture)
+            acsButNoSeedFixture++;
+        const mtime = input.mtimeBySpecPath[s.path];
+        // A spec is terminal (not stalled) if its computed stage is terminal OR if it already has tasks.
+        const isTerminal = TERMINAL_STAGES.has(stage) || s.hasTasks;
+        if (typeof mtime === 'number' && mtime <= cutoff && !isTerminal)
+            stalls++;
+    }
+    return {
+        total: input.specs.length,
+        byStage,
+        withStories,
+        withACs,
+        storiedButNoACs: storied,
+        withSeedFixtures,
+        acsButNoSeedFixture,
+        stalls,
+    };
+}
+//# sourceMappingURL=funnel.js.map

package/dist/lib/funnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"funnel.js","sourceRoot":"","sources":["../../src/lib/funnel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAyBjD,4DAA4D;AAC5D,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAErD,MAAM,UAAU,aAAa,CAAC,KAAkB;IAC9C,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC3D,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,IAAI,WAAW,GAAG,CAAC,EACjB,OAAO,GAAG,CAAC,EACX,OAAO,GAAG,CAAC,EACX,gBAAgB,GAAG,CAAC,EACpB,mBAAmB,GAAG,CAAC,EACvB,MAAM,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,CAAC,CAAC,OAAO,CAAC,cAAc;YAAE,WAAW,EAAE,CAAC;QAC5C,IAAI,CAAC,CAAC,OAAO,CAAC,qBAAqB;YAAE,OAAO,EAAE,CAAC;QAC/C,IAAI,CAAC,CAAC,OAAO,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,qBAAqB;YAAE,OAAO,EAAE,CAAC;QAC5E,IAAI,CAAC,CAAC,OAAO,CAAC,cAAc;YAAE,gBAAgB,EAAE,CAAC;QACjD,+EAA+E;QAC/E,wEAAwE;QACxE,IAAI,CAAC,CAAC,OAAO,CAAC,qBAAqB,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc;YAAE,mBAAmB,EAAE,CAAC;QACxF,MAAM,KAAK,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC5C,iGAAiG;QACjG,MAAM,UAAU,GAAG,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;QAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,MAAM,IAAI,CAAC,UAAU;YAAE,MAAM,EAAE,CAAC;IAC5E,CAAC;IACD,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;QACzB,OAAO;QACP,WAAW;QACX,OAAO;QACP,eAAe,EAAE,OAAO;QACxB,gBAAgB;QAChB,mBAAmB;QACnB,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/lib/git-mtime.d.ts

@@ -0,0 +1,4 @@
+/** Last-modified epoch-ms for each path, derived from `git log -1 --format=%ct`.
+ *  Falls back silently (path omitted) when git has no history for a path. The
+ *  caller treats absence as "fresh" (no stall). */
+export declare function gitMtimes(repoRoot: string, paths: string[]): Record<string, number>;

package/dist/lib/git-mtime.js

@@ -0,0 +1,23 @@
+import { execFileSync } from 'node:child_process';
+/** Last-modified epoch-ms for each path, derived from `git log -1 --format=%ct`.
+ *  Falls back silently (path omitted) when git has no history for a path. The
+ *  caller treats absence as "fresh" (no stall). */
+export function gitMtimes(repoRoot, paths) {
+    const out = {};
+    for (const p of paths) {
+        try {
+            const sec = execFileSync('git', ['log', '-1', '--format=%ct', '--', p], {
+                cwd: repoRoot,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            if (sec)
+                out[p] = parseInt(sec, 10) * 1000;
+        }
+        catch {
+            // path has no git history — leave it out of the map
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=git-mtime.js.map

package/dist/lib/git-mtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-mtime.js","sourceRoot":"","sources":["../../src/lib/git-mtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;mDAEmD;AACnD,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,KAAe;IACzD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;gBACtE,GAAG,EAAE,QAAQ;gBACb,QAAQ,EAAE,MAAM;gBAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;aACpC,CAAC,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,GAAG;gBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,oDAAoD;QACtD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/lib/metrics.d.ts

@@ -0,0 +1,42 @@
+import type { EosSpecEvent } from './events.js';
+export type CommandStats = {
+    count: number;
+    wallClockMs: number;
+    successRate: number;
+};
+export type ModelStats = {
+    calls: number;
+    tokensIn: number;
+    tokensOut: number;
+    totalCostUsd: number | null;
+};
+export type HaltCauseStats = {
+    /** Halts where a governance gate fired (autonomy working as designed). */
+    expectedHalts: number;
+    /** Halts from crashes/tooling failures/stalls (genuine intervention). */
+    unexpectedHalts: number;
+    /** Count by cause key: a gate name (expected), 'crash', or 'stalled' (unexpected). */
+    byCause: Record<string, number>;
+};
+export type AutonomyStats = {
+    longestRun: number;
+    humanTouches: number;
+    lastHalt?: {
+        command: string;
+        error?: string;
+        ts: string;
+    };
+    byHaltCause: HaltCauseStats;
+};
+export type MetricsReport = {
+    total: number;
+    windowStart?: string;
+    windowEnd?: string;
+    byCommand: Record<string, CommandStats>;
+    byModel: Record<string, ModelStats>;
+    autonomy: AutonomyStats;
+};
+export declare function computeMetrics(events: EosSpecEvent[], opts?: {
+    since?: Date;
+    core?: string;
+}): MetricsReport;

package/dist/lib/metrics.js

@@ -0,0 +1,92 @@
+/** D3 stall threshold. The funnel 30-day idiom is far too coarse for an
+ *  intra-run heartbeat; a multi-hour gap between consecutive events with no
+ *  terminating event is treated as a silent death (context exhaustion / wedged
+ *  process). Tunable via EOS_SPEC_STALL_GAP_MS; default 2 hours. */
+const STALL_GAP_MS = Number(process.env.EOS_SPEC_STALL_GAP_MS) || 2 * 60 * 60 * 1000;
+export function computeMetrics(events, opts = {}) {
+    const filtered = events.filter((e) => {
+        if (opts.since && new Date(e.ts).getTime() < opts.since.getTime())
+            return false;
+        if (opts.core && e.core !== opts.core)
+            return false;
+        return true;
+    });
+    const byCommand = {};
+    const byModel = {};
+    let longestRun = 0;
+    let run = 0;
+    let humanTouches = 0;
+    let lastHalt;
+    let expectedHalts = 0;
+    let unexpectedHalts = 0;
+    const byCause = {};
+    const bump = (k) => {
+        byCause[k] = (byCause[k] ?? 0) + 1;
+    };
+    let prevLifecycleTs;
+    for (const e of filtered) {
+        const c = (byCommand[e.command] ??= { count: 0, ms: 0, oks: 0 });
+        c.count++;
+        c.ms += e.ms;
+        if (e.ok)
+            c.oks++;
+        if (e.model && e.tokens) {
+            const m = (byModel[e.model] ??= { calls: 0, tokensIn: 0, tokensOut: 0, cost: 0, anyNull: false });
+            m.calls++;
+            m.tokensIn += e.tokens.prompt;
+            m.tokensOut += e.tokens.completion;
+            if (e.costUsd === null || e.costUsd === undefined)
+                m.anyNull = true;
+            else
+                m.cost += e.costUsd;
+        }
+        // D1 taxonomy — a gate event (verdict:block, or an explicit halt) is an
+        // EXPECTED halt; an ok:false with no gate is an unexpected crash. A gate
+        // event with ok:true (warn/respected-pass) is neither a halt nor a touch.
+        if (e.gate !== undefined) {
+            if (e.verdict === 'block' || e.ok === false) {
+                expectedHalts++;
+                bump(e.gate);
+            }
+            // Gate events never participate in the run/human-touch counters below.
+            continue;
+        }
+        // D2 — only command-lifecycle events (no gate) drive the run counters.
+        // D3 — a multi-hour gap between consecutive lifecycle events with no
+        // terminating event is a silent stall (unexpected halt).
+        const tsMs = new Date(e.ts).getTime();
+        if (prevLifecycleTs !== undefined && tsMs - prevLifecycleTs > STALL_GAP_MS) {
+            run = 0;
+            unexpectedHalts++;
+            bump('stalled');
+        }
+        prevLifecycleTs = tsMs;
+        if (e.ok) {
+            run++;
+            if (run > longestRun)
+                longestRun = run;
+        }
+        else {
+            run = 0;
+            humanTouches++;
+            unexpectedHalts++;
+            bump(e.haltCause ?? 'crash');
+            lastHalt = { command: e.command, error: e.error, ts: e.ts };
+        }
+    }
+    return {
+        total: filtered.length,
+        windowStart: filtered[0]?.ts,
+        windowEnd: filtered[filtered.length - 1]?.ts,
+        byCommand: Object.fromEntries(Object.entries(byCommand).map(([k, v]) => [
+            k,
+            { count: v.count, wallClockMs: v.ms, successRate: v.oks / v.count },
+        ])),
+        byModel: Object.fromEntries(Object.entries(byModel).map(([k, v]) => [
+            k,
+            { calls: v.calls, tokensIn: v.tokensIn, tokensOut: v.tokensOut, totalCostUsd: v.anyNull ? null : v.cost },
+        ])),
+        autonomy: { longestRun, humanTouches, lastHalt, byHaltCause: { expectedHalts, unexpectedHalts, byCause } },
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/lib/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/lib/metrics.ts"],"names":[],"mappings":"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"}