docs(worktrees): name scratch files per work item, since workers share one scratchpad

[devantler]

🤖 Generated by the Agentic Engineer

Why

Workers started from one session all write their scratch files into the same folder, so a worker that uses a common name silently overwrites a sibling's file. In one day, 13 such names were written by two to four workers each, and two of the run instructions still showed one fixed name for every worker as the example to copy.

What

The working-copy guide now says that the scratch folder is shared and that each worker names its scratch files with its own token, and points at the shared rule in the Engineer definition, which also tells each session to hand every worker its token. The two run-instruction examples now use a per-worker name too.

Fixes #4263

⚠️ Merge order: land devantler-tech/agent-plugins#580 first, or this guide points at a rule the installed definition does not carry yet.

[devantler]

🤖 Generated by the Agentic Engineer

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Reviewed commit: 9b281ef12431903d298a4ec4b66e8ac0403a9442

• CodeRabbit: the monorepo's included allowance is spent: its summary on monorepo#4271 at 2026-10-17T05:19Z reads "up to 1 included review per hour; 0 remain after this review". Recovery: the next hourly allowance, about 06:19Z.
• Codex: "You have reached your Codex usage limits for code reviews", posted on monorepo#4272 at 2026-10-17T05:35:27Z. The limit is the account's, not that PR's. Recovery: the maintainer adds credits.
• Cursor Bugbot: "Bugbot couldn't run - usage limit reached", posted on monorepo#4272 at 2026-10-17T05:36:50Z. Recovery: the maintainer raises the limit.

Scope: the whole PR diff at this head, one paragraph in the worktree guide. Reviewed for accuracy against the evidence on #4263, for conflict with the rest of the contract, and against this repository's Review guidelines.

• The facts match #4263: subagents of one session share that session's scratchpad, and the census found 13 names written by two to four transcript files in the 24 hours to 2026-10-16 21:08 UTC. The wording now states that window exactly instead of "on 2026-10-16".
• The paragraph adds the deployment fact (where the shared scratchpad comes from) and points at the portable rule in the Engineer definition rather than restating it as a second source, as the definition guide requires. The upstream rule is devantler-tech/agent-plugins#580, so the PR body names the merge order.
• Nothing in the always-on core changes, so the 32 KiB instruction budget is untouched. git-safety-contract.test.sh and the layout contract pass at this head.

Verdict: no P0/P1 findings

[devantler]

🤖 Generated by the Agentic Engineer

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Reviewed commit: 35dfebca30bfcc7901108a467e27fb03e59ae463

• CodeRabbit: the monorepo's included allowance is spent: its summary on monorepo#4271 at 2026-10-17T05:19Z reads "up to 1 included review per hour; 0 remain after this review". Recovery: the next hourly allowance, about 06:19Z.
• Codex: "You have reached your Codex usage limits for code reviews", posted on monorepo#4272 at 2026-10-17T05:35:27Z. The limit is the account's, not that PR's. Recovery: the maintainer adds credits.
• Cursor Bugbot: "Bugbot couldn't run - usage limit reached", posted on monorepo#4272 at 2026-10-17T05:36:50Z. Recovery: the maintainer raises the limit.

Scope: the whole PR diff at this head: one paragraph in the worktree guide and the tee-to-a-file examples in the run-loop and advance overlays. Reviewed for accuracy against the evidence on #4263, for conflict with the rest of the contract, and against this repository's Review guidelines.

• The facts match #4263: subagents of one session share that session's scratchpad, and the census found 13 names written by two to four transcript files in the 24 hours to 2026-10-16 21:08 UTC. The wording now states that window exactly instead of "on 2026-10-16".
• The paragraph adds the deployment fact (where the shared scratchpad comes from) and points at the portable rule in the Engineer definition rather than restating it as a second source, as the definition guide requires. The upstream rule is devantler-tech/agent-plugins#580, so the PR body names the merge order.
• Since the round at 9b281ef1: the paragraph follows the upstream rule as revised for CodeRabbit's finding on #580 (the dispatcher assigns each worker its own token), and the two overlay examples that showed a fixed /tmp/val.log and /tmp/out.log now show a per-worker scratch name, so the instructions no longer teach the collision the rule forbids.
• Nothing in the always-on core changes, so the 32 KiB instruction budget is untouched. git-safety-contract.test.sh, the layout contract and the self-review, review-provider-loop and provider-neutral-agents contracts (which read the two overlays) pass at this head. product-value-contract.test.sh cannot run in this worktree because the business-site submodule is not populated here; the overlay lines it would read are untouched.

Verdict: no P0/P1 findings

[devantler]

🤖 Generated by the Agentic Engineer (interactive Claude Code session)

Readiness at 35dfebca30bfcc7901108a467e27fb03e59ae463

1. Programmatically tested. Every check at this head has passed, including CI - Required Checks and the contract tests that read the changed overlays: Test product value contract, Test self-review contract, Test review-provider loop contract, and the instructions layout contract on both runners. The product value contract could not run in the authoring worktree; CI ran it here. There are no review threads, no non-thread findings, and GitHub reports the branch CLEAN.

2. Reviewed. The local review round at this head is clean (local-review-verdict.sh prints GREEN self@35dfebca30bfcc7901108a467e27fb03e59ae463). It was used because no lane would deliver at the time: the monorepo's hourly CodeRabbit allowance was spent, and Codex and Cursor Bugbot both reported account usage limits, as the round records.

3. Tried and evaluated as a user. This is guide and overlay text only, so there is nothing to run; the evaluation follows how it is read. The new paragraph points at the upstream Engineer rule instead of restating it as a second source. That rule merged as devantler-tech/agent-plugins#580, so the required merge order holds. The two overlay examples no longer show a fixed /tmp log name, so the run loop no longer teaches the collision the rule forbids. Read as a worker sent out by a parent session, which is the situation this paragraph is for, the instruction is clear and can be followed as written. This worker followed it with its own scratch prefix.

Promoting and merging at this head.