@afokapu/atdd-bun 0.7.2 → 0.8.0

package/templates/agents/delivery/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: delivery
+description: Use when a program is delivered as tranches by a coordinator and persistent drivers, with headless authors and independent reviewers. Covers activation, dispatch, model fallback, the four reviews, disputes and the evidence record the `delivery` profile checks in CI.
+---
+<!-- Generated by @afokapu/atdd-bun {{VERSION}}. Do not edit; run `atdd-bun agent init --replace`. -->
+
+The policy is the `delivery:` block of `atdd-bun.yaml`: per stage, the allowed authors and reviewers in preference order, the independence mode, and the fallback thresholds. Read it; do not hard-code models. The rules are `conventions/delivery/*.convention.yaml` in `node_modules/@afokapu/atdd-bun/`. Gate: `bun run atdd-bun delivery`.
+
+A **tranche** is one independently mergeable piece of the program, on its own branch and worktree, owned end to end by one persistent **driver**. Each tranche runs the ATDD lifecycle (`.agents/skills/atdd/SKILL.md`) with four reviews: `plan_review` after PLAN, `test_review` after RED, `code_review` after GREEN → SMOKE → REFACTOR → TRACE, and `final_review` of the PR head.
+
+## Coordinator
+
+Its job is throughput: every worker slot busy, every tranche moving. It never implements, repairs tests, reviews, or merges a tranche.
+
+1. Split the program into tranches with explicit dependencies. Activate a tranche as soon as its own dependencies have merged; do not wait for a whole wave. A tranche whose dependencies are still open may run PLAN and `plan_review` but nothing after; revalidate its plan once they merge.
+2. For each active tranche, create a worktree from the owning repository's workspace and start a driver in it through the multiplexer (see Multiplexer). Send the mandate, submit it, wait 4–6 s, and read the pane: a working indicator or agent output means it landed; an empty prompt or placeholder means retry before waiting on anything.
+3. Wait on the multiplexer's events, not polling loops, and on every driver at once. When a slot frees, give it to the next ready tranche or to planning ahead.
+4. Keep provider health for the whole program. When a driver reports a model unavailable, tell every driver to go straight to the next model in its lists until it recovers, so no tranche spends time rediscovering an outage.
+5. Intervene when a tranche is not BLOCKED yet no worker has run for a while, or when two hours pass with deliverable-shaped changes and no commit: tell the driver to commit, push and open its PR.
+6. A `BLOCKED disputed-finding` goes to the human with both sides. `BLOCKED provider-unavailable` frees the slot for other work.
+
+## Multiplexer
+
+Agents run in panes of the terminal multiplexer named in `delivery.multiplexer` (default `herdr`); say which one you are using when you start. Do not assume its commands: before the first dispatch, read its own help (`<multiplexer> --help`, then `<multiplexer> <group> --help`, and any schema it publishes) and map each operation below to a command. If one is missing, report it instead of scripting around it.
+
+| Operation | herdr |
+|---|---|
+| create a worktree under the owning repository's workspace | `herdr worktree create --workspace <repo-ws> --branch <b> --base <sha> --path <p> --label <tranche> --no-focus` |
+| start an agent in a pane with a working directory | `herdr agent start <name> --cwd <worktree> --workspace <ws> --no-focus -- codex` |
+| send text, then submit it | `herdr agent send <name> "<text>"`, then `herdr pane send-keys <pane> Enter` (send does not press Enter) |
+| read recent output | `herdr agent read <pane> --source recent-unwrapped --lines 12` |
+| wait for one pane's status or output | `herdr wait agent-status <pane> --status idle`, `herdr wait output <pane> --match "PROGRAM_EVENT" --regex` |
+| wait on every pane at once | the socket API's `events.subscribe` (`herdr api schema --json`): `pane_agent_status_changed`, `pane_exited`, `pane_output_changed` |
+| inspect a pane's process | `herdr pane process-info --pane <pane>` |
+
+## Driver
+
+1. Run each stage's author and each review as a separate headless process, a review in its own pane so its output is retained. Build the command from `delivery.commands` or the defaults below. An author runs in the tranche worktree.
+2. Run every review in its own detached worktree at the exact SHA (`git worktree add --detach <path> <sha>`), never in the tranche worktree, and give it `.agents/skills/delivery/review.md`, the stage and the SHA. The reviewer only reads and proposes. Tool allowlists cannot make a CLI fully read-only (`git diff --output=` writes), so isolation does: afterwards `git -C <path> status --porcelain` must be empty and HEAD still the SHA, or the review is a `REVIEWER_FAILURE` and does not count. Remove the worktree after retaining the report.
+3. Fallback: after `fallback.after_failures` failures within `fallback.within_minutes` (outage, rate limit, no auditable report), use the next model in the stage's list and record it with its `kind` (`outage`, `rate_limit`, `no_report`, `timeout`), `failures`, and the `window` from the first to the last counted failure. REQUEST CHANGES is never a failure. With the list exhausted, `when_exhausted: block` emits `BLOCKED provider-unavailable`; `wait` keeps retrying the last model.
+4. For each finding of a REQUEST CHANGES review, either have the author fix it, or write one rebuttal with evidence (a test result, a rule id, file:line). Then run a fresh review of the same stage. If that reviewer upholds a disputed finding, emit `BLOCKED disputed-finding`; never dispute it a second time.
+5. Any commit, regenerated file, conflict fix or rebase after an approval cancels it. A change to the code goes back through `code_review`, then `final_review`.
+6. Append every review to `<root>/<tranche>/evidence.yaml` as it happens; never edit an earlier entry, only add each finding's `outcome` (`fixed`, `withdrawn`, or `human` with the `decision`). Keep the raw reviewer output inside the tranche's folder and name it in `report`; nothing else goes in that folder. When `final_review` approves, set `status: ready` and `approved_sha` to that SHA, commit the evidence and reports alone, push, and merge with a merge commit once CI is green. A squash or rebase merge writes a commit no reviewer saw, and CI fails it after the merge.
+7. Emit events the coordinator can wait on, one line each: `PROGRAM_EVENT <tranche> <PLAN|RED|COMMIT <sha>|WORKER_START <role> <model> <sha>|WORKER_END <role> <model> <verdict>|FALLBACK <role> <from>→<to> <reason>|PLAN_REVIEW <sha>|TEST_REVIEW <sha>|CODE_REVIEW <sha>|FINAL_REVIEW <sha>|PR_OPENED <url>|MERGED <sha>|BLOCKED <reason>|HEARTBEAT>`.
+
+```yaml
+# <root>/<tranche>/evidence.yaml
+tranche: api
+status: open            # ready once final_review approves
+base_sha: 3f2a91c
+approved_sha: c77d0a2   # required when ready
+reviews:
+  - stage: code_review
+    sha: a4c0f11
+    author:   { model: glm,    run: glm-green-1 }
+    reviewer: { model: claude, run: claude-code-1 }
+    fallback: [{ role: reviewer, from: glm, kind: rate_limit, failures: 3, window: { from: "2026-09-25T09:00:00Z", to: "2026-09-25T09:08:00Z" }, reason: "429 from the provider on 3 attempts in 10 minutes" }]
+    verdict: request_changes
+    checked: [ACC-API-001, src/wagons/api, coder.bun.error-response-*]
+    findings:
+      - { id: F1, severity: high, evidence: "src/wagons/api/handler.ts:42", invariant: "coded error bodies", affects: [ui], proposed_fix: "return { code: 'API_NOT_FOUND' }" }   # outcome added once a fresh code_review confirms the fix
+    report: delivery/api/code_review-1.json
+```
+
+## Default commands
+
+`{prompt}` and `{worktree}` are substituted. Override per model under `delivery.commands.<model>.author` / `.review` when a CLI changes.
+
+| Model | Author | Review (read-only) |
+|---|---|---|
+| glm | `zcode -p="{prompt}" --cwd {worktree} --mode edit` | `zcode -p="{prompt}" --cwd {worktree} --mode plan` |
+| claude | `cd {worktree} && claude -p "{prompt}" --permission-mode acceptEdits --allowedTools "Bash(bun:*)" "Bash(git:*)" "Bash(gh pr:*)" --output-format json` | `cd {worktree} && claude -p "{prompt}" --allowedTools Read Grep Glob "Bash(git show:*)" "Bash(git diff:*)" "Bash(git log:*)" "Bash(bun test:*)" "Bash(bun run atdd-bun all)" "Bash(bun run atdd-bun planner)" "Bash(bun run atdd-bun tester)" "Bash(bun run atdd-bun coder security)" "Bash(bun run atdd-bun traceability)" "Bash(bun run atdd-bun delivery)" --disallowedTools Edit Write NotebookEdit --output-format json` |
+| codex | `codex exec --cd {worktree} --sandbox workspace-write "{prompt}"` | `codex exec --cd {worktree} --sandbox read-only "{prompt}"` |
+
+Before a hosted model receives private repository content, confirm the user or organization authorized it.
+
+Never edit this skill, `review.md`, the conventions, or loosen the `delivery:` policy to get a tranche through. If the policy must change, stop and ask the human.

package/templates/agents/delivery/review.md

@@ -0,0 +1,45 @@
+<!-- Generated by @afokapu/atdd-bun {{VERSION}}. Do not edit; run `atdd-bun agent init --replace`. -->
+# Review contract
+
+You are an independent reviewer for one stage of one tranche. The driver gave you the stage and the exact SHA.
+
+**Read only.** You run in a detached worktree at the SHA under review. Do not edit, commit, or run anything that writes to it (including output-file options such as `git diff --output=`); the driver checks it is untouched afterwards. You may read files, search, use `git show`/`git diff`/`git log`, and run the gates (`bun test`, `bun run atdd-bun …`). You judge and propose; the author applies. If you edit, your review does not count.
+
+## How to review
+
+Apply all three, every time:
+
+- **Systematic.** Work through the stage's checklist below completely. List everything you checked in `checked`, not only what failed, so a skipped area is visible.
+- **Systemic.** Look beyond the diff: contracts, other tranches, downstream owners, invariants the change could break elsewhere. Name them in each finding's `affects`.
+- **Adversarial.** Assume the work is wrong and try to prove it: inputs that fail, tests that pass for the wrong reason, ways around a gate, rules satisfied in letter only. A finding needs concrete evidence (file:line, a failing command, a counter-example); "might be an issue" is not a finding.
+
+## Checklist by stage
+
+- `plan_review`: the decomposition (wagon → WMBT → acceptance → train → journey → contract) covers the intent; every acceptance is testable and has one observable outcome; every WMBT has a SMOKE acceptance; dependencies and owned files do not overlap other tranches; `bun run atdd-bun planner` passes.
+- `test_review`: every acceptance has a RED test bound to it by URN; each test fails for the missing behaviour and would still fail for a wrong implementation; no test asserts on mocks where the acceptance names observable output; `bun run atdd-bun tester` passes.
+- `code_review`: every behaviour is correct against its acceptance, including edge and error paths; layering, composition, DTO and error-response rules hold; no security fault; SMOKE runs through the real entry point; `bun test` and `bun run atdd-bun all` pass.
+- `final_review`: the whole PR at its head SHA, read as an architecture: coherent with the plan, no drift from what the earlier stages approved, no change a stage did not review, safe for every downstream owner.
+
+## Disputes
+
+If a finding carries the author's `rebuttal`, judge it against the evidence. Withdraw it (leave it out of your findings) if the rebuttal holds. Uphold it (repeat it with the same `id`) if not. You settle it; there is no second round.
+
+## Output
+
+Return exactly one YAML document, nothing else. The driver appends it to the tranche's evidence record.
+
+```yaml
+stage: code_review            # the stage you were given
+sha: c77d0a2                  # the SHA you reviewed
+verdict: request_changes      # or approve (approve only with no critical or high finding)
+checked: [ACC-API-001, ACC-API-002, src/wagons/api, coder.bun.error-response-*]
+findings:
+  - id: F1                    # keep an upheld finding's id
+    severity: high            # critical | high | medium | low
+    evidence: src/wagons/api/handler.ts:42 returns a bare string
+    invariant: every error response carries a coded body
+    affects: [ui]
+    proposed_fix: return { code "API_NOT_FOUND" } instead of the bare string
+```
+
+Keep `proposed_fix` to a precise description or a short snippet, never a rewrite.

package/templates/github/atdd-bun.yml

@@ -4,7 +4,7 @@ on:
   pull_request:
   merge_group:
   push:
-    branches: [main, master]
+    branches: [{{PROTECTED_BRANCHES}}]
 jobs:
   atdd-bun:
     name: atdd-bun
@@ -21,6 +21,11 @@ jobs:
       - run: bun install --frozen-lockfile
       - run: bun run atdd-bun integrity
       - run: bun run atdd-bun all
+        env:
+          # The delivery profile's gate: before the merge on pull requests and the merge queue, after it on a push.
+          ATDD_DELIVERY_GATE: ${{ github.event_name == 'push' && 'post-merge' || 'merge' }}
+          # On a push, the gate judges everything since the previous tip, not only the last commit.
+          ATDD_BASE_REF: ${{ github.event_name == 'push' && github.event.before || '' }}
       - run: bun test
       - run: bun run atdd-bun release check
       - uses: actions/upload-artifact@v4