switchroom 0.19.22 → 0.19.24

package/skills/dev-protocol/SKILL.md

@@ -13,51 +13,14 @@ description: >
 
 # Development Protocol — the playbook
 
-The always-loaded CLAUDE.md "Development Protocol" section is the summary.
-This skill is the long-form procedure. Work through the five phases in order;
-they are checkpoints, not vibes.
-
-## 1. Orient — ground before you build
-
-Before forming any theory or plan:
-
-- **Read the real source.** The repo's source files at the current HEAD — not
-  build artifacts (`dist/`, generated files, caches), not your memory of the
-  code, not the task description's paraphrase. If a claim matters, open the
-  file.
-- **Verify the root cause, not the first plausible cause.** Reproduce or trace
-  the failure to a specific mechanism before fixing. "This line looks wrong"
-  is a lead; the fix ships only when you can say *why* it produced the
-  observed symptom.
-- **Report contradicting evidence.** If what you find contradicts the task
-  description, the ticket, or your own working theory — say so explicitly and
-  stop to re-plan. Never force-fit evidence to the plan you already had.
-- **Cite everything.** Claims about the codebase carry `file:line`, commit
-  hashes, or PR numbers. "The scaffold appends fragments at
-  `src/agents/scaffold.ts:4113`" is a claim; "the scaffold appends fragments
-  somewhere" is not.
-
-## 2. Clarify vs proceed
-
-- **Infer first.** Most questions are answerable from the codebase, git
-  history, existing tests, or docs. Exhaust those before asking.
-- **One question at a time.** If genuinely unsure after inferring, ask the
-  single question whose answer unblocks the most work. Phrase it as a
-  decision with a default: state what you found, the 2–3 viable options, which
-  you'd pick and why, and ask for confirmation — e.g. *"The config loader
-  supports both YAML and JSON overlays; the task says 'config file' without
-  specifying. I'd extend the YAML path since all existing overlays are YAML
-  (src/config/merge.ts:88) — confirm, or should JSON be covered too?"* Never
-  send a questionnaire.
-- **Phase discipline.** Clarify during *planning*. Once the plan is agreed,
-  execute autonomously: make the reasonable call on small ambiguities, record
-  the assumption in your report, and keep moving. Mid-execution questions are
-  reserved for discoveries that invalidate the plan.
-
-## 3. Design-align on larger tasks
-
-**Classify the task first.** Treat it as "larger" (design-align before
-implementing) when ANY of these hold:
+The always-loaded CLAUDE.md "Development Protocol" section carries the
+judgement criteria. This skill carries the parts that are *this fleet's
+specific opinion* — the ones you would get wrong by defaulting to generic
+good practice, because our answer differs from the obvious one.
+
+## 1. Is this a "larger" task? (decides whether you design-align first)
+
+Treat it as larger — design report before implementing — when ANY of these hold:
 
 - It changes a public interface, schema, config shape, or on-disk format.
 - It cuts across 3+ modules or touches a load-bearing invariant.
@@ -67,65 +30,92 @@ implementing) when ANY of these hold:
   ("add flag Y").
 - It will land as more than one PR.
 
-Small, single-concern, obvious-approach changes skip straight to phase 4.
-
-For larger tasks:
-
-1. **Design report before code.** Send the user an evidence-grounded report:
-   what exists today (with citations), what will change, the chosen approach
-   and its rejected alternatives, and the PR staging plan. Get alignment
-   before implementation.
-2. **Red-team your own plan adversarially.** Review the design item by item.
-   Each item gets a verdict — `SOUND`, `RISK`, or `WRONG` — backed by
-   evidence (a file you read, a test you ran, a documented behavior), not
-   intuition. Fix every `WRONG` and address every `RISK` before starting.
-3. **Stage delivery as focused single-concern PRs.** One concern per PR:
-   reviewable in one sitting, revertable in one command. Never bundle a
-   refactor with a behavior change.
-
-## 4. Pipeline — how a change ships
-
-1. **Branch off fresh main.** `git fetch && git checkout -b <branch> origin/main`.
-2. **Implement with durable fixes.** Fix root causes. A workaround is
-   acceptable only with an explicit reason stated and a follow-up filed.
-   Prefer deterministic mechanisms (a check, a hook, a schema, a lint gate)
-   over model-dependent behavior — if code can enforce the guarantee, don't
-   leave it to prompt discipline.
-3. **Tests assert outcomes.** Every test must fail if the bug it guards
-   returns. A test that merely exercises the code path without asserting the
-   observable outcome is not a test.
-4. **Scoped tests + lint locally.** Run the test files covering what you
-   touched, plus the repo's lint gate. Local runs are a fast filter; **CI is
-   the full-suite authority** — never claim done off a local run alone.
-5. **Adversarial review of the diff.** Dispatch a reviewer (sub-agent or
-   fresh pass) with this structure:
-   - Input: the full diff, the task statement, and the design report if one
-     exists.
-   - Charge: *find reasons this change is wrong* — correctness, missed edge
-     cases, untested behavior, inconsistency with surrounding code, docs
-     drift, security/data-loss risk.
-   - Output: a findings list, each with severity (high/medium/low), the
-     evidence (`file:line`), and a concrete fix.
-6. **Fix ALL findings — including lows.** A low you skip is a bug you
-   shipped. If a finding is genuinely invalid, rebut it with evidence in
-   writing; silence is not a rebuttal.
-7. **Re-review the fix.** The re-review verdict must contain, per original
-   finding: the finding ID, what changed (`file:line` of the fix), whether it
-   fully resolves the finding (`RESOLVED` / `PARTIAL` / `REBUTTED` with
-   evidence), and whether the fix introduced anything new. A bare "fixed" is
-   not a verdict.
-8. **Merge only on CI green.** No exceptions. A red or flaky CI run is a
-   blocker to investigate, not to override.
-
-## 5. Communicate while you work
-
-- **Consolidated messages.** Batch related findings and results into one
-  substantive update; never send five fragments where one message serves.
-- **Always-visible progress.** Long-running work surfaces status the user can
-  see (progress card, interim edit, explicit "still running: X"). Never go
-  dark mid-task.
-- **No foreground watches over 30 seconds.** Anything longer — builds, CI
-  waits, deploys — runs in the background with a notification on completion.
-  Don't block a turn polling.
-- **Max 15 parallel sub-agents.** Fan out for genuinely parallel work
-  (independent reviews, independent modules), but cap the swarm at 15.
+Small, single-concern, obvious-approach changes skip straight to the pipeline.
+Design-aligning a one-liner is its own failure mode.
+
+## 2. Design report + red-team (larger tasks only)
+
+The report states what exists today **with citations**, what will change, the
+chosen approach, the alternatives you rejected and why, and the PR staging
+plan. Get alignment before implementing.
+
+Then red-team your own plan item by item. Each item gets a verdict —
+`SOUND`, `RISK`, or `WRONG` — backed by evidence you can point at (a file you
+read, a test you ran, documented behaviour), not intuition. Fix every `WRONG`
+and address every `RISK` before starting. A red-team that returns all-`SOUND`
+on a non-trivial plan is a red-team you didn't actually do.
+
+## 3. Ask one question, as a decision with a default
+
+If you're genuinely blocked after inferring from code and history, don't send
+a questionnaire. State what you found, the 2–3 viable options, which you'd
+pick and why, and ask for confirmation:
+
+> "The config loader supports both YAML and JSON overlays; the task says
+> 'config file' without specifying. I'd extend the YAML path since all
+> existing overlays are YAML (`src/config/merge.ts:88`) — confirm, or should
+> JSON be covered too?"
+
+Clarify during *planning*. Once the plan is agreed, execute autonomously:
+make the reasonable call on small ambiguities, record the assumption in your
+report, keep moving. Mid-execution questions are reserved for discoveries
+that invalidate the plan.
+
+## 4. Adversarial review — bounded on purpose
+
+Dispatch the review to a **fresh** pass or sub-agent; the coder cannot review
+its own work in-context. Structure it:
+
+- **Input:** the full diff, the task statement, and the design report if one exists.
+- **Charge:** *find reasons this change is wrong* — correctness, missed edge
+  cases, untested behaviour, inconsistency with surrounding code, docs drift,
+  security or data-loss risk.
+- **Output:** a findings list, each with a severity, the evidence (`file:line`),
+  and a concrete fix.
+
+**The severity gate — this is the fleet-specific part.** The old rule was
+"fix ALL findings including lows, then re-review". That is a loop generator by
+construction: an adversarial reviewer always surfaces lows (that is its job),
+fixing lows produces a new diff, and a new diff earned another re-review. It
+produced PRs going four rounds where the last round's only finding was an
+inaccurate doc comment. So:
+
+- **Blockers and majors block the merge.** Fix them.
+- **Lows do NOT block.** File a low as a follow-up issue rather than fixing it
+  now. Filing is mandatory — an unfiled low is a dropped bug, and there is no
+  human team to catch it later.
+- **Fix what blocks, then merge on CI green.**
+- **Do not count review rounds, and do not run a mandatory re-review pass.**
+  Verifying your own fix is part of making it, not a separate step. Counting
+  rounds was itself a loop driver: it made the review process the subject of
+  the work instead of the change.
+
+If a finding is genuinely invalid, rebut it with evidence in writing; silence
+is not a rebuttal.
+
+## 5. Non-obvious pipeline rules
+
+- **CI is the full-suite authority.** Local scoped tests are a fast filter,
+  never the merge evidence. Never claim done off a local run alone.
+- **`main` is behind a merge queue: `gh pr merge` ENQUEUES, it does not
+  merge.** The command exits 0 and the PR stays `OPEN`. The queue then re-runs
+  all seven required contexts on its own `gh-readonly-queue/main/pr-<n>-<sha>`
+  ref before landing anything, so "green on the PR" is necessary but not
+  sufficient. Never report a PR merged off that exit code — poll until its
+  state is `MERGED` and the commit is an ancestor of `origin/main`. Two flags
+  to know: `--delete-branch` is **rejected outright** while the queue is on
+  (delete the branch after it lands), and `--subject` is ignored, since the
+  queue composes the merge commit from the PR title plus `(#<pr>)` — so the PR
+  title is the commit title, write it accordingly. An entry stuck in
+  `AWAITING_CHECKS` means a required workflow is not listening for
+  `merge_group`; `.github/MERGE-QUEUE.md` owns that failure mode and the
+  invariants that prevent it.
+- **A test that wouldn't fail on the bug it guards is not a test.** Assert the
+  observable outcome, not that the code path executed.
+- **Prefer a deterministic mechanism over prompt discipline.** If a check, a
+  hook, a schema, or a lint gate can enforce the guarantee, write that instead
+  of a convention — conventions demonstrably fail here.
+- **Never go dark, and never foreground-watch over 30 seconds.** Builds, CI
+  waits, and deploys run in the background with a notification. Batch related
+  findings into one substantive update rather than five fragments. Cap
+  parallel sub-agents at 15.

package/skills/switchroom-release/SKILL.md

@@ -100,7 +100,8 @@ The tag push triggers `docker-images` and `release`. `release` internally waits
 
 ### Gate B — the release pipeline (`release.yml`)
 - `gh run list --workflow=release.yml --limit 1` — wait for `completed` / `success`. Expect ~25-30 minutes: four native build legs plus the wait on `docker-images`.
-- Its jobs, in order: `guard` (release exists + held out of `latest`) → `build` ×4 → `bundle` → `publish` (attach) → `images-gate` (wait on docker-images) → `npm` → `finalize` (un-draft). A red job anywhere leaves the release a **draft** and npm **unpublished** — which is the correct, recoverable state.
+- Its jobs, in order: `guard` (release exists + held out of `latest`) → `build` ×4 → `bundle` → `publish` (attach) → `images-gate` (wait on docker-images) → `npm` → `finalize` (un-draft) → `images-latest` (promote `:vX.Y.Z` → `:latest`). A red job anywhere leaves the release a **draft** and npm **unpublished** — which is the correct, recoverable state.
+- `images-latest` is why a tag push no longer moves the `:latest` image tag by itself (#3685). If that last job is the one that failed, every other leg shipped and only the image tag lags: re-run it with `gh workflow run promote.yml -f from=vX.Y.Z -f to=latest`. Don't roll the fleet off `:latest` until it is green — `docker manifest inspect ghcr.io/switchroom/switchroom-agent:latest` should report the same digest as `:vX.Y.Z`.
 - Verify the release page actually has assets **and is no longer a draft**:
   ```bash
   gh release view vX.Y.Z -R switchroom/switchroom --json isDraft,assets \

package/telegram-plugin/bunfig.toml

@@ -0,0 +1,10 @@
+# bun test configuration for runs whose CWD is telegram-plugin/ — CI's
+# `bun-test-run` job (scripts/bun-test-ci.sh) and `bun run --cwd telegram-plugin`.
+#
+# bun reads the bunfig.toml in its CWD only, so this file exists purely to load
+# the same state-dir hermeticity preload as the repo-root bunfig.toml. Keep the
+# two in sync; `npm run lint:agent-state-dir-hermeticity` fails if either stops
+# loading the guard. Rationale for the guard itself lives in
+# tests/vitest-setup/agent-state-dir-guard.mjs.
+[test]
+preload = ["../tests/vitest-setup/agent-state-dir-guard.mjs"]