Plan: CLI Tool Validation Command

Planning Integrity Note

This file repairs the original plan artifact after implementation. The first saved plan did not satisfy the create-plan contract: it lacked Tn task ids, dependency graph, per-task RED/GREEN targets, assigned skill routing, and review gates. This repaired plan records the actual scope, dependency graph, validation gates, and execution evidence so future resume/review work has a truthful source of record.

This is not a claim that the create-plan stop condition was followed before implementation. It was not.

Initial Situation

The CLI already had a required-tool catalog and installer used by scaffold setup and update apply flows. Tool validation existed only as a side effect of those workflows, so an installed dp could not directly verify or repair the external toolchain.

Two adjacent issues made the operator experience worse:

• dp --version worked, but dp -v failed because @effect/cli exposes the built-in version flag as long-only.
• agent-browser had an unconditional ensure command, agent-browser install, so Harness asked it to install Chrome for Testing even when a usable system Chrome/Chromium/Brave executable was already present.

Problem

Operators need one direct command to check and repair the required Harness toolchain. That command must reuse the same registry and installer that scaffold/update already trust. The implementation also needs to stop forcing redundant browser downloads while preserving first-run browser bootstrap for users who do not have a supported browser installed.

Solution Shape

• Add root-only -v normalization so dp -v behaves like dp --version without changing subcommand flag semantics.
• Add a tools command group with an ensure subcommand.
• Implement tools ensure through a small testable helper that:
  • reads .devpunks/settings.json
  • falls back to requiredToolsForSkills([], bundledBaseline) outside scaffolded repos
  • calls ensureToolsInstalledBestEffort
  • prints human status and sets exit code on failed tools
• Add optional tool-catalog metadata that skips ensure commands when any configured executable candidate exists.
• Configure agent-browser to skip agent-browser install when AGENT_BROWSER_EXECUTABLE_PATH or common Chrome/Chromium/Brave executable candidates are found.
• Update operator docs, runbook mirror, spec index, implementation notes, and CHANGELOG.md.

Decision Ledger

Scope And Constraints

• apps/cli owns executable behavior, command registration, tool bootstrap, command tests, and release validation.
• docs owns human-facing runbooks and operational docs.
• apps/wiki/content/docs/project owns routed project spec/runbook artifacts.
• Reuse apps/cli/src/core/tools.ts, apps/cli/src/data/catalog/tools.ts, and apps/cli/src/content/tools.ts.
• Preserve scaffold/update behavior except for avoiding redundant browser installation.
• Do not hand-edit generated consumer .agents/skills/* or apps/cli/skills/* as part of this feature.
• Root scripts remain Turborepo delegators; no root workflow changes.

Codebase Findings

• apps/cli/src/index.ts registers root commands and already suppresses startup checks for -v, but passed raw process.argv to Command.run.
• apps/cli/scripts/assert-dist-commands.mjs guards built CLI command visibility and standalone executable packaging.
• apps/cli/src/core/tools.ts owns ToolCommandRuntime, command detection, package-manager detection, install behavior, version checks, best-effort status conversion, and recovery formatting.
• apps/cli/src/data/catalog/tools.ts models required tool package names, prerequisites, version contracts, and ensure commands.
• apps/cli/src/scaffold/output.ts writes required tool ids into .devpunks/settings.json.
• apps/cli/src/content/tools.ts defines the default required tool ids: agent-browser, opensrc, portless, and skills.
• apps/cli/src/ui/brand.ts renders the custom no-arg command guide, separate from @effect/cli --help.

Research Used

• parallel-research workers confirmed:
  • @effect/cli built-in version support is long-only, so -v needs root entrypoint normalization.
  • agent-browser install is the source of forced Chrome-for-Testing downloads.
  • agent-browser runtime can use existing system browsers, but its install command only skips its own cache.
  • Existing required-tool bootstrap is the correct reuse point.
• External package source inspection was limited to the research workers' upstream agent-browser findings; no new external API was introduced by implementation.

Scoped Skill Routing

Dependency Graph

T1 Root -v version alias
T2 CLI validate command
T3 Shared tool bootstrap browser skip
T4 Operator docs and changelog

T1 ─┐
T2 ─┤
T3 ─┼── T5 Spec/plan/implementation-note repair
T4 ─┘

T5 ── T6 Parent validation
T6 ── T7 Mandatory review
T7 ── T8 Docs-ingest/no-op gate
T8 ── T9 Delivery closeout

Parallel Execution Waves

Tasks

T1: Root -v Version Alias

• depends_on: []
• location: apps/cli/src/index.ts; apps/cli/scripts/assert-dist-commands.mjs; CHANGELOG.md; apps/cli/README.md; docs/README.md; docs/runbooks/dp-cli-scaffolding.md; apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md
• description: Add root-only -v behavior matching --version and document it.
• validation: Built CLI -v exits zero and includes package version; subcommands are not converted into root version output.
• status: Complete
• log: Added root-only argv normalization and built-dist assertion for -v.
• files edited/created: apps/cli/src/index.ts; apps/cli/scripts/assert-dist-commands.mjs; CHANGELOG.md; apps/cli/README.md; docs/README.md; docs/runbooks/dp-cli-scaffolding.md; apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md
• backlog_item_id: N/A
• backlog_item_url: N/A
• relation_mode: N/A
• assigned_skills: effect-authoring, effect-best-practices, tdd, simplify, turborepo
• tdd_status: recovered
• tdd_target: Root CLI -v prints the same package version as --version.
• red_command: repo-local runtime check from research: bun run apps/cli/src/index.ts -v
• expected_red_failure: Effect CLI rejects -v as an invalid argument while --version prints 2.2.0.
• green_command: bun run --cwd apps/cli build; node ./scripts/assert-dist-commands.mjs from apps/cli
• reason_not_testable:
• red_evidence: Planning-discovery worker reported --version printed 2.2.0 while -v exited 1 as invalid before implementation.
• green_evidence: Parent ran bun run --cwd apps/cli build and node ./scripts/assert-dist-commands.mjs; dist assertion passed and checks built -v output.
• codebase_design_notes: Root argv normalization is intentionally narrow: exactly one user arg, -v, becomes --version; no shared parser abstraction added.
• review_mode: cli

T2: CLI Tools Ensure Command

• depends_on: []
• location: apps/cli/src/index.ts; apps/cli/src/ui/brand.ts; apps/cli/src/cli/tools-command.ts; apps/cli/src/cli/tools-command.test.ts; apps/cli/scripts/assert-dist-commands.mjs
• description: Register tools ensure, implement the ensure helper/command, update the no-arg command guide, and assert the built CLI exposes the command.
• validation: Root help exposes tools; tools ensure --help is available; ensure helper reads scaffold manifest tool IDs or falls back to default toolchain; failed tool statuses set nonzero exit intent; repo-owned toolContracts are not executed.
• status: Complete
• log: Added toolsCommand, root command registration, command-guide text, tests, and built-dist root/subcommand help assertions.
• files edited/created: apps/cli/src/index.ts; apps/cli/src/ui/brand.ts; apps/cli/src/cli/tools-command.ts; apps/cli/src/cli/tools-command.test.ts; apps/cli/scripts/assert-dist-commands.mjs
• backlog_item_id: N/A
• backlog_item_url: N/A
• relation_mode: N/A
• assigned_skills: effect-authoring, effect-best-practices, tdd, simplify, turborepo
• tdd_status: recovered
• tdd_target: Public tools ensure runner uses .devpunks/settings.json in scaffolded repos and default required tools when absent.
• red_command: bun test ./src/cli/tools-command.test.ts from apps/cli
• expected_red_failure: Cannot find module './tools-command' before the command helper exists.
• green_command: bun run --cwd apps/cli test -- src/cli/tools-command.test.ts; node ./scripts/assert-dist-commands.mjs from apps/cli
• reason_not_testable:
• red_evidence: Worker reported bun test ./src/cli/tools-command.test.ts failed with Cannot find module './tools-command'.
• green_evidence: Parent reran bun run --cwd apps/cli test -- src/cli/tools-command.test.ts; 4 tests passed. Dist assertion passed after build.
• codebase_design_notes: runEnsureTools is the deep test seam. The Effect command is a thin adapter that resolves input, resolves a trusted stable/bundled baseline, calls the helper, renders status, and sets exit code.
• review_mode: cli

T3: Shared Tool Bootstrap Browser Skip

• depends_on: []
• location: apps/cli/src/core/tools.ts; apps/cli/src/core/tools.test.ts; apps/cli/src/data/catalog/tools.ts
• description: Extend tool catalog metadata and shared tool bootstrap so agent-browser install is skipped when a configured browser executable exists, while package installation remains unchanged.
• validation: Already-present agent-browser plus system Chrome makes no agent-browser install call; no browser still runs agent-browser install; missing package plus system Chrome installs package and skips browser bootstrap; already-present tools do not require Bun/pnpm/npm.
• status: Complete
• log: Added skipEnsureCommandsIfAnyCommandExists metadata and runtime/env candidate resolution in shared ensureToolsInstalled.
• files edited/created: apps/cli/src/core/tools.ts; apps/cli/src/core/tools.test.ts; apps/cli/src/data/catalog/tools.ts
• backlog_item_id: N/A
• backlog_item_url: N/A
• relation_mode: N/A
• assigned_skills: effect-authoring, effect-best-practices, tdd, simplify, turborepo
• tdd_status: required
• tdd_target: Shared ensureToolsInstalled skips only the agent-browser ensure command when a usable browser candidate exists.
• red_command: bun test apps/cli/src/core/tools.test.ts
• expected_red_failure: New tests expecting no ["agent-browser", ["install"]] call fail because the existing implementation always runs ensure commands.
• green_command: bun run --cwd apps/cli test -- src/core/tools.test.ts
• reason_not_testable:
• red_evidence: Worker reported failures showing unexpected ["agent-browser", ["install"]] calls before implementation.
• green_evidence: Parent reran package Vitest; src/core/tools.test.ts passed 12 tests.
• codebase_design_notes: ToolCommandRuntime.commandExists remains the seam. Browser detection is declarative catalog metadata plus runtime adapter, aligned to agent-browser runtime discovery names/paths.
• review_mode: cli

T4: Operator Docs And Release Notes

• depends_on: []
• location: apps/cli/README.md; docs/README.md; docs/runbooks/dp-cli-scaffolding.md; apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md; CHANGELOG.md
• description: Document dp -v, dp tools ensure, scaffolded/default tool resolution, mutating repair behavior, and the agent-browser browser-download skip.
• validation: Docs mention dp tools ensure in operator setup/recovery paths; no docs call it read-only; changelog entry for 2.2.0 includes user-facing changes.
• status: Complete
• log: Updated CLI README, docs README, root runbook, routed project runbook, and changelog.
• files edited/created: apps/cli/README.md; docs/README.md; docs/runbooks/dp-cli-scaffolding.md; apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md; CHANGELOG.md
• backlog_item_id: N/A
• backlog_item_url: N/A
• relation_mode: N/A
• assigned_skills: parallel-research, simplify, turborepo, docs-ingest-phase
• tdd_status: not_applicable
• tdd_target: Documentation-only task; validate by text coverage and diff checks.
• red_command:
• expected_red_failure:
• green_command: git diff --check
• reason_not_testable: Docs-only change with no runtime behavior.
• red_evidence:
• green_evidence: git diff --check passed; parent validation passed after docs integration.
• codebase_design_notes: not_applicable; no code interface changed.
• review_mode: cli

T5: Durable Spec, Plan, And Implementation Notes

• depends_on: [T1, T2, T3, T4]
• location: apps/wiki/content/docs/project/specs/cli/cli-tool-validation/SPEC.md; apps/wiki/content/docs/project/specs/cli/cli-tool-validation/PLAN.md; apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md; apps/wiki/content/docs/project/specs/cli/cli-specs.md; apps/wiki/content/docs/project/specs/cli/meta.json
• description: Keep routed project artifacts aligned with implemented behavior, evidence, and lifecycle state.
• validation: Spec/index status is implemented; plan contains T-task graph and validation gates; implementation notes contain acceptance status, sanity checks, manual review checklist, and remaining work.
• status: Complete
• log: Created spec folder, indexed it, then repaired this plan to match create-plan T-task schema after user flagged the bad original plan.
• files edited/created: apps/wiki/content/docs/project/specs/cli/cli-tool-validation/SPEC.md; apps/wiki/content/docs/project/specs/cli/cli-tool-validation/PLAN.md; apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md; apps/wiki/content/docs/project/specs/cli/cli-specs.md; apps/wiki/content/docs/project/specs/cli/meta.json
• backlog_item_id: N/A
• backlog_item_url: N/A
• relation_mode: N/A
• assigned_skills: parallel-research, simplify, turborepo, docs-ingest-phase
• tdd_status: not_applicable
• tdd_target: Documentation/bookkeeping artifact repair; validate by schema/content review and JSON parse.
• red_command:
• expected_red_failure:
• green_command: node -e "JSON.parse(require('fs').readFileSync('apps/wiki/content/docs/project/specs/cli/meta.json','utf8')); console.log('meta ok')"; git diff --check
• reason_not_testable: Routed project artifact update, not runtime behavior.
• red_evidence:
• green_evidence: meta ok; git diff --check passed.
• codebase_design_notes: not_applicable; no code interface changed.
• review_mode: cli

T6: Parent Validation

• depends_on: [T5]
• location: apps/cli; apps/wiki/content/docs/project/specs/cli/cli-tool-validation; docs
• description: Validate the integrated diff through focused tests, typecheck, build, dist assertion, lint/format, and artifact consistency checks.
• validation: All listed commands pass from a clean enough working tree, with unrelated pre-existing skill changes explicitly excluded from scope.
• status: Complete
• log: Ran focused test, package test, typecheck, build, dist assertion, CLI check, diff check, and JSON parse.
• files edited/created: none
• backlog_item_id: N/A
• backlog_item_url: N/A
• relation_mode: N/A
• assigned_skills: tdd, simplify, turborepo
• tdd_status: not_applicable
• tdd_target: Validation gate for integrated work.
• red_command:
• expected_red_failure:
• green_command: see validation gate list below.
• reason_not_testable: Validation-only closeout task.
• red_evidence:
• green_evidence: All parent validation commands listed in IMPLEMENTATION-NOTES.md passed.
• codebase_design_notes: not_applicable.
• review_mode: cli

T7: Mandatory Review

• depends_on: [T6]
• location: full scoped diff for CLI validate feature
• description: Run findings-first readonly review of the implemented diff, classify findings, and route back to implementation if blockers exist.
• validation: Review output records findings or explicit no-finding rationale with severity and next route. Exact review command: .agents/skills/autoreview/scripts/autoreview --mode local --prompt 'Delivery review scope: review the CLI tool-validation feature only: CHANGELOG.md, apps/cli/README.md, apps/cli/scripts/assert-dist-commands.mjs, apps/cli/src/index.ts, apps/cli/src/ui/brand.ts, apps/cli/src/cli/tools-command.ts, apps/cli/src/cli/tools-command.test.ts, apps/cli/src/core/tools.ts, apps/cli/src/core/tools.test.ts, apps/cli/src/data/catalog/tools.ts, docs/README.md, docs/runbooks/dp-cli-scaffolding.md, apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md, apps/wiki/content/docs/project/specs/cli/cli-tool-validation/**, apps/wiki/content/docs/project/specs/cli/cli-specs.md, apps/wiki/content/docs/project/specs/cli/meta.json. Unrelated create-plan skill and apps/cli/skills mirror changes are pre-existing/out-of-scope for this delivery; mention them only if they block review correctness. Findings-first. Check especially: validate command behavior, root-only -v semantics, agent-browser browser skip correctness, tests, docs, and lifecycle artifacts.'
• status: Complete
• log: Autoreview ran repeatedly until clean. Accepted findings were fixed: stale baseline contract handling, repo-owned contract execution risk, browser skip false positives, package-manager over-requirement, and validate-specific failure guidance.
• files edited/created:
• backlog_item_id: N/A
• backlog_item_url: N/A
• relation_mode: N/A
• assigned_skills: review-phase, simplify, turborepo
• tdd_status: not_applicable
• tdd_target: Review-only lifecycle gate.
• red_command:
• expected_red_failure:
• green_command: .agents/skills/autoreview/scripts/autoreview --mode local --prompt 'Delivery review scope: review the CLI tool-validation feature only: CHANGELOG.md, apps/cli/README.md, apps/cli/scripts/assert-dist-commands.mjs, apps/cli/src/index.ts, apps/cli/src/ui/brand.ts, apps/cli/src/cli/tools-command.ts, apps/cli/src/cli/tools-command.test.ts, apps/cli/src/core/tools.ts, apps/cli/src/core/tools.test.ts, apps/cli/src/data/catalog/tools.ts, docs/README.md, docs/runbooks/dp-cli-scaffolding.md, apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md, apps/wiki/content/docs/project/specs/cli/cli-tool-validation/**, apps/wiki/content/docs/project/specs/cli/cli-specs.md, apps/wiki/content/docs/project/specs/cli/meta.json. Unrelated create-plan skill and apps/cli/skills mirror changes are pre-existing/out-of-scope for this delivery; mention them only if they block review correctness. Findings-first. Check especially: validate command behavior, root-only -v semantics, agent-browser browser skip correctness, tests, docs, and lifecycle artifacts.'
• reason_not_testable: Review gate, not a behavior-changing task.
• red_evidence:
• green_evidence: Final autoreview exited 0 with autoreview clean: no accepted/actionable findings reported.
• codebase_design_notes: Review must check interface locality: runEnsureTools helper seam, catalog metadata shape, and shared bootstrap behavior.
• review_mode: cli

T8: Docs-Ingest Or No-Op Gate

• depends_on: [T7]
• location: apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md; apps/wiki/content/docs/project/specs/cli/cli-tool-validation/*; apps/wiki/content/docs/project/specs/cli/cli-specs.md; apps/wiki/content/docs/project/specs/cli/meta.json
• description: Route docs-affecting changes through delivery-phase docs-ingest gate, or record an explicit no-op when this spec/runbook update is already the routed project documentation artifact and no additional concept/flow ingestion is required.
• validation: apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md records either the docs-ingest phase result or the exact no-op rationale that the routed runbook/spec artifacts are already the intended documentation target.
• status: Complete
• log: Docs-ingest classified as no-op because this delivery already updated the intended routed docs/runbook/spec artifacts and no additional concept/flow page is needed.
• files edited/created:
• backlog_item_id: N/A
• backlog_item_url: N/A
• relation_mode: N/A
• assigned_skills: docs-ingest-phase, parallel-research, simplify
• tdd_status: not_applicable
• tdd_target: Docs-ingest lifecycle gate.
• red_command:
• expected_red_failure:
• green_command: edit apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md so Remaining Work and Sanity Checks include the docs-ingest result/no-op, then run rg -n "docs-ingest|no-op|Remaining Work" apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md
• reason_not_testable: Lifecycle/docs routing task, not runtime behavior.
• red_evidence:
• green_evidence: IMPLEMENTATION-NOTES.md records the docs-ingest no-op and names the routed documentation artifacts.
• codebase_design_notes: not_applicable.
• review_mode: cli

T9: Delivery Closeout

• depends_on: [T8]
• location: apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md; final response
• description: After review and docs-ingest/no-op are classified and any blockers resolved, record final route outcome, remaining work, and user-facing summary.
• validation: apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md has no stale pending validation/acceptance rows; final status states review outcome, docs-ingest outcome, and unrelated worktree quarantine. Run rg -n "pending|Remaining Work|review|docs-ingest|create-plan" apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md and git status --short.
• status: Complete
• log: Closeout artifacts updated with clean review result, docs-ingest no-op, final validation, and unrelated worktree quarantine.
• files edited/created:
• backlog_item_id: N/A
• backlog_item_url: N/A
• relation_mode: N/A
• assigned_skills: delivery-phase, simplify
• tdd_status: not_applicable
• tdd_target: Closeout bookkeeping.
• red_command:
• expected_red_failure:
• green_command: rg -n "pending|Remaining Work|review|docs-ingest|create-plan" apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md; git status --short
• reason_not_testable: Closeout/reporting task.
• red_evidence:
• green_evidence: IMPLEMENTATION-NOTES.md has final review/docs-ingest/remaining-work state; git status --short still shows unrelated quarantined create-plan skill/mirror changes.
• codebase_design_notes: not_applicable.
• review_mode: cli

Validation Gates

Already run:

• bun test apps/cli/src/core/tools.test.ts apps/cli/src/cli/tools-command.test.ts
• bun run --cwd apps/cli test -- src/core/tools.test.ts src/cli/tools-command.test.ts
• bun run --cwd apps/cli check-types
• bun run --cwd apps/cli build
• node ./scripts/assert-dist-commands.mjs from apps/cli
• bun run --cwd apps/cli check
• git diff --check
• node -e "JSON.parse(require('fs').readFileSync('apps/wiki/content/docs/project/specs/cli/meta.json','utf8')); console.log('meta ok')"
• .agents/skills/autoreview/scripts/autoreview --mode local --prompt '<scoped CLI validate feature prompt>'

Still required by delivery router:

• None for this scope.

Risks And Mitigations

Backlog Sync

No backlog sync performed. This was an ad hoc user request without a named Linear/GitHub issue, epic, or story. Creating backlog items only to mirror internal plan tasks would violate the backlog-sync rule.

Review And Docs-Ingest Expectations

• Mandatory review is still required by delivery-phase because implementation exists and no review artifact has been recorded.
• Docs-affecting changes exist. After review, route to docs-ingest or record a docs-ingest no-op if routed docs/runbooks/spec artifacts are already sufficient.
• Current dirty worktree includes unrelated create-plan skill/mirror changes. They are not part of this CLI validation plan and must be quarantined during review, closeout, staging, and any future commit.

Unresolved Questions

• None blocking implementation.
• Non-blocking future extension: whether to add dp tools ensure --check for read-only CI use.