ThothII/docs/superpowers/plans/2026-08-14-thothctl-discovery-and-pi-update.md

Simplified thothctl installation selection and Pi update Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Allow all existing thothctl commands to discover the installation descriptor automatically and make thothctl pi update use the checkout's pinned Pi version by default.

Architecture: Add a small config-level resolver that chooses one validated installation descriptor from an explicit flag, environment variable, or bounded upward search from the working directory. Keep the existing Pi lifecycle transaction intact; resolve only the requested version/source at the CLI boundary so the update engine retains its safety and recovery guarantees.

Tech Stack: Go 1.26, Docker Compose v2, existing tools/thothctl config and Pi lifecycle packages, Go tests.

Spec: docs/superpowers/specs/2026-08-14-thothctl-discovery-and-pi-update-design.md

Global Constraints

• Preserve every existing pi subcommand, alias, safety check, and explicit invocation form.
• --installation remains an explicit override and accepts only an absolute descriptor path named thothii-installation.yaml.
• Automatic discovery must not recursively scan .artifacts, home directories, or unrelated descendants.
• The default Pi version is the single ARG PI_VERSION=<version> in the selected project's docker/core.Dockerfile.
• The default Pi update uses the existing transactional build path and must not install an arbitrary network “latest”.
• All failures remain sanitized and must not reveal secret values.

File Map

• Create tools/thothctl/internal/config/discovery.go and discovery_test.go for bounded descriptor resolution and safe diagnostics.
• Modify tools/thothctl/cmd/thothctl/main.go and main_test.go for optional global selection, pi update defaults, help text, and dispatch.
• Create tools/thothctl/internal/pi/version.go and version_test.go for reading the project Pi pin.
• Modify tools/thothctl/internal/pi/update.go and update_test.go only if the default request needs a typed source/confirmation adjustment; keep lifecycle internals unchanged otherwise.
• Modify docs/contracts/tht-pi.md, docs/install/pi-management.md, and relevant command-contract verification scripts.

Task 1: Add bounded installation descriptor discovery

Files:

• Create: tools/thothctl/internal/config/discovery.go
• Test: tools/thothctl/internal/config/discovery_test.go

Interface: func Resolve(explicit string, environment func(string) string, workingDirectory string) (string, error).

• Write failing tests for explicit-path precedence, THOTHII_INSTALLATION, deploy/*/thothii-installation.yaml discovery, parent discovery, .artifacts exclusion, invalid candidates, ambiguity, and no-candidate errors.
• Run cd tools/thothctl && go test ./internal/config -run 'TestResolve' -count=1; confirm RED because Resolve is absent.
• Implement a bounded upward walk. At each level inspect only the exact descriptor and immediate deploy/*/thothii-installation.yaml entries; skip .artifacts; require regular files; validate candidates through config.Load; deduplicate canonical paths; fail clearly on zero or multiple valid candidates.
• Re-run the focused tests and confirm GREEN.
• Refactor only after green, keeping path collection separate from candidate validation.

Task 2: Make the global installation option optional

Files:

• Modify: tools/thothctl/cmd/thothctl/main.go

• Test: tools/thothctl/cmd/thothctl/main_test.go

• Add failing CLI tests proving thothctl pi status works from a project tree, the environment variable is used, an explicit flag wins, ambiguity fails before Docker, and all existing commands retain their dispatch.

• Run the focused CLI tests and confirm RED because the current parser requires --installation.

• Parse optional --installation, call config.Resolve with THOTHII_INSTALLATION and the process working directory, and update help to thothctl [--installation PATH] <command>.

• Run cd tools/thothctl && go test ./cmd/thothctl -count=1; confirm GREEN.

Task 3: Default pi update to the repository Pi pin

Files:

• Create: tools/thothctl/internal/pi/version.go
• Test: tools/thothctl/internal/pi/version_test.go
• Modify: tools/thothctl/cmd/thothctl/main.go
• Test: tools/thothctl/cmd/thothctl/main_test.go

Interface: func ReadPinnedVersion(projectDirectory string) (string, error).

• Add failing tests for one valid Dockerfile pin, missing Dockerfile, duplicate default pins, malformed versions, and pi update without --version; retain explicit version and advanced pull tests.
• Run cd tools/thothctl && go test ./internal/pi ./cmd/thothctl -run 'Test(ReadPinnedVersion|ParsePiUpdate|RunPiUpdate)' -count=1; confirm RED.
• Read only docker/core.Dockerfile, require one default ARG PI_VERSION=..., validate it with the existing version grammar, and make the short request select build mode while preserving the lifecycle transaction.
• Re-run focused tests and confirm GREEN.

Task 4: Update contracts without removing commands

Files:

• Modify: docs/contracts/tht-pi.md

• Modify: docs/install/pi-management.md

• Modify: the documentation verification script that asserts the old mandatory update invocation.

• Document automatic descriptor discovery, the explicit override, thothctl pi update as the normal path, --version as an explicit pin, and the advanced pull/digest form.

• Keep status, doctor, test/check, configure, restart, rollback, maintenance, and logs documented.

• Run the targeted documentation checks and git diff --check.

Task 5: Full verification

• Run cd tools/thothctl && go test ./... -count=1.
• Run cd tools/thothctl && go build ./cmd/thothctl.
• Run the relevant documentation contract script and inspect git status --short.
• Verify the help text contains the optional form and all existing commands; do not mutate the live Docker installation unless separately requested.