diff --git a/captain/SKILL.md b/captain/SKILL.md index 897b7b312..41dd2db74 100644 --- a/captain/SKILL.md +++ b/captain/SKILL.md @@ -110,13 +110,12 @@ through it to one person (the owner). The operating model below is what keeps do lanes merging into one base branch every day without a red base: lanes never merge, a READY block is the only merge trigger, every merge runs through a train, every decision the owner makes is recorded in their own words, and flakes are fixed daily instead of -retried away. The guide for a team setting this up on Capy, with the drive layout and -the templates, is `docs/captain.md` in the gstack checkout; the copy-paste files are in -`captain/templates/` next to this skill. +retried away. The team guide, drive layout included, is `docs/captain.md`; the copy-paste +files are in `captain/templates/` next to this skill. Usage: `/captain [setup | ready | train | digest | approvals | flaky-pass]`; `/crew` is -the same skill. With no argument, read the crew's rules file and the digest, then do whatever the open item at -the top of the digest needs. +the same skill. With no argument, read the rules file and the digest, then act on the +digest's top open item. ## Boundaries @@ -191,11 +190,10 @@ and adds the lines the tool cannot know. Validate every field before the pin goe | `READY_RECEIPT` | the receipt path the tool wrote (local and on the notes ref) | missing | | flaky cases | each one already in the ledger, with both runs | a rerun that is not logged, or a second failure called a flake | | lane statement | "head frozen from now on" | absent | +| `Unverified` | each claim the lane did not check itself, or `none` | never refused or staled; ask for it | -Optional lines a crew may require in its rules file: the gate run id and tree hash the -lane's own gate covered (useful where lanes gate on their own machines), the issue the PR -closes, and the key before/after image for the merge ask. Ship the fields as options and -let the rules file pick; one crew's habit is not the contract. +Optional lines a crew's rules file may require: the gate run id and tree hash of the +lane's own gate, the issue the PR closes, and the key before/after image. After READY the head is frozen. A push drops the PR from any train and needs a new READY at the new head, /ship rerun included. The one exception is the stamp push below. @@ -416,14 +414,16 @@ occurrence escalates. Every rerun's spend is reported. ## Reports and waves -A lane that finishes writes `reports/.md` (`captain/templates/report.md`): Outcome, -PR (number, head, version, checks), Needs (what the owner must do), Cost, Lesson, and -the Approvals table. The controller reads reports before it reads chat, and turns every -Lesson into a rule in the rules file, a line in the standing-rules file -(`captain/templates/AGENTS.md`), or a filed tool fix. The controller's own log is -append-only and timestamped (`captain/templates/NOTES.md`); the digest is derived from it. +A lane that finishes writes `reports/.md` (`captain/templates/report.md`): Outcome +with its `Unverified:` line, PR (number, head, version, checks), Needs (what the owner +must do), Cost, Lesson, and the Approvals table. The controller reads reports before +chat and turns each Lesson into a rule, a standing-rules line (`captain/templates/AGENTS.md`) +or a filed tool fix. Its log (`captain/templates/NOTES.md`) is append-only and timestamped; +the digest comes from it. After a revert or S1 fix of a merged crew PR, the controller writes a +postmortem (`captain/templates/postmortem.md`): why did the lane and every reviewer believe +it was right? Its rule change ships as a gstack PR. -Serial slots cost tens of minutes each, so PRs in one area travel together. When more +Serial slots are slow, so PRs in one area travel together. When more than `WAVE_TRIGGER` (6) PRs are READY, run `gstack-ship-queue wave plan` for area groups of 3 to 6, each with an integrator who runs `wave build`, /ship once and READY on the wave PR: one slot, one version. Constituent heads freeze, `--drop` sends a changed one back to diff --git a/captain/SKILL.md.tmpl b/captain/SKILL.md.tmpl index b234f7d31..14f3a1b14 100644 --- a/captain/SKILL.md.tmpl +++ b/captain/SKILL.md.tmpl @@ -38,13 +38,12 @@ through it to one person (the owner). The operating model below is what keeps do lanes merging into one base branch every day without a red base: lanes never merge, a READY block is the only merge trigger, every merge runs through a train, every decision the owner makes is recorded in their own words, and flakes are fixed daily instead of -retried away. The guide for a team setting this up on Capy, with the drive layout and -the templates, is `docs/captain.md` in the gstack checkout; the copy-paste files are in -`captain/templates/` next to this skill. +retried away. The team guide, drive layout included, is `docs/captain.md`; the copy-paste +files are in `captain/templates/` next to this skill. Usage: `/captain [setup | ready | train | digest | approvals | flaky-pass]`; `/crew` is -the same skill. With no argument, read the crew's rules file and the digest, then do whatever the open item at -the top of the digest needs. +the same skill. With no argument, read the rules file and the digest, then act on the +digest's top open item. ## Boundaries @@ -119,11 +118,10 @@ and adds the lines the tool cannot know. Validate every field before the pin goe | `READY_RECEIPT` | the receipt path the tool wrote (local and on the notes ref) | missing | | flaky cases | each one already in the ledger, with both runs | a rerun that is not logged, or a second failure called a flake | | lane statement | "head frozen from now on" | absent | +| `Unverified` | each claim the lane did not check itself, or `none` | never refused or staled; ask for it | -Optional lines a crew may require in its rules file: the gate run id and tree hash the -lane's own gate covered (useful where lanes gate on their own machines), the issue the PR -closes, and the key before/after image for the merge ask. Ship the fields as options and -let the rules file pick; one crew's habit is not the contract. +Optional lines a crew's rules file may require: the gate run id and tree hash of the +lane's own gate, the issue the PR closes, and the key before/after image. After READY the head is frozen. A push drops the PR from any train and needs a new READY at the new head, /ship rerun included. The one exception is the stamp push below. @@ -344,14 +342,16 @@ occurrence escalates. Every rerun's spend is reported. ## Reports and waves -A lane that finishes writes `reports/.md` (`captain/templates/report.md`): Outcome, -PR (number, head, version, checks), Needs (what the owner must do), Cost, Lesson, and -the Approvals table. The controller reads reports before it reads chat, and turns every -Lesson into a rule in the rules file, a line in the standing-rules file -(`captain/templates/AGENTS.md`), or a filed tool fix. The controller's own log is -append-only and timestamped (`captain/templates/NOTES.md`); the digest is derived from it. +A lane that finishes writes `reports/.md` (`captain/templates/report.md`): Outcome +with its `Unverified:` line, PR (number, head, version, checks), Needs (what the owner +must do), Cost, Lesson, and the Approvals table. The controller reads reports before +chat and turns each Lesson into a rule, a standing-rules line (`captain/templates/AGENTS.md`) +or a filed tool fix. Its log (`captain/templates/NOTES.md`) is append-only and timestamped; +the digest comes from it. After a revert or S1 fix of a merged crew PR, the controller writes a +postmortem (`captain/templates/postmortem.md`): why did the lane and every reviewer believe +it was right? Its rule change ships as a gstack PR. -Serial slots cost tens of minutes each, so PRs in one area travel together. When more +Serial slots are slow, so PRs in one area travel together. When more than `WAVE_TRIGGER` (6) PRs are READY, run `gstack-ship-queue wave plan` for area groups of 3 to 6, each with an integrator who runs `wave build`, /ship once and READY on the wave PR: one slot, one version. Constituent heads freeze, `--drop` sends a changed one back to diff --git a/captain/templates/CREW.md b/captain/templates/CREW.md index fb6ac2fda..fa06c29bd 100644 --- a/captain/templates/CREW.md +++ b/captain/templates/CREW.md @@ -61,14 +61,15 @@ Homes are paths in the gstack checkout the lane checked at session start. 6. **Your job ends at an unstamped READY.** Send the block from `gstack-ship-queue ready --pr --screen|--no-screen` with the full head SHA, the screen choice and its - justification, and the flaky cases. Stamp only on the controller's slot call - (`gstack-restamp --next --base …`); push only the `BASE` merge and - `STAMP_FILES`. Never merge, never enable auto-merge. Home: `docs/captain.md` (The + justification, the flaky cases and the `Unverified:` line. Stamp only on the + controller's slot call (`gstack-restamp --next --base …`); push only the `BASE` + merge and `STAMP_FILES`. Never merge, never enable auto-merge. Home: `docs/captain.md` (The READY contract), `captain/templates/READY.md`, `captain/templates/slot-call.md`, `docs/ship-policy.md` (stamp-at-merge). -7. **Report.** `reports/.md` in the controller's drive: Outcome, PR, - Needs, Cost, Lesson, Approvals. Home: `captain/templates/report.md`. +7. **Report.** `reports/.md` in the controller's drive: Outcome (with + its `Unverified:` line), PR, Needs, Cost, Lesson, Approvals. Home: + `captain/templates/report.md`. 8. **One path.** Everything goes through `CONTROLLER`, never peer to peer. Home: `docs/captain.md` (Roles, Lane discipline). diff --git a/captain/templates/READY.md b/captain/templates/READY.md index 0129ea56b..221b1f538 100644 --- a/captain/templates/READY.md +++ b/captain/templates/READY.md @@ -39,9 +39,17 @@ pin: # the full head SHA, restated screen choice: <--no-screen: cases ran focused and passed | --screen: > flaky: > review passes: (deferred: ) +Unverified: Head frozen from now on; a push drops this PR from any train and I will READY again. ``` +`Unverified:` is required. It lists every claim in the READY that the lane did not check +itself: a local test that timed out, a paid run skipped, a number a model reported, a claim +inherited from another thread, and a review finding set aside on an assumption nobody +tested. `none` means the lane looked for each of these and found none. A missing line is +asked for as a follow-up message: it never holds a PR out of a train, does not stale +READYs sent before the line existed, and needs no new `ready` or /ship run. + Optional lines a crew's rules file may require: ```text diff --git a/captain/templates/postmortem.md b/captain/templates/postmortem.md new file mode 100644 index 000000000..5e6bc4b9a --- /dev/null +++ b/captain/templates/postmortem.md @@ -0,0 +1,77 @@ +# Postmortem: # + +The controller starts one after any revert or S1 fix of a merged crew PR: when that fix's +brief goes out, or at the latest when its READY arrives. The controller or a lane it names +writes it to `reports/postmortem-.md` in the controller's drive and links it from the +fixing PR's body by that path. A revert records what was wrong with the code; this records +why everyone who passed it believed it was right. Write it from the record, not from memory +and not from the diff alone. Split the reading across read-only subagents when it is long, +and keep each section to a table or one short paragraph. + +## What broke + + + +## How it was found + + + +## Impact + + + +## Timeline + +| Time (UTC) | Event | Source | +|---|---|---| +|