@captain_z/zsk 1.8.1 → 1.8.3

package/dist/core/staffing-plan.d.ts

@@ -0,0 +1,212 @@
+import { type ProjectConfig } from "./config.js";
+import { type GateAssessment, type ReviewGateMode } from "./stage-quality.js";
+export type StaffingPlanOptions = {
+    stage?: string;
+    skill?: string;
+    surface?: string;
+    runId?: string;
+    module?: string;
+    issue?: string;
+    reviewTarget?: string;
+    gateThreshold?: number;
+    acceptRisk?: string;
+};
+export type StaffingRole = {
+    role: string;
+    subagentType: string;
+    stage: string;
+    skill: string;
+    active: boolean;
+    route: string;
+    activation: string;
+    reason: string;
+    owns: string[];
+    doesNotOwn: string[];
+    inputs: string[];
+    writeScope: string[];
+    outputs: string[];
+    evidenceRequired: string[];
+    forbiddenDecisions: string[];
+    handoffTo: string;
+    stopCondition: string;
+    mustAskWhen: string[];
+};
+export type StaffingOrchestration = {
+    requestedSurface: string;
+    selectedSurface: "auto" | "native" | "omx" | "sequential";
+    mode: string;
+    scale: string;
+    dispatchRecommended: boolean;
+    laneIndependence: "parallel-capable" | "sequential";
+    reason: string;
+    fallbackOrder: string[];
+    maxParallelLanes: number;
+    overDispatchGuards: string[];
+};
+export type StaffingEmitPacket = {
+    event: "zsk.subagent.request";
+    version: 1;
+    payload: {
+        runId: string;
+        packetId: string;
+        stage: string;
+        skill: string;
+        role: string;
+        subagentType: string;
+        active: boolean;
+        route: string;
+        activation: string;
+        prompt: string;
+        inputs: string[];
+        writeScope: string[];
+        outputs: string[];
+        evidenceRequired: string[];
+        forbiddenDecisions: string[];
+        handoffTo: string;
+        stopCondition: string;
+        constraints: string[];
+        durability: {
+            ledgerPath: string;
+            statusPath: string;
+            status: "pending";
+            attempt: number;
+            createdAt: string;
+            heartbeatIntervalMs: number;
+            staleAfterMs: number;
+            deadlineAt: string;
+            maxAttempts: number;
+            onTimeout: "fallback-to-leader-sequential";
+            resumeHint: string;
+        };
+    };
+};
+export type StaffingPacketStatus = {
+    packetId: string;
+    runId: string;
+    stage: string;
+    skill: string;
+    role: string;
+    subagentType: string;
+    route: string;
+    status: "pending" | "running" | "completed" | "blocked" | "failed" | "waived" | "stale";
+    attempt: number;
+    createdAt: string;
+    updatedAt: string;
+    lastHeartbeatAt: string;
+    deadlineAt: string;
+    staleAfterMs: number;
+    maxAttempts: number;
+    fallbackRoute: "leader-sequential";
+    statusPath: string;
+    evidence: string[];
+    blocker?: string;
+};
+export type StaffingEmitLedger = {
+    version: 1;
+    runId: string;
+    stage: string;
+    skill: string;
+    ledgerPath: string;
+    packetStatusDir: string;
+    timeoutPolicy: {
+        heartbeatIntervalMs: number;
+        staleAfterMs: number;
+        maxAttempts: number;
+        onTimeout: "fallback-to-leader-sequential";
+    };
+    packets: StaffingPacketStatus[];
+};
+export type StaffingStageGate = {
+    runId: string;
+    stage: string;
+    module?: string;
+    reviewTarget?: string;
+    reviewMode?: ReviewGateMode;
+    status: GateAssessment["status"];
+    decision: GateAssessment["decision"];
+    score: number;
+    threshold: number;
+    blockers: string[];
+    gaps: string[];
+    assessmentPath: string;
+    markdownPath: string;
+    waiverPath?: string;
+};
+export type StaffingPlan = {
+    runId: string;
+    stage: string;
+    skill: string;
+    module?: string;
+    reviewTarget?: string;
+    reviewMode?: ReviewGateMode;
+    surface: string;
+    stageGate?: StaffingStageGate;
+    orchestration: StaffingOrchestration;
+    uncertaintyPolicy: string[];
+    roles: StaffingRole[];
+    emitPackets: StaffingEmitPacket[];
+};
+export type StaffingPlanArtifacts = {
+    runId: string;
+    dir: string;
+    jsonPath: string;
+    markdownPath: string;
+    emitPath: string;
+    ledgerPath: string;
+    packetStatusDir: string;
+};
+export type StaffingPlanBundle = {
+    artifacts: StaffingPlanArtifacts;
+    plan: StaffingPlan;
+    markdown: string;
+    emitJsonl: string;
+    ledger: StaffingEmitLedger;
+};
+export type StaffingInspectOptions = {
+    runId?: string;
+    now?: Date;
+};
+export type StaffingInspectResult = {
+    runId: string;
+    ledgerPath: string;
+    total: number;
+    stale: number;
+    pending: number;
+    running: number;
+    completed: number;
+    blocked: number;
+    failed: number;
+    waived: number;
+};
+type RoleContract = {
+    owns: string[];
+    doesNotOwn: string[];
+    outputs: string[];
+    evidenceRequired: string[];
+    forbiddenDecisions: string[];
+    stopCondition: string;
+};
+type RolePoolRole = {
+    role: string;
+    subagentType?: string;
+    reason?: string;
+    stages: string[];
+    skills: string[];
+    lanes: string[];
+    required: boolean;
+    remoteSources: boolean;
+    activation?: string;
+    extraInputs: string[];
+    writeScope: string[];
+    outputs: string[];
+    evidenceRequired: string[];
+    contract?: Partial<RoleContract>;
+};
+type RolePool = {
+    roles: Record<string, RolePoolRole>;
+};
+export declare function writeStaffingPlan(target: string, config: ProjectConfig, opts?: StaffingPlanOptions): Promise<StaffingPlanBundle>;
+export declare function buildStaffingPlan(target: string, config: ProjectConfig, opts?: StaffingPlanOptions, rolePool?: RolePool): StaffingPlanBundle;
+export declare function inspectStaffingRun(target: string, config: ProjectConfig, opts?: StaffingInspectOptions): Promise<StaffingInspectResult>;
+export declare function createStaffingRunId(now?: Date): string;
+export {};