fix: gstack-docs-candidate --help works; docs gate red lines name the denying tool failure

PR run 37239016858 ship-docsync-completion: the parent ran
'gstack-docs-candidate --help' (the helper's usage error points at --help, which
failed). That undeclared command made docsToolFailures non-empty, which denied
the atomic-replacement proof of the child's legitimate native Edit, so the red
line blamed the Edit's temp file. A replay of the capture proves the atomic
replace once --help is declared.

- the helper prints its usage for --help/-h and exits 0
- the fixture interface and command grammar admit the helper's bare --help
- the atomic-proof denial names its check and the tool failures behind it
  (deny labels renumbered to their lines)
- replay with negative controls (undeclared command, temp left behind, renamed
  elsewhere); diagnostic rerun of ship-docsync-completion passed
This commit is contained in:
garrytan committed 2026-10-04 22:49:40 +00:00
1 parent 12a5187705
commit da29f66ad5
7 files changed
+479 -32

No files matched your search

+30
View File
@@ -186,3 +186,33 @@ test('the actual ship mutation callback distinguishes whole subcommands from mer
[`git ${command}`, `git ${command} argument`, `git ${command}\targument`, `git ${command}; next`, `git ${command}&& next`, `git ${command}>out`])];
expect(callback(commands.map(command => ({ tool: 'Bash', input: { command } })))).toEqual(commands.slice(3));
});
(process.platform === 'linux' ? describe : describe.skip)('replay of PR run 37239016858 ship-docsync-completion', () => {
const captured = JSON.parse(fs.readFileSync(path.join(import.meta.dir, 'fixtures/docsync-replay/37239016858-completion-native.json'), 'utf8'));
const replay = (edit: (text: string) => string = text => text, events = captured.observation.events) => {
const fixture = fixtureDocs('updated');
const lines = captured.transcript.map((event: unknown) => edit(JSON.stringify(event).replaceAll('<HOME>', fixture.home)));
const result = { ...parseNDJSON(lines), exitReason: 'success' } as unknown as SkillTestResult;
try {
return docsWriteFailures({ ...captured.observation, events }, [DOC_PATH], { result, fixture, scripts: [path.join(fixture.home, 'fixture-publish.ts')] });
} finally { fixture.clean(); }
};
test("the child's native atomic replacement of the authored doc is proven, with the helper's --help declared", () => {
expect(replay()).toEqual([]);
});
test('an undeclared helper command still denies the atomic proof and the red line names it', () => {
expect(replay(text => text.replace('gstack-docs-candidate --help', 'gstack-docs-candidate --version'))).toEqual([
'forbidden docs write: handbook/reference/commands/widget.md.tmpl.tmp.834.e81a3a0233c1 (atomic replacement unproven at docsync-observer.ts:29 (command outside declared docs observation interface))',
]);
});
test('a temp file left behind or renamed elsewhere is not an atomic replacement', () => {
const events = captured.observation.events as QAWriteObservation['events'];
const leftBehind = events.filter(event => event.cookie === 0 || event.mask !== 0x40 && event.mask !== 0x80);
expect(replay(undefined, leftBehind)).toContainEqual(expect.stringMatching(/^forbidden docs write: handbook\/reference\/commands\/widget\.md\.tmpl\.tmp\.834\.e81a3a0233c1/));
const elsewhere = events.map(event => event.mask === 0x80 ? { ...event, path: 'handbook/reference/commands/other.md' } : event);
expect(replay(undefined, elsewhere)).toContainEqual(expect.stringMatching(/^forbidden docs write: handbook\/reference\/commands\/other\.md/));
});
});