raddue/compass

<!-- CANONICAL: shared/compass-protocol.md -->

Compass

A single docs/compass.md per repo that answers "where am I, what's the next move, what will I forget?" Auto-maintained by the skills that mark meaningful lifecycle events; read by getting-started at every session entry.

Skill type: Utility — direct execution, no subagent dispatch.

Platform: POSIX only (Linux, WSL2, macOS). Native Windows not supported in v1.

When to use

| Situation | Action | |-----------|--------| | "What arc am I on?" / session reorientation | compass read or compass read --compact | | Inspect full file | compass read | | Manually set a field | compass update --field <name> --value <value> | | File is at the 40-line cap | compass compress | | Suspect schema drift or parse error | compass doctor |

Most users never invoke compass directly — it fires automatically through build, merge-pr, and finish.

File location

docs/compass.md — either committed (shared arc state) or gitignored (local session state); this is a per-repo policy choice. doctor reports the mode as advisory INFO via git check-ignore docs/compass.md and never fails on it (C-9, #308).

Schema

# Compass

**Current arc:** #NNN: <one-line subject>
**Last meaningful commit:** `<sha>` — <one-line subject>
**Updated:** YYYY-MM-DD HH:MM:SS

## Open loops
- <one line each, max 5 visible>

## Next move
<one paragraph, max 5 lines>

## Don't forget
- <terse, max 3>

40-line hard cap (D4). Exceeding it raises CompassFullError (exit 2) — no data written. Run compass compress or edit manually before retrying.

CLI reference

python scripts/compass.py <subcommand> [args]

| Subcommand | Notes | |------------|-------| | read | Print full docs/compass.md. | | read --compact | 3-5 line summary ([ARC], [NEXT], [OPEN], [STALE]). Used by getting-started. | | update --field X --value Y | Set scalar field. List fields: repeat --value for each element (destructive replace). | | update --field X --value Y --value Z | Set list field to [Y, Z]. | | append --field X --value Y | Append one entry to a list field with dedup. | | update-many --field X --value Y --field Z --value W | Atomic multi-field patch under one lock. | | doctor | Validate schema, check line count, report stale status. | | compress | v1.1 stub — exits 0 with advisory to edit manually or wait for v1.1. |

Fields: current_arc (scalar), last_meaningful_commit (scalar), next_move (scalar), open_loops (list, cap 5 visible / 10 hard), dont_forget (list, cap 3).

Grammar constraints:

• current_arc must match #NNN: <subject> (leading # required) or be empty string (arc-closure).
• last_meaningful_commit must contain a colon (sha:subject). <pending> and <pending-merge:#NNN> are valid sentinels.
• Setting current_arc to <pending> directly raises ValueError — that sentinel is internal to bootstrap only.
• current_arc subjects may contain literal @ characters but cannot contain a @ <timestamp-shape> sequence ( @ YYYY-MM-DDTHH:MM:SS) anywhere in the value — it would collide with the D8.5 paused-entry delimiter (v1.1; see #286).

Integration points

Compass is auto-maintained at four lifecycle moments. Direct invocation is rarely needed.

| Skill | Event | Fields written | |-------|-------|----------------| | build | After Gate Ledger Initialization + resume decision, before Phase 1 IN_PROGRESS. Skipped on resume path. | current_arc | | merge-pr | After gh pr merge succeeds and post-merge CI passes. | last_meaningful_commit | | finish Option 1 | After local merge + tests pass. | last_meaningful_commit + arc-closure (current_arc='', next_move) | | finish Option 2 | After gh pr checks --watch returns green. | provisional arc-closure only (current_arc='', next_move) |

finish Options 3 and 4 emit nothing. getting-started reads (never writes) via compass read --compact.

Sub-agents spawned inside these skills must not emit compass updates (D14 — best-effort in v1).

Error policy: compass emits are best-effort. A failed emit must not fail the enclosing pipeline.

Multi-arc collision (D8/D8.5)

When current_arc is set to a new non-empty arc while an arc is already active, the prior arc is pushed onto open_loops as [paused] #NNN: <subject> @ <timestamp>. On resume (setting current_arc back to a paused arc's ticket), the paused entry is removed from open_loops.

Direct writes to open_loops by integration sites are prohibited (D8 direct-write invariant). Only manual user intervention sets open_loops directly.

Environment variables

| Variable | Default | Purpose | |----------|---------|---------| | CRUCIBLE_COMPASS_STALE_DAYS | 14 | Days before [STALE] tag appears in compact output. Read per-call inside read() only. | | CRUCIBLE_COMPASS_TEST_SLEEP_MS | 0 | Bounded [0, 5000] ms sleep inside _acquire_lock for test-orchestrated contention. Intentional; do not remove. |

Key invariants

• C-9: docs/compass.md's git-tracking mode (committed vs gitignored) is a per-repo policy choice. doctor reports it as advisory INFO via git check-ignore docs/compass.md; neither mode is a failure (#308 reconciliation).
• C-4: 40-line hard cap. Any write producing >40 lines is rejected; no partial write occurs.
• D11: Idempotency — same update --field X --value Y applied twice yields the same state. True no-ops do not bump Updated:.
• D14: Compass emits only from skill orchestrators, never from sub-agents (best-effort, v1).

For full protocol details — lock mechanics, RMW flow, bootstrap sentinel, compact rendering spec, and invariants index — see skills/shared/compass-protocol.md.