Skip to content

Commit 8417145

Browse files
eduralphclaude
andcommitted
docs(do): warn that the harness checkout isn't isolated under a live flow (#130)
Per-cycle worktree isolation (#94) keeps a cycle's Do/Check off the *target* repo, but the *harness* checkout — which holds results/issue_<id>/ state and the pdca_harness code a running flow imports — has no equivalent protection. Running ordinary git maintenance there during a live `pdca flow` silently corrupts in-flight state: `git stash -u` sweeps the untracked bundle into a stale snapshot, and a branch switch / `copier update` rewrites src/pdca_harness/*.py under subprocesses the flow spawns (a mixed-version cycle). Document the discipline in the worktree-isolation section of docs/04-do.md: do harness-repo maintenance in a separate git worktree of the harness repo, never branch-switch / copier update / git stash the live checkout while a flow runs — #94's own principle turned on the harness repo. Note the advisory flow-lock as a planned follow-up. Docs-only by design (the cheapest mitigation); the acceptance is "documented as unsupported with the worktree-based alternative spelled out." Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 2c6bd2f commit 8417145

1 file changed

Lines changed: 25 additions & 0 deletions

File tree

docs/04-do.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,31 @@ git checkout falls back to editing in place. (This isolation is what publish's
3535
stash/restore worked around before; with it, serial cycles get the same clean-tree
3636
guarantee lanes already had.)
3737

38+
### The harness checkout is not isolated — don't do git maintenance under a live flow (issue #130)
39+
40+
Worktree isolation protects the **target** repo. It does **not** protect the
41+
**harness checkout** — the repo that holds `results/issue_<id>/` bundle state *and*
42+
the `pdca_harness` code a running flow imports. While a `pdca flow` is live (e.g.
43+
parked at the interactive sign-off leaf), ordinary git maintenance in that checkout
44+
silently corrupts in-flight state:
45+
46+
- **`git stash -u` clobbers the bundle.** A flow's `results/issue_<id>/` is
47+
long-lived **untracked** working-tree files (it isn't committed as it goes); a
48+
stash sweeps them into a stale snapshot while the flow keeps advancing the
49+
on-disk bundle — a later `stash pop` overwrites newer Check artifacts with older
50+
Do ones.
51+
- **A branch switch or `copier update` rewrites `src/pdca_harness/*.py` under the
52+
running interpreter.** The live process pinned the old modules in memory, but any
53+
`python -m pdca_harness …` **subprocess** it spawns afterward picks up the new
54+
code — a mixed-version cycle.
55+
56+
The discipline is just #94's own principle turned on the harness repo: **do
57+
harness-repo maintenance (version bumps, `copier update`, bundle-recording commits)
58+
in a separate `git worktree` of the harness repo** — never branch-switch,
59+
`copier update`, or `git stash` the live checkout while a flow runs. (An advisory
60+
`pdca` flow-lock that refuses such maintenance while a flow is held is planned as a
61+
follow-up; until then this is operator discipline.)
62+
3863
## What Do produces
3964

4065
Three artifacts land in the bundle:

0 commit comments

Comments
 (0)