Skip to content

Commit a55d7df

Browse files
committed
ci(docs): harden doc-e2e-runner env handling to prevent false findings
The runner's shell does not persist env vars between separate commands, so a one-time 'export XDG_DATA_HOME=...' did not reach a later inspection command — making the runner misread a tool's $HOME-fallback default as 'ignores XDG_DATA_HOME' (a false positive against the dashboard, which actually honors it since v0.3.0). Instruct the runner to persist env to a file and re-source it on every command, and to never log a default read from a shell without the env applied. No persona/journey changes.
1 parent 2c4ce77 commit a55d7df

1 file changed

Lines changed: 22 additions & 3 deletions

File tree

.claude/agents/doc-e2e-runner.md

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,28 @@ the docs read well" but "can a new user get this working from the docs alone".
1919

2020
## Environment
2121

22-
- Work in a fresh scratch directory: `WORK=$(mktemp -d)` and stay inside it.
23-
Point per-user state there too (e.g. `export XDG_DATA_HOME="$WORK/share"`) so
24-
you never touch the real machine's `~/.local/share/agent-receipts`.
22+
- Work in a fresh scratch directory and keep all per-user state there so you
23+
never touch the real machine's `~/.local/share/agent-receipts`. **Your shell
24+
does not persist environment variables, `cd`, or shell state between separate
25+
commands — a bare `export` in one step is gone by the next.** So set the scratch
26+
dir and its env *once*, write them to a file on disk (the filesystem persists
27+
even though the shell doesn't), and re-source that file at the start of **every**
28+
command:
29+
```
30+
WORK=$(mktemp -d)
31+
cat > /tmp/doc-e2e-env.sh <<EOF
32+
export WORK="$WORK"
33+
export XDG_DATA_HOME="$WORK/share"
34+
export PATH="\$(go env GOPATH)/bin:\$PATH"
35+
EOF
36+
```
37+
Then begin every later command with `. /tmp/doc-e2e-env.sh && …` so
38+
`XDG_DATA_HOME` / `PATH` are in force for **every** step — daemon, emit, CLI,
39+
dashboard, AND any `--help` / default-path inspection. Corollary: **never log a
40+
tool's default as a finding from a shell where the env wasn't applied.** A
41+
default that looks wrong (e.g. a `-db` / socket path pointing at `$HOME` instead
42+
of your scratch dir) is almost always a missing env var in *that* command, not a
43+
product bug — re-run it with the env sourced and confirm before recording it.
2544
- You run on whatever OS the runner gives you (Linux in CI). Follow the docs'
2645
instructions **for this OS**. If a step only documents another OS (e.g. only
2746
`brew`, with no source/Linux path), that is a finding — then use the closest

0 commit comments

Comments
 (0)