34 lines
4.1 KiB
Markdown
34 lines
4.1 KiB
Markdown
|
---
|
||
|
|
id: "0022"
|
||
|
|
date: 2026-07-06
|
||
|
|
status: Accepted
|
||
|
|
supersedes:
|
||
|
|
superseded-by:
|
||
|
|
affected-paths: []
|
||
|
|
affected-components: []
|
||
|
|
migration_confidence: medium
|
||
|
|
migration_source: "docs/memory-system/03-architecture-decisions.md### ADR-022 — os-status plugin: aggregated in-process SessionStart status checks"
|
||
|
|
---
|
||
|
|
|
||
|
|
# 0022 — os-status plugin: aggregated in-process SessionStart status checks
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
Two real incidents showed that cc-os plugins have per-project and per-environment preconditions nothing verifies: (1) `CLAUDE_CODE_SUBAGENT_MODEL=haiku` in `~/.claude/settings.json` silently downgraded all 23 verified subagent spawns found by the WS1 orchestration audit — and the E1 canary proved the downgrade is unobservable to the model at spawn time, so protection must be deterministic; (2) projects routinely lack artifacts plugins assume (ADR system, vault hub note), with each plugin inventing its own SessionStart reminder in isolation (os-adr, os-doc-hygiene) or having none. The WS3 plan (`docs/plans/ws3-status-convention-plugin.md`) proposed a per-plugin status-check convention plus a glue plugin; two perspective reviews (simplifier, implementer, 2026-07-06) pressure-tested where check code should live.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
New global plugin **`os-status`** (`plugins/os-status/`), one SessionStart hook running all checks **in-process**: plain Python functions in `hooks/checks.py` with the uniform signature `check(ctx) -> CheckResult(status, message)` and a single registry list. Three result states: `ok` (silent), `note` (near-zero-token line, never snoozed/suppressed — exists so os-adr's Eval-B-tuned usage note survives conversion verbatim), `warn` (aggregated into at most one banner; once-per-day snooze + permanent suppress in a gitignored per-project `.cc-os/` dir — state only, never code). Initial checks: `subagent-model-env-override` (env + settings.json `env` block; runs outside git projects too), `adr-system-present` (verbatim port of os-adr's hook, honoring legacy `.os-adr/suppress`), `vault-hub-note-present` (config-first slug in `.cc-os/config`, else `type/hub` + `project/<name>` facet-tag scan of the vault). os-adr's own SessionStart hook was removed atomically in the same change, with the cutover verified against the refreshed plugin cache.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
A new os-status plugin runs all per-project precondition checks in-process from a single SessionStart hook using a uniform check(ctx) function signature and a shared registry, with three result states (ok, note, warn) and per-project snooze/suppress state stored only as data, never code. This consolidates checks that were previously invented ad hoc per plugin (or missing entirely), catches issues like the silent CLAUDE_CODE_SUBAGENT_MODEL downgrade deterministically, and required removing os-adr's own SessionStart hook in the same change.
|
||
|
|
|
||
|
|
## Alternatives rejected
|
||
|
|
|
||
|
|
- **Option A — per-project code copies** (`.cc-os/status.d/*.py`): copies drift; the 2026-07-04 stale-cache incident is exactly this failure class; adds a per-project install step.
|
||
|
|
- **Option B as sketched — per-plugin scripts + subprocess/JSON enumeration**: overbuilt for three trivially cheap probes with one author in one repo (spawn/parse/timeout/error-normalization protocol for three registrants); and enumeration from plugin caches would silently run stale code — os-vault is wired by absolute path to git source and its cache copy is already stale (implementer finding). The uniform function signature is kept as the seam so extraction to per-plugin checks later is mechanical.
|
||
|
|
- **Blanket silent-on-ok**: would regress os-adr's present-state usage note; hence the third `note` state.
|
||
|
|
- **Deferred**: `context` injection field (no consumer yet), consolidation of `.os-adr/`/`.dochygiene/` state dirs, conversion of os-doc-hygiene's reminder, Phase 2 cache-freshness "collection manager" duties, subprocess enumeration.
|
||
|
|
- **Cross-references**: OpenSpec change `add-os-status-plugin` (proposal/design/specs/tasks), `plugins/os-status/invariants.md`, WS1 findings (`docs/orchestration-audit/2026-07-06-findings.md`), ADR-018 (marketplace-manifest procedure followed for install).
|