| name | coherence |
| description | Read-only cross-source consistency checker. Surfaces drift between Linear issue state, SpecSafe slice files, and commit Spec-Slice trailers. No mutations, no network writes. |
coherence skill
Provides read-only visibility into drift between three sources of truth:
- Linear issue state (queried via the
linear skill)
- SpecSafe slice files under
specs/
- Commit
Spec-Slice: trailers in the local git history
The skill never mutates Linear, git, or files. There is no --i-approve flag.
Prerequisites
LINEAR_API_KEY — required for every subcommand. Absence is a config error
(exit 2) with a single-line stderr notice; no stdout is emitted.- A working
linear skill at .omp/skills/linear/bin/linear.ts. Tests and CI
may override the binary via PI_COHERENCE_LINEAR_CMD.
Subcommands
check linear-vs-specs
bun run .omp/skills/coherence/bin/coherence.ts check linear-vs-specs
Compares Linear in_progress / in_review tickets against specs/<KEY>*.md.
Emits one line per drift item:
[orphan-linear] <KEY> <state>, no spec — open Linear ticket with no
matching spec file.[orphan-spec] <KEY> has spec but no matching Linear ticket — spec file
whose KEY does not appear in linear list output.
KEY matching uses the github skill regex ^([A-Z]+-[0-9]+)([-_].*)?$, so
sub-slices like CUR-92__login-fix.md and CUR-92__perf.md both cover the
single Linear ticket CUR-92.
check trailers-vs-linear [--range=<git-range>]
bun run .omp/skills/coherence/bin/coherence.ts check trailers-vs-linear
bun run .omp/skills/coherence/bin/coherence.ts check trailers-vs-linear --range=HEAD~10..HEAD
Scans commits in <git-range> (default HEAD~50..HEAD), extracts
Spec-Slice: trailers (last trailer per commit wins), and validates each
referenced ticket via linear get:
[orphan-trailer] <KEY> commit references unknown Linear ticket — linear get <KEY> returns non-zero.[stale-trailer] <KEY> commit trailer points to ticket in triage — ticket
is still in triage, meaning the trailer was committed before the ticket
was promoted to active work.
Commits with no trailer or with malformed bodies are skipped silently.
check brief-coverage
bun run .omp/skills/coherence/bin/coherence.ts check brief-coverage
For each Linear in_progress / in_review ticket, looks for a matching brief
file under specs/briefs/<KEY>*.md. Emits:
[orphan-brief] <KEY> <state>, no brief in specs/briefs/ — open ticket with
no brief file. Repos lacking a specs/briefs/ directory are tolerated; in
that case every open ticket reports orphan-brief.
Brief matching only accepts <KEY>.md, <KEY>-*, <KEY>__*, or <KEY>_*
filenames so that CUR-9 does not falsely match CUR-92-brief.md.
Exit codes
| Code | Meaning |
|---|
| 0 | All sources are coherent — no drift items |
| 1 | Drift detected — one line per item on stdout |
| 2 | Config or usage error (missing LINEAR_API_KEY, bad subcommand) |
Output format
Plain text. One drift item per line on stdout, prefixed with a category tag in
square brackets (e.g. [orphan-linear]). No JSON, no color codes. The format
is machine-greppable and human-readable; CI wrappers can pipe stdout through
grep '^\[' to pull drift items.
Implementation notes
- All Linear access goes through the
linear skill — this skill never imports
the linear-sdk package and makes no direct GraphQL calls. The upstream linear list
table is parsed by header column position so multi-word state labels like
In Progress survive intact before being normalized to in_progress.
LINEAR_API_KEY is forwarded to every spawned linear invocation via the
inherited environment.- Tests under
.omp/test/coherence/ stub Linear by setting
PI_COHERENCE_LINEAR_CMD to a shell script and providing fixture content
through PI_COHERENCE_LINEAR_LIST_FIXTURE and
PI_COHERENCE_LINEAR_GET_FIXTURE_DIR. Production code reads only
PI_COHERENCE_LINEAR_CMD; the fixture variables are inert outside the test
harness.
- The skill performs no network mutations and writes no files. It is safe to
invoke from pre-commit hooks.
