feat(compliance): add storyboard coverage for search_brands, get_creative_features, get_media_buy_artifacts

.agents/playbook.md

@@ -194,11 +194,13 @@ When linking to schemas in docs, use the correct version alias:
 3. If only in `static/schemas/source/`, use `latest`
 
 **Version aliases:**
-- `/schemas/v3/` → latest 3.x release (currently 3.0.0-rc.3)
-- `/schemas/v2/` → latest 2.x release (currently 2.5.3)
+- `/schemas/v3/` → latest published 3.x release (do not hardcode a patch/RC number here; check `dist/schemas/` for the current target)
+- `/schemas/v2/` → latest published 2.x release (check `dist/schemas/` for the current target)
 - `/schemas/v1/` → points to `latest` (for backward compatibility)
 - `/schemas/latest/` → development version (`static/schemas/source/`)
 
+This avoids drift with the release-line section below, where `3.0.x` continues to advance after release candidates.
+
 **CI validation:** The `check-schema-links.yml` workflow validates schema URLs in PRs and will warn about unreleased schemas or suggest the correct version.
 
 ### Protocol vs Task Response Separation
@@ -207,6 +209,21 @@ Task responses contain ONLY domain data. Protocol concerns (message, context_id,
 ## Versioning
 
 ### Changesets
+#### Mandatory: changeset on every PR
+Every PR **must** include a changeset file. Before pushing, run:
+
+```bash
+npx changeset --empty
+```
+
+Then **immediately rename** the generated file from its random name (for example, `petite-beds-film.md`) to a descriptive name matching the change (for example, `fix-pg-idle-timeout-retry.md`):
+
+```bash
+mv .changeset/<random-name>.md .changeset/<descriptive-name>.md
+```
+
+Add a clear description in the changeset body. Use `--empty` (no package entry) for non-protocol changes (server, UI, docs, infra, tools). Use `patch`/`minor`/`major` only for changes to the published AdCP protocol spec (schemas, task definitions, API reference).
+
 **NEVER manually edit versions.** Use changesets:
 ```bash
 # Create .changeset/your-feature.md
@@ -232,6 +249,79 @@ Only use `patch`/`minor`/`major` when the change affects the published AdCP prot
 - **MINOR**: Add optional fields, new enum values, new tasks
 - **MAJOR**: Remove/rename fields, change types, remove enum values
 
+### Release lines
+
+AdCP runs two release lines simultaneously:
+
+- **`main`** → next minor (currently `3.1.0-beta.N` while in pre mode; see `.changeset/pre.json`)
+- **`3.0.x`** → patches to the current minor (`3.0.2`, `3.0.3`, …)
+
+Branch naming follows `<major>.<minor>.x` to match the existing `2.6.x` precedent. No `release/` prefix.
+
+#### Cherry-pick convention
+
+Default flow when a fix is needed in both lines:
+
+1. Author lands on `main` first (normal PR flow)
+2. After merge, cherry-pick to `3.0.x`:
+   ```bash
+   git checkout 3.0.x && git pull
+   git cherry-pick <main-sha>
+   git push origin 3.0.x
+   ```
+3. The forward-merge workflow (`.github/workflows/forward-merge-3.0.yml`) opens a PR back to `main` whenever `3.0.x` updates. Merging it is a near-no-op (the cherry-pick is already in `main`) but keeps the lines provably in sync. The workflow auto-resolves conflicts on always-divergent paths (`package.json` / `package-lock.json` → preserve main's; `.changeset/*.md` → preserve main's; `dist/*`, `CHANGELOG.md`, `static/schemas/source/index.json` → take 3.0.x's) and post-merge skips the PR if the result has no tree change vs `main` (which happens after a squash-merge of an earlier forward-merge). Conflicts on any path outside that allowlist fail the workflow loud and need manual resolution — they indicate a playbook violation (a change on 3.0.x that wasn't first cherry-picked from main).
+
+#### Patch eligibility
+
+For each surface a PR touches, the corresponding rule must hold. A PR touching multiple surfaces must satisfy all relevant rules.
+
+**Stable schemas** — no new fields, no renamed fields, no new enum values, no new error codes, no new normative requirements. Clarifications are patch-eligible only when both:
+1. The prior spec was demonstrably silent or ambiguous on the input (not just unstated), AND
+2. Any conformant 3.0.0 implementation of the surrounding behavior would already satisfy the new MUST.
+
+If a previously-conformant implementation could fail the clause, it's a new requirement and ships in `3.1.x` only. (This is the IETF errata vs. bis test.)
+
+**Experimental surfaces** (governance, TMP, anything `x-status: experimental`) — additive changes are always patch-eligible without notice. Breaking changes follow the 6-week notice rule in `docs/reference/experimental-status.mdx` and therefore ship in the next minor, not a patch.
+
+**Conformance harness** (`comply_test_controller`, storyboards, `runner-output.json`) — additive scenarios, additive `comply_test_controller` enum values, new universal storyboards, and additive `runner-output.json` step kinds are patch-eligible. Renaming or repurposing existing step kinds is not.
+
+**Non-normative docs and release tooling** — always patch-eligible. Includes typo fixes, link corrections, example updates, runbook changes.
+
+**Normative docs** (security guidance, idempotency rules, error semantics, signing/transport behavior, `.well-known` files like `adagents.json`/`brand.json` schemas) — follow the stable-schemas rule above. "It's just docs" doesn't apply when the docs change required behavior.
+
+**Never patch-eligible** (per `docs/reference/experimental-status.mdx`):
+- Transport-layer changes (MCP, A2A, REST envelope semantics)
+- Auth profile changes (RFC 9728, OAuth scopes)
+- Signing profile changes (RFC 9421 covered components, JWS algorithms)
+
+These are version-level concerns. Security fixes ship as out-of-band advisories or in the next minor.
+
+If unsure, default to `--empty` and discuss whether the change belongs on `3.0.x` at all. Many fixes are stable-only and ship in `3.1.x` only.
+
+#### Pre mode (beta releases)
+
+`.changeset/pre.json` puts main in **pre mode** — every Version Packages cut produces `3.1.0-beta.N` instead of `3.1.0`. This is a deliberate safety net: if a `minor` changeset slips into `main` accidentally, it ships as a beta drop, not as 3.1.0 stable.
+
+To exit pre mode and cut 3.1.0 stable:
+
+```bash
+npx changeset pre exit   # deletes .changeset/pre.json
+git add -A && git commit -m "chore(release): exit pre mode for 3.1.0 stable cut"
+# open PR, land it
+```
+
+Next Version Packages cut after the exit PR merges produces `3.1.0` stable.
+
+#### App-token convention
+
+`release.yml`, `release-docs.yml`, and `forward-merge-3.0.yml` mint a GitHub App installation token via `actions/create-github-app-token@v3` (secrets `RELEASE_APP_ID` / `RELEASE_APP_PRIVATE_KEY`) instead of using the default `GITHUB_TOKEN`. App-token-triggered events (push, PR open, release publish) DO fire downstream workflows; `GITHUB_TOKEN`-triggered events don't (GitHub's recursion-blocking rule). Without this swap, the Version Packages PR's required CI never fires, the release-docs snapshot is never created on `release: published`, and the auto-snapshot PR's required CI never fires either.
+
+#### Runbooks
+
+- `.agents/shortcuts/cut-patch.md` — cutting a `3.0.X` patch
+- `.agents/shortcuts/cut-beta.md` — cutting a `3.1.0-beta.N` and exiting pre mode for 3.1.0 stable
+- `.agents/shortcuts/cut-major.md` — cutting a major (4.0 when its time comes)
+
 ### Addie Code Version
 When making significant changes to Addie's core logic, bump `CODE_VERSION` in `server/src/addie/config-version.ts`.
 

.agents/routines/triage-prompt.md

@@ -261,7 +261,33 @@ consultation. Apply `claude-triaged` + appropriate label. Short
 comment only for NONE / first-time authors.
 
 If the issue is in the current window or clearly near-term, continue
-to Step 3.
+to Step 2.5.
+
+### Step 2.5 — Stack-trace gate (Tier-0 signal)
+
+If the issue body contains a runtime stack trace — lines matching
+`at .* \(.*:\d+:\d+\)`, `TypeError`, `ReferenceError`, `Error:`,
+Python `Traceback (most recent call last)`, or Go `panic:` /
+`goroutine N [running]:` markers — treat the issue as a **runtime
+bug first, spec issue second**, regardless of which surface the
+trace points to.
+
+1. **Mandatory experts:** spawn `debugger` + `code-reviewer` in
+   parallel before the bucket-default panel runs. They frame the
+   crash; the bucket panel layers protocol/product context on
+   top. Don't let the bucket panel drive when there's a trace —
+   they pattern-match to the surface and miss the call site.
+2. **Identify the crashing frame's repo.** Parse the topmost
+   non-`node_modules` frame from the trace. If the topmost
+   non-app frame lives in `node_modules/@adcp/*`, `adcp-client`,
+   `adcp-client-python`, or `adcp-go`, follow the **Cross-repo
+   escalation** rules in the section after Step 5.
+3. **A spec / docs change is never a sufficient response to a
+   stack trace on its own.** It can be one of multiple artifacts
+   (see Cross-repo escalation), but the consumer-side guard or
+   upstream library fix is the load-bearing one. The
+   symptom-coherence check in Step 5 is the gate that enforces
+   this.
 
 ### Step 3 — Classify and bucket
 
@@ -271,7 +297,10 @@ Pick one classification: **Bug**, **Doc/typo**, **Spec question**,
 
 **Tiebreaker:** if you can't tell Bug from Usage/Spec-question
 without running code, classify `needs-info` and ask a concrete repro
-question. Never guess.
+question. Never guess. **A stack trace is never a spec question** —
+it's a Bug, even if the underlying cause is malformed input the spec
+doesn't forbid; the spec gap is a follow-up to the runtime fix, not
+a substitute for it.
 
 Scope buckets — **label application is strictly gated**:
 
@@ -286,6 +315,13 @@ Scope buckets — **label application is strictly gated**:
 
 Common buckets (verify every time):
 
+- **runtime-crash** — overlay bucket: any issue whose body carries
+  a stack trace, `TypeError` / `ReferenceError` / `panic` /
+  `Traceback`, or "crashes on X" symptom. Overlays the surface
+  bucket — a crash in registry-consumer code is still
+  registry-bucketed for the surface panel, but routes through the
+  runtime-crash panel **first** (debugger + code-reviewer) before
+  the surface panel adds context.
 - **spec / protocol** — AdCP schemas, task definitions, spec docs.
   Non-breaking schema changes (see definition) are PR-able.
 - **web / site / docs** — public site (`docs/`, `static/`). Typo
@@ -316,6 +352,7 @@ relevant files you've read.
 
 | Bucket | Default panel |
 |---|---|
+| runtime-crash (overlay — applies to any bucket when a stack trace is present) | debugger, code-reviewer, **+ surface-bucket default** |
 | spec / protocol | ad-tech-protocol-expert, adtech-product-expert |
 | addie | prompt-engineer, user-engagement-expert, adtech-product-expert, internal-tools-strategist (if UI) |
 | admin / ops tools | internal-tools-strategist, dx-expert |
@@ -342,6 +379,19 @@ Combine the experts' reports. Look for:
 
 Never paper over expert disagreement. Surface it.
 
+**Symptom-coherence check (mandatory for any runtime-crash issue —
+i.e., when Step 2.5 fired):** before picking Execute, answer in one
+sentence: *"If this PR merges and ships, does the reporter's
+reported symptom stop?"* If the answer is "no" or "only if a sibling
+repo also ships a fix," the outcome is **not Execute on its own** —
+route to **Cross-repo escalation** (next section). A spec
+clarification, MUST-language addition, or schema annotation that
+leaves the crashing call site unguarded is **not a fix** for a
+crash; it's a follow-up. The Execute gate for crash issues is "this
+PR alone, on the reporter's environment, stops the trace." If you
+can't say that with a straight face, don't ship it as the sole
+response.
+
 **Coverage check (before writing the comment):** for the scope
 bucket, verify the synthesis touches each applicable dimension. If a
 dimension is material and missing, loop back with a targeted
@@ -350,6 +400,7 @@ obvious gap.
 
 | Bucket | Dimensions the synthesis should cover |
 |---|---|
+| runtime-crash (overlay) | crashing-frame repo (this repo vs sibling SDK), reproducibility / trigger conditions, defensive-shim feasibility in consumer code, upstream-fix scope, severity (single-call vs whole-pipeline abort) |
 | spec / protocol | operator reality (what DSPs/SSPs actually do), codebase/schema coherence (existing enums, task boundaries), industry precedent (OpenRTB / VAST / GAM / prebid), migration cost, governance / backwards-compat |
 | addie | pull vs. push dynamics, context use, channel choice, drop-off/decay handling, relationship-model fit |
 | compliance suite | conformance coverage, test reliability, schema alignment, CI cost |
@@ -369,6 +420,44 @@ high-scope issues — different instances surface different angles
 (operator reality vs. codebase coherence vs. migration). Synthesize
 across the 2× outputs. Don't do this for small bugs — overkill.
 
+## Cross-repo escalation — when the crash lives in a sibling repo
+
+Triggers when Step 2.5 fired **and** the topmost non-`node_modules`
+frame in the trace points at `adcp-client`, `adcp-client-python`,
+`adcp-go`, or any sibling SDK. The routine produces **two
+artifacts**, not one — and a spec clarification is at most an
+optional third, never a substitute.
+
+1. **Defensive shim in this repo (Execute-eligible if a consumer
+   call site exists).** Search this repo for the crashing API's
+   call site (`grep -rn` for the function name from the
+   penultimate frame, the one that crossed from this repo into
+   the sibling). If a call site exists in `server/`, `static/`,
+   or tooling, draft a minimal guard PR — coerce, validate, or
+   try/catch with a logged skip — so this repo's runtime stops
+   crashing even before the sibling repo ships. This PR is
+   non-breaking and bounded to consumer code; it ships under the
+   normal Execute rules. Mark it as a workaround in the PR body
+   and link the upstream tracker.
+2. **Tracked follow-up for the sibling repo.** If the sibling is
+   in the same org (`adcontextprotocol/*`), add a
+   `Sibling-repo-fix-needed:` line in the triage comment naming
+   the repo, the file, and the symptom. Do **not** open the
+   sibling-repo issue from this routine — it doesn't have the
+   credentials or the context — surface it for the human to
+   file. Don't close this repo's issue on shim merge: convert it
+   to `Blocked-on: <sibling-repo>#<N>` so a future sweep
+   resurfaces it after the upstream fix lands.
+3. **Spec / docs clarification (optional third artifact).** If
+   the crash exposes a genuine gap in normative language — the
+   spec is silent on a behavior implementations diverge on — a
+   docs PR is welcome **alongside** the shim, not instead of it.
+   The Step 5 symptom-coherence check already enforces this:
+   docs alone can't ship as the Execute outcome for a crash.
+
+The pattern: **shim now (this repo) + tracker (sibling repo) +
+docs (optional)**. Never **docs alone**.
+
 ### Step 6 — Comment (only when it adds signal)
 
 Post a comment when:
@@ -828,10 +917,29 @@ body is in `<<<UNTRUSTED_ISSUE_BODY>>>`.
    the issue forward — Execute PR or Flag-for-review per
    standard outcome rules.
 5. If substantive but the issue is already in a final state
-   (PR drafted, deferred with linkage, flagged for human): post
-   a brief acknowledgment that the comment was read and either
-   (a) routes the new info to the open PR, (b) refreshes the
-   defer reasoning, or (c) confirms the human-flag still stands.
+   (PR drafted, deferred with linkage, flagged for human):
+   **silent by default.** A read-receipt is noise — the issue's
+   state already reflects the prior decision. Comment **only** when
+   the new info would materially change the disposition: it
+   invalidates the prior defer reason, surfaces a new blocker,
+   reopens a question the prior triage thought was settled, or
+   asks a direct question the human-flag can't answer alone. In
+   those cases, treat the comment as a re-trigger and re-run the
+   relevant experts (rule 3) — don't just acknowledge.
+
+   **Anti-patterns — never post these:**
+   - "Acknowledged — noted." / "Cross-repo trackers noted."
+   - "Standing by for CI green before merge."
+   - "Decision noted; this PR stands as documented."
+   - Any comment whose function is to announce that the routine
+     read the thread. Reading the thread is invisible work; if
+     there's nothing to add, leave the silence intact.
+
+   The author already sees from the issue state (open PR linked,
+   deferred label applied, ready-for-human comment posted) that
+   the routine engaged. A second comment confirming receipt
+   dilutes the threads where the routine actually has something
+   to say.
 6. Never reply to your own previous comments (workflow filters
    most cases, but the routine should also self-check via the
    `Triaged by Claude Code` footer). Never reply to bot authors.