From 7f1df86fac65e39390425cafa70ad610a02b6b66 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 1 Sep 2026 19:00:44 +0000 Subject: [PATCH] fix(document-release): one canonical spawned contract, downstream notes are pointers The diff-selected LLM-judge eval scored the skill's clarity 3 (threshold 4, main scores 4): the spawned-session rules read as three separately- framed rule sets (contract paragraph, Step 8.4d note, Codex-review skip). The contract paragraph now declares itself the single source of spawned behavior and the two downstream notes reference it instead of restating rationale. The pointer avoids naming the Codex section verbatim so the codex-host render (which strips that section) keeps its negative pin. Judge re-scored 4/5/4 across repeated samples after the change. Co-Authored-By: Claude Fable 5 --- document-release/SKILL.md | 7 ++++--- document-release/SKILL.md.tmpl | 7 ++++--- document-release/sections/release-body.md | 17 ++++++++--------- document-release/sections/release-body.md.tmpl | 8 ++++---- scripts/resolvers/review.ts | 9 ++++----- 5 files changed, 24 insertions(+), 24 deletions(-) diff --git a/document-release/SKILL.md b/document-release/SKILL.md index 5654c3886..4d7e20e3d 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -456,9 +456,10 @@ the AskUserQuestion Format spawned rule: auto-choose the RECOMMENDED option, rec in your completion report, and continue — never call AskUserQuestion, never render a prose decision brief, never end your response waiting for an answer. The NEVER-do invariants below do not relax: when a gate's recommended option would rewrite CHANGELOG content or change VERSION, -take that gate's Skip / leave-as-is option instead and record why (Step 8 carries the explicit -spawned note). If the dispatch prompt narrows scope further (e.g. /ship's docs-sync-only guard), -the prompt's restrictions win. +take that gate's Skip / leave-as-is option instead and record why. This paragraph is the single +source of spawned behavior — the spawned notes downstream (Step 8's VERSION gate, the +cross-model doc-review pass) are pointers back to it, not separate rules. If the dispatch +prompt narrows scope further (e.g. /ship's docs-sync-only guard), the prompt's restrictions win. **Only stop for:** - Risky/questionable doc changes (narrative, philosophy, security, removals, large rewrites) diff --git a/document-release/SKILL.md.tmpl b/document-release/SKILL.md.tmpl index 1056d12f8..db16e94b9 100644 --- a/document-release/SKILL.md.tmpl +++ b/document-release/SKILL.md.tmpl @@ -45,9 +45,10 @@ the AskUserQuestion Format spawned rule: auto-choose the RECOMMENDED option, rec in your completion report, and continue — never call AskUserQuestion, never render a prose decision brief, never end your response waiting for an answer. The NEVER-do invariants below do not relax: when a gate's recommended option would rewrite CHANGELOG content or change VERSION, -take that gate's Skip / leave-as-is option instead and record why (Step 8 carries the explicit -spawned note). If the dispatch prompt narrows scope further (e.g. /ship's docs-sync-only guard), -the prompt's restrictions win. +take that gate's Skip / leave-as-is option instead and record why. This paragraph is the single +source of spawned behavior — the spawned notes downstream (Step 8's VERSION gate, the +cross-model doc-review pass) are pointers back to it, not separate rules. If the dispatch +prompt narrows scope further (e.g. /ship's docs-sync-only guard), the prompt's restrictions win. **Only stop for:** - Risky/questionable doc changes (narrative, philosophy, security, removals, large rewrites) diff --git a/document-release/sections/release-body.md b/document-release/sections/release-body.md index aa8604489..86ed9821a 100644 --- a/document-release/sections/release-body.md +++ b/document-release/sections/release-body.md @@ -176,10 +176,10 @@ git diff ...HEAD -- VERSION - B) Keep current version — add new changes to the existing CHANGELOG entry - C) Skip — leave version as-is, handle later - **Spawned sessions:** the recommendation flips — choose C (leave version as-is) and record - the uncovered scope in your completion report (the `decisions` array when dispatched from - /ship). A spawned run must never change VERSION: the dispatching workflow owns version - numbering, and the parent's PR title derives from it. + **Spawned sessions** (per the spawned-dispatch contract at the top of this skill): the + recommendation flips — choose C (leave version as-is) and record the uncovered scope in + your completion report (the `decisions` array when dispatched from /ship). + A spawned run must never change VERSION: the dispatching workflow owns version numbering. The key insight: a VERSION bump set for "feature A" should not silently absorb "feature B" if feature B is substantial enough to deserve its own version entry. @@ -431,11 +431,10 @@ checks the docs against what actually shipped. This is a standard part of /docum not an opt-in. The user turns it off only by asking explicitly (`gstack-config set codex_reviews disabled`). -**Spawned-session skip:** if this session is spawned (`SESSION_KIND: spawned` echoed by the -preamble, or your dispatch prompt marks it — e.g. dispatched from /ship Step 18), skip this -entire section: the dispatching workflow owns its own review passes, and the apply gate below -needs a human. Note the skip in your completion report and continue with Step 9's doc health -summary. +**Spawned-session skip** (per the spawned-dispatch contract at the top of this skill): in a +spawned session, skip this entire section — the dispatching workflow owns its own review +passes, and the apply gate below needs a human. Note the skip in your completion report and +continue with Step 9's doc health summary. **Preflight — decide whether and how the doc review runs:** diff --git a/document-release/sections/release-body.md.tmpl b/document-release/sections/release-body.md.tmpl index 42cade85c..aa386b851 100644 --- a/document-release/sections/release-body.md.tmpl +++ b/document-release/sections/release-body.md.tmpl @@ -174,10 +174,10 @@ git diff ...HEAD -- VERSION - B) Keep current version — add new changes to the existing CHANGELOG entry - C) Skip — leave version as-is, handle later - **Spawned sessions:** the recommendation flips — choose C (leave version as-is) and record - the uncovered scope in your completion report (the `decisions` array when dispatched from - /ship). A spawned run must never change VERSION: the dispatching workflow owns version - numbering, and the parent's PR title derives from it. + **Spawned sessions** (per the spawned-dispatch contract at the top of this skill): the + recommendation flips — choose C (leave version as-is) and record the uncovered scope in + your completion report (the `decisions` array when dispatched from /ship). + A spawned run must never change VERSION: the dispatching workflow owns version numbering. The key insight: a VERSION bump set for "feature A" should not silently absorb "feature B" if feature B is substantial enough to deserve its own version entry. diff --git a/scripts/resolvers/review.ts b/scripts/resolvers/review.ts index 6f02f8481..215db1e04 100644 --- a/scripts/resolvers/review.ts +++ b/scripts/resolvers/review.ts @@ -764,11 +764,10 @@ checks the docs against what actually shipped. This is a standard part of /docum not an opt-in. The user turns it off only by asking explicitly (\`gstack-config set codex_reviews disabled\`). -**Spawned-session skip:** if this session is spawned (\`SESSION_KIND: spawned\` echoed by the -preamble, or your dispatch prompt marks it — e.g. dispatched from /ship Step 18), skip this -entire section: the dispatching workflow owns its own review passes, and the apply gate below -needs a human. Note the skip in your completion report and continue with Step 9's doc health -summary. +**Spawned-session skip** (per the spawned-dispatch contract at the top of this skill): in a +spawned session, skip this entire section — the dispatching workflow owns its own review +passes, and the apply gate below needs a human. Note the skip in your completion report and +continue with Step 9's doc health summary. **Preflight — decide whether and how the doc review runs:**