Make Guardex install-surface verification maintainable

openspec/changes/agent-codex-install-suite-split-and-cli-surface-clea-2026-04-22-10-52/.openspec.yaml

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

openspec/changes/agent-codex-install-suite-split-and-cli-surface-clea-2026-04-22-10-52/proposal.md

@@ -0,0 +1,42 @@
+## Why
+
+- `test/install.test.js` has become a grab bag for setup, doctor, branch, finish,
+  sandbox, release, prompt, and migration coverage. Shared module-scope state and
+  repeated git/bootstrap shell steps make failures noisy and cross-test behavior
+  harder to trust.
+- The CLI entrypoint has several overlapping managed-file registries, duplicated
+  output formatters, and accreted commands/aliases that make setup/doctor/status
+  behavior harder to reason about and easier to drift.
+- The current self-update and doctor auto-finish behaviors also do more work than
+  users expect by default, which adds latency and surprise to otherwise simple
+  status/repair flows.
+
+## What Changes
+
+- Split the install integration coverage into shared helpers plus focused command
+  suites (`setup`, `doctor`, `branch`, `finish`, `sandbox`, `release`, and related
+  follow-on files as needed), while removing the module-scope Guardex-home leak and
+  consolidating fake-bin/bootstrap helpers.
+- Replace the scattered managed-file constants with one managed-file registry that
+  drives setup/doctor/scan/migrate/targeted-force decisions consistently.
+- Reduce the public CLI surface by routing user-facing behavior through canonical
+  commands/flags, hiding internal backdoors from help, and simplifying the
+  update/prompt/install-skills paths.
+- Add a single reporting/logging path for command output and per-invocation JSONL
+  traces under `.omx/logs/`.
+
+## Impact
+
+- Affected surfaces:
+  - `test/*.test.js`
+  - `bin/multiagent-safety.js`
+  - `scripts/agent-file-locks.py`
+  - `templates/scripts/agent-file-locks.py`
+- Risks:
+  - targeted test-file commands will change as suites move out of
+    `test/install.test.js`
+  - help/status/doctor output will change materially
+  - tightening auto-finish/update defaults can break expectations in existing tests
+- Rollout note:
+  - preserve behavior first with focused coverage before deleting aliases or moving
+    tests wholesale.

openspec/changes/agent-codex-install-suite-split-and-cli-surface-clea-2026-04-22-10-52/specs/cli-surface-cleanup/spec.md

@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: cli-surface-cleanup behavior
+The system SHALL enforce cli-surface-cleanup behavior as defined by this change.
+
+#### Scenario: Split command suites use isolated helper state
+- **WHEN** the integration suite exercises setup/doctor/branch/finish/sandbox/release
+  coverage
+- **THEN** those tests SHALL live in focused test files instead of one monolithic
+  `test/install.test.js`
+- **AND** shared helpers SHALL allocate Guardex-home state per test flow unless a
+  test explicitly opts into a shared path
+- **AND** helper wrappers SHALL make agent-env stripping explicit instead of silently
+  removing session variables from every spawned command.
+
+### Requirement: managed file rules derive from one registry
+Setup, doctor, scan, migrate, and targeted `--force` behavior SHALL derive managed
+file rules from one shared managed-file registry.
+
+#### Scenario: one record drives required, critical, and legacy decisions
+- **WHEN** the CLI evaluates a managed path
+- **THEN** required-file checks, critical auto-repair, executable-bit handling,
+  targeted-force eligibility, and legacy-file cleanup SHALL come from the same
+  managed-file definition for that relative path.
+
+### Requirement: public CLI help stays on canonical surfaces
+The public command/help output SHALL emphasize canonical user-facing commands and
+hide internal backdoors.
+
+#### Scenario: help output omits internal-only commands
+- **WHEN** the user runs `gx help`, `gx`, or command catalogs derived from the public
+  registry
+- **THEN** internal shell-dispatch commands SHALL be hidden
+- **AND** the user-facing setup surface SHALL expose skill installation through
+  `gx setup`
+- **AND** deprecated aliases SHALL not require duplicate public command entries.
+
+### Requirement: default status/update flows avoid surprise side effects
+The default status path SHALL favor explicit user action over automatic mutation.
+
+#### Scenario: update checks report manual next steps
+- **WHEN** a newer GitGuardex version is detected during the default invocation or
+  `gx version`
+- **THEN** the CLI SHALL print the manual install command needed to update
+- **AND** SHALL NOT auto-install or restart into a different binary during that
+  invocation.

openspec/changes/agent-codex-install-suite-split-and-cli-surface-clea-2026-04-22-10-52/tasks.md

@@ -0,0 +1,52 @@
+## 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-install-suite-split-and-cli-surface-clea-2026-04-22-10-52`; branch=`agent/codex/install-suite-split-and-cli-surface-clea-2026-04-22-10-52`; scope=`bin/multiagent-safety.js, test/*.test.js, scripts/agent-file-locks.py, templates/scripts/agent-file-locks.py`; action=`split the install suite, collapse the managed-file contract, then shrink/report the CLI surface before finish`.
+- Copy prompt: Continue `agent-codex-install-suite-split-and-cli-surface-clea-2026-04-22-10-52` on branch `agent/codex/install-suite-split-and-cli-surface-clea-2026-04-22-10-52`. Work inside the existing sandbox, review `openspec/changes/agent-codex-install-suite-split-and-cli-surface-clea-2026-04-22-10-52/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/codex/install-suite-split-and-cli-surface-clea-2026-04-22-10-52 --base main --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-install-suite-split-and-cli-surface-clea-2026-04-22-10-52`.
+- [x] 1.2 Define normative requirements in `specs/cli-surface-cleanup/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Extract shared install-suite helpers that isolate Guardex home state, keep
+  `runCmd` env handling explicit, and replace the duplicated fake-bin builders with
+  a generic `createFakeBin(...)`.
+- [x] 2.2 Split the monolithic install coverage into focused suites
+  (`test/setup.test.js`, `test/doctor.test.js`, `test/branch.test.js`,
+  `test/finish.test.js`, `test/sandbox.test.js`, `test/release.test.js`, plus
+  additional focused files as needed) and remove the duplicate self-update prompt
+  declaration / module-scope spawn gate.
+- [x] 2.3 Replace the scattered managed-file lists with a single managed-file
+  registry that derives required, critical, executable, legacy-removal, and
+  targeted-force behavior consistently.
+- [x] 2.4 Reduce the public CLI surface by:
+  - hiding internal-only commands from help
+  - folding skill installation into `setup`
+  - consolidating prompt/help variants
+  - simplifying the default self-update path
+  - making doctor auto-finish sweeps opt-in
+- [x] 2.5 Add one reporting/logging layer for operations/scan/auto-finish output and
+  JSONL invocation traces.
+
+## 3. Verification
+
+- [x] 3.1 Run focused command-suite verification (`node --test` on the new split test
+  files plus any remaining misc suite).
+- [x] 3.2 Run `openspec validate agent-codex-install-suite-split-and-cli-surface-clea-2026-04-22-10-52 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/install-suite-split-and-cli-surface-clea-2026-04-22-10-52 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 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).