skilldrop-cli 0.16.28 → 0.16.30

package/packs/ai-engineering/skills/mcp-pairing/evals/files/5/docs/oncall-triage.md

@@ -0,0 +1,18 @@
+# On-call triage loop (draft)
+
+Trigger: a Sentry alert fires for `payments-api` or a Grafana alert pages the on-call.
+
+1. **Gather** - pull the Sentry issue (stack trace, release, affected users count) and the
+   Grafana dashboard panels for latency / error rate around the alert window.
+2. **Correlate** - find the GitLab merge requests and deploys that landed in the 24h before
+   the first event. Look at the diff of the suspect MR.
+3. **Check data** - if the error looks data-related, run a couple of SELECTs against the
+   `payments` Postgres database to see whether bad rows exist.
+4. **Ticket** - open a Linear issue in the `PAY` team with the findings, priority Urgent, and
+   assign it to the on-call.
+5. **Postmortem draft** - write a first-draft postmortem in markdown from everything above,
+   for the on-call to edit.
+
+Constraints: Sentry is self-hosted at sentry.internal.example. Grafana is Grafana Cloud.
+Payments DB has a primary and one read replica. We're PCI-scoped, so card data columns exist
+in `payments.transactions` (pan_last4, card_token, billing_address).

package/packs/ai-engineering/skills/mcp-pairing/examples/build-loop-github-jira-datadog.md

@@ -0,0 +1,69 @@
+# Worked example — the build loop on GitHub, Jira and Datadog
+
+## Input given to the skill
+
+> We're adopting the build loop for the `orders-api` repo. We use GitHub for code and PRs,
+> Jira (project ORD) for stories and bugs, and Datadog for logs and APM. Which MCP servers
+> should we connect, and with what access? We'd like the agent to open the PR itself if that's
+> sensible. About one bug a week needs logs; stories come in daily. Outside contractors open
+> PRs too.
+
+---
+
+# MCP pairing — build loop for `orders-api`
+
+**Tools in use:** GitHub, Jira (project ORD), Datadog · **Assumptions:** the developer's
+checkout is local, so implement needs no repo server `[assumption]`; Jira issues in ORD are
+written by staff and by people raising bugs from support `[assumption]`.
+
+## The plan
+
+Connect two servers, both read-only: Jira for the shape stage and GitHub for the verify stage.
+Implement and decide need none. Datadog is cut: one bug a week is a saved log query, not a live
+server. Opening the PR is the one write worth granting, on its own GitHub credential used only
+at the end of implement, and only if the team wants it; otherwise the developer opens the PR.
+
+## Pairing by stage
+
+| Stage (type, cadence) | Needs | Server | Grant | Must not | Fallback without it | Risk |
+|---|---|---|---|---|---|---|
+| shape (generate, daily) | Tracker issue: the story or bug, its comments and links | Atlassian's own server — confirm Atlassian publishes it in Atlassian's docs before connecting | A Jira account with Browse on project ORD only; the server acts with that account's permissions | Create, transition, comment, assign, edit fields; see any project but ORD | The issue exported from Jira to a text file, or the filter exported as CSV | Issue text and comments are untrusted (support-raised bugs). Shape holds no write or exec tool, so reading them is safe here; it writes the story file and nothing else |
+| shape, bugs only (generate, ~weekly) | Logs and traces for the failing request | Cut — see below | — | — | The Datadog log query result saved as JSON, and the trace's spans exported, for the bug's time window | Log lines carry request fields an attacker writes; a file a person picked keeps that bounded |
+| implement (generate, per story) | None — works from the story file shape wrote and the local checkout | None | — | — | — | Implement runs tests (exec) and edits files (write), so it gets **no** tracker or GitHub server: live issue text next to a shell is the dangerous combination. A person skims the story file before implement starts |
+| implement → open PR (generate, per story, optional) | Action: open a draft PR from the pushed branch | GitHub's own server, write configuration — confirm GitHub publishes it (GitHub's own organization, docs on GitHub's domain) | A separate fine-grained token, `orders-api` only: Pull requests read and write, Contents read and write; branch protection on `main` requires review | Merge, approve, push to `main`, change settings or branch protection, touch other repositories | The developer runs the push and opens the PR by hand | Write and exec in one stage, so this stage reads nothing untrusted: no issue comments, no PR comments |
+| verify (verify, per PR) | Repo: the PR diff, description, CI status | GitHub's own server in its read-only mode, limited to the repositories, pull requests and Actions toolsets | A separate fine-grained token, `orders-api` only: Contents read, Pull requests read, Actions read | Merge, approve, comment, request changes, label, re-run CI | The diff saved as a `.diff` file and the PR description copied to a file; the CI summary saved | Contractor PRs and comments are untrusted, and the gate script is exec. Allow only the gate script command in this session; the verdict goes to a person, never posted by the agent |
+| decide (gate, per PR) | None — reads verify's verdict and any design disagreement | None | — | — | — | The merge stays a person's action in GitHub's own UI under their own login |
+
+## Credentials
+
+| Variable | Server | Scope | Used by stages | Kind |
+|---|---|---|---|---|
+| None — OAuth sign-in, no stored token | Atlassian | Browse, project ORD | shape | Read |
+| `GH_ORDERS_READ` | GitHub | Contents, Pull requests, Actions: read; `orders-api` | verify | Read |
+| `GH_ORDERS_PR_WRITE` | GitHub | Pull requests and Contents: read and write; `orders-api` | implement → open PR (optional) | Write, separate token |
+
+Tokens live in environment variables or the client's secret store. The project's committed MCP
+config holds variable names only. The write server is a separate server entry, enabled only in
+the session that opens the PR, so the verify session never loads it.
+
+## Servers cut
+
+- **Datadog** — needed for about one bug a week. A saved log query and exported trace cover it,
+  with no standing token to the team's logs and no live attacker-written log lines in context.
+  Revisit if bugs needing logs reach several a week.
+
+## Check before installing
+
+- **Atlassian's own server** — confirm publisher; it acts with the account's own permissions,
+  so the account must have nothing beyond Browse on ORD.
+- **GitHub's own server** — confirm publisher, use its read-only mode for verify, and turn off
+  every toolset verify doesn't use.
+
+## To confirm
+
+- Whether the team wants the agent to open PRs at all; if not, drop `GH_ORDERS_PR_WRITE`.
+- That branch protection on `main` requires an approving review, so even the write token cannot
+  land code alone.
+
+Next step: review the finished setup for any path where issue or PR text could make the agent
+send private data out, before the first real story runs through it.

package/packs/ai-engineering/skills/mcp-pairing/manifest.json

@@ -0,0 +1,17 @@
+{
+  "name": "mcp-pairing",
+  "version": "0.1.0",
+  "description": "Recommend which MCP servers to connect for a loop, workflow or task, stage by stage, with the narrowest access that works — what outside context or action each stage needs, the server that provides it (only ones the user named or the vendor officially publishes), the scopes to grant (read-only by default, never write on a review or gate stage), what it must not be able to do, the export-file fallback that keeps the stage running without it, and which stages need no server at all. Use when the user asks \"which MCP servers should we hook up for this loop\", \"what should our agent connect to\", \"what token scopes does this stage need\", \"is this MCP setup too broad\", or wants to wire GitHub, GitLab, Jira, Linear, Slack, Sentry, Grafana or a database into an agent workflow.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["agent-loop-design", "agent-threat-model", "ai-usage-policy", "subagent-design"],
+  "handoff": [{
+    "to": "agent-threat-model",
+    "when": "the pairing still puts private data, untrusted content and any way to send data out in one session, or before the setup is connected at work",
+    "purpose": "Attack the finished capability surface path by path and break a leg on every path that can leak data.",
+    "fallback": "If agent-threat-model is absent, list each stage's session with three marks — private data, untrusted content, egress (write, network, rendered output) — and split or drop any session that holds all three."
+  }],
+  "tags": ["mcp", "least-privilege", "tool-permissions", "agentic", "prompt-injection"],
+  "model": { "tier": "standard", "rationale": "Matching a loop's stages to the context each needs and the narrowest access that provides it is bounded judgment over a short checklist." }
+}

package/packs/ai-engineering/skills/mcp-pairing/reference.md

@@ -0,0 +1,136 @@
+# mcp-pairing — reference
+
+## Stage types and their access ceiling
+
+The type sets the most a stage may ever hold. The stage's output decides whether it gets
+anything at all.
+
+| Type | What it does | Ceiling | Why |
+|---|---|---|---|
+| `generate` | Produces an artifact | Read; write **only** when the output *is* the write (a published release, a draft merge request), on its own credential | The write is the deliverable, so it is the one place a write is justified |
+| `verify` | Judges an artifact that exists | Read only | A reviewer that can approve, merge, comment or close has become an actor, and its verdict can no longer be trusted as independent |
+| `gate` | A person or script decides | Read only, and often nothing | The decision is the person's; the merge or ship button stays in the vendor's own UI under the person's own login |
+
+A stage that runs a fixed script (a gate script, a test suite) holds **exec**. Exec counts as
+write for rule 6: it must not sit beside live untrusted content unless the only command it can
+run is that fixed script.
+
+## Needs by category
+
+| Need | Typical stages | Untrusted? | Read grant | Must not | Export fallback |
+|---|---|---|---|---|---|
+| Tracker issues | shape, triage, status, gather | Yes — anyone with project access, and customers on a service desk | Issues read, one project or team | Create, transition, comment, assign, change fields | The filter exported as CSV, or the issue copied to a text file |
+| Repo / PR / merge request / diff | verify, announce, plan | Yes — PR and merge request text and comments; outside contributors' diffs | Contents and pull/merge requests read, one repository | Merge, approve, push, comment, change settings, read other repositories | The diff saved as a `.diff` file plus the description copied |
+| CI status | verify, ready | Partly — job logs echo whatever the code printed | Pipeline / Actions read, one repository | Re-run, cancel, edit secrets or variables | The pipeline summary page saved, failed job log saved |
+| Docs and wiki | plan, specify, design | Yes when many people edit it | Pages read, one space | Edit, create, change permissions | The page exported to Markdown or PDF |
+| Logs / metrics / traces | triage, ready, respond, learn | Log lines: yes (request fields are attacker-written). Metric values: no | Viewer role, one org or folder; no query of other teams' data sources | Edit dashboards or alerts, silence alerts, create API keys | The panel's data downloaded as CSV; the log query result saved as JSON |
+| Error events | triage, respond, learn | Yes — messages and breadcrumbs carry user input | Issues and events read, one project | Resolve, assign, change alert rules | The event JSON saved from the event page |
+| Design files | specify, design | Comments: yes | File read, one file or project | Edit, comment, share | Frames exported as PNG plus the spec copied |
+| Chat history | respond, status, decision capture | Yes — every member, and external guests in shared channels | History read, named channels only | Post, react, invite, read DMs or all channels | The thread exported or copied to a text file |
+| Database read | review, spec, measure | Free-text columns: yes | A read-only role on a replica, one schema, row limit | Any DDL or DML, superuser, production primary | The query result saved as CSV |
+| Cloud billing | cost review | No | Billing read for one account or profile | Change budgets, buy reservations, touch resources | The cost report exported as CSV |
+| Web | research, gather | Yes, always | Fetch only, no form submission | Hold any write or exec tool in the same session | The pages saved as files the user picked |
+
+## The vetting checks
+
+Run all five for any server that is not the vendor's own, and confirm the first three for one
+that is:
+
+1. **Publisher.** Who publishes it, and is that the vendor of the tool it talks to? A personal
+   account or an unrelated organization is a community server.
+2. **Source available.** Can the code be read? A server that ships only a binary or a remote
+   endpoint with no published source is trusted on reputation alone.
+3. **Pinned version.** A local server runs a pinned version or commit, never `@latest` or an
+   unpinned `npx` / `uvx` call; container images are pinned to a digest. Upgrades are
+   deliberate.
+4. **Tools exposed.** List the tools it registers. Any tool the stage doesn't need is turned off
+   in the server's own toolset option or the client's disabled-tools list.
+5. **Code and network reach.** Can any tool run a shell, execute code, or call a host other
+   than the vendor's API? Either one makes the server an egress path and an exec path, and
+   rule 6 applies to every stage it is enabled in.
+
+A server that fails 1 or 2 and has no official alternative gets the export-file fallback until
+someone reads its source and pins a commit.
+
+## Known vendor controls
+
+Checked 2026-10-01 from the vendors' docs. Confirm in the vendor's current docs before relying
+on any of them; vendors change these without notice.
+
+- **GitHub's own server** has a read-only mode and lets a client limit it to named toolsets
+  (for example repositories and issues). Fine-grained tokens limit to named repositories.
+- **Linear's own server** offers a read-only mode and a `read` OAuth scope; API keys can be
+  created with only the Read permission.
+- **Atlassian's own server** acts with the signed-in user's Jira and Confluence permissions.
+  Whatever that user can delete, the agent can delete; use an account with read access to the
+  one project.
+- **Supabase's own server** takes a read-only flag and a single-project scope.
+- **GitLab** personal, project and group tokens have a `read_api` scope that is read-only for
+  the API, and project tokens limit to one project.
+- **Grafana** service accounts take the Viewer role, which reads dashboards and queries data
+  sources without editing anything.
+- **Slack** workspace admins approve which clients may use MCP.
+- The archived reference Postgres server gets no security fixes. Use the database vendor's own
+  server or the export fallback.
+
+## The cut rule
+
+A server earns its place when the input is too much to paste at the stage's cadence:
+
+- too large — a 2,000-line diff, a release's 40 merge requests;
+- too structured — a cycle's 80 issues where status, owner and links matter;
+- too live — an incident timeline that changes by the minute.
+
+| Cadence | A handful of items | Dozens of items, structured or live |
+|---|---|---|
+| Per change or daily | Server, if the stage needs it every run | Server |
+| Weekly or fortnightly | Export file | Server |
+| Monthly or rarer | Export file | Export file, unless it is live |
+
+Otherwise the export file wins: no token to leak, no tool list in context, no injection path
+through a live feed. Say the cut out loud, with the reason, so nobody reconnects it next week.
+
+## Splitting a dangerous stage
+
+When one stage reads untrusted content and holds write, exec or network, pick in this order:
+
+1. **Split it.** A reader stage with read-only access writes a plain file (the story, the
+   triage summary); an actor stage with no untrusted reading works from that file. A person
+   skims the file between them when the actor has exec.
+2. **Hand the write to a person.** The stage drafts the comment, release or status post; a
+   person publishes it.
+3. **Drop the server** and use the export file.
+
+Never pick "tell the model to ignore instructions in the content". Instructions in the prompt
+and instructions in an issue body reach the model as the same kind of text.
+
+## Secrets placement
+
+- Committed config (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `.kiro/settings/mcp.json`)
+  holds variable references only. Each client has its own reference syntax; use the one its
+  docs give.
+- A config that must hold a value stays in the user-level file or the client's secret store,
+  not in the repository. Add a project file that holds a value to `.gitignore` and rotate the
+  value if it was ever committed.
+- Read and write credentials are separate variables with separate tokens, so revoking the
+  write leaves the read stages running.
+- OAuth beats a long-lived token where the vendor offers it.
+
+## The skilldrop loops' stages
+
+From each loop's `loop.json` (type in brackets). Use these when the user names the loop.
+
+| Loop | Stages |
+|---|---|
+| `build` | shape (generate) → implement (generate) → verify (verify, G2 mechanical) → decide (gate, human) |
+| `release` | plan (generate) → ready (verify) → announce (generate) → go (gate, human) |
+| `operate` | instrument (generate) → document (generate) → respond (generate) → learn (verify) |
+| `discover` | gather (generate) → structure (generate) → specify (generate) → ratify (gate) |
+| `design` | constrain (generate) → shape (generate) → threat (verify) → ratify (gate) → record (generate) |
+| `measure` | spec (generate) → review (verify) → sign-off (gate) |
+| `comply` | register → assess → evidence (generate) → check (verify) → sign-off (gate) |
+| `research` | plan (generate) → synthesise (generate) → compare (verify) |
+| `ship-a-draft` | intake (generate) → draft (generate) → critique (verify) → polish (verify) |
+| `apply` | fit (gate) → tailor → letter → form (generate) → confirm (verify) |
+
+If the user's copy of a loop has different stages, theirs wins.

package/packs/ai-engineering/skills/mcp-pairing/templates/mcp-pairing.md

@@ -0,0 +1,43 @@
+# MCP pairing — {loop, workflow or task}
+
+**Tools in use:** {only the tools the user named} · **Assumptions:** {each tagged [assumption]}
+
+## The plan
+
+{Two or three sentences: connect N servers, which ones, read or write; which stages need none;
+which server was cut and why.}
+
+## Pairing by stage
+
+| Stage (type, cadence) | Needs | Server | Grant | Must not | Fallback without it | Risk |
+|---|---|---|---|---|---|---|
+| {stage} ({generate / verify / gate}, {per change / daily / weekly / monthly}) | {category of context or action} | {server the user named, or "{vendor}'s own server, confirm {how}", or the category + vetting} | {scope, one project / repo / role} | {merge, comment, transition, post, write SQL…} | {the export file a person produces} | {untrusted content read; write, exec or network held; what to split} |
+| {stage} | None — works from {previous stage's output} | None | — | — | — | — |
+
+## Credentials
+
+| Variable | Server | Scope | Used by stages | Kind |
+|---|---|---|---|---|
+| {NAME_READ} | {server} | {scope, project} | {stages} | Read |
+| {NAME_WRITE} | {server} | {scope, project} | {the one stage whose output is the write} | Write, separate token |
+
+Tokens live in {environment variables / the client's secret store}. Committed config holds
+variable names only; {any project file that holds a value} stays out of git.
+
+## Servers cut
+
+- **{server or category}** — {cadence and why the export file wins}.
+
+## Check before installing
+
+For each server not confirmed as the vendor's own: publisher, source available, pinned version
+or commit, tools it exposes (turn off the rest), and whether it can run code or reach the
+network beyond its own API.
+
+- **{server}** — {which checks are still open}
+
+## To confirm
+
+- {each fact the plan needs and the input didn't give}
+
+{One plain sentence on the next step, e.g. reviewing the finished setup for ways data could be sent out.}

package/packs/data-analytics/loops/measure/LOOP.md

@@ -0,0 +1,118 @@
+---
+name: measure
+description: Take a dashboard request to a spec a BI developer can build on numbers people can defend: the decision it serves and one chart per question, every metric defined, the SQL behind each metric reviewed for the bugs that quietly inflate a figure, and the metric owner's sign-off on each definition before anything is built. Use when the user says "we need a dashboard for…", "run the measure loop", "make sure these numbers are right before the BI team builds it", or two teams disagree about a number that is about to go on a dashboard.
+---
+
+# measure
+
+One dashboard, from the request to a spec whose numbers have been checked. A wrong number
+on a dashboard does more damage than a wrong number in a query, because the chart makes it
+look settled. So the loop reviews the SQL before anything is built, and it only reviews the
+queries that matter. The spec runs first and cuts the charts that serve no decision, so no
+time goes on queries for charts that won't exist. Last, each metric's owner confirms the
+definition, because a query can be correct and still compute the wrong thing.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `spec` | generate | [`dashboard-spec`](../../skills/dashboard-spec/SKILL.md) | — |
+| 2 | `review` | verify | [`sql-review`](../../skills/sql-review/SKILL.md) | **G9** review |
+| 3 | `sign-off` | gate | [`doc-critique`](../../../core/skills/doc-critique/SKILL.md) | **G9.1** human |
+
+## How to run this loop
+
+1. **Spec the dashboard.** Run `dashboard-spec` with the audience, the decision and the
+   charts people asked for. Save `dashboard-spec.md`. Its cut list removes charts before any
+   SQL is read. Every surviving chart names its metric by defined name, grain, window and
+   comparison. A metric with no written definition is marked `undefined`. Write it down as
+   the person states it, or leave it as a question for the metric's owner. Don't define it
+   yourself.
+2. **Collect one query per surviving metric.** The person supplies the SQL, the dbt model or
+   the view that computes each one, with the engine and what one output row represents.
+   Where none exists yet, draft one from the definition and the schema they supply, and
+   mark it as a draft. A metric with no query and no schema to draft from is `BLOCKED` for
+   that metric, not skipped.
+3. **Review every query at G9.** Run `sql-review` on each, one at a time. Collect each
+   review's verdict line, findings, corrected query and verification queries. Ask the person
+   to run the verification queries, or run them yourself when you have access.
+4. **Map the reviews to G9's verdict:**
+   - every query `SHIP IT` or `SHIP WITH NOTES` → `READY`. The notes travel to the owner at G9.1.
+   - any query `BLOCK` or `FIX FIRST` → `NOT READY`. Return to `spec`. The corrected query
+     becomes that metric's source in the spec, and its verification results go beside it.
+     The fix changes the number the chart will show, sometimes by a lot, so its target,
+     comparison and any threshold the decision uses need checking against it. Then review
+     the corrected query again. Each return counts against the cap.
+5. **Critique, then put each definition to its owner at G9.1.** Run `doc-critique` on the
+   spec. Then show each metric's owner:
+   - the definition in words;
+   - the reviewed query;
+   - what changed and by how much, from the verification queries;
+   - every assumption the review made about keys, time zones and exclusions.
+
+   The owner confirms that this is what the business means by the metric. The BI developer
+   builds only from a spec that has passed G9.1.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json).
+
+- G9 emits `READY`, `NOT READY` or `BLOCKED` (no query text, or no engine to review it
+  against).
+- G9.1 emits:
+  - `PROCEED`: every metric's owner confirmed its definition and number.
+  - `PROCEED WITH CONDITIONS`: confirmed, with named items that travel to the build, such as
+    a `SHIP WITH NOTES` caveat shown on the chart, or a data gap with its date.
+  - `REVISE`: an owner says the definition is wrong (the wrong time zone, an exclusion
+    missing, the wrong grain). Return to `spec` with their definition.
+  - `BLOCKED`: an `undefined` metric has no owner to define it, or an owner is unavailable.
+
+An `undefined` metric can't pass G9.1. Its owner defines it, or the chart moves to the cut
+list with the reason.
+
+## Non-interactive runs
+
+With no person present, G9.1 cannot be satisfied. Run `spec` and `review`, deliver the spec
+with each query's review, and emit `BLOCKED: need each metric owner's confirmation of
+<every metric on the spec>`. A metric whose query passed G9 still needs its owner: the review
+says the SQL computes the definition, not that the definition is right. Never confirm a definition on an owner's behalf, and never fill an
+`undefined` metric with a plausible one: two teams will each read it as theirs.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version of that
+stage, and record that it ran degraded. A degraded `review` still checks every join for
+fan-out, every filter for NULLs and every date boundary for its time zone, in that order,
+because those are the bugs that change the number. Never skip G9.1.
+
+## Run log (opt-in)
+
+Only when the environment variable `SKILLDROP_LOOP_LOG` is set to a file path: after each
+gate's verdict, append one JSON line to that file. Nothing else is recorded, and nothing is
+sent anywhere. When the variable isn't set, or you can't read it, skip this section.
+
+```bash
+printf '%s\n' '{"ts":"2026-10-19T14:03:00Z","loop":"measure","stage":"review","gate":"G9","verdict":"NOT READY","round":1}' >> "$SKILLDROP_LOOP_LOG"
+```
+
+Fields: `ts` (UTC), `loop`, `stage`, `gate` (`null` for a stage without one), `verdict` (the
+gate's exact word), and `round` (1 for the first attempt, counting returns under the cap).
+The log holds verdicts only: never a query, a table name or a figure.
+`skilldrop loop-stats` summarises the file.
+
+## Quality bar
+
+- **The cut list runs before any SQL is read.** Only the queries behind charts that serve the decision get reviewed.
+- **Every surviving chart's metric has a definition and a reviewed query.** `undefined` and unreviewed are build blockers, not notes.
+- **A fixed query goes back through the spec.** The corrected number can move a target or a threshold, and the spec is where those live.
+- **The owner sees the change in the number.** The verification queries' before and after go to G9.1, not only the corrected SQL.
+- **The metric's owner signs the definition.** A correct query for the wrong definition is still the wrong number.
+
+## Anti-patterns to avoid
+
+- ❌ **Reviewing every query in the BI tool.** Queries for charts the spec cut cost review time and add nothing.
+- ❌ **Defining an `undefined` metric yourself to finish the spec.** That settles a disagreement between two teams by picking one at random.
+- ❌ **Shipping the corrected SQL without telling the owner the number moved.** A revenue figure that drops a third overnight with no explanation gets reverted.
+- ❌ **Passing G9 on a clean lint.** The lint can't see join fan-out; the review reads the joins.
+- ❌ **Treating `SHIP WITH NOTES` as `SHIP IT`.** The notes go to the owner and, where they change how the chart reads, onto the chart.
+- ❌ **Building before G9.1.** A dashboard built on an unconfirmed definition is the one the two teams will argue about.

package/packs/data-analytics/loops/measure/evals/eval_queries.json

@@ -0,0 +1,9 @@
+[
+  {"query": "we need a weekly revenue dashboard for the regional leads, and the numbers have to be right", "should_trigger": true},
+  {"query": "run the measure loop on the support KPI dashboard request", "should_trigger": true},
+  {"query": "make sure these numbers are right before the BI team builds the exec dashboard", "should_trigger": true},
+  {"query": "finance and sales disagree on active customers and it's going on the board dashboard", "should_trigger": true},
+  {"query": "is this SQL query right?", "should_trigger": false},
+  {"query": "what charts should go on our marketing dashboard?", "should_trigger": false},
+  {"query": "define the success metric for the new onboarding flow", "should_trigger": false}
+]

package/packs/data-analytics/loops/measure/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "loop_name": "measure",
+  "evals": [
+    {
+      "id": "spec-first-then-review",
+      "prompt": "Run the measure loop. Regional sales leads want a dashboard to decide each Monday where to send the two floating account managers. They asked for: weekly revenue by region, revenue all time, website sessions, active customers, average deal size by region, and a map. Revenue's query is in revenue.sql (Postgres; one row per region per week; customers.customer_id is unique and an order has many order_items). Nobody has written down what 'active customer' means; sales counts anyone with an open opportunity, finance counts anyone invoiced in 90 days.",
+      "assertions": [
+        "Runs dashboard-spec first and writes the decision statement before reviewing any SQL",
+        "Cuts all-time revenue, website sessions and the map with reasons",
+        "Marks active customers as undefined and does not choose between the sales and finance definitions",
+        "Reviews revenue.sql and flags the order_items join as multiplying revenue",
+        "Reports G9 as NOT READY and returns to spec with the corrected query as the metric's source",
+        "Lists verification queries that show how much the revenue number changes",
+        "Stops at G9.1 asking the metric owners to confirm; does not confirm a definition itself"
+      ]
+    },
+    {
+      "id": "owner-rejects-the-definition",
+      "prompt": "Continuing the measure loop. The revenue owner, finance, says the corrected query is right but revenue must be booked in New York time and exclude refunded orders. The query uses UTC and doesn't look at refunds.",
+      "assertions": [
+        "Treats this as G9.1 REVISE and returns to spec with finance's definition",
+        "Updates the revenue metric's definition in the spec to New York time and excluding refunded orders",
+        "Reviews the changed query again at G9 before returning to sign-off",
+        "Counts the return under the cap of 3"
+      ]
+    }
+  ]
+}

package/packs/data-analytics/loops/measure/loop.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "RFC-0052. A dashboard request to a spec whose every number is defined and whose every query has been reviewed. The spec comes first so only the queries behind charts that survive the cut list are reviewed; the metric's owner signs last, because only they can say a definition is what the business means.",
+  "name": "measure",
+  "version": "0.1.0",
+  "description": "Take a dashboard request to a spec a BI developer can build on numbers people can defend: the decision it serves and one chart per question, every metric defined, the SQL behind each metric reviewed for the bugs that quietly inflate a figure, and the metric owner's sign-off on each definition before anything is built. Use when the user says \"we need a dashboard for…\", \"run the measure loop\", \"make sure these numbers are right before the BI team builds it\", or two teams disagree about a number that is about to go on a dashboard.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "spec",
+      "type": "generate",
+      "intent": "Pin the audience and the decision, keep only the charts that serve it, and name the defined metric behind each, flagging any metric nobody has defined.",
+      "skills": ["dashboard-spec"]
+    },
+    {
+      "id": "review",
+      "type": "verify",
+      "intent": "Review the query behind every metric that survived the cut list, correctness before performance, with corrected SQL and the queries that prove the fix.",
+      "skills": ["sql-review"],
+      "gate": {
+        "id": "G9",
+        "kind": "review",
+        "verdicts": ["READY", "NOT READY", "BLOCKED"],
+        "revise_to": "spec"
+      }
+    },
+    {
+      "id": "sign-off",
+      "type": "gate",
+      "intent": "Each metric's owner confirms its definition and the number its reviewed query now produces. The critique informs that decision; it does not make it.",
+      "skills": ["doc-critique"],
+      "gate": {
+        "id": "G9.1",
+        "kind": "human",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "BLOCKED"],
+        "revise_to": "spec"
+      }
+    }
+  ]
+}

package/packs/dev-team/loops/build/LOOP.md

@@ -13,7 +13,7 @@ one. Every skill named below stays independently installable and runnable on its
 
 | # | Stage | Type | Skills | Gate |
 |---|---|---|---|---|
-| 1 | `shape` | generate | [`user-story-splitter`](../../skills/user-story-splitter/SKILL.md), [`bug-triage`](../../skills/bug-triage/SKILL.md) | — |
+| 1 | `shape` | generate | [`user-story-splitter`](../../skills/user-story-splitter/SKILL.md), [`bug-triage`](../../skills/bug-triage/SKILL.md), [`codebase-tour`](../../skills/codebase-tour/SKILL.md) | — |
 | 2 | `implement` | generate | [`feature-implement-loop`](../../skills/feature-implement-loop/SKILL.md) | — |
 | 3 | `verify` | verify | [`pre-merge-review`](../../skills/pre-merge-review/SKILL.md) | **G2** mechanical |
 | 4 | `decide` | gate | [`council-review`](../../../core/skills/council-review/SKILL.md) | **G2.1** human |
@@ -22,7 +22,9 @@ one. Every skill named below stays independently installable and runnable on its
 
 1. **Establish the unit of work.** New capability → `user-story-splitter`. Reported defect →
    `bug-triage`. The stage is done when there is one vertical slice with acceptance criteria a
-   test can assert. Vague criteria are the single largest cause of a wasted round 3.
+   test can assert. Vague criteria are the single largest cause of a wasted round 3. In a
+   repository nobody on the change knows yet, run `codebase-tour` on the slice first: where
+   the change goes, the commands that test it, and the traps, each cited to a file.
 2. **Implement.** Hand the slice to `feature-implement-loop`, which runs its own capped
    generate-challenge-gate cycle internally. Do not re-implement its rounds here — this loop's
    `cap` governs returns from G2, not the inner skill's rounds.

package/packs/dev-team/loops/build/loop.json

@@ -1,7 +1,7 @@
 {
   "$comment": "RFC-0028. This loop is docs/code-implement-verify.mmd promoted from a hand-maintained diagram into the machine-readable source that diagram is now generated from.",
   "name": "build",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Take an agreed requirement to merged code through a capped generate-verify-gate loop, with a mechanical gate that decides and a human who owns the merge. Use when the user wants to implement a story, fix a triaged bug, or ask whether a change is safe to merge.",
   "entrypoint": "LOOP.md",
   "kind": "loop",
@@ -11,7 +11,7 @@
       "id": "shape",
       "type": "generate",
       "intent": "Turn a requirement or defect into one vertically-sliced unit of work with acceptance criteria.",
-      "skills": ["user-story-splitter", "bug-triage"]
+      "skills": ["user-story-splitter", "bug-triage", "codebase-tour"]
     },
     {
       "id": "implement",