@malloy-publisher/skills 0.1.47 → 0.1.49

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/skills",
    "description": "Agent skills for Malloy and the Malloy Publisher",
-   "version": "0.1.47",
+   "version": "0.1.49",
    "license": "MIT",
    "type": "module",
    "main": "dist/index.js",

package/skills/eval-answer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-answer
 description: 'Score one analytical answer against a verified golden, and score which of the entities the golden depends on retrieval delivered to the answerer. Run the contamination checklist, re-execute the submitted query yourself, then spawn a judge subagent per skill:eval-judge. Append attempt, tool_call, score, and retrieval_score events to the file ledger (reference/ledger-schema.md). Never explain the failure (eval-diagnose) or edit the model (eval-improve). Use when asked whether an answer was correct, to score a run, or to baseline a model.'
-version: 0.1.47
+version: 0.1.49
 ---
 
 # Evaluate One Answer

package/skills/eval-answer/scripts/init_truth_package.py

@@ -15,7 +15,7 @@ The doctrine mandates raw-table goldens: every golden is computed in a
 semantics-free package over the same raw tables, never through the model under
 test, so a model bug cannot certify its own golden. `set.json` has had a
 `truthPackage` field for that since the schema was written -- and nothing built
-one. The VideoAmp author wrote `truth.malloy`, a `publisher.json`, a second
+one. One set's author wrote `truth.malloy`, a `publisher.json`, a second
 server config and an MCP client by hand before authoring case one: an hour of
 plumbing for a structure that is entirely derivable from the package.
 

package/skills/eval-answer/scripts/verify_goldens.py

@@ -25,7 +25,7 @@ WHAT IT CHECKS, AND WHAT EACH CATCHES
 
 2. rubric numbers -- every figure the rubric's ACCEPTING clause quotes appears
                  in the golden rows or their column sums. Would have caught the
-                 authoring defect that cost an arm on the VideoAmp set: a rubric
+                 authoring defect that cost an arm on a warehouse-backed set: a rubric
                  that said "122,935,709.72 (group 31681)" while its own executed
                  rows held a different number, so the judge -- correctly --
                  reported the golden as suspect. Reported as REVIEW items, not

package/skills/eval-diagnose/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-diagnose
 description: 'Diagnose why a scored answer failed and who owns the fix, then cluster the failures by shared root cause. Walk dataset, agent-call, get_context/model, get_context/retrieval, construction, then model-definition. Append issue events to the file ledger, linked by traceId, one per cluster. Use after eval-answer, when triaging a run, or before changing a model. Does not edit the model (eval-improve).'
-version: 0.1.47
+version: 0.1.49
 ---
 
 # Diagnose One Answer

package/skills/eval-diagnose/scripts/diagnose.py

@@ -1032,7 +1032,7 @@ def main(argv: list[str] | None = None) -> int:
     # The agent's clusters are the clusters of record, in the file the package
     # builder reads. Until 2026-09-02 only cluster_failures.py wrote this file,
     # so the browsable package always carried the mechanical grouping -- which
-    # on both the ecommerce and VideoAmp runs charged everything to retrieval
+    # on both the ecommerce and warehouse-backed runs charged everything to retrieval
     # while the diagnosis beside it said otherwise.
     # Imported, not spelled: this file and `cluster_failures.py` both write
     # `clusters.jsonl`, and when `score_retrieval` renamed the labels these two

package/skills/eval-import/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-import
 description: 'Turn a list of questions into an eval set, whatever shape it arrived in: a JSONL a customer sent, a CSV, a spreadsheet export, a markdown doc, an email thread, or a pull from production logs. Classify each item by what came WITH the question (a query, a number, prose criteria, or nothing), write cases.jsonl and set.json per reference/case-format.md, keep the file as it arrived, and seal each question so a later edit is detectable. Never marks a value-bearing golden verified and never invents a question. Use when questions arrive from outside and need to become a set, or before the first run against a set nobody here authored.'
-version: 0.1.47
+version: 0.1.49
 ---
 
 # Import questions into an eval set

package/skills/eval-improve/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-improve
 description: 'Make the smallest safe edit that closes a diagnosed gap the model repo owns: a Malloy model edit, or a package skill under skills/. Every factual claim carries a probe receipt. Use after eval-diagnose, or when asked to fix a model so an agent can discover the right answer. Never accepts its own edit; the acceptance check belongs to eval-loop. Does not decide whether an answer was wrong (eval-answer) or why (eval-diagnose).'
-version: 0.1.47
+version: 0.1.49
 ---
 
 # Improve the Model

package/skills/eval-judge/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-judge
 description: 'Decide whether ONE answer matches its golden, and say whether you believe the golden. Read this before emitting any verdict. Covers containment, column pairing, near_match, refusals, and the gold_status judgement. Use when scoring an attempt in an evaluation run; never to conduct a run (eval-loop), diagnose a failure (eval-diagnose) or edit a model (eval-improve).'
-version: 0.1.47
+version: 0.1.49
 ---
 
 # The judge

package/skills/eval-loop/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-loop
 description: 'Conduct a local Publisher evaluation loop in five steps: scrape/run, eval, diagnose, improve, checkpoint. You are the conductor: import cases into the file ledger, spawn a blind answerer, then run eval-answer, eval-diagnose, and eval-improve. Persistence is plain files: the set in the model package''s evals/ directory, runs in the set''s workdir; checkpoints are git commits of the model repo. `eval.py` runs each step from the set''s eval.toml. Use to score a model, diagnose failures, improve behind an acceptance check, or roll back a bad direction.'
-version: 0.1.47
+version: 0.1.49
 ---
 
 # The Evaluation Loop

package/skills/eval-loop/reference/running-a-run.md

@@ -155,7 +155,7 @@ Three layers, in this order, and the order is what makes it readable:
 Order of magnitude for planning, **calibrated on ecommerce over local duckdb**:
 a Sonnet arm over a few dozen cases costs single-digit dollars and finishes in
 minutes, at roughly a dime and a handful of turns per case. A proxied warehouse
-is a different regime: the VideoAmp set ran at $0.33 per case on Sonnet and
+is a different regime: a proxied-warehouse set ran at $0.33 per case on Sonnet and
 $0.57–0.71 on Opus, ~100 s per case, driven by warehouse latency and query
 errors -- budget 4x when the data is not local. Budget **five** such arms for a
 defensible claim -- a baseline, two for the A/A, and two post-edit -- plus the

package/skills/eval-loop/scripts/run_baseline.py

@@ -827,7 +827,7 @@ def server_alive(a: argparse.Namespace) -> bool:
 
     A dead Publisher returns an empty body that the answerer reads as a bad
     answer and the judge scores as a miss (Publisher's own friction log, item
-    7; the VideoAmp run's server died mid-session and a raw probe caught it,
+    7; a past run's server died mid-session and a raw probe caught it,
     not the harness). So every attempt asks first. Local: the REST root.
     Platform: any HTTP answer from the MCP URL -- it says 405 to a bare GET,
     which is fine; refusal or timeout is not.
@@ -3760,7 +3760,7 @@ def main(argv: list[str] | None = None) -> int:
 
     # Lint the set's expected entities before a dollar is spent: an id the
     # model does not declare is a stale set, not a retrieval miss, and both
-    # VideoAmp platform runs carried five of them (the set was written against
+    # platform runs of one set carried five of them (the set was written against
     # a later package) which read as misses until someone checked by hand.
     declared = None
     if a.target != "platform" and a.publisher:

package/skills/eval-loop/scripts/serve.py

@@ -24,7 +24,7 @@ WHY THIS EXISTS
 
 The doctrine has always said "serve the model persistently, not `&` from a
 shell that exits", and gave no recipe. A server launched from a shell wrapper
-is SIGTERM'd with the wrapper's session when it exits; both VideoAmp servers
+is SIGTERM'd with the wrapper's session when it exits; both servers of a past run
 were lost that way once, and the answerer read the dead server's empty body as
 a bad answer. This starts the server in its OWN session (setsid semantics via
 start_new_session), redirects its output to a log in the server root, writes a

package/skills/eval-report/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-report
 description: 'Write the summary a person reads after an evaluation run: what ran, what it scored, which failures were the MODEL and which were the EVAL itself (out of turns, contaminated, unestablished golden, unreadable judge), what was learned, and what to do next. Every claim links to the artifact behind it. Use at the end of any run, before quoting a number to anyone. Never scores an answer (eval-answer) or decides who owns a failure (eval-diagnose).'
-version: 0.1.47
+version: 0.1.49
 ---
 
 # Report a Run

package/skills/malloy-analysis/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-analysis
 description: "Read before your first get_context call on any business or data question. The required workflow, not background: which source, which rows, how to verify. Skipping it causes confident wrong answers."
-version: 0.1.47
+version: 0.1.49
 ---
 
 <!-- Copyright (c) Credible Data Inc. SPDX-License-Identifier: MIT -->
@@ -23,7 +23,8 @@ Restate what is being asked: which metric, which breakdown (group-by), which fil
 Find the right entities before writing any query.
 
 - If you do not already know which package to work in, confirm the environment and package with the user before continuing.
-- **Load `skill:malloy-phrase-detection`**, then call `get_context` with entity targets that describe the fields the question needs: a `measure` for the metric, a `dimension` for each breakdown or filter, and a `view` if the question sounds like a canned report. **Every target carries a `search_text`**: a target without one enumerates a capped catalog instead of searching, and the cap is blind to your question. The tool description covers what comes back and how to narrow or browse.
+- **Load `skill:malloy-phrase-detection`**, then call `get_context` with entity targets that describe the fields the question needs: a `measure` for the metric, a `dimension` for each breakdown or filter, and a `view` if the question sounds like a canned report. **One concept per target**: never list several in one `search_text` ("revenue, date, category and region"), because they then compete for one target's few picks. **Every target carries a `search_text`**: a target without one enumerates a capped catalog instead of searching, and the cap is blind to your question. The tool description covers what comes back and how to narrow or browse.
+- **A source in the results is not yet every field you need.** Check that each concept the question needs came back as a field. When one did not, when a target is listed in `unresolved_targets`, or when a warning says results were cut, call `get_context` again with `scopes[].source` set to the source that should hold it and one target per missing concept. Do not answer from a source match alone, and do not tell the user a field is missing before that narrower search.
 - **A value the user typed (a brand, a city, a product name) is not yet a filter.** Resolve it to the string the data stores before you filter on it: a `dimensional_value` target in that `get_context` call, or, where value search isn't available, a query of the dimension's distinct values. "ray ban" may be stored as `Ray-Ban` and `Ray-Ban Junior`; a `where:` on the user's own spelling, or a regex guessed from it, can match nothing and still return a result.
 - Read the documentation on each returned entity: on an entity it is `description`, on a source it is `docs`, often with a short `one_line_summary` and sometimes a longer `summary`. Which of these a server fills varies, so read the ones your response actually carries and do not go hunting for one that is absent. Authors write it as `#(doc)` in the model, but the response never uses that label, so do not go looking for that either. It is where grain, units, null handling, and any source-level filters are described. Confirm the exact field names against the results before using them.
 - **Read the source's own documentation too, not just each field's.** The source-level `docs` often defines the grain, the universe of rows it represents, how joins behave, and source-level filters or assumptions that apply to every query rooted on it. Factor both the source and the field docstrings into how you build and later verify the query.

package/skills/malloy-analysis-report/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-analysis-report
 description: Combine validated Malloy queries into a report (a linear report, read top to bottom). Use when the user asks to "create a report", "combine these into a report", or wants a persistent multi-query artifact.
-version: 0.1.47
+version: 0.1.49
 ---
 
 <!--

package/skills/malloy-charts/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-charts
 description: Read before choosing a chart or adding a chart annotation. Chart types, tag syntax and scale rules, KPI cards, dashboards, sparklines, and the renderer mistakes that fail silently.
-version: 0.1.47
+version: 0.1.49
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-classify/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: malloy-classify
+description: 'Propose #(classification) annotations for a Malloy model from an access policy''s class scheme, backed by aggregate value evidence from the served data, and show them as a diff before writing anything. Use when the user asks to "classify the model", "tag PHI/PII", "label sensitive fields", or adds fields to a package that a policy governs, and before running malloy-compliance-review on a model nobody has classified.'
+version: 0.1.49
+---
+
+<!--
+Copyright (c) Credible Data Inc.
+SPDX-License-Identifier: MIT
+-->
+
+# Classifying a Malloy Model Against a Policy
+
+> A classification says which of the policy's data classes a field carries. It is what every
+> other control reads: `#(carries)` on an analytical domain is checked against it at load, the
+> agent sees it on every `get_context` card, and the compliance review checks it against the
+> values. This skill proposes classes. A person approves them. Nothing is written until they do.
+
+Two kinds of evidence decide a field's class, and neither is enough alone:
+
+- **The values** prove a floor. A column of `123-45-6789` is a Social Security number whatever it
+  is called. A text field with one distinct value per patient singles out a person whatever it is
+  called. The values cannot say *which* day-level dates the policy treats as direct identifiers.
+- **The policy's class table** decides the rest, by what the field means: its name, its `#(doc)`,
+  the column it reads. A diagnosis code is `phi.clinical` because the table says conditions are,
+  not because of its values.
+
+A field is never proposed below its floor. Above the floor, the class table decides.
+
+## Before you start
+
+You need a running Publisher serving the package, and the policy. The profiling runs as a persona
+the policy admits to each domain, so you also need the part of a control register that names the
+classes, the personas and who is admitted where. If the package has a register (usually
+`policies/controls.json`), use it. If not, draft these keys from the policy and show them to the
+user first; `skill:malloy-compliance-review` (`reference/register.md`) describes each one:
+
+```json
+{
+  "classes": ["phi.direct_identifier", "phi.quasi_identifier", "phi.clinical", "phi.financial", "none"],
+  "identifier_classes": { "direct": ["phi.direct_identifier"], "quasi": ["phi.quasi_identifier"] },
+  "subjects": ["patient"],
+  "personas": { "clinician": { "givens": { "ROLES": ["clinical"], "ORGANIZATIONS": ["…"] } } },
+  "access": { "patient_chart": { "clinician": "scoped" } }
+}
+```
+
+`subjects` names the joins whose records are the individuals the policy protects. A text field
+reached through one of them with a distinct value for nearly every individual is a name, an
+address or a license number, and the floor for it is a direct identifier.
+
+## Workflow
+
+### 1. Read the scheme
+
+Find the policy's class table: each class, what it means, and its examples. Use the class names
+exactly as the policy writes them. If the policy has no table, stop and say so: inventing a scheme
+is the policy owner's decision, not yours.
+
+### 2. Collect the evidence (aggregates only)
+
+The script lives in `skill:malloy-compliance-review`. From the package directory:
+
+```bash
+C=<skills>/malloy-compliance-review/scripts/compliance.py
+python3 $C profile --environment <env> --package <pkg> --register policies/controls.json --out profile.json
+python3 $C propose --profile profile.json --register policies/controls.json --out proposals.md
+```
+
+`profile` runs one aggregate query per published dimension: counts, distinct counts, lengths,
+pattern-match counts and a numeric range. It never selects a row. `propose` turns that into one
+row per field with its value floor, the basis for it, and how the field is declared today. Read
+`proposals.md`; never read rows of the data into the conversation to classify them. If a domain
+cannot be profiled (no persona admits it), say which, and classify its fields by the class table
+alone.
+
+What each signal proves (`skill:malloy-compliance-review` `reference/checks.md` has the thresholds):
+
+| Signal | Least class |
+| --- | --- |
+| `ssn`, `email`, `phone`, `uuid` (a record identifier), `unique_per_subject` (one value per protected individual) | direct identifier |
+| `date_day`, `zip5`, `near_unique` (one value per row at the domain's own grain, such as a timestamp) | quasi-identifier |
+| `year`, `zip3`, `free_text` | none: a hint for the class table, never a floor |
+
+The verdicts:
+
+| Verdict | Meaning | What you do |
+| --- | --- | --- |
+| Declared below what its values prove | The current class is lower than the floor | Propose the floor or higher. This is the finding that matters most |
+| Undeclared | No class yet | Propose one: the floor, or the class table if it says higher |
+| Declared at or above its value floor | Consistent | Keep it unless the class table says higher |
+| A hint, not a floor | Years, three-digit codes, free text | The class table decides; say what the hint was |
+| No value evidence | Nothing in the values | The class table decides, by meaning |
+
+### 3. Decide each field
+
+The evidence has one row per field *path*, and a path can stand for several definitions: `patient`
+may join a different patient source on each domain, and `patient.age` may be capped on one and not
+on another. Before deciding, list every definition behind each row (step 4 says how to find them)
+and decide each definition on its own.
+
+Measures are not profiled, but every published field needs a class. Decide them by the class table
+and lineage: a measure over a classified field inherits that field's class, and a plain `count()`
+reads nothing, so it needs a declaration; the policy usually says what a count carries.
+
+For each field, in order:
+
+1. **Start at the floor.** Never propose below it. If you believe the floor is wrong, say why and
+   keep the field at the floor until the user decides.
+2. **Apply the class table.** Match the field's meaning to the table's rows and examples. When the
+   table names the thing (birth date, medical record number), that row wins. When two rows fit, take
+   the more protective one and say so. The class table outranks the policy's prose for
+   classification: a list of identifiers to remove for de-identification (HIPAA Safe Harbor) is what
+   the de-identification controls enforce, not a second class table. Where the two disagree, follow
+   the table and mark the field for the policy owner.
+   For a field with a `uuid` floor, confirm whose record it is from its `#(doc)` and the join keys
+   that read it: a record of a protected individual (a patient, an encounter of a patient) is a
+   direct identifier; a record of anything else goes to the policy owner.
+3. **Apply the derivation rule.** A field derived from a classified one carries its input's class
+   unless the policy reduces it (a birth year from a birth date, under a de-identification control).
+   Publisher's lineage follows Malloy field references, including through joins, and never raw
+   columns: `birth_year is BIRTHDATE.year` reads a column, inherits nothing, and needs its own
+   declaration, while `birth_year is birth_date.year` inherits `birth_date`'s class. Do not declare
+   a class a field already inherits. Where the policy reduces one, declare the reduced class and
+   name the control that allows it in the field's `#(doc)`.
+4. **Propose, then ask** when the class table does not name a field. Propose the most protective
+   class that fits its meaning and mark it for the policy owner with one question. Demographics,
+   state, units and specialties are typical. Never leave a field unproposed.
+5. **One class per regime.** A list is for a field under several regimes at once
+   (`["phi.direct_identifier", "gdpr.personal"]`), not for two classes of the same scheme. When two
+   classes of one scheme fit, step 2 decides.
+
+### 4. Place each declaration where the field is defined
+
+A class is declared on the dimension or measure that defines the field, usually in the package's
+core sources rather than on each analytical domain. A field defined on a domain itself is
+classified there. A field reached through a join takes
+the class declared where it lives, so `patient.ssn` is classified on `ssn` in the patient source,
+not on every domain that joins it. Find the definition with the `.malloy` files: for each domain
+the row lists, follow the join named by the path into the source that domain joins, and take the
+last segment's definition there. Two domains may join two different sources under one name; each
+definition gets its own annotation.
+
+The form is one quoted class, or a quoted, comma-separated list when a field sits under several
+regimes. One `#(classification)` per field; a second is malformed:
+
+```malloy
+#(doc) The patient's Social Security number.
+#(classification) "phi.direct_identifier"
+dimension: ssn is SSN
+
+#(classification) ["phi.direct_identifier", "gdpr.personal"]
+dimension: email is EMAIL
+```
+
+`docs/classification.md` is the reference, including how lineage and `#(carries)` read these.
+
+### 5. Show the diff and wait
+
+Present one table, every field that would change first:
+
+| Field | Defined in | Now | Value floor | Proposed | Basis |
+| --- | --- | --- | --- | --- | --- |
+| `patient.first_name` | `core.malloy` `patients_core` | `none` | direct | `phi.direct_identifier` | One value per patient; the table lists names |
+| `conditions.condition` | `core.malloy` `conditions_core` | -- | -- | `phi.clinical` | No value evidence; the table lists conditions |
+
+`--` under Now means undeclared; `none` means declared `none`.
+
+Then the fields that keep their class, briefly, and every field you need the policy owner to
+answer. **Do not edit a `.malloy` file until the user approves.** Approval of some rows is approval
+of those rows only.
+
+### 6. Write, reload, verify
+
+After approval:
+
+1. Add the annotations to the defining sources.
+2. `reload_package` (or `GET …/packages/<pkg>?reload=true`). A reload that fails is safe: the
+   previous model keeps serving and the errors come back. A `#(carries)` refusal here means a
+   domain now exposes a class it does not declare; that is the classification working. Report it,
+   do not widen `#(carries)` to make it go away; widening a domain's ceiling is a policy decision.
+3. Check `get_status` (or `GET /api/v0/status`) for a `stale: true` entry.
+4. Run the review's coverage and value checks, which fail any published field left unclassified or
+   declared below its values: `python3 $C check … --out-dir review`, then read `review/report.md`.
+
+## Rules
+
+- **Aggregates only.** Classify from `profile` output and the class table. A sample of rows from a
+  field that might hold identifiers is the disclosure the classification exists to prevent.
+- **Never below the floor**, and never lower an existing class without the user's explicit approval
+  of that row. Lowering a class can admit data to a domain that excluded it.
+- **The policy's vocabulary, exactly.** Publisher reads the shape and never the words, so a typo is
+  a new class that no `#(carries)` lists.
+- **One place per field.** Declare at the definition; let lineage carry it.
+- **Propose, don't write.** The output of this skill is a diff a person approves.

package/skills/malloy-compliance-review/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: malloy-compliance-review
+description: 'Check a Malloy package and its controls against a written access policy: turn the policy''s prose into a control register, run compliance.py check against a served package (structure, access as each role, and the values themselves), judge what needs a person, and produce a report and a signable attestation. Use when the user asks whether a model "complies with", "satisfies" or "meets" a policy, HIPAA, SOC 2, PCI or the like, asks for a compliance review or attestation, or wants the review in CI.'
+version: 0.1.49
+---
+
+<!--
+Copyright (c) Credible Data Inc.
+SPDX-License-Identifier: MIT
+-->
+
+# Reviewing a Malloy Package Against an Access Policy
+
+> A policy is prose: who may read which data, and under what conditions. A compliant package is
+> controls a machine checks: gates on the analytical domains, classifications on the fields, a
+> ceiling on what each domain carries. This skill connects the two. It writes the policy down as a
+> register of checks, runs them against the served package, and reports each control as holding,
+> failing, needing a person, or not provable from the model at all.
+
+The review has two halves, and they are kept apart on purpose:
+
+- **The register** (`policies/controls.json`) is the policy as checks. You draft it from the prose;
+  the policy owner approves it. It changes when the policy changes.
+- **The check** (`scripts/compliance.py check`) runs the register against the package as it is
+  served. It changes nothing, reads only aggregates, and exits 1 when a control fails, so the same
+  command gates every change in CI.
+
+What Publisher already refuses at load (a domain exposing a class its `#(carries)` omits, a gate
+on a given the caller can set, a join that reaches a gated source around its gate) the check
+reports as the control it breaks. It does not re-derive them.
+
+## Before you start
+
+- A Publisher serving the package, reachable over REST (default `http://localhost:4000`). Run the
+  review against a server with **no gateway in front**: each persona's givens are sent with the
+  request and honored, which is how the check asks "what would this role see". Never point it at a
+  production endpoint, where a trusted tier sets those givens and the probe would be meaningless.
+- The policy document.
+- A classified model. If fields are unclassified, `skill:malloy-classify` first.
+
+## Workflow
+
+### 1. Draft the register from the policy
+
+Read the whole policy. For each numbered requirement, write one control with its id and text as
+the policy states them, and the checks that prove it. Then the context the checks need: the class
+scheme, the personas the policy names, what each persona may read on each domain, and the rules on
+particular domains (de-identified, never carries a class, a cap). `reference/register.md` is the
+format and `reference/checks.md` says what each check proves.
+
+Rules for drafting:
+
+- **One control per requirement, in the policy's words.** The attestation quotes them back.
+- **A control with no check is `not_provable_here`**, with a `why` naming who can prove it (a log
+  store's retention, a training record). Saying so is a result, not a gap to paper over.
+- **Name a persona for every workforce class the policy names**, and one that should be refused
+  (a partner without an agreement). The refusals are half of what the access check proves.
+- **Givens come from the model.** A persona's givens are the model's `#(secure)` givens, named
+  exactly; `get_context` lists them on each domain, and the package read lists every one under `secureGivens`.
+
+Show the register to the user and stop for approval. It is the policy owner's statement of what
+the policy means; you drafted it.
+
+### 2. Run the check
+
+From the package directory:
+
+```bash
+python3 <skills>/malloy-compliance-review/scripts/compliance.py check \
+  --environment <env> --package <pkg> --register policies/controls.json --out-dir review
+```
+
+It reads the package read's classification summary, the model read's gates, `get_context` over
+the MCP endpoint (`--mcp`, default `http://127.0.0.1:4040/mcp`) and `GET /api/v0/status`. It probes
+every published domain as every persona with a count, queries every source the package does not
+publish (read from the `.malloy` files in the current directory, or `--package-dir`) to confirm it
+refuses, and profiles every published dimension with aggregates (seconds to a minute for 140
+fields). It writes `review/report.json` and `review/report.md`. Exit 0 means no
+control fails.
+
+### 3. Judge what needs a person
+
+Read `review/report.md`. `reference/report.md` explains each section. For each control:
+
+- **Holds**: report it with its evidence. Do not restate it as stronger than the evidence.
+- **FAILS**: name the domain and field from the finding, the requirement it breaks, and the
+  smallest change to the model that would fix it. A failure the server refused at load (the report
+  says the package is serving a stale model) is already contained: the change was not deployed.
+  Say both.
+- **Needs review**: a value check that could not decide (free text on a de-identified domain, a
+  probe that errored). Look at the evidence and say what you concluded and why; if it needs the
+  policy owner, say so.
+- **Not provable here**: say who can prove it.
+
+Do not fix the model in the same step. Report first; a fix is a separate change that goes through
+the same review.
+
+### 4. Attest
+
+```bash
+python3 <skills>/malloy-compliance-review/scripts/compliance.py attest \
+  --report review/report.json --out review/attestation.md
+```
+
+The attestation lists every control with its status and signature lines for the policy owner.
+It is generated from the report, not edited: if a status is wrong, fix the register or the model
+and rerun.
+
+### 5. In CI
+
+Run the same `check` on every change to a `.malloy` file, against a Publisher started on the
+change's checkout, and fail the build on exit 1. `docs/compliance-review.md` has a GitHub Actions
+example. Upload `review/` as the build's artifact so the evidence travels with the change.
+
+## Rules
+
+- **Aggregates only.** The check never selects a row. Do not add a query that does, and do not
+  read rows to investigate a finding: the finding's evidence is a count for that reason.
+- **The register is approved, not inferred.** Never change an expected outcome to make a check
+  pass. A check that fails because the register is wrong is fixed by the policy owner.
+- **Report, then fix.** A review that edits what it reviews proves nothing.
+- **Exact names.** Domain, persona and given names in the register must match the served model;
+  the check refuses an unknown check name and reports an unknown domain as a failure.

package/skills/malloy-compliance-review/reference/checks.md

@@ -0,0 +1,50 @@
+<!--
+Copyright (c) Credible Data Inc.
+SPDX-License-Identifier: MIT
+-->
+
+# The checks
+
+Each check reads one of four things: the package read's classification summary (each published
+domain's `#(carries)` and its field count by class), the model read (each domain's gates and which
+givens are `#(secure)`), `get_context` (each published dimension with its classes), or the server
+status. The rest are aggregate queries run as the register's personas. None reads a row.
+
+| Check | Fails when | Reads |
+| --- | --- | --- |
+| `inventory` | The package read has no classification summary, or `get_context` could not list the published fields | package read, `get_context` |
+| `loads` | The package did not load, or serves a stale model because its latest files were refused. One finding per refusal, tagged with the domain and kind (`ceiling`, `secure`, `join`) | `/api/v0/status` |
+| `refusals` | Never fails on a refusal: a refused change is evidence that a violating change is not deployed | `/api/v0/status` |
+| `coverage` | A published field has no class | package read |
+| `gated` | A published domain has neither `#(authorize)` nor a row filter | model read |
+| `secure_gates` | A gate reads a given that is not `#(secure)` | model read |
+| `locked_bases` | A source the package does not publish answers a count to an identity holding every role the register names. Its sources are read from the package's `.malloy` files and queried through each file's own path; with no files found it needs review | package files, a count per source |
+| `ceiling` | A domain declares no `#(carries)`, declares a class its `must_not_carry` forbids, or serves a class beyond it | package read, register |
+| `access` | A persona's outcome on a domain differs from the register, or the register names a domain the package does not publish | a count per domain per persona |
+| `values` | A field's values prove more than its class allows, a de-identified domain serves day dates, five-digit ZIPs or uncapped values. Free text there needs review | `get_context`, an aggregate profile per field |
+
+## What the values prove
+
+`values` runs one aggregate query per published dimension, as a persona admitted to its domain:
+the row count, the filled count, the distinct count, lengths, and how many values match each
+pattern. A signal counts when at least half the filled values match.
+
+| Signal | Means | Least class |
+| --- | --- | --- |
+| `ssn`, `email`, `phone` | The values are that kind of identifier | direct |
+| `uuid` | Record identifiers | direct |
+| `unique_per_subject` | A text field through a `subjects` join with a distinct value for at least 85% of the individuals that have one, over 50 or more | direct |
+| `date_day` | Dates to the day | quasi |
+| `zip5` | Five-digit ZIP codes | quasi |
+| `near_unique` | At the domain's own grain, distinct values for at least 90% of 500 or more rows | quasi |
+| `year`, `zip3`, `free_text` | Hints only; never fail a class | -- |
+
+A floor is a lower bound. A birth date's values show dates to the day, a quasi-identifier; the
+policy's class table makes it direct. The check fails a field declared *below* its floor, never one
+declared above.
+
+## Scoping
+
+A check runs once per review, however many controls name it. A control that names `values:research`
+takes only the findings about `research`; if every finding is about another domain, the control
+holds for that check and the report says nothing it found touches `research`.

package/skills/malloy-compliance-review/reference/register.md

@@ -0,0 +1,74 @@
+<!--
+Copyright (c) Credible Data Inc.
+SPDX-License-Identifier: MIT
+-->
+
+# The control register
+
+The register is a policy written as checks: one JSON file, usually `policies/controls.json` in the
+package, beside the policy it was drafted from. `compliance.py` reads it; nothing in Publisher
+does. [`examples/clinical-records/policies/controls.json`](../../../examples/clinical-records/policies/controls.json)
+is a complete one for a HIPAA minimum-necessary policy.
+
+## Keys
+
+| Key | Required | What it is |
+| --- | --- | --- |
+| `policy` | yes | Path to the policy document, relative to the package. Quoted in the report. |
+| `version` | yes | The policy version or approval date the register was drafted from. |
+| `classes` | yes | Every class the policy defines, exactly as `#(classification)` spells them. |
+| `identifier_classes` | yes | `{"direct": [...], "quasi": [...]}`: which classes identify a person outright and which in combination. The value checks read these. |
+| `subjects` | no | Join names whose records are the individuals the policy protects (`["patient"]`). A text field through one of them with a distinct value per individual must be a direct identifier. |
+| `personas` | yes | `{id: {"class": "...", "givens": {...}}}`: one per workforce class the policy names, plus the ones it refuses. `givens` are the model's `#(secure)` givens, named exactly. |
+| `access` | yes | `{domain: {persona: outcome}}`: what each persona gets from each published domain. An omitted pair means `refused`. |
+| `domains` | no | Rules on particular domains, below. |
+| `controls` | yes | The policy's requirements, below. |
+
+### Access outcomes
+
+| Outcome | Means | Proven by |
+| --- | --- | --- |
+| `rows` | Admitted, with every row | The count probe answers, and the domain has no row filter |
+| `scoped` | Admitted, with only the rows its givens select | The count probe answers, and the model read shows a row filter in force |
+| `refused` | Not admitted | The count probe answers 403 |
+
+`scoped` is read from the model's row filter, never from a smaller count: a persona may be the only
+one admitted to a domain and still be scoped.
+
+### Domain rules
+
+```json
+"research": {
+  "deidentified": true,
+  "must_not_carry": ["phi.direct_identifier"],
+  "caps": [{ "field": "patient.age", "max": 90 }]
+}
+```
+
+- `deidentified`: the domain may serve no day-level date, no five-digit ZIP, and nothing that reads
+  as free text.
+- `must_not_carry`: classes the domain's `#(carries)` may not list.
+- `caps`: a numeric field's maximum, as the values show it.
+
+### Controls
+
+```json
+{ "id": "MN-04", "text": "A researcher reads de-identified data and nothing else.",
+  "checks": ["access:research", "ceiling:research", "values:research"] }
+```
+
+- `id` and `text` are the policy's, verbatim.
+- `checks` name what proves the control. A check scoped with `:domain` takes only that domain's
+  findings; `loads:` also takes a refusal kind (`ceiling`, `secure`, `join`).
+- A control nothing in the model can prove takes `"status": "not_provable_here"` and a `why`.
+- `why` on any control is printed in the report beside it.
+
+`reference/checks.md` lists every check.
+
+## Drafting it
+
+Work requirement by requirement. For each, ask what in a served package would show it holding:
+a gate (`gated`, `secure_gates`), a classification (`coverage`, `values`), a ceiling (`ceiling`),
+an answer to a role (`access`), a refusal (`loads`). If the answer is "nothing in the package", it
+is `not_provable_here`; name who proves it. Show the draft to the policy owner before the first
+run, and treat their edits as the policy's meaning.