@aipper/aiws 0.0.47 → 0.0.49

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

@@ -0,0 +1,271 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { goalAdvanceCommand } from "./goal-advance.js";
+import { VALID_PHASES, createInitialGoalState, analyzeGoalDirtyState, healGoalState, validateGoalState, writeGoalState, readGoalState, } from "./goal-validate-state.js";
+import { goalValidateStateCommand } from "./goal-validate.js";
+function allCompleteState(goalId, overall) {
+    const base = createInitialGoalState(goalId);
+    const now = new Date().toISOString();
+    for (const phase of VALID_PHASES) {
+        base.checkpoints[phase] = {
+            status: "complete",
+            attempts: 1,
+            completed_at: now,
+            error: null,
+        };
+    }
+    base.status = overall;
+    base.current_phase = "finish";
+    return base;
+}
+function midState(goalId, current) {
+    const base = createInitialGoalState(goalId);
+    const now = new Date().toISOString();
+    const idx = VALID_PHASES.indexOf(current);
+    for (let i = 0; i < idx; i++) {
+        const p = VALID_PHASES[i];
+        base.checkpoints[p] = {
+            status: "complete",
+            attempts: 1,
+            completed_at: now,
+            error: null,
+        };
+    }
+    base.checkpoints[current] = {
+        status: "in_progress",
+        attempts: 1,
+        completed_at: null,
+        error: null,
+    };
+    base.current_phase = current;
+    base.status = "active";
+    return base;
+}
+describe("goal dirty analysis + heal", () => {
+    it("detects all checkpoints complete but status still active", () => {
+        const state = allCompleteState("G-TEST", "active");
+        const dirty = analyzeGoalDirtyState(state);
+        expect(dirty.dirty).toBe(true);
+        expect(dirty.reasons).toContain("all_checkpoints_complete_status_not_complete");
+    });
+    it("detects status active with current_phase past all complete", () => {
+        const state = allCompleteState("G-TEST", "active");
+        state.current_phase = "dev";
+        const dirty = analyzeGoalDirtyState(state);
+        expect(dirty.dirty).toBe(true);
+        expect(dirty.reasons).toContain("status_active_current_phase_after_all_complete");
+    });
+    it("heals complete+active to status=complete", () => {
+        const state = allCompleteState("G-TEST", "active");
+        const heal = healGoalState(state);
+        expect(heal.healed).toBe(true);
+        expect(heal.state.status).toBe("complete");
+        expect(analyzeGoalDirtyState(heal.state).dirty).toBe(false);
+    });
+    it("heals status=complete with incomplete checkpoints by reopening active", () => {
+        const state = allCompleteState("G-TEST", "complete");
+        state.checkpoints["finish"] = {
+            status: "pending",
+            attempts: 0,
+            completed_at: null,
+            error: null,
+        };
+        const dirty = analyzeGoalDirtyState(state);
+        expect(dirty.dirty).toBe(true);
+        expect(dirty.reasons).toContain("status_complete_with_incomplete_checkpoints");
+        const heal = healGoalState(state);
+        expect(heal.state.status).toBe("active");
+        expect(heal.state.current_phase).toBe("finish");
+    });
+    it("heals missing completed_at on complete phases", () => {
+        const state = midState("G-TEST", "goal_def");
+        state.checkpoints["intake"] = {
+            status: "complete",
+            attempts: 1,
+            completed_at: null,
+            error: null,
+        };
+        const dirty = analyzeGoalDirtyState(state);
+        expect(dirty.reasons).toContain("complete_missing_completed_at");
+        const heal = healGoalState(state);
+        expect(heal.state.checkpoints["intake"].completed_at).toBeTruthy();
+    });
+    it("validateGoalState rejects dirty by default", () => {
+        const state = allCompleteState("G-TEST", "active");
+        const result = validateGoalState(state);
+        expect(result.valid).toBe(false);
+        expect(result.errors.some((e) => e.includes("Dirty state"))).toBe(true);
+    });
+    it("validateGoalState can skip dirty with includeDirty:false", () => {
+        const state = allCompleteState("G-TEST", "active");
+        // structural only — all complete is structurally fine
+        const result = validateGoalState(state, { includeDirty: false });
+        expect(result.valid).toBe(true);
+    });
+});
+describe("goalAdvanceCommand sole writer + heal", () => {
+    let tmpDir;
+    let goalDir;
+    beforeEach(async () => {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "goal-advance-"));
+        goalDir = path.join(tmpDir, ".aiws", "goals");
+        await fs.mkdir(goalDir, { recursive: true });
+    });
+    afterEach(async () => {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    it("auto-advances in_progress phase to next", async () => {
+        const state = midState("G-ADV", "intake");
+        await writeGoalState(path.join(goalDir, "G-ADV.state.json"), state);
+        const { ok, output } = await goalAdvanceCommand({
+            goalDir,
+            goalId: "G-ADV",
+            json: true,
+        });
+        expect(ok).toBe(true);
+        const parsed = JSON.parse(output);
+        expect(parsed.ok).toBe(true);
+        expect(parsed.current_phase).toBe("goal_def");
+        expect(parsed.sole_writer).toBe("aiws goal advance");
+        const after = await readGoalState(path.join(goalDir, "G-ADV.state.json"));
+        expect(after.checkpoints["intake"].status).toBe("complete");
+        expect(after.checkpoints["goal_def"].status).toBe("in_progress");
+        expect(after.current_phase).toBe("goal_def");
+    });
+    it("refuses dirty state without --heal", async () => {
+        const state = allCompleteState("G-DIRTY", "active");
+        await writeGoalState(path.join(goalDir, "G-DIRTY.state.json"), state);
+        const { ok, output } = await goalAdvanceCommand({
+            goalDir,
+            goalId: "G-DIRTY",
+        });
+        expect(ok).toBe(false);
+        expect(output).toMatch(/Dirty goal state/i);
+        expect(output).toMatch(/--heal/);
+    });
+    it("heals all-complete+active to complete with --heal", async () => {
+        const state = allCompleteState("G-HEAL", "active");
+        await writeGoalState(path.join(goalDir, "G-HEAL.state.json"), state);
+        const { ok, output } = await goalAdvanceCommand({
+            goalDir,
+            goalId: "G-HEAL",
+            heal: true,
+            json: true,
+        });
+        expect(ok).toBe(true);
+        const parsed = JSON.parse(output);
+        expect(parsed.done || parsed.status === "complete").toBe(true);
+        const after = await readGoalState(path.join(goalDir, "G-HEAL.state.json"));
+        expect(after.status).toBe("complete");
+    });
+    it("heals status complete with incomplete checkpoints", async () => {
+        const state = allCompleteState("G-REOPEN", "complete");
+        state.checkpoints["finish"] = {
+            status: "pending",
+            attempts: 0,
+            completed_at: null,
+            error: null,
+        };
+        await writeGoalState(path.join(goalDir, "G-REOPEN.state.json"), state);
+        const { ok } = await goalAdvanceCommand({
+            goalDir,
+            goalId: "G-REOPEN",
+            heal: true,
+        });
+        expect(ok).toBe(true);
+        const after = await readGoalState(path.join(goalDir, "G-REOPEN.state.json"));
+        expect(after.status).toBe("active");
+        expect(after.current_phase).toBe("finish");
+    });
+    it("migrates missing state.json from active .md with --heal", async () => {
+        const md = `---
+ws_goal:
+  version: 1
+  state: active
+  iteration: 1
+---
+
+# G-MIG: migration test
+`;
+        await fs.writeFile(path.join(goalDir, "G-MIG.md"), md, "utf8");
+        const { ok, output } = await goalAdvanceCommand({
+            goalDir,
+            goalId: "G-MIG",
+            heal: true,
+            json: true,
+        });
+        expect(ok).toBe(true);
+        const statePath = path.join(goalDir, "G-MIG.state.json");
+        await expect(fs.access(statePath)).resolves.toBeUndefined();
+        const after = await readGoalState(statePath);
+        expect(after.status).toBe("active");
+        expect(after.current_phase).toBe("intake");
+        expect(after.checkpoints["intake"].status).toBe("in_progress");
+        expect(output).toMatch(/Migrat|heal|intake/i);
+    });
+    it("dry-run does not write", async () => {
+        const state = midState("G-DRY", "intake");
+        const statePath = path.join(goalDir, "G-DRY.state.json");
+        await writeGoalState(statePath, state);
+        const before = await fs.readFile(statePath, "utf8");
+        const { ok, output } = await goalAdvanceCommand({
+            goalDir,
+            goalId: "G-DRY",
+            dryRun: true,
+        });
+        expect(ok).toBe(true);
+        expect(output).toMatch(/DRY RUN/i);
+        const after = await fs.readFile(statePath, "utf8");
+        // dry-run may still have same logical content (updated_at may differ only if wrote)
+        const afterState = JSON.parse(after);
+        expect(afterState.checkpoints.intake.status).toBe("in_progress");
+        expect(afterState.current_phase).toBe("intake");
+        // ensure content wasn't rewritten with completed intake
+        expect(JSON.parse(before).checkpoints.intake.status).toBe("in_progress");
+    });
+    it("blocks advance to phase when prerequisite incomplete", async () => {
+        const state = midState("G-BLOCK", "intake");
+        await writeGoalState(path.join(goalDir, "G-BLOCK.state.json"), state);
+        const { ok, output } = await goalAdvanceCommand({
+            goalDir,
+            goalId: "G-BLOCK",
+            phase: "dev",
+        });
+        expect(ok).toBe(false);
+        expect(output).toMatch(/prerequisite|Cannot advance/i);
+    });
+});
+describe("goalValidateStateCommand heal", () => {
+    let tmpDir;
+    let goalDir;
+    beforeEach(async () => {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "goal-validate-"));
+        goalDir = path.join(tmpDir, ".aiws", "goals");
+        await fs.mkdir(goalDir, { recursive: true });
+    });
+    afterEach(async () => {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    it("fails dirty without heal and passes after heal", async () => {
+        const state = allCompleteState("G-V", "active");
+        await writeGoalState(path.join(goalDir, "G-V.state.json"), state);
+        const fail = await goalValidateStateCommand({
+            goalDir,
+            goalId: "G-V",
+        });
+        expect(fail.ok).toBe(false);
+        expect(fail.output).toMatch(/Dirty|FAIL/i);
+        const healed = await goalValidateStateCommand({
+            goalDir,
+            goalId: "G-V",
+            heal: true,
+        });
+        expect(healed.ok).toBe(true);
+        expect(healed.output).toMatch(/Healed|PASS/i);
+        const after = await readGoalState(path.join(goalDir, "G-V.state.json"));
+        expect(after.status).toBe("complete");
+    });
+});
+//# sourceMappingURL=goal-advance.test.js.map

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

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

package/dist/commands/goal-help.js

@@ -1,32 +1,49 @@
 export function printGoalHelp() {
     console.log(`aiws goal
 
+Authority CLI for goal state machine (contract §10 / TOOLING-003D).
+\`aiws goal advance\` is the sole phase-boundary writer for
+\`.aiws/goals/<id>.state.json\` (checkpoint status, current_phase, status).
+Skills/agents MUST NOT hand-edit those fields — call advance at each phase boundary.
+
 Usage:
-  aiws goal advance [--goal-id <id>] [--phase <phase>] [--dry-run] [--json]
-  aiws goal validate-state [--goal-id <id>]
+  aiws goal advance [--goal-id <id>] [--phase <phase>] [--dry-run] [--heal] [--json]
+  aiws goal validate-state [--goal-id <id>] [--heal] [--json]
+  aiws goal help
 
 Subcommands:
-  advance          Advance a goal to the next phase (auto-detect) or to an
-                   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.
+  advance          Sole writer: complete current in_progress phase (if any),
+                   validate, then start next phase (or --phase). Use --heal for
+                   dirty FSM recovery or §7.6 migration (active .md, no state.json).
+  validate-state   Validate one or all goal state files (structure + dirty).
+                   With --heal, write healed snapshots (same heal path as advance).
 
 Options:
   --goal-id <id>   Target a specific goal by ID (e.g., G-014). If omitted,
-                   auto-detects the active goal.
-  --phase <phase>  Explicit target phase. Valid values:
+                   auto-detects the active goal (advance) or validates all
+                   (validate-state).
+  --phase <phase>  Explicit target phase (advance only). Valid values:
                    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.
+  --dry-run        Show what would change without writing
+  --heal           Heal dirty state before advance, or heal on validate-state:
+                   - all checkpoints complete but status still active → complete
+                   - status complete with incomplete checkpoints → reopen active
+                   - missing completed_at / missing checkpoint shells
+                   - missing state.json with active/paused .md → migrate (§7.6)
+  --json           Structured JSON for AI (includes next_actions, sole_writer,
+                   heal_actions when applicable)
+
+Dirty / heal:
+  Hand-edited or drifted state is rejected by validate-state and by advance
+  (without --heal). Recovery is always via CLI heal path — not freehand JSON.
 
 Notes:
-  - Phase sequence is enforced: no phase can complete before its predecessors.
-  - State files are stored as .aiws/goals/<goal-id>.state.json.
+  - Phase sequence is enforced: no phase completes before its predecessors.
+  - State files: .aiws/goals/<goal-id>.state.json (atomic write).
   - Groups (if defined) are walked in topological order.
+  - Platform continuation (Ralph/Boulder) may re-invoke advance; they do not
+    own the FSM write path.
 `);
 }
 //# sourceMappingURL=goal-help.js.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4Bb,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6Cb,CAAC,CAAC;AACH,CAAC"}

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

@@ -32,6 +32,62 @@ export interface GoalState {
     created_at?: string;
     updated_at?: string;
 }
+/**
+ * Dirty-state reasons that validate-state can reject and advance --heal can fix.
+ * Sole writer for phase transitions remains `aiws goal advance` (contract §10).
+ */
+export type GoalDirtyReason = "all_checkpoints_complete_status_not_complete" | "status_active_current_phase_after_all_complete" | "status_complete_with_incomplete_checkpoints" | "complete_missing_completed_at" | "missing_required_checkpoints" | "current_phase_mismatch";
+export interface GoalDirtyAnalysis {
+    dirty: boolean;
+    reasons: GoalDirtyReason[];
+    details: string[];
+    healable: boolean;
+}
+/**
+ * Detect semantic dirty states beyond pure structural validation.
+ * Examples: all checkpoints complete but overall status still active;
+ * status complete while some phases pending; missing completed_at.
+ */
+export declare function analyzeGoalDirtyState(state: GoalState): GoalDirtyAnalysis;
+export interface HealGoalStateResult {
+    healed: boolean;
+    state: GoalState;
+    actions: string[];
+    dirtyBefore: GoalDirtyAnalysis;
+}
+/**
+ * Heal dirty goal state into a legal FSM snapshot.
+ * Does not invent progress: only reconciles status/current_phase/completed_at/missing shells.
+ * Phase boundary transitions after heal still go through advance.
+ */
+export declare function healGoalState(state: GoalState): HealGoalStateResult;
+/**
+ * Create a minimal valid initial goal state (all pending).
+ */
+export declare function createInitialGoalState(goalId: string): GoalState;
+/**
+ * Parse ws_goal.state from goal markdown frontmatter (simple, no full YAML dep).
+ */
+export declare function parseGoalMarkdownState(mdContent: string): {
+    state: string | null;
+    iteration: number | null;
+};
+/**
+ * Find goals that have .md with active/paused but no .state.json (migration candidates §7.6).
+ */
+export declare function findGoalsNeedingMigration(goalDir: string): Promise<Array<{
+    goalId: string;
+    mdPath: string;
+    mdState: string;
+}>>;
+/**
+ * Migrate legacy goal .md → state.json (all checkpoints pending, current_phase null per §7.6).
+ */
+export declare function migrateGoalFromMarkdown(goalDir: string, goalId: string): Promise<{
+    ok: boolean;
+    statePath: string;
+    message: string;
+}>;
 /**
  * Validate a goal state's structural integrity.
  *
@@ -43,7 +99,9 @@ export interface GoalState {
  * e) Group statuses are valid (pending/in_progress/complete)
  * f) Groups with a `phase` set must have that parent phase complete
  */
-export declare function validateGoalState(state: GoalState): {
+export declare function validateGoalState(state: GoalState, options?: {
+    includeDirty?: boolean;
+}): {
     valid: boolean;
     errors: string[];
     warnings: string[];