@lucern/contracts 0.1.1-alpha.1 → 0.1.2-alpha.2

package/dist/workflow-runtime.contract.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Workflow Runtime Contract v1
+ *
+ * Canonical TypeScript contract for Lucern's graph-local workflow runtime.
+ * WF-1 defines the typed substrate for:
+ *   - workflow definitions and run receipts
+ *   - action mutation tiering and approval expectations
+ *   - hooks over worktree/question/evidence/inbox events
+ *   - output unions for domain-specific artifacts
+ *   - deterministic integrity checks and operational metadata
+ *
+ * BREAKING CHANGE RULES:
+ *   - Adding optional fields is NON-breaking
+ *   - Removing fields or renaming enum values is BREAKING
+ *   - Reclassifying a mutation tier is BREAKING
+ *   - Changing canonical workflow IDs is BREAKING
+ */
+declare const WORKFLOW_RUNTIME_SCHEMA_VERSION: "1.0.0";
+declare const WORKFLOW_MUTATION_TIERS: readonly ["read_only", "low_risk_write", "high_risk_write"];
+type WorkflowMutationTier = (typeof WORKFLOW_MUTATION_TIERS)[number];
+declare const WORKFLOW_APPROVAL_MODES: readonly ["none", "audit_only", "human_required", "auto_approve"];
+type WorkflowApprovalMode = (typeof WORKFLOW_APPROVAL_MODES)[number];
+declare const DEFAULT_TIER_APPROVAL_MODE: Readonly<Record<WorkflowMutationTier, WorkflowApprovalMode>>;
+declare const WORKFLOW_ACTION_KINDS: readonly ["context_pack", "integrity_check", "lucern_tool", "report_compile", "brief_publish", "notification", "custom"];
+type WorkflowActionKind = (typeof WORKFLOW_ACTION_KINDS)[number];
+declare const WORKFLOW_HOOK_EVENTS: readonly ["schedule.tick", "worktree.activated", "worktree.completed", "question.created", "question.answered", "evidence.appended", "inbox.item_created"];
+type WorkflowHookEvent = (typeof WORKFLOW_HOOK_EVENTS)[number];
+declare const WORKFLOW_OUTPUT_KINDS: readonly ["engineering_brief", "research_memo", "strategy_artifact", "inbox_summary", "pipeline_brief", "structured_payload"];
+type WorkflowOutputKind = (typeof WORKFLOW_OUTPUT_KINDS)[number];
+declare const WORKFLOW_RUN_STATUSES: readonly ["queued", "running", "awaiting_approval", "completed", "failed", "cancelled"];
+type WorkflowRunStatus = (typeof WORKFLOW_RUN_STATUSES)[number];
+declare const WORKFLOW_TRIGGER_KINDS: readonly ["manual", "schedule", "hook"];
+type WorkflowTriggerKind = (typeof WORKFLOW_TRIGGER_KINDS)[number];
+declare const WORKFLOW_PROOF_ARTIFACT_KINDS: readonly ["report", "brief", "artifact", "dashboard", "test_evidence"];
+type WorkflowProofArtifactKind = (typeof WORKFLOW_PROOF_ARTIFACT_KINDS)[number];
+declare const WORKFLOW_STAFFING_HINTS: readonly ["solo", "backend+tests", "fullstack", "mcp+tests"];
+type WorkflowStaffingHint = (typeof WORKFLOW_STAFFING_HINTS)[number];
+declare const WORKFLOW_AUTO_FIX_MODES: readonly ["disabled", "dry_run", "safe", "aggressive"];
+type WorkflowAutoFixMode = (typeof WORKFLOW_AUTO_FIX_MODES)[number];
+declare const WORKFLOW_INTEGRITY_CHECKS: readonly ["null_dependency_refs", "superseded_blockers", "band_order_inconsistency", "sparse_shaping", "failed_completed_gate"];
+type WorkflowIntegrityCheckId = (typeof WORKFLOW_INTEGRITY_CHECKS)[number];
+type WorkflowProofArtifact = {
+    kind: WorkflowProofArtifactKind;
+    label: string;
+    required?: boolean;
+    sourceRef?: string;
+};
+type WorkflowAutoFixPolicy = {
+    mode: WorkflowAutoFixMode;
+    maxActionsPerRun?: number;
+    permittedMutationTiers?: WorkflowMutationTier[];
+    requireAuditTrail?: boolean;
+    escalationGate?: string;
+};
+declare const DEFAULT_WORKFLOW_AUTO_FIX_POLICY: WorkflowAutoFixPolicy;
+type WorkflowApprovalPolicy = {
+    mode: WorkflowApprovalMode;
+    approvalGate?: string;
+    autoApprovePolicyKey?: string;
+    rationaleRequired?: boolean;
+};
+type WorkflowOutputBase = {
+    outputId: string;
+    kind: WorkflowOutputKind;
+    title: string;
+    summary: string;
+    generatedAt?: number;
+};
+type EngineeringBriefOutput = WorkflowOutputBase & {
+    kind: "engineering_brief";
+    sections: Array<{
+        heading: string;
+        body: string;
+    }>;
+    touchedPaths?: string[];
+};
+type ResearchMemoOutput = WorkflowOutputBase & {
+    kind: "research_memo";
+    claims: string[];
+    evidenceRefs?: string[];
+};
+type StrategyArtifactOutput = WorkflowOutputBase & {
+    kind: "strategy_artifact";
+    recommendations: string[];
+    decisionWindow?: string;
+};
+type InboxSummaryOutput = WorkflowOutputBase & {
+    kind: "inbox_summary";
+    channel: "developer_portal" | "chat" | "ops";
+    inboxTitle: string;
+    inboxBody: string;
+};
+type PipelineBriefOutput = WorkflowOutputBase & {
+    kind: "pipeline_brief";
+    hingeWorktreeId?: string;
+    groupedBlockers: Array<{
+        blocker: string;
+        blockedWorktreeIds: string[];
+    }>;
+};
+type StructuredPayloadOutput = WorkflowOutputBase & {
+    kind: "structured_payload";
+    payload: Record<string, unknown>;
+};
+type WorkflowOutputContract = EngineeringBriefOutput | ResearchMemoOutput | StrategyArtifactOutput | InboxSummaryOutput | PipelineBriefOutput | StructuredPayloadOutput;
+type WorkflowActionContract = {
+    actionId: string;
+    kind: WorkflowActionKind;
+    title: string;
+    description: string;
+    mutationTier: WorkflowMutationTier;
+    toolName?: string;
+    produces?: WorkflowOutputKind[];
+    idempotent?: boolean;
+    approval: WorkflowApprovalPolicy;
+};
+type WorkflowHookContract = {
+    hookId: string;
+    event: WorkflowHookEvent;
+    description: string;
+    condition?: string;
+    actionIds: string[];
+};
+type WorkflowTriggerContract = {
+    kind: "manual";
+    description?: string;
+} | {
+    kind: "schedule";
+    cadence: "hourly" | "daily" | "weekly";
+    timezone?: string;
+} | {
+    kind: "hook";
+    event: WorkflowHookEvent;
+};
+type WorkflowDefinitionV1 = {
+    workflowId: string;
+    version: typeof WORKFLOW_RUNTIME_SCHEMA_VERSION;
+    title: string;
+    description: string;
+    trigger: WorkflowTriggerContract;
+    staffingHint?: WorkflowStaffingHint;
+    proofArtifacts?: WorkflowProofArtifact[];
+    autoFixPolicy?: WorkflowAutoFixPolicy;
+    actions: readonly WorkflowActionContract[];
+    hooks?: readonly WorkflowHookContract[];
+    outputs: readonly WorkflowOutputKind[];
+    integrityChecks?: readonly WorkflowIntegrityCheckId[];
+};
+type WorkflowRunReceiptV1 = {
+    runId: string;
+    workflowId: string;
+    status: WorkflowRunStatus;
+    triggeredBy: WorkflowTriggerKind;
+    startedAt: number;
+    completedAt?: number;
+    outputKinds: WorkflowOutputKind[];
+    approvalsRequired?: number;
+};
+declare const NIGHTLY_RECONCILIATION_WORKFLOW_ID: "workflow.pipeline_reconciliation.v1";
+declare const MORNING_BRIEF_WORKFLOW_ID: "workflow.morning_brief.v1";
+declare const CANONICAL_WORKFLOW_DEFINITIONS: readonly WorkflowDefinitionV1[];
+
+export { CANONICAL_WORKFLOW_DEFINITIONS, DEFAULT_TIER_APPROVAL_MODE, DEFAULT_WORKFLOW_AUTO_FIX_POLICY, type EngineeringBriefOutput, type InboxSummaryOutput, MORNING_BRIEF_WORKFLOW_ID, NIGHTLY_RECONCILIATION_WORKFLOW_ID, type PipelineBriefOutput, type ResearchMemoOutput, type StrategyArtifactOutput, type StructuredPayloadOutput, WORKFLOW_ACTION_KINDS, WORKFLOW_APPROVAL_MODES, WORKFLOW_AUTO_FIX_MODES, WORKFLOW_HOOK_EVENTS, WORKFLOW_INTEGRITY_CHECKS, WORKFLOW_MUTATION_TIERS, WORKFLOW_OUTPUT_KINDS, WORKFLOW_PROOF_ARTIFACT_KINDS, WORKFLOW_RUNTIME_SCHEMA_VERSION, WORKFLOW_RUN_STATUSES, WORKFLOW_STAFFING_HINTS, WORKFLOW_TRIGGER_KINDS, type WorkflowActionContract, type WorkflowActionKind, type WorkflowApprovalMode, type WorkflowApprovalPolicy, type WorkflowAutoFixMode, type WorkflowAutoFixPolicy, type WorkflowDefinitionV1, type WorkflowHookContract, type WorkflowHookEvent, type WorkflowIntegrityCheckId, type WorkflowMutationTier, type WorkflowOutputBase, type WorkflowOutputContract, type WorkflowOutputKind, type WorkflowProofArtifact, type WorkflowProofArtifactKind, type WorkflowRunReceiptV1, type WorkflowRunStatus, type WorkflowStaffingHint, type WorkflowTriggerContract, type WorkflowTriggerKind };

package/dist/workflow-runtime.contract.js

@@ -0,0 +1,245 @@
+// src/workflow-runtime.contract.ts
+var WORKFLOW_RUNTIME_SCHEMA_VERSION = "1.0.0";
+var WORKFLOW_MUTATION_TIERS = [
+  "read_only",
+  "low_risk_write",
+  "high_risk_write"
+];
+var WORKFLOW_APPROVAL_MODES = [
+  "none",
+  "audit_only",
+  "human_required",
+  "auto_approve"
+];
+var DEFAULT_TIER_APPROVAL_MODE = {
+  read_only: "none",
+  low_risk_write: "audit_only",
+  high_risk_write: "human_required"
+};
+var WORKFLOW_ACTION_KINDS = [
+  "context_pack",
+  "integrity_check",
+  "lucern_tool",
+  "report_compile",
+  "brief_publish",
+  "notification",
+  "custom"
+];
+var WORKFLOW_HOOK_EVENTS = [
+  "schedule.tick",
+  "worktree.activated",
+  "worktree.completed",
+  "question.created",
+  "question.answered",
+  "evidence.appended",
+  "inbox.item_created"
+];
+var WORKFLOW_OUTPUT_KINDS = [
+  "engineering_brief",
+  "research_memo",
+  "strategy_artifact",
+  "inbox_summary",
+  "pipeline_brief",
+  "structured_payload"
+];
+var WORKFLOW_RUN_STATUSES = [
+  "queued",
+  "running",
+  "awaiting_approval",
+  "completed",
+  "failed",
+  "cancelled"
+];
+var WORKFLOW_TRIGGER_KINDS = [
+  "manual",
+  "schedule",
+  "hook"
+];
+var WORKFLOW_PROOF_ARTIFACT_KINDS = [
+  "report",
+  "brief",
+  "artifact",
+  "dashboard",
+  "test_evidence"
+];
+var WORKFLOW_STAFFING_HINTS = [
+  "solo",
+  "backend+tests",
+  "fullstack",
+  "mcp+tests"
+];
+var WORKFLOW_AUTO_FIX_MODES = [
+  "disabled",
+  "dry_run",
+  "safe",
+  "aggressive"
+];
+var WORKFLOW_INTEGRITY_CHECKS = [
+  "null_dependency_refs",
+  "superseded_blockers",
+  "band_order_inconsistency",
+  "sparse_shaping",
+  "failed_completed_gate"
+];
+var DEFAULT_WORKFLOW_AUTO_FIX_POLICY = {
+  mode: "disabled",
+  permittedMutationTiers: ["read_only"],
+  requireAuditTrail: true
+};
+var NIGHTLY_RECONCILIATION_WORKFLOW_ID = "workflow.pipeline_reconciliation.v1";
+var MORNING_BRIEF_WORKFLOW_ID = "workflow.morning_brief.v1";
+var CANONICAL_WORKFLOW_DEFINITIONS = [
+  {
+    workflowId: NIGHTLY_RECONCILIATION_WORKFLOW_ID,
+    version: WORKFLOW_RUNTIME_SCHEMA_VERSION,
+    title: "Nightly Pipeline Reconciliation",
+    description: "Runs deterministic integrity checks, compiles pipeline state, and emits an operator-facing reconciliation brief.",
+    trigger: {
+      kind: "schedule",
+      cadence: "daily",
+      timezone: "America/New_York"
+    },
+    staffingHint: "backend+tests",
+    proofArtifacts: [
+      {
+        kind: "report",
+        label: "Pipeline reconciliation report",
+        required: true
+      },
+      {
+        kind: "test_evidence",
+        label: "Integrity check receipt",
+        required: true
+      }
+    ],
+    autoFixPolicy: {
+      mode: "safe",
+      maxActionsPerRun: 5,
+      permittedMutationTiers: ["read_only", "low_risk_write"],
+      requireAuditTrail: true,
+      escalationGate: "gate:workflow-runtime-contract-live"
+    },
+    actions: [
+      {
+        actionId: "compile_context_pack",
+        kind: "context_pack",
+        title: "Compile pipeline context",
+        description: "Build the ranked context needed for deterministic checks.",
+        mutationTier: "read_only",
+        produces: ["structured_payload"],
+        idempotent: true,
+        approval: { mode: "none" }
+      },
+      {
+        actionId: "run_integrity_checks",
+        kind: "integrity_check",
+        title: "Run integrity checks",
+        description: "Evaluate dependency references, blockers, execution bands, shaping coverage, and completed gates.",
+        mutationTier: "read_only",
+        produces: ["structured_payload"],
+        idempotent: true,
+        approval: { mode: "none" }
+      },
+      {
+        actionId: "record_followup_questions",
+        kind: "lucern_tool",
+        title: "Record follow-up questions",
+        description: "Create or reopen operator-facing questions for integrity failures that require human review.",
+        mutationTier: "low_risk_write",
+        toolName: "create_question",
+        produces: ["pipeline_brief"],
+        approval: { mode: "audit_only", rationaleRequired: true }
+      },
+      {
+        actionId: "publish_reconciliation_brief",
+        kind: "brief_publish",
+        title: "Publish reconciliation brief",
+        description: "Emit an inbox-routed brief summarizing the nightly pipeline state and grouped blockers.",
+        mutationTier: "low_risk_write",
+        produces: ["pipeline_brief", "inbox_summary"],
+        approval: { mode: "audit_only" }
+      }
+    ],
+    hooks: [
+      {
+        hookId: "nightly-schedule",
+        event: "schedule.tick",
+        description: "Run once per nightly cadence.",
+        actionIds: [
+          "compile_context_pack",
+          "run_integrity_checks",
+          "record_followup_questions",
+          "publish_reconciliation_brief"
+        ]
+      }
+    ],
+    outputs: ["pipeline_brief", "inbox_summary", "structured_payload"],
+    integrityChecks: WORKFLOW_INTEGRITY_CHECKS
+  },
+  {
+    workflowId: MORNING_BRIEF_WORKFLOW_ID,
+    version: WORKFLOW_RUNTIME_SCHEMA_VERSION,
+    title: "Morning Brief",
+    description: "Compiles a developer-facing morning brief from graph state, overnight workflow outputs, and inbox routing preferences.",
+    trigger: {
+      kind: "schedule",
+      cadence: "daily",
+      timezone: "America/New_York"
+    },
+    staffingHint: "solo",
+    proofArtifacts: [
+      {
+        kind: "brief",
+        label: "Morning brief",
+        required: true
+      }
+    ],
+    autoFixPolicy: {
+      mode: "dry_run",
+      maxActionsPerRun: 1,
+      permittedMutationTiers: ["read_only", "low_risk_write"],
+      requireAuditTrail: true
+    },
+    actions: [
+      {
+        actionId: "compile_brief_inputs",
+        kind: "context_pack",
+        title: "Compile brief inputs",
+        description: "Read graph state, worktree state, and overnight workflow receipts.",
+        mutationTier: "read_only",
+        produces: ["structured_payload"],
+        idempotent: true,
+        approval: { mode: "none" }
+      },
+      {
+        actionId: "publish_morning_brief",
+        kind: "brief_publish",
+        title: "Publish morning brief",
+        description: "Publish a typed inbox summary with prioritized worktree and question context.",
+        mutationTier: "low_risk_write",
+        produces: ["engineering_brief", "inbox_summary"],
+        approval: { mode: "audit_only" }
+      }
+    ],
+    hooks: [
+      {
+        hookId: "morning-schedule",
+        event: "schedule.tick",
+        description: "Run once per morning cadence.",
+        actionIds: ["compile_brief_inputs", "publish_morning_brief"]
+      },
+      {
+        hookId: "worktree-complete-refresh",
+        event: "worktree.completed",
+        description: "Refresh the queued morning brief inputs when worktree outcomes land overnight.",
+        actionIds: ["compile_brief_inputs"]
+      }
+    ],
+    outputs: ["engineering_brief", "inbox_summary", "structured_payload"],
+    integrityChecks: ["sparse_shaping"]
+  }
+];
+
+export { CANONICAL_WORKFLOW_DEFINITIONS, DEFAULT_TIER_APPROVAL_MODE, DEFAULT_WORKFLOW_AUTO_FIX_POLICY, MORNING_BRIEF_WORKFLOW_ID, NIGHTLY_RECONCILIATION_WORKFLOW_ID, WORKFLOW_ACTION_KINDS, WORKFLOW_APPROVAL_MODES, WORKFLOW_AUTO_FIX_MODES, WORKFLOW_HOOK_EVENTS, WORKFLOW_INTEGRITY_CHECKS, WORKFLOW_MUTATION_TIERS, WORKFLOW_OUTPUT_KINDS, WORKFLOW_PROOF_ARTIFACT_KINDS, WORKFLOW_RUNTIME_SCHEMA_VERSION, WORKFLOW_RUN_STATUSES, WORKFLOW_STAFFING_HINTS, WORKFLOW_TRIGGER_KINDS };
+//# sourceMappingURL=workflow-runtime.contract.js.map
+//# sourceMappingURL=workflow-runtime.contract.js.map

package/dist/workflow-runtime.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workflow-runtime.contract.ts"],"names":[],"mappings":";AAkBO,IAAM,+BAAA,GAAkC;AAExC,IAAM,uBAAA,GAA0B;AAAA,EACrC,WAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAGO,IAAM,uBAAA,GAA0B;AAAA,EACrC,MAAA;AAAA,EACA,YAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAGO,IAAM,0BAAA,GAET;AAAA,EACF,SAAA,EAAW,MAAA;AAAA,EACX,cAAA,EAAgB,YAAA;AAAA,EAChB,eAAA,EAAiB;AACnB;AAEO,IAAM,qBAAA,GAAwB;AAAA,EACnC,cAAA;AAAA,EACA,iBAAA;AAAA,EACA,aAAA;AAAA,EACA,gBAAA;AAAA,EACA,eAAA;AAAA,EACA,cAAA;AAAA,EACA;AACF;AAGO,IAAM,oBAAA,GAAuB;AAAA,EAClC,eAAA;AAAA,EACA,oBAAA;AAAA,EACA,oBAAA;AAAA,EACA,kBAAA;AAAA,EACA,mBAAA;AAAA,EACA,mBAAA;AAAA,EACA;AACF;AAGO,IAAM,qBAAA,GAAwB;AAAA,EACnC,mBAAA;AAAA,EACA,eAAA;AAAA,EACA,mBAAA;AAAA,EACA,eAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAGO,IAAM,qBAAA,GAAwB;AAAA,EACnC,QAAA;AAAA,EACA,SAAA;AAAA,EACA,mBAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF;AAGO,IAAM,sBAAA,GAAyB;AAAA,EACpC,QAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF;AAGO,IAAM,6BAAA,GAAgC;AAAA,EAC3C,QAAA;AAAA,EACA,OAAA;AAAA,EACA,UAAA;AAAA,EACA,WAAA;AAAA,EACA;AACF;AAIO,IAAM,uBAAA,GAA0B;AAAA,EACrC,MAAA;AAAA,EACA,eAAA;AAAA,EACA,WAAA;AAAA,EACA;AACF;AAGO,IAAM,uBAAA,GAA0B;AAAA,EACrC,UAAA;AAAA,EACA,SAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF;AAGO,IAAM,yBAAA,GAA4B;AAAA,EACvC,sBAAA;AAAA,EACA,qBAAA;AAAA,EACA,0BAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAmBO,IAAM,gCAAA,GAA0D;AAAA,EACrE,IAAA,EAAM,UAAA;AAAA,EACN,sBAAA,EAAwB,CAAC,WAAW,CAAA;AAAA,EACpC,iBAAA,EAAmB;AACrB;AAgIO,IAAM,kCAAA,GACX;AAEK,IAAM,yBAAA,GACX;AAEK,IAAM,8BAAA,GAAkE;AAAA,EAC7E;AAAA,IACE,UAAA,EAAY,kCAAA;AAAA,IACZ,OAAA,EAAS,+BAAA;AAAA,IACT,KAAA,EAAO,iCAAA;AAAA,IACP,WAAA,EACE,kHAAA;AAAA,IACF,OAAA,EAAS;AAAA,MACP,IAAA,EAAM,UAAA;AAAA,MACN,OAAA,EAAS,OAAA;AAAA,MACT,QAAA,EAAU;AAAA,KACZ;AAAA,IACA,YAAA,EAAc,eAAA;AAAA,IACd,cAAA,EAAgB;AAAA,MACd;AAAA,QACE,IAAA,EAAM,QAAA;AAAA,QACN,KAAA,EAAO,gCAAA;AAAA,QACP,QAAA,EAAU;AAAA,OACZ;AAAA,MACA;AAAA,QACE,IAAA,EAAM,eAAA;AAAA,QACN,KAAA,EAAO,yBAAA;AAAA,QACP,QAAA,EAAU;AAAA;AACZ,KACF;AAAA,IACA,aAAA,EAAe;AAAA,MACb,IAAA,EAAM,MAAA;AAAA,MACN,gBAAA,EAAkB,CAAA;AAAA,MAClB,sBAAA,EAAwB,CAAC,WAAA,EAAa,gBAAgB,CAAA;AAAA,MACtD,iBAAA,EAAmB,IAAA;AAAA,MACnB,cAAA,EAAgB;AAAA,KAClB;AAAA,IACA,OAAA,EAAS;AAAA,MACP;AAAA,QACE,QAAA,EAAU,sBAAA;AAAA,QACV,IAAA,EAAM,cAAA;AAAA,QACN,KAAA,EAAO,0BAAA;AAAA,QACP,WAAA,EAAa,2DAAA;AAAA,QACb,YAAA,EAAc,WAAA;AAAA,QACd,QAAA,EAAU,CAAC,oBAAoB,CAAA;AAAA,QAC/B,UAAA,EAAY,IAAA;AAAA,QACZ,QAAA,EAAU,EAAE,IAAA,EAAM,MAAA;AAAO,OAC3B;AAAA,MACA;AAAA,QACE,QAAA,EAAU,sBAAA;AAAA,QACV,IAAA,EAAM,iBAAA;AAAA,QACN,KAAA,EAAO,sBAAA;AAAA,QACP,WAAA,EACE,mGAAA;AAAA,QACF,YAAA,EAAc,WAAA;AAAA,QACd,QAAA,EAAU,CAAC,oBAAoB,CAAA;AAAA,QAC/B,UAAA,EAAY,IAAA;AAAA,QACZ,QAAA,EAAU,EAAE,IAAA,EAAM,MAAA;AAAO,OAC3B;AAAA,MACA;AAAA,QACE,QAAA,EAAU,2BAAA;AAAA,QACV,IAAA,EAAM,aAAA;AAAA,QACN,KAAA,EAAO,4BAAA;AAAA,QACP,WAAA,EACE,8FAAA;AAAA,QACF,YAAA,EAAc,gBAAA;AAAA,QACd,QAAA,EAAU,iBAAA;AAAA,QACV,QAAA,EAAU,CAAC,gBAAgB,CAAA;AAAA,QAC3B,QAAA,EAAU,EAAE,IAAA,EAAM,YAAA,EAAc,mBAAmB,IAAA;AAAK,OAC1D;AAAA,MACA;AAAA,QACE,QAAA,EAAU,8BAAA;AAAA,QACV,IAAA,EAAM,eAAA;AAAA,QACN,KAAA,EAAO,8BAAA;AAAA,QACP,WAAA,EACE,yFAAA;AAAA,QACF,YAAA,EAAc,gBAAA;AAAA,QACd,QAAA,EAAU,CAAC,gBAAA,EAAkB,eAAe,CAAA;AAAA,QAC5C,QAAA,EAAU,EAAE,IAAA,EAAM,YAAA;AAAa;AACjC,KACF;AAAA,IACA,KAAA,EAAO;AAAA,MACL;AAAA,QACE,MAAA,EAAQ,kBAAA;AAAA,QACR,KAAA,EAAO,eAAA;AAAA,QACP,WAAA,EAAa,+BAAA;AAAA,QACb,SAAA,EAAW;AAAA,UACT,sBAAA;AAAA,UACA,sBAAA;AAAA,UACA,2BAAA;AAAA,UACA;AAAA;AACF;AACF,KACF;AAAA,IACA,OAAA,EAAS,CAAC,gBAAA,EAAkB,eAAA,EAAiB,oBAAoB,CAAA;AAAA,IACjE,eAAA,EAAiB;AAAA,GACnB;AAAA,EACA;AAAA,IACE,UAAA,EAAY,yBAAA;AAAA,IACZ,OAAA,EAAS,+BAAA;AAAA,IACT,KAAA,EAAO,eAAA;AAAA,IACP,WAAA,EACE,wHAAA;AAAA,IACF,OAAA,EAAS;AAAA,MACP,IAAA,EAAM,UAAA;AAAA,MACN,OAAA,EAAS,OAAA;AAAA,MACT,QAAA,EAAU;AAAA,KACZ;AAAA,IACA,YAAA,EAAc,MAAA;AAAA,IACd,cAAA,EAAgB;AAAA,MACd;AAAA,QACE,IAAA,EAAM,OAAA;AAAA,QACN,KAAA,EAAO,eAAA;AAAA,QACP,QAAA,EAAU;AAAA;AACZ,KACF;AAAA,IACA,aAAA,EAAe;AAAA,MACb,IAAA,EAAM,SAAA;AAAA,MACN,gBAAA,EAAkB,CAAA;AAAA,MAClB,sBAAA,EAAwB,CAAC,WAAA,EAAa,gBAAgB,CAAA;AAAA,MACtD,iBAAA,EAAmB;AAAA,KACrB;AAAA,IACA,OAAA,EAAS;AAAA,MACP;AAAA,QACE,QAAA,EAAU,sBAAA;AAAA,QACV,IAAA,EAAM,cAAA;AAAA,QACN,KAAA,EAAO,sBAAA;AAAA,QACP,WAAA,EACE,oEAAA;AAAA,QACF,YAAA,EAAc,WAAA;AAAA,QACd,QAAA,EAAU,CAAC,oBAAoB,CAAA;AAAA,QAC/B,UAAA,EAAY,IAAA;AAAA,QACZ,QAAA,EAAU,EAAE,IAAA,EAAM,MAAA;AAAO,OAC3B;AAAA,MACA;AAAA,QACE,QAAA,EAAU,uBAAA;AAAA,QACV,IAAA,EAAM,eAAA;AAAA,QACN,KAAA,EAAO,uBAAA;AAAA,QACP,WAAA,EACE,+EAAA;AAAA,QACF,YAAA,EAAc,gBAAA;AAAA,QACd,QAAA,EAAU,CAAC,mBAAA,EAAqB,eAAe,CAAA;AAAA,QAC/C,QAAA,EAAU,EAAE,IAAA,EAAM,YAAA;AAAa;AACjC,KACF;AAAA,IACA,KAAA,EAAO;AAAA,MACL;AAAA,QACE,MAAA,EAAQ,kBAAA;AAAA,QACR,KAAA,EAAO,eAAA;AAAA,QACP,WAAA,EAAa,+BAAA;AAAA,QACb,SAAA,EAAW,CAAC,sBAAA,EAAwB,uBAAuB;AAAA,OAC7D;AAAA,MACA;AAAA,QACE,MAAA,EAAQ,2BAAA;AAAA,QACR,KAAA,EAAO,oBAAA;AAAA,QACP,WAAA,EACE,gFAAA;AAAA,QACF,SAAA,EAAW,CAAC,sBAAsB;AAAA;AACpC,KACF;AAAA,IACA,OAAA,EAAS,CAAC,mBAAA,EAAqB,eAAA,EAAiB,oBAAoB,CAAA;AAAA,IACpE,eAAA,EAAiB,CAAC,gBAAgB;AAAA;AAEtC","file":"workflow-runtime.contract.js","sourcesContent":["/**\n * Workflow Runtime Contract v1\n *\n * Canonical TypeScript contract for Lucern's graph-local workflow runtime.\n * WF-1 defines the typed substrate for:\n *   - workflow definitions and run receipts\n *   - action mutation tiering and approval expectations\n *   - hooks over worktree/question/evidence/inbox events\n *   - output unions for domain-specific artifacts\n *   - deterministic integrity checks and operational metadata\n *\n * BREAKING CHANGE RULES:\n *   - Adding optional fields is NON-breaking\n *   - Removing fields or renaming enum values is BREAKING\n *   - Reclassifying a mutation tier is BREAKING\n *   - Changing canonical workflow IDs is BREAKING\n */\n\nexport const WORKFLOW_RUNTIME_SCHEMA_VERSION = \"1.0.0\" as const;\n\nexport const WORKFLOW_MUTATION_TIERS = [\n  \"read_only\",\n  \"low_risk_write\",\n  \"high_risk_write\",\n] as const;\nexport type WorkflowMutationTier = (typeof WORKFLOW_MUTATION_TIERS)[number];\n\nexport const WORKFLOW_APPROVAL_MODES = [\n  \"none\",\n  \"audit_only\",\n  \"human_required\",\n  \"auto_approve\",\n] as const;\nexport type WorkflowApprovalMode = (typeof WORKFLOW_APPROVAL_MODES)[number];\n\nexport const DEFAULT_TIER_APPROVAL_MODE: Readonly<\n  Record<WorkflowMutationTier, WorkflowApprovalMode>\n> = {\n  read_only: \"none\",\n  low_risk_write: \"audit_only\",\n  high_risk_write: \"human_required\",\n} as const;\n\nexport const WORKFLOW_ACTION_KINDS = [\n  \"context_pack\",\n  \"integrity_check\",\n  \"lucern_tool\",\n  \"report_compile\",\n  \"brief_publish\",\n  \"notification\",\n  \"custom\",\n] as const;\nexport type WorkflowActionKind = (typeof WORKFLOW_ACTION_KINDS)[number];\n\nexport const WORKFLOW_HOOK_EVENTS = [\n  \"schedule.tick\",\n  \"worktree.activated\",\n  \"worktree.completed\",\n  \"question.created\",\n  \"question.answered\",\n  \"evidence.appended\",\n  \"inbox.item_created\",\n] as const;\nexport type WorkflowHookEvent = (typeof WORKFLOW_HOOK_EVENTS)[number];\n\nexport const WORKFLOW_OUTPUT_KINDS = [\n  \"engineering_brief\",\n  \"research_memo\",\n  \"strategy_artifact\",\n  \"inbox_summary\",\n  \"pipeline_brief\",\n  \"structured_payload\",\n] as const;\nexport type WorkflowOutputKind = (typeof WORKFLOW_OUTPUT_KINDS)[number];\n\nexport const WORKFLOW_RUN_STATUSES = [\n  \"queued\",\n  \"running\",\n  \"awaiting_approval\",\n  \"completed\",\n  \"failed\",\n  \"cancelled\",\n] as const;\nexport type WorkflowRunStatus = (typeof WORKFLOW_RUN_STATUSES)[number];\n\nexport const WORKFLOW_TRIGGER_KINDS = [\n  \"manual\",\n  \"schedule\",\n  \"hook\",\n] as const;\nexport type WorkflowTriggerKind = (typeof WORKFLOW_TRIGGER_KINDS)[number];\n\nexport const WORKFLOW_PROOF_ARTIFACT_KINDS = [\n  \"report\",\n  \"brief\",\n  \"artifact\",\n  \"dashboard\",\n  \"test_evidence\",\n] as const;\nexport type WorkflowProofArtifactKind =\n  (typeof WORKFLOW_PROOF_ARTIFACT_KINDS)[number];\n\nexport const WORKFLOW_STAFFING_HINTS = [\n  \"solo\",\n  \"backend+tests\",\n  \"fullstack\",\n  \"mcp+tests\",\n] as const;\nexport type WorkflowStaffingHint = (typeof WORKFLOW_STAFFING_HINTS)[number];\n\nexport const WORKFLOW_AUTO_FIX_MODES = [\n  \"disabled\",\n  \"dry_run\",\n  \"safe\",\n  \"aggressive\",\n] as const;\nexport type WorkflowAutoFixMode = (typeof WORKFLOW_AUTO_FIX_MODES)[number];\n\nexport const WORKFLOW_INTEGRITY_CHECKS = [\n  \"null_dependency_refs\",\n  \"superseded_blockers\",\n  \"band_order_inconsistency\",\n  \"sparse_shaping\",\n  \"failed_completed_gate\",\n] as const;\nexport type WorkflowIntegrityCheckId =\n  (typeof WORKFLOW_INTEGRITY_CHECKS)[number];\n\nexport type WorkflowProofArtifact = {\n  kind: WorkflowProofArtifactKind;\n  label: string;\n  required?: boolean;\n  sourceRef?: string;\n};\n\nexport type WorkflowAutoFixPolicy = {\n  mode: WorkflowAutoFixMode;\n  maxActionsPerRun?: number;\n  permittedMutationTiers?: WorkflowMutationTier[];\n  requireAuditTrail?: boolean;\n  escalationGate?: string;\n};\n\nexport const DEFAULT_WORKFLOW_AUTO_FIX_POLICY: WorkflowAutoFixPolicy = {\n  mode: \"disabled\",\n  permittedMutationTiers: [\"read_only\"],\n  requireAuditTrail: true,\n};\n\nexport type WorkflowApprovalPolicy = {\n  mode: WorkflowApprovalMode;\n  approvalGate?: string;\n  autoApprovePolicyKey?: string;\n  rationaleRequired?: boolean;\n};\n\nexport type WorkflowOutputBase = {\n  outputId: string;\n  kind: WorkflowOutputKind;\n  title: string;\n  summary: string;\n  generatedAt?: number;\n};\n\nexport type EngineeringBriefOutput = WorkflowOutputBase & {\n  kind: \"engineering_brief\";\n  sections: Array<{\n    heading: string;\n    body: string;\n  }>;\n  touchedPaths?: string[];\n};\n\nexport type ResearchMemoOutput = WorkflowOutputBase & {\n  kind: \"research_memo\";\n  claims: string[];\n  evidenceRefs?: string[];\n};\n\nexport type StrategyArtifactOutput = WorkflowOutputBase & {\n  kind: \"strategy_artifact\";\n  recommendations: string[];\n  decisionWindow?: string;\n};\n\nexport type InboxSummaryOutput = WorkflowOutputBase & {\n  kind: \"inbox_summary\";\n  channel: \"developer_portal\" | \"chat\" | \"ops\";\n  inboxTitle: string;\n  inboxBody: string;\n};\n\nexport type PipelineBriefOutput = WorkflowOutputBase & {\n  kind: \"pipeline_brief\";\n  hingeWorktreeId?: string;\n  groupedBlockers: Array<{\n    blocker: string;\n    blockedWorktreeIds: string[];\n  }>;\n};\n\nexport type StructuredPayloadOutput = WorkflowOutputBase & {\n  kind: \"structured_payload\";\n  payload: Record<string, unknown>;\n};\n\nexport type WorkflowOutputContract =\n  | EngineeringBriefOutput\n  | ResearchMemoOutput\n  | StrategyArtifactOutput\n  | InboxSummaryOutput\n  | PipelineBriefOutput\n  | StructuredPayloadOutput;\n\nexport type WorkflowActionContract = {\n  actionId: string;\n  kind: WorkflowActionKind;\n  title: string;\n  description: string;\n  mutationTier: WorkflowMutationTier;\n  toolName?: string;\n  produces?: WorkflowOutputKind[];\n  idempotent?: boolean;\n  approval: WorkflowApprovalPolicy;\n};\n\nexport type WorkflowHookContract = {\n  hookId: string;\n  event: WorkflowHookEvent;\n  description: string;\n  condition?: string;\n  actionIds: string[];\n};\n\nexport type WorkflowTriggerContract =\n  | {\n      kind: \"manual\";\n      description?: string;\n    }\n  | {\n      kind: \"schedule\";\n      cadence: \"hourly\" | \"daily\" | \"weekly\";\n      timezone?: string;\n    }\n  | {\n      kind: \"hook\";\n      event: WorkflowHookEvent;\n    };\n\nexport type WorkflowDefinitionV1 = {\n  workflowId: string;\n  version: typeof WORKFLOW_RUNTIME_SCHEMA_VERSION;\n  title: string;\n  description: string;\n  trigger: WorkflowTriggerContract;\n  staffingHint?: WorkflowStaffingHint;\n  proofArtifacts?: WorkflowProofArtifact[];\n  autoFixPolicy?: WorkflowAutoFixPolicy;\n  actions: readonly WorkflowActionContract[];\n  hooks?: readonly WorkflowHookContract[];\n  outputs: readonly WorkflowOutputKind[];\n  integrityChecks?: readonly WorkflowIntegrityCheckId[];\n};\n\nexport type WorkflowRunReceiptV1 = {\n  runId: string;\n  workflowId: string;\n  status: WorkflowRunStatus;\n  triggeredBy: WorkflowTriggerKind;\n  startedAt: number;\n  completedAt?: number;\n  outputKinds: WorkflowOutputKind[];\n  approvalsRequired?: number;\n};\n\nexport const NIGHTLY_RECONCILIATION_WORKFLOW_ID =\n  \"workflow.pipeline_reconciliation.v1\" as const;\n\nexport const MORNING_BRIEF_WORKFLOW_ID =\n  \"workflow.morning_brief.v1\" as const;\n\nexport const CANONICAL_WORKFLOW_DEFINITIONS: readonly WorkflowDefinitionV1[] = [\n  {\n    workflowId: NIGHTLY_RECONCILIATION_WORKFLOW_ID,\n    version: WORKFLOW_RUNTIME_SCHEMA_VERSION,\n    title: \"Nightly Pipeline Reconciliation\",\n    description:\n      \"Runs deterministic integrity checks, compiles pipeline state, and emits an operator-facing reconciliation brief.\",\n    trigger: {\n      kind: \"schedule\",\n      cadence: \"daily\",\n      timezone: \"America/New_York\",\n    },\n    staffingHint: \"backend+tests\",\n    proofArtifacts: [\n      {\n        kind: \"report\",\n        label: \"Pipeline reconciliation report\",\n        required: true,\n      },\n      {\n        kind: \"test_evidence\",\n        label: \"Integrity check receipt\",\n        required: true,\n      },\n    ],\n    autoFixPolicy: {\n      mode: \"safe\",\n      maxActionsPerRun: 5,\n      permittedMutationTiers: [\"read_only\", \"low_risk_write\"],\n      requireAuditTrail: true,\n      escalationGate: \"gate:workflow-runtime-contract-live\",\n    },\n    actions: [\n      {\n        actionId: \"compile_context_pack\",\n        kind: \"context_pack\",\n        title: \"Compile pipeline context\",\n        description: \"Build the ranked context needed for deterministic checks.\",\n        mutationTier: \"read_only\",\n        produces: [\"structured_payload\"],\n        idempotent: true,\n        approval: { mode: \"none\" },\n      },\n      {\n        actionId: \"run_integrity_checks\",\n        kind: \"integrity_check\",\n        title: \"Run integrity checks\",\n        description:\n          \"Evaluate dependency references, blockers, execution bands, shaping coverage, and completed gates.\",\n        mutationTier: \"read_only\",\n        produces: [\"structured_payload\"],\n        idempotent: true,\n        approval: { mode: \"none\" },\n      },\n      {\n        actionId: \"record_followup_questions\",\n        kind: \"lucern_tool\",\n        title: \"Record follow-up questions\",\n        description:\n          \"Create or reopen operator-facing questions for integrity failures that require human review.\",\n        mutationTier: \"low_risk_write\",\n        toolName: \"create_question\",\n        produces: [\"pipeline_brief\"],\n        approval: { mode: \"audit_only\", rationaleRequired: true },\n      },\n      {\n        actionId: \"publish_reconciliation_brief\",\n        kind: \"brief_publish\",\n        title: \"Publish reconciliation brief\",\n        description:\n          \"Emit an inbox-routed brief summarizing the nightly pipeline state and grouped blockers.\",\n        mutationTier: \"low_risk_write\",\n        produces: [\"pipeline_brief\", \"inbox_summary\"],\n        approval: { mode: \"audit_only\" },\n      },\n    ],\n    hooks: [\n      {\n        hookId: \"nightly-schedule\",\n        event: \"schedule.tick\",\n        description: \"Run once per nightly cadence.\",\n        actionIds: [\n          \"compile_context_pack\",\n          \"run_integrity_checks\",\n          \"record_followup_questions\",\n          \"publish_reconciliation_brief\",\n        ],\n      },\n    ],\n    outputs: [\"pipeline_brief\", \"inbox_summary\", \"structured_payload\"],\n    integrityChecks: WORKFLOW_INTEGRITY_CHECKS,\n  },\n  {\n    workflowId: MORNING_BRIEF_WORKFLOW_ID,\n    version: WORKFLOW_RUNTIME_SCHEMA_VERSION,\n    title: \"Morning Brief\",\n    description:\n      \"Compiles a developer-facing morning brief from graph state, overnight workflow outputs, and inbox routing preferences.\",\n    trigger: {\n      kind: \"schedule\",\n      cadence: \"daily\",\n      timezone: \"America/New_York\",\n    },\n    staffingHint: \"solo\",\n    proofArtifacts: [\n      {\n        kind: \"brief\",\n        label: \"Morning brief\",\n        required: true,\n      },\n    ],\n    autoFixPolicy: {\n      mode: \"dry_run\",\n      maxActionsPerRun: 1,\n      permittedMutationTiers: [\"read_only\", \"low_risk_write\"],\n      requireAuditTrail: true,\n    },\n    actions: [\n      {\n        actionId: \"compile_brief_inputs\",\n        kind: \"context_pack\",\n        title: \"Compile brief inputs\",\n        description:\n          \"Read graph state, worktree state, and overnight workflow receipts.\",\n        mutationTier: \"read_only\",\n        produces: [\"structured_payload\"],\n        idempotent: true,\n        approval: { mode: \"none\" },\n      },\n      {\n        actionId: \"publish_morning_brief\",\n        kind: \"brief_publish\",\n        title: \"Publish morning brief\",\n        description:\n          \"Publish a typed inbox summary with prioritized worktree and question context.\",\n        mutationTier: \"low_risk_write\",\n        produces: [\"engineering_brief\", \"inbox_summary\"],\n        approval: { mode: \"audit_only\" },\n      },\n    ],\n    hooks: [\n      {\n        hookId: \"morning-schedule\",\n        event: \"schedule.tick\",\n        description: \"Run once per morning cadence.\",\n        actionIds: [\"compile_brief_inputs\", \"publish_morning_brief\"],\n      },\n      {\n        hookId: \"worktree-complete-refresh\",\n        event: \"worktree.completed\",\n        description:\n          \"Refresh the queued morning brief inputs when worktree outcomes land overnight.\",\n        actionIds: [\"compile_brief_inputs\"],\n      },\n    ],\n    outputs: [\"engineering_brief\", \"inbox_summary\", \"structured_payload\"],\n    integrityChecks: [\"sparse_shaping\"],\n  },\n] as const;\n"]}

package/dist/worktrees/v1.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/worktrees/v1.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=v1.js.map
+//# sourceMappingURL=v1.js.map

package/dist/worktrees/v1.js.map

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

package/package.json

@@ -1,25 +1,41 @@
 {
   "name": "@lucern/contracts",
-  "version": "0.1.1-alpha.1",
+  "version": "0.1.2-alpha.2",
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "access": "restricted"
   },
-  "main": "src/index.ts",
-  "types": "src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./*": "./src/*.ts",
-    "./v1/*": "./src/v1/*.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
+    "build": "tsup",
+    "prepack": "npm run build",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "tsup": "^8.5.0",
     "typescript": "^5.7.0"
   }
 }

package/src/agents/v1.ts

@@ -1,8 +0,0 @@
-/**
- * Agent API Contract v1
- *
- * Defines the public surface for agent operations:
- * session management, message passing, coordination, claims.
- * Migrates from front-end/lucern/contracts/ during EK-16.
- */
-export {};