@agentic-coding-framework/orchestrator-core 0.7.3 → 0.8.1

package/dist/dispatch.js

@@ -25,12 +25,54 @@ exports.queryProjectStatus = queryProjectStatus;
 exports.listProjects = listProjects;
 exports.startCustom = startCustom;
 exports.rollback = rollback;
+exports.reopen = reopen;
+exports.review = review;
+exports.triage = triage;
 exports.checkPrerequisites = checkPrerequisites;
 exports.generateChecklist = generateChecklist;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const state_1 = require("./state");
 const rules_1 = require("./rules");
+// ─── Config Constants ────────────────────────────────────────────────────────
+/** After N stories reach "done", automatically suggest/trigger a review session */
+const REVIEW_TRIGGER_THRESHOLD = 3;
+/**
+ * Step name alias map — CC executors derive step names from display_name
+ * or prompt context, which may not match ACO's internal step identifiers.
+ * Applied during applyHandoff() to normalize HANDOFF.step before the
+ * stale guard comparison.
+ *
+ * [FIX P0] Without this, valid HANDOFFs are rejected as "stale" because
+ * e.g. "api-contract" !== "contract", causing the pipeline to stall.
+ */
+const STEP_ALIAS_MAP = {
+    // contract step aliases
+    "api-contract": "contract",
+    "api_contract": "contract",
+    "contract-update": "contract",
+    "api-contract-update": "contract",
+    // scaffold step aliases
+    "test-scaffolding": "scaffold",
+    "test_scaffolding": "scaffold",
+    "scaffolding": "scaffold",
+    "test-scaffold": "scaffold",
+    // sdd-delta aliases
+    "sdd_delta": "sdd-delta",
+    "sdd": "sdd-delta",
+    "delta": "sdd-delta",
+    "delta-spec": "sdd-delta",
+    // verify aliases
+    "quality-gate": "verify",
+    "quality_gate": "verify",
+    // update-memory aliases
+    "update_memory": "update-memory",
+    "memory-update": "update-memory",
+    // impl aliases
+    "implementation": "impl",
+    // commit aliases
+    "commit-changes": "commit",
+};
 // ─── Main Dispatch Function ──────────────────────────────────────────────────
 /**
  * Core dispatch logic — direct translation of Protocol's dispatch(project).
@@ -167,13 +209,25 @@ function _dispatchInner(projectRoot, state, dryRun) {
         state.files_changed = [];
         // Check if we just reached "done"
         if (state.step === "done") {
+            // Clear reopened_from when story completes
+            state.reopened_from = null;
+            // Feature 3: Check if review should be triggered
+            let review_suggested = false;
+            const completedCount = countCompletedStories(projectRoot);
+            if (completedCount >= REVIEW_TRIGGER_THRESHOLD) {
+                review_suggested = true;
+            }
             if (!dryRun)
                 (0, state_1.writeState)(projectRoot, state);
-            return {
+            const result = {
                 type: "done",
                 story: state.story ?? "(no story)",
                 summary: `Story ${state.story} completed. All steps passed.`,
             };
+            if (review_suggested) {
+                result.review_suggested = true;
+            }
+            return result;
         }
         // Recurse: the new step might also require human
         const newRule = (0, rules_1.getRule)(state.step);
@@ -208,7 +262,25 @@ function _dispatchInner(projectRoot, state, dryRun) {
                         : "No specific reason."),
             };
         }
-        const target = (0, rules_1.getFailTarget)(state.step, state.reason);
+        // Feature 1: Escalation logic for post-reopen verify failures
+        // If verify fails after reopen with no explicit reason, escalate by rolling back one step deeper
+        let target = (0, rules_1.getFailTarget)(state.step, state.reason);
+        if (state.step === "verify" &&
+            state.reopened_from !== null &&
+            state.reason === null // only escalate for pure RED failure (no specific reason)
+        ) {
+            // Find the step before reopened_from
+            const earlierStep = getEarlierStep(state.reopened_from);
+            if (earlierStep !== null) {
+                // Escalate to the earlier step (overriding normal routing)
+                target = earlierStep;
+                if (!dryRun) {
+                    (0, state_1.appendLog)(projectRoot, "INFO", "dispatch", `Post-reopen verify failure escalation: ${state.step} → ${earlierStep} (was reopened at ${state.reopened_from})`);
+                }
+                // Clear reopened_from so we only escalate once
+                state.reopened_from = null;
+            }
+        }
         if (target !== state.step) {
             // Route to different step
             state.step = target;
@@ -244,12 +316,12 @@ function _dispatchInner(projectRoot, state, dryRun) {
         lines.push("");
         prompt = prompt + "\n" + lines.join("\n");
     }
+    // Detect framework adoption level so caller knows the context richness
+    const framework = detectFramework(projectRoot);
     if (!dryRun) {
         const running = (0, state_1.markRunning)(state);
         (0, state_1.writeState)(projectRoot, running);
     }
-    // Detect framework adoption level so caller knows the context richness
-    const framework = detectFramework(projectRoot);
     return {
         type: "dispatched",
         project: state.project,
@@ -568,6 +640,16 @@ function applyHandoff(projectRoot) {
             message: state.last_error,
         };
     }
+    // [FIX P0] Normalize HANDOFF step name — CC executors may write display-name
+    // variants (e.g. "api-contract" instead of "contract", "test-scaffolding"
+    // instead of "scaffold"). Without this, valid HANDOFFs are rejected as stale.
+    if (handoff.step) {
+        const normalized = STEP_ALIAS_MAP[handoff.step.toLowerCase()];
+        if (normalized) {
+            (0, state_1.appendLog)(projectRoot, "INFO", "applyHandoff", `Normalized HANDOFF step: "${handoff.step}" → "${normalized}"`);
+            handoff.step = normalized;
+        }
+    }
     // [FIX P0] Stale HANDOFF guard: if HANDOFF.step doesn't match STATE.step,
     // this HANDOFF is from a previous step (e.g., hook re-fires after dispatch
     // already advanced). Applying it would overwrite the current step's status
@@ -1103,6 +1185,393 @@ function rollback(projectRoot, targetStep, options = {}) {
         message: `Rolled back to "${targetStep}" (attempt 1, status: pending)`,
     };
 }
+// ─── Helper Functions for Features ────────────────────────────────────────────
+/**
+ * Count completed stories since last review by reading .ai/history.md
+ * and matching entries with reopen pattern.
+ */
+function countCompletedStories(projectRoot) {
+    try {
+        const historyPath = (0, path_1.join)(projectRoot, ".ai", "history.md");
+        if (!(0, fs_1.existsSync)(historyPath))
+            return 0;
+        const content = (0, fs_1.readFileSync)(historyPath, "utf-8");
+        // Count lines that match "### Reopen" pattern (each represents a completed story that was reopened)
+        // Plus we need to count stories that completed naturally
+        // For now, count any story-related lines in history
+        const matches = content.match(/### Reopen/g) || [];
+        return matches.length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Find the step that comes before a given step in the sequence.
+ * Returns null if the step is the first one (no earlier step).
+ */
+function getEarlierStep(step) {
+    const sequence = (0, rules_1.getStepSequence)();
+    const index = sequence.indexOf(step);
+    if (index <= 0)
+        return null;
+    return sequence[index - 1];
+}
+// ─── Reopen ──────────────────────────────────────────────────────────────────
+/**
+ * Reopen a completed story at a specified step.
+ *
+ * Unlike rollback() which moves backwards within an active story,
+ * reopen() specifically targets stories that have reached step "done".
+ * It resets state to the target step so the pipeline can re-execute from there.
+ *
+ * Use case: Review Session or triage found issues in a completed US —
+ * human decides to reopen it at a specific step (e.g., "impl", "verify").
+ *
+ * Guards:
+ *   - Story must be in "done" state (use rollback for active stories)
+ *   - Target step must be a valid pipeline step
+ *   - Cannot reopen to "done" (that's a no-op)
+ *
+ * [v0.8.0] FB-009: Review → Triage → Re-entry
+ */
+function reopen(projectRoot, targetStep, options = {}) {
+    let state;
+    try {
+        state = (0, state_1.readState)(projectRoot);
+    }
+    catch (err) {
+        return { type: "error", code: "STATE_NOT_FOUND", message: err.message, recoverable: false };
+    }
+    // Guard: story must be completed
+    if (state.step !== "done") {
+        (0, state_1.appendLog)(projectRoot, "ERROR", "reopen", `NOT_DONE: current step is "${state.step}", not "done". Use rollback instead.`);
+        return {
+            type: "error",
+            code: "NOT_DONE",
+            message: `Cannot reopen: story is at step "${state.step}", not "done". Use "rollback" for active stories.`,
+            recoverable: false,
+        };
+    }
+    // Cannot reopen to "done" (check before sequence validation since "done" isn't in sequence)
+    if (targetStep === "done") {
+        return {
+            type: "error",
+            code: "REOPEN_TO_DONE",
+            message: `Cannot reopen to "done" — story is already done.`,
+            recoverable: false,
+        };
+    }
+    // Validate target step
+    const sequence = (0, rules_1.getStepSequence)();
+    const targetIndex = targetStep === "bootstrap" ? -1 : sequence.indexOf(targetStep);
+    if (targetStep !== "bootstrap" && targetIndex === -1) {
+        (0, state_1.appendLog)(projectRoot, "ERROR", "reopen", `INVALID_TARGET: "${targetStep}"`);
+        return {
+            type: "error",
+            code: "INVALID_TARGET",
+            message: `Invalid reopen target "${targetStep}". Valid steps: bootstrap, ${sequence.join(", ")}`,
+            recoverable: false,
+        };
+    }
+    // Reset state to target step
+    const previousStep = state.step; // "done"
+    const rule = targetStep === "bootstrap"
+        ? (0, rules_1.getRule)("bootstrap")
+        : (0, rules_1.getRule)(targetStep);
+    state.step = targetStep;
+    state.status = "pending";
+    state.attempt = 1;
+    state.max_attempts = rule.max_attempts;
+    state.timeout_min = rule.timeout_min;
+    state.reason = null;
+    state.last_error = null;
+    state.files_changed = [];
+    state.dispatched_at = null;
+    state.completed_at = null;
+    state.tests = null;
+    state.failing_tests = [];
+    state.lint_pass = null;
+    state.human_note = options.humanNote ?? null;
+    state.reopened_from = targetStep; // Feature 1: Track reopen target for escalation
+    (0, state_1.writeState)(projectRoot, state);
+    (0, state_1.appendLog)(projectRoot, "INFO", "reopen", `Reopened story "${state.story}" from "${previousStep}" to "${targetStep}"${options.humanNote ? ` note: "${options.humanNote}"` : ""}`);
+    // Feature 2: Append entry to .ai/history.md
+    const isoTimestamp = new Date().toISOString();
+    const historyEntry = `### Reopen — ${state.story} → ${targetStep}
+- **Date**: ${isoTimestamp}
+- **From**: ${previousStep} → ${targetStep}
+- **Note**: ${options.humanNote ?? "N/A"}`;
+    (0, state_1.appendHistory)(projectRoot, historyEntry);
+    return {
+        type: "ok",
+        state,
+        message: `Reopened story "${state.story}" at step "${targetStep}" (attempt 1, status: pending)`,
+    };
+}
+// ─── Review (On-Demand Review Session) ───────────────────────────────────────
+/**
+ * Generate a Review Session prompt for the current project.
+ *
+ * This is a STATELESS operation — it reads project state but does NOT
+ * mutate STATE.json. The caller (CC executor) receives the prompt and
+ * runs the review; results are acted on by the human (reopen, new US, etc.).
+ *
+ * Works on non-ACF projects too (detectFramework level 0): generates a
+ * lighter review prompt based on whatever files exist.
+ *
+ * Review Session checks (from Lifecycle v0.9):
+ *   1. Code Review — diff quality, naming, duplication
+ *   2. Spec-Code Coherence — BDD ↔ tests ↔ impl alignment
+ *   3. Regression — all existing tests still pass
+ *   4. Security Scan — no hardcoded secrets, .gitignore coverage
+ *   5. Memory Audit — PROJECT_MEMORY accuracy
+ *
+ * [v0.8.0] FB-009: Review → Triage → Re-entry
+ */
+function review(projectRoot) {
+    const framework = detectFramework(projectRoot);
+    const prompt = buildReviewPrompt(projectRoot, framework.level);
+    return {
+        type: "review_prompt",
+        prompt,
+        fw_lv: framework.level,
+    };
+}
+/**
+ * Build the review session prompt based on framework adoption level.
+ */
+function buildReviewPrompt(projectRoot, fwLevel) {
+    const lines = [];
+    lines.push("═══════════════════════════════════════════════════════════════");
+    lines.push("  ON-DEMAND REVIEW SESSION");
+    lines.push("═══════════════════════════════════════════════════════════════");
+    lines.push("");
+    if (fwLevel >= 2) {
+        // Full ACF project — rich review
+        let state = null;
+        try {
+            state = (0, state_1.readState)(projectRoot);
+        }
+        catch { /* no state */ }
+        lines.push(`Project: ${state?.project ?? "(unknown)"}`);
+        lines.push(`Story: ${state?.story ?? "(no active story)"}`);
+        lines.push(`Current Step: ${state?.step ?? "(unknown)"}`);
+        lines.push("");
+        lines.push("## Review Checklist");
+        lines.push("");
+        lines.push("### 1. Code Review");
+        lines.push("- Check recent changes for naming consistency, duplication, dead code");
+        lines.push("- Verify diff-only discipline: only files related to the story should be modified");
+        lines.push("");
+        lines.push("### 2. Spec-Code Coherence");
+        lines.push("- Read BDD scenarios in docs/bdd/ and verify each has a corresponding test");
+        lines.push("- Read SDD Delta in docs/deltas/ and verify implementation matches");
+        lines.push("- Check that API contracts in docs/api/ are synchronized");
+        lines.push("");
+        lines.push("### 3. Regression");
+        lines.push("- Run the project's test suite and confirm all tests pass");
+        lines.push("- If tests fail, record them in ISSUES section of PROJECT_MEMORY.md");
+        lines.push("");
+        lines.push("### 4. Security Scan");
+        lines.push("- grep for common secret patterns: password=, apikey=, token=, BEGIN RSA PRIVATE KEY");
+        lines.push("- Verify .gitignore covers: .env, *.key, credentials.json, *.pem");
+        lines.push("- Confirm test fixtures use mock/fake values, not real credentials");
+        lines.push("");
+        lines.push("### 5. Memory Audit");
+        lines.push("- Read PROJECT_MEMORY.md and verify NOW/TESTS/NEXT/ISSUES sections are accurate");
+        lines.push("- Check .ai/history.md for completeness");
+        lines.push("- Verify HANDOFF.md reflects the latest session state");
+    }
+    else if (fwLevel === 1) {
+        // Partial ACF — moderate review
+        lines.push("## Review Checklist (Partial ACF Project)");
+        lines.push("");
+        lines.push("### 1. Code Review");
+        lines.push("- Check recent changes for quality, naming, duplication");
+        lines.push("");
+        lines.push("### 2. Spec Coherence");
+        lines.push("- If BDD/SDD docs exist, verify alignment with code");
+        lines.push("");
+        lines.push("### 3. Regression");
+        lines.push("- Run available test suite and confirm all tests pass");
+        lines.push("");
+        lines.push("### 4. Security Scan");
+        lines.push("- grep for hardcoded secrets (password=, apikey=, token=)");
+        lines.push("- Verify .gitignore covers sensitive file patterns");
+        lines.push("");
+        lines.push("### 5. Memory Check");
+        lines.push("- If PROJECT_MEMORY.md exists, verify it is up to date");
+    }
+    else {
+        // Non-ACF project — lightweight review
+        lines.push("## Review Checklist (Non-ACF Project)");
+        lines.push("");
+        lines.push("### 1. Code Review");
+        lines.push("- Review recent git changes (git log + git diff) for quality");
+        lines.push("- Check for dead code, duplication, naming issues");
+        lines.push("");
+        lines.push("### 2. Test Check");
+        lines.push("- Locate and run the project's test suite (if any)");
+        lines.push("- Report test results");
+        lines.push("");
+        lines.push("### 3. Security Scan");
+        lines.push("- grep for hardcoded secrets (password=, apikey=, token=)");
+        lines.push("- Check .gitignore for sensitive patterns");
+    }
+    lines.push("");
+    lines.push("═══════════════════════════════════════════════════════════════");
+    lines.push("  OUTPUT FORMAT");
+    lines.push("═══════════════════════════════════════════════════════════════");
+    lines.push("");
+    lines.push("For each check, report:");
+    lines.push("  PASS — <brief note>");
+    lines.push("  WARN — <issue description>");
+    lines.push("  FAIL — <issue description + suggested action>");
+    lines.push("");
+    lines.push("At the end, provide a summary with recommended actions:");
+    lines.push("  - REOPEN <US-XXX> at <step> — if existing story needs rework");
+    lines.push("  - NEW US — <brief description> — if a new story is needed");
+    lines.push("  - ISSUE — <description> — record in PROJECT_MEMORY.md ISSUES");
+    lines.push("  - ALL CLEAR — no issues found");
+    lines.push("");
+    return lines.join("\n");
+}
+// ─── Triage (ISSUES → Actionable Plan) ──────────────────────────────────────
+/**
+ * Read unfixed ISSUES from PROJECT_MEMORY.md and generate a triage prompt.
+ *
+ * This is a STATELESS operation — reads files but does NOT mutate STATE.json.
+ * The triage prompt asks the executor (CC) to classify each issue and
+ * recommend actions (reopen US, create new US, or dismiss).
+ *
+ * Requires PROJECT_MEMORY.md to exist with an ISSUES section.
+ *
+ * [v0.8.0] FB-009: Review → Triage → Re-entry
+ */
+function triage(projectRoot) {
+    const framework = detectFramework(projectRoot);
+    // Read PROJECT_MEMORY.md
+    const memoryPath = (0, path_1.join)(projectRoot, "PROJECT_MEMORY.md");
+    if (!(0, fs_1.existsSync)(memoryPath)) {
+        return {
+            type: "error",
+            code: "NO_MEMORY",
+            message: "PROJECT_MEMORY.md not found. Cannot triage without ISSUES section.",
+            recoverable: false,
+        };
+    }
+    const memory = (0, fs_1.readFileSync)(memoryPath, "utf-8");
+    const issues = parseIssuesFromMemory(memory);
+    if (issues.length === 0) {
+        return {
+            type: "error",
+            code: "NO_ISSUES",
+            message: "No unfixed ISSUES found in PROJECT_MEMORY.md. Nothing to triage.",
+            recoverable: false,
+        };
+    }
+    const prompt = buildTriagePrompt(projectRoot, issues, framework.level);
+    return {
+        type: "triage_prompt",
+        prompt,
+        issues,
+        fw_lv: framework.level,
+    };
+}
+/**
+ * Parse ISSUES lines from PROJECT_MEMORY.md.
+ * Looks for lines starting with "- [ ]" under a section containing "ISSUES".
+ * Filters out already-checked items "- [x]".
+ */
+function parseIssuesFromMemory(memory) {
+    const lines = memory.split("\n");
+    let inIssuesSection = false;
+    const issues = [];
+    for (const line of lines) {
+        // Detect ISSUES section header (## ISSUES, ### ISSUES, or just ISSUES:)
+        if (/^#{1,4}\s*ISSUES/i.test(line) || /^ISSUES\s*:/i.test(line)) {
+            inIssuesSection = true;
+            continue;
+        }
+        // Exit ISSUES section on next header
+        if (inIssuesSection && /^#{1,4}\s/.test(line) && !/ISSUES/i.test(line)) {
+            inIssuesSection = false;
+            continue;
+        }
+        // Collect unchecked items
+        if (inIssuesSection && /^-\s*\[\s*\]/.test(line)) {
+            issues.push(line.replace(/^-\s*\[\s*\]\s*/, "").trim());
+        }
+    }
+    return issues;
+}
+/**
+ * Build the triage prompt with parsed issues.
+ */
+function buildTriagePrompt(projectRoot, issues, fwLevel) {
+    const lines = [];
+    lines.push("═══════════════════════════════════════════════════════════════");
+    lines.push("  TRIAGE SESSION");
+    lines.push("═══════════════════════════════════════════════════════════════");
+    lines.push("");
+    let state = null;
+    try {
+        state = (0, state_1.readState)(projectRoot);
+    }
+    catch { /* no state */ }
+    if (state) {
+        lines.push(`Project: ${state.project ?? "(unknown)"}`);
+        lines.push(`Current Story: ${state.story ?? "(none)"}`);
+        lines.push(`Current Step: ${state.step}`);
+        lines.push("");
+    }
+    lines.push(`## Unfixed ISSUES (${issues.length})`);
+    lines.push("");
+    for (let i = 0; i < issues.length; i++) {
+        lines.push(`  ${i + 1}. ${issues[i]}`);
+    }
+    lines.push("");
+    lines.push("## Triage Instructions");
+    lines.push("");
+    lines.push("For each issue above, analyze and classify:");
+    lines.push("");
+    lines.push("  A. REOPEN <US-XXX> at <step>");
+    lines.push("     → Issue belongs to an existing story; reopen it at the appropriate step.");
+    lines.push("     → The human will run: orchestrator reopen <project> <step>");
+    lines.push("");
+    lines.push("  B. NEW US: <title>");
+    lines.push("     → Issue requires a new User Story. Write a 1-2 sentence description.");
+    lines.push("     → The human will create the US and run: orchestrator start-story <project> <US-XXX>");
+    lines.push("");
+    lines.push("  C. DISMISS: <reason>");
+    lines.push("     → Issue is resolved, duplicate, or no longer relevant.");
+    lines.push("     → The human will mark it [x] in PROJECT_MEMORY.md.");
+    lines.push("");
+    if (fwLevel >= 2) {
+        lines.push("## Context Files");
+        lines.push("Read these files to inform your triage decisions:");
+        lines.push("  - PROJECT_MEMORY.md (full context: NOW, TESTS, NEXT, ISSUES)");
+        lines.push("  - .ai/history.md (completed work log)");
+        lines.push("  - docs/bdd/ (BDD scenarios for existing stories)");
+        lines.push("  - docs/deltas/ (SDD deltas for existing stories)");
+        lines.push("");
+    }
+    lines.push("═══════════════════════════════════════════════════════════════");
+    lines.push("  OUTPUT FORMAT");
+    lines.push("═══════════════════════════════════════════════════════════════");
+    lines.push("");
+    lines.push("Produce a triage plan as a numbered list matching the issues above:");
+    lines.push("");
+    lines.push("  1. [A] REOPEN US-001 at impl — <reason>");
+    lines.push("  2. [B] NEW US: \"Add input validation for email field\" — <reason>");
+    lines.push("  3. [C] DISMISS — resolved in commit abc123");
+    lines.push("");
+    lines.push("End with a SUMMARY: X to reopen, Y new US, Z dismissed.");
+    lines.push("This plan is HUMAN-GATED — no actions will be taken automatically.");
+    lines.push("");
+    return lines.join("\n");
+}
 /**
  * Check if prerequisite files (claude_reads) exist before dispatching.
  * Only checks concrete paths (skips wildcards like *.go, **\/*.ts).