@aipper/aiws 0.0.46 → 0.0.47

package/dist/commands/codex-status-skills.js

@@ -0,0 +1,54 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadTemplate } from "../spec.js";
+import { normalizeNewlines } from "../hash.js";
+import { findManagedBlock } from "../managed-blocks.js";
+import { pathExists, readText } from "../fs.js";
+import { listTemplateCodexSkills, resolveCodexSkillsDir } from "../codex-skills.js";
+/**
+ * @param {{ templateId: string, skillsDir?: string }} options
+ */
+export async function codexStatusSkillsCommand(options) {
+    const templateId = String(options.templateId || "workspace");
+    const tpl = await loadTemplate(templateId);
+    const skillsDir = resolveCodexSkillsDir(options.skillsDir);
+    const skillsDirIsSymlink = await fs
+        .lstat(skillsDir)
+        .then((st) => st.isSymbolicLink())
+        .catch(() => false);
+    const skillsDirReal = skillsDirIsSymlink ? await fs.realpath(skillsDir).catch(() => skillsDir) : skillsDir;
+    const skillFiles = await listTemplateCodexSkills(tpl);
+    /** @type {Array<{ name: string, status: "ok" | "missing" | "unmanaged" | "outdated" }>} */
+    const rows = [];
+    for (const sf of skillFiles) {
+        const destAbs = path.join(skillsDir, sf.skillName, "SKILL.md");
+        if (!(await pathExists(destAbs))) {
+            rows.push({ name: sf.skillName, status: "missing" });
+            continue;
+        }
+        const currentText = normalizeNewlines(await readText(destAbs));
+        const block = findManagedBlock(currentText, sf.blockId);
+        if (!block) {
+            rows.push({ name: sf.skillName, status: "unmanaged" });
+            continue;
+        }
+        rows.push({ name: sf.skillName, status: block.innerText === sf.innerText ? "ok" : "outdated" });
+    }
+    const counts = rows.reduce((acc, r) => {
+        acc[r.status] = (acc[r.status] || 0) + 1;
+        return acc;
+    }, { ok: 0, missing: 0, unmanaged: 0, outdated: 0 });
+    const header = skillsDirIsSymlink && skillsDirReal !== skillsDir ? `${skillsDir} -> ${skillsDirReal}` : skillsDir;
+    console.log(`✓ aiws codex status-skills: ${header}`);
+    console.log(`ok=${counts.ok} missing=${counts.missing} unmanaged=${counts.unmanaged} outdated=${counts.outdated}`);
+    for (const r of rows) {
+        console.log(`${r.status}\t${r.name}`);
+    }
+    if (counts.ok === 0 && counts.missing === rows.length && skillsDirIsSymlink) {
+        console.log("Note: skills dir is a symlink; if you installed to a different dir, pass --dir (or set CODEX_HOME).");
+    }
+    if (counts.missing > 0 || counts.outdated > 0) {
+        console.log("Next: aiws codex install-skills");
+    }
+}
+//# sourceMappingURL=codex-status-skills.js.map

package/dist/commands/codex-status-skills.js.map

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

package/dist/commands/codex-uninstall-prompts.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @param {{ templateId: string, promptsDir?: string }} options
+ */
+export declare function codexUninstallPromptsCommand(options: any): Promise<void>;

package/dist/commands/codex-uninstall-prompts.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { loadTemplate } from "../spec.js";
+import { normalizeNewlines } from "../hash.js";
+import { findManagedBlock } from "../managed-blocks.js";
+import { copyFile, pathExists, readText } from "../fs.js";
+import { codexBackupPathFor, codexBackupStamp, listTemplateCodexPrompts, resolveCodexPromptsDir } from "../codex-prompts.js";
+/**
+ * @param {{ templateId: string, promptsDir?: string }} options
+ */
+export async function codexUninstallPromptsCommand(options) {
+    const templateId = String(options.templateId || "workspace");
+    const tpl = await loadTemplate(templateId);
+    const promptsDir = resolveCodexPromptsDir(options.promptsDir);
+    const promptFiles = await listTemplateCodexPrompts(tpl);
+    const backupStamp = codexBackupStamp();
+    const backupDir = path.join(promptsDir, ".aiws", "backups", "codex-prompts", backupStamp);
+    /** @type {string[]} */
+    const removed = [];
+    /** @type {string[]} */
+    const skippedUnmanaged = [];
+    /** @type {string[]} */
+    const missing = [];
+    for (const pf of promptFiles) {
+        const destAbs = path.join(promptsDir, pf.filename);
+        if (!(await pathExists(destAbs))) {
+            missing.push(pf.filename);
+            continue;
+        }
+        const currentText = normalizeNewlines(await readText(destAbs));
+        const block = findManagedBlock(currentText, pf.blockId);
+        if (!block) {
+            skippedUnmanaged.push(pf.filename);
+            continue;
+        }
+        const backup = codexBackupPathFor(promptsDir, pf.filename, backupStamp);
+        await copyFile(destAbs, backup);
+        await fs.unlink(destAbs);
+        removed.push(pf.filename);
+    }
+    console.log(`✓ aiws codex uninstall-prompts: ${promptsDir}`);
+    if (removed.length > 0)
+        console.log(`removed: ${removed.join(", ")}`);
+    if (removed.length > 0)
+        console.log(`backup: ${backupDir}`);
+    if (skippedUnmanaged.length > 0)
+        console.log(`skipped (unmanaged): ${skippedUnmanaged.join(", ")}`);
+    if (missing.length > 0)
+        console.log(`missing: ${missing.join(", ")}`);
+}
+//# sourceMappingURL=codex-uninstall-prompts.js.map

package/dist/commands/codex-uninstall-prompts.js.map

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

package/dist/commands/codex-uninstall-skills.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @param {{ templateId: string, skillsDir?: string }} options
+ */
+export declare function codexUninstallSkillsCommand(options: any): Promise<void>;

package/dist/commands/codex-uninstall-skills.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { loadTemplate } from "../spec.js";
+import { normalizeNewlines } from "../hash.js";
+import { findManagedBlock } from "../managed-blocks.js";
+import { copyFile, pathExists, readText } from "../fs.js";
+import { codexSkillsBackupPathFor, codexSkillsBackupStamp, listTemplateCodexSkills, resolveCodexSkillsDir } from "../codex-skills.js";
+/**
+ * @param {{ templateId: string, skillsDir?: string }} options
+ */
+export async function codexUninstallSkillsCommand(options) {
+    const templateId = String(options.templateId || "workspace");
+    const tpl = await loadTemplate(templateId);
+    const skillsDir = resolveCodexSkillsDir(options.skillsDir);
+    const skillFiles = await listTemplateCodexSkills(tpl);
+    const backupStamp = codexSkillsBackupStamp();
+    const backupDir = path.join(skillsDir, ".aiws", "backups", "codex-skills", backupStamp);
+    /** @type {string[]} */
+    const removed = [];
+    /** @type {string[]} */
+    const skippedUnmanaged = [];
+    /** @type {string[]} */
+    const missing = [];
+    for (const sf of skillFiles) {
+        const destDir = path.join(skillsDir, sf.skillName);
+        const destAbs = path.join(destDir, "SKILL.md");
+        if (!(await pathExists(destAbs))) {
+            missing.push(sf.skillName);
+            continue;
+        }
+        const currentText = normalizeNewlines(await readText(destAbs));
+        const block = findManagedBlock(currentText, sf.blockId);
+        if (!block) {
+            skippedUnmanaged.push(sf.skillName);
+            continue;
+        }
+        const backup = codexSkillsBackupPathFor(skillsDir, sf.skillName, backupStamp);
+        await copyFile(destAbs, backup);
+        await fs.unlink(destAbs);
+        // Only remove the directory if it's empty after removing SKILL.md.
+        try {
+            await fs.rmdir(destDir);
+        }
+        catch {
+            // ignore
+        }
+        removed.push(sf.skillName);
+    }
+    console.log(`✓ aiws codex uninstall-skills: ${skillsDir}`);
+    if (removed.length > 0)
+        console.log(`removed: ${removed.join(", ")}`);
+    if (removed.length > 0)
+        console.log(`backup: ${backupDir}`);
+    if (skippedUnmanaged.length > 0)
+        console.log(`skipped (unmanaged): ${skippedUnmanaged.join(", ")}`);
+    if (missing.length > 0)
+        console.log(`missing: ${missing.join(", ")}`);
+}
+//# sourceMappingURL=codex-uninstall-skills.js.map

package/dist/commands/codex-uninstall-skills.js.map

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

package/dist/commands/goal-advance.d.ts

@@ -7,12 +7,30 @@ export interface GoalAdvanceOptions {
     phase?: string;
     /** If true, only show what would change without writing */
     dryRun?: boolean;
+    /** If true, output structured JSON for AI consumption */
+    json?: boolean;
+}
+export interface GoalAdvanceResult {
+    ok: boolean;
+    goalId: string;
+    previousPhase: string | null;
+    currentPhase: string | null;
+    status: "active" | "complete" | "blocked" | "error";
+    done: boolean;
+    nextActions: {
+        phase: string;
+        description: string;
+        needsUserInput: boolean;
+        blockers: string[];
+    } | null;
+    currentGroup: string | null;
+    message: string;
 }
 /**
  * `aiws goal advance` command handler.
  *
- * Advances a goal to a specified phase or auto-detects the next phase.
- * Validates state integrity before making changes.
+ * Completes the current phase (if in_progress), then advances to the next phase.
+ * Sets the next phase checkpoint to in_progress and writes updated state.
  */
 export declare function goalAdvanceCommand(options: GoalAdvanceOptions): Promise<{
     ok: boolean;

package/dist/commands/goal-advance.js

@@ -1,61 +1,118 @@
 import path from "node:path";
-import { VALID_PHASES, readGoalState, writeGoalState, validateGoalState, computeNextPhase, listPendingPhases, resolveGoalStatePath, } from "./goal-validate-state.js";
+import { VALID_PHASES, readGoalState, writeGoalState, validateGoalState, computeNextPhase, listPendingPhases, resolveGoalStatePath, getPhaseGuidance, } from "./goal-validate-state.js";
 /**
  * `aiws goal advance` command handler.
  *
- * Advances a goal to a specified phase or auto-detects the next phase.
- * Validates state integrity before making changes.
+ * Completes the current phase (if in_progress), then advances to the next phase.
+ * Sets the next phase checkpoint to in_progress and writes updated state.
  */
 export async function goalAdvanceCommand(options) {
-    // Resolve goal state file
     const statePath = await resolveGoalStatePath(options.goalDir, options.goalId);
     if (!statePath) {
-        const hint = options.goalId
-            ? `Goal state file not found: ${path.join(options.goalDir, `${options.goalId}.state.json`)}`
-            : "No goal state files found in " + options.goalDir;
-        return { ok: false, output: hint };
+        return formatResult({
+            ok: false,
+            goalId: options.goalId ?? "unknown",
+            previousPhase: null,
+            currentPhase: null,
+            status: "error",
+            done: false,
+            nextActions: null,
+            currentGroup: null,
+            message: options.goalId
+                ? `Goal state file not found: ${path.join(options.goalDir, `${options.goalId}.state.json`)}`
+                : "No goal state files found in " + options.goalDir,
+        }, options.json ?? false);
     }
     const goalId = options.goalId ?? path.basename(statePath, ".state.json");
     const state = await readGoalState(statePath);
     // Validate state integrity
     const validation = validateGoalState(state);
     if (!validation.valid) {
-        return {
+        return formatResult({
             ok: false,
-            output: `Goal ${goalId} state validation failed:\n${validation.errors.join("\n")}`,
-        };
+            goalId,
+            previousPhase: null,
+            currentPhase: state.current_phase ?? null,
+            status: "error",
+            done: false,
+            nextActions: null,
+            currentGroup: null,
+            message: `State validation failed:\n${validation.errors.join("\n")}`,
+        }, options.json ?? false);
     }
     if (options.phase) {
-        // Explicit phase advance
-        return advanceToExplicitPhase(statePath, state, goalId, options.phase, options.dryRun);
+        return advanceToExplicitPhase(statePath, state, goalId, options);
     }
-    // Auto-detect next phase
-    return autoAdvancePhase(statePath, state, goalId, options.dryRun);
+    return autoAdvancePhase(statePath, state, goalId, options);
 }
-async function advanceToExplicitPhase(statePath, state, goalId, phase, dryRun) {
+async function advanceToExplicitPhase(statePath, state, goalId, options) {
+    const phase = options.phase;
     if (!VALID_PHASES.includes(phase)) {
-        return {
+        return formatResult({
             ok: false,
-            output: `Invalid phase: "${phase}". Valid phases: ${VALID_PHASES.join(", ")}`,
-        };
+            goalId,
+            previousPhase: state.current_phase ?? null,
+            currentPhase: null,
+            status: "error",
+            done: false,
+            nextActions: null,
+            currentGroup: null,
+            message: `Invalid phase: "${phase}". Valid phases: ${VALID_PHASES.join(", ")}`,
+        }, options.json ?? false);
+    }
+    // Complete the current phase first
+    const prevPhase = state.current_phase ?? null;
+    if (prevPhase && prevPhase !== phase) {
+        const prevCp = state.checkpoints[prevPhase];
+        if (prevCp && prevCp.status === "in_progress") {
+            state.checkpoints[prevPhase] = {
+                ...prevCp,
+                status: "complete",
+                completed_at: new Date().toISOString(),
+            };
+        }
     }
-    // Check that all dependency phases are complete
+    // Verify all prerequisite phases are complete
     const phaseIdx = VALID_PHASES.indexOf(phase);
     for (let i = 0; i < phaseIdx; i++) {
         const depPhase = VALID_PHASES[i];
         const depCp = state.checkpoints[depPhase];
         if (depCp && depCp.status !== "complete") {
-            return {
+            return formatResult({
                 ok: false,
-                output: `Cannot advance to phase "${phase}": prerequisite phase "${depPhase}" is not complete (${depCp.status})`,
-            };
+                goalId,
+                previousPhase: prevPhase,
+                currentPhase: state.current_phase ?? null,
+                status: "blocked",
+                done: false,
+                nextActions: {
+                    phase: depPhase,
+                    description: `Prerequisite phase "${depPhase}" must be completed before advancing to "${phase}"`,
+                    needsUserInput: false,
+                    blockers: [`Phase ${depPhase} is ${depCp.status}`],
+                },
+                currentGroup: null,
+                message: `Cannot advance to "${phase}": prerequisite "${depPhase}" is ${depCp.status}`,
+            }, options.json ?? false);
         }
     }
-    if (dryRun) {
-        return {
+    if (options.dryRun) {
+        return formatResult({
             ok: true,
-            output: `[DRY RUN] Would advance ${goalId} to phase "${phase}"`,
-        };
+            goalId,
+            previousPhase: prevPhase,
+            currentPhase: phase,
+            status: "active",
+            done: false,
+            nextActions: {
+                phase,
+                description: `[DRY RUN] Would advance to phase "${phase}". No changes written.`,
+                needsUserInput: false,
+                blockers: [],
+            },
+            currentGroup: null,
+            message: `[DRY RUN] Would advance ${goalId} to phase "${phase}"`,
+        }, options.json ?? false);
     }
     // Initialize or update checkpoint for the target phase
     const existingCp = state.checkpoints[phase];
@@ -68,32 +125,89 @@ async function advanceToExplicitPhase(statePath, state, goalId, phase, dryRun) {
     state.current_phase = phase;
     state.updated_at = new Date().toISOString();
     await writeGoalState(statePath, state);
-    return {
+    const guidance = getPhaseGuidance(goalId, state);
+    return formatResult({
         ok: true,
-        output: `Advanced ${goalId} to phase "${phase}"`,
-    };
+        goalId,
+        previousPhase: prevPhase,
+        currentPhase: phase,
+        status: "active",
+        done: false,
+        nextActions: guidance,
+        currentGroup: null,
+        message: `Advanced ${goalId} to phase "${phase}"`,
+    }, options.json ?? false);
 }
-async function autoAdvancePhase(statePath, state, goalId, dryRun) {
+async function autoAdvancePhase(statePath, state, goalId, options) {
+    const prevPhase = state.current_phase ?? null;
+    // Step 1: If current phase is in_progress, complete it first
+    if (prevPhase) {
+        const prevCp = state.checkpoints[prevPhase];
+        if (prevCp && prevCp.status === "in_progress") {
+            // Mark current phase as complete
+            state.checkpoints[prevPhase] = {
+                ...prevCp,
+                status: "complete",
+                completed_at: new Date().toISOString(),
+            };
+        }
+    }
+    // Step 2: Compute next phase from the updated state
     const next = computeNextPhase(state);
     if (next.done) {
-        return { ok: true, output: `Goal ${goalId} complete` };
+        state.status = "complete";
+        state.updated_at = new Date().toISOString();
+        if (!options.dryRun) {
+            await writeGoalState(statePath, state);
+        }
+        return formatResult({
+            ok: true,
+            goalId,
+            previousPhase: prevPhase,
+            currentPhase: null,
+            status: "complete",
+            done: true,
+            nextActions: null,
+            currentGroup: null,
+            message: `Goal ${goalId} complete`,
+        }, options.json ?? false);
     }
-    if (next.phase === state.current_phase) {
-        // Current phase not yet complete — show what's pending
+    // If next phase is the same as previous (still needs work), report what's pending
+    if (!options.dryRun && next.phase === state.current_phase) {
         const pending = listPendingPhases(state);
-        return {
+        const guidance = getPhaseGuidance(goalId, state);
+        return formatResult({
             ok: true,
-            output: `Current phase "${state.current_phase}" not yet complete. Pending: ${pending.join(", ")}`,
-        };
+            goalId,
+            previousPhase: prevPhase,
+            currentPhase: state.current_phase ?? null,
+            status: "active",
+            done: false,
+            nextActions: guidance,
+            currentGroup: next.groupId,
+            message: `Phase "${state.current_phase}" not yet complete. Pending: ${pending.join(", ")}`,
+        }, options.json ?? false);
     }
     const groupInfo = next.groupId ? ` [group ${next.groupId}]` : "";
-    if (dryRun) {
-        return {
+    if (options.dryRun) {
+        return formatResult({
             ok: true,
-            output: `[DRY RUN] Would advance ${goalId} → "${next.phase}"${groupInfo}`,
-        };
+            goalId,
+            previousPhase: prevPhase,
+            currentPhase: next.phase,
+            status: "active",
+            done: false,
+            nextActions: {
+                phase: next.phase,
+                description: `[DRY RUN] Would advance to phase "${next.phase}"${groupInfo}. No changes written.`,
+                needsUserInput: false,
+                blockers: [],
+            },
+            currentGroup: next.groupId,
+            message: `[DRY RUN] Would advance ${goalId} → "${next.phase}"${groupInfo}`,
+        }, options.json ?? false);
     }
-    // Initialize or update checkpoint for the next phase
+    // Initialize checkpoint for the next phase
     const existingCp = state.checkpoints[next.phase];
     state.checkpoints[next.phase] = {
         status: "in_progress",
@@ -104,9 +218,52 @@ async function autoAdvancePhase(statePath, state, goalId, dryRun) {
     state.current_phase = next.phase;
     state.updated_at = new Date().toISOString();
     await writeGoalState(statePath, state);
-    return {
+    const guidance = getPhaseGuidance(goalId, state);
+    return formatResult({
         ok: true,
-        output: `Next: ${goalId} → "${next.phase}"${groupInfo}`,
+        goalId,
+        previousPhase: prevPhase,
+        currentPhase: next.phase,
+        status: "active",
+        done: false,
+        nextActions: guidance,
+        currentGroup: next.groupId,
+        message: `Next: ${goalId} → "${next.phase}"${groupInfo}`,
+    }, options.json ?? false);
+}
+function formatResult(result, json) {
+    if (!json) {
+        // Text output: include structured guidance as actionable text
+        let text = result.message;
+        if (result.nextActions && !result.done) {
+            text += `\n\nNext phase: ${result.nextActions.phase}`;
+            text += `\nAction: ${result.nextActions.description}`;
+            if (result.nextActions.blockers.length > 0) {
+                text += `\nBlockers:\n- ${result.nextActions.blockers.join("\n- ")}`;
+            }
+            if (result.nextActions.needsUserInput) {
+                text += "\n⚠️  User input required before continuing.";
+            }
+        }
+        return { ok: result.ok, output: text };
+    }
+    // JSON output: structured for AI consumption
+    const jsonOutput = {
+        ok: result.ok,
+        goal_id: result.goalId,
+        previous_phase: result.previousPhase,
+        current_phase: result.currentPhase,
+        status: result.status,
+        done: result.done,
+        next_actions: result.nextActions ? {
+            phase: result.nextActions.phase,
+            description: result.nextActions.description,
+            needs_user_input: result.nextActions.needsUserInput,
+            blockers: result.nextActions.blockers,
+        } : null,
+        current_group: result.currentGroup,
+        message: result.message,
     };
+    return { ok: result.ok, output: JSON.stringify(jsonOutput, null, 2) };
 }
 //# sourceMappingURL=goal-advance.js.map

package/dist/commands/goal-advance.js.map

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

package/dist/commands/goal-help.js

@@ -2,12 +2,13 @@ export function printGoalHelp() {
     console.log(`aiws goal
 
 Usage:
-  aiws goal advance [--goal-id <id>] [--phase <phase>] [--dry-run]
+  aiws goal advance [--goal-id <id>] [--phase <phase>] [--dry-run] [--json]
   aiws goal validate-state [--goal-id <id>]
 
 Subcommands:
   advance          Advance a goal to the next phase (auto-detect) or to an
-                   explicit phase (--phase). Validates state before advancing.
+                   explicit phase (--phase). Completes current phase first if
+                   it is in_progress, then starts the next phase.
   validate-state   Validate one or all goal state files for structural
                    integrity. Reports errors and warnings.
 
@@ -18,6 +19,9 @@ Options:
                    intake, goal_def, dep_check, ws_analysis, plan, dev,
                    review, finish
   --dry-run        Show what would change without writing (advance only)
+  --json           Output structured JSON for AI consumption. Includes
+                   next_actions guidance: phase name, description, blockers,
+                   and whether user input is needed.
 
 Notes:
   - Phase sequence is enforced: no phase can complete before its predecessors.

package/dist/commands/goal-help.js.map

@@ -1 +1 @@
-{"version":3,"file":"goal-help.js","sourceRoot":"","sources":["../../src/commands/goal-help.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;CAwBb,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"goal-help.js","sourceRoot":"","sources":["../../src/commands/goal-help.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4Bb,CAAC,CAAC;AACH,CAAC"}

package/dist/commands/goal-validate-state.d.ts

@@ -4,7 +4,7 @@
  */
 export declare const VALID_PHASES: readonly string[];
 export interface GoalCheckpoint {
-    status: "pending" | "in_progress" | "complete";
+    status: "pending" | "in_progress" | "complete" | "failed";
     attempts: number;
     completed_at: string | null;
     error: string | null;
@@ -75,6 +75,21 @@ export declare function computeNextPhase(state: GoalState): {
     done: boolean;
     reason: string;
 };
+/**
+ * Per-phase guidance descriptions for AI consumption.
+ * Maps each VALID_PHASE to a brief "what to do in this phase" instruction.
+ */
+export declare const PHASE_GUIDANCE: Record<string, string>;
+/**
+ * Get next-actions guidance for the current phase of a goal state.
+ * Returns a structured description telling the AI what to do next.
+ */
+export declare function getPhaseGuidance(goalId: string, state: GoalState): {
+    phase: string;
+    description: string;
+    needsUserInput: boolean;
+    blockers: string[];
+};
 /**
  * Collect pending (non-complete) phases from checkpoints.
  */