v1.70.1.0 fix: ship names the /document-release subagent at every decision point (tripwire + gate E2E) (#2700)

* fix(ship): name the /document-release subagent at every Step 18 decision point

The v1.54.0.0 carve moved Step 18 (documentation sync) into
ship/sections/pr-body.md and the Claude-host skeleton stopped saying
"document-release" anywhere in the workflow body — the dispatch became
invisible at exactly the moments an agent decides whether to open the
section. Restore visibility at three touchpoints, all subagent-framed
(never bare-slash-framed, which would invite an inline Skill invocation
that bypasses the fresh-context subagent + JSON contract):

- manifest trigger (renders into the section-index row AND the STOP
  pointer): "dispatching the /document-release subagent to sync docs
  (Step 18) and then creating or updating the PR/MR (Step 19)"
- Step 17 handoff line names Step 18's dispatch explicitly
- new hoisted doc-sync invariant beside the PR-title invariant: the
  dispatch itself is never skipped; only a failed subagent is
  non-blocking

Pin it in carve-guards: 'the /document-release subagent' (all three
touchpoints) + 'dispatches the /document-release subagent' (invariant)
must stay in the skeleton; the carved imperative 'Dispatch
/document-release as a subagent' must stay carved. Skeleton cap
91,600 → 92,300 (measured 91,764; trigger renders twice). Goldens
regenerated for all three hosts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: pin the ship→document-release Step 18 wiring with a free tripwire

Five substring/structure asserts across the carved section, the Claude
skeleton's three touchpoints, the manifest trigger, and the codex/factory
goldens (inlined Step 18 ordered before Step 19). Claude-golden asserts
deliberately omitted: host-config.test.ts already enforces golden ==
generated byte-for-byte.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: gate-tier E2E proving /ship dispatches the document-release subagent

New skill-e2e-ship-docsync: a live agent gets the sliced Step 17→19 tail
of the generated ship skeleton in a bare-remote git fixture (Steps 0-16
"done"), under a fake HOME so the STOP pointer and the Step 18 subagent
prompt resolve to planted copies, with a stub document-release skill that
returns the empty-result JSON contract. Hard assert: an Agent/Task
tool-call matching /document-release/i exists in result.toolCalls and
precedes any `gh pr create`. Neutral prompt (no STOP-Read priming, no
document-release mention — the prompt echoes into the transcript, so
asserts read toolCalls only).

Hardening from review: throw-on-marker-drift fixture slice; per-test
GSTACK_HOME + .redact-prepush-prompted marker (routes Step 17's
credential guard to its silent branch — the hermetic GSTACK_HOME pin
defeats a HOME-only override); 480s/540s timeouts (nested subagent adds
wall clock the 300s sibling never carried); 'timeout' accepted in
exitReason only because the dispatch assert is independently hard;
whole-file describeE2ETier('gate') composed with diff selection (keeps
the file out of the periodic shard census, which sits at its ceiling,
and under the hard tier-alignment invariant).

Registered as 'ship-docsync' in E2E_TOUCHFILES + E2E_TIERS (gate) in the
same commit — touchfiles.test.ts rejects either half landing first.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: fix stale document-release TODOS entry + three review-deferred items

The SHIPPED entry still described the deleted Step 8.5 post-PR cat-delegation
design from v0.8.4; replace with the current Step 18 subagent design and its
test pins. Add the three P3 items deferred from the v1.69 plan review:
dispatch receipt enforcement, land-and-deploy→canary dispatch-pin pattern,
and the periodic shard-census boundary.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: pre-landing review fixes

Testing-specialist findings, all mechanical: (1) pin the E2E fixture's git
branch (-b main / init.defaultBranch=main) and assert every setup command's
exit status so operator git config can't silently corrupt a paid run;
(2) tighten the dispatch matcher to Step 18-prompt-specific markers
(document-release/SKILL.md | executing the /document-release workflow) so a
subagent merely quoting section text can't false-pass the regression assert
(verified against recorded burn-in transcripts); (3) replace the subsumed
carve-guards anchor with three non-overlapping per-touchpoint anchors
(gerund/imperative/3rd-person) so each touchpoint is independently enforced.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: red-team review fixes

Five informational findings: TODOS shard-census arithmetic corrected (census
is 67 with one free ungated slot; the SECOND ungated file trips the floor)
and version pointer fixed (v0.18.2.0, not v0.18.1.0); the free tripwire now
pins the two dispatch-matcher marker strings so a pr-body prompt reword
fails the free suite instead of surfacing as a paid-tier mystery; the E2E
matcher gains a section-paste exclusion (scaffold strings disqualify) —
verified against all recorded runs; the E2E header documents the tierless
test:evals invisibility tradeoff.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: adversarial review fixes

Pin the E2E matcher's two EXCLUSION markers in the free tripwire (an
unpinned 'Parent processing:' reword would silently deaden the
section-paste guard while every test stayed green); add an ordering pin
(the hoisted doc-sync invariant must sit above the pr-body STOP pointer —
presence-only anchors can't catch drift below it); plant a third
cwd-relative pr-body copy inside the fixture repo, gitignored so the agent
never tries to commit test scaffolding.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore: bump version and changelog (v1.70.1.0)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: CHANGELOG accuracy fixes from the doc-release review

Three factual corrections the Step 18 doc subagent caught in the fresh
v1.70.1.0 entry: 5 tripwire tests (not 6), cost floor $0.63 per the cited
eval store (not $0.59), and the visibility claim scoped to decision points
(the re-run checklist mention survived the carve). Plus the E2E header's
stale pending-burn-in note replaced with the observed numbers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: raise bun-polyfill subprocess budget to 60s for degraded Windows runners

The 50ms-sleep test blew the 20s budget on BOTH bun retry attempts on PR
#2700's windows-latest runner (run 32989821401) — sustained AV/runner
pressure, not just the documented cold-start. Same flake passed-on-rerun on
the prompt-token-load-reduction branch yesterday. Budget only; every
assertion still checks exact output.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(ci): run the ship-docsync gate E2E in the evals matrix + silent-skip tripwire

The evals.yml matrix is hand-enumerated and the Run step never exported
EVALS_TIER, so the new whole-file-gated ship-docsync E2E would have
self-skipped even with a row — a hollow green one layer deeper than the
documented rehomed-monolith incident. Add the e2e-ship-docsync row with a
row-level `tier: gate` property, exported as EVALS_TIER by the Run step
(empty = unset for every existing row: all readers are `=== '<tier>'` or
truthiness).

New free tripwire test/evals-workflow-matrix.test.ts ratchets the class:
matrix files must exist; gate-hosting files must have a row; whole-file-gated
matrix files must carry a matching row tier; and the burn-down lists enforce
their own cleanup. It enumerates the PRE-EXISTING holes found while wiring
this (8 gate-hosting files with no row; codex/gemini rows running zero tests;
the pty-plan-smoke row hollow since its files adopted describeE2ETier) —
tracked in TODOS as the CI gate-lane hollow-coverage burn-down.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-08-27 08:46:41 -07:00
committed by GitHub
co-authored by Claude Fable 5
parent ad8400543c
commit a3749bfa4b
17 changed files with 830 additions and 19 deletions
+283
View File
@@ -0,0 +1,283 @@
/**
* /ship Step 18 doc-sync dispatch E2E — proves a live agent executing the
* ship tail (Step 17 push → Step 19 PR creation) actually dispatches the
* /document-release subagent BEFORE creating the PR. This is the behavioral
* guardrail for the wiring pinned statically by
* test/ship-document-release-dispatch.test.ts: the v1.54 carve made the
* dispatch invisible once; this test makes that class of regression loud.
*
* Gating: whole-file gate-tier self-gate (describeE2ETier) COMPOSED with
* diff-based selection (describeIfSelected). The self-gate keeps this file
* out of the periodic shard census (near its ceiling) and under the hard
* tier-alignment invariant. DELIBERATE TRADEOFF: tierless runs (`bun run
* test:evals` / `test:e2e`) skip every tier-gated file, so this test does
* NOT run there even when ship/** changed — use the gate lane locally:
* EVALS_TIER=gate bun run test:evals # diff-selected gate lane
* EVALS=1 EVALS_TIER=gate EVALS_ALL=1 bun test test/skill-e2e-ship-docsync.test.ts
*
* Fixture layout (non-obvious — fake HOME + planted skill tree):
*
* <workDir>/ (passed as env HOME)
* ├── repo/ bare-remote git fixture, feature branch,
* │ Steps 0-16 already "done" (VERSION bumped,
* │ CHANGELOG entry, change committed, not pushed)
* ├── ship/SKILL-tail.md sliced Step 17 → Step 20 from the generated
* │ skeleton (live worktree, extract-don't-copy)
* ├── ship/sections/pr-body.md planted copy (relative-resolution
* │ insurance)
* ├── gstack-home/.redact-prepush-prompted marker + env GSTACK_HOME →
* │ Step 17's credential pre-push guard takes its
* │ silent "continue" branch instead of its
* │ AskUserQuestion branch (gstack-config is absent
* │ so REDACT_PREPUSH falls back to "false")
* └── .claude/skills/gstack/
* ├── ship/sections/pr-body.md ← the STOP pointer's literal
* │ `~/.claude/...` path resolves HERE via the
* │ HOME override (CLAUDE_CONFIG_DIR is already
* │ hermetic, so overriding HOME is safe)
* └── document-release/SKILL.md ← stub: instructs the dispatched
* subagent to emit the empty-result JSON
* contract in 2-3 turns (the DISPATCH is what
* is under test; Step 18 is non-blocking)
*
* The prompt is deliberately neutral — it does NOT command STOP-Read
* compliance and does NOT name document-release. Priming the behavior under
* test would make the assert tautological (and the prompt echoes into the
* transcript, which is why asserts only ever read result.toolCalls).
*
* Cost: observed $0.63-1.04/run, 234-319s (9/9 burn-in + review runs passed;
* gate tier confirmed).
*/
import { expect, beforeAll, afterAll } from 'bun:test';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { spawnSync } from 'child_process';
import { runSkillTest } from './helpers/session-runner';
import {
ROOT, runId,
describeIfSelected, testConcurrentIfSelected,
createEvalCollector, recordE2E, finalizeEvalCollector, logCost,
} from './helpers/e2e-helpers';
import { describeE2ETier } from './helpers/e2e-gate';
const describeE2E = describeE2ETier('gate');
const evalCollector = createEvalCollector('e2e-ship-docsync');
const DOC_RELEASE_STUB = `---
name: document-release
description: Post-ship documentation update (E2E stub).
---
# Document Release (E2E stub)
You are running the documentation-sync workflow after a code push.
For this environment: compare the docs to the diff briefly; nothing needs
updating. Do NOT edit any files. Do NOT push.
Output EXACTLY this JSON object on the LAST line of your response, with no
text after it:
{"files_updated":[],"commit_sha":null,"pushed":false,"documentation_section":null}
`;
describeE2E('Ship doc-sync dispatch E2E (gate)', () => {
describeIfSelected('Ship doc-sync dispatch E2E', ['ship-docsync'], () => {
let workDir: string;
let repoDir: string;
let remoteDir: string;
beforeAll(() => {
workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-docsync-home-'));
remoteDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-docsync-remote-'));
repoDir = path.join(workDir, 'repo');
// Bare remote + clone; Steps 0-16 "already done": feature branch with a
// committed change, VERSION bumped, CHANGELOG entry written. Not pushed —
// Step 17 (the slice's first step) does that.
// Branch pinned with -b main / -c init.defaultBranch=main so operator git
// config never leaks into the fixture (default-config machines would
// otherwise create master and the later `push -u origin main` would fail).
// Every setup command asserts status — a broken fixture must fail loud
// and free here, never burn a paid run downstream.
const assertOk = (r: ReturnType<typeof spawnSync>, what: string) => {
if (r.status !== 0) {
throw new Error(
`ship-docsync fixture setup failed: ${what} → exit ${r.status}\n${r.stderr?.toString() ?? ''}`
);
}
return r;
};
assertOk(
spawnSync('git', ['init', '--bare', '-b', 'main'], { cwd: remoteDir, stdio: 'pipe', timeout: 15000 }),
'git init --bare -b main'
);
assertOk(
spawnSync('git', ['-c', 'init.defaultBranch=main', 'clone', remoteDir, repoDir], { stdio: 'pipe', timeout: 15000 }),
'git clone'
);
const run = (cmd: string, args: string[]) =>
assertOk(
spawnSync(cmd, args, { cwd: repoDir, stdio: 'pipe', timeout: 10000 }),
`${cmd} ${args.join(' ')}`
);
run('git', ['config', 'user.email', 'test@test.com']);
run('git', ['config', 'user.name', 'Test']);
run('git', ['config', 'commit.gpgsign', 'false']);
fs.writeFileSync(path.join(repoDir, 'app.ts'), 'console.log("v1");\n');
fs.writeFileSync(path.join(repoDir, 'VERSION'), '0.1.0.0\n');
fs.writeFileSync(
path.join(repoDir, 'CHANGELOG.md'),
'# Changelog\n\n## [0.1.0.0] - 2026-01-01\n\n- Initial release\n'
);
// The cwd-relative pr-body plant (below) lives inside this working tree;
// ignore it so the fixture repo stays clean and the agent never tries to
// commit test scaffolding.
fs.writeFileSync(path.join(repoDir, '.gitignore'), 'ship/\n');
run('git', ['add', 'app.ts', 'VERSION', 'CHANGELOG.md', '.gitignore']);
run('git', ['commit', '-m', 'initial']);
run('git', ['push', '-u', 'origin', 'main']);
run('git', ['checkout', '-b', 'feature/docsync-test']);
fs.writeFileSync(path.join(repoDir, 'app.ts'), 'console.log("v2");\n');
fs.writeFileSync(path.join(repoDir, 'VERSION'), '0.1.0.1\n');
fs.writeFileSync(
path.join(repoDir, 'CHANGELOG.md'),
'# Changelog\n\n## [0.1.0.1] - 2026-01-02\n\n- Docsync test feature\n\n## [0.1.0.0] - 2026-01-01\n\n- Initial release\n'
);
run('git', ['add', 'app.ts', 'VERSION', 'CHANGELOG.md']);
run('git', ['commit', '-m', 'feat: docsync test feature']);
// Extract-don't-copy: slice the LIVE generated skeleton's Step 17→19
// tail. Fail loudly on marker drift — a tolerant slice silently builds
// a wrong fixture (mirrors extractSkillSections's throw-on-rename).
const skeleton = fs.readFileSync(path.join(ROOT, 'ship', 'SKILL.md'), 'utf-8');
const start = skeleton.indexOf('## Step 17: Push');
const end = skeleton.indexOf('## Step 20: Persist ship metrics');
if (start === -1 || end === -1 || end <= start) {
throw new Error(
'ship/SKILL.md step markers moved — update the skill-e2e-ship-docsync fixture slice'
);
}
const tail = skeleton.slice(start, end);
fs.mkdirSync(path.join(workDir, 'ship', 'sections'), { recursive: true });
fs.writeFileSync(path.join(workDir, 'ship', 'SKILL-tail.md'), tail);
// Plant the real pr-body section at the STOP pointer's ~ path (HOME
// override) and at a relative path as insurance.
const prBody = fs.readFileSync(
path.join(ROOT, 'ship', 'sections', 'pr-body.md'), 'utf-8'
);
const plantedSkills = path.join(workDir, '.claude', 'skills', 'gstack');
fs.mkdirSync(path.join(plantedSkills, 'ship', 'sections'), { recursive: true });
fs.mkdirSync(path.join(plantedSkills, 'document-release'), { recursive: true });
fs.writeFileSync(path.join(plantedSkills, 'ship', 'sections', 'pr-body.md'), prBody);
fs.writeFileSync(path.join(workDir, 'ship', 'sections', 'pr-body.md'), prBody);
// Third plant: resolvable relative to the agent's cwd (repoDir), not just
// relative to SKILL-tail.md — saves a wasted turn if the agent tries a
// cwd-relative read before the ~ path.
fs.mkdirSync(path.join(repoDir, 'ship', 'sections'), { recursive: true });
fs.writeFileSync(path.join(repoDir, 'ship', 'sections', 'pr-body.md'), prBody);
fs.writeFileSync(
path.join(plantedSkills, 'document-release', 'SKILL.md'),
DOC_RELEASE_STUB
);
// Route Step 17's credential pre-push guard to its silent branch.
fs.mkdirSync(path.join(workDir, 'gstack-home'), { recursive: true });
fs.writeFileSync(
path.join(workDir, 'gstack-home', '.redact-prepush-prompted'), ''
);
});
afterAll(() => {
try { fs.rmSync(workDir, { recursive: true, force: true }); } catch {}
try { fs.rmSync(remoteDir, { recursive: true, force: true }); } catch {}
});
testConcurrentIfSelected('ship-docsync', async () => {
const result = await runSkillTest({
prompt: `You are executing the /ship workflow; your working directory is the git repo. Steps 0-16 are complete: tests passed, review done, VERSION bumped to 0.1.0.1, CHANGELOG updated, changes committed on branch feature/docsync-test. The remaining workflow is in ${path.join(workDir, 'ship', 'SKILL-tail.md')} — Read it and continue the workflow from Step 17 to completion. Base branch: main. There is no GitHub/GitLab service in this environment: if gh or glab commands fail, print the would-be PR title and body and stop. gstack helper binaries (gstack-*) are unavailable in this environment — treat their failures as no-ops and continue. Do NOT ask questions.`,
workingDirectory: repoDir,
maxTurns: 30,
allowedTools: ['Bash', 'Read', 'Grep', 'Glob', 'Write', 'Agent', 'Task'],
timeout: 480_000,
env: {
HOME: workDir,
GSTACK_HOME: path.join(workDir, 'gstack-home'),
},
testName: 'ship-docsync',
runId,
});
logCost('/ship doc-sync dispatch', result);
// Assert ONLY on result.toolCalls — the prompt and skill text echo into
// the transcript and would false-positive any transcript-wide match
// (trap documented in skill-e2e-autoplan-dual-voice.test.ts).
const calls = Array.isArray(result.toolCalls) ? result.toolCalls : [];
// Matcher is dispatch-SPECIFIC, not mention-specific: both markers come
// verbatim from the Step 18 subagent prompt dictated by pr-body.md. A
// subagent that merely quotes section text mentioning "document-release"
// (e.g. a PR-body drafter) must NOT count — that false-pass would mask
// the exact regression this test exists to catch. Verified against
// recorded burn-in transcripts: real dispatch inputs carry both markers.
// Section-paste exclusion: a subagent handed the WHOLE pr-body.md as
// context carries the markers too. The dictated Step 18 prompt never
// contains the section's scaffolding, so its presence disqualifies.
// Verified across all recorded runs: real dispatches match markers,
// zero contain scaffold strings.
const dispatchIdx = calls.findIndex((tc) => {
if (tc.tool !== 'Agent' && tc.tool !== 'Task') return false;
const input = JSON.stringify(tc.input ?? {});
return (
/document-release\/SKILL\.md|executing the \/document-release workflow/i.test(input) &&
!/## Step 19: Create PR\/MR|Parent processing:/.test(input)
);
});
const prCreateIdx = calls.findIndex(
(tc) =>
tc.tool === 'Bash' &&
/gh pr create|glab mr create/.test(String((tc.input as any)?.command ?? ''))
);
const readPrBody = calls.some(
(tc) =>
(tc.tool === 'Read' &&
/sections\/pr-body\.md/.test(String((tc.input as any)?.file_path ?? ''))) ||
(tc.tool === 'Bash' &&
/sections\/pr-body\.md/.test(String((tc.input as any)?.command ?? '')))
);
if (!readPrBody) {
// Diagnostic only — near-tautological under any prompt; the dispatch
// below is the invariant.
console.warn('ship-docsync: pr-body.md was never opened');
}
recordE2E(evalCollector, '/ship doc-sync dispatch', 'Ship doc-sync dispatch E2E', result, {
passed:
dispatchIdx >= 0 &&
(prCreateIdx < 0 || dispatchIdx < prCreateIdx) &&
['success', 'error_max_turns', 'timeout'].includes(result.exitReason),
});
// THE regression assert: the /document-release subagent was dispatched.
expect(dispatchIdx).toBeGreaterThanOrEqual(0);
// Sequencing: dispatch happens BEFORE PR creation (when a create was attempted).
if (prCreateIdx >= 0) expect(dispatchIdx).toBeLessThan(prCreateIdx);
// 'timeout' is acceptable ONLY because the dispatch assert above is
// independently hard — a run that times out AFTER a clean dispatch
// proves the invariant; one that times out before it already failed on
// dispatchIdx. Never soften dispatchIdx to compensate.
expect(['success', 'error_max_turns', 'timeout']).toContain(result.exitReason);
console.log(
`dispatchIdx=${dispatchIdx} prCreateIdx=${prCreateIdx} readPrBody=${readPrBody} exit=${result.exitReason}`
);
}, 540_000);
});
});
// Module-level afterAll — finalize eval collector after all tests complete
afterAll(async () => {
await finalizeEvalCollector(evalCollector);
});