From 32c3ddc7a5d7e39b77ff9f158aa8d89e6e25bcfe Mon Sep 17 00:00:00 2001
From: garrytan <garrytan@gmail.com>
Date: Sat, 17 Oct 2026 02:12:31 +0000
Subject: [PATCH] fix(evals): the docs observer accepts the spawned-prefixed
 gstack-skill-start --help read

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 test/docsync-lifecycle-interface.test.ts | 9 +++++++++
 test/helpers/docsync-observer.ts         | 1 +
 2 files changed, 10 insertions(+)

diff --git a/test/docsync-lifecycle-interface.test.ts b/test/docsync-lifecycle-interface.test.ts
index 7b8c1aa8c..995d5f672 100644
--- a/test/docsync-lifecycle-interface.test.ts
+++ b/test/docsync-lifecycle-interface.test.ts
@@ -36,6 +36,15 @@ test.each(['success', 'error', 'abort', 'unknown'])('same-session literal end ac
   expect(docsToolFailures(result, fixture)).toEqual([]);
 });
 
+test('start --help is a read with or without the spawned prefix; anything else after the prefix still names document-release', () => {
+  const start = `${fixture.skills.split(path.sep).join('/')}/bin/gstack-skill-start`;
+  expect(docsCommandAllowed(`GSTACK_SESSION_KIND=spawned ${start} --help`, fixture)).toBe(true);
+  expect(docsCommandAllowed(`${start} --help`, fixture)).toBe(true);
+  expect(docsCommandAllowed(`GSTACK_SESSION_KIND=spawned ${start} --help --skill qa`, fixture)).toBe(false);
+  expect(docsCommandAllowed(`GSTACK_SESSION_KIND=spawned ${start} --skill qa --model claude`, fixture)).toBe(false);
+  expect(docsCommandAllowed(`GSTACK_SESSION_KIND=spawned /tmp/gstack-skill-start --help`, fixture)).toBe(false);
+});
+
 test('historical misplaced spawned prefix remains rejected while corrected preamble stays supported', () => {
   const [original, spawned] = docsPreambleCommands(fixture);
   // The pre-#2763 wrapper put a misplaced prefix on its _SS assignment.
diff --git a/test/helpers/docsync-observer.ts b/test/helpers/docsync-observer.ts
index 3e5ccdf7f..96d575b17 100644
--- a/test/helpers/docsync-observer.ts
+++ b/test/helpers/docsync-observer.ts
@@ -281,6 +281,7 @@ function literalDocsCommandAllowed(text: string, fixture: ReturnType<typeof fixt
   const start = path.join(fixture.skills, 'bin/gstack-skill-start').split(path.sep).join('/');
   const end = path.join(fixture.skills, 'bin/gstack-skill-end').split(path.sep).join('/');
   if ((commandName === start || commandName === end) && rest.length === 1 && rest[0] === '--help') return true;
+  if (commandName === marker && rest.length === 2 && rest[0] === start && rest[1] === '--help') return true;
   return (commandName === marker && rest[0] === start || commandName === start || commandName === end) && args.includes('document-release');
 }