@encore-os/eos-spec 0.3.1

package/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 Encore-OS. All rights reserved.
+
+This software and the associated documentation files (the "Software") are the
+proprietary and confidential property of Encore-OS. The Software is licensed,
+not sold, for internal use within Encore-OS and its authorized projects only.
+
+No license, express or implied, by estoppel or otherwise, is granted to any
+third party to use, copy, modify, merge, publish, distribute, sublicense, or
+sell copies of the Software, in whole or in part, without the prior written
+permission of Encore-OS.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL ENCORE-OS BE
+LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/bin/check-dist-fresh.js

@@ -0,0 +1,51 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Newest mtime (ms) among .ts files under dir, recursively. 0 when none/unreadable. */
+function newestTsMtime(dir) {
+  let newest = 0;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return newest;
+  }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    try {
+      if (e.isDirectory()) {
+        newest = Math.max(newest, newestTsMtime(full));
+      } else if (e.name.endsWith('.ts')) {
+        newest = Math.max(newest, statSync(full).mtimeMs);
+      }
+    } catch {
+      // unreadable entry — this check must never break the CLI
+    }
+  }
+  return newest;
+}
+
+/**
+ * One-line warning when dist/index.js is missing or older than the newest
+ * src/**\/*.ts, else null. The bin runs compiled dist/ that only rebuilds on
+ * `npm ci`, so src edits are silently invisible without this hint. Detect and
+ * warn only: never auto-builds, never throws (fail-open).
+ */
+export function distStalenessWarning(pkgRoot) {
+  try {
+    const srcMtime = newestTsMtime(join(pkgRoot, 'src'));
+    if (srcMtime === 0) return null; // no sources to compare (published artifact)
+    let distMtime;
+    try {
+      distMtime = statSync(join(pkgRoot, 'dist', 'index.js')).mtimeMs;
+    } catch {
+      return 'eos-spec: dist/ build missing — run `npm --workspace tools/eos-spec run build` first.';
+    }
+    if (srcMtime > distMtime) {
+      return 'eos-spec: warning — dist/ is stale (older than src/); run `npm --workspace tools/eos-spec run build` to pick up source changes.';
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/bin/eos-spec.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Runtime-neutral: Node and Bun both import the compiled ESM in dist/.
+const { run } = await import('../dist/index.js');
+run(process.argv).catch((err) => {
+  console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+  process.exit(1);
+});

package/dist/commands/ac-backfill.d.ts

@@ -0,0 +1,31 @@
+import type { Command } from 'commander';
+import { type UserStory } from '../lib/ac-draft-prompt.js';
+import { type AcEntry } from '../lib/frontmatter.js';
+import { type SpecFile } from '../lib/specs.js';
+export type CallModel = (prompt: string) => Promise<string>;
+export declare function isBackfillTarget(spec: SpecFile): boolean;
+export type Tranche = {
+    targets: SpecFile[];
+    skipped: SpecFile[];
+};
+export declare function planTranche(specs: SpecFile[], opts?: {
+    limit?: number;
+}): Tranche;
+export type DraftInput = {
+    specId: string;
+    core: string;
+    title: string;
+    userStories: UserStory[];
+    research?: string;
+    existingAcCount: number;
+    callModel: CallModel;
+};
+export type DraftResult = {
+    ok: true;
+    acs: AcEntry[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function draftOneSpec(input: DraftInput): Promise<DraftResult>;
+export declare function registerAcBackfill(program: Command, callModel?: CallModel): void;

package/dist/commands/ac-backfill.js

@@ -0,0 +1,198 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { buildAcDraftPrompt } from '../lib/ac-draft-prompt.js';
+import { parseAcResponse } from '../lib/ac-response-parser.js';
+import { logAiCall } from '../lib/ai-call.js';
+import { appendAcceptanceCriteria } from '../lib/frontmatter.js';
+import { emit, getGlobalOptions } from '../lib/output.js';
+import { getRepoRoot } from '../lib/repo.js';
+import { listSpecs } from '../lib/specs.js';
+import { extractUserStories } from '../lib/user-stories.js';
+import { withEventLog } from '../lib/with-event-log.js';
+const AC_DRAFT_MODEL = process.env.AC_DRAFT_MODEL ?? process.env.JUDGE_MODEL ?? 'anthropic/claude-sonnet-4';
+/** Lazily load the OPTIONAL `ai` SDK — only `ac-backfill` (1 of 29 commands) needs
+ *  it, so it is an optionalDependency + dynamic import: the other 28 commands and
+ *  any `/pure` browser consumer never pull the AI SDK into their graph. */
+async function loadGenerateText() {
+    try {
+        return (await import('ai')).generateText;
+    }
+    catch {
+        throw new Error('ac-backfill needs the optional `ai` package to draft ACs. Install it: `npm i ai` (or `bun add ai`).');
+    }
+}
+const defaultCallModel = async (prompt) => {
+    const start = Date.now();
+    const generateText = await loadGenerateText();
+    try {
+        const result = await generateText({ model: AC_DRAFT_MODEL, prompt });
+        const u = result.usage;
+        const promptCount = u.promptTokens ?? u.inputTokens ?? 0;
+        const completionCount = u.completionTokens ?? u.outputTokens ?? 0;
+        const tokens = {
+            prompt: promptCount,
+            completion: completionCount,
+            total: u.totalTokens ?? promptCount + completionCount,
+        };
+        logAiCall({ command: 'ac-backfill', model: AC_DRAFT_MODEL, tokens, ms: Date.now() - start, ok: true });
+        return result.text;
+    }
+    catch (e) {
+        logAiCall({
+            command: 'ac-backfill',
+            model: AC_DRAFT_MODEL,
+            ms: Date.now() - start,
+            ok: false,
+            error: e instanceof Error ? e.message : String(e),
+        });
+        throw e;
+    }
+};
+export function isBackfillTarget(spec) {
+    if (spec.archived)
+        return false;
+    if (spec.status && /^✅|complete/i.test(spec.status))
+        return false;
+    return spec.signals.hasUserStories && !spec.signals.hasAcceptanceCriteria;
+}
+export function planTranche(specs, opts = {}) {
+    const targets = [];
+    const skipped = [];
+    for (const s of specs) {
+        if (isBackfillTarget(s)) {
+            if (opts.limit === undefined || targets.length < opts.limit)
+                targets.push(s);
+        }
+        else if (s.signals.hasUserStories) {
+            skipped.push(s);
+        }
+    }
+    return { targets, skipped };
+}
+export async function draftOneSpec(input) {
+    const prompt = buildAcDraftPrompt({
+        specId: input.specId,
+        core: input.core,
+        title: input.title,
+        userStories: input.userStories,
+        research: input.research,
+        existingAcCount: input.existingAcCount,
+    });
+    const raw = await input.callModel(prompt);
+    const parsed = parseAcResponse(raw);
+    if (!parsed.ok)
+        return { ok: false, error: parsed.error };
+    return { ok: true, acs: parsed.acs };
+}
+/** Read minimal context for drafting from the spec file on disk. */
+function readSpecContext(spec) {
+    const text = readFileSync(spec.path, 'utf8');
+    const stories = extractUserStories(text);
+    const acMatches = [...text.matchAll(/^\s*-\s*id:\s*AC-(\d+)/gim)];
+    const existingAcCount = acMatches.reduce((max, m) => Math.max(max, parseInt(m[1], 10)), 0);
+    const researchPath = spec.path.replace(/\/specs\/[^/]+\.md$/, `/research/${spec.id}-RESEARCH.md`);
+    let research;
+    try {
+        research = readFileSync(researchPath, 'utf8');
+    }
+    catch {
+        /* no research */
+    }
+    return { userStories: stories, research, existingAcCount };
+}
+export function registerAcBackfill(program, callModel = defaultCallModel) {
+    program
+        .command('ac-backfill')
+        .description('Draft Gherkin ACs for storied-but-no-ACs specs in one core (AI-gateway-backed; opens one PR).')
+        .requiredOption('--core <core>', 'Target core (cl, pm, hr, …)')
+        .option('--limit <n>', 'Stop after drafting N specs (default: all targets in the core)')
+        .option('--dry-run', 'Plan only — no AI calls, no writes, no commits', false)
+        .action(withEventLog('ac-backfill', async (options, cmd) => {
+        const global = getGlobalOptions(cmd);
+        const repoRoot = getRepoRoot(global.repoRoot);
+        const all = listSpecs(repoRoot, options.core);
+        const limit = options.limit ? parseInt(options.limit, 10) : undefined;
+        const plan = planTranche(all, { limit });
+        if (options.dryRun) {
+            emit(global, {
+                ok: true,
+                data: {
+                    core: options.core,
+                    targets: plan.targets.map((s) => s.id),
+                    skipped: plan.skipped.length,
+                    dryRun: true,
+                },
+                text: `ac-backfill (dry-run, ${options.core}): ${plan.targets.length} target(s), ${plan.skipped.length} skipped (have ACs already)\n` +
+                    plan.targets.map((s) => `  - ${s.id}`).join('\n'),
+            });
+            return;
+        }
+        if (!process.env.AI_GATEWAY_API_KEY) {
+            emit(global, {
+                ok: false,
+                data: null,
+                text: 'ac-backfill: AI_GATEWAY_API_KEY not set; pass --dry-run to plan only.',
+            });
+            return;
+        }
+        const drafted = [];
+        const failed = [];
+        for (const spec of plan.targets) {
+            const ctx = readSpecContext(spec);
+            if (ctx.userStories.length === 0) {
+                // Targeted by deriveSignals (has a "User Stories" heading) but no stories are
+                // extractable in a supported format — skip before spending an AI call.
+                failed.push({ id: spec.id, error: 'no extractable user stories (unsupported story format)' });
+                continue;
+            }
+            const r = await draftOneSpec({
+                specId: spec.id,
+                core: spec.core,
+                title: spec.title ?? spec.id,
+                userStories: ctx.userStories,
+                research: ctx.research,
+                existingAcCount: ctx.existingAcCount,
+                callModel,
+            });
+            if (!r.ok) {
+                failed.push({ id: spec.id, error: r.error });
+                continue;
+            }
+            const text = readFileSync(spec.path, 'utf8');
+            const updated = appendAcceptanceCriteria(text, r.acs);
+            if (updated === text) {
+                // Draft produced no usable ACs (empty / unparseable response) — skipping avoids
+                // an empty commit that would otherwise abort the whole campaign.
+                failed.push({ id: spec.id, error: 'no ACs produced (empty/unparseable draft)' });
+                continue;
+            }
+            writeFileSync(spec.path, updated, 'utf8');
+            try {
+                execFileSync('git', ['add', spec.path], { cwd: repoRoot });
+                execFileSync('git', ['commit', '-m', `feat(${spec.core}): draft ACs for ${spec.id} [ai-draft]`], {
+                    cwd: repoRoot,
+                });
+            }
+            catch (e) {
+                // A pre-commit gate (or empty commit) rejected this spec — revert the working-tree
+                // edit and record the failure, but keep processing the rest of the tranche.
+                try {
+                    execFileSync('git', ['checkout', '--', spec.path], { cwd: repoRoot });
+                }
+                catch {
+                    /* best-effort revert */
+                }
+                failed.push({ id: spec.id, error: `commit rejected: ${e instanceof Error ? e.message : String(e)}` });
+                continue;
+            }
+            drafted.push(spec.id);
+        }
+        emit(global, {
+            ok: true,
+            data: { core: options.core, drafted, failed },
+            text: `ac-backfill (${options.core}): drafted=${drafted.length} failed=${failed.length}\n` +
+                (failed.length ? `failures:\n${failed.map((f) => `  - ${f.id}: ${f.error}`).join('\n')}` : ''),
+        });
+    }));
+}
+//# sourceMappingURL=ac-backfill.js.map

package/dist/commands/ac-backfill.js.map

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

package/dist/commands/archive.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerArchive(program: Command): void;

package/dist/commands/archive.js

@@ -0,0 +1,101 @@
+import { archiveSpec, archiveSpecsByFilter, isArchiveEligible } from '../lib/archive.js';
+import { logEvent, RUN_ID } from '../lib/events.js';
+import { emit, emitContinuing, getGlobalOptions } from '../lib/output.js';
+import { getRepoRoot } from '../lib/repo.js';
+import { findSpec } from '../lib/specs.js';
+import { withEventLog } from '../lib/with-event-log.js';
+function followUpNotes(results) {
+    const archived = results.filter((r) => r.moved.length > 0).map((r) => r.specId);
+    if (archived.length === 0)
+        return '';
+    const ids = archived.join(', ');
+    return [
+        '',
+        'Manual follow-up:',
+        `  - Update SPEC_STATUS_REGISTRY.md — mark ${ids} as 🗄️ Archived`,
+        `  - Remove ${ids} from active section of SPEC_INDEX.md (if present)`,
+        `  - Remove ${ids} from DEFERRED_DASHBOARD.md (if present)`,
+    ].join('\n');
+}
+export function registerArchive(program) {
+    program
+        .command('archive')
+        .description('Archive completed spec files to specs/{core}/archive/.')
+        .option('--spec <id>', 'Single spec id to archive (e.g. PF-37)')
+        .option('--core <core>', 'Limit bulk archive to one core')
+        .option('--status <status>', 'Only archive specs matching this status; "complete" also matches "implemented" (default: complete)', 'complete')
+        .option('--older-than <days>', 'Only archive specs whose last git commit is older than N days')
+        .option('--dry-run', 'Show what would be archived without moving files', false)
+        .option('--force', 'Override the status guard (archive a spec whose status is not archive-eligible)', false)
+        .action(withEventLog('archive', async (options, cmd) => {
+        const global = getGlobalOptions(cmd);
+        const repoRoot = getRepoRoot(global.repoRoot);
+        const logger = global.json || global.quiet ? null : (m) => emitContinuing(global, m);
+        if (options.spec) {
+            // Look up the spec to check eligibility (used by both dry-run and telemetry below).
+            const specForGuard = findSpec(repoRoot, options.spec);
+            const eligible = !specForGuard || isArchiveEligible(specForGuard.status);
+            if (options.dryRun) {
+                // Fix: honour the status guard in dry-run so the reported outcome matches a real run.
+                const willArchive = options.force || eligible;
+                emit(global, {
+                    ok: willArchive,
+                    data: {
+                        specId: options.spec,
+                        dryRun: true,
+                        moved: [],
+                        skipped: [],
+                        ...(willArchive ? {} : { refused: true }),
+                    },
+                    text: willArchive
+                        ? `archive (dry-run): would archive ${options.spec}`
+                        : `archive (dry-run): would refuse ${options.spec} — status "${specForGuard?.status ?? '(none)'}" is not archive-eligible; pass --force to override`,
+                });
+            }
+            const result = archiveSpec(repoRoot, options.spec, logger, global.config, { force: options.force });
+            // Gate telemetry (design §4.6): emit whenever the status guard was exercised.
+            if (!eligible) {
+                logEvent({
+                    ts: new Date().toISOString(),
+                    command: 'archive',
+                    runId: RUN_ID,
+                    ms: 0,
+                    ok: !result.refused,
+                    specId: result.specId,
+                    gate: 'archive-status-guard',
+                    verdict: 'block',
+                    overridden: options.force === true,
+                });
+            }
+            emit(global, {
+                ok: result.refused ? false : result.moved.length > 0,
+                data: result,
+                text: result.refused
+                    ? `archive: refused ${result.specId} — ${result.reason}; pass --force to override`
+                    : (result.moved.length > 0
+                        ? `archive: moved ${result.moved.length} file(s) for ${result.specId}`
+                        : `archive: nothing to move for ${result.specId}${result.skipped.length ? ` (${result.skipped.length} already archived)` : ''}`) +
+                        followUpNotes([result]),
+            });
+        }
+        const olderThanDays = options.olderThan ? parseInt(options.olderThan, 10) : undefined;
+        const results = archiveSpecsByFilter(repoRoot, {
+            core: options.core,
+            status: options.status,
+            olderThanDays,
+            dryRun: options.dryRun,
+            force: options.force,
+        }, logger, global.config);
+        const totalMoved = results.reduce((n, r) => n + r.moved.length, 0);
+        const refusedCount = results.filter((r) => r.refused).length;
+        emit(global, {
+            ok: true,
+            data: { results, totalMoved, dryRun: options.dryRun },
+            text: (options.dryRun
+                ? `archive (dry-run): ${results.filter((r) => !r.refused).length} spec(s) would be archived${refusedCount ? ` (${refusedCount} refused by status guard)` : ''}`
+                : `archive: ${totalMoved} file(s) moved across ${results.filter((r) => r.moved.length > 0).length} spec(s)${refusedCount ? ` (${refusedCount} refused by status guard; --force to override)` : ''}`) +
+                followUpNotes(results),
+        });
+    }));
+}
+//# sourceMappingURL=archive.js.map

package/dist/commands/archive.js.map

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

package/dist/commands/audit.d.ts

@@ -0,0 +1,30 @@
+import type { Command } from 'commander';
+import { type SpecFile } from '../lib/specs.js';
+export type AuditRow = {
+    id: string;
+    status: string;
+    acValidated: '✅' | '❌';
+    backlinked: '✅' | '❌';
+    e2eListed: '✅' | '❌';
+    prodReady: '✅' | '❌';
+    /** Set when the row fails the audit for a reason the ✅/❌ columns can't show
+     *  (e.g. a `hand_closed` AC with no `## Verification` backlink). */
+    note?: string;
+};
+export type AuditData = {
+    date: string;
+    rows: Array<AuditRow & {
+        core: string;
+    }>;
+};
+/**
+ * Filesystem-is-truth row for one spec. The "AC Validated" gate passes when every
+ * AC has reached a terminal state — `verified | hand_closed | deferred`, i.e.
+ * nothing left `planned` (issue #174) — with at least one AC authored. A
+ * `hand_closed` AC must additionally be backed by a `## Verification` section;
+ * a hand_closed AC with no Verification backlink is itself a violation that fails
+ * the gate and is surfaced via `note`.
+ */
+export declare function buildAuditRow(spec: SpecFile, backlinkedIds: Set<string>): AuditRow;
+export declare function collectAuditData(repoRoot: string, date: string): AuditData;
+export declare function registerAudit(program: Command): void;

package/dist/commands/audit.js

@@ -0,0 +1,107 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { emit, getGlobalOptions } from '../lib/output.js';
+import { coresList, getRepoRoot, isProtectedBranch } from '../lib/repo.js';
+import { listSpecs } from '../lib/specs.js';
+import { scanVerifies } from '../lib/verifies-scan.js';
+/**
+ * Filesystem-is-truth row for one spec. The "AC Validated" gate passes when every
+ * AC has reached a terminal state — `verified | hand_closed | deferred`, i.e.
+ * nothing left `planned` (issue #174) — with at least one AC authored. A
+ * `hand_closed` AC must additionally be backed by a `## Verification` section;
+ * a hand_closed AC with no Verification backlink is itself a violation that fails
+ * the gate and is surfaced via `note`.
+ */
+export function buildAuditRow(spec, backlinkedIds) {
+    const ac = spec.signals.acStatus ?? { planned: 0, verified: 0, handClosed: 0, deferred: 0 };
+    const total = ac.planned + ac.verified + ac.handClosed + ac.deferred;
+    // A hand_closed AC asserts a CI suite the src-lane prover can't reach proved it;
+    // that assertion is only legible if the spec carries a `## Verification` backlink.
+    const handClosedUnbacked = ac.handClosed > 0 && !spec.signals.hasVerificationSection;
+    const allTerminal = total > 0 && ac.planned === 0;
+    const acValidated = allTerminal && !handClosedUnbacked ? '✅' : '❌';
+    const backlinked = backlinkedIds.size > 0 ? '✅' : '❌';
+    const e2eListed = spec.signals.hasGeneratedTests ? '✅' : '❌';
+    const prodReady = acValidated === '✅' && e2eListed === '✅' ? '✅' : '❌';
+    const note = handClosedUnbacked
+        ? `${ac.handClosed} hand_closed AC(s) without a "## Verification" section`
+        : undefined;
+    return {
+        id: spec.id,
+        status: spec.status ?? 'unknown',
+        acValidated,
+        backlinked,
+        e2eListed,
+        prodReady,
+        ...(note ? { note } : {}),
+    };
+}
+export function collectAuditData(repoRoot, date) {
+    const verifies = scanVerifies(repoRoot);
+    const rows = [];
+    for (const core of coresList(repoRoot)) {
+        // `verifies` is scanned once here and consulted per spec for the Backlinked
+        // column; the @verifies map is not threaded into listSpecs (this engine's
+        // listSpecs derives its own on-disk backlink signals).
+        const specs = listSpecs(repoRoot, core);
+        for (const s of specs.sort((a, b) => a.id.localeCompare(b.id))) {
+            rows.push({ core, ...buildAuditRow(s, verifies.get(s.id) ?? new Set()) });
+        }
+    }
+    return { date, rows };
+}
+function renderMarkdown(data) {
+    const lines = [
+        `# Completion & Readiness Audit`,
+        ``,
+        `**Date:** ${data.date} · **Method:** filesystem-is-truth (eos-spec audit). Every ✅ is backed by on-disk evidence; no hand-edited green.`,
+        ``,
+    ];
+    const cores = [...new Set(data.rows.map((r) => r.core))];
+    for (const core of cores) {
+        const coreRows = data.rows.filter((r) => r.core === core);
+        lines.push(`## ${core}`, ``, `| Spec | Status | AC Validated | Backlinked | E2E Listed | Prod Ready |`, `|------|--------|--------------|------------|------------|------------|`);
+        for (const r of coreRows) {
+            lines.push(`| ${r.id} | ${r.status} | ${r.acValidated} | ${r.backlinked} | ${r.e2eListed} | ${r.prodReady} |`);
+        }
+        lines.push(``);
+        const violations = coreRows.filter((r) => r.note);
+        if (violations.length > 0) {
+            lines.push(`> Audit violations:`);
+            for (const r of violations)
+                lines.push(`> - ${r.id}: ${r.note}`);
+            lines.push(``);
+        }
+    }
+    return lines.join('\n');
+}
+export function registerAudit(program) {
+    program
+        .command('audit')
+        .description('Render a filesystem-is-truth completion/readiness audit per core (no hand-edited green). --write saves a draft under docs/audits/ (refused on a protected branch).')
+        .option('--write', 'Write the audit to docs/audits/<date>-completion-audit.md (working-tree only; refused on main/master)', false)
+        .option('--date <date>', 'Override the date stamp (YYYY-MM-DD)')
+        .action((options, cmd) => {
+        const global = getGlobalOptions(cmd);
+        const repoRoot = getRepoRoot(global.repoRoot);
+        const date = options.date ?? new Date().toISOString().slice(0, 10);
+        const data = collectAuditData(repoRoot, date);
+        const md = renderMarkdown(data);
+        if (options.write) {
+            if (isProtectedBranch(repoRoot))
+                emit(global, {
+                    ok: false,
+                    data: {},
+                    text: 'audit: refusing to --write on a protected branch (main); run on a feature branch / draft PR',
+                    exitCode: 2,
+                });
+            const dir = join(repoRoot, 'docs', 'audits');
+            mkdirSync(dir, { recursive: true });
+            const out = join(dir, `${date}-completion-audit.md`);
+            writeFileSync(out, md);
+            emit(global, { ok: true, data: { ...data, written: out }, text: `audit: wrote ${out}` });
+        }
+        emit(global, { ok: true, data, text: md });
+    });
+}
+//# sourceMappingURL=audit.js.map

package/dist/commands/audit.js.map

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

package/dist/commands/backfill.d.ts

@@ -0,0 +1,41 @@
+import type { Command } from 'commander';
+import { type TierResult } from '../lib/classify-debt.js';
+import { type DebtRow, type RelinkEntry } from '../lib/debt-dashboard.js';
+import type { ScorecardReport, ScorecardRow } from '../lib/scorecard.js';
+/** A computed debt row plus the raw classification + the spec path, for the command's apply path. */
+export interface BackfillEntry {
+    row: DebtRow;
+    tier: TierResult;
+    scorecardRow: ScorecardRow;
+    specPath: string;
+}
+/**
+ * Rewrite ONLY the frontmatter `status:` line to `newStatus`, preserving the trailing newline —
+ * the exact single-line replacement approach as scripts/specs/remap-status-values.ts. Returns the
+ * text unchanged when no `status:` line is present. Pure (string in / string out) so the apply path
+ * is unit-testable without touching the real repo.
+ */
+export declare function rewriteStatusLine(text: string, newStatus: string): {
+    text: string;
+    changed: boolean;
+};
+/** Append a one-line evidence receipt as an HTML comment near the frontmatter (after the closing `---`). */
+export declare function appendEvidenceReceipt(text: string, receipt: string): string;
+/** Apply a downgrade to one spec's text: rewrite status + append the receipt. Pure. */
+export declare function applyDowngrade(text: string, newStatus: string, receipt: string): {
+    text: string;
+    changed: boolean;
+};
+/** Compute the list of missing verification artifacts for a claimed-complete spec. */
+export declare function computeMissing(row: ScorecardRow, report: ScorecardReport, tier: TierResult): string[];
+/** Effort heuristic: S for T1 (relink only); M for T2 with a small requirement count; L for T4 / large. */
+export declare function computeEffort(tier: TierResult, requirementsTotal: number): 'S' | 'M' | 'L';
+/**
+ * Build one BackfillEntry per claimed-complete spec in the core. Pure-ish: reads the filesystem via
+ * the scorecard + code-evidence probe but performs NO writes. The caller decides dry-run vs apply.
+ */
+export declare function buildBackfill(repoRoot: string, core: string): {
+    entries: BackfillEntry[];
+    relinkQueue: RelinkEntry[];
+};
+export declare function registerBackfill(program: Command): void;