Skip to content

Never let a later docs-audit line override an earlier blocked result (GST-2349) - #4434

Merged
capy-ai[bot] merged 3 commits into
mainfrom
docs-audit-blocked-line-carries-gst-2349
Nov 17, 2026
Merged

capy-ai[bot] merged 3 commits into
mainfrom
docs-audit-blocked-line-carries-gst-2349

Conversation

@garrytan

@garrytan garrytan commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

/ship's documentation audit no longer accepts a passing result when an earlier line from the same audit said "blocked". The blocked verdict now carries forward, and the audit gets one free chance to restate it.

What changed
  • An earlier blocked line can't be overridden. If one JSON line for an audit says "blocked" or lists a blocker, and a later JSON line for the same audit (the last line) drops that, gstack-docs-candidate result no longer accepts the last line. It prints FORMAT_REPAIR: and re-asks once without spending an attempt. The reply must stay blocked and keep every earlier blocker, though it may add more.
  • This also covers a last line whose only fault is its format. Before, that line could be repaired back to "current". Now it can't.
  • A real content problem on the last line still spends an attempt, as before.
  • Wording now matches the code. The docs-audit step no longer says it "parses only the LAST nonempty line". A new changelog entry corrects Stop /ship's docs audit halting when the child writes prose after its result (GST-2349) #4285's claim to what the parser checks: a later JSON line or a re-ask reply can't drop a blocked verdict, but a blocker written only in prose depends on the re-ask reading it.
Why

The review of #4285 found that a blocked result line followed by an unfenced "current" JSON line as the very last line was accepted as current. Main behaved the same way before #4285, but #4285's changelog promised more than that. This closes the gap with the same one-way rule #4285 applies to its re-ask.

Blast radius

Only the documentation audit's result parser (lib/ship-docs-result.ts), one sentence in ship/sections/documentation.md, the troubleshooting entry, and a new changelog entry that corrects #4285's claim (the landed entry is left as is). Output with a single result line behaves exactly as before.

Open in Capy

Agent notes

Pre-Landing Review

Pre-Landing Review: 4 issues — 0 auto-fixed, 0 asked (0 fixed, 0 skipped), 0 deferred, 4 noted
REVIEW_LOOP: passes=1 blocking_found=0 deferred=0 noted=1 fixed=0 scope=frozen dispatches=4
Gate edits: none detected (2 listed, 0 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)
Second-model review: not run (review plan: code class, no numeric claims). Native adversarial read: completed, no blockers.

Review notes

Open notes below the blocking floor (it would fail a test, break production, or lose data or secrets); recorded here and not fixed in this PR.

  • INFORMATIONAL lib/ship-docs-result.ts:94 (testing) No test has a blocked last line that drops or replaces an earlier blocker, so removing the carried.every(...) half of the keeps check would pass all 77 tests. A direct CLI probe shows the code does refuse a swapped blocker; only the test is missing.
  • INFORMATIONAL lib/ship-docs-result.ts:95 A child that prints a blocked line, fixes the blocker, then ends with a valid updated line is now refused and ends blocked (fails closed; product call).
  • INFORMATIONAL lib/ship-docs-result.ts:47 When the last line parses, the drop path ignores content problems on earlier lines and always returns repairable: true, unlike the text-follows path.
  • INFORMATIONAL lib/ship-docs-result.ts:41 A reworded earlier blocker now triggers the drop path (new friction); an earlier blocked result not on its own JSON line is not detected (older limit).

Exploratory QA

Smoke probes against bin/gstack-docs-candidate result at bc69621: current only → DOCS_RESULT: ok; blocked then current → refused; blocked then blocked with a swapped blocker → refused; blocked then the same blocked line → DOCS_RESULT: ok status=blocked. The QA method files were not loaded (unattended run).

Documentation

Status: current. The docs already describe the change, so no edits were needed.

Scope: 3 commits (2af3822..2a2fac9) and 7 committed files, with no staged, unstaged or new files. The change: a docs-audit result whose last JSON line drops an earlier blocked status or blocker for the same audit is never accepted, and gets the free re-ask, whose reply must stay blocked.

Documentation health:

  • docs/troubleshooting.md: current. The DOCS_RESULT_INVALID fix text names the new problem string, which matches the code exactly.
  • ship/sections/documentation.md and ship/sections/documentation.md.tmpl: current. The template and the generated section match.
  • changelog.d/docs-audit-blocked-line-carries-gst-2349.md: present, read only.

Coverage debt: none new. The behavior has reference coverage in troubleshooting.md and how-to coverage in ship Step 14.5. No ASCII or Mermaid diagrams cover this path, so there is no diagram drift.

Test plan

  • bun run test: carried from CI Free Tests run 44060295520/1 at tree 4f5046290d0a (head 2a2fac9), 1678 test files, exit 0.
  • bun test test/docs-audit-result.test.ts: 77 pass, 0 fail at tree f0e33706 (bc69621); 3 failures on main 2af3822 before the fix.
  • test/size-ledger.test.ts and test/parity-suite.test.ts: 15 pass, 0 fail (review read at bc69621).
  • Guards at 4f5046290d0a: typecheck, skill-size, parity-suite, context-budget, module-size, goldens, conflict-markers all pass.
  • macOS named regressions (run 44060295520) and Windows smoke (run 44060295627) green at 2a2fac9.

Approvals

No approvals recorded for branch docs-audit-blocked-line-carries-gst-2349.
Plan: exempt: bug fix (R65)
Plan check: exempt bug fix

{
  "schema_version": 1,
  "pr": 4434,
  "head": "2a2fac9bef0aba68f46c288d92d51be9a096c574",
  "version": "1.99.5.0",
  "base": "main",
  "gate": {
    "free": {
      "pass": 1678,
      "fail": 0,
      "skip": 0
    }
  },
  "ci_carried": [
    {
      "lane": "free",
      "run": 44060295520,
      "attempt": 1,
      "tree": "4f5046290d0af017faa6090f8613ec3773e7c6de"
    }
  ],
  "session_kind": "unattended",
  "run": "run2",
  "head_tree": "4f5046290d0af017faa6090f8613ec3773e7c6de",
  "product_patch_id": "1c6006b5efa1a73cd57fbbbeea2684d5a8cbbdb9",
  "gstack_version": "1.99.5.0",
  "review_depth": {
    "depth": "light",
    "class": "code",
    "runtime_lines": 18,
    "rules": "66e5174161eecc2c",
    "base": "2af3822f94a7889096b3b2c9878fee16feb9ab25",
    "registry": "2af3822f94a7889096b3b2c9878fee16feb9ab25",
    "gate_scan": {
      "tagged": 0,
      "head": "2a2fac9bef0aba68f46c288d92d51be9a096c574"
    },
    "reasons": [
      "runtime=18"
    ],
    "risk": [],
    "mode": "panel"
  },
  "pregate": "requires-remote cleared @4f5046290d0a (8 checks, current for 2a2fac9bef0a)",
  "requires_remote": [
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/44060295520/attempts/1",
    "windows-smoke.yml/windows-smoke: https://github.com/garrytan/gstack/actions/runs/44060295627/attempts/1",
    "pregate.json/remote_gate: remote-gate tree=4f5046290d0a tests=37414 skipped=105 runs=44060295520/1 profiles=ci-reuse/free-tests heads=2a2fac9bef0a verified=2026-11-17T11:05:29.859Z"
  ],
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "README.md, docs/, CLAUDE.md, AGENTS.md, CONTRIBUTING.md and ship/sections/documentation.md.tmpl against 2af3822..2a2fac9"
  },
  "review_loop": {
    "passes": 1,
    "blocking_found": 0,
    "deferred": 0,
    "noted": 1,
    "fixed": 0,
    "scope": "frozen",
    "rounds": 1,
    "dispatches": {
      "specialist": 3,
      "red-team": 1
    }
  },
  "gate_dispositions": []
}

…ST-2349)

A blocked documentation-audit result line followed by an unfenced "current"
JSON line for the same audit as the very last line was accepted as current,
and a last "current" line whose only fault was its format was repaired back to
current. The blocked verdict now carries: a last line that drops an earlier
blocked status or blocker for the audit is never accepted and gets the
one-way re-ask, whose reply must stay blocked and keep those blockers.

Step 2 of the docs audit section no longer says it parses only the last
line, and the changelog entry now claims only what the parser checks.

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

trunk-io Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

garrytan and others added 2 commits November 17, 2026 09:42
… entry (GST-2349)

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>
@capy-ai
capy-ai Bot merged commit eb54692 into main Nov 17, 2026
57 checks passed
@garrytan garrytan mentioned this pull request Nov 17, 2026
capy-ai Bot added a commit that referenced this pull request Nov 17, 2026
- /autoplan's approval page no longer hides a reviewer's product objection behind "keep your direction". (#4431)
- Every skill that loads the shared preamble, on every host, now says to ask a question once and to check a file before handing it over. (#4383)
- The Captain manuals now name the `Failed or skipped:` and `Also changed:` lines that READY and lane reports carry. (#4432)
- gstack's shell locks hold again on Ubuntu 26.04, where `mkdir` reports success when another process won the race (GST-2247). (#4262)
- `test/gstack-lock-race.test.ts` runs the old pattern and the helper against a PATH shim that behaves like uutils 0.8.0 `mkdir`, so it runs on any runner image: the old pattern lets two of four racers win, the helper admits exactly one in each of 60 races and never overlaps across take, hold and release loops, and parallel `gstack-config` writers keep every key. (#4262)
- Windows Setup E2E now runs when `bin/gstack-lock.sh` changes. (#4433)
- Claude Code's skill list now says when to use each gstack skill, so Opus loads /review and /plan-eng-review when a request fits. (#4387)
- A pull request's merge head can no longer keep its `/ship` receipt without a full review. (#4365)
- `/ship` now counts review rounds per pull request, and the head that merges always gets a full review. (#4360)
- /ship's documentation audit no longer accepts a passing result when an earlier line from the same audit said "blocked". (#4434)
- /ship's documentation audit no longer spends an attempt when the audit child writes text after its result. (#4285)
- The README lists the two new guides, and the install doc counts its hooks right. (#4403)
- docs/releases.md now says the stable release cut treats a failed commit status as red and a pending one as still going, as it has since #4257. (#4436)
- /ship's `finish --docs-requested` now accepts a docs fix when the audit named the file with a line number. (#4437)
- Document the `.gstack/approval-classes.json` schema, `gstack-approval-classes` CLI commands, and owner approval citation format in `docs/ship-policy.md#approval-classes`. (#4355)
- `/eval-plan` now runs four result checks instead of leaving them to judgment. (#4384)
- The /review coverage-audit eval no longer fails a run that really read the source file when zsh stops a command line at an `echo ====` separator. (#4364)
- Sixteen in-repo documentation links reach their section again. (#4394)
- gstack agents now open every status report with what failed, what they didn't verify and what else they changed. (#4273)
- Two new short guides. (#4380)
- A skill you wrote whose contract still lists `check_after_last_edit` keeps the rest of its contract. (#4439)
- The ship policy guide now explains how to merge any pull request with `gstack-ship-queue land`, even in a repository with one maintainer. (#4377)
- /ship's test step runs a large unit suite on Linux. (#4426)
- Every skill that loads the shared preamble, on every host, now says never to print a whole environment, git config or process table. (#4382)
- Pull requests from /ship now open with at most three plain lines, and every merge lands as one commit titled with the PR title. (#4438)
- `gstack-pr-wait`, `gstack-ci-gate` and the release cut no longer call a commit green while a check on it failed. (#4257)
- `gstack-runaway` now says what a thread's cold and empty wakes cost, not just how many there were (GST-2770). (#4385)
- The optional Stop hook no longer checks for a test run after the last edit, and /verify asks for it in plain words instead. (#4428)
- /ship's test step says when it ran out of time, and you can set its budget. (#4429)
- The remote test command no longer puts every file on one command line. (#4429)
- The stable release no longer waits on the nightly Windows tests (GST-2815). (#4400)
- Ubicloud fan-outs can no longer overshoot the vCPU limit, and owners no longer delete each other's VMs. (#4430)
- hono is pinned to 4.13.16, which fixes five advisories the weekly OSV scan found in 4.13.13 (gstack#4406). (#4408)
- `package.json` overrides (#4408)
- `test/dependency-security.test.ts`: the lockfile floor check now covers `hono >= 4.13.16`. (#4408)
- The nightly Windows test run finishes again. (#4409)
- A short write-up checklist in ETHOS.md. (#4381)

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