pi-do-always 0.9.0 → 0.10.0

package/README.md

@@ -11,26 +11,23 @@ type to filter, scroll or click, or navigate with arrows + Enter → the task's
 ```text
   do-always — pick a task
 
+   #  TASK                      DESCRIPTION                                                    ORDER
   PLAN
-▸ 1. ⚡ Review changes       Review the current code changes (Plan)
-  2. ⚡ Review code          Review the whole project's code quality (Plan)
-  3. ⚡ Cleanup              Clean up dead code and duplicates (Plan)
-  4. ⚡ Security             Security audit (Plan)
-  5. ⚡ Performance          Performance review (Plan)
-  6. ⚡ Propose features     Propose new features (Plan)
+   1  ⚡ Review changes         Review the current code changes (Plan)                           ·  
+   2  ⚡ Review code            Review the whole project's code quality (Plan)                  [1] 
+   3  ⚡ Cleanup                Clean up dead code and duplicates (Plan)                        [2] 
+   4  ⚡ Security               Security audit (Plan)                                            ·  
+   5  ⚡ Performance            Performance review (Plan)                                      ►[3] 
+   6  ⚡ Propose features       Propose new features (Plan)                                      ·  
   DO
-  7. Build                  Test build is ok and fix issues
-  8. Tests                  Run tests and fix failures
+   7  Build                     Test build is ok and fix issues                                  ·  
+   8  Tests                     Run tests and fix failures                                       ·  
   DOCS
-  9. Readme                 Update the README.md
-  OPS
- 10. Release               Prepare a release (version, changelog, tag)
- 11. Commit                Prepare a clean commit
+   9  Readme                    Update the README.md                                             ·  
 
-  Review changes — prompt:
-  Review the changes on branch fix/login-null (3 changed files: auth.ts, login.ts,
-  test/auth.test.ts). Last commit: Fix null check in login. Check `git status` and
-  `git diff` to see what changed, then double-check the changes for bugs, edge …
+  ──────────────────────────────────────────────────────────────────────────────────────────────────
+  Run the chain (3)
+  ← tasks  •  ⏎ remove  •  esc  •  ctrl+u clear
 
   1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel  •  ⚡ auto-runs
 ```
@@ -59,6 +56,82 @@ not filled): the `Plan` category does this by default, and any task can opt in o
 In non-interactive modes (no TUI) there is no editor to fill, so the selected prompt is sent
 as a user message instead.
 
+## Chains
+
+Run several tasks in a row as a **chain**. The selector shows an `ORDER` column; tasks in
+the chain get a `[n]` marker in execution order, and a pinned row at the bottom of the
+list runs the chain.
+
+Building a chain in the selector:
+
+- **Enter on a task row** runs just that task (the classic pick — the cursor starts in
+  the task column).
+- **→** moves the cursor to the ORDER column on the same row, where **Enter** toggles
+  that task's chain membership (`·` → `[n]` → `·`). **←** goes back to the task column.
+- **↑ / ↓** move the cursor in either column. The cursor is a **►** marker in the
+  theme's accent color: in the left gutter in the task column, in the ORDER cell in
+  the order column (plus a row highlight where your theme makes it visible). From the
+  last task row, **↓** lands on the pinned Run row (and **↑** back).
+- **Enter on the `Run the chain (n)` row** — or a mouse click on it — runs the chain.
+  The row is dimmed while the chain is empty. The ► marker appears on it only
+  while the cursor is on the row (as on task rows).
+- **Backspace** (with no filter typed) undoes the last add; **ctrl+u** clears the whole
+  chain; **Esc** cancels and discards it.
+- Clicking an ORDER cell toggles the task's chain membership.
+- The classic fast paths are unchanged: **1-9** runs a task immediately, and clicking a
+  task row runs it — both close the selector and discard the chain.
+
+Chains are capped at 8 tasks. Reordering is done by removing a task and re-adding it
+(mouse drag reordering is planned for a future release). On narrow terminals the ORDER
+column is dropped and the chain is shown on its own line below the list (keyboard
+chaining still works).
+
+Running a chain sends each step as its own turn, strictly one after another — the next
+step starts only after the previous run has fully finished. Each step's guards are
+re-evaluated at its turn against the current state; a step whose guards no longer hold
+stops the chain there (with a warning), as do an aborted step (Esc) or a step that
+errors. Steps already run are kept.
+
+If the first task of a chain is a fill task (no `⚡`) in the TUI, step 1 is put in the
+editor and the rest of the chain starts automatically once you press Enter and that run
+finishes.
+
+While a chain is running, a **status widget** is shown below the prompt: the chain's
+tasks with a marker per step and a `(n/N)` progress count — the step the chain is
+currently at.
+
+```
+  ⛓ do-always (2/4)
+  ✓ Review changes
+  ▶ Build
+  ○ Test
+  ○ Deploy
+```
+
+Markers: `✓` completed, `▶` running (or waiting for your Enter on a fill-first step 1),
+`○` pending, `✗` errored / failed to start, `⊘` aborted, `–` skipped because its guards
+no longer hold. The widget is removed when the chain completes; if the chain stops early
+it stays below the prompt as a trace of where it stopped (until your next prompt or a new
+session). Starting a second chain while
+one is running is refused — wait for it to finish or abort the current step with Esc.
+
+Every chain run also writes a **report file** in the project root —
+`do-always-report-tasks-YYYY-MM-DD-HHMM.md` (e.g. `do-always-report-tasks-2025-01-15-1432.md`) —
+so earlier steps' results are not lost when later steps' output scrolls them off screen.
+Each step appends a section as it finishes (the step's final assistant message, with its
+outcome and run time), so the file is complete even if the session dies mid-chain; a
+footer with the overall summary is appended when the chain ends, and the completion
+notification carries the file's path. A run that produces nothing worth keeping (no
+completed step and no step result text — e.g. step 1 errors before any output) leaves no
+file behind. Set `"report": false` in the config to disable
+it (the project file's value wins over the global one). See [Report file](#report-file).
+
+**Inline report in the chat.** When a chain completes fully (all steps done), the full
+Markdown report is sent as a message in the chat so you can read the results without
+opening the file. The message is automatically removed when you start the next
+prompt or session. A run that stops early (aborted, errored, or skipped steps) does
+not show the inline report — only the status trace widget below the prompt.
+
 ## Install
 
 Install it from npm as a Pi package, which loads the bundled `index.ts` (and its `tasks.ts`) without
@@ -117,6 +190,7 @@ In the object form you can also configure the selector shortcut:
 
 - `shortcut` (optional) — key that opens the selector, e.g. `"f4"`. Set to `null` to disable the shortcut. Defaults to `F4`. The project file's value wins over the global one.
 - `merge` (optional) — how project tasks combine with the global tasks: `"override"` (default) replaces a global task with the same `name`; `"append"` keeps the global tasks and only adds new project task names (a cascade, like CSS). The project file's value wins over the global one; when neither sets it, the default is `override` (the historical behavior).
+- `report` (optional) — whether chain runs write a Markdown report file in the project root (one per run, appended as each step finishes). Default `true`; set `false` to disable. The project file's value wins over the global one. See [Chains](#chains).
 
 Example project file that only *adds* tasks without overriding the global set: