test: ["CMD", "curl", "-fsS", "http://localhost:3000/api/v1/version"] # internal — correct, unchanged
The GAP-003 deliverable is /workspace/helix: a helix Go CLI plus onboarding docs. Three discipline rules were applied:
1. Docs grounded in the live CLI surface, not spec text. GETTING-STARTED.md embeds the actual output captured by running each command, and every command was verified to work before being written:
$ bin/helix estimate --prompt "Summarize this PR: it fixes a port drift where docs said 3000 but live truth is 3030." --model gpt-4o
Model: gpt-4o
Prompt length: 85 chars
Estimated tokens: 22
Estimated cost: $0.0001 # real cost returned, exit 0
$ bin/helix prompt list
Registered prompts:
code-review Review a diff for correctness, security, and style
incident-brief Produce a post-incident brief from a timeline
$ bin/helix verify --checklist head
...
Caveat: verification runs against the repo at HEAD. If the
deployed service is behind HEAD, this report may not reflect
what is actually running in production. # HEAD caveat documented
The doctor section is a live run (hits Forgejo over HTTP), not a spec echo — internal/doctor/doctor.go:
const ForgejoHost = "http://localhost:3030" // live truth (host)
const ForgejoInternal = "http://forgejo:3000" // container-internal, do not change
2. Port-drift fix — 3000 → 3030 at 8 host-facing sites. The repo documented host port 3000; live truth is 3030. Fixed at: (1) README quickstart URL, (2) GETTING-STARTED setup step, (3) GETTING-STARTED port table, (4) bootstrap.sh default, (5) compose ports: "3030:3000", (6) doctor.go ForgejoHost, (7) scripts/verify-port-drift.sh, (8) integration/ports_test.go. Container-internal 3000 refs were preserved, not changed (correct inside the docker network):
# docker-compose.yml — ports mapping is the host-facing fix...
ports:
- "3030:3000" # HOST_PORT:CONTAINER_PORT
healthcheck:
test: ["CMD", "curl", "-fsS", "http://localhost:3000/api/v1/version"] # internal — correct, unchanged
A drift guard now enforces both sides (integration/ports_test.go + scripts/verify-port-drift.sh): ≥1 3030 ref at each of the 8 sites, ≥8 repo-wide, and localhost:3000 healthcheck + forgejo:3000 URL must survive.
3. Probe-residue discipline. Probed helix prompt register in a redirected dir (HELIX_PROMPT_DIR=probes/nested) to observe residue: nested dir + _index.yaml write. Reverted per convention (rm -rf probes), real prompts/_index.yaml untouched, working tree clean — the probe was never committed.
- **Live truth confirmed:** a real Forgejo is running in this environment — `curl http://localhost:3030/api/v1/version` → `{"version":"1.21.11+2"}` (HTTP 200). This is the very drift the task describes, and `helix doctor` passes against it: `[PASS] forgejo (host port 3030) (… -> HTTP 200)`.
- **Commands verified before documenting:** `helix --help`, `estimate --help`, `prompt --help` all exit 0; `estimate` returned a real token/cost; `prompt list` rendered the index; `verify` printed the HEAD caveat; `doctor` ran live (also gracefully reports `[FAIL] docker daemon` since no daemon exists in this sandbox — documented degradation, not a silent pass).
- **Guards:** `go test ./integration/` → `ok` (3 tests); `scripts/verify-port-drift.sh` → `OK: port convention holds` (40 host `3030` refs across the 8 sites; healthcheck `localhost:3000` and `FORGEJO_URL=forgejo:3000` verified intact). `gofmt -l` empty, `go vet` clean.
- **Edge cases tested:** `estimate` without `--prompt` → exit 1 + `helix: --prompt is required`; unknown model → exit 1; `register` on a directory → exit 1; `register` on non-`.md` → exit 1; `verify --checklist nope` → exit 1. (This sweep surfaced and fixed a silent-error bug — `SilenceErrors` swallowed messages, now printed via `main.go`.)
- **Probe discipline:** probe residue (`probes/nested/` + `_index.yaml`) created, reverted; `git status --short` clean; `git log` shows only the two legitimate commits; integration suite still green after cleanup.{"model": "deepseek-v4-flash", "problem_class": "go-docs-onboarding", "result": "passed", "tests": 3}