skilldrop-cli 0.16.28 → 0.16.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.28",
+  "version": "0.16.29",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

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/grc/loops/comply/LOOP.md

@@ -0,0 +1,133 @@
+---
+name: comply
+description: Take a change that carries risk (a launch, a new vendor, a new use of personal data) to a risk position its owner has signed: a risk register scored inherent and residual, a DPIA when personal data is processed, the evidence behind every control the ratings rely on, a script that checks the register, and a sign-off only the named owner can give. Use when the user says "get this ready for risk sign-off", "run the comply loop", "what do we need before we can launch this", or needs a register, a DPIA and audit evidence that agree with each other.
+---
+
+# comply
+
+One change, from its risks to a signature. Each of the three documents is useful alone. The
+loop exists for the places where they disagree. A register can rate a risk low because of a
+control that leaves no record. A DPIA can find a high risk to people that never reaches the
+register its owner reads. An evidence map can show a gap that nobody connects to the rating
+that relied on it. The loop makes the three agree. Then the register's own script checks
+them, and the person who owns the risk decides.
+
+This loop prepares material for a qualified reviewer: a DPO, a risk committee, an auditor.
+It is not legal or audit advice, and every document it produces says so once, at the top.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `register` | generate | [`risk-register`](../../skills/risk-register/SKILL.md) | — |
+| 2 | `assess` | generate | [`dpia`](../../skills/dpia/SKILL.md) | — |
+| 3 | `evidence` | generate | [`soc2-evidence-map`](../../skills/soc2-evidence-map/SKILL.md) | — |
+| 4 | `check` | verify | [`risk-register`](../../skills/risk-register/SKILL.md) | **G8** mechanical |
+| 5 | `sign-off` | gate | [`doc-critique`](../../../core/skills/doc-critique/SKILL.md) | **G8.1** human |
+
+## How to run this loop
+
+1. **Register the change's risks.** Run `risk-register` with the change as its scope and the
+   objective it threatens. Save `risk-register.csv`. Owners come from the person; a missing
+   owner stays an error to resolve, never a guessed name.
+2. **Screen and assess personal data.** Run `dpia` on the processing the change introduces.
+   - When the screening finds no criteria that apply, keep its short screening record and go on.
+   - When a DPIA is needed, complete it. Then give each risk to people still at medium or high
+     residual its own register row, with the harm to people as the consequence, the same
+     owner as the DPIA measure, and `DPIA` in its controls cell. The DPIA keeps scoring harm to
+     people; the register row is how its owner sees it.
+3. **Evidence every control the ratings rely on.** List the controls named in the register's
+   residual ratings and the DPIA's in-place measures, and run `soc2-evidence-map` on that
+   list. Use the organisation's SOC 2 scope when it has one; otherwise use the skill's
+   default, Security only, tagged `[assumption]`.
+4. **Put the evidence gaps back into the register.** A residual rating can count only
+   controls that operate today. For each control the map marks `gap`:
+   - set the residual likelihood and impact of every risk that relied on it back to their
+     inherent values;
+   - move the control to a dated action under the treatment.
+
+   A `partial` control keeps its credit only for what its evidence covers; say what that is
+   in the summary for the owner. Don't lower a rating to make a heat map look better.
+5. **Check at G8.** Run the register's script on the final CSV:
+
+   ```bash
+   # Claude Code (the loop and risk-register installed side by side)
+   python3 "${CLAUDE_SKILL_DIR}/../risk-register/scripts/check_register.py" risk-register.csv --top 5 --out register-check.txt
+   # Other IDEs (from the folder the skills were installed into)
+   python3 risk-register/scripts/check_register.py risk-register.csv --top 5 --out register-check.txt
+   ```
+
+   The exit code is the verdict: `0` is `READY`, `1` is `NOT READY`, `2` is `BLOCKED`.
+   `NOT READY` returns to `register` to fix what the script names, then runs `check` again.
+   Report its warnings to the person; don't edit scores to silence them.
+6. **Critique, then put the decision to the owner at G8.1.** Run `doc-critique` on the
+   summary the owner will read. Then show them:
+   - the residual heat map from the script, as printed;
+   - every risk they are asked to accept;
+   - the evidence gaps and their dates;
+   - the DPIA's view on prior consultation.
+
+   Each owner accepts their own risks. A high or critical residual risk that its own owner
+   accepts needs a sign-off from someone above them, named in the summary.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json).
+
+- G8 emits `READY`, `NOT READY` or `BLOCKED`, from the script's exit code alone.
+- G8.1 emits:
+  - `PROCEED`: every residual risk is accepted or treated, by its named owner.
+  - `PROCEED WITH CONDITIONS`: accepted, subject to named actions with dates, each recorded
+    as a control and `due_date` on its risk.
+  - `REVISE`: the owner rejects a rating or a treatment. Return to `register` with their reasons.
+  - `RECONSIDER`: the change shouldn't go ahead as designed, for example when a residual risk
+    to people stays high and the design has to change before prior consultation. The loop
+    ends here.
+  - `BLOCKED`: no owner is available, or the DPO's advice is required and not yet given.
+
+## Non-interactive runs
+
+With no person present, G8.1 cannot be satisfied. Run every stage through G8, deliver the
+documents, and emit `BLOCKED: need sign-off from <the named owners>`. Never accept a risk
+on someone's behalf, never fill an owner, a retention period or a vendor location with a
+plausible guess, and leave the DPIA's DPO advice and decision fields blank.
+
+## 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. Without `risk-register`, G8 has no script. Say so,
+check the register by hand against the script's rules (every required field, owners that
+name a person, residual never above inherent, dates that are dates), and mark G8 degraded.
+Never skip G8.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":"comply","stage":"check","gate":"G8","verdict":"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 risk, an owner's name or any personal data.
+`skilldrop loop-stats` summarises the file.
+
+## Quality bar
+
+- **The three documents agree.** Every DPIA risk at medium or high residual has a register row, and every control a residual rating relies on appears in the evidence map.
+- **A residual rating counts only evidenced controls.** A control with an evidence gap gives no credit until the evidence exists, and the gap has a dated action.
+- **G8 is the script's exit code.** The register reaches its owner only with zero errors.
+- **Only a named owner accepts a risk.** High and critical residual risks accepted by their own owner carry a second, named sign-off.
+- **Not legal or audit advice, said once.** The DPO's advice, the decision and the sign-off fields are left for the people who give them.
+
+## Anti-patterns to avoid
+
+- ❌ **Filing the DPIA beside the register instead of into it.** A high risk to people that isn't on the owner's list doesn't get signed off; it gets missed.
+- ❌ **Leaving a residual rating on a control the evidence map marked `gap`.** That is a planned control scored as a real one, the exact thing the register bans.
+- ❌ **Editing the register to turn G8 green.** Fix the risk the script names; don't delete the row or soften the score.
+- ❌ **Running the evidence map on the whole SOC 2 scope.** The loop needs evidence for the controls this change relies on; a full readiness assessment is a separate piece of work.
+- ❌ **Self-signing at G8.1.** A clean check says the register is well-formed. It cannot say the risk is acceptable.
+- ❌ **Writing a guessed vendor location or retention period** to complete the DPIA. It stays `[to confirm: …]` and becomes a DPO question.

package/packs/grc/loops/comply/evals/eval_queries.json

@@ -0,0 +1,9 @@
+[
+  {"query": "get the new payroll vendor ready for risk sign-off", "should_trigger": true},
+  {"query": "run the comply loop on our launch of in-store facial recognition", "should_trigger": true},
+  {"query": "what do we need before we can launch this feature that profiles customers?", "should_trigger": true},
+  {"query": "I need a risk register, a DPIA and the audit evidence for this change, and they have to agree", "should_trigger": true},
+  {"query": "score these five risks on a 5x5", "should_trigger": false},
+  {"query": "do we need a DPIA for the new CRM?", "should_trigger": false},
+  {"query": "fill in this customer's security questionnaire", "should_trigger": false}
+]

package/packs/grc/loops/comply/evals/evals.json

@@ -0,0 +1,30 @@
+{
+  "loop_name": "comply",
+  "evals": [
+    {
+      "id": "evidence-gap-reverts-the-rating",
+      "prompt": "Run the comply loop. We're moving payroll to a new SaaS vendor, Paywell, on 1 December. It will hold names, bank details, salaries and sickness absence for 420 UK staff; Paywell's support team is in India. The HR director, Priya Shah, owns the change. Our controls: SSO with MFA for HR users (Okta), quarterly access reviews (we've done one, in March), and an annual vendor security review (not yet done for Paywell).",
+      "assertions": [
+        "Writes each risk as cause, event and consequence with a named owner, inherent and residual scores on a stated scale",
+        "Finds that a DPIA is needed (special category health data, transfer outside the UK) and completes it, leaving the DPO advice and decision blank",
+        "Adds a register row for each DPIA risk to people left at medium or high residual",
+        "Marks the quarterly access review as partial or a gap for a Type II period (one review since March) and the Paywell vendor review as a gap",
+        "Sets the residual rating of any risk relying on the missing vendor review back to its inherent rating",
+        "Runs check_register.py and reports G8 from its exit code",
+        "Stops at G8.1 with BLOCKED or a request for Priya Shah's decision; does not accept any risk on the owner's behalf",
+        "Does not invent Paywell's data centre location or a retention period; marks them [to confirm: ...]"
+      ]
+    },
+    {
+      "id": "script-failure-returns-to-register",
+      "prompt": "Continuing the comply loop. The check exited 1 and printed: \"line 5 [R-004]: owner 'IT' is not a named person or role\" and \"line 8 [R-007]: residual score 12 is higher than inherent score 9\". Fix it.",
+      "assertions": [
+        "Treats the output as G8 NOT READY and returns to the register stage",
+        "Asks for or names a person or role to own R-004 rather than inventing one",
+        "Corrects R-007 by revisiting its scores or controls, not by deleting the row",
+        "Re-runs the script and reports the new exit code before going to sign-off",
+        "Counts this as round 2 under the cap of 3"
+      ]
+    }
+  ]
+}

package/packs/grc/loops/comply/loop.json

@@ -0,0 +1,54 @@
+{
+  "$comment": "RFC-0052. A change to a risk position its owner has signed. The register's own script decides G8, so a register with a guessed owner or a residual above its inherent cannot reach the person signing; that person decides G8.1, because accepting a risk is theirs alone.",
+  "name": "comply",
+  "version": "0.1.0",
+  "description": "Take a change that carries risk (a launch, a new vendor, a new use of personal data) to a risk position its owner has signed: a risk register scored inherent and residual, a DPIA when personal data is processed, the evidence behind every control the ratings rely on, a script that checks the register, and a sign-off only the named owner can give. Use when the user says \"get this ready for risk sign-off\", \"run the comply loop\", \"what do we need before we can launch this\", or needs a register, a DPIA and audit evidence that agree with each other.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "register",
+      "type": "generate",
+      "intent": "Write the change's risks as cause, event and consequence, scored inherent and residual on a stated scale, each with a named owner and a treatment.",
+      "skills": ["risk-register"]
+    },
+    {
+      "id": "assess",
+      "type": "generate",
+      "intent": "Screen for a DPIA and, where one is needed, score the harm to people; each risk to people left at medium or high gets its own row in the register.",
+      "skills": ["dpia"]
+    },
+    {
+      "id": "evidence",
+      "type": "generate",
+      "intent": "For every control the residual ratings and the DPIA's measures rely on, name the evidence that it operates today, and mark the gaps.",
+      "skills": ["soc2-evidence-map"]
+    },
+    {
+      "id": "check",
+      "type": "verify",
+      "intent": "Run the register's own check, after evidence gaps have put residual ratings back where the evidence leaves them.",
+      "skills": ["risk-register"],
+      "gate": {
+        "id": "G8",
+        "kind": "mechanical",
+        "script": "packs/grc/skills/risk-register/scripts/check_register.py",
+        "verdicts": ["READY", "NOT READY", "BLOCKED"],
+        "revise_to": "register"
+      }
+    },
+    {
+      "id": "sign-off",
+      "type": "gate",
+      "intent": "The named owner accepts each residual risk, or doesn't. The critique informs that decision; it does not make it.",
+      "skills": ["doc-critique"],
+      "gate": {
+        "id": "G8.1",
+        "kind": "human",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "RECONSIDER", "BLOCKED"],
+        "revise_to": "register"
+      }
+    }
+  ]
+}

package/packs/research/loops/research/LOOP.md

@@ -0,0 +1,123 @@
+---
+name: research
+description: Take a question that turns on why something happened to an answer the evidence can carry: a plan tied to the decision it serves, a synthesis of the sources with every claim cited, and rival explanations ranked by how little evidence contradicts them, with a gate that sends the work back for the observation that would tell the leaders apart. Use when the user says "research why…", "find out what's causing…", "run the research loop", or needs a decision-ready answer on which explanation the evidence supports.
+---
+
+# research
+
+One question, from scoping to an answer someone can decide on. The three skills each work
+alone; in order, each one constrains the next. The plan fixes what would change the decision
+before anyone reads a source, so the findings can't be read to fit. The synthesis cites every
+claim, so the comparison rates only evidence that exists. The gate then asks whether that
+evidence separates the explanations, which none of the three can judge about its own output.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `plan` | generate | [`research-plan`](../../skills/research-plan/SKILL.md) | — |
+| 2 | `synthesise` | generate | [`source-synthesis`](../../skills/source-synthesis/SKILL.md) | — |
+| 3 | `compare` | verify | [`hypothesis-comparison`](../../skills/hypothesis-comparison/SKILL.md) | **G7** review |
+
+## How to run this loop
+
+1. **Plan before reading.** Run `research-plan` on the question. It asks what decision the
+   research serves, who makes it and by when; don't skip that. Save the plan as `plan.md`.
+   Carry three things from it into every later stage: the decision, the findings that would
+   change it, and the stopping rule.
+2. **Gather the sources the plan names.** The person supplies them, or you collect them under
+   the plan's inclusion and exclusion criteria with the search strings it wrote. A source the
+   criteria exclude stays out, however convenient. List each as `S1: …` in `sources.md`.
+3. **Synthesise, cited.** Run `source-synthesis` in its cited form (an evidence summary with
+   `[S1:p4]` citations), on the plan's question. It counts a source that repeats another once,
+   and its citation check runs before you hand anything on. Save it as `synthesis.md`.
+4. **Compare the explanations.** Run `hypothesis-comparison` with the observation from the
+   plan as the thing to explain and the synthesis's findings as the evidence, keeping their
+   citations. Every evidence row cites a source from `sources.md` or is marked
+   `[assumption]`. The comparison names the leader, the diagnostic evidence, the linchpins and
+   the next observation that would tell the top two apart.
+5. **Judge the evidence at G7.** Ask four questions, then choose the verdict below:
+   - Does at least one diagnostic row separate the leader from the runner-up?
+   - Does any linchpin rest on a single source or an `[assumption]`?
+   - Is the plan's stopping rule met?
+   - Would the finding move the decision past a threshold the plan set?
+6. **On `REVISE`, get the observation, not more of the same.** Return to `synthesise` with the
+   one observation the comparison named as discriminating. Add it to `sources.md` as a new
+   source, re-synthesise, and compare again. More sources that the top two both predict
+   equally add nothing. Each return counts against the cap. When only a person can get the
+   observation (a data pull, an interview, a log nobody gave you), stop here: say what to
+   get, from whom, and what each result would mean, and resume when they add it.
+7. **Hand over the answer, then the verdict.** Lead with the explanation the evidence favours
+   and its confidence, then what that means for the decision named in the plan, then the
+   open conditions. The matrix and the synthesis go underneath, for anyone who wants to
+   check. Close with the gate on its own line, `G7: <VERDICT>`, and one sentence of reasons.
+   The skills keep their own terms out of a reply; the loop's verdict is the exception,
+   because the run log and the next round both read it.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json). G7 emits:
+
+- `PROCEED`: diagnostic evidence separates the leader, no linchpin rests on one source or an
+  assumption, and the stopping rule is met.
+- `PROCEED WITH CONDITIONS`: the leader is clear, but a named linchpin is unchecked or a
+  sub-question is still open. The conditions travel with the answer: each one says what to
+  check and how the decision changes if it comes out the other way.
+- `REVISE`: the top two are not separated by any diagnostic row, or the leader rests on one
+  weak row. Return to `synthesise` with the discriminating observation.
+- `RECONSIDER`: every hypothesis is contradicted by strong evidence, or the observation
+  itself turned out wrong (a tracking change, a definition change). The question needs
+  re-planning, so the loop ends here and a new run starts at `plan`.
+- `BLOCKED`: no decision to serve, no observation to explain, or no sources.
+
+On the cap-th `REVISE`, emit `PROCEED WITH CONDITIONS` with the leaders still tied and say
+plainly that the evidence doesn't settle it: the decision will be made under that
+uncertainty, and the discriminating observation is the first thing to get.
+
+## Non-interactive runs
+
+With no person to name the decision, `research-plan` either infers it as an `[assumption]` or
+emits `BLOCKED: need the decision this research informs, who makes it, and by when`. Carry
+that `BLOCKED` through as the loop's verdict. Run no further stages on an invented decision:
+a stopping rule set against a guessed decision stops at the wrong place. With no sources and
+nothing to collect them from, emit `BLOCKED: need the sources, or access to collect them
+under the plan's criteria`.
+
+## 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 `compare` still builds a matrix that
+ranks by inconsistency and names its linchpins, because G7 can't be judged without them.
+Never skip G7.
+
+## 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":"research","stage":"compare","gate":"G7","verdict":"REVISE","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 the question, the sources or the findings.
+`skilldrop loop-stats` summarises the file.
+
+## Quality bar
+
+- **What would change the decision is written before any source is read.** Thresholds set after the findings are read get set to fit them.
+- **Every evidence row in the matrix cites a source in `sources.md` or is marked `[assumption]`.** A matrix of uncited evidence ranks a favourite theory.
+- **G7 is judged on diagnostic evidence.** Rows that every hypothesis predicts equally are named and set aside, however many there are.
+- **A `REVISE` brings back the one observation that discriminates.** It does not bring back more sources of the same kind.
+- **The answer leads with the explanation and what it means for the decision.** The matrix is the working, not the reply.
+
+## Anti-patterns to avoid
+
+- ❌ **Synthesising before the plan exists.** The sources then decide the question, and the stopping rule is whenever the reading runs out.
+- ❌ **Rating evidence the synthesis didn't cite.** An observation from memory or a plausible industry figure is an `[assumption]` row, weighted as one.
+- ❌ **Counting a press release and the three articles that quote it as four sources.** The synthesis counts them once, and so does the matrix.
+- ❌ **Passing G7 on volume.** Ten consistent rows that every rival also explains don't separate anything.
+- ❌ **Looping past the cap in search of certainty.** At the cap, say that the evidence doesn't settle it and name the next check.
+- ❌ **Re-planning inside the loop after `RECONSIDER`.** A new question is a new run, with its own plan and stopping rule.

package/packs/research/loops/research/evals/eval_queries.json

@@ -0,0 +1,9 @@
+[
+  {"query": "research why our trial-to-paid conversion dropped in September", "should_trigger": true},
+  {"query": "run the research loop on what's causing the rise in support tickets", "should_trigger": true},
+  {"query": "find out which explanation the evidence supports for the churn spike, so I can decide what to fix", "should_trigger": true},
+  {"query": "I need a decision-ready answer on why the pilot underperformed", "should_trigger": true},
+  {"query": "summarise these three papers for me", "should_trigger": false},
+  {"query": "help me scope a research plan for entering the German market", "should_trigger": false},
+  {"query": "build an ACH matrix from this evidence list", "should_trigger": false}
+]

package/packs/research/loops/research/evals/evals.json

@@ -0,0 +1,39 @@
+{
+  "loop_name": "research",
+  "evals": [
+    {
+      "id": "plans-before-reading",
+      "prompt": "Run the research loop: why did our trial-to-paid conversion drop from 14% to 9% in September? I've put the sources in sources/ (a product analytics export, the September release notes, 12 sales call notes, and a competitor's pricing page). The growth lead decides by 1 November whether to roll back the new onboarding flow.",
+      "assertions": [
+        "Runs research-plan first and writes, before synthesising, what finding would change the roll-back decision",
+        "States the stopping rule before reading the sources",
+        "The synthesis cites every claim to a listed source and location",
+        "The comparison includes a measurement hypothesis (tracking or definition change) alongside the onboarding flow and the competitor's pricing",
+        "Every evidence row in the matrix cites a listed source or is marked [assumption]",
+        "Ends with a G7 verdict from PROCEED, PROCEED WITH CONDITIONS, REVISE, RECONSIDER or BLOCKED, and the reasons for it",
+        "The reply leads with the explanation the evidence favours and what it means for the roll-back, not with the matrix"
+      ]
+    },
+    {
+      "id": "revise-brings-the-discriminating-observation",
+      "prompt": "Continuing the research loop. The comparison left H1 (the new onboarding flow) and H3 (the competitor's price cut on 4 September) tied, and named as discriminating: conversion for trials that started before the onboarding release on 11 September. I've added that cohort export as sources/cohorts.csv.",
+      "assertions": [
+        "Treats the tie as G7 REVISE and returns to synthesise, not to plan",
+        "Adds the cohort export as a new numbered source and re-synthesises with it cited",
+        "Re-runs the comparison with the new evidence row rated across every hypothesis",
+        "Counts this as round 2 under the cap of 3",
+        "Does not add further sources that both H1 and H3 predict equally"
+      ]
+    },
+    {
+      "id": "blocked-without-a-decision",
+      "prompt": "Run the research loop on why remote work is good. Non-interactive, no follow-up questions.",
+      "assertions": [
+        "Emits BLOCKED: need the decision this research informs, who makes it, and by when",
+        "Does not run source-synthesis or hypothesis-comparison",
+        "Does not invent a decision or gather sources",
+        "Says in plain words what it will produce once it has the decision"
+      ]
+    }
+  ]
+}

package/packs/research/loops/research/loop.json

@@ -0,0 +1,35 @@
+{
+  "$comment": "RFC-0052. A question to an answer the evidence can carry. The gate sits after the comparison because a synthesis can't tell you whether its own evidence separates the explanations; the matrix can.",
+  "name": "research",
+  "version": "0.1.0",
+  "description": "Take a question that turns on why something happened to an answer the evidence can carry: a plan tied to the decision it serves, a synthesis of the sources with every claim cited, and rival explanations ranked by how little evidence contradicts them, with a gate that sends the work back for the observation that would tell the leaders apart. Use when the user says \"research why…\", \"find out what's causing…\", \"run the research loop\", or needs a decision-ready answer on which explanation the evidence supports.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "plan",
+      "type": "generate",
+      "intent": "Pin the decision the research serves, the precise question, what finding would change the decision, and when to stop, before any source is read.",
+      "skills": ["research-plan"]
+    },
+    {
+      "id": "synthesise",
+      "type": "generate",
+      "intent": "Say what the sources gathered under the plan support, every claim cited to a location, a repeated source counted once.",
+      "skills": ["source-synthesis"]
+    },
+    {
+      "id": "compare",
+      "type": "verify",
+      "intent": "Rank the rival explanations against the cited evidence, then judge whether that evidence is strong enough to carry the decision.",
+      "skills": ["hypothesis-comparison"],
+      "gate": {
+        "id": "G7",
+        "kind": "review",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "RECONSIDER", "BLOCKED"],
+        "revise_to": "synthesise"
+      }
+    }
+  ]
+}