@agentic-coding-framework/orchestrator-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Agentic Coding Protocol — Orchestrator Core
+ *
+ * Three modules, one pipeline:
+ *   state.ts   → STATE.json types + I/O
+ *   rules.ts   → Step transition rules table (pure data)
+ *   dispatch.ts → State machine + prompt builder + handoff parser
+ */
+export { type State, type Step, type Status, type Reason, type TaskType, type TestResult, createInitialState, readState, writeState, initState, validate, isTimedOut, isMaxedOut, markRunning, markCompleted, } from "./state";
+export { type StepRule, type FailRouting, type TeamRole, type TeamRoles, type DispatchMode, STEP_RULES, BOOTSTRAP_RULE, DEFAULT_TEAM_ROLES, DISPATCH_MODES, getRule, resolvePaths, getDispatchMode, getFailTarget, getStepSequence, } from "./rules";
+export { type DispatchResult, type HandoffResult, dispatch, buildPrompt, parseHandoff, applyHandoff, runPostCheck, approveReview, rejectReview, startStory, startCustom, type ProjectStatus, type FrameworkDetection, type ProjectEntry, detectFramework, queryProjectStatus, listProjects, } from "./dispatch";

package/dist/index.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Agentic Coding Protocol — Orchestrator Core
+ *
+ * Three modules, one pipeline:
+ *   state.ts   → STATE.json types + I/O
+ *   rules.ts   → Step transition rules table (pure data)
+ *   dispatch.ts → State machine + prompt builder + handoff parser
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listProjects = exports.queryProjectStatus = exports.detectFramework = exports.startCustom = exports.startStory = exports.rejectReview = exports.approveReview = exports.runPostCheck = exports.applyHandoff = exports.parseHandoff = exports.buildPrompt = exports.dispatch = exports.getStepSequence = exports.getFailTarget = exports.getDispatchMode = exports.resolvePaths = exports.getRule = exports.DISPATCH_MODES = exports.DEFAULT_TEAM_ROLES = exports.BOOTSTRAP_RULE = exports.STEP_RULES = exports.markCompleted = exports.markRunning = exports.isMaxedOut = exports.isTimedOut = exports.validate = exports.initState = exports.writeState = exports.readState = exports.createInitialState = void 0;
+// State
+var state_1 = require("./state");
+Object.defineProperty(exports, "createInitialState", { enumerable: true, get: function () { return state_1.createInitialState; } });
+Object.defineProperty(exports, "readState", { enumerable: true, get: function () { return state_1.readState; } });
+Object.defineProperty(exports, "writeState", { enumerable: true, get: function () { return state_1.writeState; } });
+Object.defineProperty(exports, "initState", { enumerable: true, get: function () { return state_1.initState; } });
+Object.defineProperty(exports, "validate", { enumerable: true, get: function () { return state_1.validate; } });
+Object.defineProperty(exports, "isTimedOut", { enumerable: true, get: function () { return state_1.isTimedOut; } });
+Object.defineProperty(exports, "isMaxedOut", { enumerable: true, get: function () { return state_1.isMaxedOut; } });
+Object.defineProperty(exports, "markRunning", { enumerable: true, get: function () { return state_1.markRunning; } });
+Object.defineProperty(exports, "markCompleted", { enumerable: true, get: function () { return state_1.markCompleted; } });
+// Rules
+var rules_1 = require("./rules");
+Object.defineProperty(exports, "STEP_RULES", { enumerable: true, get: function () { return rules_1.STEP_RULES; } });
+Object.defineProperty(exports, "BOOTSTRAP_RULE", { enumerable: true, get: function () { return rules_1.BOOTSTRAP_RULE; } });
+Object.defineProperty(exports, "DEFAULT_TEAM_ROLES", { enumerable: true, get: function () { return rules_1.DEFAULT_TEAM_ROLES; } });
+Object.defineProperty(exports, "DISPATCH_MODES", { enumerable: true, get: function () { return rules_1.DISPATCH_MODES; } });
+Object.defineProperty(exports, "getRule", { enumerable: true, get: function () { return rules_1.getRule; } });
+Object.defineProperty(exports, "resolvePaths", { enumerable: true, get: function () { return rules_1.resolvePaths; } });
+Object.defineProperty(exports, "getDispatchMode", { enumerable: true, get: function () { return rules_1.getDispatchMode; } });
+Object.defineProperty(exports, "getFailTarget", { enumerable: true, get: function () { return rules_1.getFailTarget; } });
+Object.defineProperty(exports, "getStepSequence", { enumerable: true, get: function () { return rules_1.getStepSequence; } });
+// Dispatch
+var dispatch_1 = require("./dispatch");
+Object.defineProperty(exports, "dispatch", { enumerable: true, get: function () { return dispatch_1.dispatch; } });
+Object.defineProperty(exports, "buildPrompt", { enumerable: true, get: function () { return dispatch_1.buildPrompt; } });
+Object.defineProperty(exports, "parseHandoff", { enumerable: true, get: function () { return dispatch_1.parseHandoff; } });
+Object.defineProperty(exports, "applyHandoff", { enumerable: true, get: function () { return dispatch_1.applyHandoff; } });
+Object.defineProperty(exports, "runPostCheck", { enumerable: true, get: function () { return dispatch_1.runPostCheck; } });
+Object.defineProperty(exports, "approveReview", { enumerable: true, get: function () { return dispatch_1.approveReview; } });
+Object.defineProperty(exports, "rejectReview", { enumerable: true, get: function () { return dispatch_1.rejectReview; } });
+Object.defineProperty(exports, "startStory", { enumerable: true, get: function () { return dispatch_1.startStory; } });
+Object.defineProperty(exports, "startCustom", { enumerable: true, get: function () { return dispatch_1.startCustom; } });
+Object.defineProperty(exports, "detectFramework", { enumerable: true, get: function () { return dispatch_1.detectFramework; } });
+Object.defineProperty(exports, "queryProjectStatus", { enumerable: true, get: function () { return dispatch_1.queryProjectStatus; } });
+Object.defineProperty(exports, "listProjects", { enumerable: true, get: function () { return dispatch_1.listProjects; } });

package/dist/rules.d.ts

@@ -0,0 +1,65 @@
+/**
+ * rules.ts — Step Transition Rules Table
+ *
+ * Pure data, zero logic. Direct translation of the Protocol's Step Transition
+ * Rules YAML into TypeScript. The orchestrator looks up this table to decide:
+ * what files the executor reads, what it writes, what post-check to run,
+ * max attempts, timeout, and where to go on pass/fail.
+ *
+ * Projects can override defaults via `.ai/step-rules.yaml` (future).
+ */
+import type { Step, Reason } from "./state";
+/** Reason-based routing: maps failure reason → target step */
+export type FailRouting = {
+    /** Fallback when reason is null or unrecognized */
+    default: Step;
+} & Partial<Record<Reason, Step>>;
+/** Complete rule definition for a single step */
+export interface StepRule {
+    /** Display name for dispatch prompt */
+    display_name: string;
+    /** Step to advance to on success */
+    next_on_pass: Step;
+    /** Reason-based routing on failure */
+    on_fail: FailRouting;
+    /** Maximum attempts before marking as blocked */
+    max_attempts: number;
+    /** Timeout in minutes for executor session */
+    timeout_min: number;
+    /** Whether this step requires human input (pauses pipeline) */
+    requires_human: boolean;
+    /** Files executor should read at this step.
+     *  Supports {story} placeholder for current Story ID. */
+    claude_reads: string[];
+    /** Files/patterns executor may write at this step */
+    claude_writes: string[];
+    /** Shell command to run after executor exits (null = none).
+     *  Deterministic check, zero LLM tokens. */
+    post_check: string | null;
+    /** Fixed instruction for the dispatch prompt */
+    step_instruction: string;
+}
+/** Role definition for multi-executor team dispatch */
+export interface TeamRole {
+    claude_reads: string[];
+    claude_writes: string[];
+}
+/** Optional team_roles extension for multi-executor steps */
+export type TeamRoles = Record<string, TeamRole>;
+/** Dispatch mode based on story complexity */
+export type DispatchMode = "single" | "auto" | "team";
+/** Complexity-to-dispatch-mode mapping */
+export declare const DISPATCH_MODES: Record<string, DispatchMode>;
+export declare const STEP_RULES: Record<Exclude<Step, "bootstrap" | "done">, StepRule>;
+export declare const BOOTSTRAP_RULE: StepRule;
+export declare const DEFAULT_TEAM_ROLES: Record<string, TeamRoles>;
+/** Get the rule for a given step */
+export declare function getRule(step: Step): StepRule;
+/** Resolve {story} placeholders in file paths */
+export declare function resolvePaths(paths: string[], storyId: string): string[];
+/** Determine dispatch mode from complexity marker */
+export declare function getDispatchMode(complexity: string, parallelCount?: number): DispatchMode;
+/** Get the next step after a failure, using reason-based routing */
+export declare function getFailTarget(step: Step, reason: Reason | null): Step;
+/** Get ordered step sequence for the micro-waterfall loop */
+export declare function getStepSequence(): Step[];

package/dist/rules.js

@@ -0,0 +1,366 @@
+"use strict";
+/**
+ * rules.ts — Step Transition Rules Table
+ *
+ * Pure data, zero logic. Direct translation of the Protocol's Step Transition
+ * Rules YAML into TypeScript. The orchestrator looks up this table to decide:
+ * what files the executor reads, what it writes, what post-check to run,
+ * max attempts, timeout, and where to go on pass/fail.
+ *
+ * Projects can override defaults via `.ai/step-rules.yaml` (future).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TEAM_ROLES = exports.BOOTSTRAP_RULE = exports.STEP_RULES = exports.DISPATCH_MODES = void 0;
+exports.getRule = getRule;
+exports.resolvePaths = resolvePaths;
+exports.getDispatchMode = getDispatchMode;
+exports.getFailTarget = getFailTarget;
+exports.getStepSequence = getStepSequence;
+/** Complexity-to-dispatch-mode mapping */
+exports.DISPATCH_MODES = {
+    S: "single",
+    M: "auto", // check [P] count, enable team only if ≥ 2
+    L: "team",
+};
+// ─── Step Rules Table ────────────────────────────────────────────────────────
+exports.STEP_RULES = {
+    bdd: {
+        display_name: "BDD Scenario Writing",
+        next_on_pass: "sdd-delta",
+        on_fail: { default: "bdd" },
+        max_attempts: 3,
+        timeout_min: 5,
+        requires_human: false,
+        claude_reads: [
+            "PROJECT_CONTEXT.md",
+            "PROJECT_MEMORY.md",
+            ".ai/HANDOFF.md",
+        ],
+        claude_writes: ["docs/bdd/US-{story}.md"],
+        post_check: null,
+        step_instruction: "Based on MEMORY's NOW/NEXT, write BDD scenarios for this Story. " +
+            "Use RFC 2119 language, tag test levels (@unit, @integration, @component, @e2e, @perf(ID)). " +
+            "Mark unclear items [NEEDS CLARIFICATION]. " +
+            "Include Non-Goals section.",
+    },
+    "sdd-delta": {
+        display_name: "SDD Delta Spec",
+        next_on_pass: "contract",
+        on_fail: { default: "sdd-delta" },
+        max_attempts: 3,
+        timeout_min: 5,
+        requires_human: false,
+        claude_reads: [
+            "PROJECT_CONTEXT.md",
+            "PROJECT_MEMORY.md",
+            "docs/bdd/US-{story}.md",
+            "docs/sdd.md",
+            ".ai/HANDOFF.md",
+        ],
+        claude_writes: ["docs/deltas/US-{story}.md"],
+        post_check: null,
+        step_instruction: "Based on BDD scenarios, analyze affected modules, produce Delta Spec " +
+            "(ADDED / MODIFIED / REMOVED). Include Non-Goals / Out of Scope section. " +
+            "Never rewrite the entire SDD.",
+    },
+    contract: {
+        display_name: "API Contract Update",
+        next_on_pass: "review",
+        on_fail: { default: "contract" },
+        max_attempts: 2,
+        timeout_min: 5,
+        requires_human: false,
+        claude_reads: [
+            "docs/sdd.md",
+            "docs/deltas/US-{story}.md",
+            "docs/api/openapi.yaml",
+            ".ai/HANDOFF.md",
+        ],
+        claude_writes: ["docs/api/openapi.yaml"],
+        post_check: null,
+        step_instruction: "Based on Delta Spec, update affected endpoints/events in OpenAPI/AsyncAPI contracts. " +
+            "Only add or modify affected parts; don't rewrite the entire contract.",
+    },
+    review: {
+        display_name: "Review Checkpoint",
+        next_on_pass: "scaffold",
+        on_fail: {
+            default: "bdd",
+            needs_clarification: "bdd",
+            constitution_violation: "sdd-delta",
+            scope_warning: "sdd-delta",
+        },
+        max_attempts: 1,
+        timeout_min: 0, // human-paced, no timeout
+        requires_human: true,
+        claude_reads: [],
+        claude_writes: [],
+        post_check: null,
+        step_instruction: "", // not dispatched to executor
+    },
+    scaffold: {
+        display_name: "Test Scaffolding",
+        next_on_pass: "impl",
+        on_fail: { default: "scaffold" },
+        max_attempts: 2,
+        timeout_min: 5,
+        requires_human: false,
+        claude_reads: [
+            "docs/bdd/US-{story}.md",
+            "docs/nfr.md",
+            "docs/api/openapi.yaml",
+            ".ai/HANDOFF.md",
+        ],
+        claude_writes: ["*_test.go", "*.spec.ts"],
+        post_check: null, // Project-specific: configure via .ai/step-rules.yaml
+        step_instruction: "Based on BDD scenario tags and NFR table, produce corresponding test " +
+            "skeleton. All tests must fail (red). Use require for Given (preconditions), " +
+            "assert for Then (verification). Use Table-Driven tests for Scenario Outlines.",
+    },
+    impl: {
+        display_name: "Implementation",
+        next_on_pass: "verify",
+        on_fail: {
+            default: "impl",
+            constitution_violation: "sdd-delta",
+            needs_clarification: "review",
+            scope_warning: "review",
+        },
+        max_attempts: 5,
+        timeout_min: 10,
+        requires_human: false,
+        claude_reads: [
+            "docs/bdd/US-{story}.md",
+            "docs/sdd.md",
+            "docs/api/openapi.yaml",
+            ".ai/HANDOFF.md",
+        ],
+        claude_writes: ["*.go", "*.ts", "*.tsx"],
+        post_check: null, // Project-specific: configure via .ai/step-rules.yaml
+        step_instruction: "Read failing tests, write minimal code to make tests pass, then refactor. " +
+            "Only modify affected files and functions (Diff-Only principle). " +
+            "Don't refactor unrelated code.",
+    },
+    verify: {
+        display_name: "Verify (Quality Gate)",
+        next_on_pass: "update-memory",
+        on_fail: { default: "impl" },
+        max_attempts: 2,
+        timeout_min: 5,
+        requires_human: false,
+        claude_reads: [
+            "docs/bdd/US-{story}.md",
+            "docs/deltas/US-{story}.md",
+            "docs/sdd.md",
+            "docs/api/openapi.yaml",
+            "docs/constitution.md",
+            ".ai/HANDOFF.md",
+        ],
+        claude_writes: [],
+        post_check: null,
+        step_instruction: "Execute triple check: " +
+            "Completeness (all BDD scenarios have tests, all Delta items implemented), " +
+            "Correctness (tests pass, NFR thresholds met), " +
+            "Coherence (SDD merged Delta, contracts consistent, Constitution not violated). " +
+            "Merge Delta Spec into main SDD after all checks pass.",
+    },
+    "update-memory": {
+        display_name: "Update Memory",
+        next_on_pass: "done",
+        on_fail: { default: "update-memory" },
+        max_attempts: 2,
+        timeout_min: 3,
+        requires_human: false,
+        claude_reads: ["PROJECT_MEMORY.md", ".ai/HANDOFF.md"],
+        claude_writes: ["PROJECT_MEMORY.md", ".ai/history.md"],
+        post_check: null,
+        step_instruction: "Update MEMORY's NOW/NEXT based on completed work. " +
+            "Append DONE + LOG entry to .ai/history.md (session archive). " +
+            "Overwrite .ai/HANDOFF.md with latest session summary. " +
+            "Record current git commit hash.",
+    },
+    custom: {
+        display_name: "Custom Task",
+        next_on_pass: "update-memory",
+        on_fail: { default: "custom" },
+        max_attempts: 3,
+        timeout_min: 15,
+        requires_human: false,
+        claude_reads: [
+            "PROJECT_CONTEXT.md",
+            "PROJECT_MEMORY.md",
+            "docs/sdd.md",
+            "docs/constitution.md",
+            ".ai/HANDOFF.md",
+        ],
+        claude_writes: ["*"],
+        post_check: null,
+        step_instruction: "Execute the custom task described in the Human Instruction section above. " +
+            "Follow the project's Constitution constraints. " +
+            "Only modify files relevant to the task — don't refactor unrelated code. " +
+            "If the task is unclear, fill reason with needs_clarification.",
+    },
+};
+// ─── Custom Task Use Cases ──────────────────────────────────────────────────
+//
+// The "custom" step is a generic passthrough that lets OpenClaw forward ANY
+// instruction to Claude Code with full project context. Common use cases:
+//
+// ── Refactoring ──
+//   "Extract authentication logic into a separate auth module"
+//   "Rename all UserDTO references to UserResponse"
+//   "Convert class components to functional components with hooks"
+//   "Split monolithic service.ts into domain-specific modules"
+//
+// ── Code Review ──
+//   "Review src/api/ for security vulnerabilities"
+//   "Review PR #42 changes and list potential issues"
+//   "Check all error handling paths in the payment flow"
+//   "Audit dependencies for known CVEs"
+//
+// ── Bug Fix (hotfix, not full story) ──
+//   "Fix the race condition in WebSocket reconnection"
+//   "Debug why /api/users returns 500 on empty query"
+//   "Fix memory leak in event listener cleanup"
+//
+// ── DevOps / Infrastructure ──
+//   "Add GitHub Actions CI pipeline for lint + test + build"
+//   "Create Dockerfile and docker-compose.yml for local dev"
+//   "Set up pre-commit hooks for linting and formatting"
+//   "Configure Renovate for automated dependency updates"
+//
+// ── Documentation ──
+//   "Add JSDoc comments to all exported functions in src/api/"
+//   "Update README with current API endpoints and examples"
+//   "Generate OpenAPI spec from existing route handlers"
+//   "Write architecture decision record for database choice"
+//
+// ── Testing ──
+//   "Add unit tests for utils/validation.ts (target 90% coverage)"
+//   "Write integration tests for the checkout flow"
+//   "Add snapshot tests for all React components in src/ui/"
+//   "Set up E2E tests with Playwright for critical user paths"
+//
+// ── Dependency / Migration ──
+//   "Upgrade React from v17 to v18, fix breaking changes"
+//   "Migrate from Express to Fastify"
+//   "Replace moment.js with date-fns"
+//   "Migrate database schema: add soft delete to all entities"
+//
+// ── Performance ──
+//   "Profile and optimize the dashboard query (currently 3s)"
+//   "Add Redis caching for /api/products endpoint"
+//   "Implement virtual scrolling for the transaction list"
+//   "Lazy-load all route components with React.lazy"
+//
+// ── Security ──
+//   "Add rate limiting to all authentication endpoints"
+//   "Implement CSRF protection for form submissions"
+//   "Sanitize all user inputs in the search endpoint"
+//   "Add Content-Security-Policy headers"
+//
+// ── Cleanup ──
+//   "Remove all unused imports and dead code"
+//   "Standardize error response format across all endpoints"
+//   "Replace console.log with structured logger"
+//   "Fix all TypeScript strict mode errors"
+//
+// ─── Bootstrap Rule (special: one-time, not in the micro-waterfall loop) ─────
+exports.BOOTSTRAP_RULE = {
+    display_name: "Bootstrap",
+    next_on_pass: "bdd",
+    on_fail: { default: "bootstrap" },
+    max_attempts: 1,
+    timeout_min: 10,
+    requires_human: false,
+    claude_reads: [],
+    claude_writes: [
+        "PROJECT_CONTEXT.md",
+        "docs/sdd.md",
+        "docs/constitution.md",
+        "PROJECT_MEMORY.md",
+    ],
+    post_check: null,
+    step_instruction: "Set up the project using the Agentic Coding Framework. Produce: " +
+        "PROJECT_CONTEXT.md (Why/Who/What + tech stack + project structure), " +
+        "docs/sdd.md (module division + data model skeleton + inter-module interfaces), " +
+        "docs/constitution.md (3-5 inviolable architectural principles), " +
+        "PROJECT_MEMORY.md (initial state). " +
+        "Create directory structure: docs/bdd/, docs/deltas/, docs/api/, docs/ddd/ (if multi-domain).",
+};
+// ─── Team Roles (Multi-Executor, optional) ───────────────────────────────────
+exports.DEFAULT_TEAM_ROLES = {
+    impl: {
+        backend: {
+            claude_reads: [
+                "docs/sdd.md",
+                "docs/api/openapi.yaml",
+                "internal/**/*.go",
+            ],
+            claude_writes: ["*.go"],
+        },
+        frontend: {
+            claude_reads: ["docs/api/openapi.yaml", "src/components/**"],
+            claude_writes: ["*.ts", "*.tsx"],
+        },
+        test: {
+            claude_reads: [
+                "docs/bdd/US-{story}.md",
+                "docs/api/openapi.yaml",
+                "docs/nfr.md",
+            ],
+            claude_writes: ["*_test.go", "*.spec.ts"],
+        },
+        verify: {
+            claude_reads: [
+                "docs/bdd/US-{story}.md",
+                "docs/deltas/US-{story}.md",
+                "docs/api/openapi.yaml",
+                "docs/constitution.md",
+            ],
+            claude_writes: [],
+        },
+    },
+};
+// ─── Lookup Helpers ──────────────────────────────────────────────────────────
+/** Get the rule for a given step */
+function getRule(step) {
+    if (step === "bootstrap")
+        return exports.BOOTSTRAP_RULE;
+    if (step === "done")
+        throw new Error('No rule for "done" — story is complete');
+    return exports.STEP_RULES[step];
+}
+/** Resolve {story} placeholders in file paths */
+function resolvePaths(paths, storyId) {
+    return paths.map((p) => p.replace(/\{story\}/g, storyId));
+}
+/** Determine dispatch mode from complexity marker */
+function getDispatchMode(complexity, parallelCount = 0) {
+    const mode = exports.DISPATCH_MODES[complexity] ?? "single";
+    if (mode === "auto") {
+        return parallelCount >= 2 ? "team" : "single";
+    }
+    return mode;
+}
+/** Get the next step after a failure, using reason-based routing */
+function getFailTarget(step, reason) {
+    const rule = getRule(step);
+    if (reason && rule.on_fail[reason]) {
+        return rule.on_fail[reason];
+    }
+    return rule.on_fail.default;
+}
+/** Get ordered step sequence for the micro-waterfall loop */
+function getStepSequence() {
+    return [
+        "bdd",
+        "sdd-delta",
+        "contract",
+        "review",
+        "scaffold",
+        "impl",
+        "verify",
+        "update-memory",
+    ];
+}

package/dist/state.d.ts

@@ -0,0 +1,81 @@
+/**
+ * state.ts — STATE.json Type Definitions + Read / Write / Validate
+ *
+ * Maps directly to the Agentic Coding Protocol's STATE.json field specifications.
+ * All operations are synchronous file I/O — zero LLM tokens.
+ */
+/** Micro-waterfall steps, matching Protocol's valid step values */
+export type Step = "bootstrap" | "bdd" | "sdd-delta" | "contract" | "review" | "scaffold" | "impl" | "verify" | "update-memory" | "custom" | "done";
+/** Task type determines which pipeline to follow */
+export type TaskType = "story" | "custom";
+/** STATE.json status state machine:
+ *  pending → running → pass | failing | timeout | needs_human */
+export type Status = "pending" | "running" | "pass" | "failing" | "needs_human" | "timeout";
+/** Reason codes extracted from HANDOFF.md, driving reason-based routing */
+export type Reason = "constitution_violation" | "needs_clarification" | "nfr_missing" | "scope_warning" | "test_timeout";
+/** Test result summary */
+export interface TestResult {
+    pass: number;
+    fail: number;
+    skip: number;
+}
+/** Complete STATE.json schema — every field from the Protocol spec */
+export interface State {
+    /** Project identifier */
+    project: string;
+    /** Current User Story ID (e.g., "US-005") */
+    story: string | null;
+    /** Current micro-waterfall step */
+    step: Step;
+    /** Attempt count for current step (1-indexed) */
+    attempt: number;
+    /** Maximum attempts allowed (from rules table) */
+    max_attempts: number;
+    /** Current status */
+    status: Status;
+    /** Failure reason code (null = general failure/success) */
+    reason: Reason | null;
+    /** ISO 8601 timestamp when executor was dispatched */
+    dispatched_at: string | null;
+    /** ISO 8601 timestamp when executor completed */
+    completed_at: string | null;
+    /** Timeout in minutes (from rules table) */
+    timeout_min: number;
+    /** Test result summary */
+    tests: TestResult | null;
+    /** Names of failing tests */
+    failing_tests: string[];
+    /** Whether linting passed */
+    lint_pass: boolean | null;
+    /** Files modified in this run */
+    files_changed: string[];
+    /** Story IDs that block this story */
+    blocked_by: string[];
+    /** Human instruction transcribed from communication channel */
+    human_note: string | null;
+    /** Task type: "story" for micro-waterfall, "custom" for ad-hoc tasks */
+    task_type: TaskType;
+}
+/** Create a blank STATE.json for a new project */
+export declare function createInitialState(project: string): State;
+/** Resolve the STATE.json path for a project root */
+export declare function statePath(projectRoot: string): string;
+/** Read STATE.json from disk. Throws if file doesn't exist. */
+export declare function readState(projectRoot: string): State;
+/** Write STATE.json to disk. Creates .ai/ directory if needed. */
+export declare function writeState(projectRoot: string, state: State): void;
+/** Initialize .ai/STATE.json for a new project. No-op if already exists. */
+export declare function initState(projectRoot: string, project: string): {
+    created: boolean;
+    state: State;
+};
+/** Validate a State object. Throws on invalid fields. */
+export declare function validate(state: State): void;
+/** Check if a step has exceeded its timeout */
+export declare function isTimedOut(state: State): boolean;
+/** Check if current step has exhausted all attempts */
+export declare function isMaxedOut(state: State): boolean;
+/** Mark state as running with dispatch timestamp */
+export declare function markRunning(state: State): State;
+/** Mark state as completed (pass or failing) with timestamp */
+export declare function markCompleted(state: State, status: "pass" | "failing" | "needs_human", reason?: Reason | null): State;