@deksden-com/dd-flow-cli 0.7.0 → 0.8.0

package/dist/services/vnext-protocolize.js

@@ -0,0 +1,542 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { projectFeatureWorktreePath, resolveProjectRoot } from "../storage/paths.js";
+import { previewNextEntityId } from "./ids.js";
+import { registerProtocol } from "./protocols.js";
+import { requireProjectByRoot } from "./projects.js";
+import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRunStage, gitFacts, rebindFlowRunWorkspace } from "./runs.js";
+import { validateSchema } from "./schema-validation.js";
+import { assertStageStartHookEvent, hookSessionIdentity } from "./hooks.js";
+import { bindStageCoordinatorWork, refreshRunWorkProjection } from "./work-registry.js";
+import { runTargetedMemoryBankLint } from "./stage-lifecycle.js";
+import { bootstrapManagedWorktree, createManagedWorktree, recordManagedWorktree } from "./worktrees.js";
+import { loadVnextWorkspacePolicy, requireVnextWorkspaceRoute, vnextRunBranch } from "./vnext-workspace-policy.js";
+import { readVnextSpecifyResult } from "./vnext-specify.js";
+import { flowCommand, stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.js";
+import { writeStageReport } from "./stage-report-renderer.js";
+import { applyExternalStageContext } from "./stage-context.js";
+const stage = "protocolize";
+function stageSessionMode(context, run) {
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [run.project_id, run.id]);
+    const value = row ? JSON.parse(row.index_json) : null;
+    const mode = value?.execution_profile?.settings?.stage_session_mode;
+    if (mode !== "same_session" && mode !== "new_session")
+        throw new AppError("execution_profile_invalid", "RUN is missing its frozen stage session mode", 1, { run_id: run.id });
+    return mode;
+}
+export function isVnextProtocolizeRun(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    return Boolean(context.db.get("SELECT id FROM runs WHERE project_id = ? AND id = ? AND flow_kind = 'vnext_protocolize'", [project.id, input.runId]));
+}
+export function prepareVnextProtocolize(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, projectRoot, input.runId);
+    const work = requireWork(context, input.workId);
+    if (work.project_id !== project.id || work.run_id !== run.id)
+        throw new AppError("project_mismatch", "Work does not belong to the requested RUN", 1);
+    const runHome = requireRunHome(run);
+    const stageRoot = path.join(runHome, "02-protocolize");
+    const specifyPath = path.join(runHome, "01-specify", "specify.json");
+    const specifyMarkdownPath = path.join(runHome, "01-specify", "specify.md");
+    const obligations = acceptedSpecifyObligations(context, projectRoot, run.id, specifyPath);
+    fs.mkdirSync(stageRoot, { recursive: true });
+    const resultPath = path.join(stageRoot, "protocolize-result.json");
+    const promptPath = path.join(stageRoot, "prompt.md");
+    const policy = provisionWorkspaceForProtocolize(context, projectRoot, project.id, run, stageRoot);
+    const routedRun = requireRun(context, projectRoot, run.id);
+    writeJson(path.join(stageRoot, "work-context.json"), { schema_id: "dd-flow/vnext-protocolize-context@2", system: { run_id: run.id, work_id: work.work_id, stage, handoff: input.handoff }, input: { accepted_specify_json: specifyPath, accepted_specify_markdown: specifyMarkdownPath }, catalog: catalog(projectRoot), workspace: { project_root: projectRoot, workspace_root: routedRun.workspace_root, stage_root: stageRoot, git_policy: policy } });
+    if (!fs.existsSync(resultPath))
+        writeJson(resultPath, resultTemplate(obligations));
+    const templatePath = path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "protocolize.md");
+    if (!fs.existsSync(templatePath))
+        throw new AppError("not_found", "vNext PROTOCOLIZE prompt template is missing", 1, { path: templatePath });
+    const pauseCommand = stagePauseCommand(context, { runId: run.id, stage, workId: work.work_id, projectRoot });
+    const prompt = renderPrompt({ projectRoot, runId: run.id, workId: work.work_id, specifyPath, obligations, resultPath, handoff: input.handoff, catalog: catalog(projectRoot), policy, template: fs.readFileSync(templatePath, "utf8"), pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand), flow: flowCommand(context) });
+    fs.writeFileSync(promptPath, prompt);
+    // Preparation is deliberately non-productive: the standalone stage-start
+    // command atomically installs external context, binds the worker and opens
+    // the lifecycle Stage.  Do not make this prompt an implicit running stage.
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_prepared", work_id: work.work_id, stage, handoff_mode: input.handoff.stage_handoff.effective });
+    const directive = input.handoff.stage_handoff.effective === "same_session" ? { kind: "continue_current_session", stage, prompt_path: promptPath, worker_prompt_markdown: prompt } : { kind: "await_new_session", stage, work_id: work.work_id, prompt_path: promptPath, resume_command: `${flowCommand(context)} stage start ${run.id} --stage protocolize --project-root ${JSON.stringify(projectRoot)} --json` };
+    return { directive, prompt_path: promptPath };
+}
+export function startVnextProtocolize(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, projectRoot, input.runId);
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    const work = context.db.get("SELECT * FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NULL ORDER BY created_at LIMIT 1", [project.id, run.id]);
+    if (!work || work.status !== "running")
+        throw new AppError("invalid_work_state", "PROTOCOLIZE is not ready for an Agent WorkSession", 1, { run_id: run.id });
+    const protocolizeRoot = path.join(requireRunHome(run), "02-protocolize");
+    const contextPath = path.join(protocolizeRoot, "work-context.json");
+    if (!fs.existsSync(contextPath)) {
+        const handoff = specifyHandoff(path.join(requireRunHome(run), "01-specify", "work-context.json"), work.work_id);
+        prepareVnextProtocolize(context, { projectRoot, runId: run.id, workId: work.work_id, handoff });
+    }
+    const handoff = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+    const frozenContext = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+    const previous = context.db.get("SELECT ws.session_id, s.stop_reason FROM work_sessions ws LEFT JOIN sessions s ON s.project_id = ? AND s.session_id = ws.session_id WHERE ws.work_id = ? ORDER BY ws.created_at DESC LIMIT 1", [project.id, work.work_id]);
+    const activeWorkSession = context.db.get("SELECT * FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
+    const stageAttached = (() => {
+        const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, run.id]);
+        try {
+            const index = JSON.parse(row?.index_json ?? "{}");
+            return index.stage_runs?.some((item) => item.stage === stage) ?? false;
+        }
+        catch {
+            return false;
+        }
+    })();
+    const mode = handoff.system?.handoff?.stage_handoff.effective;
+    const promptPath = path.join(protocolizeRoot, "prompt.md");
+    const externalContext = applyExternalStageContext({ stageRoot: protocolizeRoot, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    const sessionId = hookSessionIdentity(context, project.id, input.hookEventId).sessionId;
+    // A stage-entry eval snapshot deliberately stops the canonical binding. Its
+    // Subject starts from a fork of the captured starter Session, so the stale
+    // canonical ID must not be treated as the live same-session owner.
+    const restoredStarter = previous?.stop_reason === "snapshot_restored";
+    if (mode === "same_session" && previous?.session_id && previous.session_id !== sessionId && !restoredStarter)
+        throw new AppError("handoff_session_mismatch", "Project policy requires PROTOCOLIZE to continue in the SPECIFY session", 1);
+    if (mode === "new_session" && previous?.session_id === sessionId)
+        throw new AppError("handoff_session_mismatch", "Project policy requires PROTOCOLIZE to start in a fresh session", 1);
+    const binding = bindStageCoordinatorWork(context, { workId: work.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(requireRunHome(run), "02-protocolize", "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    // Same-session handoff deliberately reuses the root Work/Session that
+    // SPECIFY opened. That is not evidence that PROTOCOLIZE is already attached.
+    // Attach only once; a repeated `stage start` must not archive a live attempt.
+    if (!stageAttached)
+        attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: "02-protocolize", status: "running", dataSchemaId: "dd-flow/vnext-protocolize-result@3" });
+    if (mode === "same_session" && activeWorkSession?.session_id === sessionId) {
+        return { ok: true, outcome: "work_session_required", run_id: run.id, work_id: work.work_id, id: activeWorkSession.id, prompt_path: promptPath, git_policy: frozenContext.workspace?.git_policy ?? null, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}) };
+    }
+    const workSessionId = String(binding.work_session_id);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "work_session_started", work_id: work.work_id, id: workSessionId, stage, session_id: sessionId });
+    return { ok: true, outcome: "work_session_required", run_id: run.id, work_id: work.work_id, id: workSessionId, prompt_path: promptPath, git_policy: frozenContext.workspace?.git_policy ?? null, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}) };
+}
+function specifyHandoff(file, workId) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (value.execution?.stage_handoff?.effective === "same_session" || value.execution?.stage_handoff?.effective === "new_session")
+            return value.execution;
+    }
+    catch { /* reported below */ }
+    throw new AppError("runtime_context_invalid", "SPECIFY Work is missing its immutable handoff policy", 1, { work_id: workId });
+}
+export function finishVnextProtocolize(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, projectRoot, input.runId);
+    const work = context.db.get("SELECT * FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NULL ORDER BY created_at LIMIT 1", [project.id, run.id]);
+    if (!work)
+        throw new AppError("not_found", "RUN has no PROTOCOLIZE Work", 1, { run_id: run.id });
+    const root = path.join(requireRunHome(run), "02-protocolize");
+    const resultFile = path.resolve(input.resultFile);
+    inside(root, resultFile);
+    validateSchema({ schemaName: "vnext-protocolize-result", file: resultFile, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id });
+    const result = readResult(resultFile);
+    if (result.outcome !== "protocolized")
+        throw new AppError("validation", "PROTOCOLIZE may finish only as protocolized; use stage pause for every user question", 2);
+    const acceptedObligations = acceptedSpecifyObligations(context, projectRoot, run.id, path.join(requireRunHome(run), "01-specify", "specify.json"));
+    const obligations = effectiveObligations(result, acceptedObligations);
+    validateDelivery(projectRoot, result, obligations);
+    const protocolIds = result.delivery.members.map((member) => allocateProtocolId(context, projectRoot, member.slug));
+    const psetId = result.delivery.kind === "protocol_set" ? allocatePsetId(projectRoot, result.delivery.slug) : null;
+    const resolvedPolicy = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: requireRunHome(run), workspaceRoot: run.workspace_root, stage: "protocolize" });
+    const receipt = readWorkspaceRouteReceipt(root);
+    const workspaceRoot = run.workspace_root;
+    const changedFiles = materialize(workspaceRoot, run.id, requireRunHome(run), result, obligations, protocolIds, psetId);
+    for (const protocolId of protocolIds)
+        registerProtocol(context, { handshakeId: protocolId, projectRoot, workspacePath: workspaceRoot });
+    if (receipt.created && receipt.bootstrap) {
+        for (const protocolId of protocolIds)
+            recordManagedWorktree(context, { protocolId, projectRoot, branch: requiredPolicyValue(resolvedPolicy.feature_branch, "feature branch"), base: requiredPolicyValue(resolvedPolicy.base_ref, "base ref"), created: receipt.created, bootstrap: receipt.bootstrap });
+    }
+    const now = context.now();
+    const workSession = completeWorkSession(context, work.work_id, resultFile, now);
+    const routedRun = requireRun(context, projectRoot, run.id);
+    const report = stageReport(context, routedRun, resultFile, protocolIds, changedFiles, workSession?.session_id ?? null, now, resolvedPolicy);
+    const reportJson = path.join(root, "stage-report.json");
+    const reportMarkdown = path.join(root, "stage-report.md");
+    const reportHtml = path.join(root, "stage-report.html");
+    writeStageReport(root, report);
+    validateSchema({ schemaName: "stage-report", file: reportJson, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id });
+    completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "protocolize-result.json", dataSchemaId: "dd-flow/vnext-protocolize-result@3", report: "stage-report.md", stageReport: "stage-report.html" });
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "protocol_documents_materialized", work_id: work.work_id, protocol_ids: protocolIds, stage });
+    advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "protocolized", nextAction: "start_plan" });
+    refreshRunWorkProjection(context, project.id, run.id);
+    const nextCommand = `${flowCommand(context)} stage start ${run.id} --stage plan --project-root ${JSON.stringify(projectRoot)} --json`;
+    return { ok: true, outcome: "protocolized", run_id: run.id, protocol_ids: protocolIds, workspace_root: workspaceRoot, git_policy: resolvedPolicy, next_action: "await_plan", next_command: nextCommand, next: { kind: "start_stage", stage: "plan", command: nextCommand, cwd: workspaceRoot, session_mode: resolvedPolicy.stage_session_mode }, artifacts: { result: resultFile, report_json: reportJson, report_markdown: reportMarkdown, report_html: reportHtml, protocols: protocolIds.map((id) => path.join(workspaceRoot, ".memory-bank", "protocol", id, "summary.md")) } };
+}
+function materialize(projectRoot, runId, runHome, result, obligations, ids, psetId) {
+    const psetPath = psetId ? path.join(projectRoot, ".memory-bank", "protocol", "_set", `${psetId}.md`) : null;
+    const created = [];
+    const changed = new Set();
+    const originals = new Map();
+    const remember = (file) => { if (!originals.has(file))
+        originals.set(file, fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null); };
+    const idsByMemberKey = new Map(result.delivery.members.map((member, index) => [member.key, ids[index]]));
+    try {
+        const featurePath = materializeFeature(projectRoot, result.feature, ids, created, remember, changed);
+        result.delivery.members.forEach((member, index) => {
+            const protocolRoot = path.join(projectRoot, ".memory-bank", "protocol", ids[index]);
+            fs.mkdirSync(protocolRoot, { recursive: false });
+            created.push(protocolRoot);
+            const rawIntakePath = result.durable_links.preserve_raw_intake && index === 0 ? copyRawIntake(runHome, protocolRoot) : null;
+            const blockedBy = member.blocked_by.map((key) => idsByMemberKey.get(key) ?? key);
+            fs.writeFileSync(path.join(protocolRoot, "summary.md"), protocolMarkdown(ids[index], member, blockedBy, runId, psetPath, featurePath, result, obligations, rawIntakePath));
+            fs.writeFileSync(path.join(protocolRoot, "index.md"), protocolIndexMarkdown(ids[index]));
+            changed.add(relativeMemory(path.join(protocolRoot, "summary.md")));
+            changed.add(relativeMemory(path.join(protocolRoot, "index.md")));
+            if (rawIntakePath)
+                changed.add(relativeMemory(rawIntakePath));
+        });
+        if (psetPath && psetId) {
+            fs.mkdirSync(path.dirname(psetPath), { recursive: true });
+            remember(psetPath);
+            fs.writeFileSync(psetPath, psetMarkdown(psetId, result, obligations, ids));
+            changed.add(relativeMemory(psetPath));
+        }
+        const protocolIndex = path.join(projectRoot, ".memory-bank", "protocol", "index.md");
+        remember(protocolIndex);
+        ids.forEach((id, index) => appendIndexEntry(protocolIndex, `.memory-bank/protocol/${id}/index.md`, `${id} — ${result.delivery.members[index].title}`));
+        changed.add(relativeMemory(protocolIndex));
+        const files = [...changed].sort();
+        const materializedFiles = files.filter((file) => {
+            const absolute = path.resolve(projectRoot, file);
+            return created.some((directory) => absolute.startsWith(`${directory}${path.sep}`)) || absolute === psetPath;
+        });
+        runTargetedMemoryBankLint(projectRoot, materializedFiles);
+        return files;
+    }
+    catch (error) {
+        for (const [file, content] of originals) {
+            if (content === null)
+                fs.rmSync(file, { force: true });
+            else
+                fs.writeFileSync(file, content);
+        }
+        for (const dir of created.reverse())
+            fs.rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+function protocolMarkdown(id, member, blockedBy, runId, psetPath, featurePath, result, obligations, rawIntakePath) {
+    const a = member.primary_acceptance;
+    const links = result.durable_links;
+    const allFeatures = unique([...(featurePath ? [relativeMemory(featurePath)] : []), ...links.related_features]);
+    const owned = result.obligation_ownership.filter((item) => item.member_keys.includes(member.key)).map((item) => obligations.find((obligation) => obligation.id === item.obligation_id));
+    const ownedRequirements = owned.filter((obligation) => obligation.kind === "requirement");
+    const ownedAcceptance = owned.filter((obligation) => obligation.kind === "acceptance");
+    return ["---", `file: '.memory-bank/protocol/${id}/summary.md'`, `description: '${yaml(member.goal)}'`, `purpose: '${yaml("Records the executable protocol scope and acceptance.")}'`, "version: '0.1.0'", `date: '${today()}'`, "status: 'ACTIVE'", "c4_level: 'product'", `parent: '.memory-bank/protocol/${id}/index.md'`, `protocol_set: ${psetPath ? `'${relativeMemory(psetPath)}'` : "null"}`, `blocked_by_protocols: ${yamlList(blockedBy)}`, `source_user_input: ${rawIntakePath ? `'${relativeMemory(rawIntakePath)}'` : "null"}`, `related_epics: ${yamlList(links.related_epics)}`, `related_features: ${yamlList(allFeatures)}`, `related_specs: ${yamlList(links.related_specs)}`, `related_adrs: ${yamlList(links.related_adrs)}`, `related_scenarios: ${yamlList(links.related_scenarios)}`, "tags: [protocol]", "---", "", `# ${id} — ${member.title}`, "", "## Goal", "", member.goal, "", "## Delivery role", "", member.role, "", "## Scope", "", "### In scope", ...member.in_scope.map((x) => `- ${x}`), "", "### Out of scope", ...member.out_of_scope.map((x) => `- ${x}`), "", "## Primary acceptance", "", `- Actor: ${a.actor}`, `- Initial state: ${a.initial_state}`, `- Action: ${a.action}`, `- Expected result: ${a.expected_result}`, `- Verification: ${a.verification}`, `- Proof limits: ${a.proof_limits}`, "", "## Owned requirements", "", ...ownedRequirements.map((obligation) => `- ${obligation.id}: ${obligation.statement}`), "", "## Owned acceptance criteria", "", ...ownedAcceptance.map((obligation) => `- ${obligation.id}: ${obligation.statement}`), "", "## Flow handoff", "", `- Source RUN: ${runId}`, "- Next action: PLAN", ""].join("\n");
+}
+function protocolIndexMarkdown(id) { return ["---", `file: '.memory-bank/protocol/${id}/index.md'`, "description: 'Protocol navigation.'", "purpose: 'Links the protocol summary and durable intake.'", "version: '0.1.0'", `date: '${today()}'`, "status: 'ACTIVE'", "c4_level: 'product'", "parent: '.memory-bank/protocol/index.md'", `children:\n  - .memory-bank/protocol/${id}/summary.md`, "tags: [protocol]", "---", "", `# ${id}`, "", "- [Summary](summary.md)", ""].join("\n"); }
+function psetMarkdown(id, result, obligations, members) {
+    const topology = result.delivery.pset;
+    const ids = new Map(result.delivery.members.map((member, index) => [member.key, members[index]]));
+    const replaceKeys = (value) => [...ids.entries()].reduce((text, [key, protocolId]) => text.replaceAll(key, protocolId), value);
+    return ["---", `file: '.memory-bank/protocol/_set/${id}.md'`, `description: '${yaml(result.delivery.title)}'`, "purpose: 'Records the protocol-set decomposition and execution topology.'", "version: '0.1.0'", `date: '${today()}'`, "status: 'ACTIVE'", "c4_level: 'product'", `members: ${yamlList(members.map((member) => `.memory-bank/protocol/${member}/index.md`))}`, "---", "", `# ${id} — ${result.delivery.title}`, "", "## Decomposition rationale", "", result.delivery.decomposition_rationale, "", "## Members", "", ...members.map((member, i) => `- ${member} — ${result.delivery.members[i].role}: ${result.delivery.members[i].title} (${result.delivery.members[i].blocked_by.length ? `blocked by ${result.delivery.members[i].blocked_by.map((key) => ids.get(key) ?? key).join(", ")}` : "startable now"})`), "", "## Obligation ownership", "", ...result.obligation_ownership.map((ownership) => `- ${ownership.obligation_id}: ${obligations.find((obligation) => obligation.id === ownership.obligation_id).statement} → ${ownership.member_keys.map((key) => ids.get(key) ?? key).join(", ")}`), "", "## Execution topology", "", `- Selected: ${topology.selected}`, `- Workspace owner: ${topology.workspace_owner === "not_applicable" ? "not_applicable" : ids.get(topology.workspace_owner) ?? topology.workspace_owner}`, `- Confirmation gate: ${topology.confirmation_gate}`, "", "### Dependency graph", "", ...topology.dependency_graph.map((edge) => `- ${replaceKeys(edge)}`), "", "### Feasible modes", "", ...topology.feasible_modes.map((mode) => `- ${mode.mode}: ${replaceKeys(mode.graph)}; ${mode.relative_duration}; ${mode.reason}`), "", "### Excluded modes", "", ...(topology.excluded_modes.length ? topology.excluded_modes.map((mode) => `- ${mode.mode}: ${mode.reason}`) : ["- None"]), ""].join("\n");
+}
+function materializeFeature(projectRoot, feature, protocolIds, created, remember, changed) {
+    if (feature.action === "not_applicable")
+        return null;
+    if (feature.action === "link" || feature.action === "update") {
+        if (!feature.epic_path || !feature.slug)
+            throw new AppError("validation", "feature.link requires epic_path and slug", 2);
+        const index = featureIndex(epicRootFor(projectRoot, feature.epic_path), feature.slug);
+        if (!fs.existsSync(index))
+            throw new AppError("not_found", "feature link/update must reference an existing feature", 1, { feature: relativeMemory(index) });
+        remember(index);
+        fs.writeFileSync(index, linkProtocols(fs.readFileSync(index, "utf8"), protocolIds));
+        changed.add(relativeMemory(index));
+        return index;
+    }
+    if (!feature.epic_path || !feature.title || !feature.slug)
+        throw new AppError("validation", "feature.create requires epic_path, title and slug", 2);
+    const epicRoot = epicRootFor(projectRoot, feature.epic_path);
+    if (!fs.existsSync(path.join(epicRoot, "index.md")))
+        throw new AppError("not_found", "feature epic_path must reference an existing epic", 1, { epic_path: feature.epic_path });
+    const featuresRoot = path.join(epicRoot, "features");
+    fs.mkdirSync(featuresRoot, { recursive: true });
+    const number = fs.readdirSync(featuresRoot).filter((name) => /^FT-\d+-/.test(name)).length + 1;
+    const id = `FT-${String(number).padStart(3, "0")}-${slug(feature.slug)}`;
+    const root = path.join(featuresRoot, id);
+    if (fs.existsSync(root))
+        throw new AppError("conflict", "Feature already exists", 1, { id });
+    fs.mkdirSync(root);
+    created.push(root);
+    const index = path.join(root, "index.md");
+    const summary = feature.summary?.trim() || feature.title;
+    fs.writeFileSync(index, `---\nfile: '${relativeMemory(index)}'\ndescription: '${yaml(summary)}'\npurpose: 'Records the user-facing feature and its protocol links.'\nversion: '0.1.0'\ndate: '${today()}'\nstatus: 'ACTIVE'\nparent: '${relativeMemory(path.join(epicRoot, "index.md"))}'\nrelated_protocols: [${protocolIds.map((id) => `'${id}'`).join(", ")}]\n---\n\n# ${id} — ${feature.title}\n\n${summary}\n`);
+    changed.add(relativeMemory(index));
+    const epicIndex = path.join(epicRoot, "index.md");
+    remember(epicIndex);
+    appendIndexEntry(epicIndex, relativeMemory(index), `${id} — ${feature.title}`);
+    changed.add(relativeMemory(epicIndex));
+    return index;
+}
+function copyRawIntake(runHome, protocolRoot) {
+    const source = path.join(runHome, "intake", "discussion.md");
+    if (!fs.existsSync(source))
+        return null;
+    const target = path.join(protocolRoot, "intake", "user-input.md");
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const body = fs.readFileSync(source, "utf8");
+    fs.writeFileSync(target, ["---", `file: '${relativeMemory(target)}'`, "description: 'Raw user input retained for protocol traceability.'", "purpose: 'Preserves the original intake used to form this protocol.'", "version: '0.1.0'", `date: '${today()}'`, "status: 'ACTIVE'", "c4_level: 'product'", `parent: '${relativeMemory(path.join(protocolRoot, "index.md"))}'`, "tags: [intake]", "---", "", body.trimEnd(), ""].join("\n"));
+    return target;
+}
+function today() { return new Date().toISOString().slice(0, 10); }
+function appendIndexEntry(indexPath, childPath, label) {
+    if (!fs.existsSync(indexPath))
+        throw new AppError("not_found", "Owning Memory Bank index is missing", 1, { index: indexPath });
+    const existing = fs.readFileSync(indexPath, "utf8");
+    const linkPath = path.posix.relative(path.posix.dirname(relativeMemory(indexPath)), childPath);
+    if (existing.includes(`](${linkPath})`) || existing.includes(childPath))
+        return;
+    let next = existing;
+    if (/^children:\s*\[\s*\]\s*$/m.test(next)) {
+        next = next.replace(/^children:\s*\[\s*\]\s*$/m, `children:\n  - ${childPath}`);
+    }
+    else if (/^children:\s*$/m.test(next)) {
+        next = next.replace(/^(children:\s*\n(?:\s+- .*\n)*)/m, `$1  - ${childPath}\n`);
+    }
+    else if (next.startsWith("---\n")) {
+        next = next.replace(/^---\n([\s\S]*?)\n---/, `---\n$1\nchildren:\n  - ${childPath}\n---`);
+    }
+    fs.writeFileSync(indexPath, `${next.trimEnd()}\n\n- [${label}](${linkPath})\n`);
+}
+function epicRootFor(projectRoot, value) { const resolved = path.resolve(projectRoot, value); const relative = path.relative(projectRoot, resolved); if (relative.startsWith("..") || path.isAbsolute(relative))
+    throw new AppError("path_escape", "epic_path must stay inside the project", 2, { epic_path: value }); return path.basename(resolved) === "index.md" ? path.dirname(resolved) : resolved; }
+function readResult(file) {
+    if (!fs.existsSync(file))
+        throw new AppError("not_found", "PROTOCOLIZE result is missing", 1, { file });
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    return value;
+}
+function acceptedSpecifyObligations(context, projectRoot, runId, specifyPath) {
+    if (!fs.existsSync(specifyPath))
+        throw new AppError("not_found", "PROTOCOLIZE requires accepted specify.json", 1, { path: specifyPath });
+    validateSchema({ schemaName: "vnext-specify", file: specifyPath, projectRoot, ddFlowHome: context.ddFlowHome, runId });
+    const specify = readVnextSpecifyResult(specifyPath);
+    return [
+        ...specify.requirements.map((obligation) => ({ ...obligation, kind: "requirement" })),
+        ...specify.acceptance_criteria.map((obligation) => ({ ...obligation, kind: "acceptance" }))
+    ];
+}
+/** SPECIFY is historical input; only a HITL-backed protocol amendment may alter its effective wording. */
+function effectiveObligations(result, accepted) {
+    const byId = new Map(accepted.map((obligation) => [obligation.id, obligation]));
+    const amended = new Set();
+    for (const amendment of result.obligation_amendments ?? []) {
+        const target = byId.get(amendment.target_id);
+        if (!target)
+            throw new AppError("validation", "Obligation amendment names an obligation absent from SPECIFY", 2, { target_id: amendment.target_id });
+        if (amended.has(amendment.target_id))
+            throw new AppError("validation", "An obligation may be amended only once", 2, { target_id: amendment.target_id });
+        if (!/^HITL-[A-Za-z0-9._-]+$/.test(amendment.hitl_ref))
+            throw new AppError("validation", "Obligation amendment needs a HITL reference", 2, { hitl_ref: amendment.hitl_ref });
+        byId.set(target.id, { ...target, statement: amendment.replacement });
+        amended.add(target.id);
+    }
+    return accepted.map((obligation) => byId.get(obligation.id));
+}
+function validateDelivery(projectRoot, result, obligations) {
+    const members = result.delivery.members;
+    const isSet = result.delivery.kind === "protocol_set";
+    if (!members.length || (!isSet && members.length !== 1) || (isSet && members.length < 2))
+        throw new AppError("validation", "Delivery kind and members must agree", 2);
+    if (!isSet && !["single_executable_protocol", "single_compact_protocol"].includes(result.scope_sizing_verdict))
+        throw new AppError("validation", "A single protocol requires a single-protocol scope verdict", 2);
+    if (isSet && result.scope_sizing_verdict !== "specification_with_slices_required")
+        throw new AppError("validation", "A PSET requires specification_with_slices_required", 2);
+    if (isSet && (!result.delivery.decomposition_rationale?.trim() || !result.delivery.pset))
+        throw new AppError("validation", "A PSET requires decomposition rationale and execution topology", 2);
+    const keys = new Set();
+    for (const member of members) {
+        if (![member.key, member.title, member.slug, member.goal, member.role, member.primary_acceptance?.actor, member.primary_acceptance?.action, member.primary_acceptance?.expected_result, member.primary_acceptance?.verification].every((x) => typeof x === "string" && x.trim()))
+            throw new AppError("validation", "Every protocol member needs key, role, title, slug, goal and primary acceptance", 2);
+        if (keys.has(member.key))
+            throw new AppError("validation", "Protocol member keys must be unique", 2, { key: member.key });
+        keys.add(member.key);
+        if (!Array.isArray(member.in_scope) || !Array.isArray(member.out_of_scope) || !Array.isArray(member.blocked_by))
+            throw new AppError("validation", "Protocol member scope and blocked_by must be arrays", 2);
+        for (const blocked of member.blocked_by)
+            if (!keys.has(blocked) && !members.some((candidate) => candidate.key === blocked))
+                throw new AppError("validation", "blocked_by must name a member key", 2, { member: member.key, blocked_by: blocked });
+    }
+    if (!obligations.length)
+        throw new AppError("validation", "SPECIFY has no accepted obligations", 2);
+    if (!result.obligation_ownership.length)
+        throw new AppError("validation", "A protocolized delivery needs obligation ownership", 2);
+    const covered = new Set();
+    const membersWithAcceptance = new Set();
+    for (const ownership of result.obligation_ownership) {
+        if (!obligations.some((obligation) => obligation.id === ownership.obligation_id))
+            throw new AppError("validation", "Obligation ownership names an obligation absent from SPECIFY", 2, { obligation_id: ownership.obligation_id });
+        if (covered.has(ownership.obligation_id))
+            throw new AppError("validation", "Each SPECIFY obligation needs one ownership entry", 2, { obligation_id: ownership.obligation_id });
+        covered.add(ownership.obligation_id);
+        for (const key of ownership.member_keys) {
+            if (!keys.has(key))
+                throw new AppError("validation", "Obligation ownership names an unknown member", 2, { key });
+            if (ownership.obligation_id.startsWith("AC-"))
+                membersWithAcceptance.add(key);
+        }
+    }
+    for (const obligation of obligations)
+        if (!covered.has(obligation.id))
+            throw new AppError("validation", "Every SPECIFY obligation must be owned by a protocol member", 2, { obligation_id: obligation.id });
+    for (const key of keys)
+        if (!membersWithAcceptance.has(key))
+            throw new AppError("validation", "Every protocol member must own at least one acceptance criterion", 2, { key });
+    validateDurableLinks(projectRoot, result.durable_links);
+    if (isSet)
+        validateTopology(result);
+}
+function validateDurableLinks(projectRoot, links) {
+    if (typeof links.preserve_raw_intake !== "boolean")
+        throw new AppError("validation", "durable_links.preserve_raw_intake must be boolean", 2);
+    for (const [kind, values] of Object.entries(links)) {
+        if (kind === "preserve_raw_intake")
+            continue;
+        if (!Array.isArray(values))
+            throw new AppError("validation", `durable_links.${kind} must be an array`, 2);
+        for (const value of values) {
+            const resolved = path.resolve(projectRoot, value);
+            inside(path.join(projectRoot, ".memory-bank"), resolved);
+            if (!fs.existsSync(resolved))
+                throw new AppError("not_found", "Durable link must point to an existing Memory Bank document", 1, { kind, path: value });
+        }
+    }
+}
+function validateTopology(result) {
+    const topology = result.delivery.pset;
+    if (!Array.isArray(topology.dependency_graph) || !Array.isArray(topology.feasible_modes) || !Array.isArray(topology.excluded_modes) || topology.confirmation_gate !== "before_first_code")
+        throw new AppError("validation", "PSET topology must define graph, modes and before_first_code confirmation", 2);
+    if (!["shared_serial_bundle", "isolated_parallel", "isolated_dependency_waves"].includes(topology.selected))
+        throw new AppError("validation", "PSET selected execution mode is invalid", 2);
+    const keys = new Set(result.delivery.members.map((member) => member.key));
+    if (topology.workspace_owner !== "not_applicable" && !keys.has(topology.workspace_owner))
+        throw new AppError("validation", "PSET workspace_owner must be a member key or not_applicable", 2);
+}
+function resultTemplate(obligations = []) {
+    return {
+        schema_id: "dd-flow/vnext-protocolize-result@3",
+        outcome: "protocolized",
+        scope_sizing_verdict: "single_executable_protocol",
+        delivery: { kind: "single_protocol", title: "", slug: "", members: [{ key: "primary", title: "", slug: "", goal: "", role: "Delivers the request end to end.", in_scope: [], out_of_scope: [], primary_acceptance: { actor: "", initial_state: "", action: "", expected_result: "", verification: "", proof_limits: "" }, blocked_by: [] }] },
+        obligation_ownership: obligations.map((obligation) => ({ obligation_id: obligation.id, member_keys: ["primary"] })),
+        obligation_amendments: [],
+        durable_links: { preserve_raw_intake: false, related_epics: [], related_features: [], related_specs: [], related_adrs: [], related_scenarios: [] },
+        feature: { action: "not_applicable", epic_path: "", title: "", slug: "", summary: "", reason: "" }
+    };
+}
+function renderPrompt(input) {
+    const obligationList = input.obligations.map((obligation) => `- ${obligation.id}: ${obligation.statement}`).join("\n");
+    return ["<work_context>", `- RUN: ${input.runId}`, `- Work: ${input.workId}`, `- Accepted SPECIFY JSON: ${input.specifyPath}`, `- Handoff: ${input.handoff.stage_handoff.effective}`, "</work_context>", "", "<accepted_obligations>", obligationList, "</accepted_obligations>", "", "<frozen_git_policy>", `- route: ${input.policy.route}`, `- integration branch: ${input.policy.integration_branch ?? "not applicable"}`, `- base ref: ${input.policy.base_ref ?? "not applicable"}`, `- feature branch: ${input.policy.feature_branch ?? "not applicable"}`, `- service worktree: ${input.policy.worktree_path ?? "not applicable"}`, `- bootstrap: ${input.policy.bootstrap_status}`, `- decision: ${input.policy.reason}`, "The CLI already created and bootstrapped this workspace at PROTOCOLIZE start. Do not create branches, worktrees, protocol files or Git commits yourself. This transition Work may run from the stable session; edit only the supplied RUN result file.", "</frozen_git_policy>", "", "<catalog>", input.catalog.length ? input.catalog.map((x) => `- ${x}`).join("\n") : "- inactive", "</catalog>", "", "<stage_instructions>", input.template.trim(), "</stage_instructions>", "", "<output_contract>", `Edit only ${input.resultPath}. Keep this exact JSON shape; CLI allocates ids and writes PRT/PSET/feature documents in the already provisioned workspace:\n\n\`\`\`json\n${JSON.stringify(resultTemplate(), null, 2)}\n\`\`\``, "Allocate every supplied R-* and AC-* exactly once in obligation_ownership. The CLI rejects unknown, duplicate or missing obligations, and every member must own at least one AC-*.", "If PROTOCOLIZE itself exposes a material user decision with no reasonable default, do not finish and do not return to SPECIFY. Run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:", "```sh", input.pauseCommandTemplate, "```", "Ask the returned user_message and stop. Resume this same PROTOCOLIZE Work using the exact command returned by pause.", `When the answer is incorporated and the result is protocolized, finish:\n\n${input.flow} stage finish ${input.runId} --stage protocolize --project-root ${JSON.stringify(input.projectRoot)} --result-file ${JSON.stringify(input.resultPath)} --json`, "</output_contract>", ""].join("\n");
+}
+function provisionWorkspaceForProtocolize(context, projectRoot, projectId, run, stageRoot) {
+    const receiptPath = path.join(stageRoot, "workspace-route.json");
+    if (fs.existsSync(receiptPath))
+        return readWorkspaceRouteReceipt(stageRoot).policy;
+    const config = loadVnextWorkspacePolicy(projectRoot);
+    const stableFacts = gitFacts(projectRoot);
+    if (config.workspace.route === "integration_branch_direct") {
+        const policy = { route: "integration_branch_direct", integration_branch: config.workspace.integration_branch, base_ref: stableFacts.head, feature_branch: null, worktree_path: null, reason: "Project workspace configuration explicitly selects the integration checkout.", provision_stage: "protocolize_start", stage_session_mode: stageSessionMode(context, run), provisioned: true, bootstrap_status: "not_applicable" };
+        writeJson(receiptPath, { schema_id: "dd-flow/vnext-workspace-route@1", policy, created: null, bootstrap: null });
+        return policy;
+    }
+    if (stableFacts.status === "unavailable" || !stableFacts.head || stableFacts.branch !== config.workspace.integration_branch) {
+        throw new AppError("workspace_route_invalid", "Configured feature worktree requires a clean, known integration checkout", 1, { expected_integration_branch: config.workspace.integration_branch, actual: stableFacts, project_root: projectRoot });
+    }
+    const branch = vnextRunBranch(config, run);
+    const holder = path.basename(projectRoot).replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+    const worktreePath = projectFeatureWorktreePath(context.ddFlowHome, projectId, `RUN-${run.short_id}`, holder);
+    const created = createManagedWorktree(context, { projectRoot, branch, base: stableFacts.head, path: worktreePath });
+    const bootstrap = bootstrapManagedWorktree(context, { projectRoot, worktreePath: created.worktreePath });
+    rebindFlowRunWorkspace(context, { projectRoot, runId: run.id, workspaceRoot: created.worktreePath, reason: "PROTOCOLIZE start provisioned the configured feature-worktree route" });
+    const policy = { route: "feature_worktree", integration_branch: config.workspace.integration_branch, base_ref: stableFacts.head, feature_branch: branch, worktree_path: created.worktreePath, reason: "Project workspace configuration requires a managed feature worktree before durable protocol documents exist.", provision_stage: "protocolize_start", stage_session_mode: stageSessionMode(context, run), provisioned: true, bootstrap_status: bootstrap.status };
+    writeJson(receiptPath, { schema_id: "dd-flow/vnext-workspace-route@1", policy, created, bootstrap });
+    return policy;
+}
+function readWorkspaceRouteReceipt(root) {
+    const file = path.join(root, "workspace-route.json");
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (value.schema_id !== "dd-flow/vnext-workspace-route@1" || !value.policy || !value.policy.provisioned)
+            throw new Error("invalid receipt");
+        return value;
+    }
+    catch (error) {
+        throw new AppError("workspace_route_missing", "PROTOCOLIZE workspace route receipt is missing or invalid", 1, { file, cause: String(error) });
+    }
+}
+function requiredPolicyValue(value, label) { if (!value)
+    throw new AppError("runtime_missing", `PROTOCOLIZE Git policy is missing ${label}`, 1); return value; }
+function allocateProtocolId(context, projectRoot, name) { return previewNextEntityId(context, { projectRoot, type: "protocol", slug: name }).entity.id; }
+function allocatePsetId(projectRoot, value) { const root = path.join(projectRoot, ".memory-bank", "protocol", "_set"); const used = fs.existsSync(root) ? fs.readdirSync(root).map((file) => /^PSET-(\d+)-/.exec(file)?.[1]).filter((item) => Boolean(item)).map(Number) : []; return `PSET-${String(Math.max(0, ...used) + 1).padStart(3, "0")}-${slug(value)}`; }
+function catalog(projectRoot) {
+    const memory = path.join(projectRoot, ".memory-bank");
+    const candidates = [
+        path.join(memory, "epics", "index.md"),
+        path.join(memory, "specs", "index.md"),
+        path.join(memory, "adr", "index.md"),
+        path.join(memory, "scenarios", "index.md"),
+        ...(fs.existsSync(path.join(memory, "epics")) ? fs.readdirSync(path.join(memory, "epics")).filter((name) => name.startsWith("EP-")).map((name) => path.join(memory, "epics", name, "index.md")) : [])
+    ];
+    return candidates.filter((file) => fs.existsSync(file)).map((file) => `${relativeMemory(file)}\n${fs.readFileSync(file, "utf8").trim()}`).sort();
+}
+function featureIndex(epicRoot, featureSlug) {
+    const direct = path.join(epicRoot, "features", featureSlug, "index.md");
+    if (fs.existsSync(direct))
+        return direct;
+    const features = path.join(epicRoot, "features");
+    const match = fs.existsSync(features) ? fs.readdirSync(features).find((name) => name === featureSlug || name.endsWith(`-${featureSlug}`)) : undefined;
+    return path.join(features, match ?? featureSlug, "index.md");
+}
+function requireWork(context, id) { const work = context.db.get("SELECT * FROM works WHERE work_id = ?", [id]); if (!work)
+    throw new AppError("not_found", "Work is not registered", 1, { work_id: id }); return work; }
+function requireRun(context, projectRoot, id) { const project = requireProjectByRoot(context, projectRoot); const run = context.db.get("SELECT id, short_id, slug, project_id, workspace_root, run_home_path FROM runs WHERE project_id = ? AND id = ?", [project.id, id]); if (!run)
+    throw new AppError("not_found", "RUN is not registered", 1, { run_id: id }); return run; }
+function requireRunHome(run) { if (!run.run_home_path)
+    throw new AppError("runtime_missing", "RUN has no portable workspace", 1); return run.run_home_path; }
+function inside(root, file) { const relative = path.relative(root, file); if (relative.startsWith("..") || path.isAbsolute(relative))
+    throw new AppError("path_escape", "Result must be inside the protocolize workspace", 2); }
+function writeJson(file, value) { const tmp = `${file}.${crypto.randomUUID()}.tmp`; fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`); fs.renameSync(tmp, file); }
+function slug(value) { const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""); if (!normalized)
+    throw new AppError("validation", "slug must contain ASCII letters or digits", 2); return normalized; }
+function yaml(value) { return value.replace(/'/g, "''"); }
+function yamlList(values) { return `[${values.map((value) => `'${yaml(value)}'`).join(", ")}]`; }
+function unique(values) { return [...new Set(values)]; }
+function linkProtocols(markdown, protocolIds) {
+    const line = /^related_protocols:\s*\[(.*)\]\s*$/m;
+    const existing = line.exec(markdown);
+    const ids = existing ? [...(existing[1] ?? "").matchAll(/'([^']+)'/g)].map((match) => match[1]) : [];
+    const next = `related_protocols: ${yamlList(unique([...ids, ...protocolIds]))}`;
+    if (existing)
+        return markdown.replace(line, next);
+    return markdown.replace(/^---\n([\s\S]*?)\n---/, `---\n$1\n${next}\n---`);
+}
+function relativeMemory(file) { const marker = `${path.sep}.memory-bank${path.sep}`; const at = file.indexOf(marker); return at >= 0 ? `.memory-bank/${file.slice(at + marker.length)}` : file; }
+function stageReport(context, run, resultFile, protocolIds, changedFiles, sessionId, now, policy) {
+    const startedAt = stageStartedAt(requireRunHome(run), now);
+    return { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage, generated_at: now, verdict: "done", semantic: { result: `Materialized ${protocolIds.length} executable protocol${protocolIds.length === 1 ? "" : "s"}.`, acceptance: protocolIds, changed_files: changedFiles, checks: ["result contract", "stage-report schema"], evidence: [resultFile], next_action: "start_plan" }, mechanical: { started_at: startedAt, finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(startedAt)), git: gitFacts(run.workspace_root), ...(policy ? { workspace_route: policy } : {}), observability: "query dd-flow stat after all RUN sessions have settled" }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html", summary: "stage-report.md" }, validation: { permission_scope: "known_targets_only", memory_bank_scope: "changed_files_and_links_only", status: "passed" } };
+}
+function stageStartedAt(runHome, fallback) {
+    try {
+        const index = JSON.parse(fs.readFileSync(path.join(runHome, "run.json"), "utf8"));
+        return index.stage_runs?.find((item) => item.stage === stage)?.started_at ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+function completeWorkSession(context, workId, resultFile, now) {
+    const workSession = context.db.get("SELECT * FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [workId]);
+    if (!workSession)
+        return null;
+    context.db.run("UPDATE work_sessions SET status = 'completed', result_path = ?, updated_at = ?, completed_at = ? WHERE id = ?", [resultFile, now, now, workSession.id]);
+    return { ...workSession, status: "completed", result_path: resultFile, updated_at: now, completed_at: now };
+}