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

package/src/workflow-runtime.contract.ts

@@ -1,440 +0,0 @@
-/**
- * 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
- */
-
-export const WORKFLOW_RUNTIME_SCHEMA_VERSION = "1.0.0" as const;
-
-export const WORKFLOW_MUTATION_TIERS = [
-  "read_only",
-  "low_risk_write",
-  "high_risk_write",
-] as const;
-export type WorkflowMutationTier = (typeof WORKFLOW_MUTATION_TIERS)[number];
-
-export const WORKFLOW_APPROVAL_MODES = [
-  "none",
-  "audit_only",
-  "human_required",
-  "auto_approve",
-] as const;
-export type WorkflowApprovalMode = (typeof WORKFLOW_APPROVAL_MODES)[number];
-
-export const DEFAULT_TIER_APPROVAL_MODE: Readonly<
-  Record<WorkflowMutationTier, WorkflowApprovalMode>
-> = {
-  read_only: "none",
-  low_risk_write: "audit_only",
-  high_risk_write: "human_required",
-} as const;
-
-export const WORKFLOW_ACTION_KINDS = [
-  "context_pack",
-  "integrity_check",
-  "lucern_tool",
-  "report_compile",
-  "brief_publish",
-  "notification",
-  "custom",
-] as const;
-export type WorkflowActionKind = (typeof WORKFLOW_ACTION_KINDS)[number];
-
-export const WORKFLOW_HOOK_EVENTS = [
-  "schedule.tick",
-  "worktree.activated",
-  "worktree.completed",
-  "question.created",
-  "question.answered",
-  "evidence.appended",
-  "inbox.item_created",
-] as const;
-export type WorkflowHookEvent = (typeof WORKFLOW_HOOK_EVENTS)[number];
-
-export const WORKFLOW_OUTPUT_KINDS = [
-  "engineering_brief",
-  "research_memo",
-  "strategy_artifact",
-  "inbox_summary",
-  "pipeline_brief",
-  "structured_payload",
-] as const;
-export type WorkflowOutputKind = (typeof WORKFLOW_OUTPUT_KINDS)[number];
-
-export const WORKFLOW_RUN_STATUSES = [
-  "queued",
-  "running",
-  "awaiting_approval",
-  "completed",
-  "failed",
-  "cancelled",
-] as const;
-export type WorkflowRunStatus = (typeof WORKFLOW_RUN_STATUSES)[number];
-
-export const WORKFLOW_TRIGGER_KINDS = [
-  "manual",
-  "schedule",
-  "hook",
-] as const;
-export type WorkflowTriggerKind = (typeof WORKFLOW_TRIGGER_KINDS)[number];
-
-export const WORKFLOW_PROOF_ARTIFACT_KINDS = [
-  "report",
-  "brief",
-  "artifact",
-  "dashboard",
-  "test_evidence",
-] as const;
-export type WorkflowProofArtifactKind =
-  (typeof WORKFLOW_PROOF_ARTIFACT_KINDS)[number];
-
-export const WORKFLOW_STAFFING_HINTS = [
-  "solo",
-  "backend+tests",
-  "fullstack",
-  "mcp+tests",
-] as const;
-export type WorkflowStaffingHint = (typeof WORKFLOW_STAFFING_HINTS)[number];
-
-export const WORKFLOW_AUTO_FIX_MODES = [
-  "disabled",
-  "dry_run",
-  "safe",
-  "aggressive",
-] as const;
-export type WorkflowAutoFixMode = (typeof WORKFLOW_AUTO_FIX_MODES)[number];
-
-export const WORKFLOW_INTEGRITY_CHECKS = [
-  "null_dependency_refs",
-  "superseded_blockers",
-  "band_order_inconsistency",
-  "sparse_shaping",
-  "failed_completed_gate",
-] as const;
-export type WorkflowIntegrityCheckId =
-  (typeof WORKFLOW_INTEGRITY_CHECKS)[number];
-
-export type WorkflowProofArtifact = {
-  kind: WorkflowProofArtifactKind;
-  label: string;
-  required?: boolean;
-  sourceRef?: string;
-};
-
-export type WorkflowAutoFixPolicy = {
-  mode: WorkflowAutoFixMode;
-  maxActionsPerRun?: number;
-  permittedMutationTiers?: WorkflowMutationTier[];
-  requireAuditTrail?: boolean;
-  escalationGate?: string;
-};
-
-export const DEFAULT_WORKFLOW_AUTO_FIX_POLICY: WorkflowAutoFixPolicy = {
-  mode: "disabled",
-  permittedMutationTiers: ["read_only"],
-  requireAuditTrail: true,
-};
-
-export type WorkflowApprovalPolicy = {
-  mode: WorkflowApprovalMode;
-  approvalGate?: string;
-  autoApprovePolicyKey?: string;
-  rationaleRequired?: boolean;
-};
-
-export type WorkflowOutputBase = {
-  outputId: string;
-  kind: WorkflowOutputKind;
-  title: string;
-  summary: string;
-  generatedAt?: number;
-};
-
-export type EngineeringBriefOutput = WorkflowOutputBase & {
-  kind: "engineering_brief";
-  sections: Array<{
-    heading: string;
-    body: string;
-  }>;
-  touchedPaths?: string[];
-};
-
-export type ResearchMemoOutput = WorkflowOutputBase & {
-  kind: "research_memo";
-  claims: string[];
-  evidenceRefs?: string[];
-};
-
-export type StrategyArtifactOutput = WorkflowOutputBase & {
-  kind: "strategy_artifact";
-  recommendations: string[];
-  decisionWindow?: string;
-};
-
-export type InboxSummaryOutput = WorkflowOutputBase & {
-  kind: "inbox_summary";
-  channel: "developer_portal" | "chat" | "ops";
-  inboxTitle: string;
-  inboxBody: string;
-};
-
-export type PipelineBriefOutput = WorkflowOutputBase & {
-  kind: "pipeline_brief";
-  hingeWorktreeId?: string;
-  groupedBlockers: Array<{
-    blocker: string;
-    blockedWorktreeIds: string[];
-  }>;
-};
-
-export type StructuredPayloadOutput = WorkflowOutputBase & {
-  kind: "structured_payload";
-  payload: Record<string, unknown>;
-};
-
-export type WorkflowOutputContract =
-  | EngineeringBriefOutput
-  | ResearchMemoOutput
-  | StrategyArtifactOutput
-  | InboxSummaryOutput
-  | PipelineBriefOutput
-  | StructuredPayloadOutput;
-
-export type WorkflowActionContract = {
-  actionId: string;
-  kind: WorkflowActionKind;
-  title: string;
-  description: string;
-  mutationTier: WorkflowMutationTier;
-  toolName?: string;
-  produces?: WorkflowOutputKind[];
-  idempotent?: boolean;
-  approval: WorkflowApprovalPolicy;
-};
-
-export type WorkflowHookContract = {
-  hookId: string;
-  event: WorkflowHookEvent;
-  description: string;
-  condition?: string;
-  actionIds: string[];
-};
-
-export type WorkflowTriggerContract =
-  | {
-      kind: "manual";
-      description?: string;
-    }
-  | {
-      kind: "schedule";
-      cadence: "hourly" | "daily" | "weekly";
-      timezone?: string;
-    }
-  | {
-      kind: "hook";
-      event: WorkflowHookEvent;
-    };
-
-export 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[];
-};
-
-export type WorkflowRunReceiptV1 = {
-  runId: string;
-  workflowId: string;
-  status: WorkflowRunStatus;
-  triggeredBy: WorkflowTriggerKind;
-  startedAt: number;
-  completedAt?: number;
-  outputKinds: WorkflowOutputKind[];
-  approvalsRequired?: number;
-};
-
-export const NIGHTLY_RECONCILIATION_WORKFLOW_ID =
-  "workflow.pipeline_reconciliation.v1" as const;
-
-export const MORNING_BRIEF_WORKFLOW_ID =
-  "workflow.morning_brief.v1" as const;
-
-export const CANONICAL_WORKFLOW_DEFINITIONS: readonly WorkflowDefinitionV1[] = [
-  {
-    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"],
-  },
-] as const;

package/src/worktrees/v1.ts

@@ -1,8 +0,0 @@
-/**
- * Worktree API Contract v1
- *
- * Defines the public surface for worktree operations:
- * add, activate, merge, targets, metadata, tasks.
- * Migrates from front-end/lucern/contracts/ during EK-16.
- */
-export {};

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist"]
-}