From 5f853dcec0e2062c2a6f9f36c6d500eca4e34120 Mon Sep 17 00:00:00 2001 From: JB Date: Fri, 4 Sep 2026 16:11:58 -0400 Subject: [PATCH] docs: start Bash worktree cwd workflow --- docs/workflow/bash-worktree-cwd-record.md | 80 +++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/workflow/bash-worktree-cwd-record.md diff --git a/docs/workflow/bash-worktree-cwd-record.md b/docs/workflow/bash-worktree-cwd-record.md new file mode 100644 index 0000000..26427c2 --- /dev/null +++ b/docs/workflow/bash-worktree-cwd-record.md @@ -0,0 +1,80 @@ +# Bash worktree cwd workflow record + +## Status + +- Status: waiting +- Current phase: 2. Discover and decide requirements +- Next safe action: obtain approval for the Pi dependency upgrade scope and implementation plan before changing dependencies. + +## Request and scope + +- Request: address the first repository TODO so Bash execution honors the current Pi tool context inside hidden Git worktrees. +- In scope: reproduce the Pi 0.84.4 behavior, adopt the upstream Pi 0.85.0 cwd correction through the repository dependency set, test workspace-root and nested-package execution in a disposable hidden worktree, update affected documentation, and remove the resolved TODO. +- Out of scope: adding a custom Bash override, changing Bash's public per-call arguments, publishing packages, deploying, pushing, or modifying live/production data. + +## Git identity + +- Source branch: `main` +- Base commit: `7e7cfdb5cb0e1a1218b9a2c8250267d5099637fc` +- Feature branch: `feature/honor-bash-worktree-cwd` +- Worktree: `/srv/data/code/jb-pi/harness-tools/.worktrees/honor-bash-worktree-cwd` +- Omitted source changes: none; source checkout was clean and equal to `origin/main` after `git fetch origin main`. + +## Acceptance criteria + +- [ ] The repository resolves a Pi Coding Agent version whose built-in Bash tool uses the execution `ctx.cwd` instead of the tool factory's original process directory. +- [ ] A regression test executes `pwd` from both a disposable hidden worktree root and a nested workspace package directory and observes the requested directory. +- [ ] A missing requested working directory fails before the shell command can create a sentinel side effect. +- [ ] Existing repository typecheck and test suites pass. +- [ ] The resolved TODO and temporary workaround language are removed or updated without changing unrelated historical evidence. + +## Approved implementation plan and gates + +- Plan/specification source: user request, `docs/todos.md`, and upstream Pi 0.84.4/0.85.0 source under `/srv/data/opensrc/repos/github.com/earendil-works/pi/`. +- Exact plan: pending approval. Proposed: (1) add a focused repository regression harness for dynamic Bash `ctx.cwd` with hidden-worktree root, nested package, and missing-directory cases; (2) update the aligned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` catalog versions to 0.85.0 and regenerate `bun.lock`; (3) run focused tests, typecheck, and the full suite; (4) update README compatibility text and resolve the TODO/workaround references; (5) verify in a fresh Pi 0.85.0 process without changing the currently running global Pi installation. +- Plan approval: pending. +- UI classification and direction approval: non-UI; no prototype gate applies. +- Risk decisions and scope: dependency upgrade requires explicit approval. Global Pi installation changes are excluded unless separately authorized. + +## Ownership + +| Assignment | Owner identity | Deadline | Exclusive paths | Before/after Git evidence | Outcome | +| --- | --- | --- | --- | --- | --- | +| Workflow setup and research | parent Pi session `01a06e08-8d07-76a7-a116-d7e3baf55b87` | 15 minutes | workflow record only | Before: clean `main` at `7e7cfdb`; after: pending initial record commit | In progress | + +## Verification matrix + +| Surface | Command | Exit code | Outcome | +| --- | --- | --- | --- | +| Source/cache preflight | `git status --short --branch`; `opensrc path ...` | 0 | Clean source; Pi 0.84.4 and 0.85.0 source available locally. | +| Focused cwd regression | pending | pending | pending | +| Typecheck | `bun run typecheck` | pending | pending | +| Full tests | `bun run test` | pending | pending | +| Fresh-process integration | pending | pending | pending | + +## Review + +- Base and product HEAD: pending +- Clean status and tree hash: pending +- Commit list: pending +- Exact diff command: pending +- SHA-256: pending +- Mutator identities: parent Pi session `01a06e08-8d07-76a7-a116-d7e3baf55b87` +- Standards reviewer identity, digest confirmation, and verdict: pending +- Specification reviewer identity, digest confirmation, and verdict: pending +- Findings and remediation cycles: none yet +- Before/after reviewer Git evidence: pending + +## Integration and rollback + +- Synchronization and re-verification: fetch/rebase onto latest `origin/main`, then rerun affected and full verification if the effective tree changes. +- Fast-forward result: pending +- Product and closure commits: pending +- Reachability and cleanup: pending +- Rollback strategy: before integration, delete only the isolated feature branch/worktree after proof and approval if abandoned; after integration, revert the focused dependency/test/docs product commit. + +## Checkpoints and blockers + +- Last committed valid checkpoint: none yet +- Blockers: dependency-upgrade and exact-plan approval. +- Exact next safe action: commit this initial record, present it, and ask the user to approve or reject the proposed dependency scope and plan.