Merge pull request #443 from escoffier-labs/feat/notify-docs-compat

feat(compat): complete notify beta handoff

Author: solomonneas

CHANGELOG.md

@@ -8,11 +8,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- Imported `stations/notify` Go module into the Brigade monorepo. Unified release
+  manifests now enumerate five native components (25 platform assets plus
+  `component-manifest-v1.json` and `checksums.txt`) with managed resolution
+  through `brigade setup`.
+- Beta pre-pin compatibility: beta installs the CI-green `main` Brigade wheel but
+  reuses the last verified stable component manifest; `agent-notify` is omitted
+  from setup until a stable manifest publishes its assets. Stable validation
+  stays strict.
+- Public update-channel and component-manifest policy docs.
+- Agent Pantry compatibility probe: `brigade pantry` requires `agentpantry
+  version --json` `>=0.5.0` before invoking doctor, status, or inventory
+  surfaces. Pantry remains an external Go binary.
 - Passive update notice: after a successful command, brigade prints a one-line
   stderr notice (at most once per 24h) when a newer release is on PyPI.
   Anonymous, TTY-only, skipped in CI; disable with `BRIGADE_NO_UPDATE_CHECK=1`.
 - `brigade mcp sync --user-scope` (and `brigade operator sync-mcp --user-scope`) no longer writes stdio MCP servers into a user-wide client config silently: interactive runs show the destination, stdio count, and the servers-times-sessions process formula and ask for confirmation, non-interactive and `--json` runs require `--allow-global-stdio`, and plan/sync items now carry `transport` and `scope`. (#349)
 
+### Fixed
+- Agent Pantry version parsing stays non-throwing and bounded for arbitrarily
+  long numeric segments: the parser accepts ASCII-numeric semver triples only,
+  enforces a conservative per-segment digit bound, catches `int()` conversion
+  `ValueError`, and surfaces the fixed `invalid-version` label for oversized or
+  non-ASCII-digit input without ever echoing raw content. Added huge-segment and
+  non-ASCII-digit regressions covering observed/detail and adjacent stdout.
+- `docs/component-manifest-policy.md` no longer presents the five-component /
+  25-asset contract as a current stable release. It is now stated as the future
+  first stable manifest contract after `agent-notify` publication, with current
+  bundled `agent-notify` assets empty/unpublished and no stable release claimed.
+
 ## [0.25.1] - 2026-07-21
 
 ### Added

README.md

@@ -45,6 +45,11 @@ brigade prints a one-line notice when a new release is out (checked at most
 once a day via an anonymous request; set `BRIGADE_NO_UPDATE_CHECK=1` to
 disable - details in [docs/update-channels.md](docs/update-channels.md)).
 
+Stable pinners may deliberately install an exact release with
+`pipx install brigade-cli==X.Y.Z` or refresh through
+`brigade update --channel stable`. Channel ownership, beta rules, and when to
+use `brigade update` are in [docs/update-channels.md](docs/update-channels.md).
+
 `brigade operator doctor --target ./my-repo` prints `ready: yes` when the wiring is healthy. The default footprint is small: `AGENTS.md`, `SAFETY_RULES.md`, a handoff template, and `.brigade/` state. Add `--dry-run` to preview anything before it writes. Nothing leaves your machine.
 
 Per-OS setup (apt, Homebrew, Scoop, PowerShell), workspace depth, and multi-harness installs: [install guide](https://brigade.tools/docs/getting-started/install), [QUICKSTART.md](QUICKSTART.md), [first 10 minutes](docs/first-10-minutes.md). Homegrown setup already? `brigade operator adopt plan`.
@@ -165,6 +170,7 @@ Code intelligence, Evidence, and Content Guard (`brigade scrub`, a secrets and P
 | [Agent Pantry](https://github.com/escoffier-labs/agentpantry) | `brigade add pantry` | Encrypted browser-session and secret sync across machines |
 | [Token Glace](https://github.com/escoffier-labs/token-glace) | `brigade add tokens` | Compact noisy tool output before it burns context |
 | [Skillet](https://github.com/escoffier-labs/skillet) | optional roster | Portable skills that reconcile can promote or roll back |
+| Notifications | `brigade add notifications` | Optional `agent-notify` binary for Discord, Telegram, or Signal; status and setup planning only until you wire hooks or pass an explicit `--send` |
 
 Upgrading from the standalone GraphTrail or MiseLedger installs? `brigade setup` replaces both. The old `brigade add graphtrail` / `add evidence` paths remain as compatibility shims. Details: [wiring guide](docs/wiring-graphtrail-miseledger.md), [station contract](docs/station-contract.md).
 
@@ -188,7 +194,7 @@ Beyond the daily loop, the same review-and-receipt pattern covers cross-model ru
 
 ## What Brigade is not
 
-Brigade is not a hosted memory service, a daemon, or an automatic release bot. It does not run in the background or install schedulers (one scoped exception: `brigade tools runtime start` launches a local runtime process, only when you start it, until you stop it). It does not push to GitHub, publish packages, send notifications by default, save every note automatically, or skip review for ambiguous, risky, or failed notes. That pause is the point: agent memory should be useful, not noisy.
+Brigade is not a hosted memory service, a daemon, or an automatic release bot. It does not run in the background or install schedulers (one scoped exception: `brigade tools runtime start` launches a local runtime process, only when you start it, until you stop it). It does not push to GitHub, publish packages, save every note automatically, or skip review for ambiguous, risky, or failed notes. `brigade work brief` and related status surfaces may report notification readiness or suggest installing the notifications station, but Brigade never sends a message unless the operator uses an explicit send action such as `brigade pantry expiry-alert --send`. That pause is the point: agent memory should be useful, not noisy.
 
 And it is not the other projects that share the name. This Brigade is the AI-agent operator CLI from [`escoffier-labs/brigade`](https://github.com/escoffier-labs/brigade), installed with `pipx install brigade-cli`. It is not the CNCF/Microsoft Brigade for Kubernetes event scripting (archived 2022), the Spinabot Brigade agent crew, or the 2017 `brigade` Python package that became Nornir.
 

docs/component-manifest-policy.md

@@ -5,12 +5,22 @@ from `brigade.station.v1` and `station_manifest.load`.
 
 ## Unified-release components
 
+The five-component / 25-asset contract below is the **future first stable manifest
+contract**, landing after `agent-notify` publication. No stable release yet contains
+this five-component / 25-asset `agent-notify` contract: the bundled compatibility
+manifest on `main` lists `agent-notify` as a known component with **empty/unpublished**
+assets, and the other four components have not yet shipped a stable manifest under
+this contract. Stable validation
+stays strict and will require every published component to carry the full
+five-platform matrix with matching digests and provenance.
+
 | Component id | Executable | Native release status |
 | --- | --- | --- |
 | `graphtrail` | `graphtrail` | built from the tagged Brigade commit |
 | `graphtrail-mcp` | `graphtrail-mcp` | built from the tagged Brigade commit |
 | `miseledger` | `miseledger` | built from the tagged Brigade commit |
 | `sessionfind` | `sessionfind` | built from the tagged Brigade commit |
+| `agent-notify` | `agent-notify` | bundled empty/unpublished on main; first stable manifest contract after `agent-notify` publication |
 
 Every component records the immutable 40-character tagged Brigade commit in `component_revision`.
 Every `source.repository` is `escoffier-labs/brigade`, and every `source.release_tag` is the same
@@ -50,17 +60,39 @@ download URL invariants, and a 40-character lowercase `component_revision` for e
 The revision must equal the immutable target commit of the resolved Brigade release. Unknown
 component ids remain a soft diagnostic; malformed known components are a hard failure.
 
-`scripts/generate_component_manifest.py` derives the final manifest in deterministic order from the
-tag, commit, exact 20 filenames, byte sizes, and SHA-256 values. It also writes `checksums.txt`,
-which contains exactly those 20 assets and `component-manifest-v1.json`.
+`scripts/generate_component_manifest.py` derives the future first stable
+manifest in deterministic order from the tag, commit, exact 25 filenames, byte
+sizes, and SHA-256 values. That 25-asset set is the contract the first stable
+manifest will publish after `agent-notify` publication; until then the bundled
+compatibility manifest on `main` carries empty/unpublished `agent-notify`
+assets and no stable release is claimed. The script also writes
+`checksums.txt`, which contains exactly those 25 assets and
+`component-manifest-v1.json`.
 
 The release gate runs `scripts/verify_component_manifest_provenance.py` after creating the release.
-It requires exactly one `escoffier-labs/brigade` tag for all four components, the complete five-platform
-matrix, exactly 20 native assets plus the manifest and checksum file, matching release API digests,
+It requires exactly one `escoffier-labs/brigade` tag for all five components, the complete five-platform
+matrix, exactly 25 native assets plus the manifest and checksum file, matching release API digests,
 the complete checksum map, matching fetched `checksums.txt` bytes, and a release-page manifest
-byte-for-byte equal to the packaged manifest. It uses injected fetchers in unit tests. Attestation verification is deliberately performed by `gh
+byte-for-byte equal to the packaged manifest. This is the future first stable manifest contract;
+it does not apply to the current bundled compatibility manifest, whose `agent-notify` assets remain
+empty/unpublished. It uses injected fetchers in unit tests. Attestation verification is deliberately performed by `gh
 attestation verify` in the release workflow rather than represented by an API boolean.
 
+## Pre-pin beta window
+
+Stable validation remains strict: every published component on a stable manifest must carry the full
+five-platform matrix with matching digests and provenance.
+
+Beta is the development channel for CI-green `main`. It installs the checked `main` Brigade wheel
+but reuses the last verified stable component manifest for native bytes, so beta and stable cannot
+install different native assets from two manifests at once.
+
+During the pre-pin window before `agent-notify` first appears on a stable manifest, main may list
+`agent-notify` as a known component with empty assets in the bundled compatibility manifest.
+`brigade setup` on beta skips a component explicitly unpublished on main until a stable manifest
+publishes real assets for it. Stable releases never ship with empty asset sets for a listed
+component.
+
 ## User-local path invariants
 
 Components install under the user data root, never under a repo `.brigade` directory:

docs/overview.md

@@ -283,7 +283,7 @@ For safety:
 - import Content Guard findings into the work inbox for review
 - keep generated state ignored by default
 - avoid publishing, pushing, or mutating remotes automatically
-- keep notification sending opt-in
+- keep notification sending opt-in; `brigade work brief` may report readiness or suggest the station, but Brigade never sends unless the operator uses an explicit send action
 - make risky actions visible as operator decisions
 
 ## Ecosystem
@@ -337,15 +337,15 @@ Safety and operations tools:
 
 - Content Guard is embedded in Brigade and powers `brigade scrub`, publish checks, and the seeded pre-push hook. `CONTENT_GUARD_DIR` remains an explicit compatibility override for older standalone checkouts.
 - [Agent Pantry](https://github.com/escoffier-labs/agentpantry): encrypted browser session, cookie, and secret sync for agent machines.
-- [agent-notify](https://github.com/escoffier-labs/agent-notify): optional notification hooks for long-running agent work.
+- [agent-notify](https://github.com/escoffier-labs/agent-notify) (`stations/notify/` in this monorepo): optional notification hooks for long-running agent work. Released installs resolve the pinned managed `agent-notify` binary through `brigade setup` once a stable manifest publishes its assets. The standalone repository carries a migration notice and is not archived until a containing Brigade release ships and published acceptance passes.
 - [Token Glace](https://github.com/escoffier-labs/token-glace): output compaction for terminal-heavy agent workflows.
 - Built-in Scout skills: Brigade wires `brigade-work` and `ultra-work-scout` during `brigade init`; use Skillet when you want the full optional skill roster.
 
 Evidence ledger tools:
 
 - [MiseLedger](https://github.com/escoffier-labs/miseledger): local-first evidence ledger. One binary crawls sessions, files, git history, and chat sources (`miseledger crawl ...`), stores `miseledger.adapter.v1` JSONL in SQLite with FTS5, and emits Brigade-ready evidence bundles. No separate exporter install.
 - Brigade station CLI (process boundary):
-  - `brigade setup` installs MiseLedger and SessionFind with GraphTrail and `graphtrail-mcp` from the exact release manifest
+  - `brigade setup` installs GraphTrail, `graphtrail-mcp`, MiseLedger, SessionFind, and `agent-notify` (when published on the release manifest) from the exact release manifest
   - `brigade add evidence` is a one-release compatibility fallback for an independent MiseLedger install
   - `brigade evidence status` / `doctor` — advisory health + next commands
   - `brigade evidence crawl <args...>` / `search <args...>` - transparent MiseLedger execution; engine output and exit code pass through
@@ -505,6 +505,24 @@ brigade pantry expiry-alert --send   # optional agent-notify (install notificati
 - `brigade pantry setup plan` / `service plan` — review-only plans under `.brigade/pantry/plans/`.
 - Pantry checks are advisory for workspace `doctor`. An unwired install warns but never fails a workspace run.
 
+## Notifications
+
+The `notifications` station wires optional `agent-notify` into the same operator workflow: private Discord, Telegram, or Signal delivery for long-running agent work. Source lives in [`stations/notify/`](../stations/notify/) in this repository. `agent-notify` stays a **separate Go binary** (process boundary). Brigade installs it, plans setup, and health-checks it; it does not send messages from doctor, status, or brief flows.
+
+Released pipx installs resolve `agent-notify` from the pinned unified release manifest through `brigade setup` once stable publishes its assets. `go install github.com/escoffier-labs/agent-notify/cmd/agent-notify@latest` is the explicit fallback when you are on a source checkout or the component is not yet published on the running manifest. The standalone [agent-notify](https://github.com/escoffier-labs/agent-notify) repository carries a migration notice pointing here; it is not archived until a containing Brigade release ships and published acceptance passes.
+
+```bash
+brigade add notifications
+brigade notifications status --json
+brigade notifications setup plan --profile operator
+# optional delivery after wiring:
+brigade pantry expiry-alert --send
+```
+
+- `brigade notifications status` / `brigade notifications setup plan` inspect wiring without sending.
+- `brigade work brief`, `brigade center status`, and `brigade daily status/plan` may surface notification readiness or suggest installing the station.
+- Brigade never sends unless the operator uses an explicit send action such as `brigade pantry expiry-alert --send`.
+
 ## For OpenClaw Users
 
 OpenClaw can be the memory owner. Brigade gives nearby tools a way to contribute checked handoffs back into that owner memory without forcing every tool to know OpenClaw internals.