# os-status — component detail

_Leaf file of [../implementation-status.md](../implementation-status.md). Read on demand._

**Global os-status plugin** — `cc-os/plugins/os-status/` (git-tracked, 2026-07-06);
symlinked into `~/.claude/plugins/os-status`. Decision record: ADR-0022 (architecture),
ADR-0026 (`/os-status:fix`), ADR-0027 (state location). Built via OpenSpec change
`add-os-status-plugin` (supersedes the WS3 plan doc).

- Purpose: aggregated deterministic SessionStart status checks for the cc-os plugin family —
  per-project artifacts (ADR system, vault hub note) and environment hazards (subagent model
  env override).
- Architecture: checks are **in-process** plain Python functions in `hooks/checks.py` with
  the uniform signature `check(ctx) -> CheckResult(status, message)` plus one registry entry
  (no per-plugin subprocess protocol, no per-project code copies — both rejected in
  ADR-0022). Three states: `ok` (silent), `note` (near-zero-token additionalContext line,
  never snoozed/suppressed), `warn` (aggregated into at most one banner; once-per-day snooze
  + permanent `suppress-<check>` markers in gitignored per-project `.cc-os/status/` — state
  only, never code; shared `.cc-os/config` holds optional `hub`/`vault_path` key=value
  overrides).
- Initial checks: `subagent-model-env-override` (env + `~/.claude/settings.json` `env`
  block; runs outside git projects too — catches the WS1 Cluster 1 incident deterministically
  at session start), `adr-system-present` (verbatim port of os-adr's hook behavior incl.
  `.os-adr/suppress`), `vault-hub-note-present` (config slug first, else `type/hub` +
  `project/<name>` facet-tag scan of the vault; missing → warn naming `/os-vault:write`).
  Later additions: `tracker-configured` (2026-07-10, os-backlog issue #11),
  `orchestration-audit-due` (2026-07-10), `project-graph-present` and
  `config-version-current` (2026-07-12).
- Added 2026-07-12 (ADR-0026, issue #21): `/os-status:fix` skill — the unified project
  setup/update command; runs the registry via `python3 hooks/checks.py --json` (each result
  carries a `remediation` pointer), drives the owning plugin's remediation per failing
  check, stamps `version=` into `.cc-os/config` (`CURRENT_CONFIG_VERSION`); idempotent, so
  re-running is the update path. Warn banner names `/os-status:fix` as the single entry
  point. Human gates preserved: fix never fabricates a tracker value and never edits global
  settings.json.
- Fix tune-up (2026-07-12, issues #23/#24): the credvault smoke-test of `/os-status:fix`
  (session cd1ae1cd) was on-contract but surfaced four gaps. Fixes: `clear_snooze` helper +
  self-clearing snoozes when a check evaluates ok/note (both runners); own state relocated
  to `.cc-os/status/` with legacy fallback read + migrate-on-write (ADR-0027);
  `write_config_value` normalizes the whole file to `key=value` (no spaces); fix SKILL.md
  scopes out committing, adds an explicit "`.cc-os/` in .gitignore" step, clarifies when
  re-runs are needed. Re-run of `/os-status:fix` in credvault is the pending IRL
  verification.
- Tests: `python3 tests/hook_test.py` (80 as of 2026-07-12; 64 post-#21; 36 initial) incl.
  byte-identity of PRESENT_NOTE/ABSENT_NOTE against os-adr's source. Invariants in
  `invariants.md`. Smoke-tested 2026-07-06 (cache==source, real headless session fired the
  hook, env-override canary warns).