@planu/cli 5.3.25 → 5.3.27

package/dist/tools/update-status/dod-gates.js

@@ -12,11 +12,12 @@ import { addLesson, getLessons } from '../../storage/lessons-store.js';
 import { dispatchFeedbackEvent } from '../learn.js';
 import { auditDeps } from '../../engine/dep-auditor/index.js';
 import { withEscalation } from '../../engine/escalator/with-escalation.js';
-import { writeImplementationReviewReport } from '../../engine/validator/validation-report-writer.js';
+import { AUTOMATED_VALIDATOR_AGENT, writeImplementationReviewReport, } from '../../engine/validator/validation-report-writer.js';
 import { formatKeyValue } from '../output-formatter.js';
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { verifyCurrentDoneReceipt } from './done-receipt-verifier.js';
 import { projectDataDir } from '../../storage/base-store.js';
+import { readTransitionLog } from '../../storage/transition-log.js';
 import { ValidationReportV1Schema } from '../../engine/handoff-artifacts/schemas.js';
 export { completedJobPublishesReceipt } from './done-receipt-verifier.js';
 /**
@@ -447,10 +448,10 @@ async function checkDoneReviewDigest(specId, projectId, implementationReviewDige
         !parsed.data.passed ||
         parsed.data.gates.some((gate) => !gate.passed) ||
         parsed.data.minimalityReport?.blocked === true ||
-        parsed.data.reviewer.kind !== 'implementation-review-agent' ||
-        parsed.data.reviewer.agent !== 'planu-implementation-reviewer' ||
+        parsed.data.reviewer.kind !== 'automation' ||
+        parsed.data.reviewer.agent !== AUTOMATED_VALIDATOR_AGENT ||
         parsed.data.reviewer.verdict !== 'approved') {
-        return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_UNSAFE', 'The validation report schema or independent reviewer evidence is invalid.');
+        return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_UNSAFE', 'The validation report schema or automated validator evidence is invalid.');
     }
     return null;
 }
@@ -616,6 +617,116 @@ export async function checkSpecReviewGate(specId, projectId, _forceApprove) {
         });
     }
 }
+export async function checkImplementationReviewGate(specId, projectId, _force) {
+    try {
+        const { readArtifact } = await import('../../engine/handoff-artifacts/io.js');
+        const result = await readArtifact({ projectId, specId, kind: 'implementation_review' });
+        if (!result.ok) {
+            const firstErr = result.errors[0];
+            return implementationReviewGateError({
+                specId,
+                error: firstErr?.code === 'ARTIFACT_NOT_FOUND'
+                    ? 'implementation_review_missing'
+                    : 'implementation_review_invalid',
+                message: firstErr?.code === 'ARTIFACT_NOT_FOUND'
+                    ? 'No implementation review exists for this spec. An independent planu-implementation-reviewer must review the implementation and write its own evidence before done.'
+                    : 'Implementation review evidence is malformed or uses an obsolete schema.',
+                blockers: [],
+                fixHint: firstErr?.code === 'ARTIFACT_NOT_FOUND'
+                    ? 'Have planu-implementation-reviewer write implementation_review.json (ImplementationReviewV1) into the handoff store, then retry update_status(done).'
+                    : 'Have planu-implementation-reviewer rewrite implementation_review.json as valid ImplementationReviewV1 evidence, then retry done.',
+            });
+        }
+        const review = result.payload;
+        if (isLifecycleStubBody(specId, review.body)) {
+            return implementationReviewGateError({
+                specId,
+                error: 'implementation_review_stub',
+                message: 'Implementation review evidence is a lifecycle-generated stub, not evidence from a real reviewer.',
+                blockers: [],
+                fixHint: 'Replace the stub with genuine planu-implementation-reviewer evidence in the handoff store, then retry done.',
+            });
+        }
+        if (review.verdict !== 'approved' || review.reviewer.verdict !== 'approved') {
+            return implementationReviewGateError({
+                specId,
+                error: 'implementation_review_changes_requested',
+                message: 'Implementation reviewer requested changes. Done is blocked until the review passes.',
+                blockers: review.blockers,
+                fixHint: 'Resolve the implementation review blockers and have planu-implementation-reviewer write updated evidence, then retry done.',
+            });
+        }
+        if (review.reviewer.kind !== 'implementation-review-agent' ||
+            review.reviewer.agent !== 'planu-implementation-reviewer') {
+            return implementationReviewGateError({
+                specId,
+                error: 'implementation_review_wrong_reviewer',
+                message: 'Done requires the recognized independent implementation reviewer identity.',
+                blockers: [
+                    `Reviewer was ${review.reviewer.agent}. Expected planu-implementation-reviewer.`,
+                ],
+                fixHint: 'Have planu-implementation-reviewer (with the recognized identity) write the review artifact, then retry done.',
+            });
+        }
+        const implementerActor = await findImplementingActor(specId, projectId);
+        if (implementerActor !== undefined && implementerActor === review.reviewer.agent) {
+            return implementationReviewGateError({
+                specId,
+                error: 'implementation_review_self_review',
+                message: 'The implementation reviewer must be a different identity from the implementer. Self-review is blocked.',
+                blockers: [`Implementer and reviewer share the identity "${implementerActor}".`],
+                fixHint: 'Have a different, independent agent write the implementation review evidence, then retry done.',
+            });
+        }
+        return null;
+    }
+    catch (err) {
+        /* reliability-optional: IMPLEMENTATION_REVIEW_GATE_READ — typed gate error blocks done */
+        reportClassifiedDegradation('IMPLEMENTATION_REVIEW_GATE_READ', err);
+        return implementationReviewGateError({
+            specId,
+            error: 'implementation_review_unreadable',
+            message: `Could not read implementation review evidence: ${err instanceof Error ? err.message : String(err)}`,
+            blockers: [],
+            fixHint: 'Fix the artifact store issue so implementation_review.json is readable, then retry update_status(done).',
+        });
+    }
+}
+async function findImplementingActor(specId, projectId) {
+    const entries = await readTransitionLog(projectId, specId);
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (entry?.to === 'implementing' && entry.actor) {
+            return entry.actor;
+        }
+    }
+    return undefined;
+}
+function implementationReviewGateError(args) {
+    const artifactPath = `external Planu project data: handoffs/${args.specId}/implementation_review.json`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: formatKeyValue({
+                    error: args.error,
+                    message: args.message,
+                    artifactPath,
+                    blockers: args.blockers.length,
+                    firstBlocker: args.blockers[0],
+                    fixHint: args.fixHint,
+                }, 'Implementation review gate failed'),
+            },
+        ],
+        isError: true,
+        structuredContent: {
+            error: args.error,
+            code: 422,
+            context: { specId: args.specId, artifactPath, blockers: args.blockers },
+            fixHint: args.fixHint,
+        },
+    };
+}
 function validationReportGateError(args) {
     const artifactPath = `external Planu project data: handoffs/${args.specId}/validation-report.json`;
     return {
@@ -673,6 +784,14 @@ function specReviewGateError(args) {
  */
 export async function checkDoneGates(spec, specId, projectId, projectPath, _force, _forceReason = 'No force reason provided', verifyReceipt = verifyCurrentDoneReceipt, implementationReviewDigest) {
     try {
+        const reviewGateError = await checkImplementationReviewGate(specId, projectId, _force);
+        if (reviewGateError) {
+            return {
+                blocked: reviewGateError,
+                forcedBypassWarning: null,
+                freshnessLease: null,
+            };
+        }
         if (implementationReviewDigest !== undefined) {
             const digestError = await checkDoneReviewDigest(specId, projectId, implementationReviewDigest);
             if (digestError) {

package/dist/types/handoff-artifacts.d.ts

@@ -1,6 +1,6 @@
 import type { Spec } from './spec/core.js';
 /** Artifact kinds produced/consumed by each role transition */
-export type ArtifactKind = 'intake' | 'spec.lock' | 'review_feedback' | 'implementation-report' | 'validation-report';
+export type ArtifactKind = 'intake' | 'spec.lock' | 'review_feedback' | 'implementation-report' | 'validation-report' | 'implementation_review';
 /** Triagier → Elicitor: describes the intent to be elaborated */
 export interface IntakeV1 {
     schema_version: string;
@@ -39,6 +39,21 @@ export interface ReviewFeedbackV1 {
     body: string;
     reviewedAt: string;
 }
+/** Independent reviewer → Planner: evidence that an implementation review actually happened */
+export interface ImplementationReviewV1 {
+    schema_version: string;
+    specId: string;
+    verdict: 'approved' | 'changes-requested';
+    reviewer: {
+        kind: 'implementation-review-agent' | 'human';
+        agent: string;
+        verdict: 'approved' | 'changes-requested';
+    };
+    blockers: string[];
+    suggestions: string[];
+    body: string;
+    reviewedAt: string;
+}
 /** Implementer → Validator: result of implementation run */
 export interface ImplementationReportV1 {
     schema_version: string;
@@ -125,6 +140,7 @@ export interface ArtifactPayloadMap {
     review_feedback: ReviewFeedbackV1;
     'implementation-report': ImplementationReportV1;
     'validation-report': ValidationReportV1;
+    implementation_review: ImplementationReviewV1;
 }
 export type ArtifactPayload<K extends ArtifactKind> = ArtifactPayloadMap[K];
 import type { MinimalImplementationReport } from './minimal-implementation-gate.js';

package/dist/types/project/planu-config.d.ts

@@ -8,6 +8,7 @@ import type { OrchestratorInfo, ComposeMultiplatformInfo } from './platform-spec
 import type { ProjectKnowledge, ProjectCompleteness } from './core.js';
 import type { ProjectHealthReport } from './health-checker.js';
 import type { DiscoveredRegistrySkill } from '../skill-bootstrap.js';
+import type { LegacyMigrationDirective } from '../spec-format.js';
 export interface PlanuConfig {
     version: string;
     specLocation: string;
@@ -79,6 +80,8 @@ export interface InitProjectResultInput {
         migratedCount: number;
         errors: string[];
     } | null;
+    /** SPEC-1570: content-bearing/transient legacy artifacts pending host-LLM migration. */
+    legacyMigrationDirectives: LegacyMigrationDirective[];
     criticalMigrationFailures?: {
         phase: string;
         severity: 'critical' | 'nonCritical';

package/dist/types/spec/core.d.ts

@@ -179,13 +179,6 @@ export interface ModelBudget {
     model: 'haiku' | 'sonnet' | 'opus';
     budget: 800 | 2000 | 4000;
 }
-/** SPEC-630: Result of merging technical.md into spec.md. */
-export interface UnifiedMigrationResult {
-    specDir: string;
-    merged: boolean;
-    reason: 'ok' | 'already-unified' | 'no-technical-md' | 'error';
-    error?: string;
-}
 export interface SpecSummary {
     specId: string;
     title: string;

package/dist/types/spec-format.d.ts

@@ -91,6 +91,23 @@ export interface StrictPlanuValidationOptions {
     specPath?: string;
     includeRoot?: boolean;
 }
+export interface LegacyArtifactRule {
+    id: string;
+    pattern: string;
+    classification: 'content-bearing' | 'transient';
+    targetSection?: string;
+}
+export interface LegacyArtifactHit {
+    path: string;
+    classification: 'content-bearing' | 'transient';
+    targetSection?: string;
+    inlinedContent?: string;
+}
+export interface LegacyMigrationDirective {
+    specId: string;
+    legacyFiles: LegacyArtifactHit[];
+    directive: 'migrate_legacy_spec';
+}
 export interface UpdateStatusBatchInput {
     specIds: string[];
     status: Exclude<SpecStatus, 'done'>;

package/dist/types/transition-log.d.ts

@@ -1,5 +1,5 @@
 /** Event types recorded in the transition log. */
-export type TransitionEventType = 'transitioned_to_terminal' | 'frontmatter_resealed' | 'reopen' | 'terminal_drift_detected' | 'transition' | 'handoff.intake' | 'handoff.spec.lock' | 'handoff.review_feedback' | 'handoff.implementation-report' | 'handoff.validation-report' | 'retro_audit' | 'tdd_red_locked' | 'tdd_green_achieved' | 'status_reconciled' | 'housekeeping' | 'ghost_spec_quarantined';
+export type TransitionEventType = 'transitioned_to_terminal' | 'frontmatter_resealed' | 'reopen' | 'terminal_drift_detected' | 'transition' | 'handoff.intake' | 'handoff.spec.lock' | 'handoff.review_feedback' | 'handoff.implementation-report' | 'handoff.validation-report' | 'handoff.implementation_review' | 'retro_audit' | 'tdd_red_locked' | 'tdd_green_achieved' | 'status_reconciled' | 'housekeeping' | 'ghost_spec_quarantined';
 /** SPEC-734: Outcome of a gate execution in a transition. */
 export type GateOutcome = 'pass' | 'fail' | 'skip' | 'forced';
 /** SPEC-734: Result of verifying the hash chain integrity of a project's transition log. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.25",
+  "version": "5.3.27",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -36,14 +36,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "5.3.25",
-    "@planu/core-darwin-x64": "5.3.25",
-    "@planu/core-linux-arm64-gnu": "5.3.25",
-    "@planu/core-linux-arm64-musl": "5.3.25",
-    "@planu/core-linux-x64-gnu": "5.3.25",
-    "@planu/core-linux-x64-musl": "5.3.25",
-    "@planu/core-win32-arm64-msvc": "5.3.25",
-    "@planu/core-win32-x64-msvc": "5.3.25"
+    "@planu/core-darwin-arm64": "5.3.27",
+    "@planu/core-darwin-x64": "5.3.27",
+    "@planu/core-linux-arm64-gnu": "5.3.27",
+    "@planu/core-linux-arm64-musl": "5.3.27",
+    "@planu/core-linux-x64-gnu": "5.3.27",
+    "@planu/core-linux-x64-musl": "5.3.27",
+    "@planu/core-win32-arm64-msvc": "5.3.27",
+    "@planu/core-win32-x64-msvc": "5.3.27"
   },
   "engines": {
     "node": ">=24.0.0"

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "5.3.25",
+  "version": "5.3.27",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "5.3.25",
+  "version": "5.3.27",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",
@@ -36,7 +36,8 @@
       "resolve_feedback",
       "sync_feedback",
       "feedback_status",
-      "bump_spec_version"
+      "bump_spec_version",
+      "migrate_legacy_spec"
     ],
     "resources": ["planu://specs/list", "planu://specs/{id}", "planu://project/status", "planu://roadmap"],
     "prompts": ["create-spec-from-idea", "review-spec-readiness", "generate-implementation-plan"],

package/dist/engine/spec-migrator/unified-migration.d.ts

@@ -1,18 +0,0 @@
-import type { UnifiedMigrationResult } from '../../types/index.js';
-export type { UnifiedMigrationResult };
-/**
- * Merge technical.md into spec.md under a `## Technical` section, then delete technical.md.
- * Idempotent: skips if spec.md already contains `## Technical`.
- *
- * @param specDir   Absolute path to the spec directory.
- * @param projectPath  Project root used for `safeUnlink` (git-aware deletion). Optional:
- *                     when omitted, falls back to plain unlink.
- */
-export declare function migrateToUnified(specDir: string, projectPath?: string): Promise<UnifiedMigrationResult>;
-/** Migrate all SPEC-* dirs under projectPath to unified format. Best-effort: never throws. */
-export declare function migrateAllSpecsToUnified(projectPath: string): Promise<{
-    mergedCount: number;
-    skippedCount: number;
-    errors: string[];
-}>;
-//# sourceMappingURL=unified-migration.d.ts.map

package/dist/engine/spec-migrator/unified-migration.js

@@ -1,105 +0,0 @@
-// engine/spec-migrator/unified-migration.ts — Merge technical.md into spec.md (SPEC-630)
-import { readFile } from 'node:fs/promises';
-import { atomicWriteFile } from '../safety/atomic-write-file.js';
-/** Write a verified backup of a file before overwriting. Returns backup path. Throws on failure. */
-async function writeVerifiedBackup(filePath) {
-    const content = await readFile(filePath, 'utf-8');
-    const bkPath = `${filePath}.bak.${Date.now()}`;
-    await atomicWriteFile(bkPath, content);
-    const verify = await readFile(bkPath, 'utf-8');
-    if (verify !== content) {
-        throw new Error(`backup verify failed for ${filePath}: content mismatch`);
-    }
-    return bkPath;
-}
-import { join } from 'node:path';
-import { safeUnlink } from './git-aware-fs.js';
-/**
- * Merge technical.md into spec.md under a `## Technical` section, then delete technical.md.
- * Idempotent: skips if spec.md already contains `## Technical`.
- *
- * @param specDir   Absolute path to the spec directory.
- * @param projectPath  Project root used for `safeUnlink` (git-aware deletion). Optional:
- *                     when omitted, falls back to plain unlink.
- */
-export async function migrateToUnified(specDir, projectPath) {
-    const specPath = join(specDir, 'spec.md');
-    const techPath = join(specDir, 'technical.md');
-    try {
-        const specContent = await readFile(specPath, 'utf-8');
-        if (/\n## Technical(\n|$)/.test(specContent)) {
-            try {
-                await readFile(techPath, 'utf-8');
-                if (projectPath) {
-                    await safeUnlink(projectPath, techPath);
-                }
-                else {
-                    const { unlink } = await import('node:fs/promises');
-                    await unlink(techPath);
-                }
-                return { specDir, merged: true, reason: 'already-unified' };
-            }
-            catch {
-                /* no residual technical.md */
-            }
-            return { specDir, merged: false, reason: 'already-unified' };
-        }
-        let techContent;
-        try {
-            techContent = await readFile(techPath, 'utf-8');
-        }
-        catch {
-            return { specDir, merged: false, reason: 'no-technical-md' };
-        }
-        // Strip YAML frontmatter block from technical.md before appending
-        const techBody = techContent.replace(/^---\n[\s\S]*?\n---\n/, '').trim();
-        const unified = `${specContent.trimEnd()}\n\n## Technical\n\n${techBody}\n`;
-        // SPEC-771: backup spec.md before overwriting (verified write-back)
-        try {
-            await writeVerifiedBackup(specPath);
-        }
-        catch (backupErr) {
-            return {
-                specDir,
-                merged: false,
-                reason: 'error',
-                error: `backup failed: ${String(backupErr)}`,
-            };
-        }
-        // Write spec.md first, delete technical.md second — never leave both inconsistent
-        await atomicWriteFile(specPath, unified);
-        if (projectPath) {
-            await safeUnlink(projectPath, techPath);
-        }
-        else {
-            const { unlink } = await import('node:fs/promises');
-            await unlink(techPath);
-        }
-        return { specDir, merged: true, reason: 'ok' };
-    }
-    catch (err) {
-        return { specDir, merged: false, reason: 'error', error: String(err) };
-    }
-}
-/** Migrate all SPEC-* dirs under projectPath to unified format. Best-effort: never throws. */
-export async function migrateAllSpecsToUnified(projectPath) {
-    const { glob } = await import('glob');
-    const dirs = await glob(join(projectPath, 'planu/specs/SPEC-*'));
-    let mergedCount = 0;
-    let skippedCount = 0;
-    const errors = [];
-    for (const dir of dirs) {
-        const r = await migrateToUnified(dir, projectPath);
-        if (r.merged) {
-            mergedCount++;
-        }
-        else if (!r.error) {
-            skippedCount++;
-        }
-        if (r.error) {
-            errors.push(`${dir}: ${r.error}`);
-        }
-    }
-    return { mergedCount, skippedCount, errors };
-}
-//# sourceMappingURL=unified-migration.js.map