jared
/
cc-os
1
0
Fork 0
Code Issues 17 Pull Requests Packages Projects Releases Wiki Activity
cc-os/openspec/changes/add-os-status-plugin/specs/status-banner/spec.md

2.4 KiB
Raw Blame History

status-banner — SessionStart aggregation, silence rules, snooze/suppress state

ADDED Requirements

Requirement: Single aggregated banner

The os-status SessionStart hook SHALL run all registered checks in-process and emit at most one warning banner per session, containing one short line per warn result with its corrective action. note results SHALL be emitted as individual near-zero-token lines outside the banner. When every check returns ok (and no notes exist), the hook SHALL emit nothing.

Scenario: All checks ok

  • WHEN every registered check returns ok
  • THEN the hook produces no output

Scenario: Multiple warns aggregate

  • WHEN two or more checks return warn
  • THEN exactly one banner is emitted containing one line per warning

Scenario: Note passes through without banner

  • WHEN one check returns note and all others return ok
  • THEN the note line is emitted and no warning banner appears

Requirement: Per-project snooze and suppress for warns

warn output SHALL be governed by per-project state in a gitignored .cc-os/ directory: each warning is emitted at most once per day (snooze), and a permanent suppress marker silences a given check's warnings in that project until removed. note results SHALL NOT be subject to snooze or suppress. Outside a git project, project-scoped checks SHALL be skipped and no state SHALL be written.

Scenario: Warn snoozed same day

  • WHEN a check's warning was already emitted today in this project
  • THEN the warning is not emitted again and the banner omits it

Scenario: Permanent suppress

  • WHEN .cc-os/ contains a suppress marker for a check
  • THEN that check's warnings are never emitted in this project while the marker exists

Scenario: Not a git project

  • WHEN the session starts outside a git project
  • THEN project-scoped checks are skipped, environment-scoped checks still run, and no .cc-os/ directory is created

Requirement: Hook safety envelope

The SessionStart hook SHALL complete within its configured timeout, SHALL exit 0 even when checks warn or fail internally, and SHALL never write to any file outside the project's .cc-os/ state directory.

Scenario: Internal failure stays safe

  • WHEN the checks module itself fails to import or crash-loops
  • THEN the hook exits 0 with either no output or a single generic warning line, and the session starts normally