v1.91.169.0 fix(evals): docs-sync fixture accepts joined Git reads, literal loops and tr pipes; late-result says what its repair fixes (GSTA-57) (#3325)

* fix(evals): docs-sync fixture accepts joined Git reads, literal loops and tr pipes; late-result says what its repair fixes (GSTA-57)

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

* v1.91.169.0 stamp

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>

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.91.169.0] - 2026-10-20
+
+**The docs-sync fixture now accepts joined Git reads, `for` loops over literal file names and a pipe into `tr` as reads, and tells the actor that the Claude config dir is off-limits. The late-result fixture now says what its one repair corrects.** In the last 20 Opus gates, `ship-docsync-current` went red 3 times. Two of those were pure reads the validator rejected: `cat personal-note.txt; echo ---; git diff main HEAD` (run 39347827595) and `for f in …; do echo "=== $f"; cat $f; done` (run 39344306426). The third (run 39338691964) was a real deviation: a stray `for_none=1;` assignment, plus the parent reading its child's session transcript under the fixture's CLAUDE_CONFIG_DIR. Both still fail. Focused trials then hit `git ls-files -z … | tr '\0' '\n'` twice, a form Fable also used in run 39186278010. `ship-docsync-late-result` went red once (run 39367310001): the parent stopped the hung child and judged that no concrete correction was available, because the prompt never said what the declared repair corrects. Focused Opus 5.5 trials: on the final tree, `ship-docsync-current` 4/5 and `ship-docsync-completion` 5/5. The current red was an unquoted `--include=*` that the shared grammar rejects as a globbed option, which is outside this change, and it passed its rule-16 rerun. Earlier trees: `ship-docsync-current` 5/5 (before `tr`), `ship-docsync-late-result` 5/5 (first repair), and one trial each of the other nine docs-sync cases, all passing.
+
+### Changed
+- **Gate integrity (a gate edit): joined Git reads, reversing #3288's choice.** #3288 (v1.91.143.0) kept Git reads out of grammar lines and told the actor to run each one alone, after Fable joined them in run 39186278010. Opus kept joining them anyway (run 39347827595), and a joined pure read is no less read-only than the same reads run one by one. So `test/helpers/docsync-observer.ts` now accepts a declared Git read joined with `;`, `&&` or `||` to the shared grammar's reads or to another Git read. The Git read is still checked literally against the declared list and stands in the line as a neutral read for the grammar. It is refused after a `cd` and as a pipe sink, and Git global options, Git writes, lifecycle, candidate, Preamble and script commands still never join. Controls that pinned `git rev-parse HEAD; git status`, `git rev-parse HEAD && git status`, `git rev-parse HEAD | cat`, `git check-ignore -v .qa-state; ls`, `git ls-tree -r HEAD | head`, `git status; ls`, `git log | head -5` and `git status; git branch --show-current; git rev-parse HEAD` as rejected now pin a joined Git write, bypass or shell sink instead (`test/docsync-command-grammar.test.ts`, `test/read-only-command-grammar.test.ts`, `test/fixtures/docsync-observer-commands.json`). The test "docsync keeps Git reads out of grammar lines" is now "docsync accepts joined Git reads".
+- **Gate integrity (a gate edit): loops.** A `for` loop anywhere in a line counts as its unrolled passes, but only with a lowercase variable, words that have no quotes, globs, braces, tilde or `$`, no other variable in the body and no nested loop. The completed-read check credits a `cat` of the document inside such a loop.
+- **Shared read-only grammar: `tr` (docs-sync and qa-only).** `test/helpers/read-only-commands.ts` accepts `tr` only after a pipe, with `-c`, `-C`, `-d`, `-s` or `-t` and one or two literal sets. It rejects `tr` as a first command, a third operand, a set holding `$`, a backtick, a brace or an unquoted glob, a redirect, and `tr … | sh`. The grammar's interface text says so, and qa-only's deadline fixture has its own accepted and rejected `tr` controls.
+- **Interface text.** The declared docs-sync interface now says joined Git reads and loops are accepted. It also names `actor-state.json` and the Claude config dir (except `settings.json`) as unreadable, because the dir holds credentials and every agent's session transcript, and it says a child is judged by the output it returns.
+- **Late-result fixture prompt.** The repairable launcher's `repair` now says it corrects the spawned-marker setup and the child transport, the faults behind a missing marker or a child that returns nothing by the Collect deadline. `test/docsync-fault-interface.test.ts` checks that only repairable prompts say so.
+
+### Fixed
+- **Free regressions.** The captured composed reads of runs 39347827595 and 39344306426, and of the focused trials, run in a fixture and leave the repository unchanged. Negative controls keep the run 39338691964 forms rejected, along with joined Git writes, `-c`/`-C` options, pipe sinks, `cd`, redirects, loop redirects, globbed, quoted, braced or tilde loop words, uppercase loop variables, stray variables, nested loops, and `tr` used outside a pipe or with a non-literal set.
+
 ## [1.91.168.0] - 2026-10-20
 
 **Four QA paid cases stop failing on valid or unclear agent behavior: `qa-only-no-fix` accepts reads joined with its exact bookkeeping calls, and the QA-callers fixture says where the handoff check goes and stops counting the explicit plan check as a wasted rerun.** Daily flaky-fix pass (GSTA-57), from the captured events of Opus gate runs 39313931713, 39332134395, 39336730429, 39320737890, 39181697029 and 39351737002.

VERSION

@@ -1 +1 @@
-1.91.168.0
+1.91.169.0

agents-digest/gstack-AGENTS.md

@@ -1,4 +1,4 @@
-# gstack digest v1.91.168.0 — regenerate/re-copy after upgrading gstack
+# gstack digest v1.91.169.0 — regenerate/re-copy after upgrading gstack
 
 Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
 for agent hosts without a full skill install. The full skills add workflows,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.91.168",
+  "version": "1.91.169",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",

test/docsync-command-grammar.test.ts

@@ -2,8 +2,8 @@ import { afterAll, beforeAll, expect, test } from 'bun:test';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { fixtureDocs, gitAt, repoSnapshot } from './helpers/docsync-fixture';
-import { docsCommandAllowed, docsNativeInterface, docsSessionOptions, docsToolFailures } from './helpers/docsync-observer';
+import { DOC_PATH, fixtureDocs, gitAt, repoSnapshot } from './helpers/docsync-fixture';
+import { docsCommandAllowed, docsCompletedRead, docsNativeInterface, docsSessionOptions, docsToolFailures } from './helpers/docsync-observer';
 import { parseNDJSON, type SkillTestResult } from './helpers/session-runner';
 
 let fixture: ReturnType<typeof fixtureDocs>;
@@ -57,7 +57,7 @@ test('captured check-ignore read is declared, executes without changing the repo
   expect(result.stdout).toContain('.qa-state');
   expect(docsToolFailures(nativeResult(command, result.stdout), fixture, [], true)).toEqual([]);
   expect(repoSnapshot(fixture.repo)).toEqual(before);
-  for (const denied of ['git check-ignore -v .qa-state; ls', 'git check-ignore -v .qa-state > out.txt']) {
+  for (const denied of ['git check-ignore -v .qa-state; git add .qa-state', 'git check-ignore -v .qa-state > out.txt']) {
     expect(docsCommandAllowed(denied, fixture)).toBe(false);
   }
 });
@@ -72,7 +72,7 @@ test('captured tracked-file listing is a declared read and leaves the repository
   expect(result.status).toBe(0);
   expect(docsToolFailures(nativeResult(command, result.stdout), fixture, [], true)).toEqual([]);
   expect(repoSnapshot(fixture.repo)).toEqual(before);
-  for (const rejected of ['git ls-tree -r HEAD > tree.txt', 'git ls-tree -r HEAD | head', 'git -c core.pager=less ls-tree HEAD']) {
+  for (const rejected of ['git ls-tree -r HEAD > tree.txt', 'git ls-tree -r HEAD | tee tree.txt', 'git -c core.pager=less ls-tree HEAD']) {
     expect(docsCommandAllowed(rejected, fixture)).toBe(false);
   }
 });
@@ -96,8 +96,8 @@ test.each([
   '{ git rev-parse HEAD; }', 'git rev-parse HEAD^{tree,commit}', 'git rev-parse HEAD@{0..2}',
   'git rev-parse HEAD^{tree}{,x}', 'git rev-parse HEAD^{tree', 'git rev-parse HEAD^{tree}}',
   'git rev-parse {HEAD}', 'git rev-parse HEAD$(pwd)', 'git rev-parse "HEAD$(pwd)"',
-  'git rev-parse `pwd`', 'git rev-parse ${HEAD}', 'git rev-parse HEAD; git status',
-  'git rev-parse HEAD && git status', 'git rev-parse HEAD | cat',
+  'git rev-parse `pwd`', 'git rev-parse ${HEAD}', 'git rev-parse HEAD; git add app.ts',
+  'git rev-parse HEAD && git commit -m changed', 'git rev-parse HEAD | sh',
   'git rev-parse HEAD > out.md', 'git rev-parse HEAD 2>/tmp/leak', 'git rev-parse HEAD < in.md',
   'git rev-parse HEAD\ngit status', 'git rev-parse HEAD &', 'git rev-parse HEAD\\^{tree}',
   'git rev-parse "HEAD^{tree}', "git rev-parse 'HEAD^{tree}", 'git rev-parse HEAD*',
@@ -406,3 +406,86 @@ test('describe forms that refresh the index or fall outside the declared set, an
     own.clean();
   }
 });
+
+
+// ship-docsync-current on Opus 5.5: run 39347827595 (PR #3300 @ ca215b0) went red only on the parent's joined Git read,
+// and run 39344306426 (PR #3312 @ c895ab9) only on the child's loop that printed each selected file under a header.
+// Both are pure reads; each still runs as declared and leaves the repository unchanged.
+const CURRENT_COMPOSED_READS = [
+  'cat personal-note.txt; echo ---; git diff main HEAD',
+  'for f in AGENTS.md README.md CHANGELOG.md TODOS.md VERSION app.ts package.json handbook/reference/commands/widget.md.tmpl personal-note.txt; do echo "=== $f"; cat $f; done',
+  'git status --porcelain && git diff --cached | head -5',
+  'for doc in README.md AGENTS.md; do git log --oneline -- $doc; done',
+  'for f in app.ts; do echo "== ${f}"; cat "$f" 2>/dev/null; done',
+  // Focused Opus trial after the first repair (2026-10-20): a loop joined to a find.
+  'for f in AGENTS.md README.md CHANGELOG.md TODOS.md VERSION app.ts package.json handbook/reference/commands/widget.md.tmpl; do echo "== $f"; cat $f; done; find <HOME>/repo -name .gstack -not -path "*/.git/*"',
+  'git status; for f in README.md AGENTS.md; do cat $f; done && git rev-parse HEAD',
+  // Round-1 focused trial and the round-2 ship-docsync-completion trial: NUL-separated paths shown one per line.
+  "git ls-files -z --cached --others --exclude-standard | tr '\\0' '\\n'",
+  "git status --porcelain=v1 --ignored; git rev-parse HEAD; git merge-base main HEAD; git branch --show-current; git ls-files -z --cached --others --exclude-standard | tr '\\0' '\\n'",
+];
+
+test('captured composed reads of ship-docsync-current are declared and leave the repository unchanged (39347827595, 39344306426)', () => {
+  const own = fixtureDocs('current');
+  try {
+    expect(docsNativeInterface(own)).toContain('The Git reads above may join such a line too');
+    expect(docsNativeInterface(own)).toContain('A for loop over literal words');
+    const before = repoSnapshot(own.repo);
+    for (const command of CURRENT_COMPOSED_READS.map(line => line.replaceAll('<HOME>', own.home))) {
+      expect(docsCommandAllowed(command, own), command).toBe(true);
+      expect(docsToolFailures(nativeResult(command, 'output', 'docs-dispatch'), own, [], true), command).toEqual([]);
+      const run = spawnSync('bash', ['-c', command], { cwd: own.repo, encoding: 'utf8', timeout: 10000 });
+      expect(run.status, `${command}: ${run.stderr}`).toBe(0);
+    }
+    expect(repoSnapshot(own.repo)).toEqual(before);
+    const doc = path.join(own.repo, DOC_PATH);
+    const source = fs.readFileSync(doc, 'utf8');
+    const credited = (command: string) => docsCompletedRead(nativeResult(command, source), doc, own);
+    expect(credited(`cat ${DOC_PATH}; git status`)).toBe(true);
+    expect(credited(`git status; cat ${DOC_PATH} | head`)).toBe(false);
+    // The focused trial's child read the document only inside its loop.
+    const loop = `for f in personal-note.txt README.md ${DOC_PATH} app.ts; do echo "=== $f"; cat $f; done`;
+    const looped = spawnSync('bash', ['-c', loop], { cwd: own.repo, encoding: 'utf8', timeout: 10000 }).stdout;
+    expect(docsCompletedRead(nativeResult(loop, looped), doc, own)).toBe(true);
+    expect(docsCompletedRead(nativeResult(`for f in ${DOC_PATH}; do cat $f | head -1; done`, source), doc, own)).toBe(false);
+    expect(docsCompletedRead(nativeResult(`for f in ${DOC_PATH}; do cat $f; cat $HOME; done`, source), doc, own)).toBe(false);
+  } finally {
+    own.clean();
+  }
+});
+
+// Run 39338691964 (PR #3308 @ 8da34e2) keeps failing on purpose: the child's stray assignment, and the parent's reads
+// of agents' session transcripts in the Claude config dir (now named off-limits in the interface). Joined Git reads
+// and loops grant no write, bypass option, pipe sink, cd, glob, variable or denied path.
+test.each([
+  'for_none=1; cat AGENTS.md README.md',
+  'find <HOME>/cc/projects -type f',
+  'grep -o SESSION_KIND <HOME>/cc/projects/session/subagents/agent-a.jsonl',
+  'cat README.md; git add app.ts', 'git diff; git commit -m changed', 'ls && git -c core.pager=less show HEAD',
+  'ls; git -C /tmp status', 'cat app.ts | git hash-object -w --stdin', 'cat app.ts | git hash-object --stdin',
+  'cd .. && git status; ls', 'cd handbook; git status', 'git diff > out.md; ls', 'ls; git diff --output=out.md',
+  'git status & ls', 'git status; rm app.ts', 'git log | sh', 'git log | tee log.md', 'git status; cat <HOME>/cc/.claude.json',
+  'git status; git remote get-url origin', "ls; git show 'HEAD", 'git status; ls $HOME',
+  'for f in README.md; do cat $f > out.md; done', 'for f in app.ts; do rm $f; done', 'for f in $(ls); do cat $f; done',
+  'for f in *; do cat $f; done', 'for f in c*/.claude.json; do cat "$f"; done', 'for PATH in /tmp; do cat README.md; done',
+  'for f in README.md; do cat $f; cat $HOME; done', 'for f in README.md; do cat $f; done; rm app.ts',
+  'for f in README.md; do cat $f; done > out.md', 'for f in "README.md"; do cat $f; done', 'for f in ../../outside; do cat $f; done',
+  'for f in ../cc/.claude.json; do cat $f; done', 'for f in app.ts; do git add $f; done', 'for f in a b; do for g in c; do cat $g; done; done',
+  'for f in README.md; do cat $f; done &', 'for f in {README,AGENTS}.md; do cat $f; done', 'for f in ~/x; do cat $f; done',
+  'ls; for f in README.md; do cat $f; done > out.md', 'for f in README.md; do cat $f; done; for g in app.ts; do rm $g; done',
+  'ls; for f in README.md; do cat $f; done | sh', 'cd ..; for f in README.md; do git status; done', 'for f in README.md; do cat $f && done',
+  "git ls-files -z | tr '\\0' '\\n' | sh", "git ls-files -z | tr '\\0' '\\n' > files.md", 'tr a b', "git ls-files | tr '$x' y",
+])('composed reads stay closed to writes and bypasses: %s', command => {
+  const line = command.replaceAll('<HOME>', fixture.home);
+  expect(docsCommandAllowed(line, fixture), line).toBe(false);
+  expect(docsToolFailures(nativeResult(line, 'successful tool acknowledgment', 'docs-dispatch'), fixture, [], true))
+    .toEqual(['command outside declared docs observation interface']);
+});
+
+test('the docs interface names the Claude config dir and private actor state as unreadable', () => {
+  const guidance = docsNativeInterface(fixture);
+  expect(guidance).toContain(`off ${fixture.env.CLAUDE_CONFIG_DIR} except its settings.json`);
+  expect(guidance).toContain("every agent's session transcript");
+  expect(guidance).toContain('judge a child only by the output it returns');
+  expect(guidance).toContain('Every read stays off actor-state.json');
+});

test/docsync-fault-interface.test.ts

@@ -544,6 +544,7 @@ mock.module(path.join(root, 'test/helpers/session-runner.ts'), () => ({ async ru
   const actor = path.join(root, 'test/helpers/docsync-fault-actor.ts');
   const stateFile = path.join(fixture.home, 'actor-state.json');
   expect(options.prompt.includes('bun ' + actor + ' repair ' + stateFile)).toBe(repairable);
+  expect(options.prompt.includes('returns no result within the Collect deadline')).toBe(repairable);
   expect(options.prompt.includes('This launcher has no repair operation')).toBe(!repairable);
   expect(options.prompt.includes('bun ' + actor + ' inspect ' + stateFile)).toBe(true);
   expect(options.prompt).toContain('batched read-only observation');

test/fixtures/docsync-observer-commands.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Bash commands from docsync E2E runs and their mutations. {repo} is the fixture repo, {other} a directory outside it, {home} the fixture home. known_good: read-only forms the observer must accept. known_bad: forms it must keep rejecting. known_bad also keeps genuine model misses from PR gate runs as negative controls. The composed cat; cat of ship-docsync-failure 38984977679 (bash#12) reads only inside the fixture home with stderr discarded, so the grammar's 2>/dev/null widening (GSTA-49, Minder-approved) moves it to known_good_posix; its 2> to a file and 1>/dev/null mutations stay known_bad. The Bash grep of ship-docsync-missing-asset 38983306684 (bash#13) is a pure read inside the fixture home, so the shared read-only grammar (GSTA-49) accepts it in known_good_posix (the grammar resolves POSIX paths only and accepts nothing on Windows), as it does the Opus slips wc -l (39173752116) and ls with a glob (effort study t10); its tee, outside-path, recursive-credential and denied-glob mutations stay in known_bad. The narrow pwd/ls/cat/stat/sha256sum forms only read inside the fixture home, never a Claude config file but settings.json, nor actor state (GSTA-49 tightening; the config dir itself stays listable): cat {home}/cc/.claude.json and cat /etc/hostname are known_bad. Fable 5.1 (PR #3288 E2E 39186278010 and a focused rerun): the grammar join applies only to its own reads, so joined Git reads stay known_bad; a trailing ; on a Git read is a harmless wrapper (known_good); a grep paged through sed -n with a line-range print script and an ls of the Claude config dir are known_good_posix; other sed scripts stay known_bad.",
+  "_comment": "Bash commands from docsync E2E runs and their mutations. {repo} is the fixture repo, {other} a directory outside it, {home} the fixture home. known_good: read-only forms the observer must accept. known_bad: forms it must keep rejecting. known_bad also keeps genuine model misses from PR gate runs as negative controls. The composed cat; cat of ship-docsync-failure 38984977679 (bash#12) reads only inside the fixture home with stderr discarded, so the grammar's 2>/dev/null widening (GSTA-49, Minder-approved) moves it to known_good_posix; its 2> to a file and 1>/dev/null mutations stay known_bad. The Bash grep of ship-docsync-missing-asset 38983306684 (bash#13) is a pure read inside the fixture home, so the shared read-only grammar (GSTA-49) accepts it in known_good_posix (the grammar resolves POSIX paths only and accepts nothing on Windows), as it does the Opus slips wc -l (39173752116) and ls with a glob (effort study t10); its tee, outside-path, recursive-credential and denied-glob mutations stay in known_bad. The narrow pwd/ls/cat/stat/sha256sum forms only read inside the fixture home, never a Claude config file but settings.json, nor actor state (GSTA-49 tightening; the config dir itself stays listable): cat {home}/cc/.claude.json and cat /etc/hostname are known_bad. Fable 5.1 (PR #3288 E2E 39186278010 and a focused rerun): the grammar join applies only to its own reads, so joined Git reads stayed known_bad until GSTA-57 (below); a trailing ; on a Git read is a harmless wrapper (known_good); a grep paged through sed -n with a line-range print script and an ls of the Claude config dir are known_good_posix; other sed scripts stay known_bad. Joined declared Git reads are accepted since ship-docsync-current runs 39347827595 and 39344306426 (GSTA-57), so git rev-parse HEAD; git status moves to known_good_posix while a joined Git write or bypass option stays known_bad.",
   "known_good": [
     "git status",
     "git -C {repo} status",
@@ -20,7 +20,8 @@
     "ls -la {home}/.claude/skills/gstack/ship/sections {home}/.claude/skills/gstack/document-release {home}/.claude/skills/gstack/document-release/*",
     "grep -n \"Ship-owned\\|^## \\|^### \\|read-only\\|spawned\" {home}/.claude/skills/gstack/document-release/SKILL.md | sed -n 1,200p",
     "cat {home}/candidate.json; echo; ls -la {home}/state {home}/cc {home}/.claude/skills/gstack/document-release {home}/.claude/skills/gstack/ship",
-    "cat {other}/bash-placeholder 2>/dev/null; cat {home}/state/config.yaml"
+    "cat {other}/bash-placeholder 2>/dev/null; cat {home}/state/config.yaml",
+    "git rev-parse HEAD; git status"
   ],
   "known_bad": [
     "git -C {other} status",
@@ -47,10 +48,11 @@
     "ls -la {home}/cc/.claude*",
     "cat {home}/cc/.claude.json",
     "cat /etc/hostname",
-    "git rev-parse HEAD; git status",
     "sed -n 1w {repo}/out.txt {repo}/README.md",
     "sed -i s/a/b/ {repo}/README.md",
     "cat {other}/bash-placeholder 2>{repo}/err.txt; cat {home}/state/config.yaml",
-    "cat {other}/bash-placeholder 1>/dev/null; cat {home}/state/config.yaml"
+    "cat {other}/bash-placeholder 1>/dev/null; cat {home}/state/config.yaml",
+    "git rev-parse HEAD; git add docs/guide.md",
+    "git status; git -C {other} status"
   ]
 }

test/helpers/docsync-fault-eval.ts

@@ -101,7 +101,7 @@ bun ${actorFile} dispatch ${stateFile} audit_id=ID candidate=ABSOLUTE_JSON_PATH
 bun ${actorFile} inspect ${stateFile}
 bun ${actorFile} status ${stateFile} task_id=RETURNED_TASK_ID
 bun ${actorFile} stop ${stateFile} task_id=RETURNED_TASK_ID
-${docsActorCanRepair(scenario) ? `bun ${actorFile} repair ${stateFile}\nThis launcher supports one concrete marking/transport repair, only after a dispatched child is confirmed settled. That isolated repair is authorized, not approval for document risks.` : 'This launcher has no repair operation or alternate launcher. Missing assets/marking, launch failures and invalid completions cannot be repaired here. Do not invoke repair or invent an inline fallback.'}
+${docsActorCanRepair(scenario) ? `bun ${actorFile} repair ${stateFile}\nThis launcher supports one concrete marking/transport repair, only after a dispatched child is confirmed settled: it corrects the launcher's spawned-marker setup and its child transport, the launch faults behind a child that returns without the spawned marker or returns no result within the Collect deadline. That isolated repair is authorized, not approval for document risks.` : 'This launcher has no repair operation or alternate launcher. Missing assets/marking, launch failures and invalid completions cannot be repaired here. Do not invoke repair or invent an inline fallback.'}
 bun ${actorFile} publish ${stateFile} audit_id=ID report=${report}
 
 prepare is a serialization convenience, not an audit or validation: after inspecting the required inputs and deciding an attempt is allowed, supply a fresh id of 1–80 letters/digits/underscores/hyphens, beginning with a letter or digit. It runs the installed gstack-docs-candidate snapshot (the section's Prepare helper) for the fixture's selection, so the new candidate JSON is the record gstack-docs-candidate compare reads, and copies the exact installed section's child prompt with literal substitutions and the observation interface to a new prompt file. It returns their paths and snapshot_command, the exact snapshot command it ran: where the section reruns the Prepare snapshot, run that command with only --out changed. Read these artifacts; use the returned paths unchanged in dispatch. prepare neither launches a child nor resets/increments the attempt count, repairs content, compares snapshots or accepts an audit. Saved files are never overwritten. Use the single batched inspect transport call (declared above) to read committed, staged, unstaged and new content in one response instead of one command per file.

test/helpers/docsync-fixture.ts

@@ -11,6 +11,11 @@ export const DOCSYNC_ROOT = path.resolve(import.meta.dir, '../..');
 export const DOC_PATH = 'handbook/reference/commands/widget.md.tmpl';
 export type DocsScenario = 'updated' | 'current' | 'risky' | 'store' | 'legacy';
 
+/** The fixture's CLAUDE_CONFIG_DIR: credentials and session transcripts, unreadable to the actor except settings.json. */
+export function docsConfigDir(home: string): string {
+  return path.join(home, 'cc');
+}
+
 export function gitAt(repo: string, ...args: string[]): string {
   const result = spawnSync('git', args, { cwd: repo, encoding: 'utf8', timeout: 15000,
     env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });
@@ -126,7 +131,7 @@ export function fixtureDocs(scenario: DocsScenario, generatedRoot = process.env.
   const state = path.join(home, 'state');
   fs.mkdirSync(state);
   fs.writeFileSync(path.join(state, 'config.yaml'), 'update_check: false\n');
-  const config = path.join(home, 'cc');
+  const config = docsConfigDir(home);
   fs.mkdirSync(config);
   fs.writeFileSync(path.join(config, '.claude.json'), JSON.stringify(buildSeedConfig({
     apiKey: process.env.ANTHROPIC_API_KEY, trustedDirs: [repo],

test/helpers/docsync-observer.ts

@@ -4,7 +4,7 @@ import { createHash } from 'node:crypto';
 import { observeQAWrites, type QAWriteObservation } from './qa-functional-observer';
 import { nativeCalls } from './qa-checkpoint-evidence';
 import type { SkillTestResult } from './session-runner';
-import { DOC_PATH, type DocsScenario, type fixtureDocs } from './docsync-fixture';
+import { DOC_PATH, docsConfigDir, type DocsScenario, type fixtureDocs } from './docsync-fixture';
 import { sliceBetween } from './skill-fixture';
 import { readOnlyCommandAllowed, readOnlyInterfaceText } from './read-only-commands';
 
@@ -227,7 +227,7 @@ function unwrapHarmlessRead(text: string, fixture: ReturnType<typeof fixtureDocs
 export function docsCommandAllowed(command: string, fixture: ReturnType<typeof fixtureDocs>, scripts: string[] = []): boolean {
   const text = command.trim();
   if (docsPreambleCommands(fixture).some(block => block.trim() === text)) return true;
-  if (readOnlyCommandAllowed(text, docsReadOnlyScope(fixture))) return true;
+  if (readOnlyCommandAllowed(text, docsReadOnlyScope(fixture)) || docsComposedReadAllowed(text, fixture)) return true;
   const insert = /^cat (['"]?)([^\s'"]+)\1 >> (['"]?)([^\s'"]+)\3$/.exec(text);
   if (insert) return [insert[2], insert[4]].every(file => path.isAbsolute(file) && /\.md$/i.test(file) &&
     !/[\x00-\x1f\x7f;&|<>`$\\()*?\[\]{}~#]/.test(file) && docsPrivateArtifact(file, fixture, scripts));
@@ -242,6 +242,81 @@ export function docsCommandAllowed(command: string, fixture: ReturnType<typeof f
   return literalDocsCommandAllowed(text, fixture, scripts);
 }
 
+const DOCS_LOOP_WORD = /^[A-Za-z0-9_./@%+,:=-]+$/;
+
+/** Unquoted ;, &&, || and | split a line into commands; null for an unterminated quote. */
+function docsTopLevelSegments(text: string): { start: number; end: number; op: string }[] | null {
+  const segments: { start: number; end: number; op: string }[] = [];
+  let quote = '';
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (quote) { if (c === quote) quote = ''; continue; }
+    if (c === "'" || c === '"') { quote = c; continue; }
+    const op = text.startsWith('&&', i) || text.startsWith('||', i) ? text.slice(i, i + 2) : c === ';' || c === '|' ? c : '';
+    if (!op) continue;
+    segments.push({ start, end: i, op });
+    start = i + op.length;
+    i += op.length - 1;
+  }
+  if (quote) return null;
+  segments.push({ start, end: text.length, op: '' });
+  return segments;
+}
+
+/**
+ * Each unquoted `for <var> in <words>; do <body>; done` in a line, replaced by its
+ * passes (the body once per word, the variable substituted). Null when a loop is
+ * not a plain loop over literal words: a lowercase variable, words without quotes,
+ * globs or $, no other variable in the body and no nested loop.
+ */
+function docsUnrollLoops(text: string): string | null {
+  const segments = docsTopLevelSegments(text);
+  if (!segments) return text;
+  let out = '';
+  let copied = 0;
+  for (let i = 0; i < segments.length; i++) {
+    const head = text.slice(segments[i]!.start, segments[i]!.end).trim();
+    if (!/^for(?:\s|$)/.test(head)) continue;
+    const loop = /^for\s+([a-z][a-z0-9]*)\s+in\s+(\S.*)$/.exec(head);
+    const close = segments.findIndex((segment, index) => index > i + 1 && text.slice(segment.start, segment.end).trim() === 'done');
+    const opening = segments[i + 1] && /^\s*do\s+/.exec(text.slice(segments[i + 1]!.start, segments[i + 1]!.end));
+    if (!loop || segments[i]!.op !== ';' || !opening || close < 0 || segments[close - 1]!.op !== ';') return null;
+    const body = text.slice(segments[i + 1]!.start + opening[0].length, segments[close - 1]!.end).trim();
+    const words = loop[2]!.trim().split(/\s+/);
+    const reference = new RegExp(`\\$(?:\\{${loop[1]}\\}|${loop[1]}(?![A-Za-z0-9_]))`, 'g');
+    if (!words.every(word => DOCS_LOOP_WORD.test(word)) || body.replace(reference, '').includes('$') || /(?:^|[;&|]\s*)for\s/.test(body)) return null;
+    out += text.slice(copied, segments[i]!.start) + words.map(word => body.replace(reference, word)).join('; ');
+    copied = segments[close]!.end;
+    i = close;
+  }
+  return out + text.slice(copied);
+}
+
+/**
+ * A read-only line the shared grammar cannot see whole: loops are checked as
+ * their unrolled passes, and each declared Git read joined to grammar reads
+ * (never after a cd, never fed by a pipe) is checked literally and then stands
+ * in the line as a neutral read for the grammar.
+ */
+function docsComposedReadAllowed(text: string, fixture: ReturnType<typeof fixtureDocs>): boolean {
+  const line = docsUnrollLoops(text);
+  if (line === null) return false;
+  if (line !== text && readOnlyCommandAllowed(line, docsReadOnlyScope(fixture))) return true;
+  const segments = docsTopLevelSegments(line);
+  if (!segments) return false;
+  const commands = segments.map(segment => line.slice(segment.start, segment.end).trim());
+  const git = commands.flatMap((command, index) => /^git(?:\s|$)/.test(command) ? [index] : []);
+  if (!git.length || commands.some(command => /^cd(?:\s|$)/.test(command))) return false;
+  let neutral = line;
+  for (const index of git.reverse()) {
+    const read = unwrapHarmlessRead(commands[index]!, fixture);
+    if (segments[index - 1]?.op === '|' || read === null || !/^git\s/.test(read) || !literalDocsCommandAllowed(read, fixture, [])) return false;
+    neutral = `${neutral.slice(0, segments[index]!.start)} pwd ${neutral.slice(segments[index]!.end)}`;
+  }
+  return readOnlyCommandAllowed(neutral, docsReadOnlyScope(fixture));
+}
+
 /** The shared read-only grammar inside the owned fixture home; private actor state and every Claude config file but settings.json (.claude.json holds the API key) stay unreadable. */
 function docsReadOnlyScope(fixture: ReturnType<typeof fixtureDocs>) {
   const config = actualWritePath(fixture.env.CLAUDE_CONFIG_DIR);
@@ -311,7 +386,7 @@ function literalDocsCommandAllowed(text: string, fixture: ReturnType<typeof fixt
 
 export function docsNativeInterface(fixture: Pick<ReturnType<typeof fixtureDocs>, 'home' | 'repo' | 'skills'>, scripts: string[] = [], transport = false, insert = false, file?: string): string {
   const skills = fixture.skills.split(path.sep).join('/');
-  return `Fixture observation interface (applies to parent and every child; ${file ? `saved at ${file}: each child prompt tells the child to Read that file first instead of copying this text` : 'include this interface in child prompts'}): Bash may execute only separate literal pwd, ls, cat, stat, sha256sum, Git read commands (status, diff, show, log, ls-files, ls-tree, check-ignore, rev-parse, merge-base, hash-object without -w, branch --show-current, describe with only --tags, --always, --abbrev=<n> or --exact-match and at most one revision), the exact generated Preamble block with its spawned prefix, literal installed gstack-skill-start/gstack-skill-end commands for document-release (start requires GSTACK_SESSION_KIND=spawned) or their own --help, or the literal installed ${skills}/bin/gstack-docs-candidate snapshot (its --out a private .json under ${fixture.home}), compare <that .json> and --help commands. ${readOnlyInterfaceText(fixture.home)} Git reads, the Preamble block, lifecycle and candidate commands and scripts never join such a line: run each as its own Bash call, never joined to another command with ;, &&, || or a pipe, not even to another Git read. Otherwise no shell composition, custom interpreters, arbitrary scripts, inline eval or memory-mapped writes. The only additional scripts are ${scripts.length ? scripts.join(', ') : 'none'}.${insert ? ` To insert one saved private Markdown artifact into another (a saved section file into a report), Bash may also run the single literal command cat SOURCE.md >> TARGET.md with absolute paths under ${fixture.home}.` : ''} Read/Glob/Grep remain available; Read skill and section files with Read (offset/limit for ranges), because Bash output over 30KB becomes a truncated preview. Use Write/Edit for permitted docs and private JSON/Markdown artifacts under ${fixture.home}; do not rewrite installed skills, config, actor state or scripts. No effects outside the owned fixture. The owner preserves evidence and cleans up. Missing observer coverage blocks acceptance; the Linux kernel monitor covers syscall writes in the product tree, not hostile processes or arbitrary external destinations.
+  return `Fixture observation interface (applies to parent and every child; ${file ? `saved at ${file}: each child prompt tells the child to Read that file first instead of copying this text` : 'include this interface in child prompts'}): Bash may execute only separate literal pwd, ls, cat, stat, sha256sum, Git read commands (status, diff, show, log, ls-files, ls-tree, check-ignore, rev-parse, merge-base, hash-object without -w, branch --show-current, describe with only --tags, --always, --abbrev=<n> or --exact-match and at most one revision), the exact generated Preamble block with its spawned prefix, literal installed gstack-skill-start/gstack-skill-end commands for document-release (start requires GSTACK_SESSION_KIND=spawned) or their own --help, or the literal installed ${skills}/bin/gstack-docs-candidate snapshot (its --out a private .json under ${fixture.home}), compare <that .json> and --help commands. ${readOnlyInterfaceText(fixture.home)} The Git reads above may join such a line too, but not in a line with cd. A for loop over literal words (a lowercase loop variable; words without quotes, globs or $) whose body uses only such reads counts as those reads, one pass per word, wherever it sits in the line. Every read stays off actor-state.json and off ${docsConfigDir(fixture.home)} except its settings.json: that directory holds Claude's credentials and every agent's session transcript, so judge a child only by the output it returns (its echoed SESSION_KIND line included) and by the repository. The Preamble block, lifecycle and candidate commands and scripts never join such a line: run each as its own Bash call, never joined to another command with ;, &&, || or a pipe. Otherwise no shell composition, custom interpreters, arbitrary scripts, inline eval or memory-mapped writes. The only additional scripts are ${scripts.length ? scripts.join(', ') : 'none'}.${insert ? ` To insert one saved private Markdown artifact into another (a saved section file into a report), Bash may also run the single literal command cat SOURCE.md >> TARGET.md with absolute paths under ${fixture.home}.` : ''} Read/Glob/Grep remain available; Read skill and section files with Read (offset/limit for ranges), because Bash output over 30KB becomes a truncated preview. Use Write/Edit for permitted docs and private JSON/Markdown artifacts under ${fixture.home}; do not rewrite installed skills, config, actor state or scripts. No effects outside the owned fixture. The owner preserves evidence and cleans up. Missing observer coverage blocks acceptance; the Linux kernel monitor covers syscall writes in the product tree, not hostile processes or arbitrary external destinations.
 
 The working directory for parent and child Bash calls is already ${fixture.repo}. Run Git reads directly, for example: git status, git diff --cached, git merge-base main HEAD, git rev-parse HEAD. Do not use Git global options such as -C, -c, --git-dir or --work-tree, and do not prepend cd or another shell wrapper. The literal git subcommand must immediately follow git; an absolute owned repository path does not make git -C an allowed command.
 
@@ -419,8 +494,10 @@ export function docsCompletedRead(result: SkillTestResult, file: string, fixture
     const read = call.tool === 'Read' && resolve(call.input?.file_path ?? '') === target;
     const command = String(call.input?.command ?? '').trim();
     const literal = /^cat\s+/.test(command) && !/[\n\r;&|<>`$\\(){}]/.test(command);
-    const grammar = !literal && !/(?:^|[;&|]\s*)cd\s/.test(command) && readOnlyCommandAllowed(command, docsReadOnlyScope(fixture));
-    const catArgs = !literal && !grammar ? [] : command.split(/\s*(?:;|&&|\|\|)\s*/).filter(part => /^cat\s/.test(part) && !part.includes('|'))
+    const expanded = docsUnrollLoops(command);
+    const grammar = !literal && expanded !== null && !/(?:^|[;&|]\s*)cd\s/.test(command)
+      && (readOnlyCommandAllowed(command, docsReadOnlyScope(fixture)) || docsComposedReadAllowed(command, fixture));
+    const catArgs = !literal && !grammar ? [] : (expanded ?? command).split(/\s*(?:;|&&|\|\|)\s*/).filter(part => /^cat\s/.test(part) && !part.includes('|'))
       .flatMap(part => part.match(/'[^']*'|"[^"]*"|[^\s'"]+/g)?.slice(1).map(arg => /^['"]/.test(arg) ? arg.slice(1, -1) : arg) ?? []);
     const cat = call.tool === 'Bash' && catArgs.some(arg => resolve(arg) === target);
     if ((read || cat) && !/^(?:<tool_use_error>|Error(?: reading file|:)|Exit code [1-9]\d*\b)/i.test(call.output.trimStart()) &&

test/helpers/read-only-commands.ts

@@ -7,7 +7,8 @@
  * happen keep their narrow lists.
  *
  * Accepted: one line of simple commands from READ_TOOLS joined by ;, && or ||,
- * where a | pipe may feed only a STDIN_TOOLS filter, plus cd into a directory
+ * where a | pipe may feed only a STDIN_TOOLS filter (tr only there, with literal
+ * sets), plus cd into a directory
  * inside the root. Every path operand, path-valued option and unquoted glob
  * match must resolve physically (symlinks and .. applied) inside the fixture
  * root and outside its denied paths.
@@ -95,11 +96,12 @@ export const READ_TOOLS: Readonly<Record<string, ToolSpec>> = {
   echo: { flag: /^-[neE]+$/, literal: true },
   printf: { flag: /^--$/, literal: true },
   readlink: { flag: /^-[efmnqsvz]+$/ },
+  tr: { flag: /^-[cCdst]+$/, maxOperands: 2 },
   realpath: { flag: /^-[eLmPqsz]+$/ },
 };
 
 /** Tools that may receive a pipe. Each one only prints what it reads. */
-export const STDIN_TOOLS: ReadonlySet<string> = new Set(['wc', 'head', 'tail', 'cat', 'grep', 'rg', 'sort', 'uniq', 'cut', 'nl', 'sha256sum', 'sha1sum', 'sha512sum', 'md5sum', 'sed']);
+export const STDIN_TOOLS: ReadonlySet<string> = new Set(['wc', 'head', 'tail', 'cat', 'grep', 'rg', 'sort', 'uniq', 'cut', 'nl', 'sha256sum', 'sha1sum', 'sha512sum', 'md5sum', 'sed', 'tr']);
 
 const FIND_FLAGS = new Set(['-print', '-print0', '-prune', '-empty', '-true', '-false', '-a', '-o', '-and', '-or', '-not',
   '-readable', '-writable', '-executable', '-depth', '-nowarn', '-xdev', '-mount', '-quit', '-ls', '(', ')', '!', ',']);
@@ -110,7 +112,7 @@ const FIND_PATHS = new Set(['-newer', '-anewer', '-cnewer', '-samefile']);
 
 /** Interface text an opted-in fixture declares to its actor. */
 export function readOnlyInterfaceText(root: string): string {
-  return `Shared read-only grammar: Bash also accepts pure local reads whose every path, unquoted glob matches included, resolves inside ${root} with no .., symlink or absolute-path escape: ${Object.keys(READ_TOOLS).join(', ')} (find without -exec, -ok, -delete or -fprint*; sed only as -n with a line-range print script such as sed -n 1,200p; no output-file, symlink-following or external-program options; echo and printf with literal arguments only, no printf -v). Join only these reads with ;, && or ||, pipe only into ${[...STDIN_TOOLS].join(', ')}, and cd only into a directory inside that root. Redirects other than 2>/dev/null or 2>&1 right after a read's arguments, tee, substitutions, variables, tilde or brace expansion, background jobs, multi-line commands and every other tool stay outside this grammar.`;
+  return `Shared read-only grammar: Bash also accepts pure local reads whose every path, unquoted glob matches included, resolves inside ${root} with no .., symlink or absolute-path escape: ${Object.keys(READ_TOOLS).join(', ')} (find without -exec, -ok, -delete or -fprint*; sed only as -n with a line-range print script such as sed -n 1,200p; no output-file, symlink-following or external-program options; echo and printf with literal arguments only, no printf -v; tr only after a pipe, with -c, -C, -d, -s or -t and one or two literal sets that hold no $, backtick, brace or unquoted glob). Join only these reads with ;, && or ||, pipe only into ${[...STDIN_TOOLS].join(', ')}, and cd only into a directory inside that root. Redirects other than 2>/dev/null or 2>&1 right after a read's arguments, tee, substitutions, variables, tilde or brace expansion, background jobs, multi-line commands and every other tool stay outside this grammar.`;
 }
 
 export function readOnlyCommandAllowed(command: string, scope: ReadOnlyScope): boolean {
@@ -236,6 +238,7 @@ function commandRejection(words: Word[], piped: boolean, cwds: string[], context
   if (!spec) return `unlisted tool: ${name.text}`;
   if (piped && !STDIN_TOOLS.has(name.text)) return `${name.text} cannot read a pipe`;
   if (name.text === 'find') return findRejection(args, cwds, context);
+  if (name.text === 'tr') return trRejection(args, piped);
   if (name.text === 'sed') {
     const start = args.findIndex(arg => !/^(?:-n|--quiet|--silent)$/.test(arg.text));
     const [script, ...files] = start < 0 ? [] : args.slice(start);
@@ -286,6 +289,19 @@ function commandRejection(words: Word[], piped: boolean, cwds: string[], context
   return pathsRejection([...operands.filter(operand => operand.text !== '-'), ...paths], cwds, context, recursive);
 }
 
+function trRejection(args: Word[], piped: boolean): string | undefined {
+  if (!piped) return 'tr reads only a pipe';
+  let start = 0;
+  while (start < args.length && args[start].text.startsWith('-') && args[start].text.length > 1) {
+    if (args[start].text === '--') { start++; break; }
+    if (!READ_TOOLS.tr.flag.test(args[start].text)) return `unsupported tr option: ${args[start].text}`;
+    start++;
+  }
+  const sets = args.slice(start);
+  if (!sets.length || sets.length > READ_TOOLS.tr.maxOperands!) return 'tr takes one or two literal sets';
+  if (sets.some(set => set.glob || /[$`{}]/.test(set.text))) return 'tr sets must be literal';
+}
+
 function findRejection(args: Word[], cwds: string[], context: Context): string | undefined {
   let i = args[0]?.text === '-P' ? 1 : 0;
   const paths: Word[] = [];

test/read-only-command-grammar.test.ts

@@ -72,6 +72,7 @@ const ACCEPTED = [
   'cd qa-only; wc -l SKILL.md', 'ls docs;', 'echo ----', 'echo -n done', "printf '%s\\n' done", 'printf -- -x',
   'cat docs/guide.md; echo ----; cat qa-only/SKILL.md', 'echo done | wc -c', 'sed -n 1,2p docs/guide.md', 'grep -n step qa-only/SKILL.md | sed -n 1,5p',
   'ls docs 2>/dev/null', 'ls missing 2>/dev/null || ls docs', 'cat docs/guide.md 2>&1 | head -1', 'ls missing 2>&1 | wc -l',
+  "ls qa | tr '\\n' ' '", "cat docs/guide.md | tr -d '\\r'", "cat docs/guide.md | tr '[:upper:]' '[:lower:]' | sort", 'ls | tr -cs a-z x',
 ];
 
 describe.skipIf(process.platform === 'win32')('accepted pure local reads', () => {
@@ -171,7 +172,18 @@ const REJECTED: Array<[string, string, RegExp]> = [
   ['sed', "sed -n '1p;w docs/out.txt' docs/guide.md", /sed takes only -n and a line-range print script/],
   ['path escape', 'sed -n 1p escape/secret.txt', /outside root/],
   ['unlisted tool', 'awk 1 docs/guide.md', /unlisted tool: awk/],
-  ['unlisted tool', 'tr a-z A-Z', /unlisted tool: tr/],
+  ['tr', 'tr a-z A-Z', /tr reads only a pipe/],
+  ['tr', 'tr a-z A-Z docs/guide.md', /tr reads only a pipe/],
+  ['tr', 'cat docs/guide.md | tr a-z A-Z docs/guide.md', /tr takes one or two literal sets/],
+  ['tr', 'cat docs/guide.md | tr a-z A-Z > docs/out.md', /redirect/],
+  ['tr', 'cat docs/guide.md | tr a-z A-Z | sh', /unlisted tool: sh/],
+  ['tr', "cat docs/guide.md | tr '$X' y", /tr sets must be literal/],
+  ['tr', 'cat docs/guide.md | tr "$X" y', /substitution or variable/],
+  ['tr', "cat docs/guide.md | tr '" + '\x60' + "id" + '\x60' + "' y", /tr sets must be literal/],
+  ['tr', 'cat docs/guide.md | tr [a] b', /tr sets must be literal/],
+  ['tr', "cat docs/guide.md | tr '{a,b}' c", /tr sets must be literal/],
+  ['tr', 'cat docs/guide.md | tr -x a b', /unsupported tr option: -x/],
+  ['tr', 'cat docs/guide.md | tr', /tr takes one or two literal sets/],
   ['echo/printf', 'echo hi > docs/new.md', /redirect/],
   ['echo/printf', 'echo hi >> docs/guide.md', /redirect/],
   ['echo/printf', 'echo $(touch x)', /substitution or variable/],
@@ -299,15 +311,17 @@ describe.skipIf(process.platform === 'win32')('free replays of the captured slip
     expect(docsNativeInterface(fixture)).toContain(readOnlyInterfaceText(fixture.home));
   });
 
-  // PR #3288 E2E run 39186278010 (Fable 5.1): the grammar's join invited joined Git reads, which the docsync
-  // interface keeps separate; the interface now says so, and these reads of the Claude config dir pass.
-  test('docsync keeps Git reads out of grammar lines and lists the Claude config dir (39186278010)', () => {
-    expect(docsNativeInterface(fixture)).toContain('not even to another Git read');
+  // PR #3288 E2E run 39186278010 (Fable 5.1) joined Git reads into grammar lines; #3288 told the actor not to, but
+  // Opus kept joining them (run 39347827595), so joined declared Git reads are now accepted. These reads of the
+  // Claude config dir pass, and the run's NUL-to-newline tr filter is a pipe-only read (GSTA-57); an unlisted sink is not.
+  test('docsync accepts joined Git reads and lists the Claude config dir (39186278010)', () => {
+    expect(docsNativeInterface(fixture)).toContain('The Git reads above may join such a line too');
     for (const command of ['cat {home}/candidate.json; echo; ls -la {home}/state {home}/cc {home}/.claude/skills/gstack/document-release',
-      'ls {home}/.claude/skills/gstack/ship {home}/state {home}/cc; wc -c {home}/.claude/skills/gstack/ship/sections/documentation.md'])
-      expect(docsCommandAllowed(command.replaceAll('{home}', fixture.home), fixture), command).toBe(true);
-    for (const command of ['git status; git branch --show-current; git rev-parse HEAD', 'ls -la {home}/state; git status',
+      'ls {home}/.claude/skills/gstack/ship {home}/state {home}/cc; wc -c {home}/.claude/skills/gstack/ship/sections/documentation.md',
+      'git status; git branch --show-current; git rev-parse HEAD', 'ls -la {home}/state; git status',
       'git ls-files -z --cached --others --exclude-standard | tr \'\\0\' \'\\n\''])
+      expect(docsCommandAllowed(command.replaceAll('{home}', fixture.home), fixture), command).toBe(true);
+    for (const command of ['git ls-files -z --cached --others --exclude-standard | tr \'\\0\' \'\\n\' | sh', 'tr a b'])
       expect(docsCommandAllowed(command.replaceAll('{home}', fixture.home), fixture), command).toBe(false);
   });
 
@@ -315,9 +329,9 @@ describe.skipIf(process.platform === 'win32')('free replays of the captured slip
   // grep paged through sed -n, and the phase file read by a composed cat, which the completed-read check must credit.
   test('docsync accepts the focused Fable slips and credits a composed cat as a completed read', () => {
     const skill = path.join(fixture.home, '.claude/skills/gstack/document-release/SKILL.md');
-    for (const command of ['git rev-parse HEAD; ', 'grep -n "Ship-owned\\|^## \\|read-only" ' + skill + ' | sed -n 1,200p'])
+    for (const command of ['git rev-parse HEAD; ', 'git rev-parse HEAD; git status', 'grep -n "Ship-owned\\|^## \\|read-only" ' + skill + ' | sed -n 1,200p'])
       expect(docsCommandAllowed(command, fixture), command).toBe(true);
-    for (const command of ['git rev-parse HEAD; git status', 'git commit -m x;', 'sed -n 1w ' + path.join(fixture.repo, 'out.txt') + ' ' + skill])
+    for (const command of ['git rev-parse HEAD; git reset', 'git commit -m x;', 'sed -n 1w ' + path.join(fixture.repo, 'out.txt') + ' ' + skill])
       expect(docsCommandAllowed(command, fixture), command).toBe(false);
     const phase = path.join(fixture.home, 'phase.md');
     fs.writeFileSync(phase, '# Phase\nstep one\n');
@@ -333,7 +347,7 @@ describe.skipIf(process.platform === 'win32')('free replays of the captured slip
 
   test('docsync keeps its git interface and denies credentials and actor state', () => {
     for (const command of [
-      'git status; ls', 'cd repo && git fetch', 'git log | head -5',
+      'git status; rm app.ts', 'cd repo && git fetch', 'git log | sh',
       'wc -l ' + path.join(fixture.home, 'cc/.claude.json'),
       'grep -rn apiKey ' + fixture.home,
       'head ' + path.join(fixture.home, 'actor-state.json'),
@@ -394,11 +408,19 @@ describe.skipIf(process.platform === 'win32')('qa-only deadline fixture opt-in',
     ['path escape', 'wc -l {dir}/../outside.txt'],
     ['unlisted tool', 'awk 1 {dir}/qa-only/SKILL.md'],
     ['sed write', 'sed -i s/a/b/ {dir}/qa-only/SKILL.md'],
+    ['tr as a first command', 'tr a-z A-Z'],
+    ['tr into a shell', 'cat {dir}/qa-only/SKILL.md | tr a-z A-Z | sh'],
   ])('a %s variant stays outside the fixture interface', (_, command) => {
     const run = attempt(command);
     try { expect(run.check).toThrow('QA deadline: '); } finally { run.cleanup(); }
   });
 
+  // GSTA-57: qa-only shares the grammar, so it gets the same pipe-only tr filter docsync does.
+  test('a pipe into tr is a grammar read for qa-only too', () => {
+    const run = attempt("ls {dir}/qa-only | tr '\\n' ' '; cat {dir}/qa-only/SKILL.md | tr -d '\\r'");
+    try { expect(run.check()).toMatchObject({ launchedRuns: 1 }); } finally { run.cleanup(); }
+  });
+
   // Second focused Opus run: cat of the installed exploratory section, whose prose names QA_DEADLINE receipts.
   test('a grammar read of skill prose that mentions QA_DEADLINE is not a receipt', () => {
     const prose = fs.readFileSync(path.join(path.resolve(import.meta.dir, '..'), 'qa-only/sections/exploratory.md'), 'utf8');