brigade-cli 0.5.0__py3-none-any.whl

brigade/templates/hermes/memory-handoff.harness.json

@@ -0,0 +1,36 @@
+{
+  "_comment": [
+    "EXPERIMENTAL fragment for Hermes integration.",
+    "",
+    "Describes the handoff inbox + routing targets that Hermes should treat",
+    "as the canonical memory contract."
+  ],
+  "_brigade_version": "0.1.0",
+  "_brigade_status": "experimental",
+  "memory_handoff": {
+    "inbox_dir": ".claude/memory-handoffs",
+    "processed_dir": ".claude/memory-handoffs/processed",
+    "review_inbox": "memory/handoff-inbox",
+    "routing_targets": {
+      "cards": "memory/cards",
+      "tools": "TOOLS.md",
+      "user_prefs": "USER.md",
+      "rules": "rules",
+      "errors": ".learnings/ERRORS.md",
+      "learnings": ".learnings/LEARNINGS.md",
+      "feature_requests": ".learnings/FEATURE_REQUESTS.md"
+    },
+    "auto_promote": {
+      "card_filename_regex": "^[A-Za-z0-9._-]+\\.md$",
+      "card_content_must_start_with": "---",
+      "document_targets_allowed": [
+        "TOOLS.md",
+        "USER.md",
+        "rules/*.md",
+        ".learnings/LEARNINGS.md",
+        ".learnings/ERRORS.md",
+        ".learnings/FEATURE_REQUESTS.md"
+      ]
+    }
+  }
+}

brigade/templates/hermes/model-lanes.harness.json

@@ -0,0 +1,17 @@
+{
+  "_comment": [
+    "EXPERIMENTAL fragment for Hermes integration.",
+    "",
+    "Suggested model lane names. Same shape as the OpenClaw alias map so",
+    "knowledge cards and runbooks can talk about lanes without naming providers."
+  ],
+  "_brigade_version": "0.1.0",
+  "_brigade_status": "experimental",
+  "model_lanes": {
+    "main": "<provider/main-model-id>",
+    "coder": "<provider/coder-model-id>",
+    "cron": "<provider/cron-model-id>",
+    "fast": "<provider/fast-model-id>",
+    "escalation": "<provider/escalation-model-id>"
+  }
+}

brigade/templates/hermes/workspace.harness.json

@@ -0,0 +1,30 @@
+{
+  "_comment": [
+    "EXPERIMENTAL fragment for Hermes integration.",
+    "",
+    "Hermes support follows the same contract as OpenClaw; only the file names",
+    "and command paths change. This fragment is a placeholder until validated",
+    "against a real Hermes install.",
+    "",
+    "Replace <hermes-config-path> with your Hermes config location."
+  ],
+  "_brigade_version": "0.1.0",
+  "_brigade_status": "experimental",
+  "workspace": {
+    "root": "<workspace-root>",
+    "bootstrap_files": [
+      "AGENTS.md",
+      "CLAUDE.md",
+      "SOUL.md",
+      "USER.md",
+      "TOOLS.md",
+      "MEMORY.md",
+      "IDENTITY.md",
+      "HEARTBEAT.md",
+      "SAFETY_RULES.md",
+      "INSTALL_FOR_AGENTS.md"
+    ],
+    "memory_owner": "hermes",
+    "handoff_inbox": ".claude/memory-handoffs"
+  }
+}

brigade/templates/hooks/pre-push

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# pre-push: block push if content-guard finds public-leak violations.
+#
+# Installed by `brigade init`. Activate once with:
+#   git config core.hooksPath hooks
+#
+# Bypass only if you know what you are allowing through:
+#   git push --no-verify
+#
+# Requires content-guard: https://github.com/solomonneas/content-guard
+set -euo pipefail
+
+SCANNER_DIR="${CONTENT_GUARD_DIR:-$HOME/repos/content-guard}"
+POLICY="${CONTENT_GUARD_POLICY:-$SCANNER_DIR/policies/public-repo.json}"
+
+if [[ ! -d "$SCANNER_DIR" ]]; then
+  echo "pre-push: content-guard not found at $SCANNER_DIR" >&2
+  echo "pre-push: clone https://github.com/solomonneas/content-guard, or set CONTENT_GUARD_DIR" >&2
+  exit 1
+fi
+
+if [[ ! -f "$POLICY" ]]; then
+  echo "pre-push: policy file not found: $POLICY" >&2
+  exit 1
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+echo "pre-push: scanning $REPO_ROOT against $(basename "$POLICY")"
+
+if ! PYTHONPATH="$SCANNER_DIR/src" python3 -m content_guard scan "$REPO_ROOT" --policy "$POLICY"; then
+  echo >&2
+  echo "pre-push: BLOCKED. content-guard found violations." >&2
+  echo "pre-push: fix the leak, or add an inline allow-tag on the offending line:" >&2
+  echo "pre-push:   <!-- content-guard: allow <rule-id> -->" >&2
+  exit 1
+fi

brigade/templates/includes/publisher.json

@@ -0,0 +1,15 @@
+{
+  "id": "publisher",
+  "description": "content-guard policies + scrub cache for users who publish blogs, social, or docs.",
+  "files": [
+    {"src": "policies/public-content.json", "dst": ".brigade/policies/public-content.json"},
+    {"src": "memory/cards/content-safety.md", "dst": "memory/cards/content-safety.md"}
+  ],
+  "dirs": [
+    ".brigade/scrub-cache"
+  ],
+  "post_install_notes": [
+    "Run `brigade scrub --target . --policy public-content` before publishing user-facing content.",
+    "Add `brigade scrub` to your publish workflow as a hard gate."
+  ]
+}

brigade/templates/memory/cards/backup-restic.md

@@ -0,0 +1,126 @@
+---
+topic: backup-restic
+category: infrastructure
+tags: [backup, restic, rclone, gdrive, nas, retention, recovery]
+---
+
+# Workspace Backup (Restic + rclone + NAS)
+
+Twice-daily restic backups to two destinations: Google Drive (via rclone) and a local NAS mount. Encrypted, deduplicated, snapshot-pruned. The reference script ships at `scripts/backup-restic.sh`; this card explains *why* the shape is what it is.
+
+## Why both destinations
+
+| Failure mode | Local NAS only | gdrive only | Both |
+|--------------|----------------|-------------|------|
+| Workstation disk dies | Recover from NAS, fast | Recover from gdrive, slow | Either |
+| NAS hardware failure | Lose everything | Recover from gdrive | gdrive saves you |
+| Google account locked / quota | Lose everything that ran since last NAS run | Lose everything | NAS saves you |
+| Ransomware hits workstation | Possibly hits NAS too | Off-site immutable copy | gdrive saves you |
+
+Two destinations covers the "one of them is broken" case without raising the recovery time for the common case (NAS is faster).
+
+## Cadence
+
+```cron
+0 3,15 * * * /path/to/backup-restic.sh
+```
+
+03:00 + 15:00. Twice a day means worst-case data loss window is ~12 hours. Adjust if your write velocity is higher.
+
+## What gets backed up
+
+Default paths:
+
+- The agent workspace (`~/.brigade` or your equivalent)
+- All repos under `~/repos`
+- Local scripts and bin (`~/bin`)
+- Dotfiles: `.bashrc`, `.profile`, `.gitconfig`, `.ssh`, `.claude`, `.codex`, `.npmrc`
+- Notes (`~/notes`)
+- Obsidian vault (`~/Obsidian`)
+
+Excluded by default: `node_modules`, `.git/objects`, `__pycache__`, `*.pyc`, `.venv`, `dist`, `build`, `.next`, `.astro`, `coverage`, `.turbo`, `*.jsonl`, `.pm2/logs`, `.pm2/pids`, `.ollama`, `.obsidian/workspace*.json`, `.obsidian/cache`, `.trash`.
+
+Edit the `BACKUP_PATHS` and `EXCLUDES` arrays in the script for your stack.
+
+## Retention
+
+```text
+--keep-daily 7
+--keep-weekly 4
+--keep-monthly 3
+```
+
+About 14 snapshots overlapping over three months. Plenty for human-paced workflows.
+
+## Why rclone is throttled hard
+
+Google Drive can reject bursty restic-over-rclone writes when other rclone jobs (Obsidian bisync, cookbook sync, etc.) are running. The script sets:
+
+```bash
+RCLONE_TRANSFERS=1
+RCLONE_CHECKERS=2
+RCLONE_TPSLIMIT=4
+RCLONE_TPSLIMIT_BURST=4
+RCLONE_DRIVE_PACER_MIN_SLEEP=500ms
+RCLONE_DRIVE_PACER_BURST=10
+RCLONE_RETRIES=8
+RCLONE_LOW_LEVEL_RETRIES=20
+```
+
+Conservative on purpose. A backup that takes 40 minutes and finishes beats one that races, hits Drive quota, and dies in a retry loop.
+
+## NAS shape
+
+The NAS mount is typically an SMB/NFS share at `/mnt/nas/backups`. The script:
+
+1. Skips cleanly if the mount is not present.
+2. Uses a separate restic repo path on the NAS (independent encryption + deduplication state).
+3. Tags NAS snapshots distinctly (`scheduled-nas`) so summaries are easy to read.
+
+NAS-side considerations:
+
+- **Permissions:** the NAS share must allow write from the workstation user.
+- **Lock files:** restic uses lockfiles inside the repo. A killed process can leave stale locks; the script runs `restic unlock --remove-all` after each successful backup.
+- **Read-only by default:** if the NAS holds irreplaceable family photos or other "do not touch" data, keep that data on a separate path and treat the rest of the NAS as read-only for the agent. See `SAFETY_RULES.md`.
+
+## Password
+
+```bash
+echo "<strong-password>" > ~/.brigade/.restic-password
+chmod 600 ~/.brigade/.restic-password
+```
+
+Never commit this file. Never paste the password in a chat. If the password is lost, the encrypted snapshots are unrecoverable.
+
+## Recovery
+
+```bash
+# list snapshots
+restic snapshots
+
+# restore a specific snapshot to /tmp/restore/
+restic restore <id> --target /tmp/restore
+
+# restore just one path
+restic restore <id> --target /tmp/restore --include "$HOME/repos/<project>"
+```
+
+Practice this. A backup you have never restored is a hope, not a backup.
+
+## Monitoring
+
+Log file path:
+
+```text
+~/.brigade/logs/backup-YYYYMMDD.log
+```
+
+Worth wiring into the morning report (`memory/cards/pipeline-standups.md`): grep recent logs for `ERROR` and surface in the briefing. A silent backup that has been failing for three weeks is the second-worst kind of bug.
+
+## Anti-patterns
+
+- **One destination only.** Single point of failure.
+- **No retention policy.** Old snapshots accumulate, gdrive quota fills, new backups fail.
+- **Backing up `node_modules`.** Wastes deduplication windows. Use the excludes.
+- **Backing up secrets unencrypted.** `.env` files get backed up too; that is intentional because restic encrypts everything at rest. The password file is the keystone; protect it.
+- **Skipping verification.** Run `restic check` periodically. Snapshots that exist but are corrupted are not snapshots.

brigade/templates/memory/cards/chat-surface-crawlers.md

@@ -0,0 +1,103 @@
+---
+topic: chat-surface-crawlers
+category: foundation
+tags: [chat-archives, discord, slack, whatsapp, telegram, sqlite, ingest]
+---
+
+# Chat Surface Crawlers
+
+If you let your agent operate across messaging surfaces (Discord, WhatsApp, Slack, Telegram, etc.), you need each surface mirrored into a queryable local store. Native search on those platforms is inconsistent, rate-limited, and disappears when the platform decides to. A local crawl gives you durable history and feeds the [memory-scanner](memory-scanner.md).
+
+## Pattern
+
+```text
+chat platform        local mirror             searchable store
+   (Discord,           (bot or auth-token        (SQLite + FTS5,
+    Slack,              with read access)         or vector index)
+    WhatsApp,
+    Telegram,
+    iMessage)
+                              |
+                              v
+                   crawler tail/sync (live + periodic repair)
+                              |
+                              v
+              memory scanner reads recent archive ranges
+                              |
+                              v
+              .claude/memory-handoffs/ or direct card writes
+```
+
+Each crawler is platform-specific (auth differs, intents differ, rate limits differ), but they share the same shape:
+
+- **Live tail.** Long-running process that receives new messages as they arrive.
+- **Periodic full sync.** Repair pass that catches anything the live tail missed.
+- **Local SQLite store.** Messages, threads, members, mentions, attachments.
+- **FTS5 search index** (or equivalent) so the scanner can query without ranking on the platform's API.
+- **Read-only export.** Other machines or readers consume a snapshot; only the canonical host runs live sync.
+
+## Surfaces and tools
+
+| Platform | Crawler (suggested name) | Status |
+|----------|--------------------------|--------|
+| Discord | [`discrawl`](https://github.com/solomonneas/discrawl) | Available. Bot-token, SQLite + FTS5, git-snapshot read mode. |
+| Slack | `slackcrawl` | Pattern-name. Bot-token + RTM events; same SQLite shape. |
+| WhatsApp | `whatsappcrawl` | Pattern-name. Likely via WhatsApp Business API or Multi-Device session bridge. |
+| Telegram | `tgcrawl` | Pattern-name. Bot API + MTProto for history backfill. |
+| iMessage | `imescrawl` | Pattern-name. macOS-only; reads from local `chat.db`. |
+| Signal | `signalcrawl` | Pattern-name. Signal-cli session export. |
+| Email (Gmail/IMAP) | `mailcrawl` | Pattern-name. IMAP IDLE for tail, full-folder sync for repair. |
+
+The names above follow the `<platform>crawl` convention used by `discrawl`. Swap them for whatever tool you actually use - the contract matters, not the binary name.
+
+## Discrawl reference (the tested one)
+
+`discrawl` is the canonical implementation:
+
+- mirrors Discord guilds into SQLite
+- FTS5 search across all archived content
+- offline member directory from archived profile payloads
+- structured mention/role/attachment indexing
+- Gateway event tail for live updates, periodic repair sync
+- private git-backed snapshot publish for org-wide read access without bot credentials
+
+Use it as the template for other surfaces. New crawlers should expose:
+
+1. A `sync` verb that fetches history.
+2. A `tail` verb that streams new messages.
+3. A read-only SQL or HTTP query surface.
+4. Read-only consumption that does not require platform credentials.
+
+## How the memory scanner consumes archives
+
+The [memory-scanner](memory-scanner.md) does not read raw transcripts. It queries the crawler's archive for recent ranges and asks the underlying model to extract durable facts.
+
+Typical pattern:
+
+```bash
+# scanner pseudocode
+since=$(date -d 'yesterday' -u +%Y-%m-%dT%H:%MZ)
+discrawl query --since "$since" --channel "#decisions" --format json |
+  memory-scan extract --to-handoff .claude/memory-handoffs/
+```
+
+The scanner writes one Memory Handoff per durable finding. The conservative ingester routes those handoffs into cards / runbooks / learnings the same way it routes anything else.
+
+## Privacy boundary
+
+Chat archives are *intimate*. The crawler's local SQLite often contains:
+
+- DMs the agent should not summarize back to a group
+- Private mentions of other people who never consented to AI processing
+- Credentials, addresses, financial details that landed in a chat once
+
+Rules:
+
+- The scanner produces summaries, never quotes. Original messages stay in the crawl archive.
+- Cards promoted from chat archives must not include third-party PII unless the user explicitly approved.
+- Run `brigade scrub --policy public-content` over any export of crawl-derived content before publishing.
+- The publish gate (`hooks/pre-push` + content-guard) catches accidental leaks at the repo boundary.
+
+## Not connected to a chat surface?
+
+That is fine. The memory scanner works with just daily session logs and `.learnings/*.md`. Crawlers are additive - they expand the surface from which durable facts get distilled.

brigade/templates/memory/cards/content-safety.md

@@ -0,0 +1,54 @@
+---
+topic: content-safety
+category: foundation
+tags: [publishing, content-guard, pre-push, scrubber]
+---
+
+# Content Safety
+
+`brigade` installs a publish gate so private infrastructure does not leak into public docs, commits, or social drafts.
+
+## Default blocked classes
+
+- Private IP addresses and loopback endpoints
+- Internal hostnames, usernames, and private domains
+- Local service URLs and sensitive ports
+- Secrets, tokens, API keys, OAuth material
+- Personal contact details and account IDs
+- Private project names or unreleased identifiers
+- AI attribution trailers (`Co-Authored-By: Claude`, etc.)
+
+## Two layers
+
+1. **Pre-push hook.** `hooks/pre-push` runs `content-guard` against the working tree before every `git push`. Blocks on violations. Inline allow-tags exist for intentional examples.
+2. **Deterministic scrub.** `brigade scrub --target .` runs the same scanner standalone. Use it before generating public artifacts (blog posts, social drafts, docs PRs).
+
+## Bypass
+
+`git push --no-verify` skips the pre-push hook. Use it only when you understand exactly what you are allowing through. Both `brigade scrub` and the hook log every violation so you can audit later.
+
+## Inline allow
+
+If an example genuinely needs a localhost reference: <!-- content-guard: allow localhost-bare -->
+
+```markdown
+A local service might run on localhost:8080. <!-- content-guard: allow localhost-port -->
+```
+
+## Setup
+
+```bash
+git config core.hooksPath hooks
+```
+
+If content-guard is not installed:
+
+```bash
+git clone https://github.com/solomonneas/content-guard ~/repos/content-guard
+```
+
+The hook reads `CONTENT_GUARD_DIR` (defaults to `$HOME/repos/content-guard`) and `CONTENT_GUARD_POLICY` (defaults to `$SCANNER_DIR/policies/public-repo.json`).
+
+## Why this is part of the product
+
+Most leaks are accidental. A blog post mentions a port. A commit message includes an internal IP. A social draft pastes an OAuth profile path. Without a gate, all of those reach the public eventually. The gate runs deterministically on every push, so the question stops being "did I remember to scrub" and starts being "did the scanner say clean".

brigade/templates/memory/cards/handoff-flow.md

@@ -0,0 +1,70 @@
+---
+topic: handoff-flow
+category: foundation
+tags: [memory, handoff, ingester, claude-code, codex]
+---
+
+# Memory Handoff Flow
+
+Claude Code, Codex, and other side harnesses write Memory Handoffs to `.claude/memory-handoffs/`. A conservative ingester parses them and routes durable knowledge into canonical memory.
+
+## End-to-end
+
+1. Side harness finishes a substantial task.
+2. Closeout rule fires: "did this session produce durable knowledge?"
+3. If yes, the harness writes `.claude/memory-handoffs/<YYYY-MM-DD-HHMM>-<slug>.md` using `TEMPLATE.md`.
+4. The ingester (run by the memory owner) parses each handoff.
+5. Handoffs route to: a memory card, an appendable document, or the review inbox.
+6. Processed handoffs move to `.claude/memory-handoffs/processed/`.
+
+## Multiple Workspaces
+
+If you administer more than one agent setup, keep this flow hub-and-spoke. Secondary workspaces write local handoffs, then the canonical owner pulls them into staging directories and runs the same ingester. This lets agents on separate machines or repos inform each other about what changed without creating competing memory stores.
+
+See [multi-workspace-handoff-admin](multi-workspace-handoff-admin.md) for the full pattern.
+
+## Auto-promotion rules
+
+Only three handoff shapes can silently mutate canonical memory. Everything else lands in `memory/handoff-inbox/` for manual review.
+
+**Card auto-promotion:**
+- `Recommended memory action` is `create-card` or `update-card`.
+- `Target card` matches `^[A-Za-z0-9._-]+\.md$` (no path traversal).
+- `Suggested card content` starts with YAML frontmatter.
+
+**Document routing:**
+- `Recommended memory action` is `no-card`.
+- `Target document` is one of: `TOOLS.md`, `USER.md`, `rules/*.md`, `.learnings/*.md`.
+- `Suggested document content` has no `##` headings (would parse as new sections).
+
+## Closeout instruction
+
+The harness must be told to write handoffs without prompting. Put this in the harness's instruction file (e.g. `~/.claude/CLAUDE.md` or equivalent):
+
+```text
+At the end of any substantial task, check whether the session produced durable
+knowledge. If yes, create a Memory Handoff in `.claude/memory-handoffs/`
+using the standard format. Do this without waiting to be reminded.
+```
+
+## Verification
+
+```bash
+# Handoffs being produced
+find . -path "*/.claude/memory-handoffs/*.md" -not -path "*/processed/*" -mtime -7
+
+# Ingest run
+brigade ingest --target . --dry-run
+
+# Cards landed via promotion
+find memory/cards -mtime -7 -name "*.md"
+
+# Review inbox depth
+ls memory/handoff-inbox/ 2>/dev/null | wc -l
+```
+
+## Gotchas
+
+- `##` inside `Suggested document content` parses as a new handoff section. Use `###` or deeper.
+- Auto-promotion writes to the filesystem immediately. Ingest during quiet hours if you care about cache continuity.
+- The ingester is intentionally conservative. If your inbox grows, refine your handoff quality; do not loosen the rules.

brigade/templates/memory/cards/memory-architecture.md

@@ -0,0 +1,56 @@
+---
+topic: memory-architecture
+category: foundation
+tags: [memory, bootstrap, handoff, canonical-owner]
+---
+
+# Memory Architecture
+
+This workspace uses a single canonical memory owner. Side harnesses may keep local session context, but durable knowledge flows back through Memory Handoffs and is routed into the canonical store.
+
+## Layout
+
+```text
+./
+  AGENTS.md            # operating rules + memory contract
+  MEMORY.md            # slim index pointing to cards
+  TOOLS.md             # operational runbook (appendable target)
+  USER.md              # stable user preferences (appendable target)
+  IDENTITY.md
+  SOUL.md
+  HEARTBEAT.md
+  SAFETY_RULES.md
+  INSTALL_FOR_AGENTS.md
+  memory/
+    cards/             # durable knowledge cards (auto-promotion target)
+      decay/           # optional staleness scan output + refresh queue
+    handoff-inbox/     # ambiguous handoffs land here for review
+  rules/               # workflow rules (appendable target)
+  .learnings/          # concrete failures + lessons (appendable target)
+  .claude/
+    memory-handoffs/
+      TEMPLATE.md
+      processed/       # archive of ingested handoffs
+```
+
+## Why one owner
+
+Two canonical memory systems is one too many. Either both have to be reconciled on every read, or one drifts silently and contradicts the other. Pick one owner. Everything else writes to it through handoffs.
+
+## What goes where
+
+| Kind of knowledge | Target |
+|-------------------|--------|
+| Architecture decision, durable concept, recurring pattern | `memory/cards/*.md` (frontmatter required) |
+| Command, port, endpoint, script, runbook | `TOOLS.md` |
+| Stable user preference | `USER.md` |
+| Workflow rule, recurring correction | `rules/<name>.md` |
+| Concrete failure | `.learnings/ERRORS.md` |
+| Lesson or workaround | `.learnings/LEARNINGS.md` |
+| Missing capability or enhancement request | `.learnings/FEATURE_REQUESTS.md` |
+
+## Maintenance
+
+- Keep `MEMORY.md` under ~200 lines so it stays in cache.
+- Remove stale entries after verifying the source is obsolete.
+- Consolidate duplicates. One topic, one card.

brigade/templates/memory/cards/memory-care-staleness.md

@@ -0,0 +1,58 @@
+---
+topic: memory-care-staleness
+category: foundation
+tags: [memory, staleness, decay, refresh, maintenance]
+---
+
+# Memory Care Staleness
+
+Memory needs care after it is written. Durable cards can become wrong when services move, workflows change, models are renamed, or project priorities expire. A staleness checker gives the memory owner a queue of cards that need refresh, without letting an agent rewrite sensitive or judgment-heavy knowledge blindly.
+
+## Reference Loop
+
+```text
+memory/cards/*.md
+        |
+        v
+card decay scanner
+        |
+        v
+memory/cards/decay/scan-latest.json
+memory/cards/decay/refresh-queue.json
+        |
+        v
+safe refresh agent or manual review
+```
+
+## Scanner Output
+
+Store scan state under `memory/cards/decay/`:
+
+- `scan-latest.json` - latest full scan, counts, card statuses, decay ratios, and refresh queue size.
+- `refresh-queue.json` - small queue of cards that are stale enough to review.
+
+The scanner should report at least total cards, fresh count, aging count, stale count, critical count, and refresh queue size.
+
+## Safe Refresh Rules
+
+Only auto-refresh cards when current facts are grounded in local source-of-truth files read during the run. Good sources include `TOOLS.md`, `MEMORY.md`, recent `memory/YYYY-MM-DD.md`, local project docs, local scripts, and repo health reports.
+
+Do not auto-refresh cards that require human judgment, personal context, career decisions, school work, business strategy, or outside research. Put those in a manual queue.
+
+Never refresh by only bumping an `updated:` date. The content must change because a current source proves it should change.
+
+## Suggested Schedule
+
+- Daily scanner during quiet hours.
+- Safe auto-refresh shortly after the scanner, capped to a small number of cards.
+- Weekly deep report for manual review of sensitive or repeatedly skipped stale cards.
+
+## Verification
+
+```bash
+test -f memory/cards/decay/scan-latest.json
+test -f memory/cards/decay/refresh-queue.json
+jq '.counts, .refresh_queue_size' memory/cards/decay/scan-latest.json
+```
+
+If the queue grows for several days, either the refresh agent is too conservative, the source-of-truth files are stale, or the cards need manual pruning.