recodeee · NagyVikt · Apr 22, 2026 · Apr 22, 2026 · Apr 22, 2026
@@ -45,6 +45,10 @@ npm i -g @imdeadpool/guardex
   <strong>guard many agent. keep one repo clean.</strong>
 </p>
 
+[about_description.txt](./about_description.txt)
+
+Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.
+
 <p align="center">
   Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.
 </p>

@@ -0,0 +1,18 @@
+## Why
+
+- `src/cli/main.js` still carries the protected-main doctor sandbox lifecycle inline even after the earlier parser/dispatch and doctor-foundations passes.
+- That keeps sandbox bootstrapping, nested CLI execution, auto-commit, merge-back, lock sync, and output rendering coupled to the top-level CLI file.
+- The review surfaced the next highest-value slice clearly: move the doctor lifecycle into its own module and move the remaining generic git helpers out of `main.js`.
+
+## What Changes
+
+- Add `src/doctor/index.js` as the dedicated home for the protected-main `gx doctor` sandbox lifecycle.
+- Move the remaining shared branch/config helpers used by that lifecycle into `src/git/index.js`.
+- Keep the current CLI surface and doctor output stable while shrinking `src/cli/main.js`.
+- Add focused modularization coverage that fails if `main.js` regains local doctor lifecycle ownership.
+
+## Impact
+
+- Primary surface: `gx doctor` on protected branches, especially the sandbox auto-finish + merge-back path.
+- Secondary surface: any other CLI path that uses `currentBranchName`, `readGitConfig`, `aheadBehind`, `workingTreeIsDirty`, or `branchMergedIntoBase`.
+- Risk is moderate because the doctor flow is behaviorally sensitive, so verification stays focused on doctor and CLI modularization regressions.
@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: Protected-main doctor lifecycle lives under `src/doctor`
+The CLI SHALL keep the protected-main `gx doctor` sandbox lifecycle in a dedicated `src/doctor` module instead of defining that lifecycle inline in `src/cli/main.js`.
+
+#### Scenario: Main delegates protected-main doctor execution
+- **GIVEN** a maintainer inspects the refactored CLI entrypoint
+- **WHEN** they follow the protected-main `gx doctor` path
+- **THEN** `src/cli/main.js` delegates the sandbox lifecycle into `src/doctor`
+- **AND** the observable doctor output and exit behavior remain unchanged.
+
+### Requirement: Shared git helpers are single-sourced under `src/git`
+The CLI SHALL keep reusable branch/config helpers in `src/git` instead of redefining them in `src/cli/main.js`.
+
+#### Scenario: Doctor and finish reuse the same git helpers
+- **GIVEN** the doctor lifecycle and finish flows both need branch/config helpers
+- **WHEN** the CLI resolves current branch, git config, ahead/behind counts, or merge status
+- **THEN** those helpers come from `src/git`
+- **AND** `src/cli/main.js` does not reintroduce local copies of those helpers.
@@ -0,0 +1,40 @@
+## Definition of Done
+
+This change is complete only when all of the following are true:
+
+- Every checkbox below is checked.
+- The branch `agent/codex/extract-doctor-sandbox-module-2026-04-22-15-38` reaches `MERGED` state on `origin` and the PR URL + final merge state are recorded in the completion handoff.
+- If any step blocks, add a `BLOCKED:` line under section 4 and stop.
+
+## Handoff
+
+- Handoff: change=`agent-codex-extract-doctor-sandbox-module-2026-04-22-15-38`; branch=`agent/codex/extract-doctor-sandbox-module-2026-04-22-15-38`; scope=`src/cli/main.js`, `src/doctor/index.js`, `src/git/index.js`, `test/cli-args-dispatch.test.js`; action=`move the protected-main doctor lifecycle into src/doctor and the remaining shared git helpers into src/git without changing doctor behavior`.
+
+## 1. Specification
+
+- [x] 1.1 Lock the cleanup scope to doctor lifecycle extraction plus shared git-helper relocation only.
+- [x] 1.2 Add a `cli-modularization` delta that requires the protected-main doctor flow to live under `src/doctor`.
+
+## 2. Implementation
+
+- [x] 2.1 Add `src/doctor/index.js` and move the protected-main doctor sandbox lifecycle out of `src/cli/main.js`.
+- [x] 2.2 Move `readGitConfig`, `currentBranchName`, `workingTreeIsDirty`, `aheadBehind`, `branchExists`, and `branchMergedIntoBase` into `src/git/index.js`.
+- [x] 2.3 Keep `src/cli/main.js` as the command-level integrator only and update the modularization regression test to guard the new boundary.
+- [x] 2.4 Fix the protected-base stash cleanup path so successful merge-back cannot leak a leftover stash if sandbox cleanup fails later.
+
+## 3. Verification
+
+- [x] 3.1 Run `node --check src/cli/main.js src/doctor/index.js src/git/index.js`.
+- [x] 3.2 Run `node --test test/cli-args-dispatch.test.js test/doctor.test.js`.
+- [x] 3.3 Run `openspec validate agent-codex-extract-doctor-sandbox-module-2026-04-22-15-38 --type change --strict`.
+- [x] 3.4 Run `openspec validate --specs`.
+
+Verification note: `node --check src/cli/main.js src/doctor/index.js src/git/index.js` passed; `node --test test/cli-args-dispatch.test.js` passed (10/10); `node --test test/doctor.test.js` passed (17/17); `openspec validate agent-codex-extract-doctor-sandbox-module-2026-04-22-15-38 --type change --strict` returned valid; `openspec validate --specs` returned `No items found to validate`.
+
+## 4. Cleanup
+
+- [ ] 4.1 Run `gx branch finish --branch agent/codex/extract-doctor-sandbox-module-2026-04-22-15-38 --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is removed and no local/remote refs remain for the branch.
+
+BLOCKED: the worktree also contains an overlapping scaffold/DI extraction attempt (`src/scaffold/index.js` plus `openspec/changes/agent-codex-extract-git-scaffold-doctor-di-2026-04-22-15-38/`) that was not part of this narrow doctor-module pass. Do not run the cleanup/finish pipeline for this branch until that parallel scope is either integrated intentionally or moved off the branch.
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-22
@@ -0,0 +1,18 @@
+## Why
+
+- `src/cli/main.js` is still over 5,500 lines and retains the remaining git/worktree, scaffold/template, and protected-main doctor lifecycle clusters.
+- Those clusters keep the most sensitive behavior in the least reviewable file and force `src/sandbox`, `src/toolchain`, and `src/finish` to keep constructor-style dependency bags.
+- The requested outcome is a payoff-first extraction pass: move the remaining helper seams to owned modules, then delete the DI wrappers so the CLI reads as direct module wiring instead of a service locator.
+
+## What Changes
+
+- Move the remaining git/worktree helpers from `src/cli/main.js` into `src/git/index.js`.
+- Move the remaining managed-file, template, JSONC, and repo-settings helpers from `src/cli/main.js` into `src/scaffold/index.js`.
+- Extract the protected-main doctor sandbox lifecycle and related protected-base sandbox helpers into `src/doctor/index.js`.
+- Convert `src/sandbox/index.js`, `src/toolchain/index.js`, and `src/finish/index.js` to direct modules and remove `getSandboxApi()`, `getToolchainApi()`, and `getFinishApi()` from `src/cli/main.js`.
+
+## Impact
+
+- Primary surfaces: `src/cli/main.js`, `src/git/index.js`, `src/scaffold/index.js`, new `src/doctor/index.js`, `src/sandbox/index.js`, `src/toolchain/index.js`, `src/finish/index.js`, and focused CLI regression tests.
+- Main risk surface is `gx doctor` on protected branches plus `gx finish` auto-commit/sync behavior, so the pass must extend behavior-lock coverage first and rerun doctor/install/finish-adjacent suites after each extraction stage.
+- This is an internal cleanup only; command names, output wording, and zero-copy CLI behavior must stay stable.
@@ -0,0 +1,11 @@
+## MODIFIED Requirements
+
+### Requirement: Typed protected-main doctor sandbox lifecycle
+The system SHALL keep the protected-main `gx doctor` sandbox path behaviorally equivalent while moving the lifecycle sequencing out of `src/cli/main.js` and into a dedicated doctor module.
+
+#### Scenario: Protected-main doctor lifecycle is extracted without behavior drift
+- **GIVEN** `gx doctor` runs on a protected local base branch
+- **WHEN** the protected-main doctor flow creates a sandbox, runs nested doctor, auto-commits repairs, and finishes through the PR path
+- **THEN** `src/cli/main.js` delegates that lifecycle to `src/doctor/index.js`
+- **AND** the observable output and success/failure behavior remain unchanged
+- **AND** the existing protected-main doctor regression tests still pass.
@@ -0,0 +1,19 @@
+## MODIFIED Requirements
+
+### Requirement: Module seams mirror operational responsibility
+The CLI SHALL keep git/worktree, scaffold/template, and doctor lifecycle helper ownership in their extracted `src/` modules instead of redefining those seams in `src/cli/main.js`.
+
+#### Scenario: Git and scaffold helper seams stay single-source
+- **WHEN** maintainers inspect `src/cli/main.js`
+- **THEN** git/worktree helpers are imported from `src/git/index.js`
+- **AND** scaffold/template/settings helpers are imported from `src/scaffold/index.js`
+- **AND** `src/cli/main.js` does not redefine those helpers locally.
+
+### Requirement: CLI module wiring is direct after extraction
+The modularized CLI SHALL wire extracted modules through direct exports/imports instead of constructor-style dependency bags.
+
+#### Scenario: Factory wrappers are removed after seam extraction
+- **WHEN** maintainers inspect the runtime modules after this cleanup
+- **THEN** `src/cli/main.js` does not define `getSandboxApi()`, `getToolchainApi()`, or `getFinishApi()`
+- **AND** `src/sandbox/index.js`, `src/toolchain/index.js`, and `src/finish/index.js` export direct functions instead of `create*Api` factories
+- **AND** require-time/syntax regressions do not occur from the factory removal.
@@ -0,0 +1,46 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-codex-extract-git-scaffold-doctor-di-2026-04-22-15-38`; branch=`agent/codex/extract-doctor-sandbox-module-2026-04-22-15-38`; scope=`src/cli/main.js`, `src/git/index.js`, `src/scaffold/index.js`, `src/doctor/index.js`, `src/sandbox/index.js`, `src/toolchain/index.js`, `src/finish/index.js`, `test/cli-args-dispatch.test.js`; action=`extract the remaining git/scaffold/doctor helper seams and delete the DI factory wrappers without changing CLI behavior`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize the git/scaffold/doctor/DI extraction scope and acceptance criteria for `agent-codex-extract-git-scaffold-doctor-di-2026-04-22-15-38`.
+- [x] 1.2 Confirm no capability spec delta is required because this change is a behavior-preserving internal extraction and cleanup pass.
+
+## 2. Implementation
+
+- [x] 2.1 Extend focused regression coverage so the remaining helper clusters and DI wrapper functions are behavior-locked before cleanup.
+- [x] 2.2 Move the remaining git/worktree helpers from `src/cli/main.js` into `src/git/index.js` and update callers.
+- [x] 2.3 Move the remaining scaffold/template/JSONC/settings helpers from `src/cli/main.js` into `src/scaffold/index.js` and update callers.
+- [x] 2.4 Extract the protected-main doctor sandbox lifecycle and related sandbox helpers into `src/doctor/index.js` and route `src/cli/main.js` through it.
+- [x] 2.5 Convert `src/sandbox/index.js`, `src/toolchain/index.js`, and `src/finish/index.js` to direct modules and delete the cached factory wrappers from `src/cli/main.js`.
+
+## 3. Verification
+
+- [x] 3.1 Run `node --check src/cli/main.js src/git/index.js src/scaffold/index.js src/doctor/index.js src/sandbox/index.js src/finish/index.js src/toolchain/index.js`.
+- [x] 3.2 Run `node --test test/cli-args-dispatch.test.js`.
+- [x] 3.3 Run focused CLI regression suites covering setup, doctor, install, metadata, and finish-adjacent behavior.
+- [x] 3.4 Run `npm test`.
+- [x] 3.5 Run `openspec validate agent-codex-extract-git-scaffold-doctor-di-2026-04-22-15-38 --type change --strict`.
+- [x] 3.6 Run `openspec validate --specs`.
+
+Verified on 2026-04-22:
+- `node --check src/cli/main.js src/git/index.js src/scaffold/index.js src/doctor/index.js src/sandbox/index.js src/finish/index.js src/toolchain/index.js`
+- `node --test test/cli-args-dispatch.test.js test/doctor.test.js test/install.test.js test/metadata.test.js test/finish.test.js test/setup.test.js`
+- `npm test` -> `209` pass, `0` fail, `1` skip
+- `openspec validate agent-codex-extract-git-scaffold-doctor-di-2026-04-22-15-38 --type change --strict`
+- `openspec validate --specs` -> `No items found to validate.`
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run `gx branch finish --branch agent/codex/extract-doctor-sandbox-module-2026-04-22-15-38 --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).