Skip to content

v1.92.24.0 fix(ship): finish accepts an owner-accepted documentation exception (GST-713) - #3776

Merged
capy-ai[bot] merged 25 commits into
mainfrom
gst-713-docs-exception-finish
Nov 1, 2026
Merged

capy-ai[bot] merged 25 commits into
mainfrom
gst-713-docs-exception-finish

Conversation

@garrytan

@garrytan garrytan commented Nov 1, 2026 •

Copy link
Copy Markdown
Owner
{
  "schema_version": 1,
  "pr": 3776,
  "head": "f4ee45cfba7733e9413dd92c40eaa584a2cfc4dc",
  "version": "1.91.374.0",
  "base": "main",
  "gate": {
    "focused": {
      "pass": 37,
      "fail": 0,
      "skip": 0
    }
  },
  "session_kind": "unattended",
  "head_tree": "3abb2e2059f8914abd3e1cc8d7f29e35f16a3720",
  "product_patch_id": "4d5383fbf7883a79283175d426979268dfe3c782",
  "gstack_version": "1.92.2.0",
  "review_depth": {
    "depth": "standard",
    "class": "code",
    "runtime_lines": 53,
    "rules": "150435b0a543019a",
    "base": "b71009c36b32f809c9ad918bddc378d6a96bb82f",
    "registry": "b71009c36b32f809c9ad918bddc378d6a96bb82f",
    "gate_scan": {
      "tagged": 0,
      "head": "f4ee45cfba7733e9413dd92c40eaa584a2cfc4dc"
    },
    "reasons": [
      "runtime=53>50"
    ]
  },
  "pregate": "requires-remote cleared @3abb2e2059f8 (7 checks, current for f4ee45cfba77)",
  "requires_remote": [
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/41284211484",
    "windows-free-tests.yml/windows-free-shard: https://github.com/garrytan/gstack/actions/runs/41284211459",
    "pregate.json/remote_gate: remote-gate tree=3abb2e2059f8 tests=18649 receipt=/home/user/.capy/work/ship-713/remote-gate-receipt-main.txt sha256=094da74a44aa"
  ],
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "updated",
    "scope": "AGENTS.md, CLAUDE.md, CONTRIBUTING.md, README.md, docs/, capy/, ship/ (diff hunks and tree grep)"
  },
  "review_loop": {
    "passes": 1,
    "blocking_found": 0,
    "deferred": 0,
    "noted": 1,
    "fixed": 2,
    "scope": "frozen",
    "fix_checks": 2,
    "dispatches": {
      "specialist": 1
    }
  },
  "carry": {
    "from": "20f17e63f81846ccf0d960affb02d7be2d271d09",
    "reason": "stack parent gst-407-ship-rereview-triggers landed + base merge + test-only change + release metadata",
    "product_patch_id": "4d5383fbf7883a79283175d426979268dfe3c782",
    "changed_paths": [
      "product:.github/workflows/free-tests.yml",
      "product:.gstack/ship-policy.json",
      "metadata:CHANGELOG.md",
      "product:TODOS.md",
      "metadata:VERSION",
      "metadata:agents-digest/gstack-AGENTS.md",
      "product:autoplan/SKILL.md.tmpl",
      "product:bin/gstack-doctor-components.sh",
      "product:bin/gstack-eval-plan",
      "product:bin/gstack-ff-update",
      "product:bin/gstack-office-hours-review",
      "product:bin/gstack-plan-reality",
      "product:bin/gstack-pregate",
      "product:bin/gstack-redact-prepush",
      "product:bin/gstack-repo-mode",
      "product:bin/gstack-review-dispatch",
      "product:bin/gstack-review-log",
      "product:bin/gstack-review-plan",
      "product:bin/gstack-review-read",
      "product:bin/gstack-session-update",
      "product:bin/gstack-ship-queue",
      "product:bin/gstack-skill-start",
      "product:bin/gstack-slug",
      "product:bin/gstack-tasks",
      "product:bin/gstack-upgrade",
      "product:browse/bin/remote-slug",
      "product:captain/SKILL.md",
      "product:captain/SKILL.md.tmpl",
      "product:captain/templates/CREW.md",
      "product:captain/templates/READY.md",
      "product:captain/templates/brief.md",
      "product:captain/templates/merge-train-peer.md",
      "product:capy/skill/gstack/SKILL.md",
      "product:capy/skill/gstack/captain.md",
      "product:careful/bin/hook-extract.sh",
      "metadata:changelog.d/gst-407-ship-rereview-triggers.md",
      "product:design-consultation/SKILL.md.tmpl",
      "product:design-html/SKILL.md",
      "product:design-html/SKILL.md.tmpl",
      "product:design-review/SKILL.md.tmpl",
      "product:design-shotgun/SKILL.md.tmpl",
      "product:design/scripts/live-gemini-check.ts",
      "product:design/src/auth.ts",
      "product:design/src/check.ts",
      "product:design/src/cli.ts",
      "product:design/src/commands.ts",
      "product:design/src/design-to-code.ts",
      "product:design/src/diff.ts",
      "product:design/src/evolve.ts",
      "product:design/src/generate.ts"
    ],
    "merge_commits": 1,
    "range_diff": "1:  1e4a85e =  1:  1e4a85e fix(ship): base merges, adjacent base edits, test-only and audit-requested fixes no longer force a second review loop (GST-407, GST-384, GST-391)\n 2:  b0db283 =  2:  b0db283 ship driver: trim two phrases for headroom with #3662\n 3:  28353fa =  3:  28353fa ship driver: keep the Next steps heading phrase the handoff check reads; trim elsewhere\n 4:  fa48f02 =  4:  fa48f02 test: regenerate ship goldens\n 5:  ccdc462 =  5:  ccdc462 fix: pre-landing review fixes\n 6:  37cfb48 =  6:  37cfb48 fix: pass-2 review fixes\n 7:  f6d6e23 =  7:  f6d6e23 fix: Step 11 review fixes; a version-only stamp_files edit after review is release metadata (GBRA-251)\n 8:  e70da9b =  8:  e70da9b fix: no test edit skips review; guard packet writes; exclusive attempt state\n 9:  41f6df0 =  9:  41f6df0 fix: attempt prints gstack's install command; carry checks the product diff outside context paths\n10:  b6a2d22 = 10:  b6a2d22 fix: oversized packets take the full loop; exact --docs-requested match; name-only test globs only in test dirs\n11:  6e928ef = 11:  6e928ef docs(unattended): carry's scoped-review refusal and what it keeps\n12:  a7ac53c = 12:  a7ac53c docs: carry's scoped-review route in ship-policy, review-policy and troubleshooting (docs-a-1)\n13:  a1ea723 = 13:  a1ea723 test(windows): curate ship-rereview-triggers out of the Windows lane like ship-release (run 41193336209)\n14:  b6a5bd1 = 14:  b6a5bd1 fix: restore bin/gstack-ship-receipt after the main merge\n15:  2c684f0 = 15:  2c684f0 fix(ship): finish runs after an owner-accepted Step 14.5 documentation exception (GST-713)\n16:  89987bf = 16:  89987bf test(ship): the exception match and every snapshot --exception refusal are covered (GST-713)\n17:  a04e6fd = 17:  a04e6fd fix(ship): the exception snapshot uses the receipt's docs parser; finish also matches scope and stops on a corrupt docs-audit record (GST-713)\n18:  20f17e6 = 18:  20f17e6 docs: DOCS_AUDIT_BLOCKED names the --exception snapshot finish needs (GST-713)\n -:  ------- > 19:  f4ee45c chore(changelog): drop #3684's fragment, already stamped into CHANGELOG.md on main",
    "covers": [
      "pre-landing review",
      "adversarial review",
      "gate integrity",
      "documentation audit"
    ],
    "reruns": [
      "CI at head (gstack-ship-queue ready requires it); test and helper code changed since the reviewed head runs there unreviewed"
    ],
    "ancestry": "linear",
    "trees": [
      "6a87123726b596acf4109e575300e8929ef328e6"
    ]
  }
}

What was wrong

When the owner accepted a Step 14.5 documentation exception (a blocked docs audit with a written docs.exception), nothing recorded that acceptance in the post-audit snapshot, so gstack-ship-release finish stopped on the blocked audit with no way through. The only exit was to hand-edit state or skip finish.

What changed

  • gstack-docs-candidate snapshot --exception <docs-audit.json> reads the audit record with the receipt's own docs parser (parseReceiptDocs) and writes the exception (who accepted it, date, via, reason, base SHA and audit scope) into the snapshot. It refuses a record that is missing, corrupt, not blocked, or carries no complete exception.
  • finish (lib/ship-release.ts) accepts a blocked audit only when the snapshot's exception matches the current .gstack/tmp/docs-audit.json exception, base and scope, and prints it on the DOCS: line. A blocked audit with no exception, a mismatched one, or a corrupt record still stops finish.
  • ship/sections/documentation.md(.tmpl) and docs/troubleshooting.md (DOCS_AUDIT_BLOCKED) name the --exception snapshot step.

Proof

test/ship-release-docs-exception.test.ts was written first and failed on the base: finish stopped on an accepted exception. It now passes, together with the refusal cases (no exception, mismatch, corrupt record, every snapshot --exception refusal).

Review notes

  • The adversarial review raised 3 Low findings, all fixed in a04e6fd (use parseReceiptDocs, match scope, stop on a corrupt record).
  • Fix-check 2, informational and left as is: finish calls a non-blocked audit that carries an exception "blocked". Only a hand-edited record reaches that state.

Summary

Stacked on #3684 (gst-407-ship-rereview-triggers); I retarget it to main when #3684 lands.

When the owner accepts a Step 14.5 documentation exception, gstack-docs-candidate snapshot --exception .gstack/tmp/docs-audit.json now writes the post-audit snapshot with the exception in it: who accepted it, the date, the relay, the reason, the audit scope and the base SHA. gstack-ship-release finish accepts a blocked audit only when that recorded exception matches the current .gstack/tmp/docs-audit.json (same exception, same scope), and prints it on its DOCS: line. The snapshot reads the record with the receipt's own docs parser, so the two can't disagree about what a valid exception is.

GST-713 before/after: finish after an owner-accepted docs exception

Why

GST-713 (GEVA-84 on gstack-evals#102): an accepted exception means the docs audit reader is skipped, so no post-audit snapshot exists, and finish requires one. Before this change an owner-accepted exception could never finish. The only ways out were to hand-edit state or skip finish.

Proof, failing first. test/ship-release-docs-exception.test.ts failed on the base b6a5bd1: snapshot --exception was an unknown argument and finish stopped for want of --docs-post. It now passes, along with the refusal cases. They cover a blocked audit with no exception, a snapshot whose docs-audit.json lost or changed its exception, a changed scope, a corrupt record, and every snapshot --exception refusal.

Blast radius

bin/gstack-docs-candidate (one new flag) and the docs stage of finish in lib/ship-release.ts. Without --exception, snapshots are byte-for-byte what they were. finish still stops on a blocked audit nobody accepted. The ship documentation section and its template, and the DOCS_AUDIT_BLOCKED entry in docs/troubleshooting.md, name the new step. It adds no network calls, environment reads, permission changes, workflow edits or dependencies.

Approvals

GStack Minder (GSTA-36) added GST-713 to this lane: "fix so the accepted exception writes a record naming the exception (who accepted it, base SHA) and finish accepts it, without letting finish pass when no exception was accepted."

Pre-Landing Review

Pre-Landing Review: 3 issues — 2 fixed, 0 deferred, 1 noted

Gate edits: none detected

Documentation

Scope: the candidate's 7 selected paths (gstack-docs-candidate --exception, ship-release finish exception handling, documentation.md and its .tmpl, the changelog fragment, the new test, a ship receipt fixture), plus docs that reference gstack-docs-candidate, DOCS_AUDIT_BLOCKED or finish. Result: the ship section and its template agree, and the changelog fragment is accurate. One gap fixed: docs/troubleshooting.md DOCS_AUDIT_BLOCKED did not mention saving the post snapshot with --exception or that finish stops without it. Debt: none found. Doc caps were not checked on the edited file, and the generated ship/SKILL.md and golden copies were not regenerated or checked, per the no-generation rule.

garrytan and others added 23 commits October 31, 2026 07:21
…ested fixes no longer force a second review loop (GST-407, GST-384, GST-391)

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>
…-triggers

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

# Conflicts:
#	ship/DRIVER.md
#	ship/DRIVER.md.tmpl
…ds; trim elsewhere

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>
comparePath returns same only when every hunk sits where the base change puts it (patch-ids ignore positions) and treats a file-mode change as changed; the scoped-review packet says when a fence is truncated; --docs-result must be the posted audit's result; the --context-reviewed record goes beside the packet, outside the worktree. Negative controls for each.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
A test edit routes as tests= only when it adds lines with no gate tag; a removed or changed line or an unreadable test diff goes through the full loop. Diffs skip textconv. A hunkless patch (binary, empty, mode-only) is same when its patch-id matches. Without --reviewed-base test files route as before. finish's packet path and attempt's state directory have fallbacks.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…ew is release metadata (GBRA-251)

gateEditedPaths reads removed lines only inside hunks; carry refuses when a path listing fails; docs freshness stops on a failed listing; attempt counts an unreadable state file. releasePaths includes stamp_files paths whose edit is a version swap under stamp_patterns.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…t state

A test-only edit with no gate tag gets the scoped fix-check of its test hunks instead of a lanes-only rerun. Packet write failures print a STOP or RECEIPT_CARRY_REFUSED. attempt's allowance uses an exclusive create.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…t diff outside context paths

The attempt STOP no longer echoes the audit child's fix text. A scoped-review carry now requires the product patch-id without the context paths to match at both heads.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…ch; name-only test globs only in test dirs

A scoped-review packet section over 200 lines sends that path to the full loop instead of a truncated packet. The docs-result path match is exact. test_*.py, *Test.java and similar count as test code only under a test directory.

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>
…roubleshooting (docs-a-1)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…like ship-release (run 41193336209)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…-triggers

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

# Conflicts:
#	bin/gstack-ship-receipt
…-triggers

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

# Conflicts:
#	bin/gstack-ship-receipt
The merge commit b10e2db wrote a truncated copy of the file. This is the
three-way merge of both sides with the refused() union: main's codes plus
RECEIPT_CARRY_SCOPED_REVIEW.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…n exception (GST-713)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…l are covered (GST-713)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…ish also matches scope and stops on a corrupt docs-audit record (GST-713)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…(GST-713)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…n-finish

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

# Conflicts:
#	bin/gstack-docs-candidate
#	lib/ship-release.ts
@capy-ai
capy-ai Bot changed the base branch from gst-407-ship-rereview-triggers to main November 1, 2026 07:17
@trunk-io

trunk-io Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

@github-actions github-actions Bot changed the title fix(ship): finish accepts an owner-accepted documentation exception (GST-713) v1.92.16.0 fix(ship): finish accepts an owner-accepted documentation exception (GST-713) Nov 1, 2026
garrytan and others added 2 commits November 1, 2026 07:17
@github-actions github-actions Bot changed the title v1.92.16.0 fix(ship): finish accepts an owner-accepted documentation exception (GST-713) v1.92.24.0 fix(ship): finish accepts an owner-accepted documentation exception (GST-713) Nov 1, 2026
@capy-ai
capy-ai Bot merged commit a2ce5bd into main Nov 1, 2026
89 of 91 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant