@agentic-coding-framework/orchestrator-core 0.2.0 → 0.3.1

package/dist/cli.js

@@ -8,6 +8,7 @@
  *   start-story <project-root> <story-id>       Begin a new User Story (micro-waterfall)
  *   start-custom <project-root> <instruction>   Begin a custom ad-hoc task
  *   dispatch <project-root>                     Dispatch next step (prints prompt)
+ *   peek <project-root>                         [FIX P1] Read-only dispatch preview
  *   apply-handoff <project-root>                Parse HANDOFF.md → update STATE
  *   approve <project-root> [note]               Approve review step
  *   reject <project-root> <reason> [note]       Reject review step
@@ -24,11 +25,12 @@ function usage() {
     console.error(`Usage: orchestrator <command> [args]
 
 Commands:
-  auto <project-root> <message...>                 ★ Unified entry — classify message & route automatically
+  auto <project-root> <message...>                 Unified entry — classify message & route automatically
   init <project-root> <project-name>              Initialize .ai/STATE.json
   start-story <project-root> <story-id>           Begin a new User Story (micro-waterfall)
   start-custom <project-root> <instruction>       Begin a custom ad-hoc task
   dispatch <project-root>                         Dispatch next step (prints prompt to stdout)
+  peek <project-root>                             [NEW] Read-only dispatch preview (no state mutation)
   apply-handoff <project-root>           Parse HANDOFF.md → update STATE.json
   post-check <project-root>              Run step's post_check command
   approve <project-root> [note]          Approve review step
@@ -138,7 +140,10 @@ try {
             }
             const label = args[2] || undefined; // optional label
             const agentTeams = args[3] === "--agent-teams";
-            const state = (0, dispatch_1.startCustom)(projectRoot, instruction, { label, agentTeams });
+            const state = (0, dispatch_1.startCustom)(projectRoot, instruction, {
+                label,
+                agentTeams,
+            });
             console.log(`Started custom task: "${instruction}"`);
             console.log(`  label: ${state.story}, step: ${state.step}, task_type: ${state.task_type}`);
             break;
@@ -162,14 +167,46 @@ try {
                     break;
                 case "blocked":
                     console.error(`[dispatch] BLOCKED: ${result.reason}`);
-                    process.exit(1);
+                    // [FIX P1] Use exit(0) — blocked is an expected orchestrator state,
+                    // not an error. exit(1) breaks dispatch-claude-code.sh (set -e).
+                    process.exit(0);
                     break;
                 case "already_running":
                     console.error(`[dispatch] Already running (${result.elapsed_min} min)`);
                     break;
                 case "timeout":
                     console.error(`[dispatch] TIMEOUT at ${result.step} (${result.elapsed_min} min)`);
-                    process.exit(1);
+                    // [FIX P1] Use exit(0) — timeout is an expected orchestrator state.
+                    // exit(1) would abort dispatch-claude-code.sh before it can retry.
+                    process.exit(0);
+                    break;
+            }
+            break;
+        }
+        // [FIX P1] New command: read-only dispatch preview
+        case "peek": {
+            const projectRoot = resolveRoot(args[0]);
+            const result = (0, dispatch_1.peek)(projectRoot);
+            switch (result.type) {
+                case "dispatched":
+                    console.log(result.prompt);
+                    console.error(`[peek] Would dispatch: step=${result.step} attempt=${result.attempt}`);
+                    break;
+                case "done":
+                    console.error(`[peek] DONE: ${result.summary}`);
+                    break;
+                case "needs_human":
+                    console.error(`[peek] NEEDS HUMAN REVIEW`);
+                    console.error(result.message);
+                    break;
+                case "blocked":
+                    console.error(`[peek] BLOCKED: ${result.reason}`);
+                    break;
+                case "already_running":
+                    console.error(`[peek] Already running (${result.elapsed_min} min)`);
+                    break;
+                case "timeout":
+                    console.error(`[peek] TIMEOUT at ${result.step} (${result.elapsed_min} min)`);
                     break;
             }
             break;
@@ -226,7 +263,11 @@ try {
             const projectRoot = resolveRoot(args[0]);
             const result = (0, dispatch_1.detectFramework)(projectRoot);
             console.log(JSON.stringify(result, null, 2));
-            const levelNames = ["Not adopted", "Partial adoption", "Full adoption"];
+            const levelNames = [
+                "Not adopted",
+                "Partial adoption",
+                "Full adoption",
+            ];
             console.error(`Framework adoption: Level ${result.level} — ${levelNames[result.level]}`);
             break;
         }
@@ -252,3 +293,4 @@ catch (err) {
     console.error(`Error: ${err.message}`);
     process.exit(1);
 }
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/dispatch.d.ts

@@ -5,35 +5,37 @@
  * to drive the micro-waterfall pipeline. All decisions are deterministic —
  * zero LLM tokens.
  *
- * Main entry point: dispatch(projectRoot)
+ * Main entry points:
+ *   dispatch(projectRoot)  — dispatch next step (mutates STATE)
+ *   peek(projectRoot)      — [FIX P1] read-only dispatch preview (no mutation)
  */
-import { type State, type Step, type Status, type Reason } from "./state";
-import { type StepRule } from "./rules";
+import { State } from "./state";
+import { StepRule } from "./rules";
 export type DispatchResult = {
     type: "dispatched";
-    step: Step;
+    step: string;
     attempt: number;
     prompt: string;
-    fw_lv: 0 | 1 | 2;
+    fw_lv: number;
 } | {
-    type: "blocked";
-    step: Step;
-    reason: string;
+    type: "done";
+    story: string;
+    summary: string;
 } | {
     type: "needs_human";
-    step: Step;
+    step: string;
     message: string;
 } | {
-    type: "done";
-    story: string;
-    summary: string;
+    type: "blocked";
+    step: string;
+    reason: string;
 } | {
     type: "already_running";
-    step: Step;
+    step: string;
     elapsed_min: number;
 } | {
     type: "timeout";
-    step: Step;
+    step: string;
     elapsed_min: number;
 };
 /**
@@ -47,30 +49,38 @@ export type DispatchResult = {
  * steps, etc.).
  */
 export declare function dispatch(projectRoot: string): DispatchResult;
+/**
+ * [FIX P1] Read-only dispatch preview — returns the same DispatchResult
+ * as dispatch() but never writes to STATE.json.
+ *
+ * Use cases:
+ *   - dispatch-claude-code.sh: check if dispatch would succeed before committing
+ *   - Monitoring / debugging without state contamination
+ *   - OpenClaw dry-run checks
+ */
+export declare function peek(projectRoot: string): DispatchResult;
 /**
  * Build the dispatch prompt from the template.
  * Pure template filling — zero LLM reasoning.
  */
 export declare function buildPrompt(state: State, rule: StepRule): string;
-/** Parsed result from HANDOFF.md's YAML front matter */
-export interface HandoffResult {
+export interface HandoffData {
     story: string | null;
     step: string | null;
     attempt: number | null;
-    status: Status | null;
-    reason: Reason | null;
+    status: string | null;
+    reason: string | null;
     files_changed: string[];
     tests_pass: number | null;
     tests_fail: number | null;
     tests_skip: number | null;
-    /** The markdown body (everything after the second ---) */
     body: string;
 }
 /**
  * Parse HANDOFF.md — prioritize YAML front matter, fallback to grep.
  * Direct translation of Protocol's hook pseudocode.
  */
-export declare function parseHandoff(projectRoot: string): HandoffResult | null;
+export declare function parseHandoff(projectRoot: string): HandoffData | null;
 /**
  * After executor exits, read HANDOFF.md and update STATE.json accordingly.
  * This is the TypeScript equivalent of the Protocol's post-execution hook.
@@ -93,7 +103,7 @@ export declare function approveReview(projectRoot: string, humanNote?: string):
 /**
  * Reject the review with a reason and optional note.
  */
-export declare function rejectReview(projectRoot: string, reason: Reason, humanNote?: string): void;
+export declare function rejectReview(projectRoot: string, reason: string, humanNote?: string): void;
 /**
  * Begin a new User Story. Resets state to bdd step with attempt 1.
  * Auto-initializes STATE.json if the project hasn't adopted the framework yet.
@@ -102,33 +112,10 @@ export declare function startStory(projectRoot: string, storyId: string, options
     agentTeams?: boolean;
 }): State;
 /**
- * Get a human-friendly project status summary.
- * OpenClaw calls this when the user asks "how's the project?" or "open project X".
- *
- * Returns structured data that OpenClaw LLM can translate to natural language.
+ * Detect whether a project uses the Agentic Coding Framework.
+ * OpenClaw calls this when the user asks "is this project using the framework?"
  */
-export interface ProjectStatus {
-    project: string;
-    task_type: string;
-    story: string | null;
-    step: string;
-    status: string;
-    attempt: number;
-    max_attempts: number;
-    reason: string | null;
-    tests: {
-        pass: number;
-        fail: number;
-        skip: number;
-    } | null;
-    lint_pass: boolean | null;
-    files_changed: string[];
-    blocked_by: string[];
-    human_note: string | null;
-    memory_summary: string | null;
-    has_framework: FrameworkDetection;
-}
-export interface FrameworkDetection {
+export declare function detectFramework(projectRoot: string): {
     has_state: boolean;
     has_memory: boolean;
     has_context: boolean;
@@ -136,62 +123,25 @@ export interface FrameworkDetection {
     has_sdd: boolean;
     has_handoff: boolean;
     has_history: boolean;
-    /** Adoption level: 0 = none, 1 = partial (some files), 2 = full (all core files) */
-    level: 0 | 1 | 2;
-}
-/**
- * Detect whether a project uses the Agentic Coding Framework.
- * OpenClaw calls this when the user asks "is this project using the framework?"
- */
-export declare function detectFramework(projectRoot: string): FrameworkDetection;
+    level: number;
+};
 /**
  * Get comprehensive project status for OpenClaw to summarize to the user.
- * Works for ANY project — with or without the Agentic Coding Framework.
- *
- * - Framework project (has STATE.json): returns full state + memory summary
- * - Non-framework project: returns framework detection + whatever files exist
  */
-export declare function queryProjectStatus(projectRoot: string): ProjectStatus;
-/** Project entry returned by listProjects */
-export interface ProjectEntry {
-    /** Project name (from STATE.json, package.json, or directory name) */
-    name: string;
-    /** Directory name relative to workspace root */
-    dir: string;
-    /** Current step ("none" if not using framework) */
-    step: string;
-    /** Current status ("not_initialized" if not using framework) */
-    status: string;
-    /** Current story ID */
-    story: string | null;
-    /** Whether this project uses the Agentic Coding Framework */
-    has_framework: boolean;
-}
+export declare function queryProjectStatus(projectRoot: string): Record<string, unknown>;
 /**
- * Scan a workspace directory for all projects — both framework and non-framework.
- * OpenClaw calls this when the user asks "list my projects" or "switch project".
- *
- * A directory is considered a "project" if it contains any of:
- * - .ai/STATE.json (framework project)
- * - package.json (Node.js project)
- * - go.mod (Go project)
- * - Cargo.toml (Rust project)
- * - pyproject.toml or setup.py (Python project)
- * - .git/ (any git repo)
+ * Scan a workspace directory for all projects.
  */
-export declare function listProjects(workspaceRoot: string): ProjectEntry[];
+export declare function listProjects(workspaceRoot: string): Record<string, unknown>[];
 /**
  * Begin a custom (ad-hoc) task. The orchestrator forwards the instruction
  * to Claude Code with full project context, without going through the
  * micro-waterfall pipeline.
  *
  * Pipeline: custom → update-memory → done
- * Auto-initializes STATE.json if the project hasn't adopted the framework yet.
- *
- * Use cases: refactoring, code review, bug fix, DevOps, documentation,
- * testing, migration, performance optimization, security, cleanup, etc.
  */
 export declare function startCustom(projectRoot: string, instruction: string, options?: {
     label?: string;
     agentTeams?: boolean;
 }): State;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}