Keep extracted CLI seams single-sourced

openspec/changes/agent-codex-split-cli-main-args-dispatch-2026-04-22-13-48/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-22

openspec/changes/agent-codex-split-cli-main-args-dispatch-2026-04-22-13-48/proposal.md

@@ -0,0 +1,16 @@
+## Why
+
+- `src/cli/main.js` still carries duplicate parser, git, and dispatch helpers even after the first modularization pass.
+- Those duplicate definitions already break the current branch with `SyntaxError: Identifier 'normalizeManagedForcePath' has already been declared`.
+- Keeping both copies also preserves behavior drift risk, especially around nested repo discovery and command parsing.
+
+## What Changes
+
+- Make `src/cli/main.js` import the extracted parser, git, and dispatch helpers instead of redefining them locally.
+- Keep command behavior stable by moving helper ownership to the existing extracted modules only.
+- Add focused regression coverage that fails if `src/cli/main.js` regains local copies of the extracted helpers.
+
+## Impact
+
+- Primary files: `src/cli/main.js`, `src/cli/args.js`, `src/cli/dispatch.js`, `src/git/index.js`, and `test/cli-args-dispatch.test.js`.
+- Main risk is accidental behavior drift while deleting local helpers, so verification stays focused on syntax plus representative CLI routes.

openspec/changes/agent-codex-split-cli-main-args-dispatch-2026-04-22-13-48/specs/cli-modularization/spec.md

@@ -0,0 +1,19 @@
+## MODIFIED Requirements
+
+### Requirement: Module seams mirror operational responsibility
+The CLI SHALL separate major operational seams into dedicated modules under `src/` instead of keeping duplicated helper ownership in `src/cli/main.js`.
+
+#### Scenario: Extracted helper ownership stays single-source
+- **WHEN** maintainers inspect `src/cli/main.js`
+- **THEN** parser helpers are imported from `src/cli/args.js`
+- **AND** git/worktree helpers are imported from `src/git/index.js`
+- **AND** command typo/deprecation helpers are imported from `src/cli/dispatch.js`
+- **AND** `src/cli/main.js` does not redefine those helpers locally.
+
+### Requirement: Refactor preserves targeted CLI behavior
+The modularization SHALL preserve the current command surface for targeted verified flows while deleting the local duplicate helpers.
+
+#### Scenario: Extracted helper seams remain wired through representative commands
+- **WHEN** the focused CLI regression suites are run after the helper cleanup
+- **THEN** representative command routes still execute through `src/cli/main.js`
+- **AND** syntax/require-time failures do not occur from duplicate helper definitions.

openspec/changes/agent-codex-split-cli-main-args-dispatch-2026-04-22-13-48/tasks.md

@@ -0,0 +1,38 @@
+## 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, add a `BLOCKED:` line under section 4 and stop.
+
+## Handoff
+
+- Handoff: change=`agent-codex-split-cli-main-args-dispatch-2026-04-22-13-48`; branch=`agent/codex/split-cli-main-args-dispatch-2026-04-22-13-48`; scope=`src/cli/main.js`, `src/cli/args.js`, `src/cli/dispatch.js`, `src/git/index.js`, `test/cli-args-dispatch.test.js`; action=`delete duplicate helper definitions from src/cli/main.js and keep extracted seams single-sourced`.
+
+## 1. Specification
+
+- [x] 1.1 Capture follow-up cleanup scope and acceptance criteria for the extracted CLI helper seams.
+- [x] 1.2 Add a spec delta for single-source helper ownership under `cli-modularization`.
+
+## 2. Implementation
+
+- [x] 2.1 Remove duplicate parser helper definitions from `src/cli/main.js` and use `src/cli/args.js`.
+- [x] 2.2 Remove duplicate git helper definitions from `src/cli/main.js` and use `src/git/index.js`.
+- [x] 2.3 Remove duplicate dispatch helper definitions from `src/cli/main.js` and use `src/cli/dispatch.js`.
+
+## 3. Verification
+
+- [x] 3.1 Add/update focused regression coverage for extracted args/dispatch delegation.
+- [x] 3.2 Run `node --check src/cli/main.js src/cli/args.js src/cli/dispatch.js src/git/index.js`.
+- [x] 3.3 Run focused CLI regression suites covering the extracted helper seams.
+- [x] 3.4 Run `openspec validate agent-codex-split-cli-main-args-dispatch-2026-04-22-13-48 --type change --strict`.
+- [x] 3.5 Run `openspec validate --specs`.
+
+Verification note: `node --test test/cli-args-dispatch.test.js`, `node --test test/metadata.test.js`, `node --test test/setup.test.js`, `node --test test/doctor.test.js`, and `npm test` all passed after removing the remaining local parser/dispatch copies from `src/cli/main.js`. `openspec validate --specs` exited `0` with `No items found to validate` in this repo.
+
+## 4. Cleanup
+
+- [ ] 4.1 Run `gx branch finish --branch agent/codex/split-cli-main-args-dispatch-2026-04-22-13-48 --base dev --via-pr --wait-for-merge --cleanup`.
+- [ ] 4.2 Record 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.

openspec/changes/setup-current-single-repo-alias/proposal.md

@@ -0,0 +1,17 @@
+## Why
+
+- `gx setup` recurses into nested repos by default, so a top-level workspace can rewrite child repos when the user only wanted to bootstrap the current repo.
+- `--no-recursive` already limits setup to the target repo, but users now expect the shorter `--current` alias after `gx doctor --current` shipped.
+- The user explicitly wants both `gx doctor --current` and `gx setup --current` to leave nested repos under the target path untouched.
+
+## What Changes
+
+- Accept `--current` as a setup alias for the existing single-repo traversal behavior.
+- Update recursive setup messaging to advertise `--current` alongside `--no-recursive`.
+- Add regression coverage proving `gx setup --current` leaves nested repos unmodified.
+
+## Impact
+
+- Affected surface: `src/cli/args.js`, `src/cli/main.js`, `test/setup.test.js`.
+- Expected outcome: `gx setup --current` scopes bootstrap/repair work to the target repo without mutating nested repos.
+- Risk: low, because the alias reuses the existing non-recursive traversal path.

openspec/changes/setup-current-single-repo-alias/specs/setup-workflow/spec.md

@@ -0,0 +1,10 @@
+## ADDED Requirements
+
+### Requirement: setup current alias limits installs to the target repo
+The system SHALL support `gx setup --current` as an alias for the existing single-repo setup path.
+
+#### Scenario: current alias skips nested repo setup
+- **GIVEN** a parent repo contains a nested standalone git repo
+- **WHEN** `gx setup --target <parent-repo> --current` runs
+- **THEN** the setup flow SHALL install and repair only `<parent-repo>`
+- **AND** the nested repo SHALL not be traversed or modified during that run.

openspec/changes/setup-current-single-repo-alias/tasks.md

@@ -0,0 +1,37 @@
+## 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, add a `BLOCKED:` line under section 4 and stop.
+
+## 1. Specification
+
+- [x] 1.1 Capture the `gx setup --current` alias scope and acceptance criteria.
+- [x] 1.2 Add normative OpenSpec coverage for the single-repo setup alias behavior.
+
+## 2. Implementation
+
+- [x] 2.1 Accept `--current` as a setup alias for the existing single-repo traversal path.
+- [x] 2.2 Update recursive setup messaging to mention `--current`.
+- [x] 2.3 Add a regression proving nested repos under the target path stay untouched.
+
+## 3. Verification
+
+- [x] 3.1 Run `node --check bin/multiagent-safety.js`.
+- [x] 3.2 Run `node --test test/setup.test.js`.
+- [x] 3.3 Run `node --test test/metadata.test.js`.
+- [x] 3.4 Run `openspec validate setup-current-single-repo-alias --type change --strict`.
+- [x] 3.5 Run `openspec validate --specs`.
+
+Verification note: `node --test test/doctor.test.js` also passed, keeping `gx doctor --current` green after moving repo-traversal parsing into `src/cli/args.js`. Direct dry-run CLI smoke proved both `doctor --current` and `setup --current` now parse, then continued into normal repo-drift/conflict handling instead of failing with `Unknown option: --current`.
+
+## 4. Cleanup
+
+- [ ] 4.1 Commit the change with a Lore commit message.
+- [ ] 4.2 Run `gx branch finish --branch agent/codex/split-cli-main-args-dispatch-2026-04-22-13-48 --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 4.3 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.4 Confirm the sandbox worktree and branch refs are gone after cleanup.
+
+Implementation note: the `--current` alias now routes through shared repo-traversal parsing in `src/cli/args.js`, so `gx setup --current` and `gx doctor --current` both stay on the single-repo path without mutating nested repos.