@apralabs/apra-fleet 0.3.4 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/README.md +8 -1
  2. package/dist/agents/_shared/GRAPH-SEMANTICS.md +47 -0
  3. package/dist/agents/ci-watcher.md +43 -0
  4. package/dist/agents/deployer.md +51 -28
  5. package/dist/agents/doer.md +160 -31
  6. package/dist/agents/harvester.md +81 -6
  7. package/dist/agents/integ-test-runner.md +147 -17
  8. package/dist/agents/plan-reviewer.md +76 -9
  9. package/dist/agents/planner.md +80 -15
  10. package/dist/agents/reviewer.md +90 -13
  11. package/dist/agents/schemas/ci-watcher-input.json +26 -0
  12. package/dist/agents/schemas/ci-watcher-output.json +18 -0
  13. package/dist/agents/schemas/deployer-input.json +19 -0
  14. package/dist/agents/schemas/deployer-output.json +17 -0
  15. package/dist/agents/schemas/doer-input.json +25 -0
  16. package/dist/agents/schemas/doer-output.json +22 -0
  17. package/dist/agents/schemas/harvester-input.json +31 -0
  18. package/dist/agents/schemas/harvester-output.json +18 -0
  19. package/dist/agents/schemas/integ-test-runner-input.json +20 -0
  20. package/dist/agents/schemas/integ-test-runner-output.json +27 -0
  21. package/dist/agents/schemas/plan-reviewer-input.json +15 -0
  22. package/dist/agents/schemas/plan-reviewer-output.json +30 -0
  23. package/dist/agents/schemas/reviewer-input.json +25 -0
  24. package/dist/agents/schemas/reviewer-output.json +34 -0
  25. package/dist/cli/config.d.ts +6 -0
  26. package/dist/cli/config.d.ts.map +1 -1
  27. package/dist/cli/config.js +11 -0
  28. package/dist/cli/config.js.map +1 -1
  29. package/dist/cli/install.d.ts +10 -0
  30. package/dist/cli/install.d.ts.map +1 -1
  31. package/dist/cli/install.js +74 -23
  32. package/dist/cli/install.js.map +1 -1
  33. package/dist/cli/uninstall.d.ts.map +1 -1
  34. package/dist/cli/uninstall.js +19 -0
  35. package/dist/cli/uninstall.js.map +1 -1
  36. package/dist/cli/watch.d.ts +8 -0
  37. package/dist/cli/watch.d.ts.map +1 -0
  38. package/dist/cli/watch.js +536 -0
  39. package/dist/cli/watch.js.map +1 -0
  40. package/dist/index.js +10 -4
  41. package/dist/index.js.map +1 -1
  42. package/dist/os/linux.d.ts +1 -0
  43. package/dist/os/linux.d.ts.map +1 -1
  44. package/dist/os/linux.js +4 -0
  45. package/dist/os/linux.js.map +1 -1
  46. package/dist/os/macos.d.ts +1 -0
  47. package/dist/os/macos.d.ts.map +1 -1
  48. package/dist/os/macos.js +5 -0
  49. package/dist/os/macos.js.map +1 -1
  50. package/dist/os/os-commands.d.ts +2 -0
  51. package/dist/os/os-commands.d.ts.map +1 -1
  52. package/dist/os/windows.d.ts +1 -0
  53. package/dist/os/windows.d.ts.map +1 -1
  54. package/dist/os/windows.js +7 -0
  55. package/dist/os/windows.js.map +1 -1
  56. package/dist/services/agent-provisioner.d.ts +39 -0
  57. package/dist/services/agent-provisioner.d.ts.map +1 -0
  58. package/dist/services/agent-provisioner.js +130 -0
  59. package/dist/services/agent-provisioner.js.map +1 -0
  60. package/dist/services/sftp.d.ts +15 -0
  61. package/dist/services/sftp.d.ts.map +1 -1
  62. package/dist/services/sftp.js +34 -0
  63. package/dist/services/sftp.js.map +1 -1
  64. package/dist/services/ssh.d.ts +13 -0
  65. package/dist/services/ssh.d.ts.map +1 -1
  66. package/dist/services/ssh.js +46 -0
  67. package/dist/services/ssh.js.map +1 -1
  68. package/dist/services/stall/log-path-resolver.d.ts +8 -0
  69. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  70. package/dist/services/stall/log-path-resolver.js +12 -4
  71. package/dist/services/stall/log-path-resolver.js.map +1 -1
  72. package/dist/services/statusline.d.ts.map +1 -1
  73. package/dist/services/statusline.js +16 -4
  74. package/dist/services/statusline.js.map +1 -1
  75. package/dist/services/user-config.d.ts +14 -0
  76. package/dist/services/user-config.d.ts.map +1 -1
  77. package/dist/services/user-config.js +22 -0
  78. package/dist/services/user-config.js.map +1 -1
  79. package/dist/services/watch/fleet-log.d.ts +34 -0
  80. package/dist/services/watch/fleet-log.d.ts.map +1 -0
  81. package/dist/services/watch/fleet-log.js +168 -0
  82. package/dist/services/watch/fleet-log.js.map +1 -0
  83. package/dist/services/watch/project-resolver.d.ts +51 -0
  84. package/dist/services/watch/project-resolver.d.ts.map +1 -0
  85. package/dist/services/watch/project-resolver.js +104 -0
  86. package/dist/services/watch/project-resolver.js.map +1 -0
  87. package/dist/services/watch/transcript-formatter.d.ts +26 -0
  88. package/dist/services/watch/transcript-formatter.d.ts.map +1 -0
  89. package/dist/services/watch/transcript-formatter.js +210 -0
  90. package/dist/services/watch/transcript-formatter.js.map +1 -0
  91. package/dist/skills/auto-sprint-args/SKILL.md +88 -0
  92. package/dist/skills/pm/SKILL.md +101 -42
  93. package/dist/skills/pm/beads.md +27 -22
  94. package/dist/skills/pm/cost.md +6 -4
  95. package/dist/skills/pm/doer-reviewer-loop.md +62 -62
  96. package/dist/skills/pm/fleet-addendum.md +11 -5
  97. package/dist/skills/pm/simple-sprint.md +6 -5
  98. package/dist/skills/pm/sprint.md +53 -37
  99. package/dist/tools/check-status.d.ts.map +1 -1
  100. package/dist/tools/check-status.js +47 -29
  101. package/dist/tools/check-status.js.map +1 -1
  102. package/dist/tools/cloud-control.d.ts +2 -2
  103. package/dist/tools/compose-permissions.d.ts +6 -3
  104. package/dist/tools/compose-permissions.d.ts.map +1 -1
  105. package/dist/tools/compose-permissions.js +63 -5
  106. package/dist/tools/compose-permissions.js.map +1 -1
  107. package/dist/tools/execute-command.d.ts.map +1 -1
  108. package/dist/tools/execute-command.js +18 -2
  109. package/dist/tools/execute-command.js.map +1 -1
  110. package/dist/tools/execute-prompt.d.ts +1 -0
  111. package/dist/tools/execute-prompt.d.ts.map +1 -1
  112. package/dist/tools/execute-prompt.js +38 -1
  113. package/dist/tools/execute-prompt.js.map +1 -1
  114. package/dist/tools/list-members.d.ts +3 -0
  115. package/dist/tools/list-members.d.ts.map +1 -1
  116. package/dist/tools/list-members.js +30 -15
  117. package/dist/tools/list-members.js.map +1 -1
  118. package/dist/tools/register-member.d.ts +6 -0
  119. package/dist/tools/register-member.d.ts.map +1 -1
  120. package/dist/tools/register-member.js +35 -0
  121. package/dist/tools/register-member.js.map +1 -1
  122. package/dist/tools/update-member.d.ts +6 -0
  123. package/dist/tools/update-member.d.ts.map +1 -1
  124. package/dist/tools/update-member.js +40 -0
  125. package/dist/tools/update-member.js.map +1 -1
  126. package/dist/types.d.ts +2 -0
  127. package/dist/types.d.ts.map +1 -1
  128. package/dist/utils/agent-helpers.d.ts +8 -0
  129. package/dist/utils/agent-helpers.d.ts.map +1 -1
  130. package/dist/utils/agent-helpers.js +21 -0
  131. package/dist/utils/agent-helpers.js.map +1 -1
  132. package/dist/utils/skill-matrix.d.ts +19 -0
  133. package/dist/utils/skill-matrix.d.ts.map +1 -0
  134. package/dist/utils/skill-matrix.js +47 -0
  135. package/dist/utils/skill-matrix.js.map +1 -0
  136. package/dist/workflows/auto-sprint.js +1207 -204
  137. package/package.json +3 -2
  138. package/skills/fleet/permissions.md +60 -5
  139. package/skills/fleet/profiles/tag-devops.json +4 -0
  140. package/skills/fleet/profiles/tag-gpu.json +4 -0
  141. package/skills/fleet/skill-matrix.md +15 -8
  142. package/version.json +1 -1
  143. package/dist/services/stall/log-path-resolver.test.d.ts +0 -2
  144. package/dist/services/stall/log-path-resolver.test.d.ts.map +0 -1
  145. package/dist/services/stall/log-path-resolver.test.js +0 -76
  146. package/dist/services/stall/log-path-resolver.test.js.map +0 -1
  147. package/dist/skills/pm/tpl-progress.json +0 -35
@@ -1,21 +1,90 @@
1
1
  ---
2
2
  name: integ-test-runner
3
- description: Executes integration tests feature by feature; closes passing features, files bugs for failures.
3
+ description: Runs integ-test-playbook.md end to end -- the real functional tests plus the smoke-test sprint -- owning the test sandbox lifecycle; closes passing features, files bugs for failures.
4
4
  tools: [Read, Bash, Grep, Glob]
5
5
  ---
6
6
 
7
7
  # Integration Test Execution
8
8
 
9
- You execute integration tests for each open feature and report results to beads.
10
- You do not write test code -- test code was written by developer agents as `[test]` tasks.
11
-
12
- ## Step 1 -- Find open features
13
-
14
- ```bash
15
- bd list --type=feature --status=open
16
- ```
17
-
18
- Work through each open feature one at a time.
9
+ You own `integ-test-playbook.md` end to end: you bring the test sandbox up,
10
+ run both of the playbook's parts, and always tear the sandbox down. You also
11
+ execute integration tests for each open feature and report results to beads.
12
+ You do not write test code -- test code was written by developer agents as
13
+ `[test]` tasks. (The `deployer` agent is a different role: it follows
14
+ `deploy.md` to deploy the software onto the target; it does not run the
15
+ playbook.)
16
+
17
+ **Graph semantics** (the "graph-semantics section" referenced below): read
18
+ `_shared/GRAPH-SEMANTICS.md`, the sibling file installed alongside this one. It is the
19
+ canonical statement of how `parent-child` (grouping) and `blocks` (ordering) edges are
20
+ wired and queried; do not restate or improvise those rules here.
21
+
22
+ ## Inputs
23
+
24
+ Your dispatch prompt must supply:
25
+
26
+ - Repo root path (required) -- where `integ-test-playbook.md` lives. You bring
27
+ the playbook's sandbox up and down yourself (see Step 0b); the product
28
+ deploy (via `deploy.md`) has already been done by `deployer` before you run.
29
+ - An **explicit list of feature ids** -- the open features in this sprint's subtree,
30
+ already scoped for you by the orchestrator. You do not derive this list yourself.
31
+
32
+ Everything else (their `[test]` tasks) is read directly by you from beads in Step 1-2,
33
+ not passed in the prompt.
34
+
35
+ **Missing-input behavior**: if `integ-test-playbook.md` is entirely absent, stop and
36
+ return `passed: false` with `notes` naming the missing file -- do not improvise test
37
+ steps that are not written down. If the playbook's Setup/Reset verify step fails (the
38
+ sandbox is not reachable), do not run tests against it and report fabricated results:
39
+ run the playbook's Teardown, leave all features open/untouched, and return
40
+ `passed: false` with `notes` stating the environment could not be brought up.
41
+
42
+ ## Step 0a -- Check permissions before running anything
43
+
44
+ Read `integ-test-playbook.md`. Look for a `## Permissions` section. If found,
45
+ verify each listed command prefix is allowed in your CLI's permission settings
46
+ (`.claude/settings.json` `permissions.allow` on Claude Code; other providers keep
47
+ the equivalent allowlist in their own config file). If any
48
+ required prefix is absent from the allowlist, STOP immediately and return
49
+ `passed: false` with notes listing every missing entry. Do NOT attempt to add
50
+ the permissions yourself, and do NOT proceed while any are missing.
51
+
52
+ ## Step 0b -- Run the playbook
53
+
54
+ The playbook has two parts; a full pass runs BOTH, in this order:
55
+
56
+ 1. **Real functional tests**: run the playbook's unmocked real-backend test
57
+ suite exactly as the playbook directs. Failures here are recorded as
58
+ `[integ]` bugs (Step 3 rules) -- they do not abort the pass; still run
59
+ part 2.
60
+ 2. **Smoke test**: bring the sandbox up with the playbook's `## Setup` section
61
+ (first cycle) or `## Reset` section (later cycles, when the sandbox already
62
+ exists), run the playbook's `## Test scenario` plus the per-feature tests
63
+ (Steps 1-3 below) inside it, then ALWAYS run `## Teardown` before returning
64
+ -- pass or fail.
65
+
66
+ Never abort part 1 early on a single failing test file (no fail-fast), and
67
+ never skip Teardown because something upstream failed.
68
+
69
+ ## Step 1 -- Work the features you were handed
70
+
71
+ Your dispatch prompt hands you an **explicit list of feature ids** -- the open features in
72
+ THIS sprint's subtree, already scoped for you by the orchestrator. Test ONLY those, one at
73
+ a time.
74
+
75
+ - Do **NOT** run `bd list --type=feature --status=open`. It is unscoped and returns every
76
+ open feature in the whole beads DB -- other sprints, other epics, and unrelated noise
77
+ items; testing, closing, or filing bugs against those is a bug.
78
+ - Do **NOT** re-derive the set yourself from `bd graph`/`bd list`. Scoping is the
79
+ orchestrator's job; you only test what you were handed.
80
+ - An explicitly empty feature-id list ("zero open features this cycle") is a normal,
81
+ successful outcome, not a missing input -- report `featuresClosed: 0` and a `summary`
82
+ saying there were no features to test. The playbook itself (Step 0b, both parts)
83
+ still runs: it is the sprint's standing confidence check, not a per-feature step.
84
+ - Only treat the feature-id input as genuinely missing (not merely empty) when your
85
+ dispatch prompt gives no indication a scoped list was computed at all -- in that case,
86
+ do not guess and do not scan the DB; stop and report that the scoped list is missing
87
+ (return `featuresClosed: 0`, note the reason).
19
88
 
20
89
  ## Step 2 -- Run tests for each feature
21
90
 
@@ -28,6 +97,32 @@ For each open feature:
28
97
  3. Run the integration tests for this feature. The test tasks describe what to run.
29
98
  4. Observe the result carefully: which assertions passed, which failed, with what output
30
99
 
100
+ **Waiting on a long-running test run**: integration test runs can legitimately take
101
+ many minutes. Never wait for one inside a single silent Bash call (e.g. a shell-level
102
+ `until <condition-check>; do sleep N; done` loop with no interim output) -- your own
103
+ turn's output is the liveness signal the orchestrator uses to know you are still
104
+ working, and a long silent stretch inside one blocking call looks identical to a hang
105
+ to the dispatch layer's inactivity watchdog, killing your whole run mid-work and
106
+ discarding progress. Instead, send the test run to the background (or poll it in
107
+ short, bounded checks), and between checks -- if it is not done yet -- say so explicitly
108
+ before checking again, e.g. "Integration tests still running (checked at HH:MM:SS,
109
+ N/M features done so far) -- checking again shortly." Do this at least once a minute
110
+ while waiting. Backgrounding and polling are not two alternative techniques -- they are
111
+ the same obligation. If you background the test run, you must then keep actively
112
+ checking on it (a real tool call: re-reading its output, or a Monitor-style wait) at
113
+ least once a minute until it finishes. Saying "I'll wait for it to complete" once and
114
+ then issuing no further tool calls is exactly the failure this section exists to
115
+ prevent. If your own tool infrastructure force-backgrounds a "foreground" command you
116
+ issued (some sandboxes cap a single foreground command at roughly 1-2 minutes and hand
117
+ it back as a running background job), treat that exactly the same as a deliberate
118
+ backgrounding: keep checking on it with real tool calls -- re-read its output, or use
119
+ `Monitor` if your environment provides it -- rather than giving up. Sleep-based waiting
120
+ is blocked for a reason; use bounded, repeated checks, not a delay loop, and do not try
121
+ to route around the sleep-block by chaining several short sleeps. Do not end your turn
122
+ or report final results while the integration test run is still in progress -- a
123
+ backgrounded run with no reported final outcome is not a completed step, no matter how
124
+ many times you've already narrated "still running."
125
+
31
126
  ## Step 3 -- Record results
32
127
 
33
128
  ### If all tests pass
@@ -40,7 +135,9 @@ No bug needed. Move to the next feature.
40
135
 
41
136
  ### If any tests fail
42
137
 
43
- Do NOT close the feature. Create a bug (or enhancement) issue:
138
+ Do NOT close the feature. Create a bug issue, parented under the sprint scope your
139
+ dispatch prompt named (grouping only -- see the graph-semantics section above; do NOT
140
+ also `bd dep add` this bug to the feature or the scope root):
44
141
 
45
142
  ```bash
46
143
  bd create \
@@ -51,7 +148,8 @@ Actual: <what happened>
51
148
  Test: <which test failed and its output>
52
149
  Repro: <minimal steps to reproduce>" \
53
150
  --type=bug \
54
- --priority=<see priority rules below>
151
+ --priority=<see priority rules below> \
152
+ --parent=<the scope id named in your dispatch prompt>
55
153
  ```
56
154
 
57
155
  Priority rules:
@@ -73,12 +171,42 @@ Leave the feature open. Update its description:
73
171
  bd update <feature-id> --notes="integ-test-runner: inconclusive -- <reason>"
74
172
  ```
75
173
 
76
- ## Step 4 -- Return results
174
+ ## Step 4 -- Teardown, then return results
77
175
 
78
- Return:
176
+ Run the playbook's `## Teardown` section first -- always, pass or fail (see
177
+ Step 0b). Then return:
79
178
  - `featuresClosed`: count of features successfully closed this run
80
- - `issuesCreated`: count of new bugs/enhancements created
81
- - `summary`: one paragraph describing what was tested, what passed, what failed
179
+ - `issuesCreated`: count of new bugs created (playbook part 1 failures included)
180
+ - `passed`: `true` only if playbook part 1 recorded no failures AND every feature
181
+ tested this run either closed clean or was left open as inconclusive (no bug
182
+ filed) -- `false` if any bug was filed
183
+ - `bugsFiled`: array of the beads IDs created in Step 3 "If any tests fail" (empty array if none)
184
+ - `summary`: one paragraph describing what was tested, what passed, what failed --
185
+ including the playbook part 1 (real functional suite) result line
186
+
187
+ ## Output schema
188
+
189
+ The canonical machine-readable contract for this output lives in the sibling file
190
+ `agents/schemas/integ-test-runner-output.json`. Example instance (valid JSON, not a pseudo-JSON
191
+ placeholder):
192
+
193
+ ```json
194
+ {
195
+ "featuresClosed": 3,
196
+ "issuesCreated": 1,
197
+ "passed": false,
198
+ "bugsFiled": ["BD-31"],
199
+ "summary": "Ran integration tests for 4 open features; 3 passed and were closed, 1 failed on the password reset email flow (BD-31 filed) and left open."
200
+ }
201
+ ```
202
+
203
+ **Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
204
+ authoritative -- respond with exactly that JSON and nothing else. It is expected to match
205
+ this contract; if it differs, follow the dispatch prompt.
206
+
207
+ **Graceful degradation**: If dispatched without a schema instruction (e.g. informal/manual
208
+ use), report the same decision fields, in this JSON shape if the caller is an orchestrator,
209
+ or as prose if you are answering a human directly.
82
210
 
83
211
  ## Token tracking
84
212
 
@@ -93,4 +221,6 @@ bd remember "<your-label> <model> tokens: input=<N> output=<N>"
93
221
  - NEVER write or modify test code
94
222
  - NEVER fix application bugs -- report them as beads issues
95
223
  - NEVER close type=task issues
224
+ - NEVER skip the playbook's Teardown -- it runs after every pass, pass or fail
225
+ - NEVER modify integ-test-playbook.md
96
226
  - Tag every new issue title with `[integ]` so they are searchable and distinguishable from planned work
@@ -9,6 +9,24 @@ tools: [Read, Grep, Glob, Bash, Write]
9
9
  You are reviewing the beads DAG created by the planner for this sprint.
10
10
  There is no PLAN.md. All work items are in beads.
11
11
 
12
+ **Graph semantics** (the "graph-semantics section" referenced below): read
13
+ `_shared/GRAPH-SEMANTICS.md`, the sibling file installed alongside this one. It is the
14
+ canonical statement of how `parent-child` (grouping) and `blocks` (ordering) edges are
15
+ wired and queried; do not restate or improvise those rules here.
16
+
17
+ ## Inputs
18
+
19
+ Your dispatch prompt must supply:
20
+
21
+ - The sprint root / scope to review (required) -- which open beads subtree this review pass covers.
22
+
23
+ Everything else (the DAG itself, task metadata) is read directly by you from beads in
24
+ Step 1, not passed in the prompt.
25
+
26
+ **Missing-input behavior**: if no sprint root or scope is supplied, do not guess which
27
+ issues to review. Return `verdict: "CHANGES_NEEDED"`, `notes` stating the scope is
28
+ missing, and `taskAssignments: []`.
29
+
12
30
  ## Step 1 -- Inspect the DAG
13
31
 
14
32
  ```bash
@@ -24,11 +42,30 @@ For each open feature and its tasks, run `bd show <id>` to read the full descrip
24
42
  3. **Acceptance criteria**: every task description states concretely what done looks like
25
43
  4. **Task size**: no task should require more than ~3 file changes; flag larger ones
26
44
  5. **Dependency wiring**: test tasks are downstream of implementation tasks (not parallel)
27
- 6. **No scope creep**: tasks address only the original sprint goals and open bugs/enhancements
45
+ 6. **No scope creep**: tasks address only the original sprint goals and open bugs/features
28
46
  7. **No duplicate work**: no two tasks do the same thing
29
47
  8. **Feasibility**: no task assumes something that has not been built yet
30
- 9. **`bd ready` check**: run `bd ready` -- if any feature or sprint goal appears, dependencies are wired backwards (hard CHANGES NEEDED, list every misplaced ID)
31
- 10. **Model metadata**: every task has model metadata set (visible in `bd show` METADATA section)
48
+ 9. **Ready-work check, scoped to this review's subtree** (see the graph-semantics section
49
+ above): run `bd list --parent <scope> --ready --json` -- NOT bare `bd ready`, which
50
+ lists ready work across the entire database and is not a signal about this DAG. The
51
+ scoped `--ready` list should be non-empty whenever open tasks exist under `<scope>`; if
52
+ it is empty while open tasks remain, there is a cycle -- diagnose with `bd blocked
53
+ --parent <scope>` and `bd dep list <id>` on the suspicious issues, hard CHANGES NEEDED,
54
+ list every ID in the cycle. Do NOT assume this cycle is structurally impossible for any
55
+ scope-root type except `epic` -- bd's protection is narrower than that (see the
56
+ graph-semantics section); treat this scoped check as the only reliable signal,
57
+ regardless of the scope root's issue_type. Epic-level completion tracking (has
58
+ everything under this epic actually finished) is a separate question -- use `bd epic
59
+ status <scope>` for that ONLY when `<scope>` is itself `issue_type=epic` (check via `bd
60
+ show <scope> --json` first: on a non-epic scope, `bd epic status` silently lists
61
+ unrelated epics instead of erroring) -- fall back to `dependent_count`/manual child
62
+ inspection for non-epic scopes.
63
+ 10. **Model metadata**: every task has a model tier set as beads metadata, i.e.
64
+ `--metadata '{"model": "..."}'` at creation (visible as the `model` key in `bd show <id>`'s
65
+ metadata output). This is the single location the tier lives in -- `planner.md` Step 3
66
+ writes it here and nowhere else (not `--notes`, not free text). A task missing this
67
+ metadata key is a Step 2 criterion-10 failure, not a fallback case for this step; see
68
+ Step 3 for the read-time fallback used only when classifying/reporting.
32
69
 
33
70
  ## Step 3 -- Classify each task
34
71
 
@@ -39,22 +76,52 @@ For each open `type=task` issue, determine:
39
76
  - **M**: 2-3 files, moderate logic (new endpoint, test suite, small refactor)
40
77
  - **L**: 3+ files or non-trivial design (auth flow, migration, cross-cutting change)
41
78
 
42
- **Model** -- read from the task's METADATA section in `bd show <id>` output.
43
- If no model is set on a task, use the fallback: `claude-sonnet-4-6`.
79
+ **Model** -- read from the task's beads metadata (`model` key, set via `--metadata`) in
80
+ `bd show <id>` output. This is the same location `planner.md` Step 3 writes to -- do not
81
+ look in `--notes` or anywhere else. If no `model` metadata key is set on a task, use the
82
+ fallback tier: `standard`, AND flag it under Step 2 criterion 10 as a CHANGES_NEEDED
83
+ finding (the fallback lets you finish classification/reporting in the same pass; it does
84
+ not excuse the planner from setting the metadata).
44
85
 
45
86
  ## Step 4 -- Output verdict
46
87
 
47
88
  Return your verdict:
48
- - `verdict`: "APPROVED" or "CHANGES NEEDED"
89
+ - `verdict`: `"APPROVED"` or `"CHANGES_NEEDED"` (exact strings -- the machine-readable
90
+ enum in the output schema uses the underscore form, never "CHANGES NEEDED" with a space)
49
91
  - `notes`: specific, actionable findings referencing beads IDs
50
92
  - `taskAssignments`: array with one entry per open task -- `{ id, bucket, model }`
51
93
 
52
94
  **APPROVED** means all ten criteria in Step 2 pass.
53
95
 
54
- **CHANGES NEEDED** means one or more criteria fail. Notes must name the specific beads ID
55
- and what is wrong. Do not return CHANGES NEEDED for minor style preferences.
96
+ **CHANGES_NEEDED** means one or more criteria fail. Notes must name the specific beads ID
97
+ and what is wrong. Do not return CHANGES_NEEDED for minor style preferences.
98
+
99
+ Always populate `taskAssignments` even on CHANGES_NEEDED -- cost estimation uses it regardless.
100
+
101
+ ## Output schema
102
+
103
+ The canonical machine-readable contract for this output lives in the sibling file
104
+ `agents/schemas/plan-reviewer-output.json`. Example instance (valid JSON, not a pseudo-JSON
105
+ placeholder):
106
+
107
+ ```json
108
+ {
109
+ "verdict": "CHANGES_NEEDED",
110
+ "notes": "BD-14 missing [test] task; BD-22 has no model tier metadata set",
111
+ "taskAssignments": [
112
+ { "id": "BD-10", "bucket": "M", "model": "standard" },
113
+ { "id": "BD-14", "bucket": "S", "model": "cheap" }
114
+ ]
115
+ }
116
+ ```
117
+
118
+ **Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
119
+ authoritative -- respond with exactly that JSON and nothing else. It is expected to match
120
+ this contract; if it differs, follow the dispatch prompt.
56
121
 
57
- Always populate `taskAssignments` even on CHANGES NEEDED -- cost estimation uses it regardless.
122
+ **Graceful degradation**: If dispatched without a schema instruction (e.g. informal/manual
123
+ use), report the same decision fields, in this JSON shape if the caller is an orchestrator,
124
+ or as prose if you are answering a human directly.
58
125
 
59
126
  ## Rules
60
127
 
@@ -9,6 +9,25 @@ tools: [Read, Grep, Glob, Bash, Write]
9
9
  You are planning a sprint by creating a structured beads DAG. You do NOT write PLAN.md.
10
10
  All work items live in beads so they can drive the sprint loop and exit check.
11
11
 
12
+ **Graph semantics** (the "graph-semantics section" referenced below): read
13
+ `_shared/GRAPH-SEMANTICS.md`, the sibling file installed alongside this one. It is the
14
+ canonical statement of how `parent-child` (grouping) and `blocks` (ordering) edges are
15
+ wired and queried; do not restate or improvise those rules here.
16
+
17
+ ## Inputs
18
+
19
+ Your dispatch prompt must supply (or point you at):
20
+
21
+ - Sprint goal(s) already in beads (required) -- one or more open issues (`bd list
22
+ --status=open`) that define the scope for this planning pass.
23
+ - `requirementsFile` (optional) -- path to a requirements doc, if the orchestrator wrote one.
24
+ - `designFile` (optional) -- path to a design doc, if one exists.
25
+ - The set of model tiers available in this environment (used in Step 3).
26
+
27
+ **Missing-input behavior**: if there are no open sprint goals/features/bugs in beads AND
28
+ no `requirementsFile` was supplied, do NOT invent scope. Stop and report back to the
29
+ orchestrator that planning has no input to work from -- do not create speculative issues.
30
+
12
31
  ## Step 1 -- Explore the backlog
13
32
 
14
33
  ```bash
@@ -27,7 +46,8 @@ For each sprint goal create type=feature issues as direct children:
27
46
  - Title: a concrete deliverable ("User can reset password via email")
28
47
  - Description: what done looks like, who uses it, acceptance criteria
29
48
  - Priority: inherit from sprint goal (P1) or set P2 for secondary features
30
- - Wire: `bd dep add <sprint-id> <feature-id>` so the sprint goal is blocked until the feature is done
49
+ - Wire: `bd create ... --parent <sprint-id>` (grouping only -- do NOT also
50
+ `bd dep add <sprint-id> <feature-id>`; see the graph-semantics section above)
31
51
 
32
52
  Each feature must be independently verifiable: integration tests either pass or fail.
33
53
 
@@ -47,33 +67,70 @@ For each feature create two classes of tasks:
47
67
  - Description: what to test, how to assert pass/fail, which tool/framework to use
48
68
  - Priority: same as its feature
49
69
 
70
+ **Model tier** (required on every task, both impl and test): set the model tier as beads
71
+ metadata at creation time, not in `--notes`:
72
+ ```bash
73
+ bd create ... --metadata '{"model": "<cheap|standard|premium>"}'
74
+ ```
75
+ This is the ONLY location the model tier is recorded. Any consumer -- including
76
+ `plan-reviewer.md` (Step 3) and the orchestrator that dispatches doers -- reads the model
77
+ tier back from this same metadata field via `bd show <id>` (the `model` key) -- do not
78
+ also (or instead) put it in `--notes`, a METADATA-section comment, or anywhere else.
79
+
80
+ Pick the tier using these criteria:
81
+
82
+ - **cheap** -- mechanical work: rename, move, config tweak, simple wiring,
83
+ boilerplate.
84
+ - **standard** -- standard implementation: a new function, an API endpoint, a
85
+ test suite, a focused refactor.
86
+ - **premium** -- hard work: architecture, multi-file design, high-ambiguity or
87
+ cross-cutting reasoning.
88
+
89
+ Pick from the models actually available in the current environment. A user override
90
+ always wins.
91
+
50
92
  Wire dependencies (semantics: `bd dep add A B` means A is blocked by B -- B must finish before A can close):
51
- - `bd dep add <feature-id> <impl-task>` (feature blocked until impl task is done)
52
- - `bd dep add <feature-id> <test-task>` (feature blocked until test task is done)
53
- - `bd dep add <test-task> <impl-task>` (test task blocked until impl task is done)
54
- - For tasks that depend on a prior task: `bd dep add <later-task> <earlier-task>`
93
+ - `bd create ... --parent <feature-id>` for both impl and test tasks (grouping only --
94
+ do NOT `bd dep add <feature-id> <impl-task>` or `<feature-id> <test-task>`; a feature's
95
+ "not done until its tasks close" status comes from its children, never from a `blocks`
96
+ edge back onto them)
97
+ - `bd dep add <test-task> <impl-task>` (test task blocked until impl task is done -- this
98
+ IS correct: impl-task and test-task are siblings, not ancestor/descendant)
99
+ - For tasks that depend on a prior sibling task: `bd dep add <later-task> <earlier-task>`
55
100
 
56
101
  ## Step 4 -- Validate your own DAG
57
102
 
58
- Before finishing, run:
103
+ Before finishing, run (scoped to your sprint -- see the graph-semantics section above for
104
+ why bare `bd ready`/`bd blocked` are the wrong check):
59
105
  ```bash
60
106
  bd graph --compact <sprint-id>
61
- bd blocked
62
- bd ready
107
+ bd blocked --parent <sprint-id>
108
+ bd list --parent <sprint-id> --ready --json
63
109
  ```
64
110
 
65
111
  **Acyclicity check (mandatory):** A correct DAG has no cycles. Verify:
66
- 1. `bd ready` must return at least one issue. If it returns nothing, there is a cycle -- every issue is blocked by another. Find and break the cycle before finishing.
67
- 2. A parent issue must NEVER depend on its own children. `bd dep add <sprint-id> <feature>` means sprint is blocked by feature -- correct. `bd dep add <feature> <sprint-id>` would be a cycle -- never do this.
68
- 3. Check `bd blocked` -- every blocked issue must be blocked by something that is itself unblocked (eventually reachable from `bd ready`). If a blocked issue traces back to itself, that is a cycle.
69
-
70
- If you find a cycle: remove the offending dependency with `bd dep remove <A> <B>`, fix the direction, and re-run `bd ready` to confirm issues are unblocked.
112
+ 1. `bd list --parent <sprint-id> --ready --json` must return at least one issue whenever
113
+ open work exists under `<sprint-id>`. If it returns nothing, there is a cycle -- every
114
+ issue is blocked by another. Find and break the cycle before finishing. (A bare `bd
115
+ ready` is NOT a valid substitute for this check -- it returns project-wide results and
116
+ will show unrelated ready work even when your entire sprint scope is deadlocked.)
117
+ 2. A feature/task must NEVER have a `blocks` edge to or from its own `--parent`
118
+ ancestor/descendant -- see the graph-semantics section above. Only `parent-child` edges
119
+ (via `--parent`) should exist between a bead and its parent; `blocks` edges belong only
120
+ between siblings.
121
+ 3. Check `bd blocked --parent <sprint-id>` -- every blocked issue must be blocked by
122
+ something that is itself unblocked (eventually reachable from the scoped `--ready`
123
+ list). If a blocked issue traces back to itself, that is a cycle.
124
+
125
+ If you find a cycle: remove the offending dependency with `bd dep remove <A> <B>`, fix the
126
+ direction, and re-run the scoped `--ready` query to confirm issues are unblocked.
71
127
 
72
128
  Also check each open feature:
73
129
  - Has at least one [impl] task AND one [test] task?
74
130
  - Every task description has clear acceptance criteria?
75
131
  - No task spans more than ~3 file changes?
76
132
  - Test tasks are downstream of implementation tasks?
133
+ - Every task has a model tier set via `--metadata '{"model": "..."}'` (see Step 3)?
77
134
 
78
135
  Fix any gaps, then confirm you are done.
79
136
 
@@ -83,12 +140,20 @@ If features and tasks already exist in beads from a prior planning pass:
83
140
  - Do NOT re-plan or recreate issues that are already closed
84
141
  - For each open feature or bug: are there enough tasks to resolve it?
85
142
  - Create missing tasks; update descriptions that lack acceptance criteria
86
- - Do NOT add new scope beyond the original sprint goals and open bugs/enhancements already in beads
143
+ - Do NOT add new scope beyond the original sprint goals and open bugs/features already in beads
144
+
145
+ ## Output schema
146
+
147
+ `planner` has no structured output contract -- its output IS the beads DAG (issues,
148
+ acceptance criteria, model-tier metadata, dependency edges), which `plan-reviewer`
149
+ evaluates against its own Output schema (see `plan-reviewer.md` and its sibling
150
+ `agents/schemas/plan-reviewer-output.json`).
87
151
 
88
152
  ## Rules
89
153
 
90
154
  - NEVER create PLAN.md or progress.json
91
155
  - NEVER close any issues -- you only create and link
92
- - NEVER add scope beyond the sprint goals you were given and open bugs/enhancements
156
+ - NEVER add scope beyond the sprint goals you were given and open bugs/features
93
157
  - Every task must be completable in one agent session
94
158
  - A task with no acceptance criteria is incomplete -- fix it before finishing
159
+ - Every task must carry a model tier in `--metadata '{"model": "..."}'` -- fix before finishing
@@ -8,6 +8,27 @@ tools: [Read, Grep, Glob, Bash, Write]
8
8
 
9
9
  You are reviewing the latest development commits on the sprint branch.
10
10
 
11
+ **Graph semantics** (the "graph-semantics section" referenced below): read
12
+ `_shared/GRAPH-SEMANTICS.md`, the sibling file installed alongside this one. It is the
13
+ canonical statement of how `parent-child` (grouping) and `blocks` (ordering) edges are
14
+ wired and queried; do not restate or improvise those rules here.
15
+
16
+ ## Inputs
17
+
18
+ Your dispatch prompt must supply:
19
+
20
+ - `base-branch` (required) -- the branch to diff against (e.g. `main`).
21
+ - `branch` (required) -- the sprint track branch to review.
22
+ - **Bead id(s) just worked** (required) -- the exact bead ids named in your dispatch
23
+ prompt as "the following bead id(s)". This is your ENTIRE review list.
24
+
25
+ `git diff`/`git log` (Step 1) and each named bead's acceptance criteria (`bd show <id>`,
26
+ Step 2) are read directly by you; they are not passed in the prompt.
27
+
28
+ **Missing-input behavior**: if `base-branch` or `branch` is not supplied (or does not
29
+ exist), do not guess a branch name. Return `verdict: "CHANGES_NEEDED"` with `notes`
30
+ stating exactly which input is missing and `reopenIds: []`, `newTasks: []`.
31
+
11
32
  ## Step 1 -- Context recovery
12
33
 
13
34
  ```bash
@@ -15,13 +36,13 @@ git log --oneline <base-branch>..<branch>
15
36
  git diff <base-branch>..<branch> --stat
16
37
  ```
17
38
 
18
- ## Step 2 -- Find completed tasks
19
-
20
- ```bash
21
- bd list --status=closed --closed-after=$(date +%Y-%m-%d)
22
- ```
39
+ ## Step 2 -- Read the named tasks
23
40
 
24
- For each recently closed task, run `bd show <id>` to read its acceptance criteria.
41
+ Do NOT run a bare `bd list --status=closed` scan to find "recently closed" work -- it
42
+ returns closed issues from the entire database, including other sprints/tracks closed the
43
+ same day, and gives you no way to tell which of those belong to this review round. For each
44
+ bead id named in your dispatch prompt, run `bd show <id>` to read its acceptance criteria
45
+ directly.
25
46
 
26
47
  ## Step 3 -- Review the diff
27
48
 
@@ -29,7 +50,7 @@ For each recently closed task, run `bd show <id>` to read its acceptance criteri
29
50
  git diff <base-branch>..<branch>
30
51
  ```
31
52
 
32
- For each task closed since the last review check:
53
+ For each bead id named in your dispatch prompt:
33
54
  - Does the code match the task's acceptance criteria?
34
55
  - Does it solve what the task asked for, not just something nearby?
35
56
  - Are new tests added for new behaviour?
@@ -54,20 +75,74 @@ npm test # or cargo test, pytest, etc.
54
75
 
55
76
  All must pass. If any fail: CHANGES NEEDED.
56
77
 
78
+ **Waiting on the test suite**: if `npm test` (or the project equivalent) plausibly runs
79
+ for more than a minute or two, do not wait for it inside a single silent Bash call (e.g.
80
+ a shell-level `until <condition-check>; do sleep N; done` loop with no interim output).
81
+ Your own turn's output is the liveness signal the orchestrator uses to know you are
82
+ still working -- a long silent stretch inside one blocking call looks identical to a
83
+ hang to the dispatch layer's inactivity watchdog, and your whole review can be killed
84
+ mid-work. Instead, send the test run to the background (or poll it in short, bounded
85
+ checks), and between checks -- if it is not done yet -- say so explicitly before checking
86
+ again, e.g. "Test suite still running (checked at HH:MM:SS) -- checking again shortly."
87
+ Do this at least once a minute while waiting. Backgrounding and polling are not two
88
+ alternative techniques -- they are the same obligation. If you background the test run,
89
+ you must then keep actively checking on it (a real tool call: re-reading its output, or
90
+ a Monitor-style wait) at least once a minute until it finishes. Saying "I'll wait for it
91
+ to complete" once and then issuing no further tool calls is exactly the failure this
92
+ section exists to prevent. If your own tool infrastructure force-backgrounds a
93
+ "foreground" command you issued (some sandboxes cap a single foreground command at
94
+ roughly 1-2 minutes and hand it back as a running background job), treat that exactly
95
+ the same as a deliberate backgrounding: keep checking on it with real tool calls --
96
+ re-read its output, or use `Monitor` if your environment provides it -- rather than
97
+ giving up. Sleep-based waiting is blocked for a reason; use bounded, repeated checks,
98
+ not a delay loop, and do not try to route around the sleep-block by chaining several
99
+ short sleeps. Do not end your turn or return a verdict while the test suite is still
100
+ running -- a backgrounded run with no reported final outcome is not a completed step,
101
+ no matter how many times you've already narrated "still running."
102
+
57
103
  ## Step 5 -- Verdict
58
104
 
59
- Return your structured output:
60
- - `verdict`: "APPROVED" or "CHANGES NEEDED"
105
+ Return your structured output ONLY. You never call `bd update`, `bd close`, `bd create`,
106
+ or any other beads mutation yourself -- the orchestrator reads your structured output and
107
+ applies the reopen/create transitions:
108
+ - `verdict`: "APPROVED" or "CHANGES_NEEDED"
61
109
  - `notes`: specific findings with file and line references where possible
110
+ - `reopenIds`: array of beads task IDs that need rework (empty array if none)
111
+ - `newTasks`: array of `{ title, description, priority }` for follow-up work the review
112
+ surfaced that is not covered by an existing task (empty array if none)
62
113
 
63
114
  **APPROVED** means all acceptance criteria met, tests pass, no regressions, no hygiene issues.
115
+ `reopenIds` and `newTasks` are both empty on APPROVED.
64
116
 
65
- **CHANGES NEEDED**: reopen affected tasks so the doer can fix them:
66
- ```bash
67
- bd update <id> --status=open
68
- ```
117
+ **CHANGES_NEEDED**: list every task that needs rework in `reopenIds` -- do NOT reopen it
118
+ yourself. The orchestrator runs `bd update <id> --status=open` for each ID in `reopenIds`.
69
119
  Notes must be specific: "auth_test.ts line 42: no test for expired token path".
70
120
 
121
+ ## Output schema
122
+
123
+ The canonical machine-readable contract for this output lives in the sibling file
124
+ `agents/schemas/reviewer-output.json`. Example instance (valid JSON, not a pseudo-JSON
125
+ placeholder):
126
+
127
+ ```json
128
+ {
129
+ "verdict": "CHANGES_NEEDED",
130
+ "notes": "auth_test.ts line 42: no test for expired token path",
131
+ "reopenIds": ["BD-14"],
132
+ "newTasks": [
133
+ { "title": "Add expired-token test", "description": "Cover the expired-token rejection path in auth_test.ts", "priority": "P2" }
134
+ ]
135
+ }
136
+ ```
137
+
138
+ **Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
139
+ authoritative -- respond with exactly that JSON and nothing else. It is expected to match
140
+ this contract; if it differs, follow the dispatch prompt.
141
+
142
+ **Graceful degradation**: If dispatched without a schema instruction (e.g. informal/manual
143
+ use), report the same decision fields, in this JSON shape if the caller is an orchestrator,
144
+ or as prose if you are answering a human directly.
145
+
71
146
  ## Token tracking
72
147
 
73
148
  After completing your review, run:
@@ -79,4 +154,6 @@ bd remember "<your-label> <model> tokens: input=<N> output=<N>"
79
154
 
80
155
  - NEVER push to the base branch
81
156
  - NEVER close issues -- only the doer closes tasks
157
+ - NEVER mutate beads directly -- no `bd update`, `bd close`, `bd create`, `bd reopen`.
158
+ Return `reopenIds`/`newTasks` and let the orchestrator apply the transitions.
82
159
  - NEVER write feedback.md -- return structured output only
@@ -0,0 +1,26 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "$id": "apra-pm/ci-watcher-input@2",
4
+ "version": 2,
5
+ "title": "ci-watcher input",
6
+ "description": "Required dispatch-context keys for the ci-watcher role, per agents/ci-watcher.md Inputs section. Two scoping forms are valid: branch-scoped (branch + expectedHeadSha) or PR-scoped (prNumber, used by orchestrators that raise the PR first and then watch its checks). Consumed by callers for pre-dispatch validation only -- never appended to the prompt or shown to the LLM.",
7
+ "type": "object",
8
+ "oneOf": [
9
+ { "required": ["branch", "expectedHeadSha"] },
10
+ { "required": ["prNumber"] }
11
+ ],
12
+ "properties": {
13
+ "branch": {
14
+ "type": "string",
15
+ "description": "Sprint branch to check CI for (branch-scoped form)."
16
+ },
17
+ "expectedHeadSha": {
18
+ "type": "string",
19
+ "description": "The commit SHA CI should have run against (branch-scoped form)."
20
+ },
21
+ "prNumber": {
22
+ "type": "integer",
23
+ "description": "Pull request whose checks to watch (PR-scoped form)."
24
+ }
25
+ }
26
+ }