telltale: Instructions file for Claude Code

telltale — contributor contract

This file is the convention layer a fresh session cannot get from Go itself. Read README.md, STATE.md, PARITY.md and docs/design.md too — this file is short on purpose and defers to them for the product's own claims. Rulings since 2026-09-02 live in LEDGER.md, one dated line each; read it before citing a design.md taste ruling, because three of them are lifted there.

Build and test

go vet ./...
go test ./...
go build -o telltale.exe ./cmd/telltale

A local go test ./... can time out in internal/council. That package spawns processes and runs ~455s on a reference workstation, close to Go's 600s default, so a loaded machine overruns it — a machine-speed condition, not a regression (CI runs the whole suite in ~4m22s). Two fan-out lanes hit it independently on 2026-08-16. Run go test ./internal/council -timeout 20m, or test the package you touched, when the full run overruns locally.

That is the whole CI gate (.github/workflows/ci.yml), which runs on windows-latest — Windows is the primary target (ADR-002), not an afterthought platform. CI then smoke-tests the built binary against two fixtures and asserts honesty properties directly on stdout, e.g.:

if ($out -match '5h|7d') { throw "honest-gauge violation: quota rendered without rate_limits: $out" }

If you touch a statusline segment, expect a similar assertion to exist or to be worth adding — this repo tests the rendered string, not just that the code ran.

Run git as plain git, never git -C <path> — if you are a council seat. This is posture-dependent, and PR #223 did not change it either way — read STATE.md's "write seat's git -C allowlist gap" entry for the full measurement. In the ungated write posture (PostureWrite), Claude Code's own --allowedTools matcher answers your permission prompts, and it is prefix-only: autoAllowedTools in internal/council/vendors/claude.go grants Bash(git status:*) and friends, but that cannot match a command beginning git -C, and no rule spelling fixes it (Bash(git -C:*) stays rejected — it would pre-approve every -C verb, destructive ones included). Your cwd is already the workspace, so -C buys nothing and costs that posture's git calls an approval. In the gated posture (PostureWriteGated, the one PR #223 hardened), a different mechanism answers instead — council's own autoApproveRoutine, via safeGitArgs in internal/council/persistent.go — and it strips a leading -C <path> before classifying the command, so git -C <path> status and git status are already the same call to the gate (internal/council/gate_git_test.go pins this). That classifier predates PR #223 by a week and PR #223 never touched it, so the gated posture was never the bug this instruction describes. Write plain git regardless: a seat cannot tell which posture it is running under, plain git costs nothing extra when gated, and it saves an approval when ungated. This inverts the usual advice: outside a seat, git -C is preferred precisely to avoid cd && chains. Same trap on gh in the ungated posture — gh pr and gh run are allowlisted there, gh api is not, so reach for the porcelain rather than the API.