@encore-os/eos-spec 0.3.1

package/dist/commands/backfill.js

@@ -0,0 +1,239 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { buildQueue } from '../lib/backfill-queue.js';
+import { classifyTier } from '../lib/classify-debt.js';
+import { deriveCodeEvidence } from '../lib/code-evidence.js';
+import { renderDebtDashboard } from '../lib/debt-dashboard.js';
+import { ErrorCode, emit, getGlobalOptions } from '../lib/output.js';
+import { coresList, getRepoRoot, isKnownCore } from '../lib/repo.js';
+import { buildScorecardForCore } from '../lib/scorecard-run.js';
+import { findSpec } from '../lib/specs.js';
+import { scanVerifies } from '../lib/verifies-scan.js';
+import { withEventLog } from '../lib/with-event-log.js';
+/**
+ * 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 function rewriteStatusLine(text, newStatus) {
+    const m = /^status:[ \t]*(.+?)[ \t]*$/m.exec(text);
+    if (!m)
+        return { text, changed: false };
+    if (m[1] === newStatus)
+        return { text, changed: false };
+    return { text: text.replace(m[0], `status: ${newStatus}`), changed: true };
+}
+/** Append a one-line evidence receipt as an HTML comment near the frontmatter (after the closing `---`). */
+export function appendEvidenceReceipt(text, receipt) {
+    const comment = `<!-- backfill: ${receipt} -->`;
+    // Insert right after the closing frontmatter fence so it sits near the top, not at EOF.
+    const fenceEnd = /^---\s*$/m;
+    const first = fenceEnd.exec(text);
+    if (first) {
+        const second = fenceEnd.exec(text.slice(first.index + first[0].length));
+        if (second) {
+            const insertAt = first.index + first[0].length + second.index + second[0].length;
+            return `${text.slice(0, insertAt)}\n${comment}${text.slice(insertAt)}`;
+        }
+    }
+    return `${comment}\n${text}`;
+}
+/** Apply a downgrade to one spec's text: rewrite status + append the receipt. Pure. */
+export function applyDowngrade(text, newStatus, receipt) {
+    const { text: rewritten, changed } = rewriteStatusLine(text, newStatus);
+    if (!changed)
+        return { text, changed: false };
+    return { text: appendEvidenceReceipt(rewritten, receipt), changed: true };
+}
+/** Compute the list of missing verification artifacts for a claimed-complete spec. */
+export function computeMissing(row, report, tier) {
+    if (tier.tier === 'T0')
+        return [];
+    const missing = [];
+    if (tier.tier === 'T1') {
+        // Tests exist but @verifies linkage is broken — the one missing artifact is the (re)link.
+        missing.push('@verifies');
+        return missing;
+    }
+    // T2/T3/T4: count what's absent.
+    if (row.requirementsVerified === 0)
+        missing.push('tests');
+    if (!report.hasE2E)
+        missing.push('e2e');
+    if (!report.hasDocshots)
+        missing.push('docshots');
+    return missing;
+}
+/** Effort heuristic: S for T1 (relink only); M for T2 with a small requirement count; L for T4 / large. */
+export function computeEffort(tier, requirementsTotal) {
+    if (tier.tier === 'T0' || tier.tier === 'T1')
+        return 'S';
+    if (tier.tier === 'T2')
+        return requirementsTotal <= 8 ? 'M' : 'L';
+    if (tier.tier === 'T3')
+        return 'M';
+    return 'L'; // T4
+}
+/**
+ * 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 function buildBackfill(repoRoot, core) {
+    const verified = scanVerifies(repoRoot);
+    const report = buildScorecardForCore(repoRoot, core, verified);
+    const entries = [];
+    const relinkQueue = [];
+    for (const row of report.rows) {
+        if (!row.claimsComplete)
+            continue;
+        const spec = findSpec(repoRoot, row.id);
+        if (!spec)
+            continue;
+        const evidence = deriveCodeEvidence(repoRoot, spec, row);
+        const tier = classifyTier({
+            claimsComplete: row.claimsComplete,
+            requirementsTotal: row.requirementsTotal,
+            requirementsVerified: row.requirementsVerified,
+        }, evidence);
+        const missing = computeMissing(row, report, tier);
+        const debtRow = {
+            id: row.id,
+            claimed: row.claimedStatus ?? 'complete',
+            tier: tier.tier,
+            honestStatus: tier.honestStatus,
+            missing,
+            effort: computeEffort(tier, row.requirementsTotal),
+            reason: evidence.reason,
+        };
+        entries.push({ row: debtRow, tier, scorecardRow: row, specPath: spec.path });
+        if (tier.action === 'relink') {
+            relinkQueue.push({ id: row.id, reason: evidence.reason || 'tests exist; @verifies linkage broken' });
+        }
+    }
+    return { entries, relinkQueue };
+}
+export function registerBackfill(program) {
+    program
+        .command('backfill')
+        .description('Verification-debt classifier: per claimed-complete spec, classify a debt tier (T0..T4) from code/test evidence, write specs/<core>/VERIFICATION_DEBT.md, and (with --apply) downgrade overstated status lines.')
+        .requiredOption('--core <core>', 'Core to classify (e.g. hr)')
+        .option('--apply', 'Rewrite overstated status lines to the honest status (T1 relinks are NOT downgraded)', false)
+        .option('--plan', 'Print the prioritised work queue (T1 relinks first, then T2/T3/T4 rebuilds) — read-only, no writes', false)
+        .action(withEventLog('backfill', async (options, cmd) => {
+        const global = getGlobalOptions(cmd);
+        const repoRoot = getRepoRoot(global.repoRoot);
+        const core = String(options.core).toLowerCase();
+        if (!isKnownCore(core, repoRoot)) {
+            emit(global, {
+                ok: false,
+                error: {
+                    code: ErrorCode.UNKNOWN_CORE,
+                    message: `backfill: unknown core "${options.core}". Valid cores: ${coresList(repoRoot).join(', ')}`,
+                },
+                data: { core: options.core, validCores: coresList(repoRoot) },
+                text: `backfill: unknown core "${options.core}". Valid cores: ${coresList(repoRoot).join(', ')}`,
+            });
+        }
+        const { entries, relinkQueue } = buildBackfill(repoRoot, core);
+        // --plan: print the prioritised work queue and return early (read-only).
+        if (options.plan) {
+            // Build the queue from all non-T0 entries (both relinks and downgrades), T1 first.
+            const queueRows = entries.map((e) => ({ ...e.row, action: e.tier.action }));
+            const queue = buildQueue(queueRows);
+            if (queue.length === 0) {
+                const planText = [
+                    `Backfill plan (${core}): queue is empty.`,
+                    `  ${entries.length} claimed-complete spec(s) classified — all are T0 (no work needed).`,
+                ].join('\n');
+                emit(global, {
+                    ok: true,
+                    data: { core, queue: [] },
+                    text: planText,
+                });
+                return;
+            }
+            const header = `Backfill plan (${core}): ${queue.length} spec(s) queued (T1 relinks first, then T2→T4 rebuilds)\n`;
+            const rows = queue.map((r) => {
+                const missingStr = r.missing.length > 0 ? r.missing.join(', ') : '—';
+                const nextStep = r.tier === 'T1'
+                    ? 'add @verifies tags in test files pointing to this spec id'
+                    : `restore missing artifacts: ${missingStr}`;
+                return [
+                    `  ${r.id}`,
+                    `    tier        : ${r.tier}`,
+                    `    action      : ${r.action}`,
+                    `    honest      : ${r.honestStatus}  (claimed: ${r.claimed})`,
+                    `    missing     : ${missingStr}`,
+                    `    next step   : ${nextStep}`,
+                    `    effort      : ${r.effort}`,
+                ].join('\n');
+            });
+            const planText = `${header}\n${rows.join('\n\n')}`;
+            emit(global, {
+                ok: true,
+                data: {
+                    core,
+                    queue: queue.map((r) => ({
+                        id: r.id,
+                        tier: r.tier,
+                        action: r.action,
+                        honestStatus: r.honestStatus,
+                        missing: r.missing,
+                        effort: r.effort,
+                    })),
+                },
+                text: planText,
+            });
+            return;
+        }
+        // Always write the dashboard.
+        const dashboard = renderDebtDashboard(core, entries.map((e) => e.row), { relinkQueue });
+        const dashboardPath = join(repoRoot, 'specs', core, 'VERIFICATION_DEBT.md');
+        mkdirSync(dirname(dashboardPath), { recursive: true });
+        writeFileSync(dashboardPath, dashboard);
+        const downgrades = entries.filter((e) => e.tier.action === 'downgrade');
+        let applied = 0;
+        if (options.apply) {
+            for (const e of downgrades) {
+                const text = readFileSync(e.specPath, 'utf8');
+                const failed = e.row.missing.length > 0 ? e.row.missing.join('/') : 'unverified';
+                const receipt = `${e.tier.tier} ${e.row.claimed}→${e.tier.honestStatus} (missing: ${failed})`;
+                const { text: next, changed } = applyDowngrade(text, e.tier.honestStatus, receipt);
+                if (changed) {
+                    writeFileSync(e.specPath, next);
+                    applied++;
+                }
+            }
+        }
+        const previewLines = downgrades.map((e) => `    ${e.row.id}  ${e.row.claimed} → ${e.tier.honestStatus}  (${e.tier.tier})`);
+        const text = [
+            `Verification debt (${core}): ${entries.length} claimed-complete specs classified`,
+            `  dashboard written: specs/${core}/VERIFICATION_DEBT.md`,
+            `  would downgrade  : ${downgrades.length}`,
+            `  relink queue     : ${relinkQueue.length}`,
+            options.apply ? `  APPLIED downgrades: ${applied}` : '  (dry-run — no spec frontmatter changed)',
+            '',
+            ...(downgrades.length
+                ? [options.apply ? '  Downgraded:' : '  Would downgrade (current → honest, tier):', ...previewLines]
+                : ['  No downgrades.']),
+        ].join('\n');
+        emit(global, {
+            ok: true,
+            data: {
+                core,
+                classified: entries.length,
+                downgrades: downgrades.map((e) => ({
+                    id: e.row.id,
+                    from: e.row.claimed,
+                    to: e.tier.honestStatus,
+                    tier: e.tier.tier,
+                })),
+                relinkQueue,
+                applied: options.apply ? applied : 0,
+            },
+            text,
+        });
+    }));
+}
+//# sourceMappingURL=backfill.js.map

package/dist/commands/backfill.js.map

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

package/dist/commands/checkArtifacts.d.ts

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

package/dist/commands/checkArtifacts.js

@@ -0,0 +1,48 @@
+import { checkArtifactIntegrity } from '../lib/artifact-integrity.js';
+import { emit, getGlobalOptions } from '../lib/output.js';
+import { getRepoRoot } from '../lib/repo.js';
+export function registerCheckArtifacts(program) {
+    program
+        .command('check-artifacts')
+        .description('Smoke-check automation artifact integrity: verifies that every automation/skills/*/SKILL.md, automation/commands/*.md, and automation/agents/*.md has non-empty YAML frontmatter with a `name` field, and that .claude/.cursor symlinks into automation/ resolve (no dangling links). Measure-only — does not modify anything.')
+        .action(async (_options, cmd) => {
+        const global = getGlobalOptions(cmd);
+        const repoRoot = getRepoRoot(global.repoRoot);
+        const report = checkArtifactIntegrity(repoRoot);
+        const { missingFrontmatter, danglingSymlinks } = report;
+        const totalIssues = missingFrontmatter.length + danglingSymlinks.length;
+        if (totalIssues === 0) {
+            emit(global, {
+                ok: true,
+                data: { missingFrontmatter: [], danglingSymlinks: [] },
+                text: '0 issues — all automation artifacts have valid frontmatter and all symlinks resolve.',
+            });
+        }
+        const lines = [];
+        if (missingFrontmatter.length > 0) {
+            lines.push(`${missingFrontmatter.length} file(s) missing frontmatter (no "name:" field in first 600 chars):`);
+            for (const p of missingFrontmatter) {
+                lines.push(`  ${p}`);
+            }
+        }
+        else {
+            lines.push('0 files missing frontmatter.');
+        }
+        if (danglingSymlinks.length > 0) {
+            lines.push(`${danglingSymlinks.length} dangling symlink(s) in .claude/.cursor:`);
+            for (const p of danglingSymlinks) {
+                lines.push(`  ${p}`);
+            }
+        }
+        else {
+            lines.push('0 dangling symlinks.');
+        }
+        emit(global, {
+            ok: false,
+            data: { missingFrontmatter, danglingSymlinks },
+            text: lines.join('\n'),
+            exitCode: 1,
+        });
+    });
+}
+//# sourceMappingURL=checkArtifacts.js.map

package/dist/commands/checkArtifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkArtifacts.js","sourceRoot":"","sources":["../../src/commands/checkArtifacts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CACV,gUAAgU,CACjU;SACA,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE;QAC9B,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;QAEhD,MAAM,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAAC;QACxD,MAAM,WAAW,GAAG,kBAAkB,CAAC,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC;QAExE,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,EAAE;gBACX,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAE,gBAAgB,EAAE,EAAE,EAAE;gBACtD,IAAI,EAAE,sFAAsF;aAC7F,CAAC,CAAC;QACL,CAAC;QAED,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,MAAM,qEAAqE,CAAC,CAAC;YAC9G,KAAK,MAAM,CAAC,IAAI,kBAAkB,EAAE,CAAC;gBACnC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;QAC7C,CAAC;QAED,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,MAAM,0CAA0C,CAAC,CAAC;YACjF,KAAK,MAAM,CAAC,IAAI,gBAAgB,EAAE,CAAC;gBACjC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,CAAC,MAAM,EAAE;YACX,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,EAAE,kBAAkB,EAAE,gBAAgB,EAAE;YAC9C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YACtB,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/checkPlacement.d.ts

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

package/dist/commands/checkPlacement.js

@@ -0,0 +1,31 @@
+import { emit, getGlobalOptions } from '../lib/output.js';
+import { findMisplacedSpecs } from '../lib/placement.js';
+import { getRepoRoot } from '../lib/repo.js';
+export function registerCheckPlacement(program) {
+    program
+        .command('check-placement')
+        .description('Report primary spec files that live outside their canonical location (specs/<core>/specs/ or specs/<core>/ux/). Lifecycle artifacts (TASKS, PLAN, CONTEXT, etc.) are ignored.')
+        .action(async (_options, cmd) => {
+        const global = getGlobalOptions(cmd);
+        const repoRoot = getRepoRoot(global.repoRoot);
+        const misplaced = findMisplacedSpecs(repoRoot);
+        if (misplaced.length === 0) {
+            emit(global, {
+                ok: true,
+                data: { count: 0, misplaced: [] },
+                text: '0 misplaced specs',
+            });
+        }
+        const text = [
+            `${misplaced.length} misplaced spec(s):`,
+            ...misplaced.map((m) => `  ${m.id}  ${m.path}\n    → expected in: ${m.expectedDir}`),
+        ].join('\n');
+        emit(global, {
+            ok: false,
+            data: { count: misplaced.length, misplaced },
+            text,
+            exitCode: 1,
+        });
+    });
+}
+//# sourceMappingURL=checkPlacement.js.map

package/dist/commands/checkPlacement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkPlacement.js","sourceRoot":"","sources":["../../src/commands/checkPlacement.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CACV,+KAA+K,CAChL;SACA,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE;QAC9B,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9C,MAAM,SAAS,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QAE/C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,EAAE;gBACX,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE;gBACjC,IAAI,EAAE,mBAAmB;aAC1B,CAAC,CAAC;QACL,CAAC;QAED,MAAM,IAAI,GAAG;YACX,GAAG,SAAS,CAAC,MAAM,qBAAqB;YACxC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,wBAAwB,CAAC,CAAC,WAAW,EAAE,CAAC;SACrF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,IAAI,CAAC,MAAM,EAAE;YACX,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE;YAC5C,IAAI;YACJ,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/claim.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+/** `--by` wins, then $EOS_SPEC_CLAIMED_BY, then the worktree basename. */
+export declare function resolveClaimedBy(explicit: string | undefined, repoRoot: string): string;
+export declare function registerClaim(program: Command): void;

package/dist/commands/claim.js

@@ -0,0 +1,46 @@
+import { basename } from 'node:path';
+import { activeClaims, addClaim, DEFAULT_TTL_MINUTES, readClaims, releaseClaim } from '../lib/claims.js';
+import { emit, getGlobalOptions } from '../lib/output.js';
+import { getRepoRoot } from '../lib/repo.js';
+import { withEventLog } from '../lib/with-event-log.js';
+/** `--by` wins, then $EOS_SPEC_CLAIMED_BY, then the worktree basename. */
+export function resolveClaimedBy(explicit, repoRoot) {
+    return explicit ?? process.env.EOS_SPEC_CLAIMED_BY ?? basename(repoRoot);
+}
+export function registerClaim(program) {
+    program
+        .command('claim <id>')
+        .description('Reserve a spec for this worktree (TTL lease shared across parallel worktrees); --release frees it.')
+        .option('--by <who>', 'Claimant label (defaults to $EOS_SPEC_CLAIMED_BY or the worktree basename)')
+        .option('--ttl <min>', 'Lease length in minutes', String(DEFAULT_TTL_MINUTES))
+        .option('--release', 'Release the claim instead of taking it', false)
+        .action(withEventLog('claim', async (options, cmd) => {
+        const command = cmd;
+        const global = getGlobalOptions(command);
+        const repoRoot = getRepoRoot(global.repoRoot);
+        // `claim <id>` is a positional command: commander supplies the id on the
+        // Command's args, not in the options object (withEventLog forwards the real
+        // Command as `cmd`).
+        const id = String(command.args[0] ?? '').toUpperCase();
+        if (options.release) {
+            releaseClaim(repoRoot, id);
+            const active = activeClaims(readClaims(repoRoot), Date.now());
+            emit(global, {
+                ok: true,
+                data: { released: id, active },
+                text: `claim: released ${id} (${active.length} active claim(s) remain)`,
+            });
+            return;
+        }
+        const by = resolveClaimedBy(options.by, repoRoot);
+        const ttlMinutes = Number.parseInt(String(options.ttl), 10) || DEFAULT_TTL_MINUTES;
+        const claim = addClaim(repoRoot, id, { by, ttlMinutes });
+        const active = activeClaims(readClaims(repoRoot), Date.now());
+        emit(global, {
+            ok: true,
+            data: { claim, active },
+            text: `claim: ${claim.id} reserved by ${claim.claimedBy} for ${claim.ttlMinutes}m (${active.length} active claim(s))`,
+        });
+    }));
+}
+//# sourceMappingURL=claim.js.map

package/dist/commands/claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.js","sourceRoot":"","sources":["../../src/commands/claim.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,mBAAmB,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACzG,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,0EAA0E;AAC1E,MAAM,UAAU,gBAAgB,CAAC,QAA4B,EAAE,QAAgB;IAC7E,OAAO,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO;SACJ,OAAO,CAAC,YAAY,CAAC;SACrB,WAAW,CAAC,oGAAoG,CAAC;SACjH,MAAM,CAAC,YAAY,EAAE,4EAA4E,CAAC;SAClG,MAAM,CAAC,aAAa,EAAE,yBAAyB,EAAE,MAAM,CAAC,mBAAmB,CAAC,CAAC;SAC7E,MAAM,CAAC,WAAW,EAAE,wCAAwC,EAAE,KAAK,CAAC;SACpE,MAAM,CACL,YAAY,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE;QAC3C,MAAM,OAAO,GAAG,GAAc,CAAC;QAC/B,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9C,yEAAyE;QACzE,4EAA4E;QAC5E,qBAAqB;QACrB,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAEvD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,YAAY,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YAC3B,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAC9D,IAAI,CAAC,MAAM,EAAE;gBACX,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE;gBAC9B,IAAI,EAAE,mBAAmB,EAAE,KAAK,MAAM,CAAC,MAAM,0BAA0B;aACxE,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QAClD,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,mBAAmB,CAAC;QACnF,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,EAAE;YACX,EAAE,EAAE,IAAI;YACR,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;YACvB,IAAI,EAAE,UAAU,KAAK,CAAC,EAAE,gBAAgB,KAAK,CAAC,SAAS,QAAQ,KAAK,CAAC,UAAU,MAAM,MAAM,CAAC,MAAM,mBAAmB;SACtH,CAAC,CAAC;IACL,CAAC,CAAC,CACH,CAAC;AACN,CAAC"}

package/dist/commands/complete.d.ts

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

package/dist/commands/complete.js

@@ -0,0 +1,138 @@
+import { archiveSpec } from '../lib/archive.js';
+import { evaluateCoherence } from '../lib/coherence.js';
+import { uiEvidenceGate } from '../lib/completion-gate.js';
+import { loadEnforcementAllowlist } from '../lib/enforcement-allowlist.js';
+import { runScript } from '../lib/exec.js';
+import { ErrorCode, emit, emitContinuing, getGlobalOptions } from '../lib/output.js';
+import { getRepoRoot } from '../lib/repo.js';
+import { findSpec } from '../lib/specs.js';
+export function registerComplete(program) {
+    program
+        .command('complete')
+        .description('Wrap scripts/audit/audit-spec-completion.js — verify and optionally update registry/tracking and archive a completed spec.')
+        .option('--spec <id>', 'Single spec id (e.g. PF-37)')
+        .option('--core <core>', 'Limit to one core')
+        .option('--all', 'All specs across all cores', false)
+        .option('--update-registry', 'Write back to specs/SPEC_STATUS_REGISTRY.md', false)
+        .option('--include-deferred', 'Include deferred items in audit', false)
+        .option('--archive', 'After audit passes, move spec/plan/tasks to specs/{core}/archive/', false)
+        .option('--strict', 'Fail when coherence warnings are present', false)
+        .option('--no-ui-gate', 'Skip the UI-evidence completion check (docshots + heal sign-off)')
+        .option('--signoff', 'Acknowledge the UI-evidence gate (equivalent to --no-ui-gate for this run)', false)
+        .action(async (options, cmd) => {
+        const global = getGlobalOptions(cmd);
+        const repoRoot = getRepoRoot(global.repoRoot);
+        // C1 inline UI-evidence gate: warn at completion time when a UI-bearing
+        // spec lacks docshots + a heal sign-off. Warn-first (never refuses) — the
+        // non-bypassable enforcement is the corpus invariant (spec:registry:check).
+        // commander maps `--no-ui-gate` to options.uiGate === false.
+        if (options.spec && options.uiGate !== false && !options.signoff) {
+            try {
+                const spec = findSpec(repoRoot, String(options.spec));
+                if (spec) {
+                    const verdict = uiEvidenceGate(spec);
+                    if (!verdict.ok) {
+                        const allow = loadEnforcementAllowlist(repoRoot);
+                        const blocked = allow.block.includes(spec.core);
+                        emitContinuing(global, `complete: ui-evidence ${blocked ? 'GATE' : 'warning'} — ${verdict.reason}`);
+                    }
+                }
+            }
+            catch {
+                // fail-open: a gate must never make `complete` unusable.
+            }
+        }
+        const args = ['node', 'scripts/audit/audit-spec-completion.js'];
+        if (options.spec)
+            args.push(`--spec=${options.spec}`);
+        if (options.core)
+            args.push(`--core=${options.core}`);
+        if (options.all)
+            args.push('--all');
+        if (options.updateRegistry)
+            args.push('--update-registry');
+        if (options.includeDeferred)
+            args.push('--include-deferred');
+        // F6: in JSON mode, ask the audit script for its machine-readable array so
+        // we can embed structured data instead of the raw stdout/stderr blob.
+        if (global.json)
+            args.push('--json');
+        emitContinuing(global, `complete: ${args.join(' ')}`);
+        const result = runScript(args, repoRoot);
+        const ok = result.exitCode === 0;
+        let archived = [];
+        let coherenceWarnings = [];
+        if (ok && options.spec) {
+            const core = String(options.spec).toUpperCase().split('-')[0]?.toLowerCase();
+            if (core) {
+                const coherence = evaluateCoherence(repoRoot, String(options.spec).toUpperCase(), core);
+                coherenceWarnings = coherence.warnings.map((w) => w.message);
+                if (coherenceWarnings.length > 0 && !global.json && !global.quiet) {
+                    emitContinuing(global, `complete: coherence warnings (${coherenceWarnings.length})`);
+                    for (const warning of coherenceWarnings.slice(0, 10)) {
+                        emitContinuing(global, `  - ${warning}`);
+                    }
+                }
+                if (options.strict && coherenceWarnings.length > 0) {
+                    emit(global, {
+                        ok: false,
+                        data: { coherenceWarnings },
+                        text: `complete: strict mode failed due to ${coherenceWarnings.length} coherence warning(s)`,
+                        exitCode: 1,
+                    });
+                }
+            }
+        }
+        if (ok && options.archive) {
+            if (!options.spec) {
+                emit(global, {
+                    ok: false,
+                    error: {
+                        code: ErrorCode.SCOPE_REQUIRED,
+                        message: 'complete: --archive requires --spec <id>; refusing to bulk-archive',
+                    },
+                    data: { reason: '--archive requires --spec' },
+                    text: 'complete: --archive requires --spec <id>; refusing to bulk-archive',
+                    exitCode: 2,
+                });
+            }
+            const archiveResult = archiveSpec(repoRoot, options.spec, global.json || global.quiet ? null : (m) => emitContinuing(global, m), global.config);
+            archived = archiveResult.moved;
+        }
+        // F6: when the caller asked for JSON, the audit subprocess emitted its
+        // machine-readable array on stdout; parse it and embed it as `audit`.
+        // Fail-open (mirrors the L36 ui-gate): a malformed/absent JSON payload must
+        // never make `complete` unusable — fall back to the raw stdout blob.
+        let audit = null;
+        if (global.json && ok) {
+            try {
+                audit = JSON.parse(result.stdout);
+            }
+            catch {
+                audit = null;
+            }
+        }
+        // On the JSON success path emit structured data only (the point of F6 —
+        // no raw stdout/stderr blob). Human mode or a JSON parse failure keeps the
+        // raw blob as a usable fallback.
+        const data = audit !== null
+            ? { exitCode: result.exitCode, archived, coherenceWarnings, audit }
+            : {
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                stderr: result.stderr,
+                archived,
+                coherenceWarnings,
+                audit,
+            };
+        emit(global, {
+            ok,
+            data,
+            text: ok
+                ? `complete: ${result.stdout.trim()}${coherenceWarnings.length ? `\nCoherence warnings: ${coherenceWarnings.length}` : ''}${archived.length ? `\nArchived ${archived.length} file(s) → specs/{core}/archive/` : ''}`
+                : `complete: failed (exit ${result.exitCode})\n${result.stderr || result.stdout}`,
+            exitCode: ok ? 0 : 1,
+        });
+    });
+}
+//# sourceMappingURL=complete.js.map

package/dist/commands/complete.js.map

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

package/dist/commands/conformance.d.ts

@@ -0,0 +1,23 @@
+import type { Command } from 'commander';
+/**
+ * The conformance pack the engine EXPORTS (epic #300, Wave-1 G5). A single
+ * `eos-spec conformance` runs the engine's own invariants in-process so a consumer
+ * adoption PR — and the npm-pack install smoke (scripts/conformance/pack-smoke.mjs,
+ * which runs THIS command from a clean tarball install) — has one green gate:
+ *  - both pipeline layouts (encore1 + builder) validate against the predicate registry
+ *  - each built pipeline materializes a sane stage from synthetic signals
+ *  - the typed AC model + the /pure fs-free helpers resolve and behave
+ *
+ * The golden-corpus parity, command-surface snapshot, and /pure purity gate run in
+ * CI as colocated vitest suites; this command is the runnable, post-install subset
+ * that proves the *published artifact* is sound (catches the DATA_DIR-wrong-root /
+ * missing-dist / broken-export classes a unit suite on source can't).
+ */
+type Check = {
+    name: string;
+    ok: boolean;
+    detail: string;
+};
+export declare function runConformanceChecks(): Check[];
+export declare function registerConformance(program: Command): void;
+export {};