@planu/cli 4.14.1 → 5.0.0

package/dist/tools/tool-registry/group-quality-compliance.js

@@ -1,6 +1,6 @@
 import { technologyValue } from '../../engine/technology-registry.js';
 import { z } from 'zod';
-import { safeLicensed, safeTracked } from '../safe-handler.js';
+import { safeGoverned, safeTracked } from '../safe-handler.js';
 import { projectIdSchema, withProject } from '../tool-registry-helpers.js';
 import { t } from '../../i18n/index.js';
 import { makeDeprecationStub } from './deprecated-stubs.js';
@@ -269,7 +269,7 @@ export function registerQualityComplianceGroupTools(s) {
             outputFormat: z.enum(['html', 'json']).optional().describe(FORMAT_DESCRIBE),
         },
         annotations: { title: 'Generate Compliance Report', readOnlyHint: true },
-    }, safeLicensed('generate_compliance_report', (args) => Promise.resolve(handleGenerateComplianceReport(args))));
+    }, safeGoverned('generate_compliance_report', (args) => Promise.resolve(handleGenerateComplianceReport(args))));
     s.registerTool('audit_log_export', {
         description: 'Export the project audit trail in CSV, JSON, or JSON-LD format. ' +
             'Supports optional date range filtering. ' +
@@ -290,7 +290,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe('Optional date range filter for audit entries'),
         },
         annotations: { title: 'Export Audit Log', readOnlyHint: true },
-    }, safeLicensed('audit_log_export', async (args) => handleAuditLogExport(args)));
+    }, safeGoverned('audit_log_export', async (args) => handleAuditLogExport(args)));
     s.registerTool('data_retention_policy', {
         description: 'Configure the data retention policy for the project. ' +
             'Specifies how long data should be retained and whether auto-deletion is enabled. ' +
@@ -320,7 +320,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe('Days before deletion to notify (default: 7)'),
         },
         annotations: { title: 'Configure Data Retention Policy', readOnlyHint: false },
-    }, safeLicensed('data_retention_policy', async (args) => handleDataRetentionPolicy(args)));
+    }, safeGoverned('data_retention_policy', async (args) => handleDataRetentionPolicy(args)));
     // ── Compliance gate ───────────────────────────────────────────────────────────
     s.registerTool('configure_compliance_gate', {
         description: 'Configure the compliance gate that runs automatically when a spec is sent to review. ' +
@@ -329,9 +329,9 @@ export function registerQualityComplianceGroupTools(s) {
             'Pro feature.',
         inputSchema: ConfigureComplianceGateSchema.shape,
         annotations: { title: 'Configure Compliance Gate', destructiveHint: false },
-    }, safeLicensed('configure_compliance_gate', async (args) => handleConfigureComplianceGate(args)));
+    }, safeGoverned('configure_compliance_gate', async (args) => handleConfigureComplianceGate(args)));
     s.registerTool('compliance_gate_status', {
-        description: 'Check the compliance gate configuration for this project. Returns the current mode and threshold. Free tool — no license required.',
+        description: 'Check the compliance gate configuration for this project. Returns the current mode and threshold.',
         inputSchema: {
             projectPath: z.string().describe('Absolute path to the project root'),
         },
@@ -363,7 +363,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe(TEST_FORMAT_DESCRIBE),
         },
         annotations: { title: 'Generate Compliance Tests', readOnlyHint: true },
-    }, safeLicensed('generate_compliance_tests', async (args) => handleGenerateComplianceTests(args)));
+    }, safeGoverned('generate_compliance_tests', async (args) => handleGenerateComplianceTests(args)));
     s.registerTool('compliance_coverage_report', {
         description: 'List all compliance controls for the requested frameworks, showing their IDs, ' +
             'titles, descriptions, and matching keywords. ' +
@@ -380,7 +380,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe(COMPLIANCE_TEST_FRAMEWORK_DESCRIBE),
         },
         annotations: { title: 'Compliance Coverage Report', readOnlyHint: true },
-    }, safeLicensed('compliance_coverage_report', (args) => Promise.resolve(handleComplianceCoverageReport(args))));
+    }, safeGoverned('compliance_coverage_report', (args) => Promise.resolve(handleComplianceCoverageReport(args))));
     // ── Security ─────────────────────────────────────────────────────────────────
     s.registerTool('security_check', {
         description: t('tools.security_check.description'),
@@ -398,7 +398,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .optional()
                 .describe('Absolute paths to code files to scan for insecure patterns'),
         },
-    }, safeLicensed('security_check', withProject((args) => handleSecurityCheck(args))));
+    }, safeGoverned('security_check', withProject((args) => handleSecurityCheck(args))));
     // ── Audit trail ──────────────────────────────────────────────────────────────
     s.registerTool('audit_trail', {
         description: 'Query the immutable audit log for a project. Supports filtering by specId, userId, eventType, and date range. Returns events with SHA-256 chain integrity status.',
@@ -430,7 +430,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .optional()
                 .describe('Maximum number of events to return (default: 100, max: 1000).'),
         },
-    }, safeLicensed('audit_trail', withProject((args) => handleAuditTrail(args))));
+    }, safeGoverned('audit_trail', withProject((args) => handleAuditTrail(args))));
     s.registerTool('generate_attestation', {
         description: 'Generate a compliance attestation document for a specific spec. Includes full audit history, chain integrity verification, and event summary for SOC2/HIPAA/ISO27001 audits.',
         annotations: { readOnlyHint: true },
@@ -442,7 +442,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .max(500)
                 .describe('Spec ID to generate attestation for (e.g. SPEC-042).'),
         },
-    }, safeLicensed('generate_attestation', withProject((args) => handleGenerateAttestation(args))));
+    }, safeGoverned('generate_attestation', withProject((args) => handleGenerateAttestation(args))));
     s.registerTool('export_audit_trail', {
         description: 'Export the EU AI Act Article 12 immutable audit trail for every Planu tool invocation. ' +
             'Supports filtering by project, date range, or spec. Verifies SHA-256 chain integrity. ' +
@@ -478,7 +478,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .optional()
                 .describe('Maximum number of entries to return.'),
         },
-    }, safeLicensed('export_audit_trail', (args) => Promise.resolve(handleExportAuditTrail(args))));
+    }, safeGoverned('export_audit_trail', (args) => Promise.resolve(handleExportAuditTrail(args))));
     // ── Schema parity ────────────────────────────────────────────────────────────
     s.registerTool('audit_schema_type_parity', {
         description: 'Scans all register-*.ts tool files in the project for mismatches between Zod optional ' +
@@ -493,7 +493,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .max(4096)
                 .describe('Absolute path to the project root to scan. The auditor will look for src/tools/register-*.ts and src/types/**/*.ts.'),
         },
-    }, safeLicensed('audit_schema_type_parity', async (args) => handleAuditSchemaParity(args)));
+    }, safeGoverned('audit_schema_type_parity', async (args) => handleAuditSchemaParity(args)));
     s.registerTool('fix_schema_type_parity', {
         description: 'Automatically fixes Zod/TypeScript optional parity issues found by audit_schema_type_parity. ' +
             'Adds "?" to TypeScript type definitions for fields that are marked .optional() in Zod schemas. ' +
@@ -510,7 +510,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .default(true)
                 .describe('When true (default), shows what would change without writing any files. Set to false to apply the fixes.'),
         },
-    }, safeLicensed('fix_schema_type_parity', async (args) => handleFixSchemaParity(args)));
+    }, safeGoverned('fix_schema_type_parity', async (args) => handleFixSchemaParity(args)));
     // ── Schema generator ─────────────────────────────────────────────────────────
     s.registerTool('generate_validation_schema', {
         description: 'Analyze a spec and generate validation schema code (Zod, Yup, or Valibot). ' +
@@ -605,7 +605,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe('Spec ID to analyze (e.g., "SPEC-001"), or "all" to analyze every spec in the project'),
         },
         annotations: { title: 'Spec Test Coverage', readOnlyHint: true },
-    }, safeLicensed('spec_coverage', withProject((args) => handleSpecCoverage(args))));
+    }, safeGoverned('spec_coverage', withProject((args) => handleSpecCoverage(args))));
     // ── Eval skill ───────────────────────────────────────────────────────────────
     s.registerTool('eval_skill', {
         description: 'Evaluate the quality of a Claude skill file against a set of test scenarios. ' +
@@ -838,7 +838,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe('Evaluation mode: strict (default) requires score >=70; lenient requires >=60'),
         },
         outputSchema: CheckReadinessOutputSchema,
-    }, safeLicensed('check_readiness', withProject((args) => handleCheckReadiness(args))));
+    }, safeGoverned('check_readiness', withProject((args) => handleCheckReadiness(args))));
     // ── SPEC-961: Architecture lint ─────────────────────────────────────────────
     s.registerTool('architecture_lint', {
         description: 'Scan project codebase for Clean Architecture and SOLID principle violations. Reports handler bloat, layer violations, and missing repository patterns.',
@@ -857,7 +857,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe('Glob patterns to exclude (default: node_modules, .git, dist)'),
             failFast: z.boolean().optional().describe('Stop on first error (default: false)'),
         },
-    }, safeLicensed('architecture_lint', withProject((args) => handleArchitectureLint(args))));
+    }, safeGoverned('architecture_lint', withProject((args) => handleArchitectureLint(args))));
     // ── SPEC-962: SOLID check ───────────────────────────────────────────────────
     s.registerTool('solid_check', {
         description: 'Scan project codebase for SOLID principle violations. Reports SRP, OCP, LSP, ISP, and DIP issues with a scored report (0-100) and per-principle breakdown.',
@@ -870,7 +870,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe('Glob patterns to exclude (default: node_modules, .git, dist)'),
             failFast: z.boolean().optional().describe('Stop on first error (default: false)'),
         },
-    }, safeLicensed('solid_check', withProject((args) => handleSolidCheck({
+    }, safeGoverned('solid_check', withProject((args) => handleSolidCheck({
         projectPath: args.projectPath,
         exclude: args.exclude,
         failFast: args.failFast,
@@ -917,7 +917,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .optional()
                 .describe('Fail on first failing endpoint (default: false)'),
         },
-    }, safeLicensed('verify_integrations', withProject((args) => handleVerifyIntegrations({
+    }, safeGoverned('verify_integrations', withProject((args) => handleVerifyIntegrations({
         projectPath: args.projectPath,
         endpoints: args.endpoints,
         timeout: args.timeout,
@@ -954,7 +954,7 @@ export function registerQualityComplianceGroupTools(s) {
             ...projectIdSchema,
             specId: SpecIdSchema.describe('Spec ID to generate handoff package for'),
         },
-    }, safeLicensed('package_handoff', withProject((args) => handlePackageHandoff(args))));
+    }, safeGoverned('package_handoff', withProject((args) => handlePackageHandoff(args))));
     // ── Approval ─────────────────────────────────────────────────────────────────
     s.registerTool('configure_approval_policy', {
         description: 'Define the approval policy for a project: how many approvals are required, ' +
@@ -980,7 +980,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe('Roles allowed to approve specs. If empty or omitted, any reviewer can approve.'),
         },
         annotations: { title: 'Configure Approval Policy', destructiveHint: false },
-    }, safeLicensed('configure_approval_policy', (args) => handleConfigureApprovalPolicy(args)));
+    }, safeGoverned('configure_approval_policy', (args) => handleConfigureApprovalPolicy(args)));
     s.registerTool('issue_reviewer_token', {
         description: '[SPEC-722] Issue a signed reviewer token for approve_spec. ' +
             'Must be called from a DIFFERENT session than the one that created the spec. ' +
@@ -1002,7 +1002,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe('Host/agent platform identifier (e.g. "claude-code", "cursor").'),
         },
         annotations: { title: 'Issue Reviewer Token', destructiveHint: false },
-    }, safeLicensed('issue_reviewer_token', (args) => handleIssueReviewerToken(args)));
+    }, safeGoverned('issue_reviewer_token', (args) => handleIssueReviewerToken(args)));
     s.registerTool('approve_spec', {
         description: '[SPEC-722] Record that a reviewer has approved a spec. ' +
             'Requires a signed reviewerToken (from issue_reviewer_token) and the plannerToken ' +
@@ -1036,7 +1036,7 @@ export function registerQualityComplianceGroupTools(s) {
                 'Allows approval from the same model if the panel was heterogeneous.'),
         },
         annotations: { title: 'Approve Spec', destructiveHint: true },
-    }, safeLicensed('approve_spec', (args) => handleApproveSpec(args)));
+    }, safeGoverned('approve_spec', (args) => handleApproveSpec(args)));
     s.registerTool('request_changes', {
         description: 'Request changes on a spec. The spec is moved back to draft and prior approvals are cleared. ' +
             'A comment explaining the required changes is mandatory.',
@@ -1068,7 +1068,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .describe('Role of the reviewer (e.g. "tech-lead", "qa").'),
         },
         annotations: { title: 'Request Changes', destructiveHint: true },
-    }, safeLicensed('request_changes', (args) => handleRequestChanges(args)));
+    }, safeGoverned('request_changes', (args) => handleRequestChanges(args)));
     s.registerTool('approval_status', {
         description: 'Show the current approval status for a spec: who approved, how many are needed, ' +
             'time in review, and SLA breach warning if applicable.',
@@ -1103,7 +1103,7 @@ export function registerQualityComplianceGroupTools(s) {
                 .optional()
                 .describe('Raw spec content to analyze when specId is not available'),
         },
-    }, safeLicensed('data_governance', withProject((args) => handleDataGovernance(args))));
+    }, safeGoverned('data_governance', withProject((args) => handleDataGovernance(args))));
     s.registerTool('legal_compliance_report', {
         description: 'Generate a legal compliance report for the project. ' +
             'Shows detected legal domains, applicable regulations by country, ' +
@@ -1113,7 +1113,7 @@ export function registerQualityComplianceGroupTools(s) {
         inputSchema: {
             ...projectIdSchema,
         },
-    }, safeLicensed('legal_compliance_report', withProject((args) => handleLegalComplianceReport(args))));
+    }, safeGoverned('legal_compliance_report', withProject((args) => handleLegalComplianceReport(args))));
     // ── SPEC-322: API Contract Validation ────────────────────────────────────────
     s.registerTool('validate_api_contract', {
         description: 'Validate an OpenAPI 3.x/Swagger or GraphQL SDL contract against the actual implementation in a project. ' +

package/dist/tools/tool-registry/inventory.d.ts

@@ -0,0 +1,2 @@
+export { OFFICIAL_SDD_TOOL_NAMES, readCanonicalToolNames, } from '../../config/official-sdd-tools.js';
+//# sourceMappingURL=inventory.d.ts.map

package/dist/tools/tool-registry/inventory.js

@@ -0,0 +1,2 @@
+export { OFFICIAL_SDD_TOOL_NAMES, readCanonicalToolNames, } from '../../config/official-sdd-tools.js';
+//# sourceMappingURL=inventory.js.map

package/dist/tools/tool-registry-helpers.d.ts

@@ -14,17 +14,17 @@ interface MaybeProjectArgs {
  * Wraps a handler that requires a resolved projectId.
  * Resolves projectId from projectId or projectPath; returns missingProjectIdError if neither.
  *
- * Usage (replaces the 5-line resolveProjectId block in each safeTracked/safeLicensed callback):
+ * Usage (replaces the 5-line resolveProjectId block in each safeTracked/safeGoverned callback):
  * ```ts
  * // Before:
- * safeLicensed('tool', async (args) => {
+ * safeGoverned('tool', async (args) => {
  *   const pid = resolveProjectId(args as { projectId?: string; projectPath?: string });
  *   if (!pid) return missingProjectIdError;
  *   return handleFoo({ ...args, projectId: pid } as FooInput);
  * })
  *
  * // After:
- * safeLicensed('tool', withProject((args) => handleFoo(args as never)))
+ * safeGoverned('tool', withProject((args) => handleFoo(args as never)))
  * ```
  */
 export declare function withProject<T extends MaybeProjectArgs>(handler: (args: T & {

package/dist/tools/tool-registry-helpers.js

@@ -16,17 +16,17 @@ export const projectIdSchema = {
  * Wraps a handler that requires a resolved projectId.
  * Resolves projectId from projectId or projectPath; returns missingProjectIdError if neither.
  *
- * Usage (replaces the 5-line resolveProjectId block in each safeTracked/safeLicensed callback):
+ * Usage (replaces the 5-line resolveProjectId block in each safeTracked/safeGoverned callback):
  * ```ts
  * // Before:
- * safeLicensed('tool', async (args) => {
+ * safeGoverned('tool', async (args) => {
  *   const pid = resolveProjectId(args as { projectId?: string; projectPath?: string });
  *   if (!pid) return missingProjectIdError;
  *   return handleFoo({ ...args, projectId: pid } as FooInput);
  * })
  *
  * // After:
- * safeLicensed('tool', withProject((args) => handleFoo(args as never)))
+ * safeGoverned('tool', withProject((args) => handleFoo(args as never)))
  * ```
  */
 export function withProject(handler) {

package/dist/tools/tool-usage-report/registered-tools.d.ts

@@ -1,5 +1,5 @@
 /**
- * Returns a deduplicated list of all tool names registered in license-plans.json.
+ * Returns the live tool inventory captured by the canonical registry.
  */
 export declare function readRegisteredToolNames(): Promise<string[]>;
 //# sourceMappingURL=registered-tools.d.ts.map

package/dist/tools/tool-usage-report/registered-tools.js

@@ -1,21 +1,9 @@
 // tools/tool-usage-report/registered-tools.ts — SPEC-574
-// Reads all tool names registered in license-plans.json (freeTools + proTools + alwaysAllowed).
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-function loadLicensePlans() {
-    const __filename = fileURLToPath(import.meta.url);
-    const __dirname = dirname(__filename);
-    const configPath = join(__dirname, '../../config/license-plans.json');
-    const raw = readFileSync(configPath, 'utf-8');
-    return JSON.parse(raw);
-}
+import { readCanonicalToolNames } from '../tool-registry/inventory.js';
 /**
- * Returns a deduplicated list of all tool names registered in license-plans.json.
+ * Returns the live tool inventory captured by the canonical registry.
  */
 export function readRegisteredToolNames() {
-    const plans = loadLicensePlans();
-    const allTools = new Set([...plans.freeTools, ...plans.proTools, ...plans.alwaysAllowed]);
-    return Promise.resolve([...allTools].sort());
+    return Promise.resolve(readCanonicalToolNames().sort());
 }
 //# sourceMappingURL=registered-tools.js.map

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

@@ -10,6 +10,9 @@ export async function checkComplianceGate(specId, projectId, projectPath) {
     try {
         const { scoreCompliance } = await import('../../engine/verifier/compliance-scorer.js');
         const result = await scoreCompliance(specId, projectPath);
+        if (result.totalCriteria === 0 && result.criteriaDetails.length === 0) {
+            return { skipped: true, score: null, issues: [], blocked: false };
+        }
         const score = result.score;
         const issues = result.criteriaDetails
             .filter((detail) => detail.status === 'unverified')

package/dist/tools/update-status/done-receipt-verifier.js

@@ -54,8 +54,9 @@ import { isAbsolute, join } from 'node:path';
 import { RuntimeDatabase } from '../../storage/runtime-db.js';
 import { resolveStorageLayout } from '../../storage/storage-layout.js';
 import { projectDataDir } from '../../storage/base-store.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { ValidationReceiptStore, LOCAL_VALIDATION_RECEIPT_ISSUER, createValidationReceiptAuthority, readCurrentValidationReceipt, } from '../../engine/validation/validation-receipt.js';
-import { beginValidationFreshnessBarrier, bindValidationFreshnessLease, captureValidationFreshnessLease, } from '../../engine/validation/validation-freshness.js';
+import { beginValidationFreshnessBarrier, bindValidationFreshnessLease, captureValidationFreshnessLease, closeValidationFreshnessLease, } from '../../engine/validation/validation-freshness.js';
 import { computeDurableValidationBindings, toValidationReceiptBindings, } from '../../engine/validation/durable-validation.js';
 export function completedJobPublishesReceipt(job, receiptId) {
     if (job?.state !== 'completed' || !job.result || typeof job.result !== 'object') {
@@ -105,34 +106,46 @@ export async function verifyCurrentDoneReceipt(identity) {
         if (!receiptJobExists) {
             return { valid: false, reason: 'missing-receipt' };
         }
-        let freshnessLease = await captureValidationFreshnessLease(identity, currentBindings);
-        if (!freshnessLease && identity.projectPath && identity.specPath) {
-            const projectPath = identity.projectPath;
-            const specPath = isAbsolute(identity.specPath)
-                ? identity.specPath
-                : join(projectPath, identity.specPath);
-            const lease = await beginValidationFreshnessBarrier({
-                projectId: identity.projectId,
-                specId: identity.specId,
-                projectPath,
-                handoffPath: join(projectDataDir(identity.projectId), 'handoffs', identity.specId),
-                invalidateCurrentBindings: false,
-            });
-            const observed = await computeDurableValidationBindings({
-                canonicalProjectId: identity.projectId,
-                specId: identity.specId,
-                projectPath,
-                specPath,
-            });
-            const observedBindings = toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
-            if (JSON.stringify(observedBindings) === JSON.stringify(currentBindings) &&
-                (await bindValidationFreshnessLease(lease, observedBindings))) {
-                freshnessLease = lease;
+        let ownedLease = await captureValidationFreshnessLease(identity, currentBindings);
+        try {
+            if (!ownedLease && identity.projectPath && identity.specPath) {
+                const projectPath = identity.projectPath;
+                const specPath = isAbsolute(identity.specPath)
+                    ? identity.specPath
+                    : join(projectPath, identity.specPath);
+                ownedLease = await beginValidationFreshnessBarrier({
+                    projectId: identity.projectId,
+                    specId: identity.specId,
+                    projectPath,
+                    handoffPath: join(projectDataDir(identity.projectId), 'handoffs', identity.specId),
+                    invalidateCurrentBindings: false,
+                });
+                const observed = await computeDurableValidationBindings({
+                    canonicalProjectId: identity.projectId,
+                    specId: identity.specId,
+                    projectPath,
+                    specPath,
+                });
+                const observedBindings = toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
+                if (JSON.stringify(observedBindings) !== JSON.stringify(currentBindings) ||
+                    !(await bindValidationFreshnessLease(ownedLease, observedBindings))) {
+                    return { valid: false, reason: 'stale-bindings' };
+                }
+            }
+            if (!ownedLease) {
+                return { valid: false, reason: 'stale-bindings' };
+            }
+            const transferred = ownedLease;
+            ownedLease = undefined;
+            return { ...verification, freshnessLease: transferred };
+        }
+        finally {
+            if (ownedLease) {
+                await closeValidationFreshnessLease(ownedLease).catch((error) => {
+                    reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
+                });
             }
         }
-        return freshnessLease
-            ? { ...verification, freshnessLease }
-            : { valid: false, reason: 'stale-bindings' };
     }
     catch (e_1) {
         env_1.error = e_1;

package/dist/tools/update-status/evidence-gate.js

@@ -66,8 +66,25 @@ import { ValidationReceiptStore, LOCAL_VALIDATION_RECEIPT_ISSUER, createValidati
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { captureValidationFreshnessLease } from '../../engine/validation/validation-freshness.js';
 import { computeDurableValidationBindings, toValidationReceiptBindings, } from '../../engine/validation/durable-validation.js';
+import { checkReconciliationFreshness } from '../../engine/evidence-gates/reconciliation-freshness.js';
+import { extractCanonicalFileOwnership } from '../../engine/handoff-packager.js';
 /** SPEC-1054: BDD/SDD lifecycle evidence gate. */
 export async function checkLifecycleEvidenceTransitionGate(args) {
+    const staleReconciliationEvidence = await checkReconciliationFreshness({
+        projectId: args.projectId,
+        specId: args.specId,
+    });
+    if (staleReconciliationEvidence.length > 0) {
+        return evidenceGateError({
+            specId: args.specId,
+            transition: args.transition,
+            issues: staleReconciliationEvidence.map(({ artifactId }) => ({
+                code: 'SUPERSEDED_RECONCILIATION_EVIDENCE',
+                message: artifactId,
+            })),
+            requiredContractKinds: [],
+        });
+    }
     const [criteriaResult, artifacts] = await Promise.all([
         extractLifecycleGateCriteriaAndBody(args.spec, args.projectPath),
         readEvidenceArtifacts({
@@ -108,8 +125,26 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
             artifacts,
             projectPath: args.projectPath,
         });
+        const canonicalOwnership = body
+            ? extractCanonicalFileOwnership(body)
+            : { present: false, toCreate: [], toModify: [], toTest: [], blockers: [] };
         const groundedTechnicalPaths = body ? parseGroundedTechnicalPaths(body) : [];
-        result.issues.push(...checkDoneDriftContract({ index, groundedTechnicalPaths }));
+        const approvedScopePaths = [
+            ...new Set([
+                ...canonicalOwnership.toCreate,
+                ...canonicalOwnership.toModify,
+                ...canonicalOwnership.toTest,
+                ...groundedTechnicalPaths,
+            ]),
+        ];
+        if (canonicalOwnership.blockers.length > 0) {
+            const safeBlockers = canonicalOwnership.blockers.map((blocker) => blocker.startsWith('CONFLICTING_FILE_OWNERSHIP:') ? blocker : 'INVALID_FILE_OWNERSHIP');
+            result.issues.push({
+                code: 'done_drift_unapproved_scope',
+                message: `Approved canonical ownership is invalid: ${[...new Set(safeBlockers)].join(', ')}.`,
+            });
+        }
+        result.issues.push(...checkDoneDriftContract({ index, approvedScopePaths }));
     }
     if (result.issues.length === 0) {
         return null;

package/dist/tools/update-status/file-sync.d.ts

@@ -10,7 +10,7 @@ export interface FrontmatterSyncWarning {
     specPath: string | null;
     reason: string;
 }
-export declare function syncSpecFiles(updatedSpec: Spec, _currentStatus: SpecStatus, newStatus: SpecStatus, projectPath?: string): Promise<{
+export declare function syncSpecFiles(updatedSpec: Spec, _currentStatus: SpecStatus, newStatus: SpecStatus, projectPath?: string, qualityWarnings?: readonly string[]): Promise<{
     warning?: FrontmatterSyncWarning;
 }>;
 export declare function tryReconcile(newStatus: string, specId: string, projectId: string): Promise<string | null>;
@@ -32,5 +32,6 @@ export declare function recordTerminalTransitionEvent(args: {
     modelId?: string;
     gateResults?: Record<string, 'pass' | 'fail' | 'skip' | 'forced'>;
     meta?: Record<string, unknown>;
+    projectPath?: string;
 }): Promise<void>;
 //# sourceMappingURL=file-sync.d.ts.map

package/dist/tools/update-status/file-sync.js

@@ -3,11 +3,12 @@ import { metricsStore } from '../../storage/index.js';
 import { addLesson, getLessons } from '../../storage/lessons-store.js';
 import { dispatchFeedbackEvent } from '../learn.js';
 import { autoReconcileOnDone } from '../update-status-reconcile.js';
-import { readFile } from 'node:fs/promises';
+import { lstat, readFile, realpath } from 'node:fs/promises';
 import { parseFrontmatter } from '../../engine/frontmatter-parser.js';
 import { computeFrontmatterSha } from '../../engine/frontmatter-sha/index.js';
 import { appendTransitionEvent } from '../../storage/transition-log.js';
 import { atomicWriteFile } from '../../engine/safety/atomic-write-file.js';
+import { isAbsolute, normalize, relative, resolve, sep } from 'node:path';
 import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
 export async function recordDoneMetrics(projectId, specId, spec, actuals, projectPath) {
     if (actuals.devHours + actuals.reviewHours === 0) {
@@ -74,6 +75,46 @@ async function autoCaptureLessonEstimation(spec, actuals, accuracy, projectId, p
 }
 const SPEC_BODY_SHRINK_ABSOLUTE_THRESHOLD = 200;
 const SPEC_BODY_SHRINK_RATIO_THRESHOLD = 0.05;
+async function resolveSpecPathForTransition(spec, projectPath) {
+    if (!projectPath) {
+        return spec.specPath;
+    }
+    const normalizedPath = normalize(spec.specPath);
+    const segments = normalizedPath.split(sep).filter(Boolean);
+    const planuIndex = segments.lastIndexOf('planu');
+    const specDirectory = segments[planuIndex + 2];
+    const isPortableContract = planuIndex >= 0 &&
+        segments[planuIndex + 1] === 'specs' &&
+        segments[planuIndex + 3] === 'spec.md' &&
+        planuIndex + 4 === segments.length &&
+        specDirectory !== undefined &&
+        (specDirectory === spec.id || specDirectory.startsWith(`${spec.id}-`));
+    if (!isPortableContract) {
+        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath is not a portable spec contract');
+    }
+    const selectedRoot = resolve(projectPath);
+    const candidate = resolve(selectedRoot, 'planu', 'specs', specDirectory, 'spec.md');
+    const relativeCandidate = relative(selectedRoot, candidate);
+    if (relativeCandidate.startsWith(`..${sep}`) ||
+        relativeCandidate === '..' ||
+        isAbsolute(relativeCandidate)) {
+        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath escapes the selected root');
+    }
+    const [rootRealpath, candidateRealpath, candidateStat] = await Promise.all([
+        realpath(selectedRoot),
+        realpath(candidate),
+        lstat(candidate),
+    ]);
+    const realRelative = relative(rootRealpath, candidateRealpath);
+    if (candidateStat.isSymbolicLink() ||
+        !candidateStat.isFile() ||
+        realRelative.startsWith(`..${sep}`) ||
+        realRelative === '..' ||
+        isAbsolute(realRelative)) {
+        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath is not a contained regular file');
+    }
+    return candidateRealpath;
+}
 function bodyWithoutFrontmatter(content) {
     return parseFrontmatter(content).body;
 }
@@ -95,13 +136,23 @@ function assertSpecBodyIntegrity(args) {
         throw new Error(`SPEC_INTEGRITY_WRITE_FAILED: refusing to write ${args.specId} because update_status(${args.newStatus}) would shrink spec.md body by ${String(lost)} characters without an explicit migration marker.`);
     }
 }
-export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, projectPath) {
+export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, projectPath, qualityWarnings = []) {
     let warning;
     if (updatedSpec.specPath) {
         try {
-            const specContent = await readFile(updatedSpec.specPath, 'utf-8');
+            const transitionSpecPath = await resolveSpecPathForTransition(updatedSpec, projectPath);
+            const specContent = await readFile(transitionSpecPath, 'utf-8');
+            if (projectPath) {
+                const parsedId = parseFrontmatter(specContent).metadata.id;
+                if (parsedId !== updatedSpec.id) {
+                    throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: spec frontmatter ID does not match');
+                }
+            }
             const { updateFrontmatterField } = await import('../../engine/frontmatter-parser.js');
             let updatedContent = updateFrontmatterField(specContent, 'status', newStatus);
+            if (qualityWarnings.length > 0) {
+                updatedContent = updateFrontmatterField(updatedContent, 'qualityWarnings', JSON.stringify(qualityWarnings));
+            }
             if (newStatus === 'done') {
                 updatedContent = markAllCriteriaDone(updatedContent);
                 if (isLeanSpecContent(updatedContent)) {
@@ -114,7 +165,7 @@ export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, proj
                 newStatus,
                 specId: updatedSpec.id,
             });
-            await atomicWriteFile(updatedSpec.specPath, updatedContent);
+            await atomicWriteFile(transitionSpecPath, updatedContent);
             // SPEC-544: Auto-stage spec.md after writing so it's included in the user's next commit
             // SPEC-575: Auto-commit staged planu/ docs (idempotent, safe-fail)
             // Commit message must reflect the actual transition — 'mark-done' is only
@@ -125,7 +176,7 @@ export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, proj
                 process.env.PLANU_SUPPRESS_AUTOCOMMIT !== 'true') {
                 try {
                     const { git: gitCmd } = await import('../git/git-helpers.js');
-                    await gitCmd(projectPath, ['add', '--', updatedSpec.specPath]);
+                    await gitCmd(projectPath, ['add', '--', transitionSpecPath]);
                     const { planuAutoCommit } = await import('../../engine/git/planu-autocommit.js');
                     void planuAutoCommit({
                         projectPath,
@@ -197,7 +248,7 @@ export async function recordTerminalTransitionEvent(args) {
         let frontmatterSha;
         if (args.specPath) {
             try {
-                const content = await readFile(args.specPath, 'utf-8');
+                const content = await readFile(await resolveSpecPathForTransition({ id: args.specId, specPath: args.specPath }, args.projectPath), 'utf-8');
                 const { metadata } = parseFrontmatter(content);
                 frontmatterSha = computeFrontmatterSha(metadata);
             }

package/dist/tools/update-status/index.d.ts

@@ -1,5 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { UpdateStatusInput, ToolResult } from '../../types/index.js';
+/** Bind deferred lifecycle work to one normalized absolute root without persisting that path. */
+export declare function computeTransitionRootBinding(projectPath: string): string;
 /** Recover durable post-commit work for every registered project after server startup. */
 export declare function recoverPendingPostCommitTasksAtStartup(): Promise<void>;
 export declare function handleUpdateStatus(params: UpdateStatusInput, server?: McpServer): Promise<ToolResult>;