@captain_z/zsk 1.8.1 → 1.8.2

package/dist/core/staffing-plan.js

@@ -0,0 +1,1115 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import YAML from "yaml";
+import { flattenProjectSources } from "./config.js";
+import { inferSourceOrigin } from "./origin-detection.js";
+import { gateThresholdForStage, writeGateAssessment } from "./stage-quality.js";
+import { getWorkspacePath } from "./workspace-layout.js";
+const DEFAULT_PACKET_TIMEOUT_POLICY = {
+    heartbeatIntervalMs: 60_000,
+    staleAfterMs: 600_000,
+    maxAttempts: 2,
+    onTimeout: "fallback-to-leader-sequential",
+};
+const BUILTIN_ROLE_POOL = {
+    roles: Object.fromEntries([
+        rolePoolEntry("lead-integrator", {
+            subagentType: "planner",
+            required: true,
+            activation: "required",
+            reason: "own stage scope, dispatch boundaries, integration, and final evidence",
+            writeScope: [
+                ".zsk/config.yaml",
+                ".zsk/roles.yaml",
+                ".zsk/raws/manifest.json",
+                ".zsk/raws/**/index.md",
+                ".zsk/evidence/**",
+                ".zsk/plans/**",
+            ],
+        }),
+        rolePoolEntry("product-owner", {
+            subagentType: "analyst",
+            stages: ["prepare", "proposal", "spec", "review", "verify", "acceptance"],
+            lanes: ["product", "pm", "requirement", "requirements", "srs", "prd"],
+            activation: "when product or requirement evidence is configured or in scope",
+            reason: "interpret product scope, requirement semantics, priorities, and acceptance gaps",
+        }),
+        rolePoolEntry("business-analyst", {
+            subagentType: "analyst",
+            stages: ["proposal", "spec"],
+            lanes: ["business", "domain", "process", "rules"],
+            activation: "when domain process or business-rule evidence is configured or in scope",
+            reason: "map domain process, terminology, business rules, and edge cases",
+        }),
+        rolePoolEntry("architect", {
+            subagentType: "architect",
+            stages: ["proposal", "spec", "design", "review"],
+            activation: "when architecture, API, system-boundary, or dependency decisions are in scope",
+            reason: "review system boundaries, module relationships, contracts, and technical risks",
+        }),
+        rolePoolEntry("backend-engineer", {
+            subagentType: "executor",
+            stages: ["prepare", "design"],
+            lanes: ["backend", "api", "service", "server", "repository", "repo", "repos"],
+            activation: "when backend, API, service, repository, or data sources are configured",
+            reason: "inspect backend sources, API contracts, data models, and service-boundary gaps",
+        }),
+        rolePoolEntry("frontend-engineer", {
+            subagentType: "executor",
+            stages: ["design"],
+            lanes: ["frontend", "web", "client", "mobile"],
+            activation: "when frontend implementation, routing, state, or UI integration is in scope",
+            reason: "map UI implementation, routing, state, and component integration risk",
+        }),
+        rolePoolEntry("design-specialist", {
+            subagentType: "designer",
+            stages: ["prepare", "design"],
+            lanes: ["design", "ui", "visual"],
+            activation: "when design, UI, visual, prototype, or asset sources are configured",
+            reason: "inspect design assets, screens, visual states, and design-source gaps",
+        }),
+        rolePoolEntry("ux-specialist", {
+            subagentType: "designer",
+            stages: ["prepare"],
+            lanes: ["ux", "ue", "user-experience", "research"],
+            activation: "when UX, UE, user-flow, or research sources are configured",
+            reason: "inspect user flows, interaction constraints, and usability ambiguity",
+        }),
+        rolePoolEntry("qa-engineer", {
+            subagentType: "test-engineer",
+            stages: ["prepare", "spec", "task", "coding", "review", "verify"],
+            lanes: ["qa", "test", "testing", "quality"],
+            activation: "when QA, test, acceptance, or quality evidence is configured or in scope",
+            reason: "connect requirements to acceptance scenarios, test coverage, and verification evidence",
+        }),
+        rolePoolEntry("security-reviewer", {
+            subagentType: "security-reviewer",
+            stages: ["spec", "design", "review"],
+            lanes: ["security", "sec", "auth"],
+            activation: "when auth, permission, privacy, or data-safety boundaries are in scope",
+            reason: "review trust boundaries, credentials, privacy, and abuse cases",
+        }),
+        rolePoolEntry("operations-engineer", {
+            subagentType: "executor",
+            lanes: ["ops", "devops", "release", "deploy", "platform"],
+            activation: "when environment, CI/CD, deployment, or platform risks are configured or in scope",
+            reason: "review release, deployment, rollback, and operational risks",
+        }),
+        rolePoolEntry("auth-fetch-agent", {
+            subagentType: "researcher",
+            stages: ["prepare"],
+            remoteSources: true,
+            activation: "when remote or provider-managed sources are configured",
+            reason: "materialize remote/provider sources through explicit auth, session, and fetch contracts",
+        }),
+        rolePoolEntry("researcher", {
+            subagentType: "researcher",
+            stages: ["prepare"],
+            activation: "optional when current official or external evidence is required",
+            reason: "collect official/current external references only when configured local sources are insufficient",
+        }),
+        rolePoolEntry("planner", {
+            subagentType: "planner",
+            stages: ["task"],
+            activation: "when task sequencing, dependencies, and risk flags are in scope",
+            reason: "sequence implementation tasks, dependencies, ownership, and evidence hooks",
+        }),
+        rolePoolEntry("executor", {
+            subagentType: "executor",
+            stages: ["task", "coding"],
+            activation: "when implementation ownership, write scope, or scoped code changes are in scope",
+            reason: "implement or estimate scoped code ownership and write boundaries",
+        }),
+        rolePoolEntry("technical-writer", {
+            subagentType: "writer",
+            stages: ["proposal", "archive"],
+            activation: "when documentation structure, decision records, or handoff clarity are in scope",
+            reason: "preserve traceable docs, decisions, and reusable learning",
+        }),
+        rolePoolEntry("senior-engineering-reviewer", {
+            subagentType: "code-reviewer",
+            stages: ["review"],
+            activation: "when execution-path correctness, maintainability, regressions, or API compatibility need review",
+            reason: "review execution-path correctness, maintainability, regressions, and API boundaries",
+        }),
+        rolePoolEntry("ue-a11y-reviewer", {
+            subagentType: "designer",
+            stages: ["review"],
+            activation: "when UI, UX, accessibility, i18n, or visual behavior is touched",
+            reason: "review UX, accessibility, i18n, and visual impacts when UI is touched",
+        }),
+        rolePoolEntry("verifier", {
+            subagentType: "verifier",
+            required: true,
+            activation: "required",
+            reason: "verify stage outputs against source authority and command evidence",
+        }),
+    ]),
+};
+const ROLE_CONTRACTS = {
+    "lead-integrator": {
+        owns: [
+            "stage plan, staffing, integration, source status, and evidence gate",
+            "shared config, manifest, indexes, and final handoff summary",
+        ],
+        doesNotOwn: [
+            "treating lane output as automatic approval",
+            "inventing source authority or business acceptance without evidence",
+        ],
+        outputs: [
+            ".zsk/evidence/{scope}/{run}/integration-summary.md",
+            ".zsk/raws/manifest.json when prepare snapshots change",
+        ],
+        evidenceRequired: [
+            "integrated lane status with pass/blocker/waived reason for each role",
+            "confirmation that shared/global artifacts were updated only after lane validation",
+        ],
+        forbiddenDecisions: [
+            "Do not accept subagent output without checking its evidence and write scope.",
+            "Do not decide uncertain source-to-lane mapping, platform identity, or authority without user confirmation.",
+        ],
+        stopCondition: "All required lanes are integrated with evidence, or unresolved blockers are recorded for user/next-stage action.",
+    },
+    "product-owner": {
+        owns: ["business goals, product scope, priorities, requirement semantics, and acceptance meaning"],
+        doesNotOwn: ["backend implementation details", "technical feasibility signoff without architect/engineer evidence"],
+        outputs: [".zsk/evidence/{scope}/{run}/product-source-report.md"],
+        evidenceRequired: ["requirement/source IDs or paths behind each product claim", "open requirement gaps and acceptance risks"],
+        forbiddenDecisions: ["Do not rewrite technical design or implementation ownership.", "Do not turn weak/inferred evidence into accepted requirements."],
+        stopCondition: "Product facts, gaps, and acceptance risks are explicit and handed to lead-integrator.",
+    },
+    "business-analyst": {
+        owns: ["domain process, terminology, business rules, and edge cases"],
+        doesNotOwn: ["UI aesthetics", "implementation architecture"],
+        outputs: [".zsk/evidence/{scope}/{run}/business-rule-map.md"],
+        evidenceRequired: ["business rule source references", "ambiguity list for unresolved process or terminology conflicts"],
+        forbiddenDecisions: ["Do not choose product priority or implementation strategy.", "Do not resolve contradictory business rules silently."],
+        stopCondition: "Rules, edge cases, and unresolved ambiguities are documented for lead-integrator.",
+    },
+    architect: {
+        owns: ["system boundaries, module relationships, data flow, integration risks, and API/dependency boundaries"],
+        doesNotOwn: ["product priority decisions", "business acceptance signoff"],
+        outputs: [".zsk/evidence/{scope}/{run}/architecture-review.md"],
+        evidenceRequired: ["referenced files, modules, APIs, or diagrams behind architecture claims", "risk map with owner and verification hook"],
+        forbiddenDecisions: ["Do not override product acceptance or source truth.", "Do not widen implementation scope without lead-integrator handoff."],
+        stopCondition: "Architecture risks and boundary decisions are ready for integration or recorded as blockers.",
+    },
+    "backend-engineer": {
+        owns: ["backend repositories, API contracts, data model, auth/service boundaries, and backend snapshot validation"],
+        doesNotOwn: ["product acceptance wording", "design asset interpretation"],
+        outputs: [".zsk/evidence/{scope}/{run}/backend-source-report.md"],
+        evidenceRequired: ["repository/ref/path evidence", "API contract paths, data/auth risks, and missing backend source gaps"],
+        forbiddenDecisions: ["Do not infer product behavior from implementation alone.", "Do not write shared config or manifests directly from a lane."],
+        stopCondition: "Backend facts and gaps are reported with source references and no shared artifact edits pending.",
+    },
+    "frontend-engineer": {
+        owns: ["UI implementation, routing, state, component integration, and frontend framework constraints"],
+        doesNotOwn: ["source-of-truth product decisions", "backend/API correctness signoff"],
+        outputs: [".zsk/evidence/{scope}/{run}/frontend-impact-report.md"],
+        evidenceRequired: ["component/route/state file references", "UI implementation risks and validation hooks"],
+        forbiddenDecisions: ["Do not reinterpret acceptance criteria without product-owner handoff.", "Do not approve API behavior without backend evidence."],
+        stopCondition: "Frontend impact and validation needs are clear for lead-integrator.",
+    },
+    "design-specialist": {
+        owns: ["design assets, visual constraints, screen/state inventory, and design snapshot validation"],
+        doesNotOwn: ["backend/API correctness", "final product scope acceptance"],
+        outputs: [".zsk/evidence/{scope}/{run}/design-asset-report.md"],
+        evidenceRequired: ["design/prototype source references", "screen/state map and missing asset list"],
+        forbiddenDecisions: ["Do not infer implementation truth from design assets.", "Do not store auth state or exported private assets outside declared scope."],
+        stopCondition: "Design assets are mapped or blocked with provider/auth evidence.",
+    },
+    "ux-specialist": {
+        owns: ["user flows, interaction constraints, usability risks, and UX source validation"],
+        doesNotOwn: ["backend/API correctness", "business priority decisions"],
+        outputs: [".zsk/evidence/{scope}/{run}/ux-source-report.md"],
+        evidenceRequired: ["flow/source references", "usability risks and unresolved interaction questions"],
+        forbiddenDecisions: ["Do not approve product scope or technical design alone.", "Do not resolve UX/product conflicts silently."],
+        stopCondition: "UX facts, questions, and risks are ready for lead integration.",
+    },
+    "ue-a11y-reviewer": {
+        owns: ["UX, accessibility, visual, i18n, and frontend experience review when UI is touched"],
+        doesNotOwn: ["backend/API correctness", "security signoff"],
+        outputs: [".zsk/evidence/{scope}/{run}/ue-a11y-review.md"],
+        evidenceRequired: ["screens/components/scenarios reviewed", "accessibility and visual evidence or waived reason"],
+        forbiddenDecisions: ["Do not block or pass backend/security behavior.", "Do not invent visual requirements absent source evidence."],
+        stopCondition: "UX/a11y findings are reported or explicitly waived with reason.",
+    },
+    "qa-engineer": {
+        owns: ["test cases, regression matrix, acceptance scenarios, Playwright/runtime evidence, and test gaps"],
+        doesNotOwn: ["business signoff", "implementation design ownership"],
+        outputs: [".zsk/evidence/{scope}/{run}/qa-evidence-report.md"],
+        evidenceRequired: ["test command/scenario evidence", "acceptance coverage and missing-test gaps"],
+        forbiddenDecisions: ["Do not treat unrun tests as passing.", "Do not accept partial snapshots as complete evidence."],
+        stopCondition: "Coverage status is pass/fail/blocked with concrete evidence and residual risk.",
+    },
+    "security-reviewer": {
+        owns: ["auth, permissions, privacy, trust boundaries, data safety, and abuse cases"],
+        doesNotOwn: ["general style review", "product priority decisions"],
+        outputs: [".zsk/evidence/{scope}/{run}/security-review.md"],
+        evidenceRequired: ["auth/data flow references", "secret-handling and permission-risk assessment"],
+        forbiddenDecisions: ["Do not expose credential values in outputs.", "Do not approve unsafe credential storage or broad token scanning."],
+        stopCondition: "Security/data risks are cleared, waived with rationale, or blocked for user decision.",
+    },
+    "operations-engineer": {
+        owns: ["environment, CI/CD, deployment, configuration, rollback, and release risks"],
+        doesNotOwn: ["product semantics", "code-level correctness signoff without engineer evidence"],
+        outputs: [".zsk/evidence/{scope}/{run}/release-readiness.md"],
+        evidenceRequired: ["environment/config/CI references", "deployment and rollback risks"],
+        forbiddenDecisions: ["Do not change production or external systems from a planning lane.", "Do not assume env secrets are available."],
+        stopCondition: "Operational risks and verification hooks are ready for integration.",
+    },
+    researcher: {
+        owns: ["official docs, external references, market/regulatory evidence when relevant"],
+        doesNotOwn: ["converting external evidence into accepted product requirements alone"],
+        outputs: [".zsk/evidence/{scope}/{run}/research-brief.md"],
+        evidenceRequired: ["source links and dates when external facts are used", "adaptation notes separating fact from recommendation"],
+        forbiddenDecisions: ["Do not replace local configured sources with generic web evidence.", "Do not cite stale/current-sensitive facts without retrieval evidence."],
+        stopCondition: "Research facts and confidence/gaps are handed to lead-integrator.",
+    },
+    "technical-writer": {
+        owns: ["documentation structure, decision records, changelog, handoff clarity, and learning notes"],
+        doesNotOwn: ["technical correctness approval alone", "business acceptance alone"],
+        outputs: [".zsk/evidence/{scope}/{run}/documentation-handoff.md"],
+        evidenceRequired: ["changed docs list and source/evidence links", "no-update rationale when docs feedback is not needed"],
+        forbiddenDecisions: ["Do not polish away unresolved blockers.", "Do not create docs outside configured .zsk paths."],
+        stopCondition: "Docs are traceable, scoped, and ready for the next stage.",
+    },
+    "auth-fetch-agent": {
+        owns: ["Playwright auth state references, provider export flows, current-page acquisition, and fetch/snapshot validation"],
+        doesNotOwn: ["business content interpretation", "final source authority decisions"],
+        outputs: [
+            ".zsk/evidence/prepare/{run}/adapter-results/*.json",
+            ".zsk/raws/prepare/{lane}/{source}.md",
+        ],
+        evidenceRequired: [
+            "adapter result with origin, strategy, validation, and snapshot hash",
+            "confirmation that login/chrome/empty pages were rejected",
+            "confirmation that credential material stayed outside versioned snapshots and evidence text",
+        ],
+        forbiddenDecisions: [
+            "Do not infer platform type without configured origin evidence or successful probe evidence.",
+            "Do not overwrite a prior good snapshot with login, empty, redirect, or partial content.",
+            "Do not store cookies, tokens, passwords, or Playwright storageState in committed artifacts.",
+        ],
+        stopCondition: "Snapshots are materialized with validation, or each blocked source has auth/provider evidence and a next-action hint.",
+    },
+    "senior-engineering-reviewer": {
+        owns: ["execution-path correctness, maintainability, regressions, API compatibility, and dependency boundaries"],
+        doesNotOwn: ["security/privacy signoff alone", "business acceptance signoff"],
+        outputs: [".zsk/evidence/{scope}/{run}/engineering-review.md"],
+        evidenceRequired: ["file/line or artifact references for findings", "test and residual-risk assessment"],
+        forbiddenDecisions: ["Do not approve without evidence adequacy review.", "Do not rewrite scope while reviewing."],
+        stopCondition: "Engineering findings are listed by severity or no-issue rationale is evidence-backed.",
+    },
+    verifier: {
+        owns: ["completion claim validation, evidence adequacy, and residual risk"],
+        doesNotOwn: ["implementation changes", "business acceptance decisions"],
+        outputs: [".zsk/evidence/{scope}/{run}/verification-report.md"],
+        evidenceRequired: ["fresh command/artifact evidence", "explicit pass/fail/blocked verdict against the claim"],
+        forbiddenDecisions: ["Do not claim PASS from stale or indirect evidence.", "Do not fix while acting as verifier."],
+        stopCondition: "The claim is proven, rejected, or blocked with linked evidence.",
+    },
+    planner: {
+        owns: ["task sequencing, dependencies, risk flags, and handoff shape"],
+        doesNotOwn: ["implementation edits", "final acceptance decisions"],
+        outputs: [".zsk/evidence/{scope}/{run}/planning-notes.md"],
+        evidenceRequired: ["dependency and risk rationale", "clear next legal stage"],
+        forbiddenDecisions: ["Do not skip stage gates.", "Do not assign shared writes without ownership boundaries."],
+        stopCondition: "The sequence and blockers are executable by the next role.",
+    },
+    executor: {
+        owns: ["scoped implementation or refactor work inside assigned files/modules"],
+        doesNotOwn: ["global plan rewrite", "independent final approval"],
+        outputs: [".zsk/evidence/{scope}/{run}/implementation-report.md"],
+        evidenceRequired: ["changed files and validation evidence", "blocker report for scope/write conflicts"],
+        forbiddenDecisions: ["Do not edit outside assigned write scope.", "Do not revert unknown user changes."],
+        stopCondition: "Assigned implementation slice is done with evidence or blocked for leader decision.",
+    },
+};
+async function readStaffingRolePool(target, config) {
+    const pools = [BUILTIN_ROLE_POOL];
+    const rolePoolPath = config.staffing?.rolePool;
+    if (rolePoolPath) {
+        try {
+            const content = await readFile(resolve(target, rolePoolPath), "utf8");
+            pools.push(parseRolePool(YAML.parse(content)));
+        }
+        catch (error) {
+            if (rolePoolPath !== ".zsk/roles.yaml")
+                throw error;
+        }
+    }
+    if (config.staffing?.roles) {
+        pools.push(parseRolePool({ roles: config.staffing.roles }));
+    }
+    return mergeRolePools(...pools);
+}
+function parseRolePool(value) {
+    const rolesValue = isRecord(value) ? value.roles : undefined;
+    if (!isRecord(rolesValue))
+        return { roles: {} };
+    const entries = [];
+    for (const [role, config] of Object.entries(rolesValue)) {
+        if (!isRecord(config))
+            continue;
+        entries.push(rolePoolEntry(role, {
+            subagentType: stringValue(config.subagentType),
+            reason: stringValue(config.reason),
+            stages: stringList(config.stages),
+            skills: stringList(config.skills),
+            lanes: stringList(config.lanes),
+            required: booleanValue(config.required),
+            remoteSources: booleanValue(config.remoteSources),
+            activation: stringValue(config.activation),
+            extraInputs: stringList(config.inputs),
+            writeScope: stringList(config.writeScope),
+            outputs: stringList(config.outputs),
+            evidenceRequired: stringList(config.evidenceRequired),
+            contract: {
+                owns: stringList(config.owns),
+                doesNotOwn: stringList(config.doesNotOwn),
+                forbiddenDecisions: stringList(config.forbiddenDecisions),
+                stopCondition: stringValue(config.stopCondition),
+            },
+        }));
+    }
+    return { roles: Object.fromEntries(entries) };
+}
+function mergeRolePools(...pools) {
+    const roles = {};
+    for (const pool of pools) {
+        for (const [name, role] of Object.entries(pool.roles)) {
+            const existing = roles[name];
+            roles[name] = existing ? mergeRolePoolRole(existing, role) : { ...role };
+        }
+    }
+    return { roles };
+}
+function mergeRolePoolRole(base, override) {
+    return {
+        role: base.role,
+        subagentType: override.subagentType ?? base.subagentType,
+        reason: override.reason ?? base.reason,
+        stages: unique([...base.stages, ...override.stages]),
+        skills: unique([...base.skills, ...override.skills]),
+        lanes: unique([...base.lanes, ...override.lanes]),
+        required: base.required || override.required,
+        remoteSources: base.remoteSources || override.remoteSources,
+        activation: override.activation ?? base.activation,
+        extraInputs: unique([...base.extraInputs, ...override.extraInputs]),
+        writeScope: unique([...base.writeScope, ...override.writeScope]),
+        outputs: unique([...base.outputs, ...override.outputs]),
+        evidenceRequired: unique([...base.evidenceRequired, ...override.evidenceRequired]),
+        contract: mergeContractOverrides(base.contract, override.contract),
+    };
+}
+function rolePoolEntry(role, config) {
+    return [role, {
+            role,
+            subagentType: config.subagentType,
+            reason: config.reason,
+            stages: normalizeList(config.stages ?? []),
+            skills: normalizeList(config.skills ?? []),
+            lanes: normalizeList(config.lanes ?? []),
+            required: config.required === true,
+            remoteSources: config.remoteSources === true,
+            activation: config.activation,
+            extraInputs: unique(config.extraInputs ?? []),
+            writeScope: unique(config.writeScope ?? []),
+            outputs: unique(config.outputs ?? []),
+            evidenceRequired: unique(config.evidenceRequired ?? []),
+            contract: config.contract,
+        }];
+}
+function seedFromRolePool(role, entries, overrides = {}) {
+    return {
+        role: role.role,
+        subagentType: role.subagentType ?? "executor",
+        reason: overrides.reason ?? role.reason ?? `configured ${role.role} role`,
+        entries,
+        activation: overrides.activation ?? role.activation,
+        extraInputs: role.extraInputs,
+        writeScope: unique([...(role.writeScope ?? []), ...(overrides.writeScope ?? [])]),
+        outputs: unique([...(role.outputs ?? []), ...(overrides.outputs ?? [])]),
+        evidenceRequired: unique([...(role.evidenceRequired ?? []), ...(overrides.evidenceRequired ?? [])]),
+        contract: role.contract,
+    };
+}
+function roleMatchesStageOrSkill(role, stage, skill) {
+    if (role.required)
+        return true;
+    const stageSlug = safeSlug(stage);
+    const skillSlug = safeSlug(skill);
+    return role.stages.includes(stageSlug) || role.skills.includes(skillSlug);
+}
+function rolesForLane(lane, rolePool) {
+    const laneSlug = safeSlug(lane);
+    const matches = Object.values(rolePool.roles).filter((role) => role.lanes.includes(laneSlug));
+    if (matches.length > 0)
+        return matches;
+    return [
+        rolePoolEntry(`${safeSlug(lane)}-specialist`, {
+            subagentType: "executor",
+            lanes: [lane],
+            activation: "when configured source is present",
+            reason: `collect, validate, and materialize prepare lane \`${lane}\` without changing source authority`,
+        })[1],
+    ];
+}
+function summarizeStageGate(assessment, assessmentPath, markdownPath, waiverPath) {
+    return {
+        runId: assessment.runId,
+        stage: assessment.stage,
+        ...(assessment.module ? { module: assessment.module } : {}),
+        status: assessment.status,
+        decision: assessment.decision,
+        score: assessment.score,
+        threshold: assessment.threshold,
+        blockers: assessment.blockers,
+        gaps: assessment.gaps,
+        assessmentPath,
+        markdownPath,
+        ...(waiverPath ? { waiverPath } : {}),
+    };
+}
+function packetTimeoutPolicyFromConfig(config) {
+    const configured = config.staffing?.timeoutPolicy;
+    return {
+        heartbeatIntervalMs: positiveInteger(configured?.heartbeatIntervalMs) ?? DEFAULT_PACKET_TIMEOUT_POLICY.heartbeatIntervalMs,
+        staleAfterMs: positiveInteger(configured?.staleAfterMs) ?? DEFAULT_PACKET_TIMEOUT_POLICY.staleAfterMs,
+        maxAttempts: positiveInteger(configured?.maxAttempts) ?? DEFAULT_PACKET_TIMEOUT_POLICY.maxAttempts,
+        onTimeout: configured?.onTimeout ?? DEFAULT_PACKET_TIMEOUT_POLICY.onTimeout,
+    };
+}
+function positiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+export async function writeStaffingPlan(target, config, opts = {}) {
+    const rolePool = await readStaffingRolePool(target, config);
+    const bundle = buildStaffingPlan(target, config, opts, rolePool);
+    const gateBundle = await writeGateAssessment(target, config, {
+        stage: bundle.plan.stage,
+        module: opts.module,
+        threshold: opts.gateThreshold ?? gateThresholdForStage(config, bundle.plan.stage),
+        acceptRisk: opts.acceptRisk,
+    });
+    bundle.plan = {
+        ...bundle.plan,
+        ...(opts.module ? { module: opts.module } : {}),
+        stageGate: summarizeStageGate(gateBundle.assessment, gateBundle.artifacts.jsonPath, gateBundle.artifacts.markdownPath, gateBundle.artifacts.waiverPath),
+    };
+    bundle.markdown = renderStaffingPlanMarkdown(bundle.plan, bundle.ledger.timeoutPolicy);
+    await mkdir(dirname(bundle.artifacts.jsonPath), { recursive: true });
+    await mkdir(bundle.artifacts.packetStatusDir, { recursive: true });
+    await writeFile(bundle.artifacts.jsonPath, `${JSON.stringify(bundle.plan, null, 2)}\n`, "utf8");
+    await writeFile(bundle.artifacts.markdownPath, bundle.markdown, "utf8");
+    await writeFile(bundle.artifacts.emitPath, bundle.emitJsonl, "utf8");
+    await writeFile(bundle.artifacts.ledgerPath, `${JSON.stringify(bundle.ledger, null, 2)}\n`, "utf8");
+    for (const packet of bundle.ledger.packets) {
+        await writeFile(resolve(target, packet.statusPath), `${JSON.stringify(packet, null, 2)}\n`, "utf8");
+    }
+    return bundle;
+}
+export function buildStaffingPlan(target, config, opts = {}, rolePool = BUILTIN_ROLE_POOL) {
+    const runId = opts.runId ?? createStaffingRunId();
+    const stage = normalizeStage(opts.stage ?? "prepare");
+    const skill = opts.skill ?? stage;
+    const surface = opts.surface ?? "auto";
+    const timeoutPolicy = packetTimeoutPolicyFromConfig(config);
+    const entries = flattenProjectSources(config.sources);
+    const seeds = seedRoles(stage, skill, entries, rolePool);
+    const orchestration = buildOrchestrationPlan(surface, stage, entries, seeds, config);
+    const roles = seeds.map((seed) => buildRole(seed, stage, skill, orchestration, config));
+    const dir = resolve(target, getWorkspacePath(config, "evidenceRoot"), "dispatch", runId);
+    const relativeDir = join(getWorkspacePath(config, "evidenceRoot"), "dispatch", runId);
+    const artifacts = {
+        runId,
+        dir,
+        jsonPath: join(dir, "staffing-plan.json"),
+        markdownPath: join(dir, "staffing-plan.md"),
+        emitPath: join(dir, "emit-packets.jsonl"),
+        ledgerPath: join(dir, "emit-ledger.json"),
+        packetStatusDir: join(dir, "packet-status"),
+    };
+    const relativeLedgerPath = join(relativeDir, "emit-ledger.json");
+    const relativePacketStatusDir = join(relativeDir, "packet-status");
+    const emitPackets = roles
+        .filter((role) => role.active)
+        .map((role, index) => emitPacketForRole(role, runId, index + 1, relativeLedgerPath, relativePacketStatusDir, timeoutPolicy));
+    const ledger = buildEmitLedger(runId, stage, skill, relativeLedgerPath, relativePacketStatusDir, emitPackets, timeoutPolicy);
+    const plan = {
+        runId,
+        stage,
+        skill,
+        ...(opts.module ? { module: opts.module } : {}),
+        surface,
+        orchestration,
+        uncertaintyPolicy: [
+            "Do not promote uncertain source-to-lane correspondences without user confirmation.",
+            "Do not choose a provider-specific adapter from a URL guess when authority or completeness is unclear.",
+            "Do not overwrite a useful snapshot with an empty, login, redirect, or partial capture.",
+            "Do not store credentials, cookies, tokens, or Playwright storageState in raws, docs, evidence, or committed artifacts.",
+            "Do not run provider, design, repository, or work-item fetches from generic global credential names; credentials must be explicitly bound to the source or auth profile.",
+        ],
+        roles,
+        emitPackets,
+    };
+    return {
+        artifacts,
+        plan,
+        markdown: renderStaffingPlanMarkdown(plan, timeoutPolicy),
+        emitJsonl: emitPackets.map((packet) => JSON.stringify(packet)).join("\n") + "\n",
+        ledger,
+    };
+}
+export async function inspectStaffingRun(target, config, opts = {}) {
+    const dispatchRoot = resolve(target, getWorkspacePath(config, "evidenceRoot"), "dispatch");
+    const runId = opts.runId ?? await latestDispatchRunId(dispatchRoot);
+    const ledgerPath = join(dispatchRoot, runId, "emit-ledger.json");
+    const ledger = JSON.parse(await readFile(ledgerPath, "utf8"));
+    const now = opts.now ?? new Date();
+    const packets = [];
+    for (const packet of ledger.packets) {
+        const statusPath = resolve(target, packet.statusPath);
+        const current = JSON.parse(await readFile(statusPath, "utf8"));
+        const next = shouldMarkPacketStale(current, now) ? markPacketStale(current, now) : current;
+        packets.push(next);
+        if (next !== current)
+            await writeFile(statusPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    }
+    const nextLedger = { ...ledger, packets };
+    await writeFile(ledgerPath, `${JSON.stringify(nextLedger, null, 2)}\n`, "utf8");
+    return {
+        runId,
+        ledgerPath,
+        total: packets.length,
+        stale: packets.filter((packet) => packet.status === "stale").length,
+        pending: packets.filter((packet) => packet.status === "pending").length,
+        running: packets.filter((packet) => packet.status === "running").length,
+        completed: packets.filter((packet) => packet.status === "completed").length,
+        blocked: packets.filter((packet) => packet.status === "blocked").length,
+        failed: packets.filter((packet) => packet.status === "failed").length,
+        waived: packets.filter((packet) => packet.status === "waived").length,
+    };
+}
+async function latestDispatchRunId(dispatchRoot) {
+    const entries = (await readdir(dispatchRoot, { withFileTypes: true }))
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    const latest = entries.at(-1);
+    if (!latest)
+        throw new Error(`No dispatch runs found under ${dispatchRoot}`);
+    return latest;
+}
+function shouldMarkPacketStale(packet, now) {
+    if (!["pending", "running"].includes(packet.status))
+        return false;
+    const deadline = Date.parse(packet.deadlineAt);
+    return Number.isFinite(deadline) && now.getTime() > deadline;
+}
+function markPacketStale(packet, now) {
+    return {
+        ...packet,
+        status: "stale",
+        updatedAt: now.toISOString(),
+        blocker: "No heartbeat was recorded before the packet deadline; route this lane through leader-sequential fallback or re-emit with a new packet.",
+    };
+}
+function seedRoles(stage, skill, entries, rolePool) {
+    const seeds = new Map();
+    const poolRoles = Object.values(rolePool.roles);
+    for (const role of poolRoles) {
+        if (!role.required && !roleMatchesStageOrSkill(role, stage, skill))
+            continue;
+        addSeed(seeds, seedFromRolePool(role, []));
+    }
+    if (stage === "prepare" || skill === "prepare") {
+        for (const entry of entries) {
+            const lane = entry.rawLane ?? entry.segments[0] ?? "source";
+            const mapped = rolesForLane(lane, rolePool);
+            for (const role of mapped) {
+                addSeed(seeds, seedFromRolePool(role, [entry], {
+                    reason: role.reason || `collect, validate, and materialize prepare lane \`${lane}\` without changing source authority`,
+                    activation: role.activation ?? "when configured source is present",
+                }));
+            }
+        }
+        const remoteEntries = entries.filter((entry) => inferSourceOrigin(entry.source).remote);
+        if (remoteEntries.length > 0) {
+            for (const role of poolRoles.filter((item) => item.remoteSources && roleMatchesStageOrSkill(item, stage, skill))) {
+                addSeed(seeds, seedFromRolePool(role, remoteEntries, {
+                    activation: role.activation ?? "when remote/provider source is present",
+                    writeScope: [
+                        ".zsk/raws/prepare/**",
+                        ".zsk/playwright/.auth/**",
+                        ".zsk/evidence/prepare/**",
+                        ...role.writeScope,
+                    ],
+                    outputs: [
+                        ".zsk/evidence/prepare/{run}/adapter-results/*.json",
+                        ".zsk/raws/prepare/{lane}/{source}.md",
+                        ...role.outputs,
+                    ],
+                    evidenceRequired: [
+                        "adapter result with origin, strategy, validation, and snapshot hash",
+                        "confirmation that login/chrome/empty pages were rejected",
+                        "confirmation that storageState or credentials were not copied into versioned source snapshots",
+                        ...role.evidenceRequired,
+                    ],
+                }));
+            }
+        }
+    }
+    return [...seeds.values()];
+}
+function addSeed(seeds, seed) {
+    const existing = seeds.get(seed.role);
+    if (!existing) {
+        seeds.set(seed.role, {
+            ...seed,
+            entries: [...seed.entries],
+            activation: seed.activation,
+            extraInputs: [...(seed.extraInputs ?? [])],
+            writeScope: [...(seed.writeScope ?? [])],
+            outputs: [...(seed.outputs ?? [])],
+            evidenceRequired: [...(seed.evidenceRequired ?? [])],
+            contract: seed.contract,
+        });
+        return;
+    }
+    existing.entries.push(...seed.entries);
+    if (!existing.activation && seed.activation)
+        existing.activation = seed.activation;
+    existing.extraInputs?.push(...(seed.extraInputs ?? []));
+    existing.writeScope?.push(...(seed.writeScope ?? []));
+    existing.outputs?.push(...(seed.outputs ?? []));
+    existing.evidenceRequired?.push(...(seed.evidenceRequired ?? []));
+    existing.contract = mergeContractOverrides(existing.contract, seed.contract);
+}
+function buildOrchestrationPlan(surface, stage, entries, seeds, config) {
+    const requestedSurface = normalizeSurface(surface);
+    const explicitSurface = requestedSurface !== "auto";
+    const mode = normalizeMode(config.mode);
+    const scale = normalizeScale(config.scale);
+    const policy = dispatchPolicyFor(mode, scale);
+    const lanes = new Set(entries.map((entry) => entry.rawLane ?? entry.segments[0] ?? "source"));
+    const remoteCount = entries.filter((entry) => inferSourceOrigin(entry.source).remote).length;
+    const activeSeedCount = seeds.filter((seed) => seedIsActive(seed, stage)).length;
+    const stageParallelNeed = (policy.strictReview && ["review", "verify"].includes(stage)) ||
+        (["prepare", "design"].includes(stage) && activeSeedCount > 2);
+    const hasIndependentLanes = lanes.size > 1 ||
+        remoteCount > 0 ||
+        stageParallelNeed ||
+        activeSeedCount > 4;
+    const dispatchRecommended = requestedSurface !== "sequential" &&
+        hasIndependentLanes &&
+        (explicitSurface || policy.autoDispatch);
+    const selectedSurface = requestedSurface === "auto" && !dispatchRecommended ? "sequential" : requestedSurface;
+    const maxParallelLanes = requestedSurface === "sequential"
+        ? 1
+        : Math.min(policy.maxParallelLanes, Math.max(1, activeSeedCount - 1));
+    return {
+        requestedSurface,
+        selectedSurface,
+        mode,
+        scale,
+        dispatchRecommended,
+        laneIndependence: dispatchRecommended ? "parallel-capable" : "sequential",
+        reason: dispatchRecommended
+            ? `mode=${mode}, scale=${scale}: stage has independent expert lanes or remote/provider acquisition work`
+            : `mode=${mode}, scale=${scale}: ${policy.sequentialReason}`,
+        fallbackOrder: [
+            "native Codex subagents for bounded in-session parallel lanes",
+            "omx emit/team/ultrawork when durable or tmux-based coordination is available",
+            "leader-sequential role simulation with the same lane contract",
+        ],
+        maxParallelLanes,
+        overDispatchGuards: [
+            "Do not dispatch inactive lanes without configured source, touched surface, or explicit stage need.",
+            "Do not parallelize lanes that edit the same shared config, manifest, index, or module stage document.",
+            "Do not use subagents for a compact single-lane task when leader-sequential execution is clearer.",
+            "Do not let provider lanes write shared artifacts; lead-integrator owns integration.",
+            "Apply mode/scale policy before activating parallel lanes; explicit surface flags are the only override for solo/tiny scales.",
+        ],
+    };
+}
+function normalizeMode(value) {
+    return safeSlug(value ?? "standard") || "standard";
+}
+function normalizeScale(value) {
+    return safeSlug(value ?? "auto") || "auto";
+}
+function dispatchPolicyFor(mode, scale) {
+    const strictReview = ["strict", "incident", "review-heavy"].includes(mode);
+    if (scale === "solo" || scale === "tiny") {
+        return {
+            autoDispatch: false,
+            maxParallelLanes: 1,
+            strictReview,
+            sequentialReason: "solo/tiny scale keeps the common path leader-sequential unless the caller explicitly selects a dispatch surface",
+        };
+    }
+    if (scale === "small") {
+        return {
+            autoDispatch: true,
+            maxParallelLanes: 2,
+            strictReview,
+            sequentialReason: "small scale only parallelizes when independent evidence-backed lanes exist",
+        };
+    }
+    if (scale === "standard") {
+        return {
+            autoDispatch: true,
+            maxParallelLanes: 4,
+            strictReview,
+            sequentialReason: "standard scale found no independent lane that needs parallel dispatch",
+        };
+    }
+    if (scale === "large") {
+        return {
+            autoDispatch: true,
+            maxParallelLanes: 6,
+            strictReview,
+            sequentialReason: "large scale found no independent lane that needs parallel dispatch",
+        };
+    }
+    return {
+        autoDispatch: true,
+        maxParallelLanes: 6,
+        strictReview,
+        sequentialReason: "auto scale found no independent lane that needs parallel dispatch",
+    };
+}
+function buildRole(seed, stage, skill, orchestration, config) {
+    const active = seedIsActive(seed, stage);
+    const contract = contractForSeed(seed);
+    const route = active ? chooseRoute(orchestration, seed.subagentType) : "not-scheduled";
+    const inputs = unique([
+        ...sourceInputs(seed.entries),
+        ...(seed.extraInputs ?? []),
+        getWorkspacePath(config, "config"),
+        join(getWorkspacePath(config, "docsRoot"), "PROJECT-CONFIG.md"),
+        join(getWorkspacePath(config, "docsRoot"), "SYSTEM-SPEC.md"),
+    ]);
+    const writeScope = unique([
+        ...(seed.writeScope ?? []),
+        ...sourceWriteScopes(seed.entries),
+        getWorkspacePath(config, "evidenceRoot") + "/**",
+    ]);
+    const outputs = unique([
+        ...contract.outputs,
+        ...(seed.outputs ?? []),
+        ...seed.entries.map((entry) => entry.source.snapshot ?? entry.source.output).filter(isString),
+    ]);
+    const evidenceRequired = unique([
+        ...contract.evidenceRequired,
+        ...(seed.evidenceRequired ?? []),
+        "PROJECT-CONFIG.md and SYSTEM-SPEC.md constraints checked before stage output",
+        "explicit changed/unchanged/blocker result",
+        "fresh command or artifact evidence before completion claim",
+    ]);
+    return {
+        role: seed.role,
+        subagentType: seed.subagentType,
+        stage,
+        skill,
+        active,
+        route,
+        activation: seed.activation ?? "required for this stage",
+        reason: seed.reason,
+        owns: contract.owns,
+        doesNotOwn: contract.doesNotOwn,
+        inputs,
+        writeScope,
+        outputs,
+        evidenceRequired,
+        forbiddenDecisions: contract.forbiddenDecisions,
+        handoffTo: seed.role === "lead-integrator" ? "verifier" : "lead-integrator",
+        stopCondition: contract.stopCondition,
+        mustAskWhen: [
+            "source ownership, lane mapping, or platform identity is uncertain",
+            "remote auth is required and no approved reusable session exists",
+            "multiple sources conflict about the same product or implementation fact",
+            "a fetch returns login chrome, partial content, or ambiguous page content",
+            "a migration would move, delete, overwrite, or de-authorize existing snapshots",
+            "PROJECT-CONFIG.md or SYSTEM-SPEC.md conflicts with requested stage output",
+        ],
+    };
+}
+function chooseRoute(orchestration, subagentType) {
+    if (!orchestration.dispatchRecommended)
+        return "leader-sequential";
+    if (orchestration.selectedSurface === "native")
+        return `native:${subagentType}`;
+    if (orchestration.selectedSurface === "omx")
+        return `omx:emit:${subagentType}`;
+    if (orchestration.selectedSurface === "sequential")
+        return "leader-sequential";
+    return `auto:emit-compatible:${subagentType}`;
+}
+function contractForSeed(seed) {
+    return mergeRoleContract(contractForRole(seed.role, seed.subagentType), seed.contract);
+}
+function contractForRole(role, subagentType) {
+    if (ROLE_CONTRACTS[role])
+        return ROLE_CONTRACTS[role];
+    if (ROLE_CONTRACTS[subagentType])
+        return ROLE_CONTRACTS[subagentType];
+    return {
+        owns: ["the configured lane facts, gaps, outputs, and evidence for this role"],
+        doesNotOwn: ["shared config, manifest, indexes, global scope, or final approval"],
+        outputs: [".zsk/evidence/{scope}/{run}/lane-report.md"],
+        evidenceRequired: ["source references and blocker list for this lane"],
+        forbiddenDecisions: [
+            "Do not decide source authority, lane mapping, or business acceptance without lead-integrator confirmation.",
+            "Do not write outside the assigned lane scope.",
+        ],
+        stopCondition: "Lane facts and gaps are reported with evidence, or a blocker is handed to lead-integrator.",
+    };
+}
+function mergeRoleContract(base, override) {
+    if (!override)
+        return base;
+    return {
+        owns: override.owns && override.owns.length > 0 ? override.owns : base.owns,
+        doesNotOwn: override.doesNotOwn && override.doesNotOwn.length > 0 ? override.doesNotOwn : base.doesNotOwn,
+        outputs: override.outputs && override.outputs.length > 0 ? unique([...base.outputs, ...override.outputs]) : base.outputs,
+        evidenceRequired: override.evidenceRequired && override.evidenceRequired.length > 0
+            ? unique([...base.evidenceRequired, ...override.evidenceRequired])
+            : base.evidenceRequired,
+        forbiddenDecisions: override.forbiddenDecisions && override.forbiddenDecisions.length > 0
+            ? unique([...base.forbiddenDecisions, ...override.forbiddenDecisions])
+            : base.forbiddenDecisions,
+        stopCondition: override.stopCondition ?? base.stopCondition,
+    };
+}
+function mergeContractOverrides(base, override) {
+    if (!base)
+        return override;
+    if (!override)
+        return base;
+    return {
+        owns: override.owns && override.owns.length > 0 ? override.owns : base.owns,
+        doesNotOwn: override.doesNotOwn && override.doesNotOwn.length > 0 ? override.doesNotOwn : base.doesNotOwn,
+        outputs: unique([...(base.outputs ?? []), ...(override.outputs ?? [])]),
+        evidenceRequired: unique([...(base.evidenceRequired ?? []), ...(override.evidenceRequired ?? [])]),
+        forbiddenDecisions: unique([...(base.forbiddenDecisions ?? []), ...(override.forbiddenDecisions ?? [])]),
+        stopCondition: override.stopCondition ?? base.stopCondition,
+    };
+}
+function seedIsActive(seed, stage) {
+    if (seed.entries.length > 0)
+        return true;
+    if (seed.activation === "required")
+        return true;
+    if (seed.activation?.startsWith("optional"))
+        return false;
+    if ((stage === "prepare" || stage === "design") && seed.activation?.startsWith("when"))
+        return false;
+    return true;
+}
+function normalizeSurface(value) {
+    if (value === "native" || value === "omx" || value === "sequential")
+        return value;
+    return "auto";
+}
+function sourceInputs(entries) {
+    return entries.flatMap((entry) => {
+        const origin = inferSourceOrigin(entry.source);
+        return [
+            entry.path,
+            origin.ref ? `origin:${origin.ref}` : "",
+            entry.source.snapshot ? `snapshot:${entry.source.snapshot}` : "",
+        ].filter(isString);
+    });
+}
+function sourceWriteScopes(entries) {
+    return entries
+        .map((entry) => {
+        if (entry.source.snapshot)
+            return entry.source.snapshot;
+        if (entry.rawLane)
+            return `.zsk/raws/prepare/${entry.rawLane}/**`;
+        return "";
+    })
+        .filter(isString);
+}
+function emitPacketForRole(role, runId, sequence, ledgerPath, packetStatusDir, timeoutPolicy) {
+    const packetId = `${String(sequence).padStart(3, "0")}-${safeSlug(role.role)}`;
+    const statusPath = join(packetStatusDir, `${packetId}.json`);
+    const createdAt = new Date().toISOString();
+    const deadlineAt = new Date(Date.parse(createdAt) + timeoutPolicy.staleAfterMs).toISOString();
+    return {
+        event: "zsk.subagent.request",
+        version: 1,
+        payload: {
+            runId,
+            packetId,
+            stage: role.stage,
+            skill: role.skill,
+            role: role.role,
+            subagentType: role.subagentType,
+            active: role.active,
+            route: role.route,
+            activation: role.activation,
+            prompt: [
+                `Execute the ${role.stage} stage as ${role.role}.`,
+                `Activation: ${role.activation}.`,
+                "Stay inside the declared write scope.",
+                "Check PROJECT-CONFIG.md and SYSTEM-SPEC.md before deciding stage output.",
+                "Report blockers instead of silently deciding uncertain source facts.",
+            ].join(" "),
+            inputs: role.inputs,
+            writeScope: role.writeScope,
+            outputs: role.outputs,
+            evidenceRequired: role.evidenceRequired,
+            forbiddenDecisions: role.forbiddenDecisions,
+            handoffTo: role.handoffTo,
+            stopCondition: role.stopCondition,
+            constraints: role.mustAskWhen,
+            durability: {
+                ledgerPath,
+                statusPath,
+                status: "pending",
+                attempt: 1,
+                createdAt,
+                heartbeatIntervalMs: timeoutPolicy.heartbeatIntervalMs,
+                staleAfterMs: timeoutPolicy.staleAfterMs,
+                deadlineAt,
+                maxAttempts: timeoutPolicy.maxAttempts,
+                onTimeout: timeoutPolicy.onTimeout,
+                resumeHint: "Update this packet status with evidence before the lead-integrator claims the lane is complete.",
+            },
+        },
+    };
+}
+function buildEmitLedger(runId, stage, skill, ledgerPath, packetStatusDir, packets, timeoutPolicy) {
+    return {
+        version: 1,
+        runId,
+        stage,
+        skill,
+        ledgerPath,
+        packetStatusDir,
+        timeoutPolicy,
+        packets: packets.map((packet) => ({
+            packetId: packet.payload.packetId,
+            runId,
+            stage,
+            skill,
+            role: packet.payload.role,
+            subagentType: packet.payload.subagentType,
+            route: packet.payload.route,
+            status: "pending",
+            attempt: packet.payload.durability.attempt,
+            createdAt: packet.payload.durability.createdAt,
+            updatedAt: packet.payload.durability.createdAt,
+            lastHeartbeatAt: packet.payload.durability.createdAt,
+            deadlineAt: packet.payload.durability.deadlineAt,
+            staleAfterMs: packet.payload.durability.staleAfterMs,
+            maxAttempts: packet.payload.durability.maxAttempts,
+            fallbackRoute: "leader-sequential",
+            statusPath: packet.payload.durability.statusPath,
+            evidence: [],
+        })),
+    };
+}
+function renderStaffingPlanMarkdown(plan, timeoutPolicy) {
+    return [
+        "# Staffing Plan",
+        "",
+        `- Stage: \`${plan.stage}\``,
+        `- Skill: \`${plan.skill}\``,
+        ...(plan.module ? [`- Module: \`${plan.module}\``] : []),
+        `- Surface: \`${plan.surface}\``,
+        `- Roles: ${plan.roles.length}`,
+        `- Active emit lanes: ${plan.emitPackets.length}`,
+        ...(plan.stageGate ? [
+            `- Stage gate: \`${plan.stageGate.status}\` (${plan.stageGate.score}/10, decision \`${plan.stageGate.decision}\`)`,
+            `- Stage gate evidence: \`${plan.stageGate.assessmentPath}\``,
+        ] : []),
+        "",
+        "## Orchestration",
+        "",
+        `- Requested surface: \`${plan.orchestration.requestedSurface}\``,
+        `- Selected surface: \`${plan.orchestration.selectedSurface}\``,
+        `- Mode: \`${plan.orchestration.mode}\``,
+        `- Scale: \`${plan.orchestration.scale}\``,
+        `- Dispatch recommended: ${plan.orchestration.dispatchRecommended ? "yes" : "no"}`,
+        `- Lane independence: \`${plan.orchestration.laneIndependence}\``,
+        `- Reason: ${plan.orchestration.reason}`,
+        `- Max parallel lanes: ${plan.orchestration.maxParallelLanes}`,
+        `- Durable packet ledger: \`.zsk/evidence/dispatch/${plan.runId}/emit-ledger.json\``,
+        `- Packet timeout policy: heartbeat every ${timeoutPolicy.heartbeatIntervalMs}ms; stale after ${timeoutPolicy.staleAfterMs}ms; max attempts ${timeoutPolicy.maxAttempts}; fallback ${timeoutPolicy.onTimeout}`,
+        "",
+        "### Fallback Order",
+        "",
+        ...plan.orchestration.fallbackOrder.map((item) => `- ${item}`),
+        "",
+        "### Over-Dispatch Guards",
+        "",
+        ...plan.orchestration.overDispatchGuards.map((item) => `- ${item}`),
+        "",
+        "## Uncertainty Policy",
+        "",
+        ...plan.uncertaintyPolicy.map((item) => `- ${item}`),
+        "",
+        "## Roles",
+        "",
+        ...plan.roles.flatMap((role) => [
+            `### ${role.role}`,
+            "",
+            `- Subagent type: \`${role.subagentType}\``,
+            `- Active: ${role.active ? "yes" : "no"}`,
+            `- Activation: ${role.activation}`,
+            `- Route: \`${role.route}\``,
+            `- Reason: ${role.reason}`,
+            `- Owns: ${role.owns.map((item) => `\`${item}\``).join(", ")}`,
+            `- Does not own: ${role.doesNotOwn.map((item) => `\`${item}\``).join(", ")}`,
+            `- Inputs: ${role.inputs.length === 0 ? "none" : role.inputs.map((item) => `\`${item}\``).join(", ")}`,
+            `- Write scope: ${role.writeScope.map((item) => `\`${item}\``).join(", ")}`,
+            `- Outputs: ${role.outputs.length === 0 ? "none" : role.outputs.map((item) => `\`${item}\``).join(", ")}`,
+            `- Evidence required: ${role.evidenceRequired.map((item) => `\`${item}\``).join(", ")}`,
+            `- Forbidden decisions: ${role.forbiddenDecisions.map((item) => `\`${item}\``).join(", ")}`,
+            `- Handoff to: \`${role.handoffTo}\``,
+            `- Stop condition: ${role.stopCondition}`,
+            "",
+        ]),
+    ].join("\n");
+}
+function normalizeStage(value) {
+    return safeSlug(value) || "prepare";
+}
+function normalizeList(values) {
+    return unique(values.map(safeSlug));
+}
+function safeSlug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function unique(values) {
+    return [...new Set(values.filter(isString))];
+}
+function isString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function stringList(value) {
+    if (typeof value === "string" && value.trim().length > 0)
+        return [value.trim()];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter(isString).map((item) => item.trim());
+}
+function booleanValue(value) {
+    return value === true;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function createStaffingRunId(now = new Date()) {
+    return now.toISOString().replace(/[:.]/g, "-");
+}
+//# sourceMappingURL=staffing-plan.js.map