openplanr 1.25.3 → 2.0.0

package/dist/services/spec-service.js

@@ -2,39 +2,39 @@
  * spec-service — directory-aware CRUD for spec-driven planning mode.
  *
  * Unlike agile/QT artifacts which are flat single files, each spec is a
- * **self-contained directory** (per BL-011 addendum + design doc):
+ * **self-contained directory**:
  *
  *   .planr/specs/SPEC-NNN-{slug}/
  *   ├── SPEC-NNN-{slug}.md              ← the spec document
  *   ├── design/                         ← UI mockups + design-spec.md (if any)
  *   │   ├── *.png
- *   │   └── design-spec.md              ← reserved path (written by planr-pipeline's designer-agent)
+ *   │   └── design-spec.md              ← reserved path (written by the host-native designer role)
  *   ├── stories/
- *   │   └── US-NNN-{slug}.md            ← US-NNN scoped to this spec
+ *   │   └── US-NNN-{slug}.md            ← project-global story ID
  *   └── tasks/
- *       └── T-NNN-{slug}.md             ← T-NNN scoped to this spec
+ *       └── T-NNN-{slug}.md             ← project-global task ID
  *
  * Why directory-per-spec:
  *  - Self-contained / portable / `rm -rf` clean
  *  - `PREFIX-NNN-slug` naming consistent with every other planr artifact
- *  - US-NNN and T-NNN are SCOPED TO THE PARENT SPEC (not project-globally
- *    unique). Two specs can each have their own US-001. Disambiguation is
- *    via the path or via `specId` frontmatter.
- *  - Schema matches planr-pipeline plugin verbatim — both products
- *    share one contract. See https://github.com/openplanr/planr-pipeline
+ *  - SPEC-NNN, US-NNN, and T-NNN IDs are project-global and monotonic. The
+ *    sequence never reuses gaps; `specId` and `storyId` retain the hierarchy.
+ *  - Schemas are owned by the OpenPlanr Protocol package and shared by all hosts.
  *
  * This service owns dedicated planning inside the planr CLI. The pipeline
  * independently provides feature-local PO planning as part of its complete
  * PO → Design → Review → DEV → QA flow. Both producers share the artifact
  * contract and record provenance so their intentional overlap stays clear.
  */
+import { randomUUID } from 'node:crypto';
+import fsPromises from 'node:fs/promises';
 import path from 'node:path';
 import { ensureDir, fileExists, listFiles, readFile, writeFile } from '../utils/fs.js';
 import { logger } from '../utils/logger.js';
-import { parseMarkdown } from '../utils/markdown.js';
+import { parseMarkdown, toMarkdownWithFrontmatter } from '../utils/markdown.js';
 import { slugify } from '../utils/slugify.js';
 import { atomicWriteFile } from './atomic-write-service.js';
-import { getNextId } from './id-service.js';
+import { previewPlanningIds, reservePlanningIds } from './planning-id-service.js';
 import { appendOpenPlanrProvenance, readOpenPlanrVersion } from './provenance-service.js';
 import { renderTemplate } from './template-service.js';
 // ---------------------------------------------------------------------------
@@ -101,7 +101,7 @@ export async function listSpecs(projectDir, config) {
         return [];
     const fs = await import('node:fs/promises');
     const entries = await fs.readdir(specsRoot, { withFileTypes: true });
-    const dirRegex = /^([A-Z]+-\d{3})-(.+)$/;
+    const dirRegex = /^([A-Z]+-\d{3,})-(.+)$/;
     const results = [];
     for (const entry of entries) {
         if (!entry.isDirectory())
@@ -157,7 +157,7 @@ export async function createSpec(projectDir, config, title, options = {}) {
     const specsRoot = getSpecsRootDir(projectDir, config);
     await ensureDir(specsRoot);
     // Cross-spec slug-collision check. Two specs with the same slug would be
-    // ambiguous in pipeline handoffs (`/planr-pipeline:plan {slug}` —
+    // ambiguous in host-native planning handoffs (`planr-plan {slug}` —
     // which spec?), and they'd be hard to distinguish in `planr spec list`.
     // Refuse early with a clear suggestion.
     {
@@ -169,16 +169,13 @@ export async function createSpec(projectDir, config, title, options = {}) {
         catch {
             // specs/ may not exist yet — fine
         }
-        const slugRe = new RegExp(`^[A-Z]+-\\d{3}-${slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`);
+        const slugRe = new RegExp(`^[A-Z]+-\\d{3,}-${slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`);
         const collision = entries.find((e) => e.isDirectory() && slugRe.test(e.name));
         if (collision) {
             throw new Error(`A spec with slug "${slug}" already exists at ${collision.name}. Use a different --slug or delete the existing spec with \`planr spec destroy ${collision.name.split('-').slice(0, 2).join('-')}\`.`);
         }
     }
-    const prefix = config.idPrefix.spec || 'SPEC';
-    // Custom-scan: getNextId() looks for files; here we look at *directories*.
-    // We compose a synthetic "files-only" view by listing entries with the prefix.
-    const id = await nextSpecId(specsRoot, prefix);
+    const id = (await reservePlanningIds(projectDir, config, { SPEC: 1 })).SPEC[0];
     const dirName = `${id}-${slug}`;
     const specDir = path.join(specsRoot, dirName);
     if (await fileExists(specDir)) {
@@ -195,7 +192,7 @@ export async function createSpec(projectDir, config, title, options = {}) {
         slug,
         title,
         status: 'pending',
-        schemaVersion: '1.0.0',
+        schemaVersion: '1.7.0',
         priority: options.priority || 'P1',
         milestone: options.milestone || '',
         po: options.po || '',
@@ -204,16 +201,16 @@ export async function createSpec(projectDir, config, title, options = {}) {
     }, config.templateOverrides);
     await writeFile(specFile, content);
     // Drop a .gitkeep into design/ so the empty subdir survives commits
-    // (stories/ and tasks/ will be populated by `planr spec decompose` later).
+    // (stories/ and tasks/ are populated by the host-native planning skill).
     await writeFile(path.join(getSpecDesignDir(specDir), '.gitkeep'), '');
     logger.debug(`Created spec ${id}: ${specDir}`);
     return { id, slug, specDir, specFile };
 }
 /**
- * Pick the next available SPEC ID by scanning sibling directories under
- * `.planr/specs/`. Mirrors `id-service.getNextId()` but for directories.
+ * Preview the next project-global SPEC ID from sibling directories.
+ * Reservation uses planning-id-service so deleted IDs are never reused.
  */
-async function nextSpecId(specsRoot, prefix) {
+export async function nextSpecId(specsRoot, prefix) {
     const fs = await import('node:fs/promises');
     let entries = [];
     try {
@@ -222,20 +219,174 @@ async function nextSpecId(specsRoot, prefix) {
     catch {
         return `${prefix}-001`;
     }
-    const re = new RegExp(`^${prefix}-(\\d{3})-`);
-    const taken = new Set();
+    const re = new RegExp(`^${prefix}-(\\d{3,})-`);
+    let maximum = 0;
     for (const e of entries) {
         if (!e.isDirectory())
             continue;
         const m = e.name.match(re);
         if (m)
-            taken.add(Number.parseInt(m[1], 10));
+            maximum = Math.max(maximum, Number.parseInt(m[1], 10));
     }
-    let n = 1;
-    while (taken.has(n))
-        n++;
+    const n = maximum + 1;
     return `${prefix}-${String(n).padStart(3, '0')}`;
 }
+function markdownInline(value) {
+    return String(value)
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .replace(/[\\`*_[\]()!|<>]/gu, '\\$&');
+}
+function markdownCode(value) {
+    const text = String(value).replace(/\s+/gu, ' ').trim();
+    const longestRun = Math.max(0, ...[...text.matchAll(/`+/gu)].map((match) => match[0].length));
+    const fence = '`'.repeat(longestRun + 1);
+    const padding = text.startsWith('`') || text.endsWith('`') ? ' ' : '';
+    return `${fence}${padding}${text}${padding}${fence}`;
+}
+function operatingOriginSection(input) {
+    const origin = input.operatingOrigin;
+    const line = (label, value) => `- **${label}:** ${markdownInline(value)}`;
+    const identity = (label, value) => `- **${label}:** ${markdownCode(value)}`;
+    const nested = (label, values) => values.length > 0
+        ? `  - ${label}: ${values.map(markdownInline).join('; ')}`
+        : `  - ${label}: none recorded`;
+    const perspectives = origin.perspectives
+        .map((perspective) => [
+        `- **${markdownInline(perspective.roleKind)} · ${markdownCode(perspective.roleId)}** (${markdownInline(perspective.stance)}): ${markdownInline(perspective.summary)}`,
+        nested('Constraints', perspective.constraints),
+        nested('Uncertainties', perspective.uncertainties),
+    ].join('\n'))
+        .join('\n');
+    const evidence = origin.evidence.length === 0
+        ? '- No access-safe evidence reference was available.'
+        : origin.evidence
+            .map((entry) => [
+            `- ${markdownCode(entry.evidenceRefId)} · ${markdownInline(entry.relation)} · ${markdownInline(entry.freshness)} · confidence ${entry.confidence}`,
+            `  - Summary: ${entry.summary === null ? 'restricted; summary unavailable' : markdownInline(entry.summary)}`,
+            nested('Limitations', entry.limitations),
+        ].join('\n'))
+            .join('\n');
+    const omitted = origin.omissions.map((entry) => `${entry.count} ${markdownInline(entry.reason)}`);
+    const actionPath = `#/operate/actions/${encodeURIComponent(origin.action.actionId)}/planning`;
+    return [
+        '## Operating origin',
+        '',
+        'This section is the access-safe human translation of the accepted Operate proposal. Machine authority remains in the adjacent `operating-origin.json` sidecar.',
+        '',
+        '### Problem and constraints',
+        '',
+        line('Problem', input.framing.problem),
+        line('Constraints', input.framing.constraints.length > 0 ? input.framing.constraints.join('; ') : 'none recorded'),
+        '',
+        '### Decision and intended Outcome',
+        '',
+        identity('Correlation', origin.correlationId),
+        identity('Proposal', origin.proposalId),
+        `- **Decision:** ${markdownCode(origin.decision.decisionId)} revision ${origin.decision.revision}`,
+        line('Decision title', origin.decision.title),
+        line('Decision rationale', origin.decision.rationale),
+        line('Intended Outcome', origin.decision.outcome),
+        `- **Action:** ${markdownCode(origin.action.actionId)} revision ${origin.action.revision}`,
+        line('Expected result', origin.action.expectedResult),
+        '',
+        '### Scope, non-scope, and risks',
+        '',
+        line('Scope', input.framing.scope.join('; ')),
+        line('Non-scope', input.framing.nonScope.length > 0 ? input.framing.nonScope.join('; ') : 'none recorded'),
+        line('Risks', input.framing.risks.length > 0 ? input.framing.risks.join('; ') : 'none recorded'),
+        '',
+        '### Accepted perspectives',
+        '',
+        perspectives,
+        '',
+        '### Evidence and limitations',
+        '',
+        evidence,
+        ...(omitted.length > 0 ? ['', line('Access-safe omissions', omitted.join('; '))] : []),
+        '',
+        '### Verification',
+        '',
+        identity('Metric', origin.verification.metricId),
+        line('Baseline', origin.verification.baseline),
+        line('Target', origin.verification.target),
+        line('Window', origin.verification.window),
+        line('Method', origin.verification.method),
+        '',
+        '### Continue in Operate',
+        '',
+        `Run ${markdownCode(`planr operate dashboard ${origin.cycleId} --actor <authorizedActorId>`)}, then [open this Action in Planning](${actionPath}).`,
+    ].join('\n');
+}
+/**
+ * Render, but do not publish, a Protocol 1.7 SPEC for an approved Operate handoff.
+ * Allocation reserves a project-global monotonic ID; the caller holds the
+ * Planning bridge lock until its directory rename commits.
+ */
+export async function prepareOperatingSpecDraft(projectDir, config, input) {
+    const slug = slugify(input.slug);
+    if (!slug || slug !== input.slug || Number.isNaN(Date.parse(input.createdAt))) {
+        throw Object.assign(new Error('Operating Planning requires a canonical slug and timestamp.'), {
+            code: 'E_OPERATE_PLANNING_INVALID',
+        });
+    }
+    const specsRoot = getSpecsRootDir(projectDir, config);
+    await ensureDir(specsRoot);
+    const fs = await import('node:fs/promises');
+    const entries = await fs.readdir(specsRoot, { withFileTypes: true });
+    const escapedSlug = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (entries.some((entry) => entry.isDirectory() && new RegExp(`^[A-Z]+-\\d{3,}-${escapedSlug}$`).test(entry.name))) {
+        throw Object.assign(new Error('An existing SPEC already uses this canonical planning slug.'), {
+            code: 'E_OPERATE_PLANNING_CONFLICT',
+        });
+    }
+    const id = (await reservePlanningIds(projectDir, config, { SPEC: 1 })).SPEC[0];
+    const specDir = getSpecDir(projectDir, config, id, slug);
+    const specFile = path.join(specDir, `${id}-${slug}.md`);
+    const date = input.createdAt.slice(0, 10);
+    const list = (values) => values.map((value) => `- ${value}`).join('\n');
+    const titlePlaceholder = '__OPENPLANR_OPERATING_SPEC_TITLE__';
+    const rendered = await renderTemplate('spec/spec-shaped.md.hbs', {
+        id,
+        slug,
+        title: titlePlaceholder,
+        schemaVersion: '1.7.0',
+        priority: 'P1',
+        milestone: '',
+        po: '',
+        created: date,
+        date,
+        uiFiles: [],
+        context: `${input.framing.problem}\n\nObjective: ${input.framing.objective}\n\nUsers: ${input.framing.users.join('; ')}`,
+        functionalRequirements: input.framing.requirements,
+        businessRules: list(input.framing.constraints),
+        outOfScope: input.framing.nonScope,
+        acceptanceCriteria: input.framing.acceptanceOutcomes,
+        decompositionNotes: [
+            `Scope:\n${list(input.framing.scope)}`,
+            input.framing.risks.length > 0 ? `Risks:\n${list(input.framing.risks)}` : '',
+            'This SPEC inherits its operating origin through the adjacent closed sidecar. PLAN, Design, stories, tasks, and SHIP must not copy private operating bodies.',
+        ]
+            .filter(Boolean)
+            .join('\n\n'),
+    }, config.templateOverrides);
+    const parsed = parseMarkdown(rendered);
+    const frontmatter = {
+        id,
+        title: input.title,
+        slug,
+        schemaVersion: '1.7.0',
+        status: 'shaping',
+        priority: 'P1',
+        po: input.actorId,
+        created: date,
+        updated: date,
+        ui_files: [],
+        tech_dependencies: [],
+    };
+    const content = toMarkdownWithFrontmatter(frontmatter, `${parsed.content.replaceAll(titlePlaceholder, input.title).trimEnd()}\n\n${operatingOriginSection(input)}\n`);
+    return { id, slug, specDir, specFile, content };
+}
 export async function readSpec(projectDir, config, specId) {
     const resolved = await resolveSpecDir(projectDir, config, specId);
     if (!resolved)
@@ -274,15 +425,17 @@ export async function updateSpecFields(projectDir, config, specId, fields) {
     const specFile = path.join(resolved.dir, `${specId}-${resolved.slug}.md`);
     const raw = await readFile(specFile);
     const today = new Date().toISOString().split('T')[0];
-    const allFields = { ...fields, updated: today };
+    await atomicWriteFile(specFile, updateSpecFrontmatter(raw, { ...fields, updated: today }));
+}
+function updateSpecFrontmatter(raw, fields) {
     const openIdx = raw.indexOf('---');
     const closeIdx = raw.indexOf('\n---', openIdx + 3);
     if (openIdx === -1 || closeIdx === -1) {
-        throw new Error(`Spec ${specId} has no valid frontmatter.`);
+        throw new Error('Spec has no valid frontmatter.');
     }
     let frontmatter = raw.slice(openIdx, closeIdx);
     const body = raw.slice(closeIdx);
-    for (const [key, value] of Object.entries(allFields)) {
+    for (const [key, value] of Object.entries(fields)) {
         const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
         const pattern = new RegExp(`^${escapedKey}:\\s*.*$`, 'm');
         const replacement = `${key}: ${formatYamlValue(value)}`;
@@ -293,7 +446,7 @@ export async function updateSpecFields(projectDir, config, specId, fields) {
             frontmatter += `\n${replacement}`;
         }
     }
-    await atomicWriteFile(specFile, frontmatter + body);
+    return frontmatter + body;
 }
 /**
  * Format a JS value as valid YAML for frontmatter.
@@ -340,7 +493,7 @@ export async function syncSpec(projectDir, config, specId, opts = {}) {
     const storyIds = new Set(stories.map((s) => s.id));
     for (const t of tasks) {
         if (!t.storyId) {
-            warnings.push(`Task ${t.id} (${t.filename}) has no storyId — set it manually or via \`planr spec decompose --force\`.`);
+            warnings.push(`Task ${t.id} (${t.filename}) has no storyId — set it manually or regenerate it with planr-plan.`);
         }
         else if (!storyIds.has(t.storyId)) {
             warnings.push(`Task ${t.id} (${t.filename}) references non-existent story ${t.storyId} in this spec. ` +
@@ -355,7 +508,7 @@ export async function syncSpec(projectDir, config, specId, opts = {}) {
     }
     for (const s of stories) {
         if (!tasksByStory.has(s.id)) {
-            warnings.push(`Story ${s.id} has no tasks — decomposition incomplete. Run \`planr spec decompose ${specId} --force\` or hand-author tasks.`);
+            warnings.push(`Story ${s.id} has no tasks — invoke planr-plan or hand-author tasks.`);
         }
     }
     // ── Check 3: missing specId in US/Task frontmatter ────────────────────
@@ -384,7 +537,7 @@ export async function syncSpec(projectDir, config, specId, opts = {}) {
         }
     }
     // ── Check 4: schema version drift ─────────────────────────────────────
-    const CURRENT_SCHEMA_VERSION = '1.0.0';
+    const CURRENT_SCHEMA_VERSION = '1.7.0';
     const specSchemaVersion = typeof spec.data.schemaVersion === 'string' ? spec.data.schemaVersion : null;
     if (specSchemaVersion && specSchemaVersion !== CURRENT_SCHEMA_VERSION) {
         warnings.push(`Spec uses schemaVersion ${specSchemaVersion} (current: ${CURRENT_SCHEMA_VERSION}). No auto-migration in v1 — review manually.`);
@@ -408,19 +561,314 @@ export async function syncAllSpecs(projectDir, config, opts = {}) {
     }
     return { specsScanned: specs.length, reports };
 }
+async function resolveDesignContext(projectDir, spec) {
+    const designDir = getSpecDesignDir(spec.specDir);
+    const designSpecPath = path.join(designDir, 'design-spec.md');
+    const hasDesignSpec = await fileExists(designSpecPath);
+    const pngFiles = (await listFiles(designDir, /\.png$/iu)).sort();
+    const declaredUiFiles = Array.isArray(spec.data.ui_files)
+        ? spec.data.ui_files.filter((file) => typeof file === 'string' && file.trim().length > 0)
+        : [];
+    const sections = [];
+    if (declaredUiFiles.length > 0) {
+        sections.push(`Declared UI files:\n${declaredUiFiles.map((file) => `- ${file}`).join('\n')}`);
+    }
+    if (pngFiles.length > 0) {
+        sections.push(`PNG inputs present:\n${pngFiles
+            .map((file) => `- ${path.relative(projectDir, path.join(designDir, file))}`)
+            .join('\n')}`);
+    }
+    if (hasDesignSpec) {
+        sections.push(`Design specification (${path.relative(projectDir, designSpecPath)}):\n${await readFile(designSpecPath)}`);
+    }
+    return {
+        hasDesign: declaredUiFiles.length > 0 || pngFiles.length > 0 || hasDesignSpec,
+        ...(sections.length > 0 ? { context: sections.join('\n\n') } : {}),
+    };
+}
+function specTaskInput(aiTask, storyId, taskIdMap, acceptanceCriteria) {
+    const acceptanceRefs = [...aiTask.acceptanceRefs];
+    const knownAcceptance = new Set(acceptanceCriteria.map(({ id }) => id));
+    const unknownAcceptance = acceptanceRefs.filter((id) => !knownAcceptance.has(id));
+    if (unknownAcceptance.length > 0) {
+        throw invalidDecomposition(`${aiTask.id} references unknown acceptance IDs: ${unknownAcceptance.join(', ')}.`);
+    }
+    const mappedDependencies = aiTask.dependsOn.map((dependencyId) => {
+        const mapped = taskIdMap.get(dependencyId);
+        if (!mapped)
+            throw invalidDecomposition(`${aiTask.id} depends on unknown task ${dependencyId}.`);
+        return mapped;
+    });
+    const acceptanceVerification = acceptanceCriteria
+        .filter(({ id }) => acceptanceRefs.includes(id))
+        .map(({ id, statement }) => `- ${id}: ${statement}`)
+        .join('\n');
+    const shared = {
+        storyId,
+        title: aiTask.title,
+        rationale: aiTask.rationale,
+        dependsOn: mappedDependencies,
+        filesCreate: aiTask.filesCreate,
+        filesModify: aiTask.filesModify,
+        filesPreserve: aiTask.filesPreserve,
+        objective: aiTask.objective,
+        technicalSpec: aiTask.technicalSpec,
+        testRequirements: [aiTask.testRequirements.trim(), acceptanceVerification]
+            .filter(Boolean)
+            .join('\n'),
+        reviewRisks: aiTask.reviewRisks,
+        browserSurfaces: aiTask.browserSurfaces,
+        acceptanceRefs,
+        acceptanceCriteria: acceptanceCriteria.filter(({ id }) => acceptanceRefs.includes(id)),
+    };
+    return aiTask.type === 'UI'
+        ? { ...shared, type: 'UI', agent: 'frontend-agent' }
+        : { ...shared, type: 'Tech', agent: 'backend-agent' };
+}
+function validateRenderedPlanningArtifact(content, expected) {
+    const parsed = parseMarkdown(content);
+    for (const [key, value] of Object.entries(expected)) {
+        if (parsed.data[key] !== value) {
+            throw invalidDecomposition(`rendered ${expected.id} has ${key}=${String(parsed.data[key])}; expected ${value}.`);
+        }
+    }
+}
+async function loadPlanningProtocolValidator() {
+    try {
+        const protocol = await import('planr-pipeline/protocol');
+        return protocol.validateProtocolArtifact;
+    }
+    catch (error) {
+        const moduleError = error;
+        if (moduleError.code === 'ERR_MODULE_NOT_FOUND' &&
+            moduleError.message.includes('planr-pipeline')) {
+            logger.warn('Full Protocol frontmatter validation is unavailable because optional planr-pipeline is not installed. Install the matching planr-pipeline version before promoting this spec.');
+            return null;
+        }
+        throw error;
+    }
+}
+function validatePlanningProtocolFrontmatter(validator, kind, content, artifactId, protocolVersion = '1.0.0') {
+    if (!validator)
+        return;
+    const issues = validator(kind, parseMarkdown(content).data, { protocolVersion });
+    if (issues.length === 0)
+        return;
+    const summary = issues
+        .slice(0, 8)
+        .map((issue) => `${issue.path} ${issue.rule}: ${issue.detail}`)
+        .join('; ');
+    const remainder = issues.length > 8 ? `; and ${issues.length - 8} more` : '';
+    throw invalidDecomposition(`rendered ${artifactId} violates Protocol ${protocolVersion} ${kind} frontmatter: ${summary}${remainder}.`);
+}
+async function removeDecompositionTransient(directory) {
+    try {
+        await fsPromises.rm(directory, { recursive: true, force: true });
+    }
+    catch (error) {
+        logger.debug(`Could not remove decomposition transient ${directory}`, error);
+    }
+}
+async function replaceSpecWithDecomposition(config, spec, existingStories, existingTasks, decomposition, allocation) {
+    const fs = await import('node:fs/promises');
+    const transactionId = randomUUID();
+    const specParent = path.dirname(spec.specDir);
+    const specDirName = path.basename(spec.specDir);
+    const stagedSpecDir = path.join(specParent, `.${specDirName}.decompose-stage-${transactionId}`);
+    const backupSpecDir = path.join(specParent, `.${specDirName}.decompose-backup-${transactionId}`);
+    const protocolValidator = await loadPlanningProtocolValidator();
+    try {
+        await fsPromises.cp(spec.specDir, stagedSpecDir, {
+            recursive: true,
+            force: false,
+            errorOnExist: true,
+        });
+        const stagedStoriesDir = getSpecStoriesDir(stagedSpecDir);
+        const stagedTasksDir = getSpecTasksDir(stagedSpecDir);
+        await ensureDir(stagedStoriesDir);
+        await ensureDir(stagedTasksDir);
+        for (const story of existingStories) {
+            await fs.rm(path.join(stagedStoriesDir, story.filename), { force: true });
+        }
+        for (const task of existingTasks) {
+            await fs.rm(path.join(stagedTasksDir, task.filename), { force: true });
+        }
+        let tasksCreated = 0;
+        const flatTasks = decomposition.stories.flatMap((story) => story.tasks);
+        const taskIdMap = new Map(flatTasks.map((task, index) => [task.id, allocation.T[index]]));
+        for (const [storyIndex, aiStory] of decomposition.stories.entries()) {
+            const storyId = allocation.US[storyIndex];
+            const acceptanceCriteria = aiStory.acceptanceCriteria.map((statement, index) => ({
+                id: `AC-${String(index + 1).padStart(3, '0')}`,
+                statement,
+            }));
+            const renderedTasks = [];
+            for (const aiTask of aiStory.tasks) {
+                const taskId = taskIdMap.get(aiTask.id);
+                if (!taskId)
+                    throw invalidDecomposition(`No global ID was allocated for ${aiTask.id}.`);
+                const input = specTaskInput(aiTask, storyId, taskIdMap, acceptanceCriteria);
+                const rendered = await renderSpecTaskContent(config, spec.id, taskId, input);
+                const filename = `${taskId}-${rendered.slug}.md`;
+                validateRenderedPlanningArtifact(rendered.content, {
+                    id: taskId,
+                    specId: spec.id,
+                    storyId,
+                });
+                validatePlanningProtocolFrontmatter(protocolValidator, 'task', rendered.content, taskId, '1.7.0');
+                renderedTasks.push({
+                    id: taskId,
+                    filename,
+                    agent: input.agent,
+                    title: aiTask.title,
+                    content: rendered.content,
+                    acceptanceRefs: input.acceptanceRefs ?? [],
+                });
+            }
+            const mappedAcceptance = new Set(renderedTasks.flatMap((task) => task.acceptanceRefs));
+            const uncovered = acceptanceCriteria.filter(({ id }) => !mappedAcceptance.has(id));
+            if (uncovered.length > 0) {
+                throw invalidDecomposition(`${storyId} has acceptance criteria without task verification: ${uncovered.map(({ id }) => id).join(', ')}.`);
+            }
+            const renderedStory = await renderSpecStoryContent(config, spec.id, storyId, aiStory.title, {
+                roleAction: aiStory.roleAction,
+                benefit: aiStory.benefit,
+                scope: aiStory.scope,
+                acceptanceCriteria,
+                tasks: renderedTasks.map(({ id, filename, agent, title }) => ({
+                    id,
+                    filename,
+                    agent,
+                    title,
+                })),
+            });
+            validateRenderedPlanningArtifact(renderedStory.content, { id: storyId, specId: spec.id });
+            validatePlanningProtocolFrontmatter(protocolValidator, 'story', renderedStory.content, storyId, '1.7.0');
+            await writeFile(path.join(stagedStoriesDir, `${storyId}-${renderedStory.slug}.md`), renderedStory.content);
+            for (const task of renderedTasks) {
+                await writeFile(path.join(stagedTasksDir, task.filename), task.content);
+                tasksCreated++;
+            }
+        }
+        const stagedSpecFile = path.join(stagedSpecDir, path.basename(spec.specFile));
+        const stagedSpecContent = updateSpecFrontmatter(await readFile(stagedSpecFile), {
+            status: 'decomposed',
+            updated: new Date().toISOString().split('T')[0],
+        });
+        const parsedSpec = parseMarkdown(stagedSpecContent);
+        if (parsedSpec.data.id !== spec.id || parsedSpec.data.status !== 'decomposed') {
+            throw invalidDecomposition('rendered spec status update did not preserve its identity.');
+        }
+        validatePlanningProtocolFrontmatter(protocolValidator, 'spec', stagedSpecContent, spec.id, parsedSpec.data.schemaVersion === '1.7.0' ? '1.7.0' : '1.0.0');
+        await atomicWriteFile(stagedSpecFile, stagedSpecContent);
+        await fsPromises.rename(spec.specDir, backupSpecDir);
+        try {
+            await fsPromises.rename(stagedSpecDir, spec.specDir);
+        }
+        catch (publishError) {
+            try {
+                await fsPromises.rename(backupSpecDir, spec.specDir);
+            }
+            catch (rollbackError) {
+                throw new AggregateError([publishError, rollbackError], `Could not publish the staged decomposition or restore ${spec.id}. The original plan remains at ${backupSpecDir}.`);
+            }
+            throw publishError;
+        }
+        try {
+            await fsPromises.rm(backupSpecDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            logger.debug(`Could not remove completed decomposition backup ${backupSpecDir}`, error);
+        }
+        return { storiesCreated: decomposition.stories.length, tasksCreated };
+    }
+    catch (error) {
+        await removeDecompositionTransient(stagedSpecDir);
+        throw error;
+    }
+}
+function invalidDecomposition(message) {
+    return Object.assign(new Error(`Invalid spec decomposition: ${message}`), {
+        code: 'E_SPEC_DECOMPOSITION_INVALID',
+    });
+}
+/**
+ * Enforce the deterministic parts of the planning contract before any story or
+ * task is written. Semantic dependency need is established by the prompt; this
+ * boundary verifies that the declared graph is addressable and executable.
+ */
+function validateDecompositionContract(stories, hasDesign) {
+    const flattened = [];
+    for (const [storyIndex, story] of stories.entries()) {
+        const location = `story ${storyIndex + 1} (${story.title})`;
+        if (hasDesign) {
+            if (story.tasks.length !== 2) {
+                throw invalidDecomposition(`${location} must contain exactly two tasks because design context exists: UI then Tech.`);
+            }
+            const [uiTask, techTask] = story.tasks;
+            if (uiTask.type !== 'UI' || uiTask.agent !== 'frontend-agent') {
+                throw invalidDecomposition(`${location} task 1 must use type UI with frontend-agent when design context exists.`);
+            }
+            if (techTask.type !== 'Tech' || techTask.agent !== 'backend-agent') {
+                throw invalidDecomposition(`${location} task 2 must use type Tech with backend-agent.`);
+            }
+        }
+        else {
+            if (story.tasks.length !== 1) {
+                throw invalidDecomposition(`${location} must contain exactly one Tech task because no design context exists.`);
+            }
+            const [techTask] = story.tasks;
+            if (techTask.type !== 'Tech' || techTask.agent !== 'backend-agent') {
+                throw invalidDecomposition(`${location} must use type Tech with backend-agent when no design context exists.`);
+            }
+        }
+        flattened.push(...story.tasks);
+    }
+    const taskIds = new Set();
+    for (const [index, task] of flattened.entries()) {
+        const expectedId = `T-${String(index + 1).padStart(3, '0')}`;
+        if (task.id !== expectedId) {
+            throw invalidDecomposition(`task ${index + 1} must be ${expectedId} in flattened output order; received ${task.id}.`);
+        }
+        taskIds.add(task.id);
+    }
+    for (const task of flattened) {
+        for (const dependencyId of task.dependsOn) {
+            if (!taskIds.has(dependencyId)) {
+                throw invalidDecomposition(`${task.id} depends on unknown task ${dependencyId}; dependencies must reference this decomposition.`);
+            }
+            if (dependencyId === task.id) {
+                throw invalidDecomposition(`${task.id} cannot depend on itself.`);
+            }
+        }
+    }
+    const dependencies = new Map(flattened.map((task) => [task.id, task.dependsOn]));
+    const state = new Map();
+    const visit = (taskId, path) => {
+        const currentState = state.get(taskId);
+        if (currentState === 'visited')
+            return;
+        if (currentState === 'visiting') {
+            throw invalidDecomposition(`dependency cycle detected: ${[...path, taskId].join(' -> ')}.`);
+        }
+        state.set(taskId, 'visiting');
+        for (const dependencyId of dependencies.get(taskId) ?? []) {
+            visit(dependencyId, [...path, taskId]);
+        }
+        state.set(taskId, 'visited');
+    };
+    for (const task of flattened)
+        visit(task.id, []);
+}
 /**
  * Decompose a SPEC into User Stories + Tasks via AI.
  *
  * High-level flow:
  *   1. Read the spec; refuse if stories/ or tasks/ already populated
- *      (unless `opts.force === true`)
- *   2. Read `input/tech/stack.md` (best-effort; passed as a hint to the AI)
- *   3. Build codebase context via planr's existing scanner (skipped if
- *      `opts.noCodeContext === true`)
- *   4. Build prompt + call AI provider via `generateStreamingJSON`
- *   5. Validate the response with `aiSpecDecomposeResponseSchema`
- *   6. Write each US via `createSpecStory` and each Task via `createSpecTask`
- *   7. Update SPEC frontmatter status: pending|shaping → decomposing → decomposed
+ *      (unless replacement was requested)
+ *   2. Accept the semantic decomposition authored by the active host agent.
+ *   3. Validate and render a complete staged spec directory.
+ *   4. Replace the prior spec directory only after the staged plan is valid.
  */
 export async function decomposeSpec(projectDir, config, specId, opts = {}) {
     const spec = await readSpec(projectDir, config, specId);
@@ -429,90 +877,44 @@ export async function decomposeSpec(projectDir, config, specId, opts = {}) {
     // ── Guard: refuse to overwrite existing decomposition ─────────────────
     const existingStories = await listSpecStories(spec.specDir);
     const existingTasks = await listSpecTasks(spec.specDir);
-    if ((existingStories.length > 0 || existingTasks.length > 0) && !opts.force) {
+    const replaceExisting = opts.replaceExisting === true || opts.force === true;
+    if ((existingStories.length > 0 || existingTasks.length > 0) && !replaceExisting) {
         throw new Error(`Spec ${specId} already has ${existingStories.length} stor${existingStories.length === 1 ? 'y' : 'ies'} and ${existingTasks.length} task${existingTasks.length === 1 ? '' : 's'}. ` +
-            `Pass --force to overwrite, or \`planr spec destroy ${specId}\` to start fresh.`);
-    }
-    // If forcing, wipe existing US + Task files BEFORE the AI call so a failed
-    // decomposition doesn't leave a half-overwritten tree.
-    if (opts.force && (existingStories.length > 0 || existingTasks.length > 0)) {
-        const fs = await import('node:fs/promises');
-        for (const s of existingStories)
-            await fs.rm(s.filePath, { force: true });
-        for (const t of existingTasks)
-            await fs.rm(t.filePath, { force: true });
-    }
-    // ── Determine PNG presence (drives 1-vs-2 tasks per US per rules.md R2) ─
-    const uiFilesData = spec.data.ui_files;
-    const hasPNGs = Array.isArray(uiFilesData) && uiFilesData.length > 0;
-    // ── Read stack.md (best-effort) ───────────────────────────────────────
-    let stackInfo;
-    try {
-        const stackPath = path.join(projectDir, 'input/tech/stack.md');
-        if (await fileExists(stackPath)) {
-            stackInfo = await readFile(stackPath);
-        }
+            `Pass --replace-existing to regenerate them atomically.`);
     }
-    catch {
-        // best-effort
+    if (!opts.decomposition) {
+        const error = new Error('Semantic decomposition belongs to the active host agent; provide a host-authored decomposition to the deterministic publisher.');
+        error.code = 'E_HOST_AGENT_REQUIRED';
+        throw error;
     }
-    // ── Build codebase context (lazy import keeps startup fast) ───────────
-    let codebaseContext;
-    if (!opts.noCodeContext) {
-        try {
-            const { buildCodebaseContext, extractKeywords, formatCodebaseContext } = await import('../ai/codebase/index.js');
-            const keywordSource = `${typeof spec.data.title === 'string' ? spec.data.title : ''}\n${spec.content}`;
-            const keywords = extractKeywords(keywordSource);
-            const ctx = await buildCodebaseContext(projectDir, keywords);
-            codebaseContext = formatCodebaseContext(ctx);
-            const stackHint = ctx.techStack
-                ? ` — ${ctx.techStack.language}${ctx.techStack.framework ? ` + ${ctx.techStack.framework}` : ''}`
-                : '';
-            logger.dim(`  Scanned codebase${stackHint}`);
-        }
-        catch (err) {
-            logger.debug('Codebase scanning failed during spec decompose', err);
-        }
-    }
-    // ── Update status to "decomposing" so observers see in-progress state ─
-    await updateSpecFields(projectDir, config, specId, { status: 'decomposing' });
-    // ── Call AI (lazy imports — keep heavy deps off startup path) ─────────
-    const { buildSpecDecomposePrompt } = await import('../ai/prompts/prompt-builder.js');
-    const { aiSpecDecomposeResponseSchema } = await import('../ai/schemas/ai-response-schemas.js');
-    const { generateStreamingJSON, getAIProvider } = await import('./ai-service.js');
-    const { TOKEN_BUDGETS } = await import('../ai/types.js');
-    const provider = await getAIProvider(config);
-    const messages = buildSpecDecomposePrompt(spec.content, hasPNGs, stackInfo, codebaseContext, opts.maxStories);
-    const { result } = await generateStreamingJSON(provider, messages, aiSpecDecomposeResponseSchema, { maxTokens: TOKEN_BUDGETS.taskFeature });
-    // ── Persist stories + tasks ────────────────────────────────────────────
-    let storiesCreated = 0;
-    let tasksCreated = 0;
-    for (const aiStory of result.stories) {
-        const created = await createSpecStory(projectDir, config, specId, aiStory.title, {
-            roleAction: aiStory.roleAction,
-            benefit: aiStory.benefit,
-            scope: aiStory.scope,
-            acceptanceCriteria: aiStory.acceptanceCriteria,
-        });
-        storiesCreated++;
-        for (const aiTask of aiStory.tasks) {
-            await createSpecTask(projectDir, config, specId, {
-                storyId: created.id,
-                title: aiTask.title,
-                type: aiTask.type,
-                agent: aiTask.agent,
-                filesCreate: aiTask.filesCreate,
-                filesModify: aiTask.filesModify,
-                filesPreserve: aiTask.filesPreserve,
-                objective: aiTask.objective,
-                technicalSpec: aiTask.technicalSpec,
-                testRequirements: aiTask.testRequirements,
-            });
-            tasksCreated++;
-        }
+    // Resolve design context for deterministic one-vs-two task validation.
+    const design = await resolveDesignContext(projectDir, spec);
+    const result = opts.decomposition;
+    validateDecompositionContract(result.stories, design.hasDesign);
+    const flatTasks = result.stories.flatMap((story) => story.tasks);
+    const counts = { US: result.stories.length, T: flatTasks.length };
+    const allocation = opts.preview
+        ? await previewPlanningIds(projectDir, config, counts)
+        : await reservePlanningIds(projectDir, config, counts);
+    const firstReadyIndex = flatTasks.findIndex((task) => task.dependsOn.length === 0);
+    const selectedIndex = firstReadyIndex >= 0 ? firstReadyIndex : 0;
+    const taskSelector = allocation.T[selectedIndex];
+    const shipCommand = `$planr:ship ${taskSelector}`;
+    if (opts.preview) {
+        return {
+            storiesCreated: result.stories.length,
+            tasksCreated: flatTasks.length,
+            decompositionNotes: result.decompositionNotes,
+            preview: true,
+            storyIds: allocation.US,
+            taskIds: allocation.T,
+            taskSelector,
+            shipCommand,
+        };
     }
-    // ── Final status: decomposed ──────────────────────────────────────────
-    await updateSpecFields(projectDir, config, specId, { status: 'decomposed' });
+    // Render and validate outside the live spec directory. The final rename is
+    // the first mutation of the existing plan, and it rolls back on failure.
+    const { storiesCreated, tasksCreated } = await replaceSpecWithDecomposition(config, spec, existingStories, existingTasks, result, allocation);
     await appendOpenPlanrProvenance({
         projectDir,
         artifactId: spec.id,
@@ -527,8 +929,231 @@ export async function decomposeSpec(projectDir, config, specId, opts = {}) {
         storiesCreated,
         tasksCreated,
         decompositionNotes: result.decompositionNotes,
+        preview: false,
+        storyIds: allocation.US,
+        taskIds: allocation.T,
+        taskSelector,
+        shipCommand,
     };
 }
+// ---------------------------------------------------------------------------
+// Shape — professional specification authoring
+// ---------------------------------------------------------------------------
+export const PROFESSIONAL_SPECIFICATION_CONTRACT = 'professional-specification@1.0.0';
+export const PROFESSIONAL_SPECIFICATION_KIND = 'professional-specification';
+export const PROFESSIONAL_SPECIFICATION_SCHEMA_VERSION = '1.0.0';
+export const PROFESSIONAL_SPECIFICATION_PROTOCOL_VERSION = '1.1.0';
+export const PROFESSIONAL_SPECIFICATION_MAX_INPUT_BYTES = 128 * 1024;
+export const PROFESSIONAL_SPEC_SPECIALISTS = Object.freeze([
+    'security',
+    'performance',
+    'migration',
+    'api-contract',
+    'data-integrity',
+]);
+export class ProfessionalSpecValidationError extends Error {
+    code = 'E_PROFESSIONAL_SPEC_INVALID';
+    missing;
+    constructor(problem, missing = []) {
+        super(problem);
+        this.name = this.code;
+        this.missing = [...missing];
+    }
+    toJSON() {
+        return {
+            ok: false,
+            code: this.code,
+            problem: this.message,
+            recovery: 'Provide one closed professional-specification@1.0.0 JSON object with every required field.',
+            ...(this.missing.length > 0 ? { missing: [...this.missing] } : {}),
+        };
+    }
+}
+const PROFESSIONAL_SPEC_TOP_LEVEL_KEYS = Object.freeze([
+    'kind',
+    'schemaVersion',
+    'protocolVersion',
+    'context',
+    'audience',
+    'outcome',
+    'functionalRequirements',
+    'constraints',
+    'evidenceExpectations',
+    'failureModes',
+    'rollback',
+    'scope',
+    'acceptanceCriteria',
+    'declaredSpecialists',
+    'businessRules',
+    'decompositionNotes',
+]);
+const REQUIRED_PROFESSIONAL_SPEC_FIELDS = Object.freeze([
+    'kind',
+    'schemaVersion',
+    'protocolVersion',
+    'context',
+    'audience',
+    'outcome',
+    'functionalRequirements',
+    'constraints',
+    'evidenceExpectations',
+    'failureModes',
+    'rollback',
+    'scope',
+    'acceptanceCriteria',
+    'declaredSpecialists',
+]);
+function plainRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function rejectUnknownKeys(value, allowed, label) {
+    if (Object.keys(value).some((key) => !allowed.includes(key))) {
+        throw new ProfessionalSpecValidationError(`${label} contains unsupported fields.`);
+    }
+}
+function isPlaceholder(value) {
+    const normalized = value
+        .replace(/[*_`#]/gu, '')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .toLowerCase();
+    return (normalized.length === 0 ||
+        /^(?:tbd|todo|n\/?a|unknown|later|placeholder|none|\.{3}|…)[.!]?$/u.test(normalized) ||
+        /\b(?:tbd|todo|placeholder)\b/u.test(normalized) ||
+        /(?:given|when|then)\s+(?:\.{3}|…)/u.test(normalized) ||
+        /^\[(?:insert|describe|add|fill)[^\]]*\]$/u.test(normalized));
+}
+function meaningfulText(value, label, options = {}) {
+    const min = options.min ?? 8;
+    const max = options.max ?? 4_096;
+    if (typeof value !== 'string') {
+        throw new ProfessionalSpecValidationError(`${label} must be text.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length < min || normalized.length > max || isPlaceholder(normalized)) {
+        throw new ProfessionalSpecValidationError(`${label} must be explicit, decision-complete text between ${min} and ${max} characters.`);
+    }
+    return normalized;
+}
+function meaningfulList(value, label, options = {}) {
+    const min = options.min ?? 1;
+    const max = options.max ?? 32;
+    if (!Array.isArray(value) || value.length > max || (!options.allowEmpty && value.length < min)) {
+        throw new ProfessionalSpecValidationError(`${label} must contain ${options.allowEmpty ? 'zero or more' : `between ${min} and ${max}`} items.`);
+    }
+    const normalized = value.map((item) => meaningfulText(item, `${label} item`, { min: options.itemMin ?? 8, max: 2_048 }));
+    const identities = normalized.map((item) => item.toLocaleLowerCase('en-US'));
+    if (new Set(identities).size !== identities.length) {
+        throw new ProfessionalSpecValidationError(`${label} contains duplicate items.`);
+    }
+    return normalized;
+}
+/** Parse, normalize, and close one professional specification authoring request. */
+export function parseProfessionalSpecAnswers(value) {
+    let byteLength = 0;
+    try {
+        byteLength = Buffer.byteLength(JSON.stringify(value), 'utf8');
+    }
+    catch {
+        throw new ProfessionalSpecValidationError('Professional specification input must be one JSON object.');
+    }
+    if (byteLength > PROFESSIONAL_SPECIFICATION_MAX_INPUT_BYTES) {
+        throw new ProfessionalSpecValidationError('Professional specification input exceeds the 128KB limit.');
+    }
+    const input = plainRecord(value);
+    if (!input) {
+        throw new ProfessionalSpecValidationError('Professional specification input must be one JSON object.');
+    }
+    rejectUnknownKeys(input, PROFESSIONAL_SPEC_TOP_LEVEL_KEYS, 'Professional specification input');
+    const missing = REQUIRED_PROFESSIONAL_SPEC_FIELDS.filter((field) => !(field in input));
+    if (missing.length > 0) {
+        throw new ProfessionalSpecValidationError('Professional specification input is missing required fields.', [...missing]);
+    }
+    if (input.kind !== PROFESSIONAL_SPECIFICATION_KIND ||
+        input.schemaVersion !== PROFESSIONAL_SPECIFICATION_SCHEMA_VERSION ||
+        input.protocolVersion !== PROFESSIONAL_SPECIFICATION_PROTOCOL_VERSION) {
+        throw new ProfessionalSpecValidationError('Professional specification contract identity is unsupported.');
+    }
+    const audience = plainRecord(input.audience);
+    if (!audience)
+        throw new ProfessionalSpecValidationError('audience must be one object.');
+    rejectUnknownKeys(audience, ['primary', 'affected'], 'audience');
+    const audienceMissing = ['primary', 'affected'].filter((field) => !(field in audience));
+    if (audienceMissing.length > 0) {
+        throw new ProfessionalSpecValidationError('audience is missing required fields.', audienceMissing);
+    }
+    const outcome = plainRecord(input.outcome);
+    if (!outcome)
+        throw new ProfessionalSpecValidationError('outcome must be one object.');
+    rejectUnknownKeys(outcome, ['statement', 'measure', 'target', 'timeframe'], 'outcome');
+    const outcomeMissing = ['statement', 'measure', 'target', 'timeframe'].filter((field) => !(field in outcome));
+    if (outcomeMissing.length > 0) {
+        throw new ProfessionalSpecValidationError('outcome is missing required fields.', outcomeMissing);
+    }
+    const scope = plainRecord(input.scope);
+    if (!scope)
+        throw new ProfessionalSpecValidationError('scope must be one object.');
+    rejectUnknownKeys(scope, ['inScope', 'outOfScope'], 'scope');
+    const scopeMissing = ['inScope', 'outOfScope'].filter((field) => !(field in scope));
+    if (scopeMissing.length > 0) {
+        throw new ProfessionalSpecValidationError('scope is missing required fields.', scopeMissing);
+    }
+    if (!Array.isArray(input.declaredSpecialists)) {
+        throw new ProfessionalSpecValidationError('declaredSpecialists must be one array.');
+    }
+    const declaredSpecialists = input.declaredSpecialists.map((candidate) => {
+        if (typeof candidate !== 'string' ||
+            !PROFESSIONAL_SPEC_SPECIALISTS.includes(candidate)) {
+            throw new ProfessionalSpecValidationError('declaredSpecialists contains an unsupported specialist identity.');
+        }
+        return candidate;
+    });
+    if (new Set(declaredSpecialists).size !== declaredSpecialists.length) {
+        throw new ProfessionalSpecValidationError('declaredSpecialists contains duplicates.');
+    }
+    const orderedSpecialists = PROFESSIONAL_SPEC_SPECIALISTS.filter((specialist) => declaredSpecialists.includes(specialist));
+    const businessRules = input.businessRules === undefined
+        ? []
+        : meaningfulList(input.businessRules, 'businessRules', { allowEmpty: true });
+    const decompositionNotes = input.decompositionNotes === undefined
+        ? ''
+        : typeof input.decompositionNotes === 'string' && input.decompositionNotes.length <= 8_192
+            ? input.decompositionNotes.trim()
+            : (() => {
+                throw new ProfessionalSpecValidationError('decompositionNotes must be text no longer than 8192 characters.');
+            })();
+    return Object.freeze({
+        kind: PROFESSIONAL_SPECIFICATION_KIND,
+        schemaVersion: PROFESSIONAL_SPECIFICATION_SCHEMA_VERSION,
+        protocolVersion: PROFESSIONAL_SPECIFICATION_PROTOCOL_VERSION,
+        context: meaningfulText(input.context, 'context'),
+        audience: Object.freeze({
+            primary: meaningfulText(audience.primary, 'audience.primary'),
+            affected: Object.freeze(meaningfulList(audience.affected, 'audience.affected')),
+        }),
+        outcome: Object.freeze({
+            statement: meaningfulText(outcome.statement, 'outcome.statement'),
+            measure: meaningfulText(outcome.measure, 'outcome.measure'),
+            target: meaningfulText(outcome.target, 'outcome.target'),
+            timeframe: meaningfulText(outcome.timeframe, 'outcome.timeframe'),
+        }),
+        functionalRequirements: Object.freeze(meaningfulList(input.functionalRequirements, 'functionalRequirements')),
+        constraints: Object.freeze(meaningfulList(input.constraints, 'constraints')),
+        evidenceExpectations: Object.freeze(meaningfulList(input.evidenceExpectations, 'evidenceExpectations')),
+        failureModes: Object.freeze(meaningfulList(input.failureModes, 'failureModes')),
+        rollback: meaningfulText(input.rollback, 'rollback'),
+        scope: Object.freeze({
+            inScope: Object.freeze(meaningfulList(scope.inScope, 'scope.inScope')),
+            outOfScope: Object.freeze(meaningfulList(scope.outOfScope, 'scope.outOfScope')),
+        }),
+        acceptanceCriteria: Object.freeze(meaningfulList(input.acceptanceCriteria, 'acceptanceCriteria', { itemMin: 20 })),
+        declaredSpecialists: Object.freeze([...orderedSpecialists]),
+        businessRules: Object.freeze(businessRules),
+        decompositionNotes,
+    });
+}
 /**
  * Re-render the SPEC body from a structured set of answers and write it back
  * atomically. Preserves frontmatter values that the user (or `planr spec
@@ -541,6 +1166,7 @@ export async function shapeSpec(projectDir, config, specId, answers) {
     const spec = await readSpec(projectDir, config, specId);
     if (!spec)
         throw new Error(`Spec ${specId} not found.`);
+    const professional = parseProfessionalSpecAnswers(answers);
     const today = new Date().toISOString().split('T')[0];
     // Carry through every frontmatter field that was already set, so we don't
     // accidentally erase user customizations on re-shape.
@@ -561,16 +1187,24 @@ export async function shapeSpec(projectDir, config, specId, answers) {
         created: typeof data.created === 'string' ? data.created : today,
         date: today,
         uiFiles,
-        context: answers.context.trim(),
-        functionalRequirements: answers.functionalRequirements.map((s) => s.trim()).filter(Boolean),
-        businessRules: (answers.businessRules || '').trim(),
-        outOfScope: (answers.outOfScope || []).map((s) => s.trim()).filter(Boolean),
-        acceptanceCriteria: answers.acceptanceCriteria.map((s) => s.trim()).filter(Boolean),
-        decompositionNotes: (answers.decompositionNotes || '').trim(),
+        specificationContract: PROFESSIONAL_SPECIFICATION_CONTRACT,
+        context: professional.context,
+        audience: professional.audience,
+        outcome: professional.outcome,
+        functionalRequirements: professional.functionalRequirements,
+        constraints: professional.constraints,
+        evidenceExpectations: professional.evidenceExpectations,
+        failureModes: professional.failureModes,
+        rollback: professional.rollback,
+        scope: professional.scope,
+        acceptanceCriteria: professional.acceptanceCriteria,
+        declaredSpecialists: professional.declaredSpecialists,
+        businessRules: professional.businessRules,
+        decompositionNotes: professional.decompositionNotes,
         projectName: config.projectName,
     }, config.templateOverrides);
     await atomicWriteFile(spec.specFile, content);
-    logger.debug(`Shaped spec ${spec.id} (status: shaping)`);
+    logger.debug(`Shaped professional spec ${spec.id} (status: shaped)`);
     return { specFile: spec.specFile };
 }
 /**
@@ -586,19 +1220,43 @@ export async function destroySpec(projectDir, config, specId) {
     await fs.rm(resolved.dir, { recursive: true, force: true });
     logger.debug(`Destroyed spec ${specId}: ${resolved.dir}`);
 }
+async function renderSpecStoryContent(config, specId, id, title, body) {
+    const slug = slugify(title);
+    if (!slug)
+        throw invalidDecomposition(`story ${id} title must produce a non-empty slug.`);
+    const today = new Date().toISOString().split('T')[0];
+    const acceptanceCriteria = (body.acceptanceCriteria ?? []).map((criterion, index) => typeof criterion === 'string'
+        ? { id: `AC-${String(index + 1).padStart(3, '0')}`, statement: criterion }
+        : criterion);
+    const content = await renderTemplate('spec/story.md.hbs', {
+        id,
+        slug,
+        title,
+        specId,
+        schemaVersion: '1.7.0',
+        status: 'pending',
+        date: today,
+        roleAction: body.roleAction,
+        benefit: body.benefit,
+        scope: body.scope || '',
+        acceptanceCriteria,
+        tasks: body.tasks || [],
+        projectName: config.projectName,
+    }, config.templateOverrides);
+    return { slug, content };
+}
 /**
- * List US-NNN files inside a spec's stories/ subdirectory.
- * Returns IDs scoped to this spec — two specs can each have US-001.
+ * List project-global US-NNN files inside a spec's stories/ subdirectory.
  */
 export async function listSpecStories(specDir) {
     const storiesDir = getSpecStoriesDir(specDir);
     const exists = await fileExists(storiesDir);
     if (!exists)
         return [];
-    const files = await listFiles(storiesDir, /^US-\d{3}-.+\.md$/);
+    const files = await listFiles(storiesDir, /^US-\d{3,}-.+\.md$/);
     const out = [];
     for (const filename of files.sort()) {
-        const m = filename.match(/^(US-\d{3})-(.+)\.md$/);
+        const m = filename.match(/^(US-\d{3,})-(.+)\.md$/);
         if (!m)
             continue;
         const [, id, slug] = m;
@@ -626,26 +1284,10 @@ export async function createSpecStory(projectDir, config, specId, title, body) {
         throw new Error(`Spec ${specId} not found.`);
     const storiesDir = getSpecStoriesDir(resolved.dir);
     await ensureDir(storiesDir);
-    const slug = slugify(title);
-    const prefix = config.idPrefix.story || 'US';
-    const id = await getNextId(storiesDir, prefix);
+    const id = (await reservePlanningIds(projectDir, config, { US: 1 })).US[0];
+    const { slug, content } = await renderSpecStoryContent(config, specId, id, title, body);
     const filename = `${id}-${slug}.md`;
     const filePath = path.join(storiesDir, filename);
-    const today = new Date().toISOString().split('T')[0];
-    const content = await renderTemplate('spec/story.md.hbs', {
-        id,
-        slug,
-        title,
-        specId,
-        schemaVersion: '1.0.0',
-        status: 'pending',
-        date: today,
-        roleAction: body.roleAction,
-        benefit: body.benefit,
-        scope: body.scope || '',
-        acceptanceCriteria: body.acceptanceCriteria || [],
-        projectName: config.projectName,
-    }, config.templateOverrides);
     await writeFile(filePath, content);
     return { id, slug, filePath };
 }
@@ -657,10 +1299,10 @@ export async function listSpecTasks(specDir) {
     const exists = await fileExists(tasksDir);
     if (!exists)
         return [];
-    const files = await listFiles(tasksDir, /^T-\d{3}-.+\.md$/);
+    const files = await listFiles(tasksDir, /^T-\d{3,}-.+\.md$/);
     const out = [];
     for (const filename of files.sort()) {
-        const m = filename.match(/^(T-\d{3})-(.+)\.md$/);
+        const m = filename.match(/^(T-\d{3,})-(.+)\.md$/);
         if (!m)
             continue;
         const [, id, slug] = m;
@@ -700,39 +1342,65 @@ export async function listSpecTasks(specDir) {
     }
     return out;
 }
-/** Create a new T-NNN task file under the spec's tasks/ directory. */
-export async function createSpecTask(projectDir, config, specId, input) {
-    const resolved = await resolveSpecDir(projectDir, config, specId);
-    if (!resolved)
-        throw new Error(`Spec ${specId} not found.`);
-    const tasksDir = getSpecTasksDir(resolved.dir);
-    await ensureDir(tasksDir);
+async function renderSpecTaskContent(config, specId, id, input) {
     const slug = slugify(input.title);
-    // Task ID prefix: 'T' (single letter) by convention in spec mode
-    // (vs agile mode's 'TASK'). Matches planr-pipeline schema.
-    const id = await getNextId(tasksDir, 'T');
-    const filename = `${id}-${slug}.md`;
-    const filePath = path.join(tasksDir, filename);
+    if (!slug)
+        throw invalidDecomposition(`task ${id} title must produce a non-empty slug.`);
     const today = new Date().toISOString().split('T')[0];
+    const rationale = input.rationale?.trim() ||
+        `${input.title} is required for ${input.storyId}; the listed files define the expected ${input.type === 'UI' ? 'user-interface' : 'technical'} change surface.`;
+    const rationaleSentences = rationale.split(/(?<=[.!?])\s+/u).filter(Boolean);
+    if (rationaleSentences.length > 3) {
+        throw new Error('Task rationale must contain 1-3 sentences.');
+    }
+    const dependsOn = input.dependsOn ?? [];
+    if (dependsOn.some((dependencyId) => !/^T-\d{3,}$/u.test(dependencyId)) ||
+        new Set(dependsOn).size !== dependsOn.length) {
+        throw new Error('Task dependencies must be unique project-global T-NNN IDs.');
+    }
+    if (dependsOn.includes(id)) {
+        throw new Error(`Task ${id} cannot depend on itself.`);
+    }
     const content = await renderTemplate('spec/task.md.hbs', {
         id,
         slug,
         title: input.title,
         storyId: input.storyId,
         specId,
-        schemaVersion: '1.0.0',
+        schemaVersion: '1.7.0',
         type: input.type,
         agent: input.agent,
         status: 'pending',
         date: today,
+        rationale,
+        dependsOn,
         filesCreate: input.filesCreate || [],
         filesModify: input.filesModify || [],
         filesPreserve: input.filesPreserve || [],
         objective: input.objective || '',
         technicalSpec: input.technicalSpec || '',
         testRequirements: input.testRequirements || '',
+        reviewRisks: input.reviewRisks || [],
+        browserSurfaces: input.browserSurfaces || [],
+        acceptanceRefs: input.acceptanceRefs || [],
+        acceptanceCriteria: input.acceptanceCriteria || [],
         projectName: config.projectName,
     }, config.templateOverrides);
+    return { slug, content };
+}
+/** Create a new T-NNN task file under the spec's tasks/ directory. */
+export async function createSpecTask(projectDir, config, specId, input) {
+    const resolved = await resolveSpecDir(projectDir, config, specId);
+    if (!resolved)
+        throw new Error(`Spec ${specId} not found.`);
+    const tasksDir = getSpecTasksDir(resolved.dir);
+    await ensureDir(tasksDir);
+    // Task ID prefix: 'T' (single letter) by convention in spec mode
+    // (vs agile mode's 'TASK'). Matches planr-pipeline schema.
+    const id = (await reservePlanningIds(projectDir, config, { T: 1 })).T[0];
+    const { slug, content } = await renderSpecTaskContent(config, specId, id, input);
+    const filename = `${id}-${slug}.md`;
+    const filePath = path.join(tasksDir, filename);
     await writeFile(filePath, content);
     return { id, slug, filePath };
 }
@@ -781,8 +1449,99 @@ export async function getSpecStatus(projectDir, config) {
     const totalTasks = specs.reduce((acc, s) => acc + s.taskCount, 0);
     return { specCount: specs.length, specs, totalStories, totalTasks };
 }
+const PROFESSIONAL_SPEC_REQUIRED_SECTIONS = Object.freeze([
+    'Context & Goal',
+    'Audience',
+    'Outcome & Measurement',
+    'Functional Requirements',
+    'Constraints',
+    'Evidence Expectations',
+    'Failure Modes',
+    'Rollback',
+    'Scope Boundaries',
+    'Acceptance Criteria',
+    'Declared Risk Specialists',
+]);
+function markdownSection(content, heading, level = 2) {
+    const lines = content.split(/\r?\n/u);
+    const prefix = '#'.repeat(level);
+    const start = lines.findIndex((line) => line.trim() === `${prefix} ${heading}`);
+    if (start === -1)
+        return null;
+    const next = lines.findIndex((line, index) => index > start && new RegExp(`^#{1,${level}}\\s`, 'u').test(line));
+    return lines
+        .slice(start + 1, next === -1 ? undefined : next)
+        .join('\n')
+        .trim();
+}
+function sectionHasExplicitText(section) {
+    return section
+        .split(/\r?\n/u)
+        .map((line) => line
+        .replace(/^[-*+]\s+/u, '')
+        .replace(/^\[[ xX]\]\s*/u, '')
+        .replace(/^\*\*[^*]+:\*\*\s*/u, '')
+        .trim())
+        .some((line) => line.length >= 8 && !isPlaceholder(line));
+}
+/** Validate only documents that explicitly claim the professional marker. */
+export function validateProfessionalSpecDocument(content) {
+    const issues = [];
+    const sections = new Map();
+    for (const heading of PROFESSIONAL_SPEC_REQUIRED_SECTIONS) {
+        const section = markdownSection(content, heading);
+        if (section === null) {
+            issues.push(`Professional specification is missing the "${heading}" section.`);
+            continue;
+        }
+        sections.set(heading, section);
+        if (!sectionHasExplicitText(section)) {
+            issues.push(`Professional specification section "${heading}" is not decision complete.`);
+        }
+    }
+    const audience = sections.get('Audience');
+    if (audience) {
+        if (!/^\*\*Primary:\*\*\s+\S.+$/mu.test(audience)) {
+            issues.push('Professional specification Audience must name one primary audience.');
+        }
+        const affected = /^\*\*Affected:\*\*\s*$([\s\S]*)$/mu.exec(audience)?.[1]?.trim();
+        if (!affected || !sectionHasExplicitText(affected)) {
+            issues.push('Professional specification Audience must list affected audiences.');
+        }
+    }
+    const outcome = sections.get('Outcome & Measurement');
+    if (outcome) {
+        for (const label of ['Statement', 'Measure', 'Target', 'Timeframe']) {
+            const escaped = label.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+            if (!new RegExp(`^\\*\\*${escaped}:\\*\\*\\s+\\S.{7,}$`, 'mu').test(outcome)) {
+                issues.push(`Professional specification Outcome must include an explicit ${label}.`);
+            }
+        }
+    }
+    const scope = sections.get('Scope Boundaries');
+    if (scope) {
+        for (const label of ['In Scope', 'Out of Scope']) {
+            const boundary = markdownSection(`## Scope Boundaries\n${scope}`, label, 3);
+            if (boundary === null || !sectionHasExplicitText(boundary)) {
+                issues.push(`Professional specification Scope Boundaries must include ${label}.`);
+            }
+        }
+    }
+    const acceptance = sections.get('Acceptance Criteria');
+    if (acceptance) {
+        const criteria = acceptance
+            .split(/\r?\n/u)
+            .map((line) => /^- \[[ xX]\]\s+(.+)$/u.exec(line.trim())?.[1]?.trim())
+            .filter((line) => Boolean(line));
+        if (criteria.length === 0 ||
+            criteria.some((criterion) => criterion.length < 20 || isPlaceholder(criterion))) {
+            issues.push('Professional specification Acceptance Criteria must contain decision-complete checklist items.');
+        }
+    }
+    return issues;
+}
 /**
- * Validate that a spec is ready to hand off to planr-pipeline.
+ * Validate that a spec is ready for host-native implementation.
  * Returns the list of issues, or empty array if ready.
  */
 export async function validateSpecForPromotion(projectDir, config, specId) {
@@ -793,11 +1552,11 @@ export async function validateSpecForPromotion(projectDir, config, specId) {
     }
     const stories = await listSpecStories(spec.specDir);
     if (stories.length === 0) {
-        issues.push(`No User Stories found. Run \`planr spec decompose ${specId}\` first.`);
+        issues.push(`No User Stories found. Invoke planr-plan for ${specId} first.`);
     }
     const tasks = await listSpecTasks(spec.specDir);
     if (tasks.length === 0) {
-        issues.push(`No Tasks found. Run \`planr spec decompose ${specId}\` first.`);
+        issues.push(`No Tasks found. Invoke planr-plan for ${specId} first.`);
     }
     // Each story should have at least 1 task
     const storyIds = new Set(stories.map((s) => s.id));
@@ -811,6 +1570,14 @@ export async function validateSpecForPromotion(projectDir, config, specId) {
     if (spec.content.trim().length < 100) {
         issues.push(`Spec body is very short (< 100 chars). Run \`planr spec shape ${specId}\` to flesh it out.`);
     }
+    const specificationContract = spec.data.specificationContract;
+    if (specificationContract !== undefined &&
+        specificationContract !== PROFESSIONAL_SPECIFICATION_CONTRACT) {
+        issues.push('Spec declares an unsupported professional specification contract.');
+    }
+    else if (specificationContract === PROFESSIONAL_SPECIFICATION_CONTRACT) {
+        issues.push(...validateProfessionalSpecDocument(spec.content));
+    }
     return { ready: issues.length === 0, issues };
 }
 //# sourceMappingURL=spec-service.js.map