# Bash worktree cwd workflow record

## Status

- Status: waiting
- Current phase: 3. Design and obtain plan approval
- Next safe action: obtain approval for the corrected explicit-`cwd` tool contract before further product mutation.

## 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; add a repository-owned, publishable `@jbcode/pi-bash-cwd` extension with an optional `cwd` tool argument resolved from the live session context; delegate command execution to Pi's built-in Bash implementation; test workspace-root, nested-package, relative-path, and missing-directory execution in a disposable hidden worktree; update package inventory and documentation; remove the resolved TODO.
- Out of scope: upgrading Pi, installing or publishing the new package, 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

- [ ] `@jbcode/pi-bash-cwd` overrides the built-in `bash` tool with one backward-compatible optional `cwd` argument while preserving the existing command, timeout, output, truncation, cancellation, session-environment, and renderer contracts.
- [ ] Absolute and relative `cwd` values resolve from the live session `ctx.cwd`; omitted `cwd` retains the session directory.
- [ ] The requested directory is validated before delegating command execution.
- [ ] 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.
- [ ] Package inventory, README guidance, and the upstream Pi 0.85.0 packaging blocker TODO are synchronized.
- [ ] Existing repository typecheck and test suites pass.
- [ ] The resolved Bash cwd 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 corrected approval. Proposed: (1) keep `extensions/bash-cwd` as the approved publishable package; (2) replace the built-in Bash schema with its existing `command` and `timeout` fields plus optional `cwd`; (3) resolve relative `cwd` from `ctx.cwd`, validate that the result is a directory, and only then construct and invoke Pi's built-in Bash definition for that directory; (4) preserve built-in rendering, prompt metadata, output, timeout, cancellation, truncation, and session environment by spreading and delegating to the host definition; (5) revise the regression to pass explicit absolute and relative `cwd` arguments while the session context remains the primary fixture checkout, covering hidden-worktree root, nested package, omitted cwd, and fail-before-sentinel cases; (6) retain approved package inventory/docs/full-verification work and record that Pi 0.85.0's separate `ctx.cwd` correction does not add this per-call argument.
- Plan approval: pending because direct use of the live Bash tool proved the prior `ctx.cwd`-only plan did not satisfy the original explicit-`cwd` report.
- UI classification and direction approval: non-UI; no prototype gate applies.
- Risk decisions and scope: the Pi dependency upgrade remains abandoned. The corrected tool schema adds one optional, backward-compatible field and uses the repository's existing `typebox` dependency. The package remains repository-only and will not be installed, published, or added to the active global Pi environment in this task.

## 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: clean feature worktree at `5f853dc` | Complete |
| Initial dependency-plan implementation | parent Pi session `01a06e08-8d07-76a7-a116-d7e3baf55b87` | 15 minutes | `package.json`, `bun.lock`, focused test, workflow record | Before: clean feature worktree at `9d68d5f`; after: Pi 0.85.0 upgrade restored; focused red test retained unstaged | Paused and replanned after upstream packaging blocker |
| Local override implementation | parent Pi session `01a06e08-8d07-76a7-a116-d7e3baf55b87` | 15 minutes | `extensions/bash-cwd/**`, `scripts/bash-cwd.test.mjs` removal, `package.json`, `scripts/package-workspaces.test.mjs`, `README.md`, `docs/npm-packages.md`, `docs/todos.md`, `docs/workflow/skill-led-development-workflow-plan.md`, workflow record | Before: feature worktree at `f61f197` with inspected product changes | Paused for corrected contract approval |

## 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 reproduction | inline Node harness against Pi 0.84.4 | 0 (asserted buggy outcome) | Both hidden-worktree requests observed the primary checkout; a missing requested cwd still executed a sentinel command. |
| Focused cwd regression | pending repository test | 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: Pi 0.85.0 includes a separate upstream `ctx.cwd` correction but its public package imports undeclared `@earendil-works/pi-server`, causing `ERR_MODULE_NOT_FOUND`; the user selected a repository-owned override instead. During implementation, a direct live call with an extra `cwd` field still printed the primary checkout, proving Pi's schema/executor silently ignore the requested per-call directory and the first local design addressed the wrong seam. Current uncommitted package/test/docs changes were inspected; further mutation is paused for the corrected explicit-argument plan.
- 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: local-override approval commit `f61f197`
- Blockers: corrected explicit-`cwd` plan approval.
- Exact next safe action: present this corrected plan and ask the user to approve or reject the additive Bash tool argument.