@planu/cli 5.7.5 → 5.7.6

package/dist/config/subagent-templates/planu-spec-implementer.md

@@ -12,9 +12,7 @@ tools:
   - mcp__planu__update_status
   - mcp__planu__validate
   - mcp__planu__get_job
-  - mcp__planu__watch_job
   - mcp__planu__check_readiness
-  - mcp__planu__tdd_scaffold
 ---
 
 # Planu Spec Implementer
@@ -32,11 +30,11 @@ You are an autonomous implementation agent for Spec Driven Development. Your job
 2. **Verify approval** — confirm spec status is `approved`. If not, call `check_readiness` and stop with a note.
 3. **Update status to `implementing`** — call `update_status({ specId, status: "implementing" })`.
 4. **Create a feature branch** — `git checkout -b feat/SPEC-NNN-slug`.
-5. **Scaffold TDD tests** — call `tdd_scaffold` to generate test stubs from acceptance criteria.
+5. **Write TDD tests** — write failing test stubs mirroring `src/` in `tests/`, one per acceptance criterion.
 6. **Implement** — write all source files in dependency order: types → engine → storage → tools/resources. Follow Clean Architecture (types layer imports nothing; tools import engine+storage+types).
 7. **Run tests** — `pnpm typecheck && pnpm lint && pnpm test:coverage`. Fix all failures.
 8. **Submit validation** — call `validate({ specId })` and capture `operationId`, `projectId`, `workspaceId`, and `cursor` from the durable acknowledgement.
-9. **Await and inspect** — call `watch_job` with those identifiers and the latest cursor until terminal. Require `completed`, then inspect `job.result.structuredContent`. Stop on `failed`, `dead-letter`, or `cancelled`; fix failures and submit a new validation job.
+9. **Await and inspect** — poll `get_job` with those identifiers and the latest cursor until terminal. Require `completed`, then inspect `job.result.structuredContent`. Stop on `failed`, `dead-letter`, or `cancelled`; fix failures and submit a new validation job.
 10. **Commit** — only after the completed validation result reports `ready: true`, `status: "passing"`, and passing quality gates, run `git add <files> && git commit -m "feat(SPEC-NNN): <title>"`.
 11. **Update status to `done`** — call `update_status({ specId, status: "done" })` only after that completed passing result.
 

package/dist/config/subagent-templates/planu-validator.md

@@ -8,11 +8,9 @@ tools:
   - Grep
   - mcp__planu__validate
   - mcp__planu__get_job
-  - mcp__planu__watch_job
   - mcp__planu__list_specs
-  - mcp__planu__spec_health_check
   - mcp__planu__check_readiness
-  - mcp__planu__auto_fix_validation
+  - mcp__planu__restart_job
 ---
 
 # Planu Validator
@@ -29,15 +27,14 @@ You are a validation specialist. Your job is to verify that implemented code sat
 
 1. **Load spec** — call `list_specs` and read `spec.md` for all acceptance criteria.
 2. **Submit validation** — call `validate({ specId })` and capture `operationId`, `projectId`, `workspaceId`, and `cursor` from the durable acknowledgement.
-3. **Wait for the terminal result** — call `watch_job` with those identifiers and the latest cursor. Repeat while state is `accepted`, `running`, or `checkpointed`. Require `completed`; stop and report `failed`, `dead-letter`, or `cancelled`.
+3. **Wait for the terminal result** — poll `get_job` with those identifiers and the latest cursor. Repeat while state is `accepted`, `running`, or `checkpointed`. Require `completed`; stop and report `failed`, `dead-letter`, or `cancelled`.
 4. **Read the validation result** — inspect `job.result.structuredContent`. The acknowledgement is not a pass/fail result.
-5. **Run health check** — call `spec_health_check({ specId })` for structural issues.
-6. **Assess gaps** — for each failing criterion:
+5. **Assess gaps** — for each failing criterion:
    - Identify which source files are responsible
    - Diagnose the root cause (missing logic, wrong condition, untested branch)
    - Propose a minimal fix
-7. **Auto-fix when safe** — call `auto_fix_validation` for fixable issues, then submit and await a new validation job.
-8. **Report** — provide a summary with: passing count, failing count, and concrete next steps for each failure.
+6. **Fix and re-validate** — fix the underlying code or test, then call `validate({ specId })` again and poll `get_job` until terminal; use `restart_job` if the job itself failed or was cancelled rather than the criteria.
+7. **Report** — provide a summary with: passing count, failing count, and concrete next steps for each failure.
 
 ## Output format
 

package/dist/config/tool-groups.json

@@ -3,22 +3,8 @@
     {
       "id": "core",
       "name": "Core",
-      "description": "The 9 Tier 1 tools every new user needs: project setup, spec creation, lifecycle management, and status.",
-      "tools": [
-        "facilitate",
-        "init_project",
-        "create_spec",
-        "list_specs",
-        "update_status",
-        "validate",
-        "planu_status",
-        "capture_idea",
-        "quick_start",
-        "set_locale",
-        "init_constitution",
-        "activate_group",
-        "list_groups"
-      ],
+      "description": "The Tier 1 tools every new user needs: project setup, spec creation, lifecycle management, and status.",
+      "tools": ["facilitate", "init_project", "create_spec", "list_specs", "update_status", "validate", "planu_status"],
       "defaultEnabled": true,
       "locked": true
     },
@@ -26,143 +12,19 @@
       "id": "spec-lifecycle",
       "name": "Spec Lifecycle",
       "description": "Create, validate, estimate, and manage specs through their full lifecycle.",
-      "tools": [
-        "estimate",
-        "request_changes",
-        "challenge_spec",
-        "check_readiness",
-        "clarify_requirements",
-        "summarize_spec",
-        "reconcile_spec",
-        "reconcile_hooks",
-        "reconcile_rules",
-        "reconcile_skills",
-        "config_health",
-        "list_templates",
-        "apply_template",
-        "spec_history",
-        "log_decision"
-      ],
+      "tools": ["estimate", "request_changes", "challenge_spec", "check_readiness", "reconcile_spec"],
       "defaultEnabled": true,
       "locked": false,
       "triggerTools": ["estimate", "challenge_spec", "check_readiness"]
     },
-    {
-      "id": "analysis",
-      "name": "Analysis",
-      "description": "Audit, drift detection, contradiction checks, and deep code analysis.",
-      "tools": [
-        "audit",
-        "audit_stack",
-        "detect_drift",
-        "detect_contradictions",
-        "detect_deprecations",
-        "detect_agent",
-        "reality_check",
-        "check_spec_accuracy",
-        "paradigm_report",
-        "spec_coverage",
-        "validate_annotations",
-        "generate_annotations",
-        "snapshot_spec_hashes",
-        "auto_reconcile",
-        "living_spec_watch",
-        "living_spec_status",
-        "spec_diff",
-        "living_spec_coverage",
-        "sync_spec_to_code",
-        "sync_code_to_spec",
-        "resolve_sync_conflict"
-      ],
-      "defaultEnabled": false,
-      "locked": false,
-      "triggerTools": ["audit", "detect_drift", "reality_check"]
-    },
-    {
-      "id": "generation",
-      "name": "Generation",
-      "description": "Generate docs, tests, schemas, UI contracts, skills, rules, and ADRs.",
-      "tools": [
-        "generate_docs",
-        "generate_tests",
-        "design_schema",
-        "define_ui_contract",
-        "generate_adr",
-        "generate_checklist",
-        "generate_rules",
-        "generate_skill",
-        "generate_sub_agent",
-        "consult_docs",
-        "event_contracts"
-      ],
-      "defaultEnabled": false,
-      "locked": false,
-      "triggerTools": ["generate_docs", "generate_tests", "design_schema"]
-    },
     {
       "id": "orchestration",
       "name": "Orchestration",
-      "description": "Multi-agent orchestration, execution plans, handoff packages, and AI cost estimation.",
-      "tools": [
-        "orchestrate",
-        "orchestrate_agents",
-        "package_handoff",
-        "generate_execution_plan",
-        "generate_orchestration_script",
-        "estimate_ai_cost",
-        "integrate_pm"
-      ],
-      "defaultEnabled": false,
-      "locked": false,
-      "triggerTools": ["orchestrate", "orchestrate_agents", "generate_execution_plan"]
-    },
-    {
-      "id": "devops",
-      "name": "DevOps",
-      "description": "Git management, tooling suggestions, CI generation, upgrades, and stack recommendations.",
-      "tools": [
-        "manage_git",
-        "suggest_tooling",
-        "suggest_stack",
-        "suggest_mcps",
-        "suggest_mcp_server",
-        "plan_upgrade",
-        "check_versions",
-        "check_config_health",
-        "generate_ci",
-        "discover_mcps",
-        "validate_workflow"
-      ],
-      "defaultEnabled": false,
-      "locked": false,
-      "triggerTools": ["manage_git", "suggest_tooling", "generate_ci"]
-    },
-    {
-      "id": "governance",
-      "name": "Governance",
-      "description": "Security checks, data governance, scope management, and context control.",
-      "tools": [
-        "security_check",
-        "data_governance",
-        "legal_compliance_report",
-        "manage_scope",
-        "manage_context",
-        "context_budget",
-        "request_context",
-        "contribute_context"
-      ],
-      "defaultEnabled": false,
-      "locked": false,
-      "triggerTools": ["security_check", "data_governance", "manage_scope"]
-    },
-    {
-      "id": "learning",
-      "name": "Learning",
-      "description": "Pattern learning, knowledge capture, reverse engineering, and migration.",
-      "tools": ["learn_pattern", "capture_learning", "reverse_engineer", "migrate_tech", "manage_hooks"],
+      "description": "Handoff packages for implementation agents.",
+      "tools": ["package_handoff"],
       "defaultEnabled": false,
       "locked": false,
-      "triggerTools": ["learn_pattern", "capture_learning", "reverse_engineer"]
+      "triggerTools": ["package_handoff"]
     }
   ]
 }

package/dist/engine/ambiguity-scorer.js

@@ -40,6 +40,44 @@ function buildSuggestion(term, criterion) {
     const clean = criterion.slice(0, 80);
     return `Replace "${term}" with a concrete measurable value, e.g.: "${clean.replace(new RegExp(`\\b${term}\\b`, 'gi'), `<${term}_value>`)}"`;
 }
+const ENUM_LITERAL_TOKEN = /^[A-Za-z0-9_.-]+$/;
+const NON_WORD_MASK_CHAR = '#';
+function maskSpan(span) {
+    return span.replace(/\S/g, NON_WORD_MASK_CHAR);
+}
+function maskLiteralSpans(line) {
+    let masked = '';
+    let cursor = 0;
+    while (cursor < line.length) {
+        const char = line.charAt(cursor);
+        if (char === '`') {
+            const closeIndex = line.indexOf('`', cursor + 1);
+            if (closeIndex === -1) {
+                masked += line.slice(cursor);
+                break;
+            }
+            masked += maskSpan(line.slice(cursor, closeIndex + 1));
+            cursor = closeIndex + 1;
+            continue;
+        }
+        if (char === '"') {
+            const closeIndex = line.indexOf('"', cursor + 1);
+            if (closeIndex === -1) {
+                masked += line.slice(cursor);
+                break;
+            }
+            const content = line.slice(cursor + 1, closeIndex);
+            masked += ENUM_LITERAL_TOKEN.test(content)
+                ? maskSpan(line.slice(cursor, closeIndex + 1))
+                : line.slice(cursor, closeIndex + 1);
+            cursor = closeIndex + 1;
+            continue;
+        }
+        masked += char;
+        cursor += 1;
+    }
+    return masked;
+}
 function hasAdjacentNumber(line, term) {
     // Check if a number appears within 4 words of the vague term
     const words = line.toLowerCase().split(/\s+/);
@@ -63,10 +101,11 @@ export function scoreAmbiguity(criteriaLines) {
             continue;
         }
         const lower = line.toLowerCase();
+        const maskedLower = maskLiteralSpans(line).toLowerCase();
         // Check vague units (skip if adjacent number is present)
         for (const [term, reason] of Object.entries(VAGUE_UNITS)) {
             const pattern = new RegExp(`\\b${term}\\b`);
-            if (pattern.test(lower) && !hasAdjacentNumber(lower, term)) {
+            if (pattern.test(maskedLower) && !hasAdjacentNumber(maskedLower, term)) {
                 violations.push({
                     term,
                     criterion: line.slice(0, 120),

package/dist/engine/autopilot/bootstrap.js

@@ -106,7 +106,7 @@ function registerPluginInstalledListener() {
 /**
  * SPEC-1345 AC4: Fire-and-forget semantic index refresh on spec:created.
  * Reconciles the persisted TF-IDF index against the current corpus so the next
- * semantic_search call hits a warm, up-to-date index.
+ * internal pattern-learning lookup hits a warm, up-to-date index.
  */
 function registerSemanticIndexRefreshListener() {
     onAutopilotEvent('spec:created', (event) => {

package/dist/engine/code-impact-analyzer.js

@@ -1,5 +1,5 @@
 // engine/code-impact-analyzer.ts — Code Change → Spec Impact Analyzer (SPEC-366)
-import { execSync } from 'node:child_process';
+import { execGitCapture } from './git/exec-git.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -138,11 +138,7 @@ export function suggestSpecUpdates(specs, filePath) {
 export function runGitDiffImpact(specs, projectPath) {
     let diffText = '';
     try {
-        diffText = execSync('git diff HEAD', {
-            cwd: projectPath,
-            encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
+        diffText = execGitCapture('git diff HEAD', projectPath);
     }
     catch {
         // ignore git errors — proceed with empty diff

package/dist/engine/context-orchestrator/index.js

@@ -1,6 +1,6 @@
 import { suggestArchivableSpecs, archiveSpecToPath } from '../context-manager.js';
 import { writeCheckpoint } from '../session/checkpoint-writer.js';
-import { sessionTracker } from '../session/session-tracker.js';
+import { getSessionTracker } from '../session/session-tracker.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { specStore } from '../../storage/index.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
@@ -114,7 +114,7 @@ async function archiveDoneSpecs(projectId, projectPath, actionsExecuted) {
 }
 async function createSessionCheckpoint(projectPath, actionsExecuted) {
     try {
-        const snapshot = sessionTracker.getSnapshot();
+        const snapshot = getSessionTracker(projectPath).getSnapshot();
         await writeCheckpoint(projectPath, snapshot);
         actionsExecuted.push('session_checkpoint: written to planu/session-context.md');
     }

package/dist/engine/convention-scanner/codebase-scanner.js

@@ -1,13 +1,13 @@
 // engine/convention-scanner/codebase-scanner.ts — SPEC-192
 // Scans actual codebase files against parsed conventions
-import { execSync } from 'node:child_process';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
+import { execGitCapture } from '../git/exec-git.js';
 const MAX_VIOLATIONS_PER_CATEGORY = 50;
 // ── helpers ───────────────────────────────────────────────────────────────────
 function execSafe(cmd, cwd) {
     try {
-        return execSync(cmd, { cwd, timeout: 5_000, stdio: ['pipe', 'pipe', 'pipe'] }).toString();
+        return execGitCapture(cmd, cwd);
     }
     catch {
         return '';

package/dist/engine/dogfooding/runtime-gap-detector.js

@@ -78,7 +78,7 @@ const SIGNAL_RULES = [
         signature: 'manual-recovery-loop',
         title: 'Repeated manual recovery steps',
         severity: 'medium',
-        nextAction: 'submit_feedback',
+        nextAction: 'create_spec',
         patterns: [
             /\bmanual recovery\b/gi,
             /\brepair_frontmatter_drift\b/gi,
@@ -342,7 +342,7 @@ export async function analyzeRuntimeDogfooding(projectPath) {
             signature: 'session-version-drift',
             title: 'Persisted session version drifted from the current package version',
             severity: 'medium',
-            nextAction: 'submit_feedback',
+            nextAction: 'create_spec',
             occurrences: 1,
             evidence: ['Persisted session version does not match package.json'],
         });

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

@@ -45,6 +45,7 @@ export declare function traceabilityRowHasCurrentCommandEvidence(row: Traceabili
     projectId: string;
     projectPath: string;
 }): boolean;
+export declare function artifactHint(label: string): string;
 /** SPEC-1356: exported so evidence-autofill (and other producers) target the same path convention. */
 export declare function handoffEvidencePath(projectId: string, specId: string, filename: string): string;
 export declare function readEvidenceArtifacts(args: {

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

@@ -247,7 +247,7 @@ const ARTIFACT_HINTS = {
     'contract-validation-ui.json': 'Expected filename contract-validation-ui.json with { version: 1, kind: "ui", passed: boolean, reportPath?, summary? }.',
     'contract-validation-mcp.json': 'Expected filename contract-validation-mcp.json with { version: 1, kind: "mcp", passed: boolean, reportPath?, summary? }.',
 };
-function artifactHint(label) {
+export function artifactHint(label) {
     return ARTIFACT_HINTS[label] ?? '';
 }
 /** SPEC-1356: exported so evidence-autofill (and other producers) target the same path convention. */

package/dist/engine/evidence-gates/evidence-autofill.d.ts

@@ -4,12 +4,20 @@ export declare const PLANU_BOOKKEEPING_FILES: readonly ['planu/context.md', 'pla
 /** Normalizes a spec.md path (absolute or already repo-relative) to a repo-relative,
  * forward-slash path so it can be compared against `git diff` output. */
 export declare function toRepoRelativePath(specPath: string, projectPath?: string): string;
+/** Prose template + matching regex for the generator's validation evidence, shared by the
+ * generator (renders it) and the staleness classifier (recognizes it). */
+export declare function buildValidationEvidenceText(specId: string, score: number | undefined): string;
+export declare const VALIDATION_EVIDENCE_PATTERN: RegExp;
+/** Prose template + matching regex for the generator's reviewer evidence, shared by the
+ * generator (renders it) and the staleness classifier (recognizes it). */
+export declare function buildReviewerEvidenceText(agent: string, kind: string, verdict: string): string;
+export declare const REVIEWER_EVIDENCE_PATTERN: RegExp;
 /**
- * Generate `traceability-matrix.json` in the handoff evidence store when it does
- * not already exist. Never overwrites an existing file — if one is present this
- * is a no-op that reports `already-exists`. Tolerates every failure by returning
- * a typed non-throwing result; callers must never let this crash a lifecycle
- * transition.
+ * Generate `traceability-matrix.json` in the handoff evidence store, or regenerate
+ * it in place when it is autofill-shaped but stale relative to the current
+ * validation report. Never touches a hand-written or mixed matrix — those are a
+ * permanent no-op. Tolerates every failure by returning a typed non-throwing
+ * result; callers must never let this crash a lifecycle transition.
  */
 export declare function autofillTraceabilityMatrix(args: AutofillTraceabilityMatrixArgs): Promise<AutofillTraceabilityMatrixResult>;
 //# sourceMappingURL=evidence-autofill.d.ts.map

package/dist/engine/evidence-gates/evidence-autofill.js

@@ -1,22 +1,4 @@
 // engine/evidence-gates/evidence-autofill.ts — SPEC-1356: automated lifecycle evidence pipeline
-//
-// Generates traceability-matrix.json in the handoff evidence store when it is
-// missing, so a `done` transition never fails purely because nobody hand-wrote
-// the traceability artifact.
-//
-// ORDERING CAVEAT (documented per SPEC-1356 T-A3): writing traceability-matrix.json
-// *after* `validate` has already computed and bound durable validation receipts
-// would make those bindings stale relative to the newly-written evidence — the
-// receipt would be certifying a repository state that does not include this file.
-// This module does NOT attempt to re-run or re-bind validation. Instead, callers
-// (see `src/tools/update-status/index.ts`) MUST treat a write from this module as
-// "evidence created, not yet bound": when autofill actually writes the file, the
-// caller must block the `done` transition with a message telling the operator to
-// re-run `validate` once so the freshly-created evidence gets bound, then retry
-// `done`. This is the simpler, safe choice given SPEC-1356 could not fully verify
-// that skipping straight through to the done gates after autofill would keep
-// receipt bindings correct in every code path (reconciliation, forced bypass,
-// legacy harnesses, etc.).
 import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
@@ -113,6 +95,18 @@ function filterExistingRepoFiles(projectPath, paths) {
         }
     });
 }
+/** Prose template + matching regex for the generator's validation evidence, shared by the
+ * generator (renders it) and the staleness classifier (recognizes it). */
+export function buildValidationEvidenceText(specId, score) {
+    return `Validated by handoffs/${specId}/validation-report.json (score=${score ?? 'n/a'}).`;
+}
+export const VALIDATION_EVIDENCE_PATTERN = /^Validated by handoffs\/.+\/validation-report\.json \(score=.+\)\.$/;
+/** Prose template + matching regex for the generator's reviewer evidence, shared by the
+ * generator (renders it) and the staleness classifier (recognizes it). */
+export function buildReviewerEvidenceText(agent, kind, verdict) {
+    return `Reviewed by ${agent} (${kind}), verdict=${verdict}.`;
+}
+export const REVIEWER_EVIDENCE_PATTERN = /^Reviewed by .+ \(.+\), verdict=.+\.$/;
 /** Best-effort read + sha256 summary of the persisted validation report, for prose evidence. */
 async function readValidationReportSummary(projectId, specId) {
     const reportPath = join(projectDataDir(projectId), 'handoffs', specId, 'validation-report.json');
@@ -124,47 +118,103 @@ async function readValidationReportSummary(projectId, specId) {
         }
         const { score, reviewer } = parsed.data;
         return {
-            validationEvidence: `Validated by handoffs/${specId}/validation-report.json (score=${score ?? 'n/a'}).`,
-            reviewerEvidence: `Reviewed by ${reviewer.agent} (${reviewer.kind}), verdict=${reviewer.verdict}.`,
+            validationEvidence: buildValidationEvidenceText(specId, score),
+            reviewerEvidence: buildReviewerEvidenceText(reviewer.agent, reviewer.kind, reviewer.verdict),
         };
     }
     catch {
         return {};
     }
 }
+function isAutofillShapedMatrix(candidate) {
+    if (typeof candidate !== 'object' ||
+        candidate === null ||
+        !Array.isArray(candidate.rows)) {
+        return false;
+    }
+    const rows = candidate.rows;
+    if (rows.length === 0) {
+        return false;
+    }
+    return rows.every((row) => row.validationEvidence !== undefined &&
+        row.reviewerEvidence !== undefined &&
+        VALIDATION_EVIDENCE_PATTERN.test(row.validationEvidence) &&
+        REVIEWER_EVIDENCE_PATTERN.test(row.reviewerEvidence));
+}
+const LEGACY_ROW_ALLOWED_KEYS = new Set(['acceptanceCriterion', 'testEvidence', 'changedFiles']);
+/** A pre-evidence-schema matrix: every row uses only the generator's original
+ * keys, with neither validationEvidence nor reviewerEvidence present. Safe to
+ * regenerate the same way a stale autofill-shaped matrix is. */
+function isLegacyGeneratorShapedMatrix(candidate) {
+    if (typeof candidate !== 'object' ||
+        candidate === null ||
+        !Array.isArray(candidate.rows)) {
+        return false;
+    }
+    const rows = candidate.rows;
+    if (rows.length === 0) {
+        return false;
+    }
+    return rows.every((row) => Object.keys(row).every((key) => LEGACY_ROW_ALLOWED_KEYS.has(key)));
+}
+/** Reads the on-disk matrix, if any, and classifies whether it is safe to
+ * regenerate. A hand-written, mixed, or unparseable matrix is never touched. */
+async function readRegeneratableMatrix(targetPath) {
+    if (!existsSync(targetPath)) {
+        return { kind: 'absent' };
+    }
+    const raw = await readFile(targetPath, 'utf-8');
+    try {
+        const parsed = JSON.parse(raw);
+        return isAutofillShapedMatrix(parsed) || isLegacyGeneratorShapedMatrix(parsed)
+            ? { kind: 'autofill-shaped', raw }
+            : { kind: 'manual' };
+    }
+    catch {
+        return { kind: 'manual' };
+    }
+}
+async function resolveChangedFiles(args) {
+    const exec = args.exec ?? defaultExec;
+    const baseBranch = args.baseBranch ?? 'main';
+    const gitEntries = args.projectPath
+        ? await computeChangedFilesFromGit(args.projectPath, exec, baseBranch)
+        : [];
+    const gitChangedFiles = excludeBookkeepingChanges(gitEntries, args.ownSpecMdPath);
+    const ownership = extractCanonicalFileOwnership(args.specBody);
+    const ownershipFiles = [...ownership.toCreate, ...ownership.toModify, ...ownership.toTest];
+    const rawChangedFiles = gitChangedFiles.length > 0 ? gitChangedFiles : ownershipFiles;
+    return [
+        ...new Set(args.projectPath
+            ? filterExistingRepoFiles(args.projectPath, rawChangedFiles)
+            : rawChangedFiles),
+    ];
+}
 /**
- * Generate `traceability-matrix.json` in the handoff evidence store when it does
- * not already exist. Never overwrites an existing file — if one is present this
- * is a no-op that reports `already-exists`. Tolerates every failure by returning
- * a typed non-throwing result; callers must never let this crash a lifecycle
- * transition.
+ * Generate `traceability-matrix.json` in the handoff evidence store, or regenerate
+ * it in place when it is autofill-shaped but stale relative to the current
+ * validation report. Never touches a hand-written or mixed matrix — those are a
+ * permanent no-op. Tolerates every failure by returning a typed non-throwing
+ * result; callers must never let this crash a lifecycle transition.
  */
 export async function autofillTraceabilityMatrix(args) {
     const targetPath = handoffEvidencePath(args.projectId, args.specId, 'traceability-matrix.json');
     try {
-        if (existsSync(targetPath)) {
-            return { written: false, reason: 'already-exists' };
-        }
         const criteria = extractAcceptanceCriteriaTexts(args.specBody);
         if (criteria.length === 0) {
             return { written: false, reason: 'no-criteria' };
         }
+        const existingLookup = await readRegeneratableMatrix(targetPath);
+        if (existingLookup.kind === 'manual') {
+            return { written: false, reason: 'already-exists-manual' };
+        }
+        const existingRaw = existingLookup.kind === 'autofill-shaped' ? existingLookup.raw : undefined;
         const scenarios = parseFrontmatterScenarios(args.specBody);
-        const exec = args.exec ?? defaultExec;
-        const baseBranch = args.baseBranch ?? 'main';
-        const gitEntries = args.projectPath
-            ? await computeChangedFilesFromGit(args.projectPath, exec, baseBranch)
-            : [];
-        const gitChangedFiles = excludeBookkeepingChanges(gitEntries, args.ownSpecMdPath);
-        const ownership = extractCanonicalFileOwnership(args.specBody);
-        const ownershipFiles = [...ownership.toCreate, ...ownership.toModify, ...ownership.toTest];
-        const rawChangedFiles = gitChangedFiles.length > 0 ? gitChangedFiles : ownershipFiles;
-        const changedFiles = [
-            ...new Set(args.projectPath
-                ? filterExistingRepoFiles(args.projectPath, rawChangedFiles)
-                : rawChangedFiles),
-        ];
+        const changedFiles = await resolveChangedFiles(args);
         const { validationEvidence, reviewerEvidence } = await readValidationReportSummary(args.projectId, args.specId);
+        if (existingRaw !== undefined && validationEvidence === undefined) {
+            return { written: false, reason: 'already-exists-current' };
+        }
         const rows = criteria.map((acceptanceCriterion, index) => {
             const testPaths = scenarios[index]?.tests?.map((test) => test.path) ?? [];
             return {
@@ -176,7 +226,20 @@ export async function autofillTraceabilityMatrix(args) {
             };
         });
         const payload = { version: 1, rows };
-        await atomicWriteFile(targetPath, JSON.stringify(payload, null, 2));
+        const payloadJson = JSON.stringify(payload, null, 2);
+        if (existingRaw !== undefined) {
+            if (existingRaw === payloadJson) {
+                return { written: false, reason: 'already-exists-current' };
+            }
+            await atomicWriteFile(targetPath, payloadJson);
+            return {
+                written: true,
+                path: targetPath,
+                rowCount: rows.length,
+                reason: 'regenerated-stale',
+            };
+        }
+        await atomicWriteFile(targetPath, payloadJson);
         return { written: true, path: targetPath, rowCount: rows.length };
     }
     catch (error) {

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

@@ -1,5 +1,5 @@
 import { isAbsolute, join } from 'node:path';
-import { DISCOVERY_TEMPLATE_OVERRIDES, DiscoverySchema, evidenceArtifactCollectionDigest, evidenceArtifactDigest, } from './artifact-reader.js';
+import { DISCOVERY_TEMPLATE_OVERRIDES, DiscoverySchema, artifactHint, 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';
@@ -218,7 +218,7 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
     if (!matrix) {
         issues.push({
             code: 'traceability_missing',
-            message: 'Traceability matrix evidence is required before done. Add traceability-matrix.json covering each acceptance criterion.',
+            message: `Traceability matrix evidence is required before done. Add traceability-matrix.json covering each acceptance criterion. ${artifactHint('Traceability matrix evidence')}`,
         });
     }
     else {
@@ -238,7 +238,7 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
             const rowDetails = incompleteRows.map(describeIncompleteRow);
             issues.push({
                 code: 'traceability_incomplete_rows',
-                message: `Traceability rows must include evidence, changed files, validation evidence, and reviewer evidence. Incomplete rows: ${rowDetails.join('; ')}`,
+                message: `Traceability rows must include evidence, changed files, validation evidence, and reviewer evidence. Incomplete rows: ${rowDetails.join('; ')}. Check traceability-matrix.json in this spec's handoff evidence store: a generator-shaped matrix regenerates automatically the next time validate runs and the done transition is retried, but a hand-written matrix must be edited in place.`,
             });
         }
     }
@@ -251,9 +251,12 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
         .map((artifact) => artifact.kind);
     const missingKinds = requiredKinds.filter((kind) => !passedKinds.has(kind));
     if (missingKinds.length > 0) {
+        const hints = missingKinds
+            .map((kind) => artifactHint(`contract-validation-${kind}.json`))
+            .join(' ');
         issues.push({
             code: 'contract_validation_missing',
-            message: `Contract validation evidence is required for: ${missingKinds.join(', ')}`,
+            message: `Contract validation evidence is required for: ${missingKinds.join(', ')}. ${hints}`,
         });
     }
     if (failedKinds.length > 0) {