@planu/cli 5.0.0 → 5.1.1

package/CHANGELOG.md

@@ -1,3 +1,51 @@
+## [5.1.1] - 2026-08-04
+
+### Bug Fixes
+- fix(release-harness): resolve published artifact from staged repack when publish has no tarball argv
+- fix(release): stop CLI-guard stdout pollution, npm view array probe, and tarball-path publish leak
+
+
+## [5.1.0] - 2026-08-04
+
+### Features
+- feat(lifecycle): automate done evidence pipeline end to end
+
+### Bug Fixes
+- fix(update-status): make typed failure explicit at dod-gates catch sites
+- fix(deps): patch hono, fast-uri, ip-address, and undici advisories via overrides
+- fix(evidence-gates): derive contract example kinds from filenames
+- fix(reverse-engineer): share walk-ignore list and add fast release-gate test lane
+- fix(challenge): suppress ungrounded concurrency boilerplate in challenge_spec
+- fix(update-status): report per-spec failure reasons in batch results
+- fix(create-spec): guarantee spec.md write before reporting persisted
+- fix(create-spec): release idempotency claim when create_spec fails before commit
+- fix(release): accept npm 12 pack metadata
+- fix(deps): patch transitive security advisories
+- fix(privacy): redact minimality policy locators
+- fix(lifecycle): route review evidence by target
+- fix(readiness): unify canonical validation evidence
+
+### Chores
+- chore(pnpm): disable modules purge confirmation for non-TTY automation
+- chore(planu): session checkpoint before release
+- chore(planu): close SPEC-1350 lifecycle state
+- chore(planu): hand off freshness blocker
+- chore(planu): checkpoint release handoff
+- chore(planu): preserve native engine review state
+- chore(planu): persist delayed challenge evidence
+- chore(planu): recover delayed audit specs
+- chore(planu): capture lifecycle dogfood failures
+- chore(planu): persist release remediation handoffs
+- chore(planu): approve final release blockers
+- chore(planu): start dependency security remediation
+- chore(planu): approve final security remediation
+- chore(planu): checkpoint final release remediations
+- chore(planu): start lifecycle routing implementation
+- chore(planu): approve lifecycle routing remediation
+- chore(planu): checkpoint release remediation specs
+- chore(planu): track v5 release dogfood regressions
+
+
 ## [5.0.0] - 2026-07-31
 
 ### Breaking Changes
@@ -4508,4 +4556,4 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 - Mermaid diagram generation (architecture, sequence, state machine, ER, data flow)
 - Multi-language i18n (EN/ES/PT) for generated specs
 - Clean Architecture (hexagonal) — engine, tools, storage, types layers
-- 10,857 tests with ≥95% coverage
+- 10,857 tests with ≥95% coverage

package/dist/cli/commands/spec.js

@@ -30,13 +30,14 @@ function printSpecSubcommandHelp() {
         `  ${'list'.padEnd(10)} ${dim('List specs [--status draft|approved|done...]')}`,
         `  ${'show'.padEnd(10)} ${dim('Show spec details (SPEC-NNN)')}`,
         `  ${'status'.padEnd(10)} ${dim('Update spec status (SPEC-NNN <status>)')}`,
+        `  ${''.padEnd(10)} ${dim('Batch targets: draft|review|approved|implementing|discarded')}`,
         `  ${'validate'.padEnd(10)} ${dim('Validate a spec against its codebase')}`,
         '',
         cyan('Examples:'),
         `  planu spec create "Add login flow"`,
         `  planu spec list --status approved`,
         `  planu spec show SPEC-001`,
-        `  planu spec status SPEC-001 done`,
+        `  planu spec status SPEC-001 done --implementation-review-digest sha256:<64-hex>`,
         `  planu spec validate SPEC-001`,
     ];
     process.stdout.write(lines.join('\n') + '\n');
@@ -207,6 +208,7 @@ async function runShow(args, flags) {
 // ---------------------------------------------------------------------------
 // Subcommand: spec status
 // ---------------------------------------------------------------------------
+// eslint-disable-next-line complexity -- batch done requires an explicit pre-resolution fail-closed branch
 async function runStatus(args, flags) {
     const { positionals, values } = parseArgs({
         args,
@@ -215,6 +217,7 @@ async function runStatus(args, flags) {
             notes: { type: 'string', short: 'n' },
             batch: { type: 'boolean' },
             set: { type: 'string', short: 's' },
+            'implementation-review-digest': { type: 'string' },
         },
         strict: false,
         allowPositionals: true,
@@ -232,6 +235,11 @@ async function runStatus(args, flags) {
         process.exitCode = 1;
         return;
     }
+    if (batch && status === 'done') {
+        process.stderr.write(`${red('BATCH_DONE_UNSUPPORTED:')} Close specs individually with update_status(done) and full implementation review evidence.\n`);
+        process.exitCode = 1;
+        return;
+    }
     const projectId = values['project-id'] ?? detectProjectId();
     if (batch) {
         const result = await handleUpdateStatusBatch({
@@ -253,6 +261,7 @@ async function runStatus(args, flags) {
         projectId,
         status: status,
         reviewNotes: values.notes ?? undefined,
+        implementationReviewDigest: values['implementation-review-digest'] ?? undefined,
     });
     if (result.isError) {
         process.stderr.write(`${red(formatToolResult(result, flags))}\n`);

package/dist/core/spec-validator.js

@@ -6,6 +6,8 @@ import { readFile } from 'node:fs/promises';
 import { checkSpecReadiness } from '../engine/readiness-checker.js';
 import { scoreSpecQuality } from '../engine/spec-quality-scorer.js';
 import { parseFrontmatter, stripFrontmatter } from '../engine/frontmatter-parser.js';
+import { extractNormalizedAcceptanceCriteria } from '../engine/spec-format/acceptance-criteria.js';
+import { parseFrontmatterScenarios } from '../engine/validator/spec-compliance-runner.js';
 // ── Required frontmatter fields ──────────────────────────────────────────────
 const REQUIRED_FRONTMATTER_FIELDS = ['id', 'title', 'status', 'type', 'target', 'scope'];
 // ── Required body sections (SPEC-785 aligned with lean-spec-generator output) ─
@@ -133,6 +135,20 @@ function mapQualityToValidation(dimensions) {
     }
     return warnings;
 }
+function countCanonicalBddScenarios(raw) {
+    const criteria = extractNormalizedAcceptanceCriteria(raw, { allowLegacyBodyFallback: false });
+    const bodyCriteria = criteria.filter((criterion) => criterion.source === 'body');
+    const bddCandidates = bodyCriteria.length > 0
+        ? bodyCriteria.map((criterion) => criterion.text)
+        : parseFrontmatterScenarios(raw).map((scenario) => scenario.steps?.map((step) => `${step.keyword} ${step.text}`).join(' ') ??
+            scenario.title);
+    return {
+        criteriaCount: criteria.length,
+        bddScenarioCount: bddCandidates.filter((criterion) => /\b(?:given|dado)\b/i.test(criterion) &&
+            /\b(?:when|cuando)\b/i.test(criterion) &&
+            /\b(?:then|entonces)\b/i.test(criterion)).length,
+    };
+}
 // ── Public API ───────────────────────────────────────────────────────────────
 /**
  * Validate a spec's format against the unified spec.md schema (SPEC-630).
@@ -168,22 +184,16 @@ export async function validateSpecFormat(spec, opts) {
     allWarnings.push(...unifiedResult.warnings);
     // ── 4. Readiness check ───────────────────────────────────────────────────
     let readinessScore = 0;
-    let bddScenarioCount = 0;
-    let criteriaCount = 0;
+    let readinessReport;
+    // The canonical metrics are independent from the readiness checker. Keep
+    // them truthful even when that best-effort checker throws.
+    const { criteriaCount, bddScenarioCount } = countCanonicalBddScenarios(raw);
     try {
         // Cast to Spec since checkSpecReadiness needs the full type but only reads
         // the fields available on the Pick type we receive.
-        const report = await checkSpecReadiness(spec, readinessMode);
-        readinessScore = report.score;
-        // Count scenarios from frontmatter block
-        bddScenarioCount = (raw.match(/^\s+-\s+title:/gm) ?? []).length;
-        // Count criteria lines (checkbox or GIVEN/WHEN/THEN)
-        const bodyLines = body.split('\n');
-        criteriaCount = bodyLines.filter((l) => /^- \[[ x]\]/i.test(l.trim()) || /^- .*\bgiven\b.*\bwhen\b.*\bthen\b/i.test(l.trim())).length;
-        if (criteriaCount === 0) {
-            criteriaCount = bddScenarioCount;
-        }
-        const mapped = mapReadinessToValidation(report.issues.blockers, report.issues.warnings);
+        readinessReport = await checkSpecReadiness(spec, readinessMode);
+        readinessScore = readinessReport.score;
+        const mapped = mapReadinessToValidation(readinessReport.issues.blockers, readinessReport.issues.warnings);
         allErrors.push(...mapped.errors);
         allWarnings.push(...mapped.warnings);
     }
@@ -197,11 +207,12 @@ export async function validateSpecFormat(spec, opts) {
         return { valid, errors: allErrors, warnings: allWarnings };
     }
     // ── 5. Quality scoring ───────────────────────────────────────────────────
-    let qualityScore = 0;
-    let qualityGrade = 'F';
+    let qualityScore;
+    let qualityGrade;
+    let qualityReport;
     if (!skipQuality) {
         try {
-            const qualityReport = await scoreSpecQuality(spec);
+            qualityReport = await scoreSpecQuality(spec);
             qualityScore = qualityReport.score.total;
             qualityGrade = qualityReport.score.grade;
             const qualityWarnings = mapQualityToValidation(qualityReport.dimensions);
@@ -226,11 +237,14 @@ export async function validateSpecFormat(spec, opts) {
         warnings: allWarnings,
         metrics: {
             readinessScore,
-            qualityScore,
-            qualityGrade,
             bddScenarioCount,
             criteriaCount,
+            ...(qualityScore === undefined || qualityGrade === undefined
+                ? {}
+                : { qualityScore, qualityGrade }),
         },
+        readinessReport,
+        qualityReport,
     };
 }
 //# sourceMappingURL=spec-validator.js.map

package/dist/engine/evidence-gates/artifact-reader.d.ts

@@ -15,6 +15,8 @@ export declare function traceabilityRowHasCurrentCommandEvidence(row: Traceabili
     projectId: string;
     projectPath: string;
 }): boolean;
+/** SPEC-1356: exported so evidence-autofill (and other producers) target the same path convention. */
+export declare function handoffEvidencePath(projectId: string, specId: string, filename: string): string;
 export declare function readEvidenceArtifacts(args: {
     spec: Spec;
     projectId: string;

package/dist/engine/evidence-gates/artifact-reader.js

@@ -244,7 +244,58 @@ const ARTIFACT_HINTS = {
 function artifactHint(label) {
     return ARTIFACT_HINTS[label] ?? '';
 }
-function handoffEvidencePath(projectId, specId, filename) {
+/**
+ * SPEC-1356 / AC5: compact JSON literal per artifact kind, appended verbatim to
+ * schema-validation errors so a retrying caller sees the exact expected shape
+ * instead of re-deriving it from prose.
+ */
+const ARTIFACT_EXAMPLES = {
+    'Discovery evidence': JSON.stringify({
+        version: 1,
+        rules: ['Rule text'],
+        examples: [{ rule: 'Rule text', example: 'Example text' }],
+        openQuestions: [{ question: 'Open question?', status: 'open' }],
+        outOfScope: ['Not in scope item'],
+        glossary: [{ term: 'Term', meaning: 'Meaning' }],
+    }),
+    'Task plan evidence': JSON.stringify({
+        version: 1,
+        tasks: [{ id: 'T1', title: 'Task title', acceptanceCriteria: ['AC1'], status: 'pending' }],
+    }),
+    'Traceability matrix evidence': JSON.stringify({
+        version: 1,
+        rows: [
+            {
+                acceptanceCriterion: 'AC text',
+                testEvidence: ['tests/example.test.ts'],
+                changedFiles: ['src/example.ts'],
+                validationEvidence: 'validate passed with score 100',
+                reviewerEvidence: 'planu-implementation-reviewer approved',
+            },
+        ],
+    }),
+    // Contract kinds are derived from the artifact filenames so no
+    // configurable technology literal is hardcoded here (audit:hardcodes).
+    ...Object.fromEntries([
+        'contract-validation-api.json',
+        'contract-validation-graphql.json',
+        'contract-validation-event.json',
+        'contract-validation-ui.json',
+        'contract-validation-mcp.json',
+    ].map((label) => [
+        label,
+        JSON.stringify({
+            version: 1,
+            kind: label.slice('contract-validation-'.length, -'.json'.length),
+            passed: true,
+        }),
+    ])),
+};
+function artifactExample(label) {
+    return ARTIFACT_EXAMPLES[label] ?? '';
+}
+/** SPEC-1356: exported so evidence-autofill (and other producers) target the same path convention. */
+export function handoffEvidencePath(projectId, specId, filename) {
     return join(projectDataDir(projectId), 'handoffs', specId, filename);
 }
 async function readUnknown(paths) {
@@ -273,7 +324,13 @@ async function readOptional(args) {
         }
         const parsed = args.schema.safeParse(found.value);
         if (!parsed.success) {
-            args.invalidArtifacts.push(`${args.label} is invalid at ${found.path}: ${parsed.error.issues.map((issue) => issue.message).join('; ')} ${artifactHint(args.label)}`.trim());
+            // SPEC-1356 / AC5: surface every Zod issue (field path + message), not just the
+            // first one, so a single retry can fix every constraint violation at once.
+            const allIssues = parsed.error.issues
+                .map((issue) => `${issue.path.length > 0 ? issue.path.join('.') : '(root)'}: ${issue.message}`)
+                .join('; ');
+            const example = artifactExample(args.label);
+            args.invalidArtifacts.push(`${args.label} is invalid at ${found.path}: ${allIssues} ${artifactHint(args.label)}${example ? ` Expected shape example: ${example}` : ''}`.trim());
             return undefined;
         }
         return parsed.data;

package/dist/engine/evidence-gates/evidence-autofill.d.ts

@@ -0,0 +1,10 @@
+import type { AutofillTraceabilityMatrixArgs, AutofillTraceabilityMatrixResult } from '../../types/evidence-autofill.js';
+/**
+ * Generate `traceability-matrix.json` in the handoff evidence store when it does
+ * not already exist. Never overwrites an existing file — if one is present this
+ * is a no-op that reports `already-exists`. Tolerates every failure by returning
+ * a typed non-throwing result; callers must never let this crash a lifecycle
+ * transition.
+ */
+export declare function autofillTraceabilityMatrix(args: AutofillTraceabilityMatrixArgs): Promise<AutofillTraceabilityMatrixResult>;
+//# sourceMappingURL=evidence-autofill.d.ts.map

package/dist/engine/evidence-gates/evidence-autofill.js

@@ -0,0 +1,148 @@
+// engine/evidence-gates/evidence-autofill.ts — SPEC-1356: automated lifecycle evidence pipeline
+//
+// Generates traceability-matrix.json in the handoff evidence store when it is
+// missing, so a `done` transition never fails purely because nobody hand-wrote
+// the traceability artifact.
+//
+// ORDERING CAVEAT (documented per SPEC-1356 T-A3): writing traceability-matrix.json
+// *after* `validate` has already computed and bound durable validation receipts
+// would make those bindings stale relative to the newly-written evidence — the
+// receipt would be certifying a repository state that does not include this file.
+// This module does NOT attempt to re-run or re-bind validation. Instead, callers
+// (see `src/tools/update-status/index.ts`) MUST treat a write from this module as
+// "evidence created, not yet bound": when autofill actually writes the file, the
+// caller must block the `done` transition with a message telling the operator to
+// re-run `validate` once so the freshly-created evidence gets bound, then retry
+// `done`. This is the simpler, safe choice given SPEC-1356 could not fully verify
+// that skipping straight through to the done gates after autofill would keep
+// receipt bindings correct in every code path (reconciliation, forced bypass,
+// legacy harnesses, etc.).
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { extractAcceptanceCriteriaTexts } from '../spec-format/acceptance-criteria.js';
+import { parseFrontmatterScenarios } from '../validator/spec-compliance-runner.js';
+import { extractCanonicalFileOwnership } from '../handoff-packager.js';
+import { handoffEvidencePath } from './artifact-reader.js';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+import { ValidationReportV1Schema } from '../handoff-artifacts/schemas.js';
+import { projectDataDir } from '../../storage/base-store.js';
+import { readFile } from 'node:fs/promises';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+const execFileAsync = promisify(execFile);
+const defaultExec = async (command, args, options) => {
+    const { stdout } = await execFileAsync(command, args, { cwd: options.cwd, encoding: 'utf-8' });
+    return stdout;
+};
+/** Best-effort `git diff --name-only <mergeBase>...HEAD`; never throws. */
+async function computeChangedFilesFromGit(projectPath, exec, baseBranch) {
+    try {
+        const mergeBaseOut = await exec('git', ['merge-base', 'HEAD', baseBranch], {
+            cwd: projectPath,
+        });
+        const mergeBase = mergeBaseOut.trim();
+        if (!mergeBase) {
+            return [];
+        }
+        const diffOut = await exec('git', ['diff', '--name-only', `${mergeBase}...HEAD`], {
+            cwd: projectPath,
+        });
+        return diffOut
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
+    catch (error) {
+        /* reliability-optional: EVIDENCE_AUTOFILL_GIT_DIFF — falls back to ## Files ownership */
+        reportClassifiedDegradation('EVIDENCE_AUTOFILL_GIT_DIFF', error);
+        return [];
+    }
+}
+function filterExistingRepoFiles(projectPath, paths) {
+    return paths.filter((path) => {
+        if (isAbsolute(path)) {
+            return false;
+        }
+        try {
+            return existsSync(resolve(projectPath, path));
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Best-effort read + sha256 summary of the persisted validation report, for prose evidence. */
+async function readValidationReportSummary(projectId, specId) {
+    const reportPath = join(projectDataDir(projectId), 'handoffs', specId, 'validation-report.json');
+    try {
+        const raw = await readFile(reportPath, 'utf-8');
+        const parsed = ValidationReportV1Schema.safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+            return {};
+        }
+        const { score, reviewer } = parsed.data;
+        return {
+            validationEvidence: `Validated by handoffs/${specId}/validation-report.json (score=${score ?? 'n/a'}).`,
+            reviewerEvidence: `Reviewed by ${reviewer.agent} (${reviewer.kind}), verdict=${reviewer.verdict}.`,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Generate `traceability-matrix.json` in the handoff evidence store when it does
+ * not already exist. Never overwrites an existing file — if one is present this
+ * is a no-op that reports `already-exists`. Tolerates every failure by returning
+ * a typed non-throwing result; callers must never let this crash a lifecycle
+ * transition.
+ */
+export async function autofillTraceabilityMatrix(args) {
+    const targetPath = handoffEvidencePath(args.projectId, args.specId, 'traceability-matrix.json');
+    try {
+        if (existsSync(targetPath)) {
+            return { written: false, reason: 'already-exists' };
+        }
+        const criteria = extractAcceptanceCriteriaTexts(args.specBody);
+        if (criteria.length === 0) {
+            return { written: false, reason: 'no-criteria' };
+        }
+        const scenarios = parseFrontmatterScenarios(args.specBody);
+        const exec = args.exec ?? defaultExec;
+        const baseBranch = args.baseBranch ?? 'main';
+        const gitChangedFiles = args.projectPath
+            ? await computeChangedFilesFromGit(args.projectPath, exec, baseBranch)
+            : [];
+        const ownership = extractCanonicalFileOwnership(args.specBody);
+        const ownershipFiles = [...ownership.toCreate, ...ownership.toModify, ...ownership.toTest];
+        const rawChangedFiles = gitChangedFiles.length > 0 ? gitChangedFiles : ownershipFiles;
+        const changedFiles = args.projectPath
+            ? filterExistingRepoFiles(args.projectPath, rawChangedFiles)
+            : rawChangedFiles;
+        const { validationEvidence, reviewerEvidence } = await readValidationReportSummary(args.projectId, args.specId);
+        const rows = criteria.map((acceptanceCriterion, index) => {
+            const testPaths = scenarios[index]?.tests?.map((test) => test.path) ?? [];
+            return {
+                acceptanceCriterion,
+                ...(testPaths.length > 0 ? { testEvidence: testPaths } : {}),
+                changedFiles,
+                ...(validationEvidence ? { validationEvidence } : {}),
+                ...(reviewerEvidence ? { reviewerEvidence } : {}),
+            };
+        });
+        const payload = { version: 1, rows };
+        await atomicWriteFile(targetPath, JSON.stringify(payload, null, 2));
+        return { written: true, path: targetPath, rowCount: rows.length };
+    }
+    catch (error) {
+        /* reliability-optional: EVIDENCE_AUTOFILL_WRITE — caller proceeds without autofill */
+        reportClassifiedDegradation('EVIDENCE_AUTOFILL_WRITE', error);
+        return {
+            written: false,
+            reason: 'write-failed',
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+//# sourceMappingURL=evidence-autofill.js.map

package/dist/engine/evidence-gates/evidence-skeletons.d.ts

@@ -0,0 +1,19 @@
+import type { Spec } from '../../types/spec/core.js';
+import type { DiscoveryEvidence, TaskPlanEvidence } from '../../types/evidence-gates.js';
+/** Build a strict-schema discovery.json skeleton grounded in the spec's own grounding metadata. */
+export declare function generateDiscoverySkeleton(args: {
+    spec: Spec;
+    body: string | null;
+}): DiscoveryEvidence;
+/** Build a strict-schema task-plan.json skeleton with one pending task per canonical criterion. */
+export declare function generateTaskPlanSkeleton(args: {
+    criteria: string[];
+}): TaskPlanEvidence;
+/** Persist an auto-generated evidence skeleton to the external handoff store. */
+export declare function writeEvidenceSkeleton(args: {
+    projectId: string;
+    specId: string;
+    filename: string;
+    artifact: DiscoveryEvidence | TaskPlanEvidence;
+}): Promise<string>;
+//# sourceMappingURL=evidence-skeletons.d.ts.map

package/dist/engine/evidence-gates/evidence-skeletons.js

@@ -0,0 +1,69 @@
+// evidence-skeletons.ts — SPEC-1356: auto-generate schema-valid discovery/task-plan skeletons
+// when the underlying handoff evidence file is missing, so lifecycle gates self-heal instead
+// of blocking on a manual authoring step. Skeletons still require review; they only unblock
+// the transition, they do not fabricate confidence.
+import { join } from 'node:path';
+import { extractListItems, extractSection } from '../spec-format/markdown-sections.js';
+import { parseCriterionGroundingRecords } from '../spec-grounding/contract.js';
+import { projectDataDir } from '../../storage/base-store.js';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
+const DEFAULT_OUT_OF_SCOPE = 'None declared beyond the spec scope.';
+const DEFAULT_RULE = 'Behavior must follow the approved spec Problem and Technical sections.';
+function specFrontmatter(specBody) {
+    return FRONTMATTER_RE.exec(specBody)?.[1] ?? '';
+}
+function outOfScopeFromBody(specBody) {
+    if (!specBody) {
+        return [DEFAULT_OUT_OF_SCOPE];
+    }
+    const section = extractSection(specBody, 'out of scope');
+    if (!section) {
+        return [DEFAULT_OUT_OF_SCOPE];
+    }
+    const items = extractListItems(section);
+    return items.length > 0 ? items : [DEFAULT_OUT_OF_SCOPE];
+}
+/** Build a strict-schema discovery.json skeleton grounded in the spec's own grounding metadata. */
+export function generateDiscoverySkeleton(args) {
+    const records = args.body ? parseCriterionGroundingRecords(specFrontmatter(args.body)) : [];
+    const rules = records.length > 0 ? [...new Set(records.map((record) => record.text))] : [DEFAULT_RULE];
+    const examples = records.length > 0
+        ? records.map((record) => ({
+            rule: record.text,
+            example: record.evidence[0] ??
+                `Derived from ${args.spec.id} (${args.spec.title}) grounding evidence.`,
+        }))
+        : [{ rule: DEFAULT_RULE, example: `Derived from spec ${args.spec.id}: ${args.spec.title}.` }];
+    return {
+        version: 1,
+        rules,
+        examples,
+        openQuestions: [],
+        outOfScope: outOfScopeFromBody(args.body),
+        glossary: [{ term: args.spec.title, meaning: args.spec.feature ?? args.spec.title }],
+    };
+}
+/** Build a strict-schema task-plan.json skeleton with one pending task per canonical criterion. */
+export function generateTaskPlanSkeleton(args) {
+    const criteria = args.criteria.length > 0 ? args.criteria : ['Implementation satisfies the approved spec.'];
+    return {
+        version: 1,
+        tasks: criteria.map((criterion, index) => ({
+            id: `AC-${String(index + 1)}`,
+            title: criterion.length > 500 ? `${criterion.slice(0, 497)}...` : criterion,
+            acceptanceCriteria: [`AC${String(index + 1)}`],
+            status: 'pending',
+        })),
+    };
+}
+function handoffPath(projectId, specId, filename) {
+    return join(projectDataDir(projectId), 'handoffs', specId, filename);
+}
+/** Persist an auto-generated evidence skeleton to the external handoff store. */
+export async function writeEvidenceSkeleton(args) {
+    const path = handoffPath(args.projectId, args.specId, args.filename);
+    await atomicWriteFile(path, `${JSON.stringify(args.artifact, null, 2)}\n`);
+    return path;
+}
+//# sourceMappingURL=evidence-skeletons.js.map

package/dist/engine/execution/operation-journal.js

@@ -54,9 +54,15 @@ export class OperationJournal {
             const existing = this.get(operation, idempotencyKey);
             if (existing) {
                 if (existing.requestDigest !== requestDigest) {
-                    throw new BoundaryFailure('Conflict', 'operation begin', 'Use a new idempotency key for a different request.');
+                    // SPEC-1348: a rolled-back attempt produced no durable effects, so the
+                    // key is re-claimable even when the retry payload differs byte-wise.
+                    if (existing.state !== 'rolled-back') {
+                        throw new BoundaryFailure('Conflict', 'operation begin', 'Use a new idempotency key for a different request.');
+                    }
+                }
+                else {
+                    return existing;
                 }
-                return existing;
             }
             const now = new Date().toISOString();
             const entry = {
@@ -66,8 +72,8 @@ export class OperationJournal {
                 requestDigest,
                 state: 'intent',
                 ...(recovery ?? {}),
-                recoveryAttempts: 0,
-                createdAt: now,
+                recoveryAttempts: existing?.recoveryAttempts ?? 0,
+                createdAt: existing?.createdAt ?? now,
                 updatedAt: now,
             };
             this.put(entry);