@captain_z/zsk 1.8.5 → 1.8.7

package/dist/core/workflow-graph.js

@@ -0,0 +1,655 @@
+import { randomUUID } from "node:crypto";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import YAML from "yaml";
+import { templateIdFromConfig } from "./template-registry.js";
+import { getWorkspacePath } from "./workspace-layout.js";
+import { isPathInside, resolveProjectPath } from "./workspace-conformance.js";
+const STAGE_BLUEPRINTS = {
+    prepare: {
+        id: "prepare",
+        skill: "prepare",
+        reason: "shared source material should be indexed before downstream stage work starts",
+        inputs: () => [".zsk/config.yaml", ".zsk/raws/**", ".zsk/CONTEXT.md"],
+        outputs: () => [
+            ".zsk/raws/manifest.json",
+            ".zsk/evidence/prepare/{run-id}/acquisition-plan.json",
+            ".zsk/evidence/prepare/{run-id}/source-promotion-suggestions.md",
+        ],
+        qualityGate: "configured sources are acquired, explicitly blocked, or written as gaps/conflicts",
+        capabilities: ["resource-indexing", "source-readiness", "context-record"],
+    },
+    preproposal: {
+        id: "preproposal",
+        skill: "preproposal",
+        reason: "the intake needs product direction and readiness checks before a formal proposal",
+        inputs: (moduleId) => moduleArtifactInputs(moduleId, ["prepare evidence", ".zsk/CONTEXT.md"]),
+        outputs: (moduleId) => [modulePath(moduleId, "proposal-readiness.md", ".zsk/docs/proposal-readiness.md")],
+        qualityGate: "roadmap, product intent, UX readiness, and source gaps are explicit",
+        capabilities: ["product-framing", "readiness-review", "issue-routing"],
+    },
+    proposal: {
+        id: "proposal",
+        skill: "proposal",
+        reason: "scope and success criteria need to be frozen before detailed requirements",
+        inputs: (moduleId) => moduleArtifactInputs(moduleId, ["prepare evidence", ".zsk/CONTEXT.md"]),
+        outputs: (moduleId) => [modulePath(moduleId, "proposal.md", ".zsk/docs/proposal.md")],
+        qualityGate: "problem, non-goals, success criteria, stakeholders, and open questions are sourced",
+        capabilities: ["issue-routing", "source-traceability"],
+    },
+    spec: {
+        id: "spec",
+        skill: "spec",
+        reason: "requirements and acceptance criteria must become testable downstream inputs",
+        inputs: (moduleId) => [modulePath(moduleId, "proposal.md", ".zsk/docs/proposal.md"), ".zsk/CONTEXT.md"],
+        outputs: (moduleId) => [modulePath(moduleId, "spec.md", ".zsk/docs/spec.md")],
+        qualityGate: "FR/NFR, AC, scenarios, edge cases, and unresolved questions are traceable",
+        capabilities: ["acceptance-criteria", "source-traceability", "issue-routing"],
+    },
+    design: {
+        id: "design",
+        skill: "design",
+        reason: "interfaces, data flow, state, rollout, and risks should be explicit before tasks",
+        inputs: (moduleId) => [modulePath(moduleId, "spec.md", ".zsk/docs/spec.md"), ".zsk/CONTEXT.md"],
+        outputs: (moduleId) => [modulePath(moduleId, "design.md", ".zsk/docs/design.md")],
+        qualityGate: "implementation surfaces, ADRs, triggered controls, and risks are inspectable",
+        capabilities: ["architecture", "ux-flow", "risk-review"],
+    },
+    task: {
+        id: "task",
+        skill: "task",
+        reason: "the implementation should be split into issue-sized tasks before coding starts",
+        inputs: (moduleId) => [
+            modulePath(moduleId, "spec.md", ".zsk/docs/spec.md"),
+            modulePath(moduleId, "design.md", ".zsk/docs/design.md"),
+            ".zsk/work.yaml",
+            ".zsk/team.yaml",
+        ],
+        outputs: (moduleId) => [
+            modulePath(moduleId, "tasks.md", ".zsk/docs/tasks.md"),
+            ".zsk/work.jsonl",
+        ],
+        qualityGate: "tasks map to FR/AC, dependencies, owners, evidence hooks, and external work ids where available",
+        capabilities: ["issue-decomposition", "work-ledger", "talent-routing"],
+    },
+    coding: {
+        id: "coding",
+        skill: "coding",
+        reason: "the scoped task can now be implemented with fresh local evidence",
+        inputs: (moduleId) => [modulePath(moduleId, "tasks.md", ".zsk/docs/tasks.md"), ".zsk/work.jsonl"],
+        outputs: (moduleId) => [modulePath(moduleId, "_evidence/coding", ".zsk/evidence/coding")],
+        qualityGate: "changed behavior has targeted tests, lint/type evidence, and no unresolved blocker",
+        capabilities: ["tdd", "smoke", "work-status"],
+    },
+    demo: {
+        id: "demo",
+        skill: "demo",
+        reason: "browser-facing behavior should be demonstrated before formal verification",
+        inputs: (moduleId) => [
+            modulePath(moduleId, "_playwright/specs", ".zsk/playwright/specs"),
+            modulePath(moduleId, "_playwright/test-plans", ".zsk/playwright/test-plans"),
+        ],
+        outputs: (moduleId) => [modulePath(moduleId, "_evidence/demo", ".zsk/evidence/demo")],
+        qualityGate: "demo evidence includes reproducible screenshots/video/trace/logs or an explicit no-demo rationale",
+        capabilities: ["playwright", "visual-evidence", "issue-routing"],
+    },
+    verify: {
+        id: "verify",
+        skill: "verify",
+        reason: "the completion claim must be checked against acceptance criteria and evidence",
+        inputs: (moduleId) => [
+            modulePath(moduleId, "spec.md", ".zsk/docs/spec.md"),
+            modulePath(moduleId, "_evidence", ".zsk/evidence"),
+        ],
+        outputs: (moduleId) => [modulePath(moduleId, "verify.md", ".zsk/docs/verify.md")],
+        qualityGate: "fresh evidence proves or blocks every claimed acceptance criterion",
+        capabilities: ["verification", "evidence-review", "issue-routing"],
+    },
+    acceptance: {
+        id: "acceptance",
+        skill: "acceptance",
+        reason: "stakeholder acceptance or explicit rejection should be recorded before closure",
+        inputs: (moduleId) => [modulePath(moduleId, "verify.md", ".zsk/docs/verify.md")],
+        outputs: (moduleId) => [modulePath(moduleId, "acceptance.md", ".zsk/docs/acceptance.md")],
+        qualityGate: "accept/reject decision links evidence and residual risks",
+        capabilities: ["decision-record", "risk-ownership"],
+    },
+    archive: {
+        id: "archive",
+        skill: "archive",
+        reason: "durable decisions, evidence, and learning should be preserved after acceptance",
+        inputs: (moduleId) => [modulePath(moduleId, "acceptance.md", ".zsk/docs/acceptance.md")],
+        outputs: (moduleId) => [modulePath(moduleId, "archive.md", ".zsk/docs/archive.md")],
+        qualityGate: "handoff, evidence, issues, decisions, and documentation feedback are closed or linked",
+        capabilities: ["archive", "documentation-feedback", "learning"],
+    },
+};
+const PROFILE_FLOWS = {
+    "zsk-entry": ["coding"],
+    "zsk-lite": ["coding"],
+    "zsk-sdlc": ["prepare", "proposal", "spec", "design", "task", "coding", "verify", "acceptance", "archive"],
+    "zsk-frontend": ["prepare", "proposal", "spec", "design", "task", "coding", "demo", "verify", "acceptance", "archive"],
+    "zsk-enterprise": ["prepare", "proposal", "spec", "design", "task", "coding", "verify", "acceptance", "archive"],
+};
+export async function buildWorkflowGraphBundle(target, config, opts = {}) {
+    const workflowPolicy = await readWorkflowPolicy(target, config);
+    const profile = opts.profile ?? workflowPolicy.profile ?? config.workflow?.profile ?? "zsk-sdlc";
+    const runId = opts.runId ?? createWorkflowRunId();
+    const now = new Date().toISOString();
+    const explicitStages = parseStages(opts.stages);
+    const selection = selectStages(config, workflowPolicy, profile, opts.goal, explicitStages);
+    const stages = buildStages(selection.stages, opts.module, selection.failureReturnsTo);
+    const artifacts = resolveWorkflowArtifacts(target, config, runId);
+    const graph = {
+        version: 1,
+        runId,
+        createdAt: now,
+        updatedAt: now,
+        goal: normalizeGoal(opts.goal),
+        project: {
+            name: config.project?.name ?? config.project?.display_name ?? "<project-name>",
+            ...(opts.module ? { module: opts.module } : {}),
+            template: templateIdFromConfig(config),
+        },
+        profile,
+        strategy: workflowPolicy.strategy ?? config.workflow?.strategy ?? "adaptive",
+        selection: {
+            source: explicitStages.length > 0 ? "explicit" : "auto",
+            preferMinimalStages: selection.preferMinimalStages,
+            preferEvidenceStages: selection.preferEvidenceStages,
+            allowCustomStages: selection.allowCustomStages,
+            requireStageContract: selection.requireStageContract,
+            reasons: selection.reasons,
+        },
+        stages,
+        stopCondition: "all required stages are passed, skipped with rationale, or blocked with an issue and handoff",
+        artifacts: {
+            yaml: projectRelative(target, artifacts.yamlPath),
+            json: projectRelative(target, artifacts.jsonPath),
+            markdown: projectRelative(target, artifacts.markdownPath),
+            current: projectRelative(target, artifacts.currentPath),
+        },
+    };
+    return {
+        graph,
+        markdown: renderWorkflowGraphMarkdown(graph),
+        artifacts,
+    };
+}
+export async function writeWorkflowGraphBundle(bundle) {
+    await mkdir(bundle.artifacts.dir, { recursive: true });
+    await mkdir(dirname(bundle.artifacts.currentPath), { recursive: true });
+    await writeFile(bundle.artifacts.jsonPath, `${JSON.stringify(bundle.graph, null, 2)}\n`, "utf8");
+    await writeFile(bundle.artifacts.yamlPath, YAML.stringify(bundle.graph), "utf8");
+    await writeFile(bundle.artifacts.markdownPath, bundle.markdown, "utf8");
+    await writeFile(bundle.artifacts.currentPath, `${JSON.stringify({
+        runId: bundle.graph.runId,
+        graph: bundle.graph.artifacts.json,
+        markdown: bundle.graph.artifacts.markdown,
+        yaml: bundle.graph.artifacts.yaml,
+        updatedAt: bundle.graph.updatedAt,
+    }, null, 2)}\n`, "utf8");
+}
+export async function loadWorkflowGraph(target, config, runId) {
+    const plansRoot = resolve(target, getWorkspacePath(config, "plansRoot"));
+    const graphPath = runId
+        ? join(plansRoot, runId, "workflow-graph.json")
+        : await currentWorkflowGraphPath(target, config);
+    const content = await readFile(graphPath, "utf8");
+    const parsed = JSON.parse(content);
+    return { graph: parsed, path: graphPath };
+}
+export async function markWorkflowStage(target, config, opts) {
+    const { graph } = await loadWorkflowGraph(target, config, opts.runId);
+    const stage = graph.stages.find((candidate) => candidate.id === normalizeStageId(opts.stage));
+    if (!stage) {
+        throw new Error(`Unknown workflow stage: ${opts.stage}`);
+    }
+    const updatedAt = new Date().toISOString();
+    stage.status = opts.status;
+    stage.updatedAt = updatedAt;
+    if (opts.note)
+        stage.note = opts.note;
+    graph.updatedAt = updatedAt;
+    const artifacts = resolveWorkflowArtifacts(target, config, graph.runId);
+    return {
+        graph,
+        markdown: renderWorkflowGraphMarkdown(graph),
+        artifacts,
+    };
+}
+export async function advanceWorkflowGraph(target, config, opts = {}) {
+    const { graph } = await loadWorkflowGraph(target, config, opts.runId);
+    const stage = opts.stage
+        ? graph.stages.find((candidate) => candidate.id === normalizeStageId(opts.stage))
+        : nextWorkflowStage(graph);
+    const artifacts = resolveWorkflowArtifacts(target, config, graph.runId);
+    if (!stage) {
+        return {
+            graph,
+            markdown: renderWorkflowGraphMarkdown(graph),
+            artifacts,
+            updated: false,
+            result: {
+                runId: graph.runId,
+                action: "unchanged",
+                reason: "no pending workflow stage found",
+                evidence: [],
+            },
+        };
+    }
+    const previousStatus = stage.status;
+    const decision = await decideWorkflowAdvance(target, config, graph, stage);
+    if (decision.action !== "unchanged") {
+        const updatedAt = new Date().toISOString();
+        stage.status = decision.action === "passed" ? "passed" : "blocked";
+        stage.updatedAt = updatedAt;
+        stage.note = decision.reason;
+        graph.updatedAt = updatedAt;
+    }
+    return {
+        graph,
+        markdown: renderWorkflowGraphMarkdown(graph),
+        artifacts,
+        updated: decision.action !== "unchanged",
+        result: {
+            runId: graph.runId,
+            stage: stage.id,
+            previousStatus,
+            status: stage.status,
+            action: decision.action,
+            reason: decision.reason,
+            evidence: decision.evidence,
+            next: nextWorkflowStage(graph),
+        },
+    };
+}
+export function nextWorkflowStage(graph) {
+    return graph.stages.find((stage) => stage.status === "pending" || stage.status === "running" || stage.status === "blocked");
+}
+export function renderWorkflowGraphMarkdown(graph) {
+    return [
+        `# Workflow Graph: ${graph.goal}`,
+        "",
+        `- run_id: ${graph.runId}`,
+        `- profile: ${graph.profile}`,
+        `- strategy: ${graph.strategy}`,
+        `- module: ${graph.project.module ?? "project"}`,
+        `- selection: ${graph.selection.source}`,
+        `- stop_condition: ${graph.stopCondition}`,
+        "",
+        "## Selection Reasons",
+        "",
+        ...graph.selection.reasons.map((reason) => `- ${reason}`),
+        "",
+        "## Stages",
+        "",
+        ...graph.stages.flatMap((stage, index) => [
+            `### ${index + 1}. ${stage.id}`,
+            "",
+            `- status: ${stage.status}`,
+            `- skill: ${stage.skill}`,
+            `- reason: ${stage.reason}`,
+            `- depends_on: ${stage.dependsOn.length ? stage.dependsOn.join(", ") : "none"}`,
+            `- quality_gate: ${stage.qualityGate}`,
+            `- failure_returns_to: ${stage.failureReturnsTo}`,
+            `- capabilities: ${stage.capabilities.join(", ")}`,
+            "- inputs:",
+            ...stage.inputs.map((input) => `  - ${input}`),
+            "- outputs:",
+            ...stage.outputs.map((output) => `  - ${output}`),
+            "- command_hints:",
+            ...stage.commandHints.map((command) => `  - ${command}`),
+            ...(stage.note ? [`- note: ${stage.note}`] : []),
+            "",
+        ]),
+    ].join("\n");
+}
+function selectStages(config, workflowPolicy, profile, goal, explicitStages) {
+    const selection = {
+        ...(config.workflow?.stageSelection ?? {}),
+        ...(workflowPolicy.stageSelection ?? {}),
+    };
+    const allowCustomStages = selection.allowCustomStages ?? true;
+    const requireStageContract = selection.requireStageContract ?? true;
+    const preferMinimalStages = selection.preferMinimalStages ?? (profile === "zsk-entry" || profile === "zsk-lite");
+    const preferEvidenceStages = selection.preferEvidenceStages ?? (profile === "zsk-frontend" || profile === "zsk-enterprise");
+    const failureReturnsTo = workflowPolicy.workflowGraph?.failureReturnsTo ?? config.workflow?.workflowGraph?.failureReturnsTo ?? "nearest-owner-stage";
+    if (explicitStages.length > 0) {
+        return {
+            stages: normalizeStageList(explicitStages, allowCustomStages),
+            preferMinimalStages,
+            preferEvidenceStages,
+            allowCustomStages,
+            requireStageContract,
+            failureReturnsTo,
+            reasons: [
+                "explicit stage list was supplied by the caller",
+                `custom stages are ${allowCustomStages ? "allowed" : "rejected unless known"}`,
+            ],
+        };
+    }
+    const goalText = (goal ?? "").toLowerCase();
+    const reasons = [`profile ${profile} selected ${profileRoute(profile)}`];
+    let stages = [...(PROFILE_FLOWS[profile] ?? PROFILE_FLOWS["zsk-sdlc"] ?? [])];
+    if (preferMinimalStages) {
+        stages = hasConfiguredResources(config) ? ["prepare", "coding", "verify"] : ["coding", "verify"];
+        reasons.push("minimal stage preference reduced the graph to implementation plus verification");
+    }
+    if (!preferMinimalStages && shouldInsertPreproposal(goalText)) {
+        stages = insertAfter(stages, "prepare", "preproposal");
+        reasons.push("brief appears underspecified, so preproposal readiness was inserted");
+    }
+    if (shouldInsertDemo(goalText, profile, preferEvidenceStages)) {
+        stages = insertBefore(stages, "verify", "demo");
+        reasons.push("browser, UI, visual, or evidence-sensitive work requires a demo stage");
+    }
+    if (profile === "zsk-enterprise") {
+        stages = appendMissing(stages, ["acceptance", "archive"]);
+        reasons.push("enterprise profile keeps acceptance and archive gates explicit");
+    }
+    stages = normalizeStageList(stages, allowCustomStages);
+    return {
+        stages,
+        preferMinimalStages,
+        preferEvidenceStages,
+        allowCustomStages,
+        requireStageContract,
+        failureReturnsTo,
+        reasons,
+    };
+}
+function buildStages(stageIds, moduleId, failureReturnsTo) {
+    return stageIds.map((id, index) => {
+        const previous = stageIds[index - 1];
+        const blueprint = STAGE_BLUEPRINTS[id] ?? genericStageBlueprint(id);
+        const skill = blueprint.skill;
+        const stage = {
+            id,
+            skill,
+            status: "pending",
+            reason: blueprint.reason,
+            dependsOn: previous ? [previous] : [],
+            inputs: blueprint.inputs(moduleId),
+            outputs: blueprint.outputs(moduleId),
+            qualityGate: blueprint.qualityGate,
+            failureReturnsTo,
+            capabilities: blueprint.capabilities,
+            commandHints: commandHints(id, skill, moduleId),
+        };
+        return stage;
+    });
+}
+async function readWorkflowPolicy(target, config) {
+    const policyPath = config.customize?.workflow;
+    if (!policyPath || typeof policyPath !== "string")
+        return {};
+    const resolved = resolveProjectPath(target, policyPath);
+    if (!isPathInside(target, resolved) || !(await exists(resolved)))
+        return {};
+    const parsed = YAML.parse(await readFile(resolved, "utf8"));
+    if (!isRecord(parsed))
+        return {};
+    const policy = parsed;
+    return {
+        ...(typeof policy.profile === "string" ? { profile: policy.profile } : {}),
+        ...(typeof policy.strategy === "string" ? { strategy: policy.strategy } : {}),
+        ...(isRecord(policy.stageSelection) ? { stageSelection: policy.stageSelection } : {}),
+        ...(isRecord(policy.workflowGraph) ? { workflowGraph: policy.workflowGraph } : {}),
+        ...(isRecord(policy.capabilities) ? { capabilities: policy.capabilities } : {}),
+        ...(isRecord(policy.qualityGates) ? { qualityGates: policy.qualityGates } : {}),
+    };
+}
+function resolveWorkflowArtifacts(target, config, runId) {
+    const plansRoot = resolve(target, getWorkspacePath(config, "plansRoot"));
+    const dir = join(plansRoot, runId);
+    return {
+        dir,
+        yamlPath: join(dir, "workflow-graph.yaml"),
+        jsonPath: join(dir, "workflow-graph.json"),
+        markdownPath: join(dir, "workflow-graph.md"),
+        currentPath: join(plansRoot, "current-workflow-graph.json"),
+    };
+}
+async function decideWorkflowAdvance(target, config, graph, stage) {
+    const gate = await latestGateAssessment(target, config, stage.id, graph.project.module);
+    if (gate) {
+        const evidence = [projectRelative(target, gate.path)];
+        if ((gate.assessment.status === "READY" || gate.assessment.status === "WAIVED") && gate.assessment.decision === "proceed") {
+            return {
+                action: "passed",
+                reason: `stage gate ${gate.assessment.status} allows proceed`,
+                evidence,
+            };
+        }
+        if (gate.assessment.status === "BLOCKED" || gate.assessment.decision === "blocked") {
+            return {
+                action: "blocked",
+                reason: `stage gate blocked: ${firstReason(gate.assessment.blockers)}`,
+                evidence,
+            };
+        }
+        if (gate.assessment.status === "NEEDS_CONFIRMATION") {
+            return {
+                action: "blocked",
+                reason: `stage gate needs confirmation: ${firstReason(gate.assessment.gaps)}`,
+                evidence,
+            };
+        }
+    }
+    if (stage.id === "prepare") {
+        const manifestPath = resolve(target, getWorkspacePath(config, "rawsManifest"));
+        if (await exists(manifestPath)) {
+            return {
+                action: "passed",
+                reason: "prepare raw manifest exists",
+                evidence: [projectRelative(target, manifestPath)],
+            };
+        }
+    }
+    return {
+        action: "unchanged",
+        reason: `no decisive evidence found for ${stage.id}`,
+        evidence: [],
+    };
+}
+async function latestGateAssessment(target, config, stage, moduleId) {
+    const gatesRoot = resolve(target, getWorkspacePath(config, "evidenceRoot"), "gates");
+    let entries;
+    try {
+        entries = (await readdir(gatesRoot, { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort()
+            .reverse();
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        const file = join(gatesRoot, entry, "summary.json");
+        if (!(await exists(file)))
+            continue;
+        try {
+            const parsed = JSON.parse(await readFile(file, "utf8"));
+            if (!isRecord(parsed))
+                continue;
+            if (parsed.stage !== stage)
+                continue;
+            if (moduleId) {
+                if (parsed.module !== moduleId)
+                    continue;
+            }
+            else if (typeof parsed.module === "string" && parsed.module.trim().length > 0) {
+                continue;
+            }
+            return {
+                path: file,
+                assessment: {
+                    stage: typeof parsed.stage === "string" ? parsed.stage : undefined,
+                    module: typeof parsed.module === "string" ? parsed.module : undefined,
+                    status: typeof parsed.status === "string" ? parsed.status : undefined,
+                    decision: typeof parsed.decision === "string" ? parsed.decision : undefined,
+                    blockers: Array.isArray(parsed.blockers) ? parsed.blockers.filter((item) => typeof item === "string") : undefined,
+                    gaps: Array.isArray(parsed.gaps) ? parsed.gaps.filter((item) => typeof item === "string") : undefined,
+                },
+            };
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+async function currentWorkflowGraphPath(target, config) {
+    const plansRoot = resolve(target, getWorkspacePath(config, "plansRoot"));
+    const currentPath = join(plansRoot, "current-workflow-graph.json");
+    if (await exists(currentPath)) {
+        const parsed = JSON.parse(await readFile(currentPath, "utf8"));
+        if (typeof parsed.graph === "string" && parsed.graph.trim()) {
+            const graphPath = resolveProjectPath(target, parsed.graph);
+            if (!isPathInside(target, graphPath))
+                throw new Error("Current workflow graph pointer escapes the project.");
+            return graphPath;
+        }
+    }
+    const entries = await readdir(plansRoot, { withFileTypes: true });
+    const latest = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort()
+        .at(-1);
+    if (!latest)
+        throw new Error("No workflow graph found; run `zsk workflow plan` first.");
+    return join(plansRoot, latest, "workflow-graph.json");
+}
+function commandHints(stage, skill, moduleId) {
+    const moduleFlag = moduleId ? ` -m ${moduleId}` : "";
+    if (stage === "prepare") {
+        return ["zsk prepare run"];
+    }
+    if (stage === "coding") {
+        return [
+            `zsk gate assess --stage coding${moduleFlag}`,
+            `zsk dispatch plan --stage coding --skill ${skill}${moduleFlag} --surface auto`,
+        ];
+    }
+    return [
+        `zsk gate assess --stage ${stage}${moduleFlag}`,
+        `zsk dispatch plan --stage ${stage} --skill ${skill}${moduleFlag} --surface auto`,
+    ];
+}
+function moduleArtifactInputs(moduleId, fallback) {
+    if (!moduleId)
+        return fallback;
+    return [".zsk/raws/manifest.json", `.zsk/modules/${moduleId}/CONTEXT.md`, ...fallback];
+}
+function modulePath(moduleId, file, fallback) {
+    return moduleId ? join(".zsk/modules", moduleId, file) : fallback;
+}
+function normalizeGoal(goal) {
+    const trimmed = goal?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : "Continue the current ZSK delivery workflow";
+}
+function parseStages(value) {
+    if (!value)
+        return [];
+    return value.split(",").map((stage) => normalizeStageId(stage)).filter(Boolean);
+}
+function normalizeStageList(stages, allowCustomStages) {
+    const normalized = [];
+    for (const stage of stages) {
+        const id = normalizeStageId(stage);
+        if (!id || normalized.includes(id))
+            continue;
+        if (!allowCustomStages && !STAGE_BLUEPRINTS[id])
+            continue;
+        normalized.push(id);
+    }
+    return normalized;
+}
+function normalizeStageId(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function genericStageBlueprint(id) {
+    return {
+        id,
+        skill: id,
+        reason: "custom stage selected by workflow graph policy",
+        inputs: () => [".zsk/CONTEXT.md", ".zsk/plans/current-workflow-graph.json"],
+        outputs: () => [join(".zsk/evidence", id)],
+        qualityGate: "stage contract, sourced output, and explicit handoff are present",
+        capabilities: ["custom-stage", "issue-routing", "evidence"],
+    };
+}
+function hasConfiguredResources(config) {
+    return Object.keys(config.sources ?? {}).length > 0 || (config.resources ?? []).length > 0;
+}
+function shouldInsertPreproposal(goalText) {
+    if (!goalText)
+        return true;
+    if (/(vague|unclear|idea|brainstorm|探索|想法|模糊|不清楚|不确定)/i.test(goalText))
+        return true;
+    const tokens = goalText.split(/\s+/).filter(Boolean);
+    return tokens.length > 0 && tokens.length <= 4;
+}
+function shouldInsertDemo(_goalText, profile, _preferEvidenceStages) {
+    return profile === "zsk-frontend";
+}
+function insertAfter(stages, anchor, stage) {
+    if (stages.includes(stage))
+        return stages;
+    const index = stages.indexOf(anchor);
+    if (index === -1)
+        return [stage, ...stages];
+    return [...stages.slice(0, index + 1), stage, ...stages.slice(index + 1)];
+}
+function insertBefore(stages, anchor, stage) {
+    if (stages.includes(stage))
+        return stages;
+    const index = stages.indexOf(anchor);
+    if (index === -1)
+        return [...stages, stage];
+    return [...stages.slice(0, index), stage, ...stages.slice(index)];
+}
+function appendMissing(stages, additions) {
+    const next = [...stages];
+    for (const stage of additions) {
+        if (!next.includes(stage))
+            next.push(stage);
+    }
+    return next;
+}
+function firstReason(items) {
+    return items?.find((item) => item.trim().length > 0) ?? "see gate assessment";
+}
+function profileRoute(profile) {
+    return profile === "zsk-lite" || profile === "zsk-entry"
+        ? "adaptive-minimal"
+        : profile === "zsk-frontend"
+            ? "adaptive-frontend"
+            : profile === "zsk-enterprise"
+                ? "adaptive-enterprise"
+                : "adaptive-sdlc";
+}
+function projectRelative(root, value) {
+    const resolved = isAbsolute(value) ? value : resolve(root, value);
+    const rel = relative(root, resolved);
+    return rel === "" ? basename(resolved) : rel;
+}
+function createWorkflowRunId(now = new Date()) {
+    return `${now.toISOString().replace(/[:.]/g, "-")}-${randomUUID().slice(0, 12)}`;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=workflow-graph.js.map