Skip to content

Accept a requested docs fix when the audit names the file with a line number - #4437

Merged
capy-ai[bot] merged 1 commit into
mainfrom
docs-requested-accepts-path-line-blockers
Nov 17, 2026
Merged

capy-ai[bot] merged 1 commit into
mainfrom
docs-requested-accepts-path-line-blockers

Conversation

@garrytan

@garrytan garrytan commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

/ship no longer refuses a small docs fix just because the documentation audit named the file with a line number, such as docs/guide.md:8: wording.

What changed
  • finish --docs-requested <path> checks that the audit's blockers or decisions name the file. The path may now be followed by :<line> or :<line>:<column> (for example changelog.d/engine-parity-decisions.md:8: wording or ...md:8:12 wording). Before, only forms like ...md: line 8 were accepted.
  • A different file whose name starts with the same path, such as docs/KEY_FILES.md.tmpl:8: when the fix is to docs/KEY_FILES.md, still doesn't match.
Why

Vorflux hit this. The audit asked for a one-line fix to a file and named it in the common path:line form, the fix was correct, and /ship still stopped with "is not named in the audit result's blockers or decisions".

Blast radius

One regular expression in lib/ship-release.ts, used only by finish --docs-requested. Every other check in finish is unchanged.

Open in Capy

Agent notes

Reported by Vorflux via FOUN-32. Lane GSTA-513.

Approvals

No approvals recorded for branch docs-requested-accepts-path-line-blockers.
Plan: exempt: bug fix (R65)
Plan check: exempt bug fix

Pre-Landing Review

Pre-Landing Review: No issues found.
REVIEW_LOOP: passes=1 blocking_found=0 deferred=0 noted=0 fixed=0 scope=frozen dispatches=1
Gate edits: none detected (1 listed, 0 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)
Review plan: light depth; one batched specialist (testing, security, state-machines, red-team) found nothing; the native adversarial reader found 2 Low items, both below the blocking floor. No second-model review (code class, no numeric claims).

Review notes

Below the blocking floor; recorded here and not fixed in this PR (open notes).

  • INFORMATIONAL lib/ship-release.ts:549 completeness: an audit that names the doc as a line range (docs/X.md:8-12) or an anchor (docs/X.md#L8) is still refused. It fails safe into stage 3 recovery, so nothing unnamed gets through.
  • INFORMATIONAL test/ship-rereview-triggers.test.ts:566 testing: the test.each title says "matches" for every case, including the negative prefix-sibling case that asserts a refusal.

Exploratory QA

Functional smoke, 2 probes, both pass: the four new finish cases (4 pass, 0 fail), and the shipped regex on 13 near-miss inputs (:8x, :8.tmpl, :8:12:3, :a, a .tmpl sibling, a prefixed path) with 0 mismatches.

Documentation

Status: current. No documentation changes were needed.

Scope: base 2af3822 to HEAD 1f2d496, one commit and three files (lib/ship-release.ts, test/ship-rereview-triggers.test.ts, changelog.d/docs-requested-accepts-path-line-blockers.md), with no staged, unstaged or new files. I searched every authored doc and template that mentions --docs-requested.

Documentation health:

  • ship/SKILL.md.tmpl: Current. Its usage line --docs-requested <path> --docs-result <json> is still accurate.
  • changelog.d/docs-requested-accepts-path-line-blockers.md: Current. It describes the path:line and path:line:column matching.

Coverage debt: the rule that decides whether an audit names a file (path, path:line, path:line:column, never a prefix-sharing sibling) is covered only by the changelog fragment and the test. No reference doc describes it, so this is a common gap but not one that blocks merge.

Diagram drift: none.

Test evidence

  • Failing first: two of the four new cases (path:line and path:line:column) fail on main 2af3822; at 1f2d496 the file passes 41/0.
  • Tests ran: targeted (bun test test/ship-rereview-triggers.test.ts) 41, exit 0.
  • Tests ran: free (bun run test) 1678 files, carried from CI run 44072066852 at tree c7d35b282001 (37,413 tests).
  • Pregate on the final tree: pass, 8 of 8 checks, 0 requires-remote obligations.
  • No prompt or template changed: evals not affected. No frontend change: no design review.
{
  "schema_version": 1,
  "pr": 4437,
  "head": "1f2d496aafa079efeaf3cf5ff048726e75ecf5ed",
  "version": "1.99.5.0",
  "base": "main",
  "gate": {
    "targeted": {
      "pass": 41,
      "fail": 0,
      "skip": 0
    },
    "free": {
      "pass": 1678,
      "fail": 0,
      "skip": 0
    }
  },
  "ci_carried": [
    {
      "lane": "free",
      "run": 44072066852,
      "attempt": 1,
      "tree": "c7d35b2820013b530f9e52ea61c7f2cc6c0add63"
    }
  ],
  "session_kind": "unattended",
  "run": "ship-4437",
  "head_tree": "c7d35b2820013b530f9e52ea61c7f2cc6c0add63",
  "product_patch_id": "971e4f7ebffd477eecbf4168f8ef49cb5455bc0e",
  "gstack_version": "1.99.5.0",
  "review_depth": {
    "depth": "light",
    "class": "code",
    "runtime_lines": 2,
    "rules": "66e5174161eecc2c",
    "base": "eb546924279c136364b1554d4f75b38d7af7e3ab",
    "registry": "eb546924279c136364b1554d4f75b38d7af7e3ab",
    "gate_scan": {
      "tagged": 0,
      "head": "1f2d496aafa079efeaf3cf5ff048726e75ecf5ed"
    },
    "reasons": [
      "runtime=2"
    ],
    "risk": [],
    "mode": "panel"
  },
  "pregate": "pass @c7d35b282001 (8 checks, current for 1f2d496aafa0)",
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "docs/, README.md, CONTRIBUTING.md and every authored doc or template mentioning --docs-requested"
  },
  "review_loop": {
    "passes": 1,
    "blocking_found": 0,
    "deferred": 0,
    "noted": 0,
    "fixed": 0,
    "scope": "frozen",
    "rounds": 1,
    "dispatches": {
      "specialist": 1
    }
  },
  "gate_dispositions": []
}

… number

finish --docs-requested refused a correct fix when the docs audit named the
file as path:line ("changelog.d/engine-parity-decisions.md:8: wording") or
path:line:column, because the match only allowed whitespace, quotes or
punctuation right after the path. It now also allows :<line> and
:<line>:<column> before those, while a different file sharing the path's
prefix still doesn't match. Reported by Vorflux via FOUN-32.

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.

@capy-ai
capy-ai Bot merged commit 127bcd6 into main Nov 17, 2026
78 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