Document the worktree config section #324

New issue

david · 2026-11-05T21:43:57Z

david commented

2026-11-05 21:43:57 +00:00

Summary

Update all user-facing documentation for the new worktree: section: AGENTS.md, README.md, DESIGN.md §7.1, piloop-config.example.yaml, and CHANGELOG.md.

Background

Earlier steps in this series implement ADR-022 (already in the repo at docs/adr/022-configurable-worktree-dir.md): the worktree: config section, parse-time dir validation, worktree routing for both repo kinds, and the widened early issue-fetch gate. The docs now have to describe the implemented behavior:

Schema: worktree: { enabled?: boolean, dir?: string } in piloop-config.yaml. enabled defaults to true when the section is present; dir is required when enabled is true (no hidden defaults). enabled: false → today's behavior, dir never validated.
dir rules (all checked at config-parse time, before any git/agent work, raised as ConfigFileError → error.json with kind: config, exit 1): absolute only; no tilde (dedicated message advising the full path); not equal to or inside the launch repo root (separator-aware test; a parent of the repo is allowed); exists and is a directory. Deliberately no writability test.
Behavior: with the section enabled, worktrees are created under dir for both bare repos and normal clones (linked worktree — the run's cwd has a .git file, not a directory). Absent or disabled → today's behavior (bare: worktree next to the repo; normal clone: run in place).
State location: the worktree registry and run artifacts stay at the launch repo root; the registry wins on resume (a changed dir never moves an in-flight tree).
YAML only — there are no PILOOP_WORKTREE_DIR / PILOOP_WORKTREE_ENABLED environment variables.
Behavior change to call out: for worktree-mode runs (bare, or normal clone with enabled: true), an issue-API error now aborts the run before any stage as a GitWorktreeError (stderr, exit 1, no error.json); today a normal clone reaches the issue-fetch stage, which has the bounded-retry policy.

Depends on: #320, #321, #322, #323 (the docs describe their combined behavior).

Implementation Details

Files: AGENTS.md, README.md, DESIGN.md, piloop-config.example.yaml, CHANGELOG.md.

AGENTS.md — add a worktree: bullet in the Configuration (env) section next to the docs: / research: bullets, covering the section, its default, the parse-time validation, and the normal-clone behavior change.
README.md — extend the piloop-config.yaml section with a worktree: example and the five-row decision table from ADR-022 §2.
DESIGN.md §7.1 — add worktree to the config-file schema listing.
piloop-config.example.yaml — add a commented-out worktree: block. A unit test (src/config/services/configFile.test.ts → piloop-config.example.yaml) parses this file, so it must stay valid: a live worktree: block without dir would fail the strict parser.
CHANGELOG.md — entry covering: the new worktree: section; worktree mode for normal clones when enabled; the behavior change (issue-API errors in worktree mode abort before any stage as GitWorktreeError, no error.json); YAML-only, no env vars.

Acceptance Criteria

AGENTS.md's Configuration section documents worktree.enabled (default true), worktree.dir (required when enabled is true), the parse-time validation, and the normal-clone behavior change.
README.md's config section shows a valid worktree: example and the decision table.
DESIGN.md §7.1's schema listing includes worktree.
piloop-config.example.yaml has a commented-out worktree: block and still parses in the existing example-file test.
CHANGELOG.md has an entry containing the four bullets above.
npm run lint and npm test are clean.

Test Plan

Run npm run lint and npm test — the existing piloop-config.example.yaml test in configFile.test.ts is the guard for the example file.

## Summary Update all user-facing documentation for the new `worktree:` section: `AGENTS.md`, `README.md`, `DESIGN.md` §7.1, `piloop-config.example.yaml`, and `CHANGELOG.md`. ## Background Earlier steps in this series implement ADR-022 (already in the repo at `docs/adr/022-configurable-worktree-dir.md`): the `worktree:` config section, parse-time `dir` validation, worktree routing for both repo kinds, and the widened early issue-fetch gate. The docs now have to describe the implemented behavior: - **Schema:** `worktree: { enabled?: boolean, dir?: string }` in `piloop-config.yaml`. `enabled` defaults to `true` when the section is present; `dir` is **required** when `enabled` is true (no hidden defaults). `enabled: false` → today's behavior, `dir` never validated. - **`dir` rules** (all checked at config-parse time, before any git/agent work, raised as `ConfigFileError` → `error.json` with `kind: config`, exit 1): absolute only; no tilde (dedicated message advising the full path); not equal to or inside the launch repo root (separator-aware test; a parent of the repo is allowed); exists and is a directory. Deliberately **no** writability test. - **Behavior:** with the section enabled, worktrees are created under `dir` for **both** bare repos and normal clones (linked worktree — the run's cwd has a `.git` **file**, not a directory). Absent or disabled → today's behavior (bare: worktree next to the repo; normal clone: run in place). - **State location:** the worktree registry and run artifacts stay at the **launch** repo root; the registry wins on resume (a changed `dir` never moves an in-flight tree). - **YAML only** — there are no `PILOOP_WORKTREE_DIR` / `PILOOP_WORKTREE_ENABLED` environment variables. - **Behavior change to call out:** for worktree-mode runs (bare, or normal clone with `enabled: true`), an issue-API error now aborts the run **before any stage** as a `GitWorktreeError` (stderr, exit 1, **no `error.json`**); today a normal clone reaches the issue-fetch stage, which has the bounded-retry policy. **Depends on:** #320, #321, #322, #323 (the docs describe their combined behavior). ## Implementation Details Files: `AGENTS.md`, `README.md`, `DESIGN.md`, `piloop-config.example.yaml`, `CHANGELOG.md`. - **`AGENTS.md`** — add a `worktree:` bullet in the **Configuration (env)** section next to the `docs:` / `research:` bullets, covering the section, its default, the parse-time validation, and the normal-clone behavior change. - **`README.md`** — extend the `piloop-config.yaml` section with a `worktree:` example and the five-row decision table from ADR-022 §2. - **`DESIGN.md` §7.1** — add `worktree` to the config-file schema listing. - **`piloop-config.example.yaml`** — add a **commented-out** `worktree:` block. A unit test (`src/config/services/configFile.test.ts` → `piloop-config.example.yaml`) parses this file, so it must stay valid: a *live* `worktree:` block without `dir` would fail the strict parser. - **`CHANGELOG.md`** — entry covering: the new `worktree:` section; worktree mode for normal clones when enabled; the behavior change (issue-API errors in worktree mode abort before any stage as `GitWorktreeError`, no `error.json`); YAML-only, no env vars. ## Acceptance Criteria - [ ] `AGENTS.md`'s Configuration section documents `worktree.enabled` (default `true`), `worktree.dir` (required when enabled is true), the parse-time validation, and the normal-clone behavior change. - [ ] `README.md`'s config section shows a valid `worktree:` example and the decision table. - [ ] `DESIGN.md` §7.1's schema listing includes `worktree`. - [ ] `piloop-config.example.yaml` has a commented-out `worktree:` block and still parses in the existing example-file test. - [ ] `CHANGELOG.md` has an entry containing the four bullets above. - [ ] `npm run lint` and `npm test` are clean. ## Test Plan Run `npm run lint` and `npm test` — the existing `piloop-config.example.yaml` test in `configFile.test.ts` is the guard for the example file.

david added this to the Configurable worktree directory milestone

2026-11-05 21:43:57 +00:00

david added the

documentation

ready

labels

2026-11-05 21:43:57 +00:00

david referenced this issue

2026-11-06 02:44:17 +00:00

issue-322: Route worktree creation into the configured parent directory #328

david referenced this issue from a pull request that will close it,

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