cc-os/plugins/os-status/CLAUDE.md

os-status

Aggregated, in-process SessionStart status checks for the cc-os plugin family: per-project artifact checks (ADR system, vault hub note, project graph, tracker config, config version) and environment hazard checks (subagent model env override). See docs/adr/0022 for why checks are aggregated into one plugin instead of scattered per-plugin hooks.

At most one systemMessage banner per session (one line per surviving warn); note-level results bypass snooze/suppress and go out as additionalContext. Snooze/suppress state lives under .cc-os/status/ (ADR-027, with legacy top-level fallback read).

Component map

• hooks/checks.py — the check registry (REGISTRY at the bottom of the file) plus each check function and the --json CLI entry point the fix skill drives. Current checks: subagent-model-env-override, adr-system-present, vault-hub-note-present, orchestration-audit-due, tracker-configured, config-version-current, project-graph-present. Read checks.py directly for exact check logic — this list is a pointer, not a restatement.
• hooks/session_start.py — the SessionStart hook entry point; runs the registry, applies snooze/suppress, emits the single banner.
• hooks/state.py — project-root resolution, .cc-os/config read, snooze/ suppress state read/write.
• hooks/hooks.json — SessionStart wiring.
• skills/fix/SKILL.md — /os-status:fix: remediates whatever the registry flags, idempotent, doubles as the update-to-current-approach path (ADR-026).
• invariants.md — the reversion-protection contract (8 numbered invariants, including byte-identical wording parity with os-adr's session_start.py); enforced by tests/hook_test.py.
• tests/hook_test.py — 80 tests, model-free (python3 tests/hook_test.py).

Adding a check means adding a function + a Check(...) entry to REGISTRY in checks.py, following the uniform check(ctx) -> CheckResult signature (invariant #8) — do not special-case a new check's wiring elsewhere.