compare exit-code threshold (0.5) is an undocumented, untested magic number
- Dominant language
- TypeScript
- Stars
- 31
- Forks
- 7
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 35
Description
### Summary
The pass/fail exit code for plain `ghost compare` uses a hardcoded `distance > 0.5` cutoff, inlined twice in `packages/ghost/src/cli.ts` (the pairwise and `--temporal` paths). The value is undocumented, untested, and was introduced as a bare literal in the founding commit (`618f275`) with no rationale in the message or code.
### Evidence
- Inline literal at `cli.ts` (pairwise exit + temporal exit), no named constant, no comment.
- No test pins the cutoff — `gate.test.ts`/`sync.test.ts` only use `0.5` as input data, not as a gate assertion. Changing the cutoff breaks zero tests.
- The only place `0.5` is given meaning is `docs/ideas/guided-migration.md` (">0.5 = different design languages"), but that's an *ideas* doc and is not referenced by the code. The alignment is coincidental, not wired.
### Why it matters
Users meet bare `compare` first and assume it's *the* drift gate. The real governance path is `compare --gate` (baseline-relative, per-dimension, acked via `.ghost-sync.json`). The arbitrary-looking `0.5` erodes trust in the number and obscures `--gate`.
### Proposed fix (non-breaking)
1. Promote `0.5` to a named, commented constant in `cli.ts` describing it as a heuristic and pointing to `--gate` for real gating.
2. Add one line to `compare --help` steering serious CI users to `--gate`.
3. (Optional, separate) consider a `--threshold ` flag only if there's real demand.
### Related
The `WEIGHTS` constants in `embedding/compare.ts` have the same "taste captured once, undocumented" smell (`1f8decb`).
Contributor guide
Research direction
Start in packages/ghost/src/cli.ts and inspect both pairwise and --temporal exit paths, then review compare --help and the existing gate.test.ts and sync.test.ts coverage. Done means the shared 0.5 heuristic is named and documented, help text points serious CI users to --gate, and a test pins the cutoff behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- cli
- Issue type
- Refactor
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100