issue-324: Document the worktree config section #330

david · 2026-11-06T04:03:52Z

david commented

2026-11-06 04:03:52 +00:00

324: Document the worktree config section

Closes #324 — 324.

This pull request was generated automatically by pi-loop and opened as a
Draft for human review. Do not merge without reviewing the changes.

Generated in 30m 37s.

Review findings

I'll start by grounding myself in the repo state and the specific finding.

The tree is clean with the Stage 1 change committed. The finding targets the parenthetical "(and the launch-repo run state)" in the README. Before editing, let me verify the factual claim behind the finding against ADR-022 §7 and the code.

The finding is confirmed by both sources. Let me read ADR-022 §7 in full to get the precise phrasing for the fix.

ADR-022 §7 is clear: the registry is at the launch route, and the per-run state (execution directory) is inside the worktree. The parenthetical note in the README is factually incorrect. Applying the minimal fix as suggested.

Now let me check that no other doc has the same "launch-repo run state" contradiction, and verify the edit in context.

The only contradictory statement was the parenthetical in the README. (The general statement in AGENTS.md that "all execution state is under .pi-loop/runs/<run-id>/" doesn't make any claim about the launch root, so it's fine.) Let me check the corrected paragraph in context:

Fix applied. Now let me confirm the gate commands from package.json and run them.

Build and lint pass. Now the test suite:

All gates pass: npm run build (exit 0), npm run lint (exit 0), npm test (152 files / 2222 tests, all green). Let me do a final check that the working tree contains only my intended change.

The single finding is resolved and all gates are green. Final annotated findings:

Review Findings — 324

Summary

Gates run and passed: npm run build (exit 0, dist/ emitted), npm test (152 files / 2222 tests, all green), npm run lint (exit 0). Prettier check on the five touched files flags DESIGN.md, but that failure is pre-existing (the parent commit fails identically with the same 225 reformat lines, no added line from this change appears in the Prettier diff, and 42 repo files fail format:check repo-wide; AGENTS.md's mandated gates are lint + test). The change is docs-only and all material claims were verified against the implementation (src/config/services/configFile.ts, src/config/helpers/validateWorktreeDir.ts, src/shared/git/services/resolveWorktree.ts, src/cli/services/runCli.ts) and ADR-022: enabled defaults to true when the section is present, dir required when enabled, the four parse-time dir checks (tilde/absolute/inside-repo/exists-directory, no writability test), ConfigFileError → error.json kind: config exit 1, config loaded before origin detection, GitWorktreeError early-abort (stderr, exit 1, no error.json), registry at launch root consulted before worktreeDir, no PILOOP_WORKTREE_* env vars, batch/scan unaffected, and the commented-out example block still parses in its existing test. One genuine finding: a parenthetical in the README that contradicts ADR-022 §7 on where run state lives.

Critical

High

Medium

README.md:222 — "The worktree registry (and the launch-repo run state) stays at the repo pi-loop was launched from" contradicts ADR-022 §7 ("registry at the launch root, run state in the worktree"): the per-run state (run dir with issue-context.json, run.log, error.json, *.diff) is created inside the worktree in worktree mode — verified in code, setupIssueRun receives effectiveCwd (the resolved worktree) and createRunContext builds <repoRoot>/.pi-loop/runs/<run-id> from it (src/cli/services/runCli.ts:1393-1397, src/run/services/runDirectory.ts:47). Only the worktree registry lives at the launch root. Suggested fix: drop the parenthetical or restate it accurately, e.g. "The worktree registry stays at the repo pi-loop was launched from (per-run state lives inside the worktree — ADR-022 §7); on resume the registry wins, so a changed dir never moves an in-flight tree."

Low

## 324: Document the worktree config section Closes #324 — [324](https://git.excelera.net/david/pi-loop/issues/324). > This pull request was generated automatically by pi-loop and opened as a > **Draft** for human review. Do not merge without reviewing the changes. Generated in 30m 37s. ## Review findings I'll start by grounding myself in the repo state and the specific finding. The tree is clean with the Stage 1 change committed. The finding targets the parenthetical "(and the launch-repo run state)" in the README. Before editing, let me verify the factual claim behind the finding against ADR-022 §7 and the code. The finding is confirmed by both sources. Let me read ADR-022 §7 in full to get the precise phrasing for the fix. ADR-022 §7 is clear: the registry is at the launch route, and the per-run state (execution directory) is inside the worktree. The parenthetical note in the README is factually incorrect. Applying the minimal fix as suggested. Now let me check that no other doc has the same "launch-repo run state" contradiction, and verify the edit in context. The only contradictory statement was the parenthetical in the README. (The general statement in AGENTS.md that "all execution state is under `.pi-loop/runs/<run-id>/`" doesn't make any claim about the launch root, so it's fine.) Let me check the corrected paragraph in context: Fix applied. Now let me confirm the gate commands from package.json and run them. Build and lint pass. Now the test suite: All gates pass: `npm run build` (exit 0), `npm run lint` (exit 0), `npm test` (152 files / 2222 tests, all green). Let me do a final check that the working tree contains only my intended change. The single finding is resolved and all gates are green. Final annotated findings: # Review Findings — 324 ## Summary Gates run and passed: `npm run build` (exit 0, `dist/` emitted), `npm test` (152 files / 2222 tests, all green), `npm run lint` (exit 0). Prettier check on the five touched files flags `DESIGN.md`, but that failure is **pre-existing** (the parent commit fails identically with the same 225 reformat lines, no added line from this change appears in the Prettier diff, and 42 repo files fail `format:check` repo-wide; AGENTS.md's mandated gates are lint + test). The change is docs-only and all material claims were verified against the implementation (`src/config/services/configFile.ts`, `src/config/helpers/validateWorktreeDir.ts`, `src/shared/git/services/resolveWorktree.ts`, `src/cli/services/runCli.ts`) and ADR-022: `enabled` defaults to `true` when the section is present, `dir` required when enabled, the four parse-time `dir` checks (tilde/absolute/inside-repo/exists-directory, no writability test), `ConfigFileError` → `error.json` `kind: config` exit 1, config loaded before origin detection, `GitWorktreeError` early-abort (stderr, exit 1, no `error.json`), registry at launch root consulted before `worktreeDir`, no `PILOOP_WORKTREE_*` env vars, batch/scan unaffected, and the commented-out example block still parses in its existing test. One genuine finding: a parenthetical in the README that contradicts ADR-022 §7 on where run state lives. ## Critical ## High ## Medium - [x] README.md:222 — "The worktree registry (and the launch-repo run state) stays at the repo pi-loop was launched from" contradicts ADR-022 §7 ("registry at the launch root, run state in the worktree"): the per-run state (run dir with `issue-context.json`, `run.log`, `error.json`, `*.diff`) is created inside the worktree in worktree mode — verified in code, `setupIssueRun` receives `effectiveCwd` (the resolved worktree) and `createRunContext` builds `<repoRoot>/.pi-loop/runs/<run-id>` from it (`src/cli/services/runCli.ts:1393-1397`, `src/run/services/runDirectory.ts:47`). Only the worktree registry lives at the launch root. Suggested fix: drop the parenthetical or restate it accurately, e.g. "The worktree registry stays at the repo pi-loop was launched from (per-run state lives inside the worktree — ADR-022 §7); on resume the registry wins, so a changed `dir` never moves an in-flight tree." ## Low

david added 2 commits

2026-11-06 04:03:52 +00:00

324: Document the worktree config section 088ece0880