@planu/cli 4.2.3 → 4.2.4

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [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`

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;
@@ -60,8 +74,8 @@ export declare const ValidationReportV1Schema: z.ZodObject<{
     reviewer: z.ZodObject<{
         kind: z.ZodEnum<{
             human: "human";
-            "implementation-review-agent": "implementation-review-agent";
             automation: "automation";
+            "implementation-review-agent": "implementation-review-agent";
         }>;
         agent: z.ZodString;
         verdict: z.ZodEnum<{
@@ -115,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;
@@ -144,8 +172,8 @@ export declare const ARTIFACT_SCHEMAS: {
         reviewer: z.ZodObject<{
             kind: z.ZodEnum<{
                 human: "human";
-                "implementation-review-agent": "implementation-review-agent";
                 automation: "automation";
+                "implementation-review-agent": "implementation-review-agent";
             }>;
             agent: z.ZodString;
             verdict: z.ZodEnum<{

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,

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/tools/update-status/dod-gates.d.ts

@@ -78,6 +78,10 @@ export interface DoneGateResult {
  * 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

@@ -9,6 +9,7 @@ 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.
  *
@@ -320,6 +321,71 @@ export async function checkValidationReportGate(specId, projectId, force) {
         });
     }
 }
+/** 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 {
@@ -344,6 +410,30 @@ function validationReportGateError(args) {
         },
     };
 }
+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.
  * When force=true, gates are not blocking but failing items are recorded in

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, checkValidationReportGate, } 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) {

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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.2.3",
+  "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.3",
-    "@planu/core-darwin-x64": "4.2.3",
-    "@planu/core-linux-arm64-gnu": "4.2.3",
-    "@planu/core-linux-arm64-musl": "4.2.3",
-    "@planu/core-linux-x64-gnu": "4.2.3",
-    "@planu/core-linux-x64-musl": "4.2.3",
-    "@planu/core-win32-arm64-msvc": "4.2.3",
-    "@planu/core-win32-x64-msvc": "4.2.3"
+    "@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"