@deksden-com/dd-flow-cli 0.2.0 → 0.3.0

package/dist/services/flow-guidance.js

@@ -0,0 +1,214 @@
+import path from "node:path";
+import { defaultFlowContract, flowContractForState } from "../domain/flow-contract.js";
+export function buildProtocolFlowGuidance(input) {
+    const contract = flowContractForState(input.state);
+    const stageChain = latestRunStageChain(input.latestRun);
+    return buildFlowGuidance({
+        currentStage: input.state.stage,
+        contract,
+        stageChain,
+        runId: stringValue(input.latestRun?.id),
+        queueStatus: input.queueStatus ?? null
+    });
+}
+export function buildRunFlowGuidance(input) {
+    const contract = input.contract ?? defaultFlowContract;
+    const chain = input.stageRuns.map((stage) => `${String(stage.stage ?? "unknown")}:${String(stage.status ?? "unknown")}`);
+    const currentStage = input.protocolStage ?? inferStageFromRun(input.stageRuns);
+    return buildFlowGuidance({
+        currentStage,
+        contract,
+        stageChain: chain,
+        runId: input.runId ?? null,
+        runDir: input.runDir ?? null,
+        stageRuns: input.stageRuns
+    });
+}
+export function buildStaticFlowGuidance(input) {
+    return buildFlowGuidance({
+        currentStage: input.stage,
+        contract: input.contract ?? defaultFlowContract,
+        stageChain: [],
+        runId: null,
+        queueStatus: input.queueStatus ?? null
+    });
+}
+function buildFlowGuidance(input) {
+    const planDone = hasDoneStage(input.stageChain, "plan");
+    const codeDone = hasDoneStage(input.stageChain, "code") || hasDoneStage(input.stageChain, "implementation") || hasDoneStage(input.stageChain, "readiness");
+    const evidence = evidencePaths(input.runId, input.runDir ?? null, input.stageRuns);
+    if (input.currentStage === "closed" || input.currentStage === "cancelled") {
+        return guidance(input, {
+            action: "none",
+            prompt: "none",
+            evidence: [],
+            guards: [{ id: "flow_terminal", status: "not_applicable", summary: `Protocol is ${input.currentStage}.` }],
+            missing: []
+        });
+    }
+    if (input.currentStage === "ready_for_merge" || input.currentStage === "queued_for_merge") {
+        return guidance(input, {
+            action: input.currentStage === "queued_for_merge" ? "wait for or run merge worker" : "run merge flow",
+            prompt: ".memory-bank/dd-flow/merge.md",
+            evidence: evidence.code.length > 0 ? evidence.code : defaultEvidence(input.runId, input.runDir ?? null, "03-code"),
+            guards: [
+                {
+                    id: "merge_requires_ready_for_merge",
+                    status: "pass",
+                    summary: input.queueStatus ? `Protocol is ${input.currentStage}; queue status is ${input.queueStatus}.` : `Protocol is ${input.currentStage}.`
+                }
+            ],
+            missing: []
+        });
+    }
+    if (input.currentStage === "integration") {
+        return guidance(input, {
+            action: "finish merge job",
+            prompt: ".memory-bank/dd-flow/merge/job.md",
+            evidence: evidence.code.length > 0 ? evidence.code : defaultEvidence(input.runId, input.runDir ?? null, "03-code"),
+            guards: [{ id: "merge_requires_ready_for_merge", status: "pass", summary: "Merge job is in integration stage." }],
+            missing: []
+        });
+    }
+    if (input.currentStage === "readiness") {
+        return guidance(input, {
+            action: "complete readiness and mark ready for merge",
+            prompt: ".memory-bank/dd-flow/code/readiness.md",
+            evidence: evidence.code.length > 0 ? evidence.code : defaultEvidence(input.runId, input.runDir ?? null, "03-code"),
+            guards: [{ id: "merge_requires_ready_for_merge", status: codeDone ? "unknown" : "fail", summary: codeDone ? "Code evidence exists; readiness must still be completed." : "Code evidence is missing." }],
+            missing: codeDone ? ["ready_for_merge transition"] : ["code stage report", "ready_for_merge transition"]
+        });
+    }
+    if (input.currentStage === "implementation" || input.currentStage === "hardening") {
+        return guidance(input, {
+            action: "continue code flow",
+            prompt: input.currentStage === "hardening" ? ".memory-bank/dd-flow/finish.md" : ".memory-bank/dd-flow/code.md",
+            evidence: evidence.plan.length > 0 ? evidence.plan : defaultEvidence(input.runId, input.runDir ?? null, "02-plan"),
+            guards: [{
+                    id: "code_flow_requires_plan_ready",
+                    status: planDone ? "pass" : "unknown",
+                    summary: planDone ? "Plan stage evidence exists." : "Plan evidence was not found in the linked run."
+                }],
+            missing: planDone ? [] : ["plan stage report", "ready_for_code verdict"]
+        });
+    }
+    if (input.currentStage === "plan") {
+        return guidance(input, {
+            action: planDone ? "run code flow" : "complete plan flow",
+            prompt: planDone ? ".memory-bank/dd-flow/code.md" : ".memory-bank/dd-flow/plan.md",
+            evidence: evidence.plan.length > 0 ? evidence.plan : defaultEvidence(input.runId, input.runDir ?? null, "02-plan"),
+            guards: [{
+                    id: "code_flow_requires_plan_ready",
+                    status: planDone ? "pass" : "fail",
+                    summary: planDone ? "Plan stage report exists in linked run evidence." : "Plan stage evidence is not complete."
+                }],
+            missing: planDone ? [] : ["plan stage report", "ready_for_code verdict"]
+        });
+    }
+    if (input.currentStage === "specify" || input.currentStage === "priming" || input.currentStage === "prime" || input.currentStage === "registered") {
+        const action = input.currentStage === "registered" ? "run protocol/specify flow" : "run plan flow after specification is complete";
+        return guidance(input, {
+            action,
+            prompt: input.currentStage === "registered" ? ".memory-bank/dd-flow/protocol.md" : ".memory-bank/dd-flow/plan.md",
+            evidence: [],
+            guards: [{
+                    id: "plan_requires_protocol_and_specification",
+                    status: input.currentStage === "registered" ? "unknown" : "pass",
+                    summary: input.currentStage === "registered" ? "Protocol is registered; specification evidence must be checked by the prompt." : "Protocol has progressed past registration."
+                }],
+            missing: input.currentStage === "registered" ? ["specification evidence"] : []
+        });
+    }
+    if (input.currentStage === "blocked") {
+        return guidance(input, {
+            action: "resolve blocker and continue named safe flow",
+            prompt: "depends_on_blocker",
+            evidence: [],
+            guards: [{ id: "flow_blocked", status: "fail", summary: "Protocol is blocked." }],
+            missing: ["blocker resolution"]
+        });
+    }
+    if (input.currentStage === "waiting_for_user") {
+        return guidance(input, {
+            action: "collect user answer",
+            prompt: "active_protocol_context",
+            evidence: [],
+            guards: [{ id: "flow_waiting_for_user", status: "unknown", summary: "Protocol is waiting for user input." }],
+            missing: ["user answer"]
+        });
+    }
+    return guidance(input, {
+        action: `continue ${input.currentStage}`,
+        prompt: "active_flow_prompt",
+        evidence: [],
+        guards: [{ id: "flow_guidance_unknown_stage_policy", status: "unknown", summary: `No specific guidance rule for stage ${input.currentStage}.` }],
+        missing: []
+    });
+}
+function guidance(input, value) {
+    return {
+        current_stage: input.currentStage,
+        allowed_next_stages: input.contract.transitions[input.currentStage] ?? [],
+        recommended_next_action: value.action,
+        recommended_prompt: value.prompt,
+        required_predecessor_evidence: value.evidence,
+        guards: value.guards,
+        blocked_if_missing: value.missing
+    };
+}
+function latestRunStageChain(run) {
+    return Array.isArray(run?.stage_chain) ? run.stage_chain.filter((item) => typeof item === "string") : [];
+}
+function hasDoneStage(chain, stage) {
+    return chain.includes(`${stage}:done`);
+}
+function inferStageFromRun(stageRuns) {
+    const done = new Set(stageRuns.filter((stage) => stage.status === "done").map((stage) => stage.stage));
+    if (done.has("merge"))
+        return "closed";
+    if (done.has("code") || done.has("implementation") || done.has("readiness"))
+        return "ready_for_merge";
+    if (done.has("plan"))
+        return "plan";
+    return "registered";
+}
+function evidencePaths(runId, runDir, stageRuns) {
+    const result = { plan: [], code: [] };
+    if (!stageRuns)
+        return result;
+    for (const stage of stageRuns) {
+        const bucket = stage.stage === "plan" ? result.plan : ["code", "implementation", "readiness"].includes(String(stage.stage)) ? result.code : null;
+        if (!bucket)
+            continue;
+        const dir = stage.dir ? path.posix.join(runDir ?? legacyRunDir(runId), stage.dir) : stage.dir;
+        for (const field of [stage.data, stage.stage_report, stage.report]) {
+            if (field)
+                bucket.push(toEvidencePath(runId, runDir, stage.dir, field, dir));
+        }
+    }
+    return result;
+}
+function toEvidencePath(runId, runDir, stageDir, field, prefixedStageDir) {
+    if (!runId)
+        return field;
+    if (field.startsWith(".tasks/dd-flow-runs/"))
+        return field;
+    if (field.startsWith("runs/"))
+        return field;
+    if (stageDir && field.startsWith(`${stageDir}/`)) {
+        return path.posix.join(runDir ?? legacyRunDir(runId), field);
+    }
+    return prefixedStageDir ? path.posix.join(prefixedStageDir, field) : field;
+}
+function defaultEvidence(runId, runDir, dir) {
+    if (!runId)
+        return [`<RUN>/${dir}/stage-report.json`, `<RUN>/${dir}/stage-report.html`];
+    const base = path.posix.join(runDir ?? legacyRunDir(runId), dir);
+    return [path.posix.join(base, "stage-report.json"), path.posix.join(base, "stage-report.html")];
+}
+function legacyRunDir(runId) {
+    return runId ? path.posix.join(".tasks/dd-flow-runs", runId) : "<RUN>";
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/services/ids.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+import { formatFullId, parseFullEntityId } from "../domain/entity-ids.js";
+import { AppError } from "../shared/errors.js";
+import { projectRunHome, resolveProjectRoot } from "../storage/paths.js";
+const kindConfig = {
+    protocol: { type: "PRT", table: "protocols", fileRoot: ".memory-bank/protocol" },
+    run: { type: "RUN", table: "flow_runs", fileRoot: ".tasks/dd-flow-runs" }
+};
+export function previewNextEntityId(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const kind = parseEntityKind(input.type);
+    const slug = normalizeSlug(input.slug);
+    const config = kindConfig[kind];
+    const used = new Set();
+    for (const id of databaseIds(context, config.table, config.type)) {
+        addSequence(used, id, config.type);
+    }
+    for (const id of filesystemIds(projectRoot, config.fileRoot, config.type)) {
+        addSequence(used, id, config.type);
+    }
+    if (kind === "run") {
+        for (const id of homeRunIds(context, projectRoot)) {
+            addSequence(used, id, config.type);
+        }
+        for (const id of filesystemIds(projectRoot, ".tasks", config.type)) {
+            addSequence(used, id, config.type);
+        }
+    }
+    for (let sequence = 1; sequence <= 999; sequence += 1) {
+        if (used.has(sequence))
+            continue;
+        const id = formatFullId(config.type, sequence, slug);
+        const parsed = parseFullEntityId(id);
+        return {
+            ok: true,
+            project_root: projectRoot,
+            entity: {
+                kind,
+                type: config.type,
+                id,
+                short_id: parsed.shortId,
+                slug,
+                sequence,
+                reserved: false
+            }
+        };
+    }
+    throw new AppError("validation", `${config.type} id sequence exhausted`, 2);
+}
+function homeRunIds(context, projectRoot) {
+    const project = context.db.get("SELECT id FROM projects WHERE root = ? AND status = 'active'", [projectRoot]);
+    if (!project) {
+        return [];
+    }
+    const root = projectRunHome(context.ddFlowHome, project.id, "__placeholder__").replace(/__placeholder__$/, "");
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        return [];
+    }
+    return fs.readdirSync(root).filter((entry) => entry.startsWith("RUN-"));
+}
+function parseEntityKind(value) {
+    const normalized = value.toLowerCase();
+    if (normalized === "protocol" || normalized === "prt")
+        return "protocol";
+    if (normalized === "run")
+        return "run";
+    throw new AppError("validation", "--type must be protocol or run", 2, { type: value });
+}
+function databaseIds(context, table, type) {
+    return context.db.all(`SELECT id FROM ${table} WHERE id LIKE ?`, [`${type}-%`]).map((row) => row.id);
+}
+function filesystemIds(projectRoot, relativeRoot, type) {
+    const root = path.join(projectRoot, relativeRoot);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        return [];
+    }
+    return fs
+        .readdirSync(root)
+        .filter((entry) => entry.startsWith(`${type}-`))
+        .map((entry) => entry.replace(/\.md$/, ""));
+}
+function addSequence(used, id, type) {
+    try {
+        const parsed = parseFullEntityId(id);
+        if (parsed.type !== type)
+            return;
+        used.add(Number(parsed.shortId.slice(type.length + 1)));
+    }
+    catch {
+        return;
+    }
+}
+function normalizeSlug(value) {
+    const slug = value
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    if (!slug) {
+        throw new AppError("validation", "--slug must contain at least one ASCII letter or digit", 2);
+    }
+    return slug;
+}

package/dist/services/merge-queue.js

@@ -2,7 +2,7 @@ import { loadProjectFlowContract } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
 import { appendAudit } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
-import { persistProtocolState, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+import { persistProtocolState, protocolRunDiagnostics, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { acquireLaneLock, ensureLaneWorkspace, heartbeatLaneLock, releaseLaneLock, requireLaneLockOwner } from "./lanes.js";
 import { stopMergeWorker, stoppedMergeWorkerState } from "./sessions.js";
@@ -349,6 +349,14 @@ function transitionClaimedProtocolToIntegration(context, protocolId, workerId, n
             allowed: ["ready_for_merge", "queued_for_merge"]
         });
     }
+    const diagnostics = protocolRunDiagnostics(context, protocol, state).diagnostics;
+    const blockingDiagnostics = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (blockingDiagnostics.length > 0) {
+        throw new AppError("merge_protocol_run_mismatch", "Cannot claim a protocol while protocol and run evidence disagree", 1, {
+            protocol_id: protocolId,
+            diagnostics: blockingDiagnostics
+        });
+    }
     persistProtocolState(context, protocol, {
         ...state,
         stage: "integration",

package/dist/services/merge-worker.js

@@ -4,6 +4,8 @@ import { appendAudit } from "./audit.js";
 import { ensureLaneWorkspace, acquireLaneLock, releaseLaneLock, expireProjectLaneLocks } from "./lanes.js";
 import { claimNextMergeJob, queueForProject } from "./merge-queue.js";
 import { requireProjectByRoot } from "./projects.js";
+import { buildStaticFlowGuidance } from "./flow-guidance.js";
+import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { registerFlowSession, stopMergeWorker } from "./sessions.js";
 export function getMergeWorkerStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -11,7 +13,7 @@ export function getMergeWorkerStatus(context, input) {
         ok: true,
         project: { id: project.id, root: project.root },
         merge_worker: detectMergeWorkerState(context, project.id),
-        queue: queueForProject(context, project.id)
+        queue: queueForProject(context, project.id).map((job) => withJobGuidance(context, { ...job }))
     };
 }
 export function startMergeWorker(context, input) {
@@ -101,7 +103,34 @@ export function oneShotMergeClaim(context, input) {
             reason: "one-shot merge no job"
         });
     }
-    return { ok: true, claimed: Boolean(claimed.job), mode: "one_shot", job: claimed.job ?? null, lock: claimed.job ? lock.lock : null };
+    return {
+        ok: true,
+        claimed: Boolean(claimed.job),
+        mode: "one_shot",
+        job: claimed.job ? withJobGuidance(context, { ...claimed.job }) : null,
+        lock: claimed.job ? lock.lock : null,
+        flow_guidance: claimed.job ? withJobGuidance(context, { ...claimed.job }).flow_guidance : undefined
+    };
+}
+function withJobGuidance(context, job) {
+    const protocolId = typeof job.protocol_id === "string" ? job.protocol_id : "";
+    if (!protocolId)
+        return job;
+    try {
+        const protocol = requireProtocol(context, protocolId);
+        const state = readProtocolRuntimeState(context, protocol).state;
+        return {
+            ...job,
+            flow_guidance: buildStaticFlowGuidance({
+                stage: state.stage,
+                ...(state.flow_contract ? { contract: state.flow_contract } : {}),
+                queueStatus: String(job.status ?? "")
+            })
+        };
+    }
+    catch {
+        return job;
+    }
 }
 function detectMergeWorkerState(context, projectId) {
     expireProjectLaneLocks(context, projectId);

package/dist/services/projects.js

@@ -6,6 +6,8 @@ import { projectRuntimeRoot, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProject, codexHomeProfilesForProject, codexHookEventsForProject, hookStatusForProject } from "./hooks.js";
 import { dashboardMarkdownPath, globalDashboardMarkdownPath, readProjectConfig } from "./config.js";
+import { loadProjectFlowContract } from "../domain/flow-contract.js";
+import { buildStaticFlowGuidance } from "./flow-guidance.js";
 export function registerProject(context, input) {
     const root = resolveProjectRoot(input.root);
     const existing = findProjectByRoot(context, root);
@@ -154,10 +156,14 @@ export function getProjectStatus(context, input) {
     if (!project) {
         throw new AppError("not_found", `Project is not registered: ${root}`, 1);
     }
+    const flowContract = loadProjectFlowContract(root);
     const protocols = context.db.all(`SELECT id, status, stage, next_action, updated_at
      FROM protocols
      WHERE project_id = ?
-     ORDER BY updated_at DESC`, [project.id]);
+     ORDER BY updated_at DESC`, [project.id]).map((protocol) => ({
+        ...protocol,
+        flow_guidance: buildStaticFlowGuidance({ stage: String(protocol.stage), contract: flowContract })
+    }));
     const mergeQueue = context.db.all(`SELECT protocol_id, status, claimed_by_session_id, claimed_at, attempts_count, last_reason, completed_at,
        created_at, updated_at
      FROM merge_queue