[codex] Implement official catalog discovery runtime

[shpoont]

Summary

Issue: #228
Risk tier: Tier 1
Branch: codex/228-official-catalog-discovery-runtime

This PR implements the #228 official-catalog discovery runtime from the current frozen execution package.

Frozen contract used

Source of truth:

• v2 catalogs: implement official catalog discovery baseline #228 issue contract
• v2 catalogs: implement official catalog discovery baseline #228 implementation-start gate comment from 2026-07-03
• docs/internal/project/v2-reset-execution-record.md
• PR Recontract #228 discovery around the official catalog #258 recontract/design evidence
• docs/internal/ux/v2-catalog-discovery-storyboard.md
• docs/internal/ux/mocks/v2-catalog-discovery/

Implemented scope:

• dotfiles-manager list
• dotfiles-manager search <query>
• dotfiles-manager explain <app>
• dotfiles-manager catalog list
• user-facing official catalog wording
• normal discovery excludes internal custom.files
• normal discovery no longer repeats read-only safety footers
• catalog list reports dotfiles-manager/official, version, and updated time

Explicit non-scope preserved:

• no catalog update
• no catalog add
• no additional remote catalog lifecycle
• no local catalog lifecycle
• no first-run catalog download/update
• no network fetching
• no live-settings writes
• no stored-settings writes
• no broad v2 CLI: normalize flattened normal-user command vocabulary #252 command cleanup

What changed

• Updated app discovery to map bundled recipe metadata to the normal-user official catalog surface.
• Filtered custom.files out of normal list and search discovery while leaving advanced recipe internals untouched.
• Simplified normal discovery text output to match the accepted runnable mock.
• Added a narrow internal/v2/catalogdiscovery package for deterministic official catalog listing.
• Wired dotfiles-manager catalog list into the CLI before the advanced recipe namespace.
• Updated package and CLI tests around the v2 catalogs: implement official catalog discovery baseline #228 frozen behavior.

Design evidence used

• Runnable mock check:

PYTHON="$HOME/.asdf/shims/python" docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check

Result:

OK: recontracted catalog discovery UX mock output matches expected-demo.txt

Real-result verification

Focused tests:

go test ./internal/v2/appdiscovery ./internal/v2/catalogdiscovery ./internal/app

Full test suite:

go test ./...

Static checks:

bash scripts/ci/run-static-checks.sh

Notes:

• Static checks were run with temporary one-off GOBIN linter binaries for staticcheck and golangci-lint; nothing was installed globally.

Coverage gate:

bash scripts/ci/run-tests.sh unit darwin true
bash scripts/ci/run-tests.sh integration darwin true
bash scripts/ci/run-tests.sh contract linux true
bash scripts/ci/coverage-aggregate.sh artifacts/coverage-unit.out artifacts/coverage-integration.out artifacts/coverage-contract.out artifacts/branch-metrics.json

Result:

Coverage gates passed.
- line: 90.1% (threshold: 90%)
- branch: 90.1% (threshold: 85%)
- logging-critical branch: 100.0% (threshold: 100%)

Temp-home CLI transcript verified:

$ dotfiles-manager list
Supported apps

  APP       CATALOG   STATE
  git       official  not managed
  nvim      official  not managed
  ssh       official  not managed
  starship  official  not managed
  tmux      official  not managed
  zsh       official  not managed

Use `dotfiles-manager explain <app>` to see what can be managed.

$ dotfiles-manager search git
Search results for "git"

  APP       CATALOG   STATE
  git       official  not managed

Use `dotfiles-manager explain git` to see what can be managed.

$ dotfiles-manager search wezterm
No supported apps found for "wezterm".

The current official catalog supports:
  git, nvim, ssh, starship, tmux, zsh

This version searches only the current official catalog.
Future versions may refresh official support data or add remote catalogs.
This version cannot do that yet.

$ dotfiles-manager explain git
Git is supported.

App ID: git
Catalog: official
State: not managed

Can manage:
  git:user.email  Git user email
  git:user.name   Git user name

Does not manage:
  credential.helper
  [credential] sections
  include/includeIf expansion

$ dotfiles-manager catalog list
Catalogs

Catalogs define app/tool support; they do not store your settings.

  dotfiles-manager/official  active for discovery
    Catalog version: 9f2c7a1
    Catalog updated: 2026-06-30 18:00 UTC

The temp working directory and temp HOME remained empty after the discovery commands.

Validation status

Implementation and local verification are complete for the frozen #228 runtime package.

Remaining gates after this PR:

• PR review
• CI verification
• validation record against v2 catalogs: implement official catalog discovery baseline #228 criteria
• Project Owner acceptance decision for v2 catalogs: implement official catalog discovery baseline #228
• project-record checkpoint if accepted

[shpoont]

Advisory review fixes and final local validation

Two advisory subagent reviews were run for PR #260:

• code / standards review;
• UX review of the v2 catalogs: implement official catalog discovery baseline #228 CLI surface.

Blockers found and fixed in amended commit ff9f190:

1. dotfiles-manager explain custom.files and the custom-files alias no longer expose the internal pseudo-app through normal discovery. They now return App not supported with a non-zero exit.
2. dotfiles-manager catalog add ... and dotfiles-manager catalog update no longer look successful via generic catalog help. They now fail non-zero as unsupported/unknown commands.
3. catalog list --verbose false affordance was removed; the flag is no longer advertised and now fails as an unknown flag.
4. search git table spacing now matches the accepted runnable mock transcript.

Regression coverage added:

• package-level Explain("custom.files") / alias rejection tests;
• CLI tests for explain custom.files, explain custom-files;
• CLI tests for unsupported catalog add, catalog update;
• CLI help/flag tests proving catalog list --verbose is absent/unsupported;
• exact search-table spacing assertion aligned with the mock.

Final local validation after fixes:

PYTHON="$HOME/.asdf/shims/python" docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check

Result:

OK: recontracted catalog discovery UX mock output matches expected-demo.txt

go test ./internal/v2/appdiscovery ./internal/v2/catalogdiscovery ./internal/app
go test ./...

Result: pass.

Static checks:

bash scripts/ci/run-static-checks.sh

Result: pass. As before, staticcheck and golangci-lint were provided through a temporary one-off GOBIN; no global install was performed.

Coverage gate:

bash scripts/ci/run-tests.sh unit darwin true
bash scripts/ci/run-tests.sh integration darwin true
bash scripts/ci/run-tests.sh contract linux true
bash scripts/ci/coverage-aggregate.sh artifacts/coverage-unit.out artifacts/coverage-integration.out artifacts/coverage-contract.out artifacts/branch-metrics.json

Result:

Coverage gates passed.
- line: 90.1% (threshold: 90%)
- branch: 90.1% (threshold: 85%)
- logging-critical branch: 100.0% (threshold: 100%)

Temp-home transcript after fixes confirmed:

• happy-path v2 catalogs: implement official catalog discovery baseline #228 commands match the accepted runtime shape;
• explain custom.files exits 2;
• explain custom-files exits 2;
• catalog add shpoont/custom-recipes exits 1;
• catalog update exits 1;
• catalog list --verbose exits 1;
• temp cwd and temp HOME remained empty after discovery commands.

The PR remains draft while GitHub CI reruns on the amended commit.

[shpoont]

Validation record for PR #260

Work item: #228 official-catalog discovery baseline
Frozen package: #228 implementation-start gate from 2026-07-03
PR: #260
Head: ff9f1901fcf1121a4cf310655a2c0f57c46d5ea0
Risk tier: Tier 1
Validator: executor + advisory subagents
Validation date: 2026-07-03

Real-result evidence reviewed:

• PR [codex] Implement official catalog discovery runtime #260 diff against current main.
• Runtime CLI behavior from an isolated temp HOME / temp cwd.
• Local targeted tests.
• Local full go test ./....
• Local static checks with temporary one-off linter binaries.
• Local unit/integration/contract coverage aggregation gate.
• GitHub CI on PR [codex] Implement official catalog discovery runtime #260.
• Advisory subagent code/standards review.
• Advisory subagent UX review and re-review after fixes.

Criteria checked:

• list, search, explain, and catalog list implement only the v2 catalogs: implement official catalog discovery baseline #228 official-catalog discovery baseline.
• Normal discovery uses official catalog wording and does not expose user-facing built-in wording.
• Normal list / search exclude custom.files and internal pseudo-app discovery.
• explain custom.files and explain custom-files do not expose the pseudo-app through normal discovery.
• Unsupported search output points to future official refresh / remote catalog support without promoting local catalog workarounds or unavailable commands.
• catalog list reports dotfiles-manager/official, catalog version, and updated time without source/cache/network/removable details.
• catalog add, catalog update, and catalog list --verbose do not look successful in v2 catalogs: implement official catalog discovery baseline #228.
• No live-settings writes, stored-settings writes, network fetching, first-run catalog download/update, local catalog lifecycle, remote catalog lifecycle, or broad v2 CLI: normalize flattened normal-user command vocabulary #252 cleanup were introduced.

Validation result:

Pass for the frozen #228 runtime implementation package.

Evidence summary:

GitHub CI for PR #260: all required checks passed.
- static-checks: success
- linux-unit: success
- linux-integration: success
- linux-contract: success
- linux-performance: success
- macos-integration: success
- coverage-aggregation: success
- final-required-check: success

Local coverage gate result:

Coverage gates passed.
- line: 90.1% (threshold: 90%)
- branch: 90.1% (threshold: 85%)
- logging-critical branch: 100.0% (threshold: 100%)

Advisory review result:

• Initial advisory reviews found blockers around custom.files, unsupported catalog lifecycle verbs, catalog list --verbose, and search table spacing.
• Those findings were fixed in amended commit ff9f190 and covered by regression tests.
• Re-review found no blockers and no new scope creep.

Known limitations / future work outside #228:

• v2 catalogs: implement official and remote catalog management with write gates #229 owns official-catalog update/download behavior and additional remote catalog lifecycle.
• v2 CLI: normalize flattened normal-user command vocabulary #252 owns broader command vocabulary cleanup.
• Future UX improvements such as multi-result search CTA and adaptive managed-app next actions were noted as future work, not v2 catalogs: implement official catalog discovery baseline #228 criteria failures.

Next owner-gated decision needed:

Project Owner acceptance decision for PR #260 / #228 validation result. This validation record does not by itself decide acceptance, merge, #228 completion, or project-level acceptance.

[shpoont]

Project Owner acceptance of validation

Project Owner decision recorded from chat on 2026-07-03: accepted the #228 validation result for PR #260 and approved moving the PR out of draft status.

Decision scope:

• Accepts the validation evidence recorded in v2 catalogs: implement official catalog discovery baseline #228 and PR [codex] Implement official catalog discovery runtime #260 for the frozen v2 catalogs: implement official catalog discovery baseline #228 runtime implementation package.
• Authorizes changing PR [codex] Implement official catalog discovery runtime #260 from draft to ready-for-review state.
• Does not by itself record final project-level acceptance for v2 reset: realign product plan around settings-folder sync #209 or authorize any v2 catalogs: implement official and remote catalog management with write gates #229/v2 CLI: normalize flattened normal-user command vocabulary #252 scope.

Next action:

• Mark PR [codex] Implement official catalog discovery runtime #260 ready.
• Await explicit merge action/approval before integrating into main.