@planu/cli 5.3.50 → 5.3.51

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [5.3.51] - 2026-08-25
+
+### Bug Fixes
+- fix(evidence-gates): derive rejection templates from the rejecting schema
+
+### Chores
+- chore(planu): close SPEC-1578 and file SPEC-1601
+
+
 ## [5.3.50] - 2026-08-24
 
 ### Bug Fixes

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

@@ -1,5 +1,35 @@
+import { z } from 'zod';
 import type { Spec } from '../../types/spec/core.js';
 import type { EvidenceArtifacts, TraceabilityMatrixEvidence } from '../../types/evidence-gates.js';
+export declare const DiscoverySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    provenance: z.ZodOptional<z.ZodObject<{
+        receiptId: z.ZodString;
+        artifactDigest: z.ZodString;
+        specId: z.ZodString;
+        issuerId: z.ZodString;
+    }, z.core.$strict>>;
+    rules: z.ZodArray<z.ZodString>;
+    examples: z.ZodArray<z.ZodObject<{
+        rule: z.ZodString;
+        example: z.ZodString;
+    }, z.core.$strict>>;
+    openQuestions: z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        status: z.ZodEnum<{
+            open: "open";
+            out_of_scope: "out_of_scope";
+            resolved: "resolved";
+        }>;
+        resolution: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    outOfScope: z.ZodArray<z.ZodString>;
+    glossary: z.ZodArray<z.ZodObject<{
+        term: z.ZodString;
+        meaning: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const DISCOVERY_TEMPLATE_OVERRIDES: Record<string, unknown>;
 /** Digest of canonical artifact content; the provenance envelope is excluded. */
 export declare function evidenceArtifactDigest(artifact: unknown): string;
 export declare function evidenceArtifactCollectionDigest(artifacts: readonly {

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

@@ -7,6 +7,7 @@ import { z } from 'zod';
 import { projectDataDir } from '../../storage/base-store.js';
 import { computeValidationEvidenceIdentity, computeValidationEvidenceKey, normalizeValidationCommand, readMatchingValidationEvidence, } from '../validation-evidence-ledger.js';
 import { VALIDATION_COMMANDS } from '../validation-impact-planner.js';
+import { renderSchemaSkeleton } from '../handoff-artifacts/schema-skeleton.js';
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const SPEC_ID = /^SPEC-[1-9]\d*$/u;
 const ISSUER_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
@@ -33,7 +34,7 @@ const ProvenanceSchema = z
     issuerId: z.string().regex(ISSUER_ID),
 })
     .strict();
-const DiscoverySchema = z
+export const DiscoverySchema = z
     .object({
     version: z.literal(1),
     provenance: ProvenanceSchema.optional(),
@@ -56,6 +57,9 @@ const DiscoverySchema = z
         .max(200),
 })
     .strict();
+export const DISCOVERY_TEMPLATE_OVERRIDES = {
+    'openQuestions[].status': 'resolved',
+};
 const TaskPlanSchema = z
     .object({
     version: z.literal(1),
@@ -244,56 +248,6 @@ const ARTIFACT_HINTS = {
 function artifactHint(label) {
     return ARTIFACT_HINTS[label] ?? '';
 }
-/**
- * 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);
@@ -329,7 +283,9 @@ async function readOptional(args) {
             const allIssues = parsed.error.issues
                 .map((issue) => `${issue.path.length > 0 ? issue.path.join('.') : '(root)'}: ${issue.message}`)
                 .join('; ');
-            const example = artifactExample(args.label);
+            const example = args.template === false
+                ? ''
+                : renderSchemaSkeleton(args.schema, { overrides: args.templateOverrides });
             args.invalidArtifacts.push(`${args.label} is invalid at ${found.path}: ${allIssues} ${artifactHint(args.label)}${example ? ` Expected shape example: ${example}` : ''}`.trim());
             return undefined;
         }
@@ -340,6 +296,29 @@ async function readOptional(args) {
         return undefined;
     }
 }
+const CONTRACT_VALIDATION_KIND_BY_FILENAME = {
+    'contract-validation-api.json': 'api',
+    'contract-validation-graphql.json': technologyValue('technology-graphql-aed31c'),
+    'contract-validation-event.json': 'event',
+    'contract-validation-ui.json': 'ui',
+    'contract-validation-mcp.json': 'mcp',
+};
+async function readContractValidations(args, invalidArtifacts, contractProvenance) {
+    const contractValidations = [];
+    for (const filename of Object.keys(CONTRACT_VALIDATION_KIND_BY_FILENAME)) {
+        const evidence = await readOptional({
+            label: filename,
+            invalidArtifacts,
+            schema: ContractValidationSchema,
+            paths: [handoffEvidencePath(args.projectId, args.specId, filename)],
+            templateOverrides: { kind: CONTRACT_VALIDATION_KIND_BY_FILENAME[filename] },
+        });
+        if (evidence) {
+            contractValidations.push(contractProvenance ? { ...evidence, provenance: contractProvenance } : evidence);
+        }
+    }
+    return contractValidations;
+}
 export async function readEvidenceArtifacts(args) {
     const invalidArtifacts = [];
     const discovery = await readOptional({
@@ -347,6 +326,7 @@ export async function readEvidenceArtifacts(args) {
         invalidArtifacts,
         schema: DiscoverySchema,
         paths: [handoffEvidencePath(args.projectId, args.specId, 'discovery.json')],
+        templateOverrides: DISCOVERY_TEMPLATE_OVERRIDES,
     });
     const taskPlan = await readOptional({
         label: 'Task plan evidence',
@@ -359,6 +339,11 @@ export async function readEvidenceArtifacts(args) {
         invalidArtifacts,
         schema: TraceabilityMatrixSchema,
         paths: [handoffEvidencePath(args.projectId, args.specId, 'traceability-matrix.json')],
+        templateOverrides: {
+            'rows[].testEvidence': ['example'],
+            'rows[].validationEvidence': 'example',
+            'rows[].reviewerEvidence': 'example',
+        },
     });
     const [discoveryProvenance, taskPlanProvenance, traceabilityProvenance, contractProvenance] = await Promise.all([
         'discovery.provenance.json',
@@ -370,25 +355,9 @@ export async function readEvidenceArtifacts(args) {
         invalidArtifacts,
         schema: ProvenanceSchema,
         paths: [handoffEvidencePath(args.projectId, args.specId, filename)],
+        template: false,
     })));
-    const contractValidations = [];
-    for (const filename of [
-        'contract-validation-api.json',
-        'contract-validation-graphql.json',
-        'contract-validation-event.json',
-        'contract-validation-ui.json',
-        'contract-validation-mcp.json',
-    ]) {
-        const evidence = await readOptional({
-            label: filename,
-            invalidArtifacts,
-            schema: ContractValidationSchema,
-            paths: [handoffEvidencePath(args.projectId, args.specId, filename)],
-        });
-        if (evidence) {
-            contractValidations.push(contractProvenance ? { ...evidence, provenance: contractProvenance } : evidence);
-        }
-    }
+    const contractValidations = await readContractValidations(args, invalidArtifacts, contractProvenance);
     return {
         discovery: discovery && discoveryProvenance
             ? { ...discovery, provenance: discoveryProvenance }

package/dist/engine/evidence-gates/lifecycle-gate.js

@@ -1,5 +1,6 @@
 import { isAbsolute, join } from 'node:path';
-import { evidenceArtifactCollectionDigest, evidenceArtifactDigest } from './artifact-reader.js';
+import { DISCOVERY_TEMPLATE_OVERRIDES, DiscoverySchema, evidenceArtifactCollectionDigest, evidenceArtifactDigest, } from './artifact-reader.js';
+import { renderSchemaSkeleton } from '../handoff-artifacts/schema-skeleton.js';
 import { hasAnyAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../text-signal-boundaries.js';
 import { createCriterionIdentity } from '../criterion-identity.js';
 import { computeDurableValidationBindings, doneReceiptBindingsDifferOnlyInEvidence, toValidationReceiptBindings, writeValidationArtifactProvenance, } from '../validation/durable-validation.js';
@@ -140,6 +141,9 @@ export function inferRequiredContractEvidence(spec, criteria) {
     }
     return required;
 }
+const DISCOVERY_TEMPLATE = renderSchemaSkeleton(DiscoverySchema, {
+    overrides: DISCOVERY_TEMPLATE_OVERRIDES,
+});
 export function checkDiscoveryGate(spec, artifacts) {
     if (!isNonTrivial(spec)) {
         return [];
@@ -148,7 +152,8 @@ export function checkDiscoveryGate(spec, artifacts) {
     if (!artifacts.discovery) {
         issues.push({
             code: 'discovery_missing',
-            message: 'Discovery evidence is required before approval. Add discovery.json with rules, examples, open questions, out-of-scope boundaries, and glossary.',
+            message: 'Discovery evidence is required before approval. Add discovery.json with rules, examples, open questions, out-of-scope boundaries, and glossary.' +
+                (DISCOVERY_TEMPLATE ? ` Expected shape example: ${DISCOVERY_TEMPLATE}` : ''),
         });
         return issues;
     }

package/dist/engine/handoff-artifacts/schema-skeleton.d.ts

@@ -0,0 +1,5 @@
+import type { z } from 'zod';
+export declare function renderSchemaSkeleton(schema: z.ZodType, options?: {
+    overrides?: Record<string, unknown>;
+}): string;
+//# sourceMappingURL=schema-skeleton.d.ts.map

package/dist/engine/handoff-artifacts/schema-skeleton.js

@@ -0,0 +1,108 @@
+const MAX_TEMPLATE_LENGTH = 600;
+const OMIT_FIELD = Symbol('omit-field');
+class UnsupportedSchemaNodeError extends Error {
+}
+function runtimeDef(schema) {
+    const zodInternals = schema?._zod;
+    const def = zodInternals?.def;
+    if (!def || typeof def.type !== 'string') {
+        throw new UnsupportedSchemaNodeError();
+    }
+    return def;
+}
+function buildObjectValue(def) {
+    const shape = (def.shape ?? {});
+    const result = {};
+    for (const [key, propSchema] of Object.entries(shape)) {
+        const value = buildNodeValue(propSchema);
+        if (value !== OMIT_FIELD) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function buildNodeValue(schema) {
+    const def = runtimeDef(schema);
+    switch (def.type) {
+        case 'object':
+            return buildObjectValue(def);
+        case 'array': {
+            const element = buildNodeValue(def.element);
+            if (element === OMIT_FIELD) {
+                throw new UnsupportedSchemaNodeError();
+            }
+            return [element];
+        }
+        case 'enum': {
+            const entries = def.entries;
+            const firstOption = entries ? Object.values(entries)[0] : undefined;
+            if (firstOption === undefined) {
+                throw new UnsupportedSchemaNodeError();
+            }
+            return firstOption;
+        }
+        case 'literal': {
+            const values = def.values;
+            const firstValue = values?.[0];
+            if (firstValue === undefined) {
+                throw new UnsupportedSchemaNodeError();
+            }
+            return firstValue;
+        }
+        case 'string':
+            return 'example';
+        case 'number':
+            return 1;
+        case 'boolean':
+            return true;
+        case 'optional':
+            return OMIT_FIELD;
+        default:
+            throw new UnsupportedSchemaNodeError();
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function applyOverrideAtPath(node, segments, value) {
+    const [head, ...rest] = segments;
+    if (head === undefined) {
+        return value;
+    }
+    const arrayMatch = /^(.+)\[\]$/u.exec(head);
+    if (arrayMatch) {
+        const [, key] = arrayMatch;
+        if (key === undefined || !isPlainObject(node) || !Array.isArray(node[key])) {
+            return node;
+        }
+        return {
+            ...node,
+            [key]: node[key].map((element) => applyOverrideAtPath(element, rest, value)),
+        };
+    }
+    if (!isPlainObject(node)) {
+        return node;
+    }
+    return { ...node, [head]: applyOverrideAtPath(node[head], rest, value) };
+}
+function applyOverrides(skeleton, overrides) {
+    return Object.entries(overrides).reduce((node, [path, value]) => applyOverrideAtPath(node, path.split('.'), value), skeleton);
+}
+export function renderSchemaSkeleton(schema, options = {}) {
+    try {
+        const skeleton = buildNodeValue(schema);
+        if (skeleton === OMIT_FIELD) {
+            return '';
+        }
+        const withOverrides = applyOverrides(skeleton, options.overrides ?? {});
+        const json = JSON.stringify(withOverrides);
+        return json.length <= MAX_TEMPLATE_LENGTH ? json : '';
+    }
+    catch (err) {
+        if (err instanceof UnsupportedSchemaNodeError) {
+            return '';
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=schema-skeleton.js.map

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

@@ -4,6 +4,9 @@ import type { EscalateResult } from '../../types/escalator.js';
 import type { ValidationFreshnessLease } from '../../engine/validation/validation-freshness.js';
 import { type DoneReceiptVerifier } from './done-receipt-verifier.js';
 export { completedJobPublishesReceipt } from './done-receipt-verifier.js';
+export declare const reviewFeedbackTemplate: () => string;
+export declare const implementationReviewTemplate: () => string;
+export declare const validationReportTemplate: () => string;
 /**
  * The reason why the validate gate blocked a `done` transition.
  * Each reason maps to a specific fix-hint shown to the LLM.

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

@@ -18,8 +18,40 @@ import { reportClassifiedDegradation } from '../../errors/classified-degradation
 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';
+import { ImplementationReviewV1Schema, ReviewFeedbackV1Schema, ValidationReportV1Schema, } from '../../engine/handoff-artifacts/schemas.js';
+import { renderSchemaSkeleton } from '../../engine/handoff-artifacts/schema-skeleton.js';
 export { completedJobPublishesReceipt } from './done-receipt-verifier.js';
+const HANDOFF_ARTIFACT_TEMPLATE_TIMESTAMP = '2026-01-01T00:00:00.000Z';
+const HANDOFF_ARTIFACT_TEMPLATE_SCHEMA_VERSION = '1.0.0';
+function lazyTemplate(render) {
+    let cached;
+    return () => {
+        cached ??= render();
+        return cached;
+    };
+}
+export const reviewFeedbackTemplate = lazyTemplate(() => renderSchemaSkeleton(ReviewFeedbackV1Schema, {
+    overrides: {
+        schema_version: HANDOFF_ARTIFACT_TEMPLATE_SCHEMA_VERSION,
+        reviewedAt: HANDOFF_ARTIFACT_TEMPLATE_TIMESTAMP,
+        'reviewer.agent': 'planu-spec-reviewer',
+    },
+}));
+export const implementationReviewTemplate = lazyTemplate(() => renderSchemaSkeleton(ImplementationReviewV1Schema, {
+    overrides: {
+        schema_version: HANDOFF_ARTIFACT_TEMPLATE_SCHEMA_VERSION,
+        reviewedAt: HANDOFF_ARTIFACT_TEMPLATE_TIMESTAMP,
+        'reviewer.agent': 'planu-implementation-reviewer',
+    },
+}));
+export const validationReportTemplate = lazyTemplate(() => renderSchemaSkeleton(ValidationReportV1Schema, {
+    overrides: {
+        schema_version: HANDOFF_ARTIFACT_TEMPLATE_SCHEMA_VERSION,
+        completedAt: HANDOFF_ARTIFACT_TEMPLATE_TIMESTAMP,
+        'reviewer.agent': AUTOMATED_VALIDATOR_AGENT,
+        'reviewer.kind': 'automation',
+    },
+}));
 /**
  * SPEC-721 / SPEC-222 Trigger 1: Run validate engine before marking done.
  *
@@ -482,6 +514,7 @@ export async function readApprovedValidationReportGate(specId, projectId, force)
                         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.',
+                        template: validationReportTemplate(),
                     }),
                 };
             }
@@ -493,6 +526,7 @@ export async function readApprovedValidationReportGate(specId, projectId, force)
                     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.',
+                    template: validationReportTemplate(),
                 }),
             };
         }
@@ -572,6 +606,7 @@ export async function checkSpecReviewGate(specId, projectId, _forceApprove) {
                 fixHint: firstErr?.code === 'ARTIFACT_NOT_FOUND'
                     ? 'Have planu-spec-reviewer write review_feedback.md (ReviewFeedbackV1) into the handoff store, then retry update_status(approved).'
                     : 'Have planu-spec-reviewer rewrite review_feedback.md as valid ReviewFeedbackV1 evidence, then retry approval.',
+                template: reviewFeedbackTemplate(),
             });
         }
         const review = result.payload;
@@ -635,6 +670,7 @@ export async function checkImplementationReviewGate(specId, projectId, _force) {
                 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.',
+                template: implementationReviewTemplate(),
             });
         }
         const review = result.payload;
@@ -724,6 +760,7 @@ function implementationReviewGateError(args) {
             code: 422,
             context: { specId: args.specId, artifactPath, blockers: args.blockers },
             fixHint: args.fixHint,
+            ...(args.template ? { template: args.template } : {}),
         },
     };
 }
@@ -749,6 +786,7 @@ function validationReportGateError(args) {
             code: 422,
             context: { specId: args.specId, artifactPath, gates: args.gates },
             fixHint: args.fixHint,
+            ...(args.template ? { template: args.template } : {}),
         },
     };
 }
@@ -774,6 +812,7 @@ function specReviewGateError(args) {
             code: 422,
             context: { specId: args.specId, artifactPath, blockers: args.blockers },
             fixHint: args.fixHint,
+            ...(args.template ? { template: args.template } : {}),
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.50",
+  "version": "5.3.51",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",

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.50",
+  "version": "5.3.51",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",