72 lines
4.2 KiB
Markdown
72 lines
4.2 KiB
Markdown
# Proposal: add-os-status-plugin
|
|
|
|
## Why
|
|
|
|
Two real incidents show that cc-os plugins have per-project and per-environment preconditions
|
|
that nothing verifies: (1) the WS1 orchestration audit found `CLAUDE_CODE_SUBAGENT_MODEL=haiku`
|
|
had silently downgraded all 23 verified subagent spawns for weeks — the E1 canary proved this
|
|
is unobservable to the model at spawn time, so protection must be deterministic; (2) projects
|
|
routinely lack the artifacts plugins assume (no ADR system, no vault hub note), and each plugin
|
|
currently invents its own SessionStart reminder in isolation (os-adr, os-doc-hygiene) or has
|
|
none (os-vault hub notes, os-orchestration env checks). A single aggregated status check at
|
|
SessionStart closes this class of gap; WS2's eval work also depends on it (hub-note presence
|
|
becomes a checked artifact).
|
|
|
|
## What Changes
|
|
|
|
- New global plugin `os-status` (per the cc-os `os-[domain]` naming convention): one
|
|
SessionStart hook that runs all cc-os status checks **in-process** and emits at most one
|
|
short banner.
|
|
- Checks are plain Python functions in a shared module inside `os-status` — NOT per-plugin
|
|
subprocess scripts and NOT project-local copies. This was pressure-tested 2026-07-06 by
|
|
simplifier and implementer perspective reviews (see `design.md`): per-project copies are the
|
|
proven copy-drift failure class, and a subprocess/JSON enumeration protocol is overbuilt for
|
|
the current three checks. The function signature is convention-shaped (each check returns a
|
|
status + message), so extraction to per-plugin `status/check.py` enumeration later is
|
|
mechanical if a check ever needs isolation.
|
|
- Initial checks (Phase 1):
|
|
- `adr-system-present` — refactors os-adr's existing existence-check behavior into a
|
|
conforming check; **BREAKING (internal)**: os-adr's own SessionStart hook is removed in the
|
|
same change (atomic cutover, to avoid double banners).
|
|
- `vault-hub-note-present` — new: warns when the current project has no hub note in the
|
|
SecondBrain vault, naming the corrective skill.
|
|
- `subagent-model-env-override` — new: warns when `CLAUDE_CODE_SUBAGENT_MODEL` (or a
|
|
model-forcing equivalent) is set in the environment or `~/.claude/settings.json`. Would
|
|
have caught the WS1 Cluster 1 incident at SessionStart.
|
|
- Per-project state dir `.cc-os/` (gitignored) for snooze/suppress of warnings — state only,
|
|
never code. Existing `.os-adr/` and `.dochygiene/` dirs are left untouched (consolidation
|
|
deliberately deferred).
|
|
- Explicitly deferred to a later change: `context` injection field (no consumer yet),
|
|
state-dir consolidation, cache-freshness verification (Phase 2 "collection manager"),
|
|
subprocess/enumeration protocol.
|
|
|
|
## Capabilities
|
|
|
|
### New Capabilities
|
|
|
|
- `status-checks`: the in-process check contract (function signature, ok/warn/note semantics,
|
|
timeout/failure-isolation rules) and the three initial checks.
|
|
- `status-banner`: SessionStart aggregation — silence rules, single-banner output, per-project
|
|
snooze/suppress state in `.cc-os/`.
|
|
|
|
### Modified Capabilities
|
|
|
|
<!-- none — os-adr's hook behavior moves, but no existing openspec/specs/ capability covers it;
|
|
the os-adr change is captured under status-checks' migration requirements. -->
|
|
|
|
## Impact
|
|
|
|
- New: `plugins/os-status/` (hooks/hooks.json + session_start.py entry point, shared checks
|
|
module, model-free Python tests, invariants.md).
|
|
- Modified: `plugins/os-adr/hooks/hooks.json` + `hooks/session_start.py` (SessionStart entry
|
|
removed; usage-note behavior preserved via the new check's `note` semantics — the perspective
|
|
review flagged that a naive "silent on ok" would regress os-adr's present-state usage note).
|
|
- Unchanged: os-doc-hygiene's reminder (converted in a follow-up, not this change, to keep the
|
|
migration surface small); os-vault hooks (its wiring inconsistency — absolute-path source
|
|
wiring vs cache — is documented in design.md as a known issue but not a blocker for the
|
|
in-process shape, which reads nothing from other plugins' caches).
|
|
- Requires `bin/refresh-plugins` + marketplace manifest entry + `claude plugin install` for the
|
|
new plugin; fresh-session smoke test.
|
|
- ADR to be added in `docs/memory-system/03-architecture-decisions.md` (status-check
|
|
convention + in-process code-location decision).
|