@matthew-cochran/crossmatrix 0.0.0-stage → 0.3.1

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@matthew-cochran/crossmatrix",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "npx launcher for the crossmatrix MCP server (multidimensional House of Quality): downloads the verified release binary for your platform, runs it over stdio, and ships the crossmatrix agent skills.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "crossmatrix",
+    "house-of-quality",
+    "qfd",
+    "crossmatrix-mcp"
+  ],
+  "license": "Apache-2.0",
+  "author": "Matthew Cochran <matthew@cochranweb.com>",
+  "homepage": "https://github.com/praxec/crossmatrix#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/praxec/crossmatrix.git",
+    "directory": "npm"
+  },
+  "bugs": {
+    "url": "https://github.com/praxec/crossmatrix/issues"
+  },
+  "bin": {
+    "crossmatrix-mcp": "bin/crossmatrix-mcp.js"
+  },
+  "files": [
+    "bin/crossmatrix-mcp.js",
+    "lib/install.js",
+    "lib/postinstall.js",
+    "lib/sync-skills.js",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "postinstall": "node lib/postinstall.js",
+    "prepack": "node lib/sync-skills.js",
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/crossmatrix/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: crossmatrix
+description: "Method reference for the crossmatrix-mcp tools (crossmatrix.command and crossmatrix.query): a generic, multidimensional House of Quality / weighted cross-reference matrix. Use when you build, fill or read any crossmatrix model, or when no narrower crossmatrix-* skill fits. Covers the Configuration / Dimensions / State split, observation-only writes (tokens plus evidence, never numbers), the driver loop (gaps.next, observe, analyze), scoped slices, optimistic versions and requestIds, links, and the committed .crossmatrix/ store."
+---
+
+# crossmatrix
+
+crossmatrix keeps a sparse, weighted cross-reference between **dimensions** (lists of
+things: needs, characteristics, jobs, tests, risks, deliverables...). You make the
+judgments; the engine does every number. Domain meaning lives in your configuration and
+in these skills, never in the engine.
+
+## Three documents, linked by id@version
+
+| Layer | Holds | Op family |
+|---|---|---|
+| Configuration | scales, relation declarations, contractions | `scale.declare`, `relation.declare`, `contraction.declare` |
+| Dimensions | dimensions and their members (rosters, weights) | `dimension.register`, `members.sync`, `member.propose` |
+| State | cells: observations on member pairs | `observe`, `evidence.attach`, `deprecate` |
+
+Findings are computed on every read and are never stored.
+
+## The store: `.crossmatrix/` (commit it)
+
+Run `crossmatrix-mcp init` once at the repo root. It creates `.crossmatrix/` with
+`config/<configId>@<version>.json`, `dimensions/<dimensionSetId>@<version>.json`,
+`state/<stateId>.json`, an append-only `audit/<stateId>.jsonl` (union-merged), a README and
+a `.gitattributes`. Files are canonical JSON, so diffs are small. **Commit the folder.** Run
+`crossmatrix-mcp check` after merges and in CI; it exits 1 with path-specific diagnostics.
+
+The server picks its store from `CROSSMATRIX_DIR`, else the nearest `.crossmatrix/` above
+its working directory, else a per-user data directory. Confirm `root` in `model.status`
+before you write.
+
+## Calling the tools
+
+Every write is one `crossmatrix.command`:
+
+```json
+{"request": {"schemaVersion": "0.2.0", "requestId": "obs-0007", "modelId": "checkout",
+  "expectedVersion": 6, "actor": {"actorType": "llm", "persona": "observer"},
+  "op": {"kind": "observe", "relationId": "rel_need_char", "from": "need_fast",
+         "to": "char_latency", "observation": "strong", "provenanceClass": "inferred",
+         "evidence": [{"sourceRef": {"sourceRef": "docs/perf.md", "locator": "L10-L24"}}]}}}
+```
+
+- `requestId` is an idempotency key: resending it replays the first answer.
+- `expectedVersion` is the version you last saw. A `version_conflict` means someone else
+  wrote; re-read `model.status` and retry.
+- Every response, including a rejection, carries `links`: the legal next ops. A rejection
+  carries `error.code`; fix the cause the code names, then follow a link.
+
+Reads are `crossmatrix.query` with `{"request": {"query": {"kind": "...", ...}}}`.
+
+## Observation-only
+
+- A cell value is a **token** from the relation's scale (`none|weak|moderate|strong` or
+  whatever the scale declares), never a number.
+- Member importance is a `weightObservation` token from the dimension's `weightScale`. A
+  numeric `weight` is accepted only from a deterministic source with `sourceRef.system`
+  (for example an FMECA criticality import).
+- `provenanceClass`: `normative` (a decision), `observed` (measured or seen), `inferred`
+  (your judgment; **evidence is required**). A `measuredValue` needs `observed` plus a
+  `sourceRef`.
+- Support and opposition are separate relations (`supports` vs `opposes`, `mitigates` vs
+  `exposes`), so strong-for and strong-against never cancel; the engine reports net and
+  tension.
+
+## Build a model
+
+1. `model.open` with `stateId` (creates it if absent; reopens it after a restart).
+2. `scale.declare` your relationship scale and an importance scale.
+3. `dimension.register` each axis (`dimensionKind` is any snake_case word; set
+   `weightScale` on weighted axes), then `members.sync` its roster.
+4. `relation.declare` each pair of axes (`from == to` is a correlation roof), with a
+   `coveragePolicy` (`every_from`, `every_to`, `both`) when gaps must be filled.
+5. `contraction.declare` a chain when you need a derived A→C view through B.
+
+## The driver loop
+
+Do not fill cells in bulk from memory. Let the engine pick:
+
+1. `gaps.next` → the most important uncovered members.
+2. Open the evidence, then `observe` one cell (token + rationale + evidence).
+3. Repeat until `gaps.next` is empty or the remaining gaps are knowingly `none`.
+4. `analyze.findings`, `conflicts`, `coverage`, `analyze.marginalize` for priorities.
+
+## Scoped reads
+
+Never ask for the whole model when a slice answers the question: `describe` (structure),
+`slice {relationId, from?, to?}`, `trace {member}`, `explain {relationId, from, to}`,
+`coverage`, `gaps.orphans`. Use `export` only to hand the model to another tool, and
+`report` for a human-readable House of Quality.
+
+## Large rosters, hierarchies and sources
+
+- Sync rosters straight from their source (files, tickets, tests) with a per-member
+  `sourceRef {"uri": "file://src/lib.rs", "hash": "sha256:..."}`. `members.sync` handles
+  10k+ members; re-sending an unchanged roster is a no-op (no new version).
+- Model nesting (directory contains file, epic contains story) as a `contains`
+  self-relation, parent → child. Add `rollup: true` to `trace`, `slice`, `coverage`,
+  `gaps.next` or `analyze.*` to roll leaf observations up to ancestors.
+- `trace {"member": "<id or uri>"}` and `slice {"relationId", "from"|"to": "<id or uri>"}`
+  work in both directions and page with `limit` / `cursor` (`nextCursor`).
+- `stale {"hashes": {"<uri>": "<hash>"}}` (or `"readFiles": true` for `file://` sources
+  inside the project) returns the changed members and every cell that rests on them.
+
+## Changing your mind
+
+Never delete. `deprecate {targetId, reason, supersededBy?}` retires a member or relation;
+deprecated elements leave analyses but stay in history. A re-synced roster deprecates
+members that disappeared from the source.
+
+Narrower skills: [crossmatrix-hoq](../crossmatrix-hoq/SKILL.md),
+[crossmatrix-jtbd](../crossmatrix-jtbd/SKILL.md),
+[crossmatrix-competitive](../crossmatrix-competitive/SKILL.md),
+[crossmatrix-test-coverage](../crossmatrix-test-coverage/SKILL.md),
+[crossmatrix-risk](../crossmatrix-risk/SKILL.md),
+[crossmatrix-prioritize](../crossmatrix-prioritize/SKILL.md),
+[crossmatrix-review](../crossmatrix-review/SKILL.md).

package/skills/crossmatrix-competitive/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: crossmatrix-competitive
+description: "Benchmark customer needs against competitors (including your own product) with crossmatrix-mcp and find the gaps worth winning: high-importance needs every competitor serves weakly. Use when the user asks for competitive benchmarking, a competitor matrix, a QFD planning matrix, or where to differentiate."
+---
+
+# Needs × competitors
+
+Read [crossmatrix](../crossmatrix/SKILL.md) first.
+
+## Model
+
+- Reuse the weighted needs from a House of Quality ([crossmatrix-hoq](../crossmatrix-hoq/SKILL.md))
+  or register `dim_need` with `weightScale: "importance"`.
+- `dimension.register {"dimensionId": "dim_competitor", "dimensionKind": "competitor"}` and
+  `members.sync` the competitors **and your own product** (`attributes.self: true`). Give
+  each a `sourceRef` to the page, review or teardown you assessed.
+- `scale.declare` a performance scale, e.g. `absent|poor|fair|good|best` (0/1/3/6/9), with
+  rubric descriptions a second reviewer could apply the same way.
+- `relation.declare {"relationId": "rel_need_competitor", "from": "dim_need", "to": "dim_competitor", "relationType": "satisfies", "scale": "performance", "coveragePolicy": "both"}`.
+
+## Fill
+
+For each need and competitor, `observe` the performance token with evidence (screenshot
+path, review URL, test log) and `provenanceClass: "observed"` when you saw it yourself,
+`inferred` when you deduced it. Use `gaps.next` to keep the work in importance order.
+
+## Read
+
+- `slice {"relationId": "rel_need_competitor", "from": "<need>"}`: one need across all
+  competitors.
+- `analyze.marginalize {"relationId": "rel_need_competitor", "axis": "from"}`: competitors
+  ranked by importance-weighted performance (your product's rank is your position).
+- Gaps worth winning: needs with high importance where **no** competitor is above `fair`.
+  Read them from `report {"relationId": "rel_need_competitor"}` (weights and grid in one
+  place) and list them with their evidence. Gaps where only you are weak are catch-up work.
+- `coverage` shows needs or competitors you have not assessed yet.
+
+Feed the gaps worth winning into [crossmatrix-prioritize](../crossmatrix-prioritize/SKILL.md)
+as value drivers.

package/skills/crossmatrix-hoq/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: crossmatrix-hoq
+description: "Build a classic House of Quality (QFD) with crossmatrix-mcp: weighted customer needs (WHATs) against engineering characteristics (HOWs), the correlation roof between characteristics, technical-importance ranking and targets. Use when the user asks for a House of Quality, QFD, needs-to-characteristics matrix, or which engineering characteristics matter most."
+---
+
+# House of Quality with crossmatrix
+
+Read [crossmatrix](../crossmatrix/SKILL.md) first for the envelope, observation-only rules
+and the driver loop. Every op below is a `crossmatrix.command` `op`.
+
+## 1. Frame
+
+- `model.open {"stateId": "<product>-hoq", "aspect": "hoq", "title": "<product> House of Quality"}`
+- `scale.declare` the relationship scale (classic 0/1/3/9):
+
+```json
+{"kind": "scale.declare", "scale": {"id": "qfd", "levels": [
+  {"observation": "none", "value": 0, "description": "No relationship."},
+  {"observation": "weak", "value": 1, "description": "Indirect or minor effect."},
+  {"observation": "moderate", "value": 3, "description": "Contributes, not the main lever."},
+  {"observation": "strong", "value": 9, "description": "Primary mechanism."}]}}
+```
+
+- `scale.declare` an importance scale (`low` 1, `medium` 3, `high` 9) with rubric
+  descriptions the customer evidence can be checked against.
+
+## 2. Rooms
+
+- `dimension.register {"dimensionId": "dim_need", "dimensionKind": "customer_requirement", "weightScale": "importance"}`
+- `members.sync` the needs in the customer's words, each with `weightObservation` and a
+  `sourceRef` to the interview, survey or ticket it came from.
+- `dimension.register {"dimensionId": "dim_char", "dimensionKind": "engineering_characteristic"}`
+- `members.sync` measurable characteristics. Put the target and unit in `attributes`
+  (`{"target": "< 200", "unit": "ms"}`); the report prints a Targets table from them.
+
+## 3. Relations
+
+- `relation.declare {"relationId": "rel_need_char", "from": "dim_need", "to": "dim_char", "relationType": "satisfies", "scale": "qfd", "coveragePolicy": "every_from"}`
+  (every need must be served by something).
+- The roof is a self-relation on the characteristics. Use `supports` for synergies and
+  `opposes` for trade-offs, as two separate relations:
+  `relation.declare {"relationId": "roof_conflict", "from": "dim_char", "to": "dim_char", "relationType": "opposes", "scale": "qfd"}`.
+
+## 4. Fill (driver loop)
+
+`gaps.next` → `observe` one cell with rationale and evidence → repeat. Observe the roof
+only for pairs where a real trade-off or synergy exists. Do not fill `none` everywhere.
+
+## 5. Read the house
+
+- Technical importance: `analyze.marginalize {"relationId": "rel_need_char", "axis": "from"}`
+  rolls the needs up into a ranked list of characteristics (weight × strength).
+- Trade-offs: `conflicts` lists characteristics where opposition meets or beats support.
+- Gaps: `coverage` with the `every_from` policy flags needs no characteristic serves.
+- The full house: `report {"relationId": "rel_need_char"}` returns Markdown with weights,
+  the matrix, the roof, technical importance, targets, coverage and findings.
+
+Hand the ranked characteristics to [crossmatrix-prioritize](../crossmatrix-prioritize/SKILL.md)
+or to a planner, and finish with [crossmatrix-review](../crossmatrix-review/SKILL.md).

package/skills/crossmatrix-jtbd/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: crossmatrix-jtbd
+description: "Map jobs to be done against user segments and journey steps with crossmatrix-mcp, then contract the axes to see which journey steps carry the most weighted job importance per segment. Use when the user wants a JTBD map, a jobs-by-segment matrix, journey coverage of jobs, or to find under-served jobs and journey steps."
+---
+
+# Jobs to be done × segments × journeys
+
+Read [crossmatrix](../crossmatrix/SKILL.md) first. This is a three-axis model joined by a
+contraction.
+
+## Axes
+
+- `dimension.register {"dimensionId": "dim_segment", "dimensionKind": "user_segment", "weightScale": "importance"}`:
+  segments weighted by business importance (`weightObservation`), each with a `sourceRef`
+  to the research that defines it.
+- `dimension.register {"dimensionId": "dim_job", "dimensionKind": "jtbd_step"}`: jobs
+  phrased as "When <situation>, I want to <motivation>, so I can <outcome>" in the
+  `label`.
+- `dimension.register {"dimensionId": "dim_journey", "dimensionKind": "journey_step"}`:
+  the product's journey steps, in order (`attributes.order`).
+
+## Relations
+
+- `rel_segment_job` (`dim_segment` → `dim_job`, `relationType: "supports"`, scale
+  `importance-of-job`): how much this segment needs this job done. Declare a scale such as
+  `none|nice|important|critical` (0/1/3/9) with rubric descriptions.
+- `rel_job_journey` (`dim_job` → `dim_journey`, `relationType: "satisfies"`, scale `qfd`,
+  `coveragePolicy: "every_from"`): which journey steps get the job done.
+- `contraction.declare {"contractionId": "ctr_segment_journey", "chain": ["rel_segment_job", "rel_job_journey"], "weightCombination": "product"}`.
+
+## Fill
+
+Use the driver loop: `gaps.next`, then observe from interview notes or analytics, with
+evidence. Leave a cell empty rather than guessing `none`.
+
+## Read
+
+- `analyze.contract`: segment → journey-step findings, each with the path through the
+  jobs that carries the weight. The top rows are the steps to invest in for each segment.
+- `analyze.marginalize {"relationId": "rel_job_journey", "axis": "from"}`: journey steps
+  ranked by how much job importance they serve.
+- `coverage` / `gaps.orphans`: jobs that no journey step serves are the under-served jobs.
+- `report {"relationId": "rel_job_journey"}` for the Markdown matrix.
+
+Pairs with [crossmatrix-test-coverage](../crossmatrix-test-coverage/SKILL.md), which reuses
+the journey steps, and with [crossmatrix-prioritize](../crossmatrix-prioritize/SKILL.md).

package/skills/crossmatrix-prioritize/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: crossmatrix-prioritize
+description: "Rank deliverables against weighted value drivers with crossmatrix-mcp and hand the ranked list to a planner such as cpm-planner. Use when the user asks what to build first, wants a value-weighted backlog, or needs a priority order derived from needs, gaps, risks or competitive gaps rather than gut feel."
+---
+
+# Deliverables × value drivers
+
+Read [crossmatrix](../crossmatrix/SKILL.md) first.
+
+## Model
+
+- `dimension.register {"dimensionId": "dim_value", "dimensionKind": "business_metric", "weightScale": "importance"}`:
+  the value drivers (customer needs, gaps worth winning, risks to retire, revenue or cost
+  goals), each with a `weightObservation` and a `sourceRef` to where its importance comes
+  from. Reuse members from other crossmatrix models where they exist.
+- `dimension.register {"dimensionId": "dim_deliverable", "dimensionKind": "deliverable"}`
+  and `members.sync` the candidate deliverables (epics, features, fixes). Put effort or
+  duration hints in `attributes`; the engine does not use them, the planner does.
+- `scale.declare` a contribution scale (`none|weak|moderate|strong`, 0/1/3/9).
+- `relation.declare {"relationId": "rel_value_deliverable", "from": "dim_value", "to": "dim_deliverable", "relationType": "satisfies", "scale": "contribution", "coveragePolicy": "every_from"}`.
+- If a deliverable works against a driver (it adds risk, slows a goal), record that in a
+  separate `opposes` relation. Never lower the support token instead.
+
+## Fill
+
+Use the driver loop: `gaps.next`, then observe the contribution with rationale.
+
+## Rank and hand off
+
+1. `analyze.marginalize {"relationId": "rel_value_deliverable", "axis": "from"}`: the
+   ranked deliverables (value-weighted score, highest first).
+2. `conflicts`: deliverables with strong opposition; decide or split them before
+   planning.
+3. `coverage`: value drivers no deliverable serves (`every_from` makes them violations).
+4. Hand the ranked list to the planner. For cpm-planner, keep the order as the priority,
+   carry each deliverable's id, and add durations and dependencies there. Do not invent
+   numeric scores for the planner; pass the rank and the engine's score.
+
+Record the hand-off in the report: `report {"relationId": "rel_value_deliverable"}`.

package/skills/crossmatrix-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: crossmatrix-review
+description: "Review and sign off a crossmatrix model before it is relied on: run crossmatrix-mcp check, validate, conflicts, stale and coverage, produce the Markdown report, and walk a sign-off checklist. Use when the user asks to review, audit, validate or sign off a House of Quality or any crossmatrix model, or before committing .crossmatrix/ changes."
+---
+
+# Review and sign-off
+
+Read [crossmatrix](../crossmatrix/SKILL.md) first. Review is read-only: it never writes
+except to record fixes the reviewer approves.
+
+## 1. Integrity
+
+- `crossmatrix-mcp check` at the repo root: exit 0, no diagnostics. Fix any path it names.
+- `model.open {"stateId": "<id>"}`, then `model.status`: right `root` (the repo's
+  `.crossmatrix/`), expected version, counts.
+- `validate` returns `validated: true`.
+
+## 2. Evidence
+
+- `stale {"hashes": {...}}` with the current content hashes of every source you can
+  re-hash: each stale entry is a cell or weight whose source changed. Re-observe or
+  deprecate it.
+- `slice` the most important rows and confirm each `inferred` observation has evidence
+  that still says what the rationale claims.
+
+## 3. Findings
+
+- `conflicts`: every `conflict` (opposition ≥ support) needs a decision recorded in the
+  report or a design change.
+- `analyze.findings`: read the contributors of each finding; they name the cells that
+  drive it.
+- `coverage` / `gaps.orphans`: violations of a `coveragePolicy` must be closed or the
+  policy consciously relaxed.
+
+## 4. Report
+
+`report {}` (whole aspect) or `report {"relationId": "..."}`. Attach it to the PR or the
+review record. `export {"format": "model"}` gives the merged JSON for another tool.
+
+## Sign-off checklist
+
+- [ ] `crossmatrix-mcp check` passes and `.crossmatrix/` is committed.
+- [ ] Every weighted dimension has a weight on every active member, from a token or a
+      deterministic import.
+- [ ] No unresolved `conflict` findings, or each has a recorded decision.
+- [ ] No coverage violations, or each is accepted in writing.
+- [ ] No stale references.
+- [ ] Every `inferred` observation has evidence.
+- [ ] The top of the technical-importance or priority ranking matches the team's
+      understanding, or the disagreement is explained.
+- [ ] The report is attached to the review.

package/skills/crossmatrix-risk/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: crossmatrix-risk
+description: "Cross failure modes against components or requirements with crossmatrix-mcp: import FMECA criticality as deterministic weights, separate exposes from mitigates, and find unmitigated critical exposure. Pairs with fmeca-mcp. Use when the user wants a risk × component matrix, to tie an FMECA to the design, or to see which requirements carry the most failure exposure."
+---
+
+# Failure modes × components / requirements
+
+Read [crossmatrix](../crossmatrix/SKILL.md) first. Criticality comes from an FMECA (for
+example fmeca-mcp `report.export`), never from you.
+
+## Model
+
+- `dimension.register {"dimensionId": "dim_fail", "dimensionKind": "failure_mode", "system": "fmeca"}`.
+- `members.sync` the failure modes with their **imported** criticality as `weight` and a
+  deterministic `sourceRef` (`{"system": "fmeca", "sourceRef": "<session>/<fm id>", "contentHash": "..."}`).
+  A numeric weight without `sourceRef.system` is rejected (`observation_only`).
+- The design axis: components (`implementation_asset`) or requirements
+  (`customer_requirement`), synced from the repo or the requirements doc.
+- Two relations, never one signed scale:
+  - `rel_comp_exposes_fail` (`relationType: "exposes"`): the component can produce the
+    failure mode.
+  - `rel_comp_mitigates_fail` (`relationType: "mitigates"`): the component prevents or
+    detects it.
+- Optional chain to requirements: `contraction.declare {"contractionId": "ctr_req_exposure", "chain": ["rel_req_comp", "rel_comp_exposes_fail"]}`.
+
+## Fill
+
+Observe exposure and mitigation separately, with evidence (code path, design doc, test).
+Re-sync `dim_fail` whenever the FMECA changes; `stale` with the new hashes shows which
+cells rest on outdated failure modes.
+
+## Read
+
+- `analyze.contract`: requirement → failure exposure, with the components on the path.
+- `conflicts` / `analyze.findings`: failure modes where exposure meets or exceeds
+  mitigation (`conflict`, severity `block`), most critical first.
+- `analyze.marginalize {"relationId": "rel_comp_exposes_fail", "axis": "to"}`: components
+  ranked by criticality-weighted exposure.
+- Send unmitigated critical exposures back to fmeca-mcp as actions, and their components
+  to [crossmatrix-prioritize](../crossmatrix-prioritize/SKILL.md).

package/skills/crossmatrix-test-coverage/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: crossmatrix-test-coverage
+description: "Trace requirements or journey steps to tests with crossmatrix-mcp: a requirements × tests matrix whose orphans are untested requirements and orphan tests, weighted so the most important untested requirement comes first. Use when the user asks about test coverage of requirements, a traceability matrix, untested features, or which tests to write next."
+---
+
+# Requirements / journeys × tests
+
+Read [crossmatrix](../crossmatrix/SKILL.md) first.
+
+## Model
+
+- The WHAT axis: requirements (`dimensionKind: "customer_requirement"`) or journey steps
+  (`journey_step`, reused from [crossmatrix-jtbd](../crossmatrix-jtbd/SKILL.md)), weighted
+  with `weightObservation`.
+- `dimension.register {"dimensionId": "dim_test", "dimensionKind": "test_artifact"}`, then
+  `members.sync` the tests from the source: one member per test id, `sourceRef` pointing to
+  the file and test name (`{"sourceRef": "tests/checkout.rs", "locator": "fn pays_once"}`)
+  plus a `contentHash` of the file. Re-sync after test changes; removed tests are
+  deprecated, not deleted.
+- `scale.declare` a verification scale, e.g. `none|smoke|partial|full` (0/1/3/9).
+- `relation.declare {"relationId": "rel_req_test", "from": "dim_req", "to": "dim_test", "relationType": "verifies", "scale": "verification", "coveragePolicy": "every_from"}`.
+
+## Fill
+
+Read each test, then `observe` how fully it verifies each requirement it touches, with
+the assertion lines as evidence. Do not credit a test for a requirement it only executes
+without asserting on.
+
+## Read
+
+- `coverage`: with `every_from`, every uncovered requirement is a **violation** (untested).
+- `gaps.next`: untested requirements ordered by importance; write tests in that order.
+- `gaps.orphans`: tests that verify no requirement (dead or misfiled tests) and
+  requirements no test touches.
+- `stale {"hashes": {"tests/checkout.rs": "<current hash>"}}`: which recorded test
+  evidence changed since it was observed; re-observe those cells.
+- `report {"relationId": "rel_req_test"}` for the traceability matrix.
+
+Finish with [crossmatrix-review](../crossmatrix-review/SKILL.md) before a release.