ex-workflow 0.0.0-stage → 0.2.0-stage

package/dist/types.d.cts

@@ -0,0 +1,330 @@
+type ItemType = "epic" | "story" | "task" | "bug" | "change-request" | "deliverable" | "question";
+type ItemStatus = "todo" | "in_progress" | "blocked" | "review" | "awaiting_human" | "done" | "dropped";
+type ClassOfService = "expedite" | "fixed-date" | "standard" | "intangible";
+interface Evidence {
+    kind: string;
+    ref: string;
+    by: string;
+    at: string;
+}
+interface Blocker {
+    id: string;
+    reason: string;
+    owner: string;
+    raisedAt: string;
+    clearedAt?: string;
+}
+interface Transition {
+    from: {
+        stage: string;
+        status: ItemStatus;
+    };
+    to: {
+        stage: string;
+        status: ItemStatus;
+    };
+    at: string;
+    by: string;
+}
+interface WorkItem {
+    id: string;
+    type: ItemType;
+    title: string;
+    description?: string;
+    dependsOn: string[];
+    priority?: number;
+    weight?: number;
+    deadline?: string;
+    classOfService?: ClassOfService;
+    stage: string;
+    status: ItemStatus;
+    role?: string;
+    parent?: string;
+    acceptance: string[];
+    evidence: Evidence[];
+    blockers: Blocker[];
+    transitions: Transition[];
+    iteration?: string;
+    traces?: string[];
+    tags?: string[];
+    /** bug / change-request: ids of items whose finished work this invalidates */
+    affects?: string[];
+}
+/** Fields a caller supplies to addItem; the rest are defaulted. */
+type NewItem = Pick<WorkItem, "id" | "title"> & Partial<Omit<WorkItem, "id" | "title" | "stage" | "status" | "evidence" | "blockers" | "transitions">> & {
+    stage?: string;
+};
+type Policy = {
+    kind: "evidence";
+    evidenceKind: string;
+} | {
+    kind: "acceptance-written";
+} | {
+    kind: "estimate-present";
+} | {
+    kind: "no-open-blockers";
+} | {
+    kind: "dependencies-done";
+} | {
+    kind: "custom";
+    id: string;
+    description: string;
+};
+type GateRequirement = "human" | {
+    capability: string;
+};
+interface Gate {
+    id: string;
+    requires: GateRequirement[];
+    evidence: string[];
+    onFail: {
+        action: "block";
+    } | {
+        action: "return-to";
+        stage: string;
+    };
+}
+interface Stage {
+    id: string;
+    name: string;
+    wipLimit?: number;
+    entryPolicy: Policy[];
+    exitPolicy: Policy[];
+    gate?: Gate;
+    commitmentPoint?: boolean;
+    deliveryPoint?: boolean;
+    /** Items entering this stage wait for a reviewer (status "review") instead of "todo". */
+    review?: boolean;
+}
+interface Budget {
+    tokens?: number;
+    turns?: number;
+    wallclockMs?: number;
+}
+interface Iteration {
+    id: string;
+    goal: string;
+    budget: Budget;
+    spent: Required<Budget>;
+    startedAt: string;
+    endedAt?: string;
+    committed: string[];
+    carryover: string[];
+    outcome?: "completed" | "cancelled";
+    /** Budget is exhausted; in-flight items may finish, nothing new is dispatched. */
+    closing?: boolean;
+}
+type ModelTier = "small" | "medium" | "large";
+type Capability = "order-backlog" | "define-acceptance" | "facilitate" | "deliver" | "review" | "verify" | "approve-gate" | "manage-flow" | "control-change" | "escalate";
+interface Role {
+    id: string;
+    name: string;
+    modelTier: ModelTier;
+    resourceClass?: string;
+    maxConcurrent?: number;
+    capabilities: Capability[];
+    canApprove: string[];
+    inputs: string[];
+    outputs: string[];
+    do_not: string[];
+    constraints?: string[];
+}
+type Verdict = "done" | "blocked" | "needs-review" | "rework" | "escalate";
+interface Handoff {
+    item: string;
+    role: string;
+    produced: Array<{
+        kind: string;
+        ref: string;
+    }>;
+    notes: string;
+    do_not: string[];
+    open_questions: string[];
+    verdict?: Verdict;
+    /** new work discovered while doing this item; lands in the FIRST stage (backlog), never in the iteration */
+    follow_ups?: NewItem[];
+    /** raised by the worker the moment it happens, e.g. "spec was vague here" */
+    lessons?: Array<{
+        text: string;
+        scope: Lesson["scope"];
+    }>;
+}
+interface Accounting {
+    item: string;
+    role: string;
+    model: string;
+    tokensIn: number;
+    tokensOut: number;
+    durationMs: number;
+    startedAt: string;
+    endedAt: string;
+}
+interface Event {
+    seq: number;
+    at: string;
+    type: string;
+    by: string;
+    payload: unknown;
+}
+interface PendingHuman {
+    id: string;
+    kind: "gate" | "decision";
+    item?: string;
+    gate?: string;
+    question: string;
+    raisedAt: string;
+}
+type LessonChange = {
+    kind: "agreement";
+    text: string;
+} | {
+    kind: "dod";
+    policy: Policy;
+} | {
+    kind: "backlog";
+    item: NewItem;
+} | {
+    kind: "skill";
+    note: string;
+};
+interface Lesson {
+    id: string;
+    at: string;
+    text: string;
+    scope: "policy" | "skill" | "memory" | "spec" | "review";
+    status: "raised" | "adopted" | "dismissed";
+    from?: string;
+    item?: string;
+    suggestedChange?: LessonChange;
+}
+interface Phase {
+    id: string;
+    name: string;
+    deliverables: string[];
+    gate: Gate;
+    status: "pending" | "open" | "baselined" | "reopened";
+}
+interface Baseline {
+    phase: string;
+    version: number;
+    at: string;
+    approvedBy: string[];
+    itemSnapshot: Record<string, WorkItem>;
+}
+type MethodologyName = "scrum" | "kanban" | "waterfall";
+interface WorkflowState {
+    version: 1;
+    methodology: MethodologyName;
+    config: unknown;
+    items: Record<string, WorkItem>;
+    stages: Stage[];
+    roles: Record<string, Role>;
+    iterations: Iteration[];
+    phases?: Phase[];
+    baseline?: Baseline;
+    events: Event[];
+    accounting: Accounting[];
+    pending: PendingHuman[];
+    lessons: Lesson[];
+    /** adopted working agreements; synthesizeBrief appends them to invariants */
+    agreements: string[];
+}
+interface Action {
+    type: string;
+    by: string;
+    payload?: unknown;
+}
+interface Violation {
+    rule: string;
+    severity: "error" | "warning";
+    item?: string;
+    message: string;
+    fix: string;
+}
+interface Rule {
+    id: string;
+    severity: "error" | "warning";
+    check(state: WorkflowState, action: Action): Violation[];
+}
+interface ApplyResult {
+    state: WorkflowState;
+    warnings: Violation[];
+}
+interface Brief {
+    item: WorkItem;
+    role: Role;
+    modelTier: ModelTier;
+    invariants: string[];
+    do_not: string[];
+    acceptance: string[];
+    upstream: Array<{
+        item: string;
+        produced: Handoff["produced"];
+        notes: string;
+    }>;
+    /** earlier completions of THIS item (rework feedback) */
+    priorHandoffs: Array<{
+        role: string;
+        verdict: Verdict;
+        notes: string;
+        produced: Handoff["produced"];
+        at: string;
+    }>;
+    /** open bug/change-request items whose `affects` touches this item or its dependsOn */
+    relatedBugs: Array<{
+        id: string;
+        title: string;
+        affects: string[];
+    }>;
+    budgetRemaining: Budget;
+    gateAhead?: Gate;
+}
+type CoreTerm = "backlog" | "item" | "stage" | "iteration" | "increment" | "ceremony" | "gate";
+type CeremonyInput = {
+    by: string;
+    now?: string;
+} & Record<string, unknown>;
+type Ceremony = (state: WorkflowState, input: CeremonyInput) => ApplyResult;
+interface PlannerOptions {
+    schedulerMode: "level" | "throughput";
+    /** Stage a todo item is pulled into when dispatched; a function decides per item; omitted/undefined = stay in its current stage. */
+    dispatchStage?: string | ((item: WorkItem) => string | undefined);
+    concurrencyCap?: number;
+    fairnessPolicy?: "none" | "aging";
+    maxDeferralRounds?: number;
+    deadlineStrategy?: "earliest-first" | "latest-first";
+    weightStrategy?: "higher-first" | "lower-first";
+    /** Priority the planner orders by; defaults to item.priority. */
+    priorityOf?(item: WorkItem): number | undefined;
+    /** Orders items of equal priority (after deadline/weight strategies); e.g. class of service, then age. */
+    tieBreaker?(a: WorkItem, b: WorkItem): number;
+    /** Statuses that occupy a stage's wipLimit slot; default ["in_progress"]. */
+    wipCounts?: ItemStatus[];
+    /** Per-item replacement for the target stage's wipLimit (e.g. an expedite bypass); undefined = no limit. */
+    wipLimitOf?(stage: Stage, item: WorkItem): number | undefined;
+}
+interface Methodology<C = unknown> {
+    name: MethodologyName;
+    vocabulary: Record<CoreTerm, string>;
+    validateConfig(config: unknown): C;
+    defaultStages(config: C): Stage[];
+    defaultRoles(config: C): Role[];
+    requiredCapabilities: Capability[];
+    exclusiveCapabilities: Capability[];
+    plannerOptions(state: WorkflowState): PlannerOptions;
+    candidates(state: WorkflowState): WorkItem[];
+    invariants(state: WorkflowState, item: WorkItem): string[];
+    ceremonies: Record<string, Ceremony>;
+    rules: Rule[];
+    metrics(state: WorkflowState): Record<string, number | number[] | Record<string, number>>;
+    humanDefaults: {
+        gates: "all" | "none" | string[];
+    };
+    /** Called after complete(); lets the methodology react (e.g. close a sprint when the budget is gone). */
+    afterComplete?(state: WorkflowState, itemId: string, now: string): WorkflowState;
+    /** Methodology-specific status for hosts (e.g. cadences due); printed by `exwf status`. */
+    report?(state: WorkflowState): Record<string, unknown>;
+}
+type ErrorCode = "unknown-item" | "duplicate-item" | "unknown-role" | "duplicate-role" | "unknown-stage" | "missing-capability" | "exclusive-capability" | "role-has-open-items" | "invalid-transition" | "policy-unmet" | "gate-unmet" | "conflict-of-interest" | "handoff-invalid" | "accounting-invalid" | "rule-violation" | "planner-error" | "no-op" | "unknown-pending" | "unknown-ceremony" | "state-version" | "config-invalid" | "budget-exhausted" | "invalid-input";
+
+export type { Accounting, Action, ApplyResult, Baseline, Blocker, Brief, Budget, Capability, Ceremony, CeremonyInput, ClassOfService, CoreTerm, ErrorCode, Event, Evidence, Gate, GateRequirement, Handoff, ItemStatus, ItemType, Iteration, Lesson, LessonChange, Methodology, MethodologyName, ModelTier, NewItem, PendingHuman, Phase, PlannerOptions, Policy, Role, Rule, Stage, Transition, Verdict, Violation, WorkItem, WorkflowState };

package/dist/types.d.ts

@@ -0,0 +1,330 @@
+type ItemType = "epic" | "story" | "task" | "bug" | "change-request" | "deliverable" | "question";
+type ItemStatus = "todo" | "in_progress" | "blocked" | "review" | "awaiting_human" | "done" | "dropped";
+type ClassOfService = "expedite" | "fixed-date" | "standard" | "intangible";
+interface Evidence {
+    kind: string;
+    ref: string;
+    by: string;
+    at: string;
+}
+interface Blocker {
+    id: string;
+    reason: string;
+    owner: string;
+    raisedAt: string;
+    clearedAt?: string;
+}
+interface Transition {
+    from: {
+        stage: string;
+        status: ItemStatus;
+    };
+    to: {
+        stage: string;
+        status: ItemStatus;
+    };
+    at: string;
+    by: string;
+}
+interface WorkItem {
+    id: string;
+    type: ItemType;
+    title: string;
+    description?: string;
+    dependsOn: string[];
+    priority?: number;
+    weight?: number;
+    deadline?: string;
+    classOfService?: ClassOfService;
+    stage: string;
+    status: ItemStatus;
+    role?: string;
+    parent?: string;
+    acceptance: string[];
+    evidence: Evidence[];
+    blockers: Blocker[];
+    transitions: Transition[];
+    iteration?: string;
+    traces?: string[];
+    tags?: string[];
+    /** bug / change-request: ids of items whose finished work this invalidates */
+    affects?: string[];
+}
+/** Fields a caller supplies to addItem; the rest are defaulted. */
+type NewItem = Pick<WorkItem, "id" | "title"> & Partial<Omit<WorkItem, "id" | "title" | "stage" | "status" | "evidence" | "blockers" | "transitions">> & {
+    stage?: string;
+};
+type Policy = {
+    kind: "evidence";
+    evidenceKind: string;
+} | {
+    kind: "acceptance-written";
+} | {
+    kind: "estimate-present";
+} | {
+    kind: "no-open-blockers";
+} | {
+    kind: "dependencies-done";
+} | {
+    kind: "custom";
+    id: string;
+    description: string;
+};
+type GateRequirement = "human" | {
+    capability: string;
+};
+interface Gate {
+    id: string;
+    requires: GateRequirement[];
+    evidence: string[];
+    onFail: {
+        action: "block";
+    } | {
+        action: "return-to";
+        stage: string;
+    };
+}
+interface Stage {
+    id: string;
+    name: string;
+    wipLimit?: number;
+    entryPolicy: Policy[];
+    exitPolicy: Policy[];
+    gate?: Gate;
+    commitmentPoint?: boolean;
+    deliveryPoint?: boolean;
+    /** Items entering this stage wait for a reviewer (status "review") instead of "todo". */
+    review?: boolean;
+}
+interface Budget {
+    tokens?: number;
+    turns?: number;
+    wallclockMs?: number;
+}
+interface Iteration {
+    id: string;
+    goal: string;
+    budget: Budget;
+    spent: Required<Budget>;
+    startedAt: string;
+    endedAt?: string;
+    committed: string[];
+    carryover: string[];
+    outcome?: "completed" | "cancelled";
+    /** Budget is exhausted; in-flight items may finish, nothing new is dispatched. */
+    closing?: boolean;
+}
+type ModelTier = "small" | "medium" | "large";
+type Capability = "order-backlog" | "define-acceptance" | "facilitate" | "deliver" | "review" | "verify" | "approve-gate" | "manage-flow" | "control-change" | "escalate";
+interface Role {
+    id: string;
+    name: string;
+    modelTier: ModelTier;
+    resourceClass?: string;
+    maxConcurrent?: number;
+    capabilities: Capability[];
+    canApprove: string[];
+    inputs: string[];
+    outputs: string[];
+    do_not: string[];
+    constraints?: string[];
+}
+type Verdict = "done" | "blocked" | "needs-review" | "rework" | "escalate";
+interface Handoff {
+    item: string;
+    role: string;
+    produced: Array<{
+        kind: string;
+        ref: string;
+    }>;
+    notes: string;
+    do_not: string[];
+    open_questions: string[];
+    verdict?: Verdict;
+    /** new work discovered while doing this item; lands in the FIRST stage (backlog), never in the iteration */
+    follow_ups?: NewItem[];
+    /** raised by the worker the moment it happens, e.g. "spec was vague here" */
+    lessons?: Array<{
+        text: string;
+        scope: Lesson["scope"];
+    }>;
+}
+interface Accounting {
+    item: string;
+    role: string;
+    model: string;
+    tokensIn: number;
+    tokensOut: number;
+    durationMs: number;
+    startedAt: string;
+    endedAt: string;
+}
+interface Event {
+    seq: number;
+    at: string;
+    type: string;
+    by: string;
+    payload: unknown;
+}
+interface PendingHuman {
+    id: string;
+    kind: "gate" | "decision";
+    item?: string;
+    gate?: string;
+    question: string;
+    raisedAt: string;
+}
+type LessonChange = {
+    kind: "agreement";
+    text: string;
+} | {
+    kind: "dod";
+    policy: Policy;
+} | {
+    kind: "backlog";
+    item: NewItem;
+} | {
+    kind: "skill";
+    note: string;
+};
+interface Lesson {
+    id: string;
+    at: string;
+    text: string;
+    scope: "policy" | "skill" | "memory" | "spec" | "review";
+    status: "raised" | "adopted" | "dismissed";
+    from?: string;
+    item?: string;
+    suggestedChange?: LessonChange;
+}
+interface Phase {
+    id: string;
+    name: string;
+    deliverables: string[];
+    gate: Gate;
+    status: "pending" | "open" | "baselined" | "reopened";
+}
+interface Baseline {
+    phase: string;
+    version: number;
+    at: string;
+    approvedBy: string[];
+    itemSnapshot: Record<string, WorkItem>;
+}
+type MethodologyName = "scrum" | "kanban" | "waterfall";
+interface WorkflowState {
+    version: 1;
+    methodology: MethodologyName;
+    config: unknown;
+    items: Record<string, WorkItem>;
+    stages: Stage[];
+    roles: Record<string, Role>;
+    iterations: Iteration[];
+    phases?: Phase[];
+    baseline?: Baseline;
+    events: Event[];
+    accounting: Accounting[];
+    pending: PendingHuman[];
+    lessons: Lesson[];
+    /** adopted working agreements; synthesizeBrief appends them to invariants */
+    agreements: string[];
+}
+interface Action {
+    type: string;
+    by: string;
+    payload?: unknown;
+}
+interface Violation {
+    rule: string;
+    severity: "error" | "warning";
+    item?: string;
+    message: string;
+    fix: string;
+}
+interface Rule {
+    id: string;
+    severity: "error" | "warning";
+    check(state: WorkflowState, action: Action): Violation[];
+}
+interface ApplyResult {
+    state: WorkflowState;
+    warnings: Violation[];
+}
+interface Brief {
+    item: WorkItem;
+    role: Role;
+    modelTier: ModelTier;
+    invariants: string[];
+    do_not: string[];
+    acceptance: string[];
+    upstream: Array<{
+        item: string;
+        produced: Handoff["produced"];
+        notes: string;
+    }>;
+    /** earlier completions of THIS item (rework feedback) */
+    priorHandoffs: Array<{
+        role: string;
+        verdict: Verdict;
+        notes: string;
+        produced: Handoff["produced"];
+        at: string;
+    }>;
+    /** open bug/change-request items whose `affects` touches this item or its dependsOn */
+    relatedBugs: Array<{
+        id: string;
+        title: string;
+        affects: string[];
+    }>;
+    budgetRemaining: Budget;
+    gateAhead?: Gate;
+}
+type CoreTerm = "backlog" | "item" | "stage" | "iteration" | "increment" | "ceremony" | "gate";
+type CeremonyInput = {
+    by: string;
+    now?: string;
+} & Record<string, unknown>;
+type Ceremony = (state: WorkflowState, input: CeremonyInput) => ApplyResult;
+interface PlannerOptions {
+    schedulerMode: "level" | "throughput";
+    /** Stage a todo item is pulled into when dispatched; a function decides per item; omitted/undefined = stay in its current stage. */
+    dispatchStage?: string | ((item: WorkItem) => string | undefined);
+    concurrencyCap?: number;
+    fairnessPolicy?: "none" | "aging";
+    maxDeferralRounds?: number;
+    deadlineStrategy?: "earliest-first" | "latest-first";
+    weightStrategy?: "higher-first" | "lower-first";
+    /** Priority the planner orders by; defaults to item.priority. */
+    priorityOf?(item: WorkItem): number | undefined;
+    /** Orders items of equal priority (after deadline/weight strategies); e.g. class of service, then age. */
+    tieBreaker?(a: WorkItem, b: WorkItem): number;
+    /** Statuses that occupy a stage's wipLimit slot; default ["in_progress"]. */
+    wipCounts?: ItemStatus[];
+    /** Per-item replacement for the target stage's wipLimit (e.g. an expedite bypass); undefined = no limit. */
+    wipLimitOf?(stage: Stage, item: WorkItem): number | undefined;
+}
+interface Methodology<C = unknown> {
+    name: MethodologyName;
+    vocabulary: Record<CoreTerm, string>;
+    validateConfig(config: unknown): C;
+    defaultStages(config: C): Stage[];
+    defaultRoles(config: C): Role[];
+    requiredCapabilities: Capability[];
+    exclusiveCapabilities: Capability[];
+    plannerOptions(state: WorkflowState): PlannerOptions;
+    candidates(state: WorkflowState): WorkItem[];
+    invariants(state: WorkflowState, item: WorkItem): string[];
+    ceremonies: Record<string, Ceremony>;
+    rules: Rule[];
+    metrics(state: WorkflowState): Record<string, number | number[] | Record<string, number>>;
+    humanDefaults: {
+        gates: "all" | "none" | string[];
+    };
+    /** Called after complete(); lets the methodology react (e.g. close a sprint when the budget is gone). */
+    afterComplete?(state: WorkflowState, itemId: string, now: string): WorkflowState;
+    /** Methodology-specific status for hosts (e.g. cadences due); printed by `exwf status`. */
+    report?(state: WorkflowState): Record<string, unknown>;
+}
+type ErrorCode = "unknown-item" | "duplicate-item" | "unknown-role" | "duplicate-role" | "unknown-stage" | "missing-capability" | "exclusive-capability" | "role-has-open-items" | "invalid-transition" | "policy-unmet" | "gate-unmet" | "conflict-of-interest" | "handoff-invalid" | "accounting-invalid" | "rule-violation" | "planner-error" | "no-op" | "unknown-pending" | "unknown-ceremony" | "state-version" | "config-invalid" | "budget-exhausted" | "invalid-input";
+
+export type { Accounting, Action, ApplyResult, Baseline, Blocker, Brief, Budget, Capability, Ceremony, CeremonyInput, ClassOfService, CoreTerm, ErrorCode, Event, Evidence, Gate, GateRequirement, Handoff, ItemStatus, ItemType, Iteration, Lesson, LessonChange, Methodology, MethodologyName, ModelTier, NewItem, PendingHuman, Phase, PlannerOptions, Policy, Role, Rule, Stage, Transition, Verdict, Violation, WorkItem, WorkflowState };

package/dist/types.mjs

@@ -0,0 +1,2 @@
+import'./chunk-KIQOUUEZ.mjs';//# sourceMappingURL=types.mjs.map
+//# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"types.mjs"}