@planu/cli 5.0.0 → 5.2.0

package/dist/engine/drift-monitor.js

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { fastScanProjectMetadata, isNativeActive, fastDetectDriftParallel, } from './core-bridge.js';
+import { fastScanProjectMetadataAsync, fastDetectDriftParallelAsync, } from './core-bridge.js';
 import { readSpecTechnicalSection } from './spec-format/read-technical-section.js';
 // ---------------------------------------------------------------------------
 // Config builder
@@ -41,13 +41,11 @@ export async function computeSummaryReport(projectPath, specList, config, rules,
     const alerts = [];
     let drifted = 0;
     let clean = 0;
-    // Layer 3 (AC coverage) Optimization:
-    // If native is active, we can do a single parallel scan for keywords across ALL specs.
-    // This is much faster than doing it one-by-one.
-    const nativeActive = isNativeActive();
-    const metadataMap = nativeActive
-        ? new Map(fastScanProjectMetadata(projectPath).map((m) => [m.path, m]))
-        : undefined;
+    // Layer 3 (AC coverage) Optimization: a single project-wide metadata scan
+    // (worker-dispatched when native is available) is much faster than doing it
+    // spec-by-spec.
+    const { value: projectMetadata } = await fastScanProjectMetadataAsync(projectPath);
+    const metadataMap = new Map(projectMetadata.map((m) => [m.path, m]));
     for (const specId of specList) {
         const technicalPath = specTechnicalPaths?.get(specId);
         const { score: healthScore } = await computeDriftScore(projectPath, specId, undefined, technicalPath, metadataMap);
@@ -272,19 +270,19 @@ async function computeAcCoverageScore(criteria, filePaths) {
         return 100;
     }
     let foundTerms;
-    if (isNativeActive()) {
-        // Use Rust to find which terms appear in implementation files across the WHOLE project.
-        // Note: Rust already does parallel walking and multi-threaded search.
-        // We pass any directory/file from the spec, but Rust will scan efficiently.
-        const firstFile = existingFiles[0];
-        if (!firstFile) {
-            return 100;
-        }
+    const firstFile = existingFiles[0];
+    if (!firstFile) {
+        return 100;
+    }
+    try {
+        // Worker-dispatched (native when available) parallel search across the WHOLE
+        // project rooted at the first file's dir — much faster than reading files
+        // one by one, and never blocks the main thread's event loop.
         const rootPath = path.dirname(firstFile); // Use first file's dir as heuristic
-        const result = fastDetectDriftParallel(rootPath, [...allTerms]);
+        const { value: result } = await fastDetectDriftParallelAsync(rootPath, [...allTerms]);
         foundTerms = new Set(result.foundKeywords);
     }
-    else {
+    catch {
         // Fallback: Read all implementation files once
         const fileContents = [];
         for (const filePath of existingFiles) {

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);

package/dist/engine/living-spec/hash-tracker.js

@@ -3,7 +3,7 @@
 import { createHash } from 'node:crypto';
 import { readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { fastScanAndHashFiles, isNativeActive } from '../core-bridge.js';
+import { fastScanAndHashFilesAsync } from '../core-bridge.js';
 /**
  * Compute SHA-256 hash of a file's content.
  */
@@ -34,38 +34,36 @@ export async function createFileHashEntry(projectPath, relativePath) {
  * Create hash entries for multiple files.
  */
 export async function createFileHashEntries(projectPath, relativePaths) {
-    // Try native Rust implementation for bulk hashing
-    if (isNativeActive()) {
-        try {
-            const results = fastScanAndHashFiles(projectPath);
-            const resultMap = new Map(results.map((r) => [r.path, r.hash]));
-            const entries = [];
-            for (const rel of relativePaths) {
-                const fullPath = join(projectPath, rel);
-                const hash = resultMap.get(fullPath);
-                if (hash) {
-                    try {
-                        const s = await stat(fullPath);
-                        entries.push({
-                            file: rel,
-                            hash,
-                            size: s.size,
-                            snapshotAt: new Date().toISOString(),
-                        });
-                    }
-                    catch {
-                        // File might have disappeared between scan and stat
-                    }
+    // Try the accelerated bulk-hash path (worker-dispatched native, or the TS fallback).
+    try {
+        const { value: results } = await fastScanAndHashFilesAsync(projectPath);
+        const resultMap = new Map(results.map((r) => [r.path, r.hash]));
+        const entries = [];
+        for (const rel of relativePaths) {
+            const fullPath = join(projectPath, rel);
+            const hash = resultMap.get(fullPath);
+            if (hash) {
+                try {
+                    const s = await stat(fullPath);
+                    entries.push({
+                        file: rel,
+                        hash,
+                        size: s.size,
+                        snapshotAt: new Date().toISOString(),
+                    });
+                }
+                catch {
+                    // File might have disappeared between scan and stat
                 }
-            }
-            if (entries.length > 0) {
-                return entries;
             }
         }
-        catch (err) {
-            console.warn('[Planu-RS] Native bulk hash failed, falling back to Node.', err);
+        if (entries.length > 0) {
+            return entries;
         }
     }
+    catch (err) {
+        console.warn('[Planu-RS] Bulk hash failed, falling back to Node.', err);
+    }
     const entries = [];
     for (const relativePath of relativePaths) {
         const entry = await createFileHashEntry(projectPath, relativePath);