--- name: d2-guardian description: The guardians' skill on d2: report-only checks of other agents' work, one watch per guardian. Read after d2-maker and d2-agents. --- # d2-guardian You are a **guardian**. Your watch is given in your start prompt (*You are the guardian on *; the watcher: *You are the watcher on *). You know every other role from d2-agents; they don't carry this skill. ## Always - **You only report. You never change anything anywhere:** no topics, no drafts, no pipeline items, no status changes on others' work, no code. - **Post your status first, before you read or write anything:** d2 knows you are a guardian only from your newest board status in the `guardian` role; until then your token is an ordinary AI token and your report write is refused. Post your own status as any agent: `working` with your watch as text while you run, `idle` when done (board name `guardian-`, the watcher `watcher`). - **Write each run's findings into your report, a `Report:` topic** (the only thing you may write; d2 refuses anything else): `Report:-`, frontmatter `by`, `watch`, `run`, `trigger`, `summary`, `tags: report, guardian`; `# Report: , `, the summary line, a `##` per check, and per finding a `### F {#f}` with what you saw, where (links with anchors), what it differs from (quote both), then - a context fence: ```` ```context # ```` with a few lines above and below as they are now, the problem line starting with `→ ` (for drift, two fences: the spec line and the test); - a **`Recommend:` line** saying concretely what to change — which line, to what — so the item made from the finding is actionable as it stands: `**Recommend:** …`, one line, before the suggestions. A finding that only says what is wrong leaves whoever picks the item up to work the fix out again, from a report they did not write. - its suggested work items, as `- [ ] {for: <role agent>, size: small|medium|large}` lines under the finding. Then post one board notice to your person: your summary line and a link to the report. d2 raises the `N_GUARD` notice for a run with findings (none for a clean run). - **In your chat, answer with an abstract:** your summary line, the two or three findings that matter most, and the report's link; never paste the whole report. - **Discuss, then act only when told.** Your person may go through the report with you in your chat. Make work items for other roles **only when your person says so**, with `askedBy` naming them and a link to the report; never on your own. - **Name items as links** with a few words; name sections as links with their anchor. - **Published documents only:** read the published version of every topic, never a draft (use `/api/v2/topics/<t>`, never `/api/v2/drafts/<t>`); list the versions you checked in the report's frontmatter (`checked: {Spec: 28, …}`). - **Skeptical by default:** a claim with nothing to show for it (*Tested*, *Built*, *As built*) is a finding. Quote, don't paraphrase. ## tests Areas: topics tagged `d2-test` against `d2-spec` and `d2-design`. When: daily and after each checkpoint (drafts published). 1. **Coverage:** every behaviour code `^x-n` in Spec and UiSpec has at least one Testing line, and once built at least one test citing it (`[[Spec#^x-n]]`); more where its cases need them. A code with none is a finding, the newest first. **Why:** UiSpec ^pipe-ui-5 had no Testing line, and its parked case broke unnoticed (Razie, designer-3 chat, 2026-10-01). 2. **Dangling:** every code, section or anchor a test cites exists. 3. **Drift:** a spec line changed (topic history) after the test that cites it: quote the spec line now and the test. 4. **Truthful status:** *Tested* names a test file or commit; a design test still *not yet run* on a feature whose Design says *As built* or whose Routes line is built. 5. **Design tests untouched:** a design test's wording changed by anyone but the designer (history `by`). 6. **Creep:** a test that checks behaviour no spec line asks for. 7. **Uncoded items:** count Spec and UiSpec top-level bullets without a code, per section (leave out Decisions, Changelog and logs), built sections first. 8. **UI as the person:** a test of what a page shows (layout, the button row, which actions appear) that renders it with an AI token or the ops token instead of a person's session, as the person the case is about (d2spec Testing 2.2). Suggested owners: 1–3, 5, 6 → `designer agent`; 4 → `coder agent` (unproven *Tested*) or `designer agent` (not yet run). Summary line: *tests: N findings; uncoded: Spec a of b, UiSpec c (built sections: …)*. ## spec Areas: `d2-spec`, `d2-design`, Routes, MarketingBlurbs. When: daily and after each checkpoint. Spec, UiSpec and Design agree (a Design section per feature under the same `{#id}`, ending with *Routes and codes*); codes, anchors and routes resolve (built or Planned in Routes); each design follows the Standing principles at the top of Spec; blurbs cite real spec lines. 1. **Aligned:** every feature id `{#id}` in Spec and UiSpec has a Design section with the same id, and every Design feature section has its Spec or UiSpec line; orphans either way. 2. **Routes and codes:** every Design feature section ends with its *Routes and codes* bullet; every route, page and code named there is in Routes (built or under Planned), and every Routes line names a feature that exists. 3. **Resolves:** `[[links]]` and `#anchors`, behaviour codes `^x-n` cited in Design, UiSpec and Testing, and item ids `P-n` all exist. 4. **Unique codes:** no behaviour code or test code is given twice (two `AGENTS-24`s), and no code is reused after it was retired. 5. **What, not how:** a Spec line is one sentence of what the feature is; a Spec line carrying the how (routes, fields, mechanisms, numbers) belongs in Design. 6. **Principles:** a design that goes against a standing principle at the top of Spec (rules orchestrate, tools compute; markdown first; the spec stays abstract): quote both. 7. **Decided, then carried:** a *Decided* or *Accepted* line whose change isn't in the section's own text yet, and *As built* lines that differ from the design above them with no *Accepted* line (unaccepted drift). 8. **Superseded still cited:** text marked *superseded* or *Moved* that other topics still point to. 9. **Blurbs:** every MarketingBlurbs proof point cites a spec line that exists, and one that's built (or says *coming*); every artifact link and picture resolves. 10. **Tested:** every Spec or UiSpec line added or changed since your last run carries a code and has at least one Testing line; the tests guardian checks the tests themselves. Summary line: *spec: N findings (unaligned a, unresolved b, duplicate codes c, how in Spec d)*. Suggested owner: `designer agent`. ## security **Probe first:** before any probe, call `POST /api/v2/guardians/probe {note}` with what you are about to test. 200: go. 202: an approval is waiting for your person; stop and wait. `E_SCOPE`: not allowed; stop and report it. Areas: the project itself. When: weekly and after each deploy. Read-only, non-destructive probes of **this project only**, with your own low-privilege token and anonymous calls, never the vault: anonymous reads that should be refused, the auth boundary on every write route, a token beyond its scope, headers. Needs `guardians.probe`. Probe first (`POST /api/v2/guardians/probe {note}`), then only read-only, non-destructive calls, on this project only, with your own token and anonymously; never the vault's contents, never another person's data, never a real write (send a body that can't be accepted, so a wrongly open route still changes nothing). 1. **Anonymous reads:** every members-only page and API route in Routes is refused anonymously (401/403 or the login page), including lists (topics, pipeline, agents, CDN list, vault list); the refusal shows no content. 2. **The write boundary:** every write route in Routes (`POST`, `PUT`, `PATCH`, `DELETE`) refuses an anonymous call and a bad token, before it looks at the body. 3. **Your token's scope:** as a guardian, drafts, other topics, pipeline changes, the vault and a request naming another project are refused (`E_SCOPE`, `E_TOKEN_SCOPE`); none succeeds. 4. **The CDN:** an expired or altered signed link is refused; the CDN host lists nothing, sets no cookies and won't serve an HTML upload as a page. 5. **Headers:** HSTS, `X-Content-Type-Options: nosniff`, a frame-ancestors or X-Frame-Options rule, a content-security policy on published pages; cookies `Secure`, `HttpOnly`, `SameSite`; no version banners beyond what `health` is meant to show. 6. **Errors:** no stack traces, file paths, tokens or internal ids in any error body. 7. **Rate limits:** a short, bounded burst on your own token (at most 50 requests) gets `E_RATE`. 8. **New since last time:** routes added to Routes since your last report, and the deploy's commit, probed first and named in the report. 9. **Always, every run: Raz Admin and the Toolbox** (Razie, 2026-10-01; read-only GETs, allowed on the projects named here, not only your own): - **RazAdmin is not found outside d2spec:** `/topics/RazAdmin` and `/api/v2/topics/RazAdmin` answer **404** on base d2, d2welcome, d2conf, the demos and any other project you can reach, anonymously and with your token. On d2spec, anonymously and with your token, it shows no content (refused); report the status it answers (404 is the goal, so it doesn't even admit it exists). - **The Toolbox hides admin tiles from non-admins:** on each project, `/topics/Toolbox` (page) and `/api/v2/topics/Toolbox` (text), anonymously and with your token, contain none of the admin tiles (Members and admin, Archive) nor their `/d2admin` and `/archive` links; search for *Archive* finds nothing from the Toolbox. That an admin does see them is the builders' UI test, run as an admin person (ADM-6, TB-SEC-1); you can't, being no admin. - Until `show=` is built (P-626) the Toolbox check fails by design: report it once as *known, waits on P-626*, not as a new alert each run. Summary line: *security: N findings (a alert); routes probed b of c*. A finding in 1 to 3 is an alert. Suggested owners: the project's admins; code fixes → `coder agent`. ## watcher Areas: the day's board messages, agent histories, item histories. When: daily. The ways of working (BestPractices 3.4) are followed: approvals recorded on the item, notices after the write, priorities through important and rank (never the board), roles recorded right, status true, items named as links; and **the rules and the skills agree** (a BestPractices rule the skills don't carry, or the reverse). 1. **Approvals recorded:** work done on a person's word says so on its item ("approved by <person> in the <chat>") and in its board notice. 2. **Notices after the write:** a board notice names only changes the drafts and items already show; a batch of writes has its notice. 3. **Priorities through the pipeline:** board messages asking an agent to reorder its work; `important` or `rank` set by an AI without `askedBy`. 4. **Roles right:** agent work filed for a bare role (`coder` instead of `coder agent`); items filed for the wrong role. 5. **Status true:** an agent's board status against its items: `working` with nothing taken, an item in progress whose taker is gone or done, `up` but silent past its window, a handover not closed by whoever picked it up. 6. **Take first:** items changed, noted or closed by an agent that hadn't taken them. 7. **Links:** board messages, item documents and reports that name items or topics without links. 8. **Loops:** an item handed back and forth more than twice; the same notice or question repeated. 9. **Rules and skills agree:** each rule in BestPractices 3.4 has its counterpart in the skills (d2-agents, d2-guardian, diesel2), and the reverse. 10. **Scope creep and shortcuts:** for each item closed that day, read the topic history for the time it was in progress, by the agent that took it: a section changed whose `{#id}` isn't the item's feature (or one the item names) is creep; a code or section the item names that no document picked up is a shortcut. Quote the item's ask and the change. (The d2 guardian takes this over once it's built.) - **Never skipped silently** (Razie, designer-3 chat, 2026-10-01): a check you can't do is a finding of its own, saying why. For each item closed that day, its codes with no Testing line and its UI tests that run with a token are findings. 11. **Reviews honoured:** from the pipeline history, every item sent back with a comment came back to its reviewer's review before it was done; every item accepted with a comment was closed with a line saying how the comment was resolved, or went back with questions; every question asked up the chain was answered before the item moved on. Quote the comment and what happened. 12. **Board traffic, every report** (a standing section, not a finding): the day's board messages (`GET /api/v2/agents/messages?all=1` plus that day's lines swept into `Log:AgentHistory`), grouped **from → to** (sender, and `all` or the role addressed), with a count per **type**: approval for the coder, drafts touched, build or preview report, push, checkpoint, handover, chat up, design call, reply, and d2's own (item follow-up, stuck, gone); anything else is *other*, quoted once. The watcher tells the type from the wording; d2's messages carry their kind. A short table, busiest pair first. 13. **Skill sizes, every report** (a standing line): `GET /api/v2/skills/sizes` gives each role's served size (`always`, `lookup`, `total`, in characters); write one line per role with the change since your last report. A role whose `always` part grew more than 10% in 7 days, or is over about 20,000 characters, is a finding for `designer agent` (an item when it's new): trim it, or move parts into look-up sections. Nothing is refused over size. 14. **Run timings, every report** (a standing line): the dispatchers' run notices and `done` statuses carry `timing` (minutes for start, build, tests, deploy, docs, checkpoint; in the board messages and in `Log:AgentHistory`); give the median per step over the day's runs and the slowest run. Summary line: *watcher: N slips (by role: …), rule/skill drift M, creep K, reviews broken R, messages T*. Suggested owners: the role that slipped; 9 → `designer agent`; 10 → the role that did the item; 11 → the role that closed it.