@planu/cli 4.2.2 → 4.2.4

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [4.2.4] - 2026-05-22
+
+**Tarball SHA-256:** `963c0c81820ad002206299f102fdcae6635d96cdbe2e602e4f1dbb2d1b41e0c5`
+
+### Features
+- feat(planu): require spec reviewer before approval
+
+
+## [4.2.3] - 2026-05-22
+
+**Tarball SHA-256:** `6d23ef6f7bd12e2a94eb9984e272beb37cd0d9b54ad12170529f95ca870e46a4`
+
+### Features
+- feat(planu): require implementation reviewer gate
+
+
 ## [4.2.2] - 2026-05-21
 
 **Tarball SHA-256:** `83193f54dc2fc5f461ef38b8bf2a9931d5d587ece50c77836942351e39b3c415`

package/dist/engine/handoff-artifacts/schemas.d.ts

@@ -31,13 +31,27 @@ export declare const SpecLockV1Schema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const ReviewFeedbackV1Schema: z.ZodObject<{
     schema_version: z.ZodString;
+    specId: z.ZodString;
     verdict: z.ZodEnum<{
         approved: "approved";
         "changes-requested": "changes-requested";
     }>;
+    reviewer: z.ZodObject<{
+        kind: z.ZodEnum<{
+            human: "human";
+            "spec-review-agent": "spec-review-agent";
+            automation: "automation";
+        }>;
+        agent: z.ZodString;
+        verdict: z.ZodEnum<{
+            approved: "approved";
+            "changes-requested": "changes-requested";
+        }>;
+    }, z.core.$strip>;
     blockers: z.ZodArray<z.ZodString>;
     suggestions: z.ZodArray<z.ZodString>;
     body: z.ZodString;
+    reviewedAt: z.ZodISODateTime;
 }, z.core.$strip>;
 export declare const ImplementationReportV1Schema: z.ZodObject<{
     schema_version: z.ZodString;
@@ -57,6 +71,31 @@ export declare const ValidationReportV1Schema: z.ZodObject<{
         passed: z.ZodBoolean;
         reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    reviewer: z.ZodObject<{
+        kind: z.ZodEnum<{
+            human: "human";
+            automation: "automation";
+            "implementation-review-agent": "implementation-review-agent";
+        }>;
+        agent: z.ZodString;
+        verdict: z.ZodEnum<{
+            approved: "approved";
+            "changes-requested": "changes-requested";
+        }>;
+    }, z.core.$strip>;
+    specCompliance: z.ZodOptional<z.ZodObject<{
+        score: z.ZodNumber;
+        command: z.ZodString;
+        scenarios: z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            verdict: z.ZodEnum<{
+                fail: "fail";
+                missing: "missing";
+                pass: "pass";
+            }>;
+            evidence: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     score: z.ZodOptional<z.ZodNumber>;
     completedAt: z.ZodISODateTime;
 }, z.core.$strip>;
@@ -90,13 +129,27 @@ export declare const ARTIFACT_SCHEMAS: {
     }, z.core.$strip>;
     readonly review_feedback: z.ZodObject<{
         schema_version: z.ZodString;
+        specId: z.ZodString;
         verdict: z.ZodEnum<{
             approved: "approved";
             "changes-requested": "changes-requested";
         }>;
+        reviewer: z.ZodObject<{
+            kind: z.ZodEnum<{
+                human: "human";
+                "spec-review-agent": "spec-review-agent";
+                automation: "automation";
+            }>;
+            agent: z.ZodString;
+            verdict: z.ZodEnum<{
+                approved: "approved";
+                "changes-requested": "changes-requested";
+            }>;
+        }, z.core.$strip>;
         blockers: z.ZodArray<z.ZodString>;
         suggestions: z.ZodArray<z.ZodString>;
         body: z.ZodString;
+        reviewedAt: z.ZodISODateTime;
     }, z.core.$strip>;
     readonly 'implementation-report': z.ZodObject<{
         schema_version: z.ZodString;
@@ -116,6 +169,31 @@ export declare const ARTIFACT_SCHEMAS: {
             passed: z.ZodBoolean;
             reason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        reviewer: z.ZodObject<{
+            kind: z.ZodEnum<{
+                human: "human";
+                automation: "automation";
+                "implementation-review-agent": "implementation-review-agent";
+            }>;
+            agent: z.ZodString;
+            verdict: z.ZodEnum<{
+                approved: "approved";
+                "changes-requested": "changes-requested";
+            }>;
+        }, z.core.$strip>;
+        specCompliance: z.ZodOptional<z.ZodObject<{
+            score: z.ZodNumber;
+            command: z.ZodString;
+            scenarios: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                verdict: z.ZodEnum<{
+                    fail: "fail";
+                    missing: "missing";
+                    pass: "pass";
+                }>;
+                evidence: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
         score: z.ZodOptional<z.ZodNumber>;
         completedAt: z.ZodISODateTime;
     }, z.core.$strip>;

package/dist/engine/handoff-artifacts/schemas.js

@@ -27,10 +27,17 @@ export const SpecLockV1Schema = z.object({
 });
 export const ReviewFeedbackV1Schema = z.object({
     schema_version: SchemaVersion,
+    specId: z.string(),
     verdict: z.enum(['approved', 'changes-requested']),
+    reviewer: z.object({
+        kind: z.enum(['spec-review-agent', 'human', 'automation']),
+        agent: z.string().min(1),
+        verdict: z.enum(['approved', 'changes-requested']),
+    }),
     blockers: z.array(z.string()),
     suggestions: z.array(z.string()),
     body: z.string(),
+    reviewedAt: z.iso.datetime(),
 });
 export const ImplementationReportV1Schema = z.object({
     schema_version: SchemaVersion,
@@ -50,6 +57,22 @@ export const ValidationReportV1Schema = z.object({
         passed: z.boolean(),
         reason: z.string().optional(),
     })),
+    reviewer: z.object({
+        kind: z.enum(['implementation-review-agent', 'human', 'automation']),
+        agent: z.string().min(1),
+        verdict: z.enum(['approved', 'changes-requested']),
+    }),
+    specCompliance: z
+        .object({
+        score: z.number().min(0).max(100),
+        command: z.string(),
+        scenarios: z.array(z.object({
+            title: z.string(),
+            verdict: z.enum(['pass', 'fail', 'missing']),
+            evidence: z.array(z.string()),
+        })),
+    })
+        .optional(),
     score: z.number().optional(),
     completedAt: z.iso.datetime(),
 });

package/dist/engine/validator/spec-review-writer.d.ts

@@ -0,0 +1,14 @@
+import type { Spec } from '../../types/index.js';
+import type { ReviewFeedbackV1 } from '../../types/handoff-artifacts.js';
+export declare function writeSpecReviewFeedback(input: {
+    projectId: string;
+    specId: string;
+    spec: Spec;
+}): Promise<{
+    written: boolean;
+    path?: string;
+    sha?: string;
+    payload: ReviewFeedbackV1;
+    error?: string;
+}>;
+//# sourceMappingURL=spec-review-writer.d.ts.map

package/dist/engine/validator/spec-review-writer.js

@@ -0,0 +1,49 @@
+import { appendArtifact } from '../handoff-artifacts/io.js';
+export async function writeSpecReviewFeedback(input) {
+    const blockers = buildSpecReviewBlockers(input.spec);
+    const verdict = blockers.length === 0 ? 'approved' : 'changes-requested';
+    const payload = {
+        schema_version: '1.0.0',
+        specId: input.specId,
+        verdict,
+        reviewer: {
+            kind: 'spec-review-agent',
+            agent: 'planu-spec-reviewer',
+            verdict,
+        },
+        blockers,
+        suggestions: blockers.length === 0
+            ? ['Proceed to approval gates; keep implementation reviewer separate after coding.']
+            : [
+                'Resolve blockers, rerun challenge/readiness checks, then move the spec back to review.',
+            ],
+        body: blockers.length === 0
+            ? `Spec ${input.specId} reviewed by planu-spec-reviewer and approved for approval gates.`
+            : `Spec ${input.specId} reviewed by planu-spec-reviewer with requested changes.`,
+        reviewedAt: new Date().toISOString(),
+    };
+    try {
+        const artifact = await appendArtifact({
+            projectId: input.projectId,
+            specId: input.specId,
+            kind: 'review_feedback',
+            payload,
+        });
+        return { written: true, path: artifact.path, sha: artifact.sha, payload };
+    }
+    catch (err) {
+        return {
+            written: false,
+            payload,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function buildSpecReviewBlockers(spec) {
+    const blockers = [];
+    if (!spec.title || spec.title.trim().length === 0) {
+        blockers.push('Spec title is missing.');
+    }
+    return blockers;
+}
+//# sourceMappingURL=spec-review-writer.js.map

package/dist/engine/validator/validation-report-writer.d.ts

@@ -0,0 +1,21 @@
+import type { Spec } from '../../types/index.js';
+import type { ValidationReportV1 } from '../../types/handoff-artifacts.js';
+export declare function writeImplementationReviewReport(input: {
+    projectId: string;
+    specId: string;
+    spec: Spec;
+    projectPath: string;
+    score: number | null;
+    lintPassed?: boolean;
+    conventionRegression?: boolean;
+}): Promise<{
+    written: boolean;
+    path?: string;
+    sha?: string;
+    error?: string;
+    reviewer: ValidationReportV1['reviewer'];
+    passed: boolean;
+    gates: ValidationReportV1['gates'];
+    specCompliance: NonNullable<ValidationReportV1['specCompliance']>;
+}>;
+//# sourceMappingURL=validation-report-writer.d.ts.map

package/dist/engine/validator/validation-report-writer.js

@@ -0,0 +1,106 @@
+import { appendArtifact } from '../handoff-artifacts/io.js';
+import { runSpecCompliance, } from './spec-compliance-runner.js';
+export async function writeImplementationReviewReport(input) {
+    const specCompliance = await runSpecCompliance(input.spec, input.projectPath);
+    const gates = buildGates({
+        score: input.score,
+        lintPassed: input.lintPassed ?? true,
+        conventionRegression: input.conventionRegression ?? false,
+        specCompliance,
+    });
+    const passed = gates.every((gate) => gate.passed);
+    const reviewer = {
+        kind: 'implementation-review-agent',
+        agent: 'planu-implementation-reviewer',
+        verdict: passed ? 'approved' : 'changes-requested',
+    };
+    const reportCompliance = toValidationReportCompliance(specCompliance);
+    const payload = {
+        schema_version: '1.0.0',
+        specId: input.specId,
+        passed,
+        gates,
+        reviewer,
+        specCompliance: reportCompliance,
+        score: input.score ?? undefined,
+        completedAt: new Date().toISOString(),
+    };
+    try {
+        const artifact = await appendArtifact({
+            projectId: input.projectId,
+            specId: input.specId,
+            kind: 'validation-report',
+            payload,
+        });
+        return {
+            written: true,
+            path: artifact.path,
+            sha: artifact.sha,
+            reviewer,
+            passed,
+            gates,
+            specCompliance: reportCompliance,
+        };
+    }
+    catch (err) {
+        return {
+            written: false,
+            error: err instanceof Error ? err.message : String(err),
+            reviewer,
+            passed,
+            gates,
+            specCompliance: reportCompliance,
+        };
+    }
+}
+function buildGates(args) {
+    return [
+        {
+            name: 'validate-score',
+            passed: args.score === 100,
+            reason: args.score === 100
+                ? undefined
+                : `Expected validation score 100 before done, got ${String(args.score ?? 'unscored')}.`,
+        },
+        {
+            name: 'lint',
+            passed: args.lintPassed,
+            reason: args.lintPassed ? undefined : 'Configured lint command failed.',
+        },
+        {
+            name: 'convention-regression',
+            passed: !args.conventionRegression,
+            reason: args.conventionRegression ? 'Convention baseline regression detected.' : undefined,
+        },
+        buildSpecComplianceGate(args.specCompliance),
+    ];
+}
+function buildSpecComplianceGate(result) {
+    if (result.perScenario.length === 0) {
+        return {
+            name: 'spec-compliance',
+            passed: true,
+            reason: 'No executable scenarios declared; spec-compliance runner skipped.',
+        };
+    }
+    const passed = result.dimensionScore === 100;
+    return {
+        name: 'spec-compliance',
+        passed,
+        reason: passed
+            ? undefined
+            : `Expected all executable scenarios to pass, got ${String(result.dimensionScore)}.`,
+    };
+}
+function toValidationReportCompliance(result) {
+    return {
+        score: result.dimensionScore,
+        command: result.command,
+        scenarios: result.perScenario.map((scenario) => ({
+            title: scenario.title,
+            verdict: scenario.verdict,
+            evidence: scenario.evidence,
+        })),
+    };
+}
+//# sourceMappingURL=validation-report-writer.js.map

package/dist/tools/update-status/dod-gates.d.ts

@@ -45,7 +45,10 @@ export type ValidateGateResult = {
  * @param forceStatusReason  Why — required and ≥100 chars when forceStatus=true.
  * @param budgetMs        Max milliseconds to wait for validate. Default: 9000.
  */
-export declare function runValidateGate(spec: Spec, projectPath: string, forceStatus: boolean, forceStatusReason: string | undefined, budgetMs?: number): Promise<ValidateGateResult>;
+export declare function runValidateGate(spec: Spec, projectPath: string, forceStatus: boolean, forceStatusReason: string | undefined, budgetMs?: number, reviewContext?: {
+    projectId: string;
+    specId: string;
+}): Promise<ValidateGateResult>;
 /**
  * Checks the DoD gate before transitioning to 'done'.
  * Returns an error ToolResult if blocked (unless force=true), null if passed.
@@ -71,11 +74,14 @@ export interface DoneGateResult {
 }
 /**
  * SPEC-725: Check the validation-report artifact gate before marking done.
- * If a validation-report.json exists and payload.passed === false, block transition.
- * If the artifact is absent, allow (backward compat).
- * Never throws — always best-effort.
+ * SPEC-1050: Fail closed. A done transition requires a fresh validation-report
+ * with reviewer evidence and all validation gates passing.
  */
 export declare function checkValidationReportGate(specId: string, projectId: string, force: boolean | undefined): Promise<ToolResult | null>;
+/** SPEC-1051: Write spec-review evidence when a spec enters review. */
+export declare function writeSpecReviewArtifact(spec: Spec, specId: string, projectId: string): Promise<ToolResult | null>;
+/** SPEC-1051: Approval requires a dedicated spec reviewer artifact. */
+export declare function checkSpecReviewGate(specId: string, projectId: string, _forceApprove: boolean | undefined): Promise<ToolResult | null>;
 /**
  * SPEC-335: Combined done-gates runner — DoD + security.
  * When force=true, gates are not blocking but failing items are recorded in

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

@@ -8,6 +8,8 @@ import { getComplianceGateConfig } from '../../storage/compliance-gate-config-st
 import { readJson, writeJson, projectDataDir } from '../../storage/base-store.js';
 import { randomUUID } from 'node:crypto';
 import { withEscalation } from '../../engine/escalator/with-escalation.js';
+import { writeImplementationReviewReport } from '../../engine/validator/validation-report-writer.js';
+import { writeSpecReviewFeedback } from '../../engine/validator/spec-review-writer.js';
 /**
  * SPEC-721 / SPEC-222 Trigger 1: Run validate engine before marking done.
  *
@@ -24,7 +26,7 @@ import { withEscalation } from '../../engine/escalator/with-escalation.js';
  * @param forceStatusReason  Why — required and ≥100 chars when forceStatus=true.
  * @param budgetMs        Max milliseconds to wait for validate. Default: 9000.
  */
-export async function runValidateGate(spec, projectPath, forceStatus, forceStatusReason, budgetMs = 9_000) {
+export async function runValidateGate(spec, projectPath, forceStatus, forceStatusReason, budgetMs = 9_000, reviewContext) {
     // ---- Path A: explicit force bypass ----------------------------------------
     if (forceStatus) {
         if (!forceStatusReason || forceStatusReason.trim().length < 100) {
@@ -96,13 +98,29 @@ export async function runValidateGate(spec, projectPath, forceStatus, forceStatu
         };
     }
     // ---- Normal score check — scoreValue is guaranteed number here (null/undefined filtered above) ---
-    if (scoreValue < 70) {
+    if (scoreValue < 100) {
+        if (reviewContext) {
+            await writeImplementationReviewReport({
+                ...reviewContext,
+                spec,
+                projectPath,
+                score: scoreValue,
+            });
+        }
         return {
             blocked: true,
             score: scoreValue,
             reason: 'validate_score_below_threshold',
         };
     }
+    if (reviewContext) {
+        await writeImplementationReviewReport({
+            ...reviewContext,
+            spec,
+            projectPath,
+            score: scoreValue,
+        });
+    }
     return { blocked: false, score: scoreValue, forced: false };
 }
 /**
@@ -243,9 +261,8 @@ async function recordForceDoneBypass(specId, projectId, failingItems, warningIte
 }
 /**
  * SPEC-725: Check the validation-report artifact gate before marking done.
- * If a validation-report.json exists and payload.passed === false, block transition.
- * If the artifact is absent, allow (backward compat).
- * Never throws — always best-effort.
+ * SPEC-1050: Fail closed. A done transition requires a fresh validation-report
+ * with reviewer evidence and all validation gates passing.
  */
 export async function checkValidationReportGate(specId, projectId, force) {
     if (force) {
@@ -254,45 +271,168 @@ export async function checkValidationReportGate(specId, projectId, force) {
     try {
         const { readArtifact } = await import('../../engine/handoff-artifacts/io.js');
         const result = await readArtifact({ projectId, specId, kind: 'validation-report' });
-        // If not found (ARTIFACT_NOT_FOUND), allow — backward compat
         if (!result.ok) {
             const firstErr = result.errors[0];
             if (firstErr?.code === 'ARTIFACT_NOT_FOUND') {
-                return null;
+                return validationReportGateError({
+                    specId,
+                    error: 'validation_report_missing',
+                    message: 'No validation-report artifact exists for this spec. Run validate to generate implementation-review evidence before marking done.',
+                    gates: [],
+                    fixHint: 'Run validate for this spec, fix any failing gates, then retry update_status(done). Use force:true only with an audited reason.',
+                });
             }
-            // Other errors (malformed file) — best-effort: allow
-            return null;
+            return validationReportGateError({
+                specId,
+                error: 'validation_report_invalid',
+                message: 'The validation-report artifact is malformed or uses an obsolete schema. Re-run validate so Planu can generate reviewer evidence.',
+                gates: [],
+                fixHint: 'Re-run validate for this spec. The report must include reviewer evidence and passing gates.',
+            });
         }
         if (!result.payload.passed) {
-            const artifactPath = `external Planu project data: handoffs/${specId}/validation-report.json`;
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            error: 'validation_report_failed',
-                            message: `Validation report at ${artifactPath} has passed: false — fix all failing gates before marking done.`,
-                            artifactPath,
-                            gates: result.payload.gates,
-                            fixHint: 'Fix all failing gates and re-run validation, then retry update_status(done). Use force:true to bypass.',
-                        }, null, 2),
-                    },
-                ],
-                isError: true,
-                structuredContent: {
-                    error: 'validation_report_failed',
-                    code: 422,
-                    context: { specId, artifactPath, gates: result.payload.gates },
-                    fixHint: 'Fix failing gates and re-run validation. Use force:true to bypass.',
-                },
-            };
+            return validationReportGateError({
+                specId,
+                error: 'validation_report_failed',
+                message: 'Validation report has passed:false — fix all failing gates before marking done.',
+                gates: result.payload.gates,
+                fixHint: 'Fix failing gates and re-run validate before marking done.',
+            });
+        }
+        if (result.payload.reviewer.verdict !== 'approved' ||
+            result.payload.reviewer.agent.trim().length === 0) {
+            return validationReportGateError({
+                specId,
+                error: 'validation_report_reviewer_not_approved',
+                message: 'The implementation reviewer did not approve this spec. Fix the requested changes and re-run validate.',
+                gates: result.payload.gates,
+                fixHint: 'Fix reviewer findings and re-run validate before marking done.',
+            });
         }
         return null;
     }
-    catch {
-        /* best-effort — never block transition */
+    catch (err) {
+        return validationReportGateError({
+            specId,
+            error: 'validation_report_unreadable',
+            message: `Could not read validation-report artifact: ${err instanceof Error ? err.message : String(err)}`,
+            gates: [],
+            fixHint: 'Re-run validate for this spec, then retry update_status(done).',
+        });
+    }
+}
+/** SPEC-1051: Write spec-review evidence when a spec enters review. */
+export async function writeSpecReviewArtifact(spec, specId, projectId) {
+    const result = await writeSpecReviewFeedback({ projectId, specId, spec });
+    if (result.written) {
+        return null;
+    }
+    return specReviewGateError({
+        specId,
+        error: 'spec_review_write_failed',
+        message: `Could not write spec review feedback: ${result.error ?? 'unknown error'}`,
+        blockers: result.payload.blockers,
+        fixHint: 'Fix the artifact store issue, then retry update_status(review).',
+    });
+}
+/** SPEC-1051: Approval requires a dedicated spec reviewer artifact. */
+export async function checkSpecReviewGate(specId, projectId, _forceApprove) {
+    try {
+        const { readArtifact } = await import('../../engine/handoff-artifacts/io.js');
+        const result = await readArtifact({ projectId, specId, kind: 'review_feedback' });
+        if (!result.ok) {
+            const firstErr = result.errors[0];
+            return specReviewGateError({
+                specId,
+                error: firstErr?.code === 'ARTIFACT_NOT_FOUND' ? 'spec_review_missing' : 'spec_review_invalid',
+                message: firstErr?.code === 'ARTIFACT_NOT_FOUND'
+                    ? 'No spec review feedback exists for this spec. Move it to review so planu-spec-reviewer can review it before approval.'
+                    : 'Spec review feedback is malformed or uses an obsolete schema. Re-run update_status(review).',
+                blockers: [],
+                fixHint: firstErr?.code === 'ARTIFACT_NOT_FOUND'
+                    ? 'Run update_status(review), resolve any review blockers, then retry update_status(approved).'
+                    : 'Re-run update_status(review) to regenerate reviewer evidence, then retry approval.',
+            });
+        }
+        const review = result.payload;
+        if (review.verdict !== 'approved' || review.reviewer.verdict !== 'approved') {
+            return specReviewGateError({
+                specId,
+                error: 'spec_review_changes_requested',
+                message: 'Spec reviewer requested changes. Approval is blocked until the review passes.',
+                blockers: review.blockers,
+                fixHint: 'Resolve the spec review blockers, rerun update_status(review), then retry approval.',
+            });
+        }
+        if (review.reviewer.kind !== 'spec-review-agent' ||
+            review.reviewer.agent !== 'planu-spec-reviewer') {
+            return specReviewGateError({
+                specId,
+                error: 'spec_review_wrong_reviewer',
+                message: 'Approval requires a dedicated spec reviewer. The implementation reviewer cannot approve the spec plan.',
+                blockers: [`Reviewer was ${review.reviewer.agent}. Expected planu-spec-reviewer.`],
+                fixHint: 'Run update_status(review) so planu-spec-reviewer writes a fresh review artifact.',
+            });
+        }
         return null;
     }
+    catch (err) {
+        return specReviewGateError({
+            specId,
+            error: 'spec_review_unreadable',
+            message: `Could not read spec review feedback: ${err instanceof Error ? err.message : String(err)}`,
+            blockers: [],
+            fixHint: 'Re-run update_status(review), then retry update_status(approved).',
+        });
+    }
+}
+function validationReportGateError(args) {
+    const artifactPath = `external Planu project data: handoffs/${args.specId}/validation-report.json`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    error: args.error,
+                    message: args.message,
+                    artifactPath,
+                    gates: args.gates,
+                    fixHint: args.fixHint,
+                }, null, 2),
+            },
+        ],
+        isError: true,
+        structuredContent: {
+            error: args.error,
+            code: 422,
+            context: { specId: args.specId, artifactPath, gates: args.gates },
+            fixHint: args.fixHint,
+        },
+    };
+}
+function specReviewGateError(args) {
+    const artifactPath = `external Planu project data: handoffs/${args.specId}/review_feedback.md`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    error: args.error,
+                    message: args.message,
+                    artifactPath,
+                    blockers: args.blockers,
+                    fixHint: args.fixHint,
+                }, null, 2),
+            },
+        ],
+        isError: true,
+        structuredContent: {
+            error: args.error,
+            code: 422,
+            context: { specId: args.specId, artifactPath, blockers: args.blockers },
+            fixHint: args.fixHint,
+        },
+    };
 }
 /**
  * SPEC-335: Combined done-gates runner — DoD + security.
@@ -309,11 +449,6 @@ export async function checkDoneGates(spec, specId, projectId, projectPath, force
         if (secError) {
             return { blocked: secError, forcedBypassWarning: null };
         }
-        // SPEC-725: Check validation-report artifact gate
-        const validationReportError = await checkValidationReportGate(specId, projectId, false);
-        if (validationReportError) {
-            return { blocked: validationReportError, forcedBypassWarning: null };
-        }
         return { blocked: null, forcedBypassWarning: null };
     }
     // force=true: run DoD in audit mode — collect results but do not block

package/dist/tools/update-status/index.js

@@ -13,7 +13,7 @@ import { checkApprovedDepGate } from '../../engine/dep-guard/index.js';
 import { checkApprovalGate } from '../../engine/approval-workflow.js';
 import * as approvalStore from '../../storage/approval-store.js';
 import { isLocked, getLock } from '../../storage/spec-lock-store.js';
-import { runValidateGate, checkDoneGates, checkComplianceGate, checkQaGate, checkApprovedFormatGate, } from './dod-gates.js';
+import { runValidateGate, checkDoneGates, checkComplianceGate, checkQaGate, checkApprovedFormatGate, checkValidationReportGate, checkSpecReviewGate, writeSpecReviewArtifact, } from './dod-gates.js';
 import { buildStatusResponse, buildValidateBlockedResponse, buildDryRunResponse, } from './response-builder.js';
 import { getSuggestedMode } from './mode-hints.js';
 import { autoFillActuals, createDefaultActuals } from '../../engine/actuals-estimator.js';
@@ -398,6 +398,18 @@ export async function handleUpdateStatus(params, server) {
                 if (challengeGate) {
                     return challengeGate;
                 }
+                if (newStatus === 'review') {
+                    const specReviewWriteError = await writeSpecReviewArtifact(spec, specId, projectId);
+                    if (specReviewWriteError) {
+                        return specReviewWriteError;
+                    }
+                }
+                if (newStatus === 'approved') {
+                    const specReviewError = await checkSpecReviewGate(specId, projectId, params.forceApprove);
+                    if (specReviewError) {
+                        return specReviewError;
+                    }
+                }
                 // SPEC-595: Elicit confirmation for destructive status transitions (→done with forceStatus)
                 const elicitResult = await runForceStatusElicitation(server, specId, newStatus, params.forceStatus);
                 if (elicitResult) {
@@ -477,7 +489,7 @@ export async function handleUpdateStatus(params, server) {
                     // SPEC-721: timeout lives inside runValidateGate (Promise.race) — do NOT wrap with
                     // withToolTimeout here, which would silently convert timeout into blocked:false (fail-open).
                     newStatus === 'done'
-                        ? runValidateGate(spec, effectiveGatePath ?? '', params.forceStatus ?? false, params.forceStatusReason, 9_000)
+                        ? runValidateGate(spec, effectiveGatePath ?? '', params.forceStatus ?? false, params.forceStatusReason, 9_000, { projectId, specId })
                         : Promise.resolve(null),
                     // Crash shield: only on 'done', skipped if rate-limited (SPEC-628)
                     newStatus === 'done' && effectiveGatePath && !crashShieldSkipReason
@@ -507,6 +519,12 @@ export async function handleUpdateStatus(params, server) {
                         };
                     }
                 }
+                if (newStatus === 'done' && !(params.force ?? params.forceStatus ?? false)) {
+                    const validationReportError = await checkValidationReportGate(specId, projectId, false);
+                    if (validationReportError) {
+                        return validationReportError;
+                    }
+                }
                 // Process crash shield result — record run timestamp on success (SPEC-628)
                 /* c8 ignore next */
                 if (crashRisksReport !== null) {
@@ -1033,7 +1051,7 @@ export async function handleUpdateStatus(params, server) {
                     result.cascadeFastResults = cascadeRunResult.fastHookResults;
                 }
                 // SPEC-772 Scenario 4: surface validate failure from cascade as explicit warning
-                const autopilotValidateWarning = validateScore !== null && validateScore < 70
+                const autopilotValidateWarning = validateScore !== null && validateScore < 100
                     ? `Validate score ${String(validateScore)}/100 — below threshold. Check workspace_alerts for cascade details.`
                     : null;
                 if (autopilotValidateWarning) {

package/dist/tools/update-status/response-builder.js

@@ -6,7 +6,7 @@ import { buildUpdateStatusSummary } from '../../engine/human-summary.js';
 // SPEC-721: Validate gate blocked response builder
 // ---------------------------------------------------------------------------
 const REASON_TO_FIX_HINT = {
-    validate_score_below_threshold: 'Fix failing acceptance criteria, then retry. Or use forceStatus:true + forceStatusReason (≥100 chars).',
+    validate_score_below_threshold: 'Reach 100/100 validation coverage for the spec, then retry. Or use forceStatus:true + forceStatusReason (≥100 chars).',
     validate_gate_no_criteria: 'Add `scenarios:` to the spec frontmatter (BDD format), or use check_readiness to inject ' +
         'criteria, then retry. Or use forceStatus:true + forceStatusReason (≥100 chars).',
     validate_gate_crash: 'The validate engine crashed. Inspect logs, fix the spec or engine, and retry. ' +

package/dist/tools/validate.js

@@ -14,6 +14,7 @@ import { validateContractCompliance } from '../engine/test-scaffold-generator.js
 import { parseConventions, scanConventions } from '../engine/convention-scanner/index.js';
 import { validateScopeCompliance } from '../engine/scope-boundaries/index.js';
 import { compareWithBaseline } from '../storage/convention-baseline.js';
+import { writeImplementationReviewReport } from '../engine/validator/validation-report-writer.js';
 // Re-export for external use (SPEC-018)
 export { validateContractCompliance };
 /** Build the fallback interactiveQuestion for validation failures. */
@@ -130,6 +131,16 @@ export async function handleValidate(args, server) {
     }
     // 7. Lint check (best-effort — non-blocking)
     const lintCheck = runLintCheck(projectPath, knowledge.lintCommand ?? null);
+    // SPEC-1050: Generate a mandatory implementation-review artifact.
+    const validationReport = await writeImplementationReviewReport({
+        projectId,
+        specId,
+        spec,
+        projectPath,
+        score: result.score,
+        lintPassed: lintCheck.passed,
+        conventionRegression: regressionDetected,
+    });
     // 8. Build output
     const output = {
         specId,
@@ -204,6 +215,7 @@ export async function handleValidate(args, server) {
             })),
         },
         lintCheck,
+        validationReport,
     };
     // SPEC-612: Scope boundary validation — warn if impl files match outOfScope items
     if (spec.outOfScope !== undefined && spec.outOfScope.length > 0) {

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

@@ -26,10 +26,17 @@ export interface SpecLockV1 {
 /** Reviewer → Planner: structured feedback from code review */
 export interface ReviewFeedbackV1 {
     schema_version: string;
+    specId: string;
     verdict: 'approved' | 'changes-requested';
+    reviewer: {
+        kind: 'spec-review-agent' | 'human' | 'automation';
+        agent: string;
+        verdict: 'approved' | 'changes-requested';
+    };
     blockers: string[];
     suggestions: string[];
     body: string;
+    reviewedAt: string;
 }
 /** Implementer → Validator: result of implementation run */
 export interface ImplementationReportV1 {
@@ -51,6 +58,20 @@ export interface ValidationReportV1 {
         passed: boolean;
         reason?: string;
     }[];
+    reviewer: {
+        kind: 'implementation-review-agent' | 'human' | 'automation';
+        agent: string;
+        verdict: 'approved' | 'changes-requested';
+    };
+    specCompliance?: {
+        score: number;
+        command: string;
+        scenarios: {
+            title: string;
+            verdict: 'pass' | 'fail' | 'missing';
+            evidence: string[];
+        }[];
+    };
     score?: number;
     completedAt: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.2.2",
+  "version": "4.2.4",
   "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",
@@ -32,14 +32,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.2.2",
-    "@planu/core-darwin-x64": "4.2.2",
-    "@planu/core-linux-arm64-gnu": "4.2.2",
-    "@planu/core-linux-arm64-musl": "4.2.2",
-    "@planu/core-linux-x64-gnu": "4.2.2",
-    "@planu/core-linux-x64-musl": "4.2.2",
-    "@planu/core-win32-arm64-msvc": "4.2.2",
-    "@planu/core-win32-x64-msvc": "4.2.2"
+    "@planu/core-darwin-arm64": "4.2.4",
+    "@planu/core-darwin-x64": "4.2.4",
+    "@planu/core-linux-arm64-gnu": "4.2.4",
+    "@planu/core-linux-arm64-musl": "4.2.4",
+    "@planu/core-linux-x64-gnu": "4.2.4",
+    "@planu/core-linux-x64-musl": "4.2.4",
+    "@planu/core-win32-arm64-msvc": "4.2.4",
+    "@planu/core-win32-x64-msvc": "4.2.4"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -189,7 +189,7 @@
     "happy-dom": "^20.9.0",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.4.3",
-    "knip": "^6.14.1",
+    "knip": "^6.14.2",
     "lint-staged": "^17.0.5",
     "madge": "^8.0.0",
     "prettier": "^3.8.3",