@planu/cli 4.14.1 → 5.1.1

package/dist/tools/register-sdd-tools.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare const OFFICIAL_SDD_TOOL_NAMES: readonly ['planu_status', 'facilitate', 'init_project', 'clarify_requirements', 'create_spec', 'list_specs', 'challenge_spec', 'check_readiness', 'update_status', 'update_status_batch', 'package_handoff', 'validate', 'get_job', 'watch_job', 'cancel_job', 'restart_job', 'reconcile_spec', 'create_rule', 'create_skill', 'skill_search', 'configure_code_graph', 'code_graph_status', 'submit_feedback', 'triage_feedback', 'resolve_feedback', 'sync_feedback', 'feedback_status'];
+export { OFFICIAL_SDD_TOOL_NAMES } from './tool-registry/inventory.js';
 export declare function registerSddTools(server: McpServer): void;
 //# sourceMappingURL=register-sdd-tools.d.ts.map

package/dist/tools/register-sdd-tools.js

@@ -12,35 +12,8 @@ import { handleCreateRule } from './create-rule.js';
 import { handleCreateSkill } from './create-skill.js';
 import { handleReconcileUniversalRules } from './reconcile-universal-rules.js';
 import { registerPrompts } from '../prompts/index.js';
-export const OFFICIAL_SDD_TOOL_NAMES = [
-    'planu_status',
-    'facilitate',
-    'init_project',
-    'clarify_requirements',
-    'create_spec',
-    'list_specs',
-    'challenge_spec',
-    'check_readiness',
-    'update_status',
-    'update_status_batch',
-    'package_handoff',
-    'validate',
-    'get_job',
-    'watch_job',
-    'cancel_job',
-    'restart_job',
-    'reconcile_spec',
-    'create_rule',
-    'create_skill',
-    'skill_search',
-    'configure_code_graph',
-    'code_graph_status',
-    'submit_feedback',
-    'triage_feedback',
-    'resolve_feedback',
-    'sync_feedback',
-    'feedback_status',
-];
+import { OFFICIAL_SDD_TOOL_NAMES } from './tool-registry/inventory.js';
+export { OFFICIAL_SDD_TOOL_NAMES } from './tool-registry/inventory.js';
 const OFFICIAL_SDD_TOOL_SET = new Set(OFFICIAL_SDD_TOOL_NAMES);
 const noop = () => undefined;
 const DUMMY_TOOL_SLOT = {

package/dist/tools/register-spec-tools/analysis-tools.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { t } from '../../i18n/index.js';
-import { safeTracked, safeLicensed } from '../safe-handler.js';
+import { safeTracked, safeGoverned } from '../safe-handler.js';
 import { ChecklistFocusEnum, AuditCategoryEnum, SpecIdSchema } from '../schemas/index.js';
 import { resolveProjectId, missingProjectIdError } from '../resolve-project-id.js';
 import { handleDetectDrift } from '../detect-drift.js';
@@ -92,7 +92,7 @@ export function registerAnalysisTools(server) {
                 .optional()
                 .describe('Focus areas for the checklist'),
         },
-    }, safeLicensed('generate_checklist', async (args) => {
+    }, safeGoverned('generate_checklist', async (args) => {
         const pid = resolveProjectId(args);
         if (!pid) {
             return missingProjectIdError;
@@ -130,7 +130,7 @@ export function registerAnalysisTools(server) {
                 .optional()
                 .describe('Manual changes to apply'),
         },
-    }, safeLicensed('reconcile_spec', async (args) => {
+    }, safeGoverned('reconcile_spec', async (args) => {
         const pid = resolveProjectId(args);
         if (!pid) {
             return missingProjectIdError;
@@ -178,7 +178,7 @@ export function registerAnalysisTools(server) {
                 .describe('Audit categories to check'),
             specId: SpecIdSchema.optional().describe('Spec ID to audit against'),
         },
-    }, safeLicensed('audit', async (args) => {
+    }, safeGoverned('audit', async (args) => {
         const pid = resolveProjectId(args);
         if (!pid) {
             return missingProjectIdError;
@@ -220,7 +220,7 @@ export function registerAnalysisTools(server) {
                 .describe('Path to MCP config file (auto-detected if omitted)'),
             projectId: z.string().max(500).optional().describe('Project ID'),
         },
-    }, safeLicensed('discover_mcps', async (args) => handleDiscoverMcps(args)));
+    }, safeGoverned('discover_mcps', async (args) => handleDiscoverMcps(args)));
     // 19. suggest_mcps
     server.registerTool('suggest_mcps', {
         description: t('tools.suggest_mcps.description'),
@@ -233,7 +233,7 @@ export function registerAnalysisTools(server) {
                 .describe('Absolute path to project root. Derives projectId automatically.'),
             specId: SpecIdSchema.optional().describe('Spec ID for context-specific suggestions'),
         },
-    }, safeLicensed('suggest_mcps', async (args) => {
+    }, safeGoverned('suggest_mcps', async (args) => {
         const pid = resolveProjectId(args);
         if (!pid) {
             return missingProjectIdError;
@@ -252,7 +252,7 @@ export function registerAnalysisTools(server) {
                 .optional()
                 .describe('Absolute path to project root. Derives projectId automatically.'),
         },
-    }, safeLicensed('suggest_mcp_server', async (args) => {
+    }, safeGoverned('suggest_mcp_server', async (args) => {
         const pid = resolveProjectId(args);
         if (!pid) {
             return missingProjectIdError;
@@ -321,6 +321,6 @@ export function registerAnalysisTools(server) {
                 .describe('When false (default), done-status specs are skipped (respects SPEC-747 freeze). ' +
                 'Set true to migrate done specs (writes backup to planu/backups/ first).'),
         },
-    }, safeLicensed('ssr_back_migration', async (args) => handleSsrBackMigration(args)));
+    }, safeGoverned('ssr_back_migration', async (args) => handleSsrBackMigration(args)));
 }
 //# sourceMappingURL=analysis-tools.js.map

package/dist/tools/register-spec-tools/core-spec-tools.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { t } from '../../i18n/index.js';
-import { safeTracked, safeLicensed } from '../safe-handler.js';
-import { SupportedLocaleEnum, SpecStatusEnum, SpecTypeEnum, SpecScopeEnum, SpecTargetEnum, ExperienceLevelEnum, WorkModeEnum, ListSpecsOutputSchema, EstimateOutputSchema, ValidateOutputSchema, SpecIdSchema, } from '../schemas/index.js';
+import { safeTracked, safeGoverned } from '../safe-handler.js';
+import { SupportedLocaleEnum, SpecStatusEnum, ExperienceLevelEnum, WorkModeEnum, ListSpecsOutputSchema, EstimateOutputSchema, ValidateOutputSchema, SpecIdSchema, } from '../schemas/index.js';
+import { SpecAcFormatEnum, SpecScopeEnum, SpecTargetEnum, SpecTypeEnum } from '../schemas/spec.js';
 import { handleSetLocale } from '../set-locale.js';
 import { handleInitProject } from '../init-project.js';
 import { handleSetWorkMode } from '../set-work-mode-handler.js';
@@ -15,6 +16,7 @@ import { handleEstimate } from '../estimate.js';
 import { handleReverseEngineer } from '../reverse-engineer.js';
 import { handleValidate } from '../validate.js';
 import { handleTypeSafetyGate } from '../type-safety-gate.js';
+import { runWithTrustedLocalMcpContext } from '../../engine/lifecycle-reconciliation.js';
 /** init_project inputSchema — extracted to keep registerCoreSpecTools within line budget. */
 const INIT_PROJECT_INPUT_SCHEMA = {
     projectPath: z.string().max(4096).describe('Absolute path to the project root'),
@@ -216,10 +218,7 @@ export function registerCoreSpecTools(server) {
                 .max(500)
                 .optional()
                 .describe('Feature group tag (e.g. "Authentication", "Billing"). Added to tags for categorization. Flat structure — no subdirectories created.'),
-            acFormat: z
-                .enum(['bdd', 'checkbox'])
-                .optional()
-                .describe('SPEC-224: Format for acceptance criteria in spec.md. ' +
+            acFormat: SpecAcFormatEnum.optional().describe('SPEC-224: Format for acceptance criteria in spec.md. ' +
                 'checkbox (default) — markdown checkboxes (- [ ] criterion). ' +
                 'bdd — Gherkin Given-When-Then scenarios for BDD workflows.'),
             clarificationAnswers: z
@@ -360,18 +359,18 @@ export function registerCoreSpecTools(server) {
                 .describe('Set true when implementation drift requires reconcile_spec before status=done; true blocks done.'),
             actuals: z
                 .object({
-                devHours: z.number().min(0),
-                reviewHours: z.number().min(0),
-                tokensOpus: z.number().min(0),
-                tokensSonnet: z.number().min(0),
-                apiCostUsd: z.number().min(0),
-                humanCostUsd: z.number().min(0),
-                totalCostUsd: z.number().min(0),
-                completedAt: z.string().max(500),
-                notes: z.string().max(10_000),
+                devHours: z.number().min(0).optional(),
+                reviewHours: z.number().min(0).optional(),
+                tokensOpus: z.number().min(0).optional(),
+                tokensSonnet: z.number().min(0).optional(),
+                apiCostUsd: z.number().min(0).optional(),
+                humanCostUsd: z.number().min(0).optional(),
+                totalCostUsd: z.number().min(0).optional(),
+                completedAt: z.string().max(500).optional(),
+                notes: z.string().max(10_000).optional(),
             })
                 .optional()
-                .describe('Actual metrics (required when status = done)'),
+                .describe('Actual metrics for status = done. All fields optional (SPEC-1356): missing numeric fields default to 0, completedAt/notes are auto-filled when omitted.'),
             reviewNotes: z
                 .string()
                 .max(10_000)
@@ -399,12 +398,23 @@ export function registerCoreSpecTools(server) {
                 .max(2000)
                 .optional()
                 .describe('SPEC-733: Required for reverse transitions (done→implementing, discarded→draft). Must be ≥30 chars explaining why the spec is being reopened.'),
+            reconciliationRequestId: z
+                .string()
+                .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u)
+                .optional()
+                .describe('Trusted local MCP only: lowercase UUID idempotency key for implementing to review reconciliation.'),
+            expectedImplementingTransitionId: z.string().max(500).optional(),
+            implementationReviewDigest: z
+                .string()
+                .regex(/^sha256:[a-f0-9]{64}$/u)
+                .optional()
+                .describe('SHA-256 of the exact validation-report.json bytes. Required implementation evidence for status=done; for status=review it is valid only inside the complete trusted local-MCP reconciliation tuple.'),
             forceApprove: z
                 .boolean()
                 .optional()
                 .describe('SPEC-769: Force-approve a spec that scored below 70 on the readiness gate. Warnings are stored in spec.md frontmatter. Use when the LLM has explicitly confirmed the spec is ready despite a low readiness score.'),
         },
-    }, safeTracked('update_status', async (args) => handleUpdateStatus(args)));
+    }, safeTracked('update_status', async (args) => runWithTrustedLocalMcpContext(() => handleUpdateStatus(args))));
     server.registerTool('update_status_batch', {
         description: 'Batch update many specs to the same status in one MCP execution. Uses the same transition rules as update_status and reports updated/skipped/failed per spec.',
         inputSchema: {
@@ -415,7 +425,7 @@ export function registerCoreSpecTools(server) {
                 .max(4096)
                 .optional()
                 .describe('Absolute project root. Preferred when projectId is unknown.'),
-            status: SpecStatusEnum.describe('New status for all specs'),
+            status: SpecStatusEnum.exclude(['done']).describe('New status for all specs. Batch supports draft, review, approved, implementing, and discarded; close done specs individually with full evidence.'),
             dryRun: z.boolean().optional().describe('Preview the batch without mutating any spec.'),
             reviewNotes: z
                 .string()
@@ -444,7 +454,7 @@ export function registerCoreSpecTools(server) {
                 .optional()
                 .describe('Analysis depth: shallow (fast scan), deep (full file scan), deep-v2 (full scan + test coverage, dependency graph, API detection, complexity metrics, config analysis). Default: shallow'),
         },
-    }, safeLicensed('reverse_engineer', async (args) => handleReverseEngineer(args)));
+    }, safeGoverned('reverse_engineer', async (args) => handleReverseEngineer(args)));
     // 10. validate
     server.registerTool('validate', {
         description: t('tools.validate.description'),

package/dist/tools/safe-handler.d.ts

@@ -30,27 +30,19 @@ export declare function withToolTimeout<T>(p: Promise<T>, ms: number, fallback:
  * graceful MCP error response, preventing server crashes. Also enforces a
  * configurable execution timeout (default 55s, env PLANU_TOOL_TIMEOUT_MS).
  *
- * Usage — only for alwaysAllowed tools (activate_license, license_status, etc.):
+ * Usage — for infrastructure tools that do not need usage recording:
  *   server.registerTool('my_tool', schema, safe(async (args) => { ... }));
  */
 export declare function safe<T>(handler: (args: T, extra?: unknown) => Promise<ToolResult>): (args: T, extra?: unknown) => Promise<ToolResult>;
 /**
- * Composable wrapper: usage tracking + error boundary.
- * Use for free-tier tools that need rate limiting and usage recording.
+ * Composable wrapper: neutral local usage tracking + error boundary.
  *
  * Usage:
- *   server.registerTool('free_tool', schema, safeTracked('free_tool', async (args) => { ... }));
+ *   server.registerTool('tracked_tool', schema, safeTracked('tracked_tool', async (args) => { ... }));
  */
 export declare function safeTracked<T>(toolName: string, handler: (args: T, extra?: unknown) => Promise<ToolResult>): (args: T, extra?: unknown) => Promise<ToolResult>;
 /**
- * Composable wrapper: usage tracking + license gate + error boundary.
- * Use for tools that require a paid plan.
- *
- * Trial bypass: if the 30-day free trial is active, skips the license gate
- * entirely and routes to safeTracked (usage tracking without restriction).
- *
- * Usage:
- *   server.registerTool('pro_tool', schema, safeLicensed('pro_tool', async (args) => { ... }));
+ * Neutral governed wrapper: engineering budget + local usage + error boundary.
  */
-export declare function safeLicensed<T>(toolName: string, handler: (args: T, extra?: unknown) => Promise<ToolResult>): (args: T, extra?: unknown) => Promise<ToolResult>;
+export declare function safeGoverned<T>(toolName: string, handler: (args: T, extra?: unknown) => Promise<ToolResult>): (args: T, extra?: unknown) => Promise<ToolResult>;
 //# sourceMappingURL=safe-handler.d.ts.map

package/dist/tools/safe-handler.js

@@ -1,8 +1,7 @@
 // tools/safe-handler.ts — Generic error-boundary wrapper for MCP tool handlers.
 // Catches any unhandled error and returns a graceful MCP error response
 // instead of crashing the server. Includes cancellation-aware execution deadlines.
-import { withLicenseGate, withUsageTracking } from './license-gate.js';
-import { isTrialActive } from '../engine/trial-engine.js';
+import { withUsageTracking } from './usage-tracking.js';
 import { sanitizePath } from './sanitize-path.js';
 import { ensureHooksStarted } from './start-hooks.js';
 import { ensureWorkersStarted } from '../engine/workers/index.js';
@@ -388,7 +387,7 @@ export function withToolTimeout(p, ms, fallback) {
  * graceful MCP error response, preventing server crashes. Also enforces a
  * configurable execution timeout (default 55s, env PLANU_TOOL_TIMEOUT_MS).
  *
- * Usage — only for alwaysAllowed tools (activate_license, license_status, etc.):
+ * Usage — for infrastructure tools that do not need usage recording:
  *   server.registerTool('my_tool', schema, safe(async (args) => { ... }));
  */
 export function safe(handler) {
@@ -616,26 +615,18 @@ function safeWithTelemetry(toolName, handler) {
     };
 }
 /**
- * Composable wrapper: usage tracking + error boundary.
- * Use for free-tier tools that need rate limiting and usage recording.
+ * Composable wrapper: neutral local usage tracking + error boundary.
  *
  * Usage:
- *   server.registerTool('free_tool', schema, safeTracked('free_tool', async (args) => { ... }));
+ *   server.registerTool('tracked_tool', schema, safeTracked('tracked_tool', async (args) => { ... }));
  */
 export function safeTracked(toolName, handler) {
     return safeWithTelemetry(toolName, withUsageTracking(toolName, handler));
 }
 /**
- * Composable wrapper: usage tracking + license gate + error boundary.
- * Use for tools that require a paid plan.
- *
- * Trial bypass: if the 30-day free trial is active, skips the license gate
- * entirely and routes to safeTracked (usage tracking without restriction).
- *
- * Usage:
- *   server.registerTool('pro_tool', schema, safeLicensed('pro_tool', async (args) => { ... }));
+ * Neutral governed wrapper: engineering budget + local usage + error boundary.
  */
-export function safeLicensed(toolName, handler) {
+export function safeGoverned(toolName, handler) {
     return safeWithTelemetry(toolName, async (args, extra) => {
         // Enforce spec budget limit when specId is present in args (opt-in enforcement)
         if (args !== null && typeof args === 'object') {
@@ -646,14 +637,7 @@ export function safeLicensed(toolName, handler) {
                 await checkBudgetEnforcement(specId, projectPath);
             }
         }
-        // Check server-backed 30-day trial (fast local read only)
-        if (process.env.PLANU_SKIP_TRIAL !== 'true') {
-            const trialActive = isTrialActive(); // always false — trial tools removed
-            if (trialActive) {
-                return withUsageTracking(toolName, handler)(args, extra);
-            }
-        }
-        return withUsageTracking(toolName, withLicenseGate(toolName, handler))(args, extra);
+        return withUsageTracking(toolName, handler)(args, extra);
     });
 }
 //# sourceMappingURL=safe-handler.js.map

package/dist/tools/schemas/index.d.ts

@@ -16,7 +16,7 @@ export { TokenIntelligencePeriodEnum, TokenIntelligenceGroupByEnum, TokenIntelli
 export { ProjectGraphActionEnum, ProjectGraphQueryKindEnum } from './project-graph.js';
 export { ConfigureLLMProvidersActionEnum, LoadBalancingStrategyEnum, } from './llm-provider-schemas.js';
 export { PluginActionEnum } from './plugins-schemas.js';
-export { ListSpecsOutputSchema, EstimateOutputSchema, ValidateOutputSchema, CheckReadinessOutputSchema, LicenseStatusOutputSchema, } from './output-schemas.js';
+export { ListSpecsOutputSchema, EstimateOutputSchema, ValidateOutputSchema, CheckReadinessOutputSchema, } from './output-schemas.js';
 export { CreatePRFromSpecSchema, PRStatusSchema, ReviewPRSchema, CreateReleaseSchema, GenerateChangelogSchema, } from './github.js';
 export { SkillSearchInputSchema, SkillInstallInputSchema } from './skill-registry-schemas.js';
 export { EcosystemStatusInputSchema } from './ecosystem-schemas.js';

package/dist/tools/schemas/index.js

@@ -17,7 +17,7 @@ export { TokenIntelligencePeriodEnum, TokenIntelligenceGroupByEnum, TokenIntelli
 export { ProjectGraphActionEnum, ProjectGraphQueryKindEnum } from './project-graph.js';
 export { ConfigureLLMProvidersActionEnum, LoadBalancingStrategyEnum, } from './llm-provider-schemas.js';
 export { PluginActionEnum } from './plugins-schemas.js';
-export { ListSpecsOutputSchema, EstimateOutputSchema, ValidateOutputSchema, CheckReadinessOutputSchema, LicenseStatusOutputSchema, } from './output-schemas.js';
+export { ListSpecsOutputSchema, EstimateOutputSchema, ValidateOutputSchema, CheckReadinessOutputSchema, } from './output-schemas.js';
 export { CreatePRFromSpecSchema, PRStatusSchema, ReviewPRSchema, CreateReleaseSchema, GenerateChangelogSchema, } from './github.js';
 export { SkillSearchInputSchema, SkillInstallInputSchema } from './skill-registry-schemas.js';
 export { EcosystemStatusInputSchema } from './ecosystem-schemas.js';

package/dist/tools/schemas/output-schemas.d.ts

@@ -216,27 +216,4 @@ export declare const CheckReadinessOutputSchema: {
     }, z.core.$strip>>;
     humanSummary: z.ZodOptional<z.ZodString>;
 };
-export declare const LicenseStatusOutputSchema: {
-    version: z.ZodString;
-    plan: z.ZodString;
-    toolsAvailable: z.ZodNumber;
-    toolsTotal: z.ZodNumber;
-    limits: z.ZodObject<{
-        maxProjects: z.ZodNumber;
-        currentProjects: z.ZodNumber;
-        maxActiveSpecs: z.ZodNumber;
-    }, z.core.$strip>;
-    customer: z.ZodOptional<z.ZodObject<{
-        name: z.ZodString;
-        email: z.ZodString;
-        variant: z.ZodString;
-        activatedAt: z.ZodString;
-        lastValidatedAt: z.ZodString;
-    }, z.core.$strip>>;
-    activationSlots: z.ZodOptional<z.ZodObject<{
-        used: z.ZodNumber;
-        total: z.ZodNumber;
-    }, z.core.$strip>>;
-    upgradeUrl: z.ZodOptional<z.ZodString>;
-};
 //# sourceMappingURL=output-schemas.d.ts.map

package/dist/tools/schemas/output-schemas.js

@@ -159,32 +159,4 @@ export const CheckReadinessOutputSchema = {
         .optional(),
     humanSummary: z.string().optional(),
 };
-// ── license_status ──────────────────────────────────────────────────────────
-export const LicenseStatusOutputSchema = {
-    version: z.string(),
-    plan: z.string(),
-    toolsAvailable: z.number(),
-    toolsTotal: z.number(),
-    limits: z.object({
-        maxProjects: z.number(),
-        currentProjects: z.number(),
-        maxActiveSpecs: z.number(),
-    }),
-    customer: z
-        .object({
-        name: z.string(),
-        email: z.string(),
-        variant: z.string(),
-        activatedAt: z.string(),
-        lastValidatedAt: z.string(),
-    })
-        .optional(),
-    activationSlots: z
-        .object({
-        used: z.number(),
-        total: z.number(),
-    })
-        .optional(),
-    upgradeUrl: z.string().optional(),
-};
 //# sourceMappingURL=output-schemas.js.map

package/dist/tools/schemas/spec.d.ts

@@ -38,6 +38,10 @@ export declare const SpecTargetEnum: z.ZodEnum<{
     ios: "ios";
     shared: "shared";
 }>;
+export declare const SpecAcFormatEnum: z.ZodEnum<{
+    bdd: "bdd";
+    checkbox: "checkbox";
+}>;
 export declare const ExperienceLevelEnum: z.ZodEnum<{
     beginner: "beginner";
     expert: "expert";

package/dist/tools/schemas/spec.js

@@ -31,6 +31,9 @@ export const SpecTargetEnum = z
     'android',
 ])
     .describe('Target area: frontend | backend | shared | fullstack | infrastructure | database | ios | android');
+export const SpecAcFormatEnum = z
+    .enum(['bdd', 'checkbox'])
+    .describe('Acceptance criteria format: bdd | checkbox');
 export const ExperienceLevelEnum = z
     .enum(['beginner', 'intermediate', 'expert'])
     .describe('Experience level: beginner, intermediate, or expert');

package/dist/tools/schemas/validate-output-schema.d.ts

@@ -244,6 +244,17 @@ export declare const ValidateOutputSchema: {
     }>;
     submittedAt: z.ZodISODateTime;
     cursor: z.ZodString;
+    queue: z.ZodObject<{
+        status: z.ZodEnum<{
+            active: "active";
+            queued: "queued";
+            terminal: "terminal";
+        }>;
+        position: z.ZodNullable<z.ZodNumber>;
+        aheadCount: z.ZodNumber;
+        capacity: z.ZodNumber;
+        remainingBudgetMs: z.ZodNumber;
+    }, z.core.$strip>;
     terminalStates: z.ZodTuple<[z.ZodLiteral<"completed">, z.ZodLiteral<"failed">, z.ZodLiteral<"cancelled">, z.ZodLiteral<"dead-letter">], null>;
     resultSchema: z.ZodLiteral<"validate-completion/v1">;
     observation: z.ZodObject<{

package/dist/tools/schemas/validate-output-schema.js

@@ -195,6 +195,13 @@ export const ValidateOutputSchema = {
     state: z.enum(['accepted', 'running', 'checkpointed']),
     submittedAt: z.iso.datetime(),
     cursor: z.string().regex(/^[a-f0-9]{64}$/),
+    queue: z.object({
+        status: z.enum(['active', 'queued', 'terminal']),
+        position: z.number().int().positive().nullable(),
+        aheadCount: z.number().int().nonnegative(),
+        capacity: z.number().int().positive(),
+        remainingBudgetMs: z.number().int().nonnegative(),
+    }),
     terminalStates: z.tuple([
         z.literal('completed'),
         z.literal('failed'),

package/dist/tools/spec-prompt-handler.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { safeLicensed } from './safe-handler.js';
+import { safeGoverned } from './safe-handler.js';
 import { getSpec } from '../storage/spec-store.js';
 import { hashProjectPath } from '../storage/base-store.js';
 import { generatePromptFromSpec } from '../engine/spec-prompt-generator.js';
@@ -109,7 +109,7 @@ export function registerSpecPromptHandlers(server) {
             destructiveHint: false,
             openWorldHint: false,
         },
-    }, safeLicensed('expose_spec_as_prompt', async (args) => handleExposeSpecAsPrompt(args, server)));
+    }, safeGoverned('expose_spec_as_prompt', async (args) => handleExposeSpecAsPrompt(args, server)));
     server.registerTool('list_spec_prompts', {
         description: 'List all Planu spec prompts registered in the current session. ' +
             'Returns prompt names, spec IDs, and titles.',
@@ -120,6 +120,6 @@ export function registerSpecPromptHandlers(server) {
             destructiveHint: false,
             openWorldHint: false,
         },
-    }, safeLicensed('list_spec_prompts', (args) => Promise.resolve(handleListSpecPrompts(args))));
+    }, safeGoverned('list_spec_prompts', (args) => Promise.resolve(handleListSpecPrompts(args))));
 }
 //# sourceMappingURL=spec-prompt-handler.js.map

package/dist/tools/sync-spec-state-handler.d.ts

@@ -12,7 +12,7 @@ export declare function syncSpecState(projectPath: string, projectId: string): P
 export declare function startupSync(): Promise<void>;
 /**
  * Registers the sync_spec_state tool on the MCP server (SPEC-334).
- * Always-on (free) tool — registered directly without safeLicensed.
+ * Always-on (free) tool — registered directly without safeGoverned.
  */
 export declare function registerSyncSpecStateTool(server: McpServer): void;
 //# sourceMappingURL=sync-spec-state-handler.d.ts.map

package/dist/tools/sync-spec-state-handler.js

@@ -12,7 +12,7 @@ import { parseFrontmatter } from '../engine/frontmatter-parser.js';
 import { verifyTerminalFrontmatter } from '../engine/frontmatter-sha/index.js';
 import { appendTransitionEvent } from '../storage/transition-log.js';
 import { cleanEphemeralArtifacts } from '../engine/housekeeping/index.js';
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 // ---------------------------------------------------------------------------
 // Sync helpers (exported for startup use)
 // ---------------------------------------------------------------------------
@@ -33,9 +33,15 @@ export async function syncSpecState(projectPath, projectId) {
             divergences: [],
             errors: [`Failed to load specs for ${projectId}: ${msg}`],
             rejected: [],
+            ghosts: [],
         };
     }
+    // SPEC-1351 (AC3): quarantine store entries whose spec.md is missing on
+    // disk — ghost registrations left behind by a create_spec attempt that
+    // reported success but never persisted (or whose file was later deleted).
+    const ghosts = await detectGhostSpecs(projectId, dataEntries);
     const { updates, report } = await detectSpecStateDivergences(projectPath, dataEntries);
+    report.ghosts = ghosts;
     // SyncReport.rejected is always defined (SPEC-720)
     const TERMINAL_STATUSES = ['done', 'discarded'];
     for (const { specId, newStatus } of updates) {
@@ -136,6 +142,41 @@ export async function syncSpecState(projectPath, projectId) {
     }
     return report;
 }
+/**
+ * SPEC-1351 (AC3): scan the data store for entries whose spec.md is missing on
+ * disk and quarantine each one — appends a `ghost_spec_quarantined` transition
+ * event (surfaced by workspace_alerts with a recovery action) and returns the
+ * list so callers can report it inline.
+ */
+async function detectGhostSpecs(projectId, dataEntries) {
+    const ghosts = [];
+    await Promise.all(dataEntries.map(async (entry) => {
+        if (!entry.specPath) {
+            return;
+        }
+        try {
+            const fileStat = await stat(entry.specPath);
+            if (fileStat.size > 0) {
+                return;
+            }
+        }
+        catch {
+            // fall through to quarantine — missing or unreadable spec.md
+        }
+        const reason = `Store entry ${entry.id} references spec.md at ${entry.specPath}, which is missing or empty on disk. Recreate the spec via create_spec or restore spec.md from git/backup.`;
+        ghosts.push({ specId: entry.id, specPath: entry.specPath, reason });
+        void appendTransitionEvent({
+            projectId,
+            specId: entry.id,
+            eventType: 'ghost_spec_quarantined',
+            actor: 'sync_spec_state',
+            reason,
+        }).catch(() => {
+            /* best-effort */
+        });
+    }));
+    return ghosts;
+}
 /**
  * Startup sync: iterates all registered projects and calls syncSpecState for each.
  * Non-blocking — errors are logged but not propagated.
@@ -183,6 +224,13 @@ function formatReport(report, label) {
             lines.push(`    - ${r.specId}: ${r.reason}`);
         }
     }
+    // SPEC-1351: Ghost store entries quarantined (missing spec.md on disk)
+    if ((report.ghosts?.length ?? 0) > 0) {
+        lines.push('  Quarantined ghosts (spec.md missing — recreate or restore):');
+        for (const g of report.ghosts ?? []) {
+            lines.push(`    - ${g.specId}: ${g.specPath}`);
+        }
+    }
     if (report.errors.length > 0) {
         lines.push('  Errors:');
         for (const e of report.errors) {
@@ -196,7 +244,7 @@ function formatReport(report, label) {
 // ---------------------------------------------------------------------------
 /**
  * Registers the sync_spec_state tool on the MCP server (SPEC-334).
- * Always-on (free) tool — registered directly without safeLicensed.
+ * Always-on (free) tool — registered directly without safeGoverned.
  */
 export function registerSyncSpecStateTool(server) {
     server.registerTool('sync_spec_state', {

package/dist/tools/tool-entry.d.ts

@@ -29,12 +29,12 @@ export interface ToolEntry {
     annotations?: Record<string, unknown>;
     /**
      * Which safe-handler wrapper to apply.
-     * - 'tracked'  → safeTracked (free tier, usage tracking)    [default]
-     * - 'licensed' → safeLicensed (requires paid plan)
-     * - 'safe'     → safe (no license/tracking — for infra/admin tools)
+     * - 'tracked'  → safeTracked (local usage tracking) [default]
+     * - 'governed' → safeGoverned (engineering budget + local usage)
+     * - 'safe'     → safe (no usage tracking — for infra/admin tools)
      * - 'none'     → raw handler with no wrapper (rare — test only)
      */
-    wrap?: 'tracked' | 'licensed' | 'safe' | 'none';
+    wrap?: 'tracked' | 'governed' | 'safe' | 'none';
     /**
      * Optional Zod output schema for MCP outputSchema validation.
      * When provided, passed as `outputSchema` to server.registerTool().

package/dist/tools/tool-entry.js

@@ -3,7 +3,7 @@
 // Phase 1 (refactor/declarative-registry): replaces the register-*-tools.ts boilerplate pattern:
 //   server.registerTool(name, { description, inputSchema, annotations }, safeXxx(name, handler))
 // with a plain data array that registerFromEntries() consumes.
-import { safe, safeTracked, safeLicensed } from './safe-handler.js';
+import { safe, safeGoverned, safeTracked } from './safe-handler.js';
 // ---------------------------------------------------------------------------
 // Registration helper
 // ---------------------------------------------------------------------------
@@ -21,8 +21,8 @@ export function registerFromEntries(server, entries) {
         if (wrap === 'none') {
             wrappedHandler = handler;
         }
-        else if (wrap === 'licensed') {
-            wrappedHandler = safeLicensed(name, handler);
+        else if (wrap === 'governed') {
+            wrappedHandler = safeGoverned(name, handler);
         }
         else if (wrap === 'safe') {
             wrappedHandler = safe(handler);