@specverse/engines 6.21.2 → 6.27.10

package/dist/ai/analyse-runner.d.ts

@@ -52,6 +52,22 @@ export interface RunAnalyseOptions {
     caseName?: string;
     /** Loose case meta for the manifest (kind: 'analyse' is fixed). */
     caseMeta?: RunCaseEntry;
+    /**
+     * Phase B opt-in: use the skeleton-emitter + per-action micro-calls
+     * pipeline instead of the giant single analyse call. See plan:
+     * specverse-self/docs/plans/2026-05-04-ANALYSE-VIA-FAITHFUL-SKELETON-AND-MICROCALLS.md
+     *
+     * Default false (existing behaviour). When true:
+     *   - runPrepass produces facts (unchanged)
+     *   - emitFaithfulSkeleton turns facts into a faithful skeleton
+     *   - runActionMicrocalls fires parallel LLM calls per action stub
+     *   - assembleFinalSpec merges skeleton + filled bodies into main.specly
+     *   - skeleton.specly + skeleton-provenance.json + microcall-decisions.json
+     *     sidecars written alongside existing artifacts
+     */
+    useMicrocalls?: boolean;
+    /** Concurrency cap for per-action micro-calls (default 10). */
+    microcallConcurrency?: number;
 }
 export interface RunAnalyseResult {
     outputDir: string;

package/dist/ai/analyse-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyse-runner.d.ts","sourceRoot":"","sources":["../../src/ai/analyse-runner.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,EAGL,KAAK,WAAW,EAAE,KAAK,YAAY,EACpC,MAAM,gBAAgB,CAAC;AAiBxB,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,UAAU,EAAE,OAAO,GAAG,UAAU,CAAC;IACjC,aAAa,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,OAAO,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAqCD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6TnF"}
+{"version":3,"file":"analyse-runner.d.ts","sourceRoot":"","sources":["../../src/ai/analyse-runner.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,EAGL,KAAK,WAAW,EAAE,KAAK,YAAY,EACpC,MAAM,gBAAgB,CAAC;AAiBxB,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,UAAU,EAAE,OAAO,GAAG,UAAU,CAAC;IACjC,aAAa,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,OAAO,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAqCD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwnBnF"}

package/dist/ai/analyse-runner.js

@@ -22,9 +22,10 @@
  * artifacts. It writes manifest.json itself with what it knows; callers
  * can re-write it with additional fields after scoring.
  */
-import { writeFileSync, readFileSync, existsSync, rmSync, cpSync } from 'fs';
-import { join } from 'path';
+import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, cpSync, statSync, readdirSync } from 'fs';
+import { join, relative } from 'path';
 import { execSync, spawnSync } from 'child_process';
+import { createHash } from 'crypto';
 import { promptsDir, llmOutputDir, factsDir, specsDir, ensureSubdirs, writeStageSpec, writeProjectReadme, writeManifest, writeReadme, } from './run-paths.js';
 import { runPrompt, extractSpecAndManifest } from './prompt-runner.js';
 import { resolveModel, resolveProviderId } from './model-resolver.js';
@@ -87,6 +88,48 @@ export async function runAnalyse(opts) {
     const startedAt = new Date().toISOString();
     const t0 = Date.now();
     ensureSubdirs(opts.outputDir);
+    // Verify-stage recorder (#audit-trail-2026-05-03 plan, engines 6.22.x+).
+    // Captures every schema-validation pass + retry event + structural-check
+    // result at the moment they happen during the analyse pipeline.
+    const { InMemoryVerifyRecorder, categoriseValidationError } = await import('../audit/verify-recorder.js');
+    const { runAllChecks } = await import('../audit/verify-checks.js');
+    const verifyRecorder = new InMemoryVerifyRecorder();
+    // Wrap runValidate so every call records into the verify recorder. Also
+    // runs structural checks after a successful schema-validation pass.
+    // The js-yaml import is hoisted out of the function so it loads once
+    // (ESM project — `require()` is not available without createRequire).
+    const yamlModule = await import('js-yaml');
+    const recordedRunValidate = (specPath, kind = 'schema-validation') => {
+        const t = Date.now();
+        const r = runValidate(specPath);
+        const errorList = r.ok ? [] : r.errors.split('\n').filter((l) => l.trim());
+        verifyRecorder.recordPass({
+            kind,
+            ok: r.ok,
+            errorCount: errorList.length,
+            errors: errorList.slice(0, 50), // cap to keep sidecar bounded
+            durationMs: Date.now() - t,
+        });
+        // Structural checks run after a clean schema-validation pass. They
+        // surface SpecVerse-semantic invariant violations as human-review
+        // items without failing the validation gate.
+        if (r.ok && existsSync(specPath)) {
+            try {
+                const parsed = yamlModule.load(readFileSync(specPath, 'utf8'));
+                const checkResults = runAllChecks(parsed);
+                for (const cr of checkResults)
+                    verifyRecorder.recordStructuralCheck(cr);
+            }
+            catch (e) {
+                verifyRecorder.recordHumanReviewItem({
+                    severity: 'warning',
+                    kind: 'structural-checks-skipped',
+                    message: `Could not parse spec for structural checks: ${e?.message ?? e}`,
+                });
+            }
+        }
+        return r;
+    };
     // 1. Resolve facts content (if any). Two sources: --facts <path> (manual)
     // or runPrepass on sourceDir (--auto-facts). Manual wins if both passed.
     let factsContent = '';
@@ -97,9 +140,12 @@ export async function runAnalyse(opts) {
     // #27-C: pre-classified candidate-step timelines are surfaced
     // alongside method facts as a third structured-input stream.
     let candidateStepsContent = '';
+    // Hoisted so the microcall branch (Phase B) can build the skeleton.
+    let prepassFacts;
     if (opts.autoFacts && !opts.factsPath) {
         const { runPrepass, formatFactsAsMarkdown, formatMethodFactsAsMarkdown, formatCandidateMethodsAsMarkdown } = await import('./../analyse-prepass/index.js');
         const facts = await runPrepass(opts.sourceDir);
+        prepassFacts = facts;
         factsContent = formatFactsAsMarkdown(facts);
         methodFactsContent = formatMethodFactsAsMarkdown(facts.methodFactSheets);
         candidateStepsContent = formatCandidateMethodsAsMarkdown(facts.candidateMethods);
@@ -116,6 +162,33 @@ export async function runAnalyse(opts) {
             writeFileSync(join(factsDir(opts.outputDir), 'facts.json'), JSON.stringify(facts, null, 2));
         }
         catch { /* non-serializable; skip */ }
+        // Audit-trail sidecars (#audit-trail-2026-05-03 plan, engines 6.22.0+).
+        // These let `spv report run` regenerate the markdown report without
+        // heuristic re-parsing of facts.md / candidate-steps.md.
+        if (facts.auditDecisions) {
+            try {
+                const t1 = Date.now();
+                const stats = {
+                    schemaVersion: '1.0',
+                    extractedAt: new Date().toISOString(),
+                    sourceDir: opts.sourceDir,
+                    backend: facts.meta.backend,
+                    adaptersRun: facts.meta.adaptersRun,
+                    durationMs: facts.meta.durationMs,
+                    totalDurationMs: t1 - t0,
+                    ...facts.auditDecisions.stats,
+                };
+                writeFileSync(join(factsDir(opts.outputDir), 'extract-decisions.json'), JSON.stringify(facts.auditDecisions, null, 2));
+                writeFileSync(join(factsDir(opts.outputDir), 'extract-stats.json'), JSON.stringify(stats, null, 2));
+                // Source fingerprint — SHA256 of the input tree for reproducibility.
+                const fingerprint = await computeSourceFingerprint(opts.sourceDir);
+                writeFileSync(join(factsDir(opts.outputDir), 'source-fingerprint.json'), JSON.stringify(fingerprint, null, 2));
+            }
+            catch (e) {
+                // Sidecar writes are advisory — don't fail the run on serialization issues.
+                console.error(`[audit] sidecar emit failed: ${e?.message ?? e}`);
+            }
+        }
     }
     else if (opts.factsPath) {
         factsContent = readFileSync(opts.factsPath, 'utf8');
@@ -145,83 +218,233 @@ export async function runAnalyse(opts) {
         timeout: opts.timeoutMs ?? 15 * 60_000,
         sessionId: opts.sessionId,
     });
-    // 3. Analyse pass.
-    const draftResult = await runPrompt({
-        operation: 'analyse',
-        values: {
-            implementationPath: opts.sourceDir,
-            spec: '',
-            environment: 'development',
-        },
-        model,
-        timeoutMs: opts.timeoutMs ?? 15 * 60_000,
-        userPrefix,
-        onAssembled: ({ system, user }) => {
-            writeFileSync(join(promptsDir(opts.outputDir), 'analyse-system.txt'), system);
-            writeFileSync(join(promptsDir(opts.outputDir), 'analyse-user.txt'), user);
-        },
-    });
-    // analyse@9.6+ emits TWO code blocks: spec (components+deployments) +
-    // canonical capability-mapping manifest. extractSpecAndManifest pulls
-    // both; older single-block output still works (manifest is null then).
-    let { spec: draftSpec, manifest: draftManifest } = extractSpecAndManifest(draftResult.text);
+    // 3. Analyse pass — two paths:
+    //    (a) useMicrocalls=true (Phase B): skeleton + per-action micro-calls + manifest call
+    //    (b) default: one giant runPrompt call producing spec + manifest in one shot
+    let draftResult;
+    let draftSpec;
+    let draftManifest;
+    // Microcall state hoisted out of the if-block so the retry path
+    // (TODO #152 surgical retry) can re-fire failed microcalls instead
+    // of calling the giant analyse prompt.
+    let microcallState = null;
+    if (opts.useMicrocalls) {
+        if (!prepassFacts) {
+            throw new Error('useMicrocalls requires autoFacts (skeleton emitter consumes prepass facts)');
+        }
+        // Skeleton emitter (Phase A) — deterministic facts → faithful skeleton.
+        const { emitFaithfulSkeleton } = await import('./skeleton-emitter.js');
+        const { skeleton, provenance: skeletonProvenance } = emitFaithfulSkeleton(prepassFacts);
+        writeFileSync(join(specsDir(opts.outputDir), 'skeleton.specly'), skeleton);
+        writeFileSync(join(factsDir(opts.outputDir), 'skeleton-provenance.json'), JSON.stringify(skeletonProvenance, null, 2));
+        // Build candidateStepsByMethodKey from facts. Each method's timeline as
+        // markdown text the per-action prompt can consume directly.
+        const candidateStepsByMethodKey = new Map();
+        for (const cls of prepassFacts.candidateMethods ?? []) {
+            for (let mi = 0; mi < cls.methods.length; mi++) {
+                const m = cls.methods[mi];
+                const lines = m.candidates.map((c, i) => `${i + 1}. [${c.kind}] ${c.summary}`);
+                candidateStepsByMethodKey.set(`${cls.entityName}::${mi}`, lines.join('\n'));
+            }
+        }
+        // Build a manifest overview from the skeleton (top-level component
+        // names + a summary of detected entities).
+        const skeletonOverview = skeleton.split('\n').slice(0, 80).join('\n');
+        // Run the orchestrator.
+        const { runActionMicrocalls, assembleFinalSpec } = await import('./microcall-orchestrator.js');
+        const microcallResult = await runActionMicrocalls({
+            skeleton,
+            skeletonProvenance,
+            candidateStepsByMethodKey,
+            model,
+            // Default 5 (was 10) — empirically claude-cli rate-limits at >5 in
+            // parallel for sustained calls. Override via --microcall-concurrency
+            // when running against a higher-tier API key.
+            concurrencyCap: opts.microcallConcurrency ?? 5,
+            timeoutMsPerCall: 5 * 60_000,
+            manifestInputs: {
+                skeletonOverview,
+                importsList: '(imports list extraction TBD — stub)',
+                language: 'typescript',
+                frameworks: prepassFacts.meta?.adaptersRun?.join(', ') || 'none-detected',
+            },
+        });
+        // Forward-log: write microcall provenance sidecar.
+        writeFileSync(join(llmOutputDir(opts.outputDir), 'microcall-decisions.json'), JSON.stringify(microcallResult.provenance, null, 2));
+        // Save state for surgical retry.
+        microcallState = {
+            skeleton,
+            skeletonProvenance,
+            candidateStepsByMethodKey,
+            actionBodies: microcallResult.actionBodies,
+        };
+        // Assemble final spec + manifest.
+        draftSpec = assembleFinalSpec(skeleton, skeletonProvenance, microcallResult.actionBodies);
+        draftManifest = microcallResult.manifestYaml;
+        // Synthesize a draftResult equivalent for downstream code paths.
+        draftResult = {
+            text: draftSpec,
+            tokens: { input: null, output: null },
+            duration_ms: microcallResult.provenance.wallTimeMs,
+            system: '(microcall path — multiple system prompts)',
+            user: '(microcall path — multiple user prompts)',
+            providerId: opts.providerId ?? resolveProviderId(),
+            modelId: opts.modelId ?? 'default',
+        };
+    }
+    else {
+        // Existing one-shot path.
+        draftResult = await runPrompt({
+            operation: 'analyse',
+            values: {
+                implementationPath: opts.sourceDir,
+                spec: '',
+                environment: 'development',
+            },
+            model,
+            timeoutMs: opts.timeoutMs ?? 15 * 60_000,
+            userPrefix,
+            onAssembled: ({ system, user }) => {
+                writeFileSync(join(promptsDir(opts.outputDir), 'analyse-system.txt'), system);
+                writeFileSync(join(promptsDir(opts.outputDir), 'analyse-user.txt'), user);
+            },
+        });
+        const extracted = extractSpecAndManifest(draftResult.text);
+        draftSpec = extracted.spec;
+        draftManifest = extracted.manifest;
+    }
     const draftSpecPath = writeStageSpec(opts.outputDir, 'draft', draftSpec);
     if (draftManifest)
         writeManifestArtifact(opts.outputDir, draftManifest);
     writeFileSync(join(llmOutputDir(opts.outputDir), 'analyse.txt'), draftResult.text);
+    // Audit-trail attribution moved to a separate focused LLM call after
+    // final-validate (engines 6.22.4+, assets 1.13.1+). See plan:
+    // specverse-self/docs/plans/2026-05-03-PIPELINE-AUDIT-TRAIL-INSTRUMENTATION.md
+    // and TODO #47 for spec-call decomposition follow-up work.
     // 4. Validate draft; retry up to MAX_RETRIES times if invalid. Each retry
     // feeds the most recent validation error + the prior draft back to the LLM
     // so it can fix one defect at a time. Larger specs surface multiple subtle
     // YAML defects in succession (cal-com case, 2026-04-28); a single retry is
     // not enough.
     const MAX_RETRIES = 3;
-    let validateAfterDraft = runValidate(draftSpecPath);
+    let validateAfterDraft = recordedRunValidate(draftSpecPath);
     let draftRetried = false;
     if (!validateAfterDraft.ok) {
         writeFileSync(join(opts.outputDir, 'validate-error-1.txt'), validateAfterDraft.errors);
-        let priorDraft = draftSpec;
-        let priorError = validateAfterDraft.errors;
-        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
-            try {
-                const retryResult = await runPrompt({
-                    operation: 'analyse',
-                    values: {
-                        implementationPath: opts.sourceDir,
-                        spec: '',
-                        environment: 'development',
-                    },
+        // Microcalls path → surgical retry: parse error paths, re-fire only
+        // affected microcalls. Skeleton-structural errors are recorded as
+        // humanReviewItems and NOT retried (those are code bugs, not LLM-fixable).
+        if (opts.useMicrocalls && microcallState) {
+            const { classifyValidationErrors, runSurgicalRetry, assembleFinalSpec } = await import('./microcall-orchestrator.js');
+            let priorError = validateAfterDraft.errors;
+            let currentBodies = microcallState.actionBodies;
+            for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+                const classification = classifyValidationErrors(priorError, microcallState.skeletonProvenance);
+                for (const e of classification.structuralErrors) {
+                    verifyRecorder.recordHumanReviewItem({
+                        severity: 'error',
+                        kind: 'skeleton-structural-error',
+                        message: e,
+                    });
+                }
+                if (classification.actionPathErrors.size === 0) {
+                    // No action-stub errors — only structural. LLM retry can't fix
+                    // those; fail validation cleanly.
+                    break;
+                }
+                const retryStart = Date.now();
+                const surgical = await runSurgicalRetry({
+                    skeleton: microcallState.skeleton,
+                    skeletonProvenance: microcallState.skeletonProvenance,
+                    candidateStepsByMethodKey: microcallState.candidateStepsByMethodKey,
+                    prior: { actionBodies: currentBodies, classification },
                     model,
-                    timeoutMs: opts.timeoutMs ?? 15 * 60_000,
-                    userPrefix: `Your previous draft (attempt ${attempt}) failed \`spv validate\` with the following error:\n\n` +
-                        '```\n' + priorError + '\n```\n\n' +
-                        'Your previous output:\n```specly\n' + priorDraft + '\n```\n\n' +
-                        'Fix the error and emit a corrected spec. Keep everything else identical.\n\n',
-                    onAssembled: ({ system, user }) => {
-                        writeFileSync(join(promptsDir(opts.outputDir), `analyse-retry-${attempt}-system.txt`), system);
-                        writeFileSync(join(promptsDir(opts.outputDir), `analyse-retry-${attempt}-user.txt`), user);
-                    },
+                    concurrencyCap: opts.microcallConcurrency ?? 5,
+                    timeoutMsPerCall: 5 * 60_000,
                 });
-                const { spec: retrySpec, manifest: retryManifest } = extractSpecAndManifest(retryResult.text);
+                currentBodies = surgical.actionBodies;
+                const retrySpec = assembleFinalSpec(microcallState.skeleton, microcallState.skeletonProvenance, currentBodies);
                 const retrySpecPath = join(specsDir(opts.outputDir), `draft-retry-${attempt}.specly`);
                 writeFileSync(retrySpecPath, retrySpec);
-                writeFileSync(join(llmOutputDir(opts.outputDir), `analyse-retry-${attempt}.txt`), retryResult.text);
-                const validateAfterRetry = runValidate(retrySpecPath);
+                const validateAfterRetry = recordedRunValidate(retrySpecPath);
                 writeFileSync(join(opts.outputDir, `validate-after-retry-${attempt}.txt`), validateAfterRetry.ok ? 'OK' : validateAfterRetry.errors);
+                verifyRecorder.recordRetry({
+                    trigger: attempt === 1 ? 'first-validate-failed' : `retry-${attempt - 1}-failed`,
+                    errorCount: priorError.split('\n').filter((l) => l.trim()).length,
+                    errorCategories: categoriseValidationError(priorError),
+                    tokenCountIn: undefined,
+                    tokenCountOut: undefined,
+                    latencyMs: Date.now() - retryStart,
+                    itemsChangedSummary: `surgical retry: ${surgical.retriedStubs} stub(s) re-fired (${classification.structuralErrors.length} structural error(s) skipped)` +
+                        (validateAfterRetry.ok
+                            ? `, resolved ${priorError.split('\n').length} error line(s)`
+                            : `, ${validateAfterRetry.errors.split('\n').length} error line(s) remain`),
+                    ok: validateAfterRetry.ok,
+                });
                 if (validateAfterRetry.ok) {
                     draftSpec = retrySpec;
                     writeStageSpec(opts.outputDir, 'draft', retrySpec);
-                    if (retryManifest)
-                        writeManifestArtifact(opts.outputDir, retryManifest);
                     validateAfterDraft = validateAfterRetry;
                     draftRetried = true;
                     break;
                 }
-                // Not OK — set up for next retry attempt with the new error + new draft.
-                priorDraft = retrySpec;
                 priorError = validateAfterRetry.errors;
             }
-            catch { /* retry failed; continue with original draft */
-                break;
+        }
+        else {
+            // Legacy giant-call path retry — full spec re-emission via analyse prompt.
+            let priorDraft = draftSpec;
+            let priorError = validateAfterDraft.errors;
+            for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+                try {
+                    const retryResult = await runPrompt({
+                        operation: 'analyse',
+                        values: {
+                            implementationPath: opts.sourceDir,
+                            spec: '',
+                            environment: 'development',
+                        },
+                        model,
+                        timeoutMs: opts.timeoutMs ?? 15 * 60_000,
+                        userPrefix: `Your previous draft (attempt ${attempt}) failed \`spv validate\` with the following error:\n\n` +
+                            '```\n' + priorError + '\n```\n\n' +
+                            'Your previous output:\n```specly\n' + priorDraft + '\n```\n\n' +
+                            'Fix the error and emit a corrected spec. Keep everything else identical.\n\n',
+                        onAssembled: ({ system, user }) => {
+                            writeFileSync(join(promptsDir(opts.outputDir), `analyse-retry-${attempt}-system.txt`), system);
+                            writeFileSync(join(promptsDir(opts.outputDir), `analyse-retry-${attempt}-user.txt`), user);
+                        },
+                    });
+                    const { spec: retrySpec, manifest: retryManifest } = extractSpecAndManifest(retryResult.text);
+                    const retrySpecPath = join(specsDir(opts.outputDir), `draft-retry-${attempt}.specly`);
+                    writeFileSync(retrySpecPath, retrySpec);
+                    writeFileSync(join(llmOutputDir(opts.outputDir), `analyse-retry-${attempt}.txt`), retryResult.text);
+                    const validateAfterRetry = recordedRunValidate(retrySpecPath);
+                    writeFileSync(join(opts.outputDir, `validate-after-retry-${attempt}.txt`), validateAfterRetry.ok ? 'OK' : validateAfterRetry.errors);
+                    verifyRecorder.recordRetry({
+                        trigger: attempt === 1 ? 'first-validate-failed' : `retry-${attempt - 1}-failed`,
+                        errorCount: priorError.split('\n').filter((l) => l.trim()).length,
+                        errorCategories: categoriseValidationError(priorError),
+                        itemsChangedSummary: validateAfterRetry.ok
+                            ? `retry-${attempt} resolved ${priorError.split('\n').length} error line(s)`
+                            : `retry-${attempt} still has ${validateAfterRetry.errors.split('\n').length} error line(s)`,
+                        ok: validateAfterRetry.ok,
+                    });
+                    if (validateAfterRetry.ok) {
+                        draftSpec = retrySpec;
+                        writeStageSpec(opts.outputDir, 'draft', retrySpec);
+                        if (retryManifest)
+                            writeManifestArtifact(opts.outputDir, retryManifest);
+                        validateAfterDraft = validateAfterRetry;
+                        draftRetried = true;
+                        break;
+                    }
+                    priorDraft = retrySpec;
+                    priorError = validateAfterRetry.errors;
+                }
+                catch {
+                    break;
+                }
             }
         }
     }
@@ -338,8 +561,63 @@ export async function runAnalyse(opts) {
     }
     // 6. Final validation.
     const finalSpecPath = join(specsDir(opts.outputDir), 'main.specly');
-    const validateFinal = runValidate(finalSpecPath);
+    const validateFinal = recordedRunValidate(finalSpecPath);
     writeFileSync(join(opts.outputDir, 'validate.txt'), validateFinal.ok ? 'OK' : validateFinal.errors);
+    // 6.5. Audit-trail attribution call (focused, small, post-validate).
+    // Runs only when:
+    //   (a) candidate-step timelines were generated (we're auto-facts mode), AND
+    //   (b) final spec validated cleanly (no point attributing an invalid spec)
+    // Failure is non-fatal — falls back to no-attribution and logs a human
+    // review item.
+    if (validateFinal.ok && candidateStepsContent) {
+        try {
+            const finalSpec = readFileSync(finalSpecPath, 'utf8');
+            const attributeResult = await runPrompt({
+                operation: 'attribute',
+                values: {
+                    spec: finalSpec,
+                    candidateSteps: candidateStepsContent,
+                },
+                model,
+                timeoutMs: 5 * 60_000, // 5 minutes — attribution is a small focused call
+                onAssembled: ({ system, user }) => {
+                    writeFileSync(join(promptsDir(opts.outputDir), 'attribute-system.txt'), system);
+                    writeFileSync(join(promptsDir(opts.outputDir), 'attribute-user.txt'), user);
+                },
+            });
+            writeFileSync(join(llmOutputDir(opts.outputDir), 'attribute.txt'), attributeResult.text);
+            const attribution = await extractAttributionBlock(attributeResult.text);
+            if (attribution) {
+                writeFileSync(join(llmOutputDir(opts.outputDir), 'analyse-attribution.json'), JSON.stringify({ schemaVersion: '1.0', attribution: attribution.attribution ?? [] }, null, 2));
+                writeFileSync(join(llmOutputDir(opts.outputDir), 'analyse-decisions.json'), JSON.stringify({ schemaVersion: '1.0', elidedWalkerMethods: attribution.elidedWalkerMethods ?? [] }, null, 2));
+            }
+            else {
+                verifyRecorder.recordHumanReviewItem({
+                    severity: 'warning',
+                    kind: 'attribute-block-missing',
+                    message: 'Attribute LLM call returned response without AUDIT-ATTRIBUTION block; report assembler falls back to name-similarity heuristic.',
+                });
+            }
+        }
+        catch (e) {
+            verifyRecorder.recordHumanReviewItem({
+                severity: 'warning',
+                kind: 'attribute-call-failed',
+                message: `Attribute LLM call failed: ${e?.message ?? e}. Report assembler falls back to heuristic.`,
+            });
+        }
+    }
+    // Drain verify recorder into sidecars.
+    try {
+        const verifyDir = join(opts.outputDir, 'verify');
+        if (!existsSync(verifyDir))
+            mkdirSync(verifyDir, { recursive: true });
+        writeFileSync(join(verifyDir, 'invariants.json'), JSON.stringify(verifyRecorder.buildInvariants(), null, 2));
+        writeFileSync(join(verifyDir, 'retries.json'), JSON.stringify(verifyRecorder.buildRetries(), null, 2));
+    }
+    catch (e) {
+        console.error(`[audit] verify sidecar emit failed: ${e?.message ?? e}`);
+    }
     // 7. Optional realize.
     let realize = null;
     if (opts.realize && validateFinal.ok) {
@@ -396,4 +674,90 @@ export async function runAnalyse(opts) {
         validateAfterDraftOk: validateAfterDraft.ok,
     };
 }
+/**
+ * Compute SHA256 fingerprint of a source tree for reproducibility records.
+ * Skips node_modules, dist, .git, and any path containing those segments.
+ */
+async function computeSourceFingerprint(rootPath) {
+    const skipDirs = new Set(['node_modules', 'dist', '.git', '.next', '.turbo', '.cache', '.specverse']);
+    const files = [];
+    let totalBytes = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true }).map((e) => ({
+                name: e.name,
+                isDir: e.isDirectory(),
+            }));
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of entries) {
+            if (skipDirs.has(e.name))
+                continue;
+            const full = join(dir, e.name);
+            if (e.isDir) {
+                walk(full);
+            }
+            else {
+                try {
+                    const st = statSync(full);
+                    if (!st.isFile())
+                        continue;
+                    const data = readFileSync(full);
+                    totalBytes += data.length;
+                    files.push({
+                        rel: relative(rootPath, full),
+                        bytes: data.length,
+                        hash: createHash('sha256').update(data).digest('hex'),
+                    });
+                }
+                catch { /* unreadable file — skip */ }
+            }
+        }
+    };
+    walk(rootPath);
+    // Combine per-file hashes into a single tree hash (order-stable via sort).
+    files.sort((a, b) => a.rel.localeCompare(b.rel));
+    const treeHash = createHash('sha256');
+    for (const f of files) {
+        treeHash.update(f.rel).update('\0').update(f.hash).update('\0');
+    }
+    return {
+        schemaVersion: '1.0',
+        rootPath,
+        sha256: treeHash.digest('hex'),
+        fileCount: files.length,
+        byteCount: totalBytes,
+        scannedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Extract the AUDIT-ATTRIBUTION YAML block from a v9.17+ analyse LLM
+ * response. The block follows the spec/manifest blocks and is keyed by
+ * a sentinel comment on its first line. Returns null when not present
+ * (older prompts, or LLM omitted the block).
+ */
+async function extractAttributionBlock(text) {
+    // Match a fenced yaml block that begins with the AUDIT-ATTRIBUTION sentinel comment.
+    const re = /```ya?ml\s*\n#\s*AUDIT-ATTRIBUTION\s*\n([\s\S]*?)```/i;
+    const m = text.match(re);
+    if (!m)
+        return null;
+    const body = m[1];
+    if (!body)
+        return null;
+    try {
+        const yaml = await import('js-yaml');
+        const parsed = yaml.load(body);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=analyse-runner.js.map