testguard-cli 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-10-11
+
+Automated weekly release — everything merged since `v0.19.0`.
+
+### Changed
+
+- feat(spec): structured requirement references in source.ref (#214)
+- docs(jules): note the Inactive-schedule quirk and the shallow VM clone (#213)
+- chore(homebrew): sha256 for v0.19.0 (#212)
+
+
+### Added
+
+- Structured requirement references: a claim's `source.ref` may name the requirement it defends as `req:<spec-id>#<requirement-id>` (kind `spec`). A malformed `req:` reference, or one under another kind, now fails validation; every other reference stays opaque. The claim source is now defined once in `common.schema.json` (`$defs/claimSource`), and `requirementRef()` in `spec/lib/origins.mjs` parses the same pattern. Older readers accept the form as an opaque string. This is the format DocGuard's requirement anchors read to report the tests that cite a changed requirement as re-verified.
+
 ## [0.19.0] - 2026-10-11
 
 Automated weekly release — everything merged since `v0.18.3`.

package/README.md

@@ -129,9 +129,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.19.0` |
+| GitHub Action | `uses: raccioly/testguard@v0.20.0` |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-gate`, `testguard-probe` |
-| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.19.0/packaging/gitlab/testguard.gitlab-ci.yml` |
+| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.20.0/packaging/gitlab/testguard.gitlab-ci.yml` |
 
 Requirements, offline installs, `ENOVERSIONS` and every CI option are in the
 [installation guide](https://github.com/raccioly/testguard/blob/main/docs/installation.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Breaks your code on purpose and reports every promise your tests did not notice breaking. Mutation testing bound to the claims a project makes — vitest, jest, Playwright, pytest and unittest.",
   "type": "module",
   "license": "MIT",

package/spec/GATE-SEMANTICS.md

@@ -16,6 +16,24 @@ These are declarations, not authentication of independence, chronology,
 production occurrence or correctness. The optional reference remains opaque
 metadata (at most 512 characters); verification does not fetch it. Producer
 provenance and measured test independence are separate signals.
+
+One prefix is reserved. A `ref` that starts with `req:` is a structured
+requirement reference, `req:<spec-id>#<requirement-id>`, with `<spec-id>`
+matching `[A-Za-z0-9][A-Za-z0-9._-]{0,127}` and `<requirement-id>` matching
+`[A-Za-z][A-Za-z0-9._-]{0,63}`. It must be declared with kind `spec`.
+Validation rejects a malformed one at `/source/ref` and one under another kind
+at `/source/kind`; it is never degraded to opaque, because a typo would
+otherwise read as "no evidence for this requirement". Every other `ref` stays
+opaque. A structured reference is still a declaration. TestGuard does not
+resolve it, fetch the spec or check that the requirement exists. A consumer
+that keeps a requirement index, such as DocGuard, compares
+`<spec-id>#<requirement-id>` exactly against its own keys. `requirementRef()`
+in `spec/lib/origins.mjs` parses the same pattern the shared
+`$defs/claimSource` declares. Older readers accept the form as an opaque string,
+so adopting it needs no upgrade; only readers with this rule catch a malformed
+one. The reference is claim metadata: editing it makes saved evidence for that
+claim stale, as any source edit does. Fingerprints, verdicts and gates do not
+change.
 Adding kinds does not change verdicts, baseline/fingerprint identity or default
 gates. Existing ranking weights stay unchanged; new kinds use the existing 0.9
 fallback, not an invented strength hierarchy. Existing documents remain valid

package/spec/lib/origins.mjs

@@ -5,6 +5,25 @@ import { isDeepStrictEqual } from 'node:util';
 const common = JSON.parse(readFileSync(new URL('../schemas/common.schema.json', import.meta.url), 'utf8'));
 export const CLAIM_SOURCE_KINDS = Object.freeze([...common.$defs.claimSourceKind.enum]);
 const kindSet = new Set(CLAIM_SOURCE_KINDS);
+
+/**
+ * A structured requirement reference, `req:<spec-id>#<requirement-id>`, read
+ * from the one pattern the shared schema declares (`$defs/claimSource`). It is
+ * a declaration: nothing here resolves the spec or checks the requirement
+ * exists. Consumers compare `specId#requirementId` exactly.
+ */
+const sourceRef = common.$defs.claimSource.properties.ref.pattern;
+// The schema's second alternative is the structured form; the first keeps every other ref opaque.
+export const REQUIREMENT_REF_PATTERN = new RegExp(`^${sourceRef.slice(sourceRef.indexOf('|^') + 2)}`, 'u');
+const REQUIREMENT_REF_PARTS = /^req:([^#]+)#(.+)$/u;
+
+/** `{ specId, requirementId }` for a valid structured `spec` reference; `null` for anything else. */
+export function requirementRef(source) {
+  if (!source || typeof source !== 'object' || source.kind !== 'spec' || typeof source.ref !== 'string') return null;
+  if (!REQUIREMENT_REF_PATTERN.test(source.ref)) return null;
+  const [, specId, requirementId] = REQUIREMENT_REF_PARTS.exec(source.ref);
+  return { specId, requirementId };
+}
 const counts = () => Object.fromEntries(CLAIM_SOURCE_KINDS.map((kind) => [kind, 0]));
 
 // Consumers validate their full document first. These narrow guards prevent

package/spec/schemas/claims.schema.json

@@ -46,21 +46,7 @@
           "maxLength": 2000
         },
         "source": {
-          "description": "Declared origin of claim intent. A source label or opaque reference does not authenticate independence, chronology or correctness. Producer provenance and measured test independence are separate.",
-          "type": "object",
-          "required": [
-            "kind"
-          ],
-          "properties": {
-            "kind": {
-              "$ref": "urn:claimspec:v1:common#/$defs/claimSourceKind"
-            },
-            "ref": {
-              "type": "string",
-              "maxLength": 512
-            }
-          },
-          "additionalProperties": false
+          "$ref": "urn:claimspec:v1:common#/$defs/claimSource"
         },
         "severity": {
           "$ref": "urn:claimspec:v1:common#/$defs/severity"

package/spec/schemas/common.schema.json

@@ -77,6 +77,22 @@
       "description": "Declared origin of claim intent, not authenticated independence or an evidence-strength order. References remain opaque; producer provenance and measured test independence are separate.",
       "enum": ["spec", "adr", "annotation", "comment", "manual", "doc", "bug", "incident", "review", "inferred"]
     },
+    "claimSource": {
+      "description": "Declared origin of claim intent. A source label or reference does not authenticate independence, chronology or correctness. Producer provenance and measured test independence are separate. `ref` is opaque, except that the `req:` prefix is reserved for a structured requirement reference, `req:<spec-id>#<requirement-id>`, which must be declared with kind `spec`. Neither form is ever resolved or fetched.",
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": { "$ref": "#/$defs/claimSourceKind" },
+        "ref": {
+          "type": "string",
+          "maxLength": 512,
+          "pattern": "^(?!req:)[\\s\\S]*$|^req:[A-Za-z0-9][A-Za-z0-9._-]{0,127}#[A-Za-z][A-Za-z0-9._-]{0,63}$"
+        }
+      },
+      "additionalProperties": false,
+      "if": { "type": "object", "required": ["ref"], "properties": { "ref": { "type": "string", "pattern": "^req:" } } },
+      "then": { "properties": { "kind": { "const": "spec" } } }
+    },
     "nestedProject": {
       "description": "Changed files delegated to a separately validated descendant TestGuard project. This is not coverage or evidence; run that project's gate separately.",
       "type": "object",

package/spec/schemas/evidence.schema.json

@@ -339,20 +339,7 @@
               "$ref": "urn:claimspec:v1:common#/$defs/severity"
             },
             "source": {
-              "type": "object",
-              "required": [
-                "kind"
-              ],
-              "properties": {
-                "kind": {
-                  "$ref": "urn:claimspec:v1:common#/$defs/claimSourceKind"
-                },
-                "ref": {
-                  "type": "string",
-                  "maxLength": 512
-                }
-              },
-              "additionalProperties": false
+              "$ref": "urn:claimspec:v1:common#/$defs/claimSource"
             },
             "producedBy": {
               "$ref": "urn:claimspec:v1:common#/$defs/provenance"