@4pm/cli 1.28.0 → 1.30.0

package/dist/project-sample/.claude/AUTONOMOUS.md

@@ -15,17 +15,30 @@
 | `.claude/hooks/autonomous-tick.sh` | **Dumb** cron tick — its only job is `exec 4pm auto-run`. No gates, no schedule sync, no lock, no settings. |
 | `4pm auto-run` (cli) | Asks the running **`4pm start`** daemon to run **one** cycle over the control socket (token-authenticated — ADR-0320/0321). |
 | cli daemon (`runAutonomousCycle`) | Owns **all** logic: reads `autonomous.config.json`; the gates (paused / quiet-hours / max-ticks / **has-work** / **quota**); cron schedule sync; run histories + auto-pause; serialize one cycle at a time; model; usage via the live snapshot (ADR-0072). Runs the cycle as a write-capable agent (bypass — ADR-0271: branch + PR). |
-| `~/.4pm/profiles/<name>/autonomous.config.json` | The config knobs (paused, cronSchedule, quietHours, maxTicksPerDay, stopOnConsecutiveFailures, logRetentionDays, model, **maxSessionPct**, **maxWeeklyPct**). Clean JSON — the web Settings Form labels + explains each field. **Outside the repo.** |
+| `~/.4pm/profiles/<name>/autonomous.config.json` | The config knobs (paused, cronSchedule, quietHours, maxTicksPerDay, stopOnConsecutiveFailures, logRetentionDays, model, **maxSessionPct**, **maxWeeklyPct**, claimTtlHours, claimCheckMinutes, maxTaskAttempts, taskSizeHints). Clean JSON — the web Settings Form labels + explains each field. **Outside the repo.** |
 | `USER_TODO.md` / `USER_QA.md` / `AI_TODO.md` / `AI_PROGRESS.md` / `AI_DONE.md` | The data books (content-only tables — ADR-0320). |
 | `.claude/.autonomous.approvals.json` · `.autonomous.authors.json` | Per-row approver / writer (ADR-0320) — project data. `.autonomous.histories.json` = runtime state (gitignored). |
+| `.claude/.autonomous.attempts.json` | Per-task attempt count + split-pending state (ADR-0371) — committed on the base branch with the books. |
+
+## Branches & claims (ADR-0371)
+- The **books** (the five `.md` files + the `.claude/.autonomous.*.json` sidecars) always live on the
+  **base branch** and are the only files pushed to it directly; a claim is a books commit + push, and a
+  rejected (non-fast-forward) push means another worker won — the cli re-syncs and re-picks.
+- **Code** always goes through a task branch + a pull request into the base branch (submodules too).
+- A failed task returns to `AI_TODO` (attempt + 1); out of tokens keeps the claim until the reset, but a
+  claim older than `claimTtlHours` may be taken over. After `maxTaskAttempts` the task is split into
+  smaller unapproved children (a split child that fails again becomes a `USER_QA` question).
+- A task that needs a decision parks on a new `USER_QA` row listed in its `Depends`.
 
 ## Lifecycle (1 tick)
 ```
 cron → autonomous-tick.sh → `4pm auto-run` → the running daemon:
   ├─ paused / quiet-hours / max-ticks / has-work / quota over caps? → log "skip", done
   └─ run ONE cycle (write-capable agent):
-       sync the primary repo's branch → analyse APPROVED USER_TODO → fold APPROVED USER_QA →
-       one approved task → implement + test → open a PULL REQUEST into the base branch → update books
+       protected-base guard → sync <base> → resume/verify our claim → fold answered task-QAs →
+       intake (APPROVED USER_TODO + USER_QA → AI_TODO, sized S/M, L split) → CLAIM one eligible task
+       (books commit + push on <base> = the lock) → a task branch per task (root + subs)
+       → implement + test → PULL REQUESTS into <base> → move the task to AI_DONE (ADR-0371)
   └─ record history (N consecutive failures → auto-pause); serialized (one cycle at a time)
 ```
 

package/dist/project-sample/.claude/templates/AI_PROGRESS.empty.md

@@ -1,8 +1,12 @@
-# AI_PROGRESS — Task in progress
+# AI_PROGRESS — Tasks in progress
 
-> The current in-progress task — a **single row** in the table below (set when the cycle starts a task,
-> cleared back to this empty template when it finishes) — per `.claude/templates/AI_PROGRESS.sample.md`.
+> The tasks currently **claimed** by workers — **one row per claim** (ADR-0371). The 4PM cli writes this
+> table on the base branch (commit + push = the claim; a lost push race means another worker won the task)
+> and clears the row when the task finishes or is released. **Do not edit by hand** while a cycle runs.
+> `Worker` = the claiming worker · `Claim` = a unique claim id · `Attempt` = which try this is (see
+> `.claude/.autonomous.attempts.json`). A claim older than `claimTtlHours` (default 6) may be taken over.
+> Per `.claude/templates/AI_PROGRESS.sample.md`.
 
-| Started | ID | Task description |
-|---------|----|------------------|
-| | | |
+| Started | ID | Worker | Claim | Attempt | Task description |
+|---|---|---|---|---|---|
+| | | | | | |

package/dist/project-sample/.claude/templates/AI_PROGRESS.sample.md

@@ -1,5 +1,6 @@
-# AI_PROGRESS — Task in progress
+# AI_PROGRESS — Tasks in progress
 
-| Started | ID | Task description |
-|---------|----|------------------|
-| 2026-01-01 10:00 | TSK-0001-0001 | Add login-form validation |
+| Started | ID | Worker | Claim | Attempt | Task description |
+|---|---|---|---|---|---|
+| 2026-01-01 10:00:00 | TSK-0001-0001 | wsl-dev-1 | c-4f2a9b | 1 | Add login-form validation |
+| 2026-01-01 10:05:12 | TSK-0002-0001 | wsl-dev-2 | c-91d0e7 | 2 | Export the report as CSV |

package/dist/project-sample/.claude/templates/AI_TODO.empty.md

@@ -7,9 +7,15 @@
 > the project when the task is approved (approval is committed on Save — ADR-0311).
 > **Approval** is NOT a table column — it lives in `.claude/.autonomous.approvals.json` (ADR-0152), set
 > from the web AI Todo grid; the autonomous cli reads that file, never the table.
-> **Depends** = the `TSK-…` ids that must be DONE (present in `AI_DONE.md`) first.
-> the autonomous cli only takes tasks that are approved AND have their dependencies met → moves them to
-> `AI_PROGRESS.md`; runs group by group, within a group High → Medium → Low.
+> **Depends** = comma-separated `TSK-…` and/or `QA-…` ids (ADR-0371). One `TSK` dependency must be in
+> `AI_DONE.md` (the task's branch starts from that task's branch); **two or more** must all have their PRs
+> **merged** into the base branch. A `QA-…` dependency parks the task until that `USER_QA` row is answered
+> and approved (the cli then folds the answer into Notes and drops the id).
+> **Notes** may carry `size: S|M` (the intake sizing — an `L` request is always split), `from: <branch>`
+> (a split child continuing a WIP branch) and failure notes. Retries/split state live in
+> `.claude/.autonomous.attempts.json`, not the table.
+> The autonomous cli only takes tasks that are approved AND have their dependencies met → claims them in
+> `AI_PROGRESS.md` (one row per worker); runs group by group, within a group High → Medium → Low.
 
 | ID | Priority | Tag | Depends | Group | Task description | Notes |
 |----|----------|-----|---------|-------|------------------|-------|

package/dist/project-sample/.claude/templates/AI_TODO.sample.md

@@ -4,10 +4,12 @@
 > **Priority** = High / Medium / Low. **Tag** = optional catalog tag(s) (e.g. `UpdateSpecFromDB`) whose
 > action runs from the server down to the project on approve (committed on Save — ADR-0311).
 > **Approval** lives in `.claude/.autonomous.approvals.json` (ADR-0152), not the table. **Depends** =
-> `TSK-…` ids that must be in `AI_DONE.md` first.
+> `TSK-…` ids (one ⇒ in `AI_DONE.md`; two or more ⇒ all PRs merged into the base branch) and/or `QA-…` ids
+> (wait for that answer — ADR-0371). **Notes** may carry `size: S|M` and `from: <branch>`.
 
 | ID | Priority | Tag | Depends | Group | Task description | Notes |
 |----|----------|-----|---------|-------|------------------|-------|
 | TSK-0001-0001 | High | | | Auth | Add login-form validation per docs/auth.md | |
 | TSK-0001-0002 | Medium | | TSK-0001-0001 | Auth | Wire the login API call + error handling | After 0001 |
-| TSK-0001-0003 | Low | UpdateSpecFromDB | | Spec | Sync the project spec into project.spec.json on approve | Server action |
+| TSK-0001-0003 | Low | UpdateSpecFromDB | | Spec | Sync the project spec into project.spec.json on approve | Server action; size: S |
+| TSK-0001-0004 | Medium | | TSK-0001-0002, QA-0001-0002 | Auth | Add the password-reset flow | Waits for QA-0001-0002 (which mail provider?); size: M |

package/dist/project-sample/.claude/templates/USER_QA.empty.md

@@ -8,6 +8,9 @@
 > `.claude/.autonomous.authors.json` — the web USER_QA grid shows them and enforces four-eyes (the person
 > who answered can't approve their own answer, except ADMIN). See `.claude/templates/USER_QA.sample.md`.
 >
+> A question raised **while implementing a task** (ADR-0371) is also a row here: its id is added to the
+> task's `Depends` in `AI_TODO.md`, and the task waits until this row is answered + approved.
+>
 > **Columns (content only):** `ID` · `Group` · `Depends` (comma-separated `QA-…`) · `Original request` ·
 > `Question / options` · `Answer`.
 

package/dist/project-sample/AI_PROGRESS.md

@@ -1,8 +1,12 @@
-# AI_PROGRESS — Task in progress
+# AI_PROGRESS — Tasks in progress
 
-> The current in-progress task — a **single row** in the table below (set when the cycle starts a task,
-> cleared back to this empty template when it finishes) — per `.claude/templates/AI_PROGRESS.sample.md`.
+> The tasks currently **claimed** by workers — **one row per claim** (ADR-0371). The 4PM cli writes this
+> table on the base branch (commit + push = the claim; a lost push race means another worker won the task)
+> and clears the row when the task finishes or is released. **Do not edit by hand** while a cycle runs.
+> `Worker` = the claiming worker · `Claim` = a unique claim id · `Attempt` = which try this is (see
+> `.claude/.autonomous.attempts.json`). A claim older than `claimTtlHours` (default 6) may be taken over.
+> Per `.claude/templates/AI_PROGRESS.sample.md`.
 
-| Started | ID | Task description |
-|---------|----|------------------|
-| | | |
+| Started | ID | Worker | Claim | Attempt | Task description |
+|---|---|---|---|---|---|
+| | | | | | |

package/dist/project-sample/AI_TODO.md

@@ -7,9 +7,15 @@
 > the project when the task is approved (approval is committed on Save — ADR-0311).
 > **Approval** is NOT a table column — it lives in `.claude/.autonomous.approvals.json` (ADR-0152), set
 > from the web AI Todo grid; the autonomous cli reads that file, never the table.
-> **Depends** = the `TSK-…` ids that must be DONE (present in `AI_DONE.md`) first.
-> the autonomous cli only takes tasks that are approved AND have their dependencies met → moves them to
-> `AI_PROGRESS.md`; runs group by group, within a group High → Medium → Low.
+> **Depends** = comma-separated `TSK-…` and/or `QA-…` ids (ADR-0371). One `TSK` dependency must be in
+> `AI_DONE.md` (the task's branch starts from that task's branch); **two or more** must all have their PRs
+> **merged** into the base branch. A `QA-…` dependency parks the task until that `USER_QA` row is answered
+> and approved (the cli then folds the answer into Notes and drops the id).
+> **Notes** may carry `size: S|M` (the intake sizing — an `L` request is always split), `from: <branch>`
+> (a split child continuing a WIP branch) and failure notes. Retries/split state live in
+> `.claude/.autonomous.attempts.json`, not the table.
+> The autonomous cli only takes tasks that are approved AND have their dependencies met → claims them in
+> `AI_PROGRESS.md` (one row per worker); runs group by group, within a group High → Medium → Low.
 
 | ID | Priority | Tag | Depends | Group | Task description | Notes |
 |----|----------|-----|---------|-------|------------------|-------|

package/dist/project-sample/USER_QA.md

@@ -8,6 +8,9 @@
 > `.claude/.autonomous.authors.json` — the web USER_QA grid shows them and enforces four-eyes (the person
 > who answered can't approve their own answer, except ADMIN). See `.claude/templates/USER_QA.sample.md`.
 >
+> A question raised **while implementing a task** (ADR-0371) is also a row here: its id is added to the
+> task's `Depends` in `AI_TODO.md`, and the task waits until this row is answered + approved.
+>
 > **Columns (content only):** `ID` · `Group` · `Depends` (comma-separated `QA-…`) · `Original request` ·
 > `Question / options` · `Answer`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4pm/cli",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "private": false,
   "description": "4PM CLI — drives Claude/Codex CLIs on AI worker machines (Node + TypeScript)",
   "license": "LicenseRef-4PM-Source-Available",