fix(limps): finalize grouped CLI migration and completion UX

[paulbreuler]

Summary

• complete the breaking CLI refactor to canonical hierarchical command groups (server, plan, docs, config, health, graph, proposals, completion)
• move command implementations into grouped directories and extract shared command/completion helpers under src/core/
• fix post-refactor regressions in completion discoverability, init guidance, and exit semantics

Changes

• CLI routing and command architecture
• reorganize commands into grouped modules under packages/limps/src/commands/{server,plan,docs}/
• add grouped index help commands and remove flat root command entry points from command discovery
• keep command context/task-target resolution in packages/limps/src/core/command-context.ts and packages/limps/src/core/task-target.ts
• Completion behavior
• add completion core in packages/limps/src/core/completion.ts
• remove public/internal __complete command exposure from --help; switch scripts to env-based internal completion (LIMPS_COMPLETE=1)
• remove invalid completion suggestions (health drift, proposals list), add missing options (docs process --config), and honor typed --config tokens for plan/agent suggestions
• UX and correctness fixes
• update limps init next-step output to canonical limps server start --config ...
• remove accidental flat start --foreground bootstrap path in CLI entry
• make non-JSON validation failures return non-zero for plan score/plan scores
• Build and docs
• make build cleanup cross-platform in packages/limps/package.json (node -e fs.rmSync(...))
• align README command examples with canonical hierarchy (proposals [plan], remove health drift CLI example)
• Tests
• add completion regression coverage for invalid suggestions, --config token context, and completion script wiring
• add init-project output test for canonical startup command
• extend e2e error handling tests for non-zero exit behavior and hidden internal completion command

Tests

• npm run build (packages/limps)
• npm test -- tests/cli/completion.test.ts tests/cli/e2e.test.ts tests/cli/init-project.test.ts tests/cli/score-task-command.test.tsx (packages/limps)
• full suite via pre-push hook:
• packages/limps: 123 files / 1397 tests passed
• packages/limps-headless: 21 files / 317 tests passed

Code Review

• General review: ✅ Passed (manual senior review this session)
• MCP/LLM review: Not run (dedicated /mcp-code-review skill not available in this session)
• Commit review: ✅ Passed (conventional commit format; atomic commits)
• Fixed findings from review:
• stale/invalid completion suggestions and config-aware completion context
• canonical command migration inconsistencies (init output, foreground bootstrap alias)
• non-zero exit behavior for missing required args
• cross-platform build cleanup

Breaking Changes

• CLI command hierarchy is now canonical and grouped.
• flat root aliases are removed (for example, legacy flat commands should be replaced with grouped equivalents).
• migration path:
• use grouped commands (limps server start, limps plan list, limps docs search, etc.)
• regenerate shell completion scripts after upgrade (limps completion <shell>)
• no commit footer contained BREAKING CHANGE:; this section documents operational migration impact for this PR.

Notes / Risks

• shell completion behavior changed to env-driven internal mode (LIMPS_COMPLETE=1) and should be re-sourced in user shells after upgrade
• command/help discoverability now depends on grouped index commands; tests were added for these paths

Plan / Agent (if applicable)

• Plan: N/A
• Agent: N/A

[Copilot]

Pull request overview

Completes the migration of limps CLI to canonical grouped commands (e.g., limps server start, limps plan ..., limps docs ...), and adds an env-driven completion engine plus UX fixes around help text, init guidance, and exit semantics.

Changes:

• Reorganizes CLI commands into grouped modules and updates help/README/examples to match the new hierarchy.
• Introduces a new completion core (LIMPS_COMPLETE=1) and updates completion suggestions/behavior + adds regression tests.
• Improves UX correctness (canonical init next steps, updated daemon guidance strings, non-zero exit on missing required scoring flags).

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/limps/tests/cli/tags.test.ts	Updates tests to use limps docs tags ... group.
packages/limps/tests/cli/score-task-command.test.tsx	Adds UX coverage for limps plan score guidance + scoring output.
packages/limps/tests/cli/process.test.tsx	Updates imports for grouped docs process command module.
packages/limps/tests/cli/init-project.test.ts	Adds regression test for canonical daemon management instructions in init output.
packages/limps/tests/cli/e2e.test.ts	Updates e2e CLI invocations to grouped commands; asserts internal completion command hidden; checks non-zero exits.
packages/limps/tests/cli/completion.test.ts	Adds completion engine + completion script wiring tests.
packages/limps/tests/cli/commands.test.tsx	Updates Pastel command module imports to grouped plan commands.
packages/limps/src/utils/daemon-manager.ts	Updates daemon-start error guidance to limps server start.
packages/limps/src/server-http.ts	Updates daemon conflict guidance strings to limps server ....
packages/limps/src/server-http-entry.ts	Updates comment to reflect new spawn source command.
packages/limps/src/core/task-target.ts	Adds shared helper to resolve a task ID from --plan/--agent.
packages/limps/src/core/completion.ts	Adds completion suggestion engine + generated shell scripts.
packages/limps/src/core/command-context.ts	Adds shared config resolution/loading helper for commands.
packages/limps/src/commands/server/stop.tsx	Migrates to grouped server module layout and shared command context loader.
packages/limps/src/commands/server/status.tsx	Migrates imports + uses shared command context loader.
packages/limps/src/commands/server/start.tsx	Migrates imports + updates entry path and user-facing guidance strings.
packages/limps/src/commands/server/index.tsx	Adds grouped server index/help command.
packages/limps/src/commands/server/bridge.tsx	Migrates to grouped server module layout + updates guidance strings.
packages/limps/src/commands/plan/status.tsx	Migrates to grouped plan module layout + updates help usage/examples.
packages/limps/src/commands/plan/scores.tsx	Switches to --plan option, adds non-zero exit behavior on missing required flags.
packages/limps/src/commands/plan/score.tsx	Switches to --plan/--agent options; adds non-zero exit behavior on missing required flags.
packages/limps/src/commands/plan/repair.tsx	Migrates imports + updates user guidance to limps plan repair.
packages/limps/src/commands/plan/next.tsx	Migrates imports + updates help usage/examples to grouped form.
packages/limps/src/commands/plan/list.tsx	Migrates imports + uses shared command context loader.
packages/limps/src/commands/plan/index.tsx	Adds grouped plan index/help command.
packages/limps/src/commands/plan/create.tsx	Migrates imports + uses shared command context loader.
packages/limps/src/commands/plan/agents.tsx	Migrates imports + updates help usage/examples to grouped form.
packages/limps/src/commands/index.tsx	Updates root help to emphasize grouped commands and new completion command.
packages/limps/src/commands/docs/update.tsx	Migrates imports + updates help usage/examples to grouped form.
packages/limps/src/commands/docs/tags/remove.tsx	Migrates imports + updates help usage/examples to grouped form.
packages/limps/src/commands/docs/tags/list.tsx	Migrates imports + updates help usage/examples to grouped form.
packages/limps/src/commands/docs/tags/index.tsx	Updates nested tags help to limps docs tags ....
packages/limps/src/commands/docs/tags/add.tsx	Migrates imports + updates help usage/examples to grouped form.
packages/limps/src/commands/docs/search.tsx	Migrates imports + updates help usage/examples to grouped form.
packages/limps/src/commands/docs/reindex.tsx	Migrates imports + uses shared command context loader.
packages/limps/src/commands/docs/process.tsx	Migrates imports + updates help usage/examples to grouped form.
packages/limps/src/commands/docs/list.tsx	Migrates imports + uses shared command context loader.
packages/limps/src/commands/docs/index.tsx	Adds grouped docs index/help command.
packages/limps/src/commands/docs/delete.tsx	Migrates imports + updates help usage/examples to grouped form.
packages/limps/src/commands/docs/create.tsx	Migrates imports + updates help usage/examples to grouped form.
packages/limps/src/commands/completion.tsx	Adds user-facing limps completion <shell> command.
packages/limps/src/cli/next-task.ts	Updates warning guidance to limps plan repair ....
packages/limps/src/cli/init-project.ts	Updates init next steps and daemon management examples to grouped commands.
packages/limps/src/cli/config-cmd.ts	Updates generated instructions to limps server start.
packages/limps/src/cli.tsx	Adds env-driven completion request handling and updates foreground start bypass to grouped command.
packages/limps/package.json	Makes build cleanup cross-platform by removing dist before tsc.
README.md	Updates examples and docs to canonical grouped CLI hierarchy and removes invalid command examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.