52 lines
2.4 KiB
Markdown
52 lines
2.4 KiB
Markdown
# 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 `note`s 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
|