From e66a77272270f4a260f4bc4fcce73d116fd7fa95 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 17 Nov 2026 20:18:43 +0800 Subject: [PATCH] Explain the new failed-or-skipped and also-changed report lines in the crew manuals (GST-1455) (#4432) * Name the Failed or skipped and Also changed lines in the Captain manuals (GST-1455) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> #4273 added these lines to the READY and lane report templates; crew/docs/captain.md, the /captain skill, the crew CREW.md template and the Capy captain page still named only Unverified:. They now list all three, and say a controller asks for a missing one in a follow-up, never refuses or stales a READY for it, as with Unverified:. * fix: pre-landing review fixes Review-Finding: p1/specialist-batched#1 reader=red-team Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Add the changelog fragment for the Captain manual report lines (GST-1455) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- captain/SKILL.md | 4 +++- captain/SKILL.md.tmpl | 4 +++- captain/templates/CREW.md | 5 +++-- capy/skill/gstack/captain.md | 3 ++- changelog.d/captain-docs-report-lines.md | 1 + crew/docs/captain.md | 10 +++++++--- 6 files changed, 19 insertions(+), 8 deletions(-) create mode 100644 changelog.d/captain-docs-report-lines.md diff --git a/captain/SKILL.md b/captain/SKILL.md index ff3f42283..f5635fa43 100644 --- a/captain/SKILL.md +++ b/captain/SKILL.md @@ -191,6 +191,8 @@ and adds the lines the tool cannot know. Validate every field before the pin goe | 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 | +| `Failed or skipped` | each check, case or step that failed or never ran, or `none` | never refused or staled; ask for it | +| `Also changed` | each config, CI or out-of-scope file the PR touches, or `none` | never refused or staled; ask for it | 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. @@ -416,7 +418,7 @@ occurrence escalates. Every rerun's spend is reported. ## Reports and waves 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 +with its `Unverified:` line (after `Failed or skipped:` and `Also changed:`), 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; diff --git a/captain/SKILL.md.tmpl b/captain/SKILL.md.tmpl index ae8ea7053..03622be32 100644 --- a/captain/SKILL.md.tmpl +++ b/captain/SKILL.md.tmpl @@ -119,6 +119,8 @@ and adds the lines the tool cannot know. Validate every field before the pin goe | 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 | +| `Failed or skipped` | each check, case or step that failed or never ran, or `none` | never refused or staled; ask for it | +| `Also changed` | each config, CI or out-of-scope file the PR touches, or `none` | never refused or staled; ask for it | 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. @@ -344,7 +346,7 @@ occurrence escalates. Every rerun's spend is reported. ## Reports and waves 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 +with its `Unverified:` line (after `Failed or skipped:` and `Also changed:`), 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; diff --git a/captain/templates/CREW.md b/captain/templates/CREW.md index eb931330f..93d344a20 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, the flaky cases and the `Unverified:` line. Stamp only on the + justification, the flaky cases and the `Failed or skipped:`, `Also changed:` and + `Unverified:` lines (a missing one is asked for, never refused). 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: `crew/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 (with - its `Unverified:` line), PR, Needs, Cost, Lesson, Approvals. Home: + its `Failed or skipped:`, `Also changed:` and `Unverified:` lines), PR, Needs, Cost, Lesson, Approvals. Home: `captain/templates/report.md`. 8. **One path.** Everything goes through `CONTROLLER`, never peer to peer. Home: diff --git a/capy/skill/gstack/captain.md b/capy/skill/gstack/captain.md index 7bb28aa7e..0e9374902 100644 --- a/capy/skill/gstack/captain.md +++ b/capy/skill/gstack/captain.md @@ -150,7 +150,8 @@ Every PR you send READY on, and the READY report itself, has: evidence-ladder rung that fact reached. 4. **Approvals.** `gstack-approvals render`. 5. **Evidence.** Checks green at the head, gate or train results, flaky cases, and an `Unverified:` line: - each claim you did not check yourself and why, or `none`. You write this item; /ship does not. + each claim you did not check yourself and why, or `none`; `Failed or skipped:` and `Also changed:` lines too. + A controller asks for a missing one of the three, never refuses it. You write this item; /ship does not. The READY report attaches the key image (Capy message attachment), so the Captain can show it inline. /ship does items 1-4 when `GSTACK_CAPY=1` (its `capy-pr` section). Outside Capy, the PR body is unchanged. diff --git a/changelog.d/captain-docs-report-lines.md b/changelog.d/captain-docs-report-lines.md new file mode 100644 index 000000000..a580b24c2 --- /dev/null +++ b/changelog.d/captain-docs-report-lines.md @@ -0,0 +1 @@ +- **The Captain manuals now name the `Failed or skipped:` and `Also changed:` lines that READY and lane reports carry.** A controller asks for a missing one in a follow-up and never refuses or stales a READY over it, the same as a missing `Unverified:` (GST-1455). diff --git a/crew/docs/captain.md b/crew/docs/captain.md index 83d81079d..aa3eb84fc 100644 --- a/crew/docs/captain.md +++ b/crew/docs/captain.md @@ -68,7 +68,7 @@ surface. Keep it small and predictable: | `DIGEST.md` | the controller | Needs you / New / In progress, rewritten every turn ([template](../../captain/templates/DIGEST.md)) | | `NOTES.md` | the controller | the append-only timestamped log the digest is derived from ([template](../../captain/templates/NOTES.md)) | | `skills//SKILL.md` | the controller | crew procedures the lanes load (the runbooks) | -| `reports/.md` | each lane, once | Outcome with its Unverified line, PR, Needs, Cost, Lesson, Approvals ([template](../../captain/templates/report.md)) | +| `reports/.md` | each lane, once | Outcome with its Failed or skipped, Also changed and Unverified lines, PR, Needs, Cost, Lesson, Approvals ([template](../../captain/templates/report.md)) | | `reports/postmortem-.md` | the controller, or a lane it names | why a reverted or S1-fixed merged PR passed every reviewer ([template](../../captain/templates/postmortem.md)) | | `handoffs/` | lanes | datasets and specs the next lane needs; `handoffs/flaky-ledger.md` is the flaky ledger ([template](../../captain/templates/flaky-ledger.md)) | | `plans/` | the controller | approved plans, with their Approvals table | @@ -106,7 +106,7 @@ Where each rule lives: | 4 | File ownership: edit only what you own; the controller routes the rest | [Lane discipline](#lane-discipline); the ownership list is the digest's **In progress** | | 5 | Standing spend and its cap per rerun | [Approvals, shape A](#approvals-three-shapes); the `SPEND` parameter | | 6 | The job ends at an unstamped READY; stamp on call; never merge | [The READY contract](#the-ready-contract), the [READY](../../captain/templates/READY.md) and [slot call](../../captain/templates/slot-call.md) templates, [ship-policy.md](../../docs/ship-policy.md#stamp-at-merge) | -| 7 | One report per lane: Outcome with its Unverified line, PR, Needs, Cost, Lesson, Approvals | [Drive layout](#drive-layout); the [report template](../../captain/templates/report.md) | +| 7 | One report per lane: Outcome with its Failed or skipped, Also changed and Unverified lines, PR, Needs, Cost, Lesson, Approvals | [Drive layout](#drive-layout); the [report template](../../captain/templates/report.md) | | 8 | One path: everything through the controller, never peer to peer | [Roles](#roles); [Lane discipline](#lane-discipline) | | 9 | Hands: a real browser, the owner's session or local work go through the controller | [The owner's device](#the-owners-device) | | 10 | Keep going; come back only for scope, a conflict, access or the owner's decision | [Lane discipline](#lane-discipline) | @@ -427,7 +427,9 @@ cases are already in the ledger; the CHANGELOG entry sits under `## [Unreleased] the version files at the base's version; the lane declares the head frozen; and an `Unverified:` line lists every claim the lane did not check itself (a local test that timed out, a paid run skipped, a number a model reported, a review finding set aside on an -assumption nobody tested), or says `none`. A green PR page is not a READY. A cheap test +assumption nobody tested), or says `none`. `Failed or skipped:` and `Also changed:` lines +name each check, case or step that failed or never ran, and each config, CI or out-of-scope +file the PR touches, or say `none`. A green PR page is not a READY. A cheap test tier is not merge evidence. The controller refuses a block that misses any of this and sends the lane back, never into a train. When the contract changes (a new required line, a new check name, a new receipt), every READY @@ -435,6 +437,8 @@ taken before the change is stale: the lane runs `ready` again at the same pin an the fresh block; the controller trains nothing older than the change. The `Unverified:` line is the one exception: the controller asks for a missing line in a follow-up message, never refuses or stales a READY for it, and the lane reruns neither `ready` nor /ship. +The same exception covers a missing `Failed or skipped:` or `Also changed:` line: the +controller asks for it in a follow-up message and never refuses or stales a READY over it. ### The lane's /ship sequence before READY