@selesai/code 0.3.10 → 0.5.0

package/docs/workflows.md

@@ -1,6 +1,6 @@
 # Workflows
 
-Selesai ships a workflow engine under `src/extensions/workflow/`. It powers the built-in `prototype` and `quick` workflows and is designed so you can add a new workflow mode as a thin config file — no engine changes.
+Selesai ships a workflow engine under `src/extensions/workflow/`. It powers the built-in `prototype`, `quick`, and `task` workflows and is designed so you can add a new workflow mode as a thin config file — no engine changes.
 
 ## How it fits together
 
@@ -8,15 +8,18 @@ Selesai ships a workflow engine under `src/extensions/workflow/`. It powers the
 src/extensions/workflow/
   package.json          pi package manifest; loads ./extension.ts as the single entry
   state-machine.ts      pure phase state machine (no fs, no pi API)
-  adapter.ts            pi wiring: tools, commands, events, fs, agent continuation
+  adapter.ts            pi wiring: tools, commands, events, fs, durable-state lifecycle
+  run-state.ts          versioned atomic workflow.json load/save/discovery
   extension.ts          single pi extension that mounts every workflow mode
   modes/
     prototype.ts        mode config + registration object (exported as `prototypeMode`)
     quick.ts            mode config + registration object (exported as `quickMode`)
+    task.ts             mode config + registration object (exported as `taskMode`)
 ```
 
 - **`state-machine.ts`** is the deep module. It owns the phase graph, artifact gating, skip rules, the terminal close gate, and the reentrancy guard. It imports nothing external — no `node:fs`, no pi API, no `pi-tui`, no `typebox`. Every method returns a `WorkflowEffect` (a discriminated union in domain vocabulary) that the adapter pattern-matches on.
-- **`adapter.ts`** is the thin glue. One state-machine method per call site (`start` tool, `end` tool, `tool_result` auto-advance, `/<command>`) plus one `applyEffect` switch. It owns all pi/fs wiring and the git-based `reuse` skip predicate. There is no `next` tool — phase advance is automatic once the phase artifact lands, and terminal close is via the `end` tool.
+- **`adapter.ts`** is the thin glue. It owns Pi/fs wiring, durable state, explicit resume, loop review persistence, and the git-based `reuse` skip predicate. Parent-written artifacts advance durable phase state. `prototype` and `quick` stop at user-controlled boundaries; `task` queues its build loop as soon as its plan is ready.
+- **`workflow.json`** in each artifact directory is the canonical, versioned run record. It is atomically replaced after state changes; session custom entries are only pointers for UI/history and never reconstruct an active run.
 - **`extension.ts`** imports each mode's registration object and calls `createWorkflowExtension(config, options)(pi)` for each, so one extension load resolves a single shared writer tool + one start/end tool pair per mode.
 - **A mode file** is pure data: the phase list, the per-phase artifact filenames, the per-phase prompt generators, the terminal close artifacts, and identity strings (tool names, command name, status key, entry type). Prompts are functions that receive `{ artifactDir, userPrompt }` and return a string. Each mode exports a `WorkflowModeRegistration` object (e.g. `prototypeMode`, `quickMode`); it does not call `createWorkflowExtension` itself.
 
@@ -90,10 +93,12 @@ export const rigorousMode: WorkflowModeRegistration = {
     "Run the rigorous workflow (grill → spec → research → plan → reuse → handoff → loop → audit → sign-off)",
   toolNames: {
     start: "start_rigorous_workflow",
+    resume: "resume_rigorous_workflow",
     end: "end_rigorous_workflow",
   },
   toolLabels: {
     start: "Start Rigorous Workflow",
+    resume: "Resume Rigorous Workflow",
     end: "End Rigorous Workflow",
   },
 };
@@ -111,7 +116,21 @@ import { rigorousMode } from "./modes/rigorous.ts";
 const MODES = [prototypeMode, quickMode, rigorousMode] as const;
 ```
 
-That's it. The loader picks it up at boot (`package.json` loads only `./extension.ts`); the two tools (`start_rigorous_workflow`, `end_rigorous_workflow`) and the `/rigorous` command are registered automatically. There is no `next` tool — phases auto-advance as artifacts land and the `end` tool closes the terminal phase.
+That's it. The loader picks it up at boot (`package.json` loads only `./extension.ts`); start/resume/end tools and the `/rigorous` command are registered automatically. There is no `next` tool — phases auto-advance as artifacts land and only the `end` tool completes the terminal phase.
+
+## Built-in modes
+
+### `task` — rapid plan + build/review loop
+
+The simplest workflow: an architect subagent produces a validated `plan.md`, then a builder↔commentator review loop runs (max 3 blocking rounds). A clean review makes the workflow terminal-ready; `end_task_workflow` completes it.
+
+Lifecycle: `plan → loop (build ↔ review) → terminal-ready → end_task_workflow`
+
+- `/workflow-task <goal>` — start a new run
+- `/workflow-task resume` — list and resume active runs
+- `/workflow-task help` — show the lifecycle
+- Its ready plan automatically queues the builder↔review loop
+- No grilling, research, reuse, or handoff phases
 
 ## Config reference
 
@@ -124,8 +143,9 @@ That's it. The loader picks it up at boot (`package.json` loads only `./extensio
 | `closeArtifacts` | `string[]` | Files that must exist before `end()` succeeds. Config-owned, no built-in default. |
 | `skipRules?` | `{ phase, shouldSkip }[]` | Optional per-phase skip rules. `shouldSkip` is a boolean predicate; when true the engine skips to the next phase. Omit to use the adapter's default (skip `reuse` on empty projects). |
 | `statusKey` | `string` | Footer status key. |
-| `entryType` | `string` | Persisted entry custom-type, used for session resume. |
+| `entryType` | `string` | Session-history custom-type. It stores a pointer only; `workflow.json` is canonical. |
 | `footerLabel` | `string` | Label shown in the footer (`● label · step/total phase`). |
+| `continueAfterArtifact?` | `boolean` | Queue the next phase prompt after the parent writes a valid artifact. `task` enables this for plan → build. |
 
 ### Adapter options
 
@@ -133,12 +153,31 @@ The second argument to `createWorkflowExtension`:
 
 | Field | Description |
 |---|---|
-| `toolNames` | `{ start, end }` — the two registered tool names. There is no `next` tool; phases auto-advance as artifacts land. |
+| `toolNames` | `{ start, resume, end }` — registered tool names. Artifacts advance phase state; the user explicitly continues the attached run. |
 | `toolLabels` | Human-readable labels for the tools. |
 | `commandName` | The `/<command>` name users type to kick off the workflow. |
 | `commandDescription` | Description shown in the command list. |
 
-## How transitions work
+## Durable runs and explicit resume
+
+Each started workflow receives a UUID artifact directory under `.selesai/artifacts/` and an adjacent `workflow.json`. It stores the mode, phase, armed state, loop round/review path, and timestamps. Writes use a temporary sibling file plus rename, so a crash cannot partially overwrite the canonical record.
+
+Runs are **never** auto-resumed on session start. At most one run can be attached to a Pi instance, but older active runs remain resumable:
+
+- `resume_workflow({ run: "<id-or-path>" })` / `resume_quick_workflow(...)` / `resume_task_workflow(...)`
+- `/workflow-prototype resume <id-or-artifact-dir-or-workflow.json>` / `/workflow-quick resume ...` / `/workflow-task resume ...`
+- `/workflow-prototype resume`, `/workflow-quick resume`, or `/workflow-task resume` lists active runs (and offers a UI picker when available).
+- `/workflow-prototype help`, `/workflow-quick help`, or `/workflow-task help` shows the start, resume, continue, and explicit-completion lifecycle.
+
+Resume validates the selected file is under the artifacts base, belongs to that mode, is active, and matches its containing directory. It reconciles the current expected artifact once before emitting the current prompt, covering a crash after `write_workflow_artifact` writes the file but before the phase-state write. Artifact writes do not inject the next phase prompt or launch the next subagent; they terminate the parent turn and wait for the user to continue. A mode can opt out of that pause after a parent artifact write; `task` does so after `plan.md` so the build loop starts immediately. Corrupt records are skipped during discovery.
+
+A valid terminal artifact makes a workflow **terminal-ready**; it does not complete the run. Call the mode-specific `end_*_workflow` tool to write `status: "completed"`, append the done entry, and terminate. This is the only completion path.
+
+## Artifact ownership
+
+Workflow artifacts have one writer: the parent session's `write_workflow_artifact` tool. Every workflow child call uses `output: false` and returns inline. In artifact phases (`plan`, `reuse`, `handoff`, and `audit`), the parent inspects that result, validates any required marker, and immediately passes it to `write_workflow_artifact`. Child output paths and fallback persistence are deliberately disabled; a child result alone cannot create an artifact or advance a phase.
+
+The implement/review loop is the explicit exception to parent persistence, not inline return: the engine persists `loop-review-<round>.md` and `loop-complete.md` from commentator results so it can manage review rounds. Builders only change workspace code.
 
 Every state-machine method returns a `WorkflowEffect` — a discriminated union the adapter switches on:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@selesai/code",
-	"version": "0.3.10",
+	"version": "0.5.0",
 	"description": "Selesai coding agent",
 	"type": "module",
 	"piConfig": {