testguard-cli 0.19.0__tar.gz → 0.20.1__tar.gz

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/.jules/README.md

@@ -61,6 +61,19 @@ branch `main`. Paste the prompt verbatim.
 | runner-scout | Weekly, Wednesday | `Follow .jules/routines/runner-scout.md exactly. Read .jules/RULES.md first. If preflight prints STOP, end the task with no changes and no pull request.` |
 | docs-drift | Weekly, Friday | `Follow .jules/routines/docs-drift.md exactly. Read .jules/RULES.md first. If preflight prints STOP, end the task with no changes and no pull request.` |
 
+**A new task can show `Inactive`.** A task created from the Task Input box
+can stay `Inactive` even though its menu offers "Pause schedule". Pause it,
+then resume it, and it shows `Active`. Check the badge after creating each
+task, because an `Inactive` task never runs.
+
+**The VM is a shallow clone.** Jules runs `git clone --depth 1` and sets a
+global `core.hooksPath /dev/null`.
+
+- The routines only diff against `origin/main` and build scratch worktrees
+  from `HEAD`, so both work in that clone.
+- Do not write a routine step that needs history, such as `git log` over
+  many commits or `replay` over old fixes.
+
 That is three tasks a week at most. On the free plan's 15 tasks a day the
 quota is never the limit; the review queue is.
 

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/.pre-commit-hooks.yaml

@@ -7,7 +7,7 @@
 #
 #     repos:
 #       - repo: https://github.com/raccioly/testguard
-#         rev: v0.19.0
+#         rev: v0.20.1
 #         hooks:
 #           - id: testguard-claims        # fast: validates the claims file + drift
 #           - id: testguard-gate          # fast: every changed source file must carry a claim

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.1] - 2026-10-12
+
+Automated weekly release — everything merged since `v0.20.0`.
+
+### Changed
+
+- chore(homebrew): sha256 for v0.20.0 (#216)
+
+
+## [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`.

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.19.0
+Version: 0.20.1
 Summary: 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. A wrapper that runs the Node.js CLI (requires Node.js 20+): a project-local node_modules/testguard-cli when present, otherwise the npm release of this same version through npx.
 Project-URL: Homepage, https://github.com/raccioly/testguard
 Project-URL: Documentation, https://github.com/raccioly/testguard#readme
@@ -153,9 +153,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.1` |
 | 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.1/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).

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/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.1` |
 | 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.1/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).

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/action.yml

@@ -50,7 +50,7 @@ inputs:
   version:
     description: 'testguard-cli version to run'
     required: false
-    default: '0.19.0'
+    default: '0.20.1'
   node-version:
     description: 'Node.js version (20+)'
     required: false

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/docs/guides/ci/github-actions.md

@@ -100,7 +100,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0               # the base branch must exist locally
-      - uses: raccioly/testguard@v0.19.0
+      - uses: raccioly/testguard@v0.20.1
         with:
           command: gate                # every changed source file needs a claim
 
@@ -114,7 +114,7 @@ jobs:
         with:
           node-version: 22
       - run: npm ci                    # the probe runs the project's own test runner
-      - uses: raccioly/testguard@v0.19.0
+      - uses: raccioly/testguard@v0.20.1
         with:
           command: probe
           severity: high               # fail only on new high or critical findings
@@ -162,7 +162,7 @@ jobs:
             testguard-evidence-
 
       - id: testguard
-        uses: raccioly/testguard@v0.19.0
+        uses: raccioly/testguard@v0.20.1
         with:
           command: probe
 
@@ -211,7 +211,7 @@ the probe at the interpreter if it is not one TestGuard finds on its own
         with:
           python-version: '3.12'
       - run: python -m venv .venv && .venv/bin/pip install -r requirements.txt
-      - uses: raccioly/testguard@v0.19.0
+      - uses: raccioly/testguard@v0.20.1
         with:
           command: probe
           runner: python             # pytest if .venv can import it, else unittest
@@ -227,7 +227,7 @@ Each project in a monorepo gets its own step, because a passing parent gate
 says nothing about a child project's coverage:
 
 ```yaml
-      - uses: raccioly/testguard@v0.19.0
+      - uses: raccioly/testguard@v0.20.1
         with:
           command: gate
           working-directory: services/billing
@@ -245,7 +245,7 @@ run that verified nothing must not look like a pass. During adoption set
 `allow-empty`:
 
 ```yaml
-      - uses: raccioly/testguard@v0.19.0
+      - uses: raccioly/testguard@v0.20.1
         with:
           command: probe
           allow-empty: 'true'

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/docs/guides/ci/gitlab.md

@@ -17,7 +17,7 @@ move together:
 
 ```yaml
 include:
-  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.19.0/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.20.1/packaging/gitlab/testguard.gitlab-ci.yml'
     inputs:
       dir: backend          # where testguard.claims.json lives (default ".")
       post_note: true       # post the brief on the merge request; needs TESTGUARD_GITLAB_TOKEN

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/docs/guides/ci/pre-commit.md

@@ -34,7 +34,7 @@ gate that sees a commit before it exists.
 default_install_hook_types: [pre-commit, pre-push]
 repos:
   - repo: https://github.com/raccioly/testguard
-    rev: v0.19.0
+    rev: v0.20.1
     hooks:
       - id: testguard-claims
         stages: [pre-commit]

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/docs/guides/monorepo.md

@@ -215,12 +215,12 @@ jobs:
           node-version: 22
       - run: npm ci               # every workspace's dependencies, from the root
       - name: gate
-        uses: raccioly/testguard@v0.19.0
+        uses: raccioly/testguard@v0.20.1
         with:
           command: gate
           working-directory: ${{ matrix.project }}
       - name: probe
-        uses: raccioly/testguard@v0.19.0
+        uses: raccioly/testguard@v0.20.1
         with:
           command: probe
           working-directory: ${{ matrix.project }}

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/docs/guides/writing-claims.md

@@ -96,6 +96,23 @@ lowest, but a label never waives a finding. `producedBy.producer` is separate:
 it records who *wrote the entry*, while `source` records where the *intent*
 came from.
 
+### Naming the requirement a claim defends
+
+`source.ref` is free text, except that the `req:` prefix is reserved for a
+structured requirement reference:
+
+```json
+"source": { "kind": "spec", "ref": "req:acme.billing#FR-003" }
+```
+
+The part before `#` is the spec ID and the part after it is the requirement
+ID. A requirement-tracing tool can then tell which evidence speaks for which
+requirement without guessing from a file path; DocGuard uses it to report the
+tests that cite a changed requirement as re-verified. The form must be
+declared with `kind: "spec"`. A malformed `req:` reference, or one under
+another kind, fails validation. TestGuard never resolves it, so a spec ID that
+does not exist is still valid here; the consumer checks it.
+
 ## Faults
 
 A fault is one concrete way the claim could be false, written as an exact

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/docs/i18n/es/README.md

@@ -147,9 +147,9 @@ falsa.
 | npm | `npm i -D testguard-cli` y luego `npx testguard probe` |
 | pip | `pip install testguard-cli` y luego `testguard probe` (requiere 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.1` |
 | 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.1/packaging/gitlab/testguard.gitlab-ci.yml` |
 
 Los requisitos, las instalaciones sin conexión, `ENOVERSIONS` y todas las
 opciones de CI están en la

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/docs/i18n/pt-BR/README.md

@@ -145,9 +145,9 @@ a cobertura. O TestGuard o admite porque ele falha quando a alegação é falsa.
 | npm | `npm i -D testguard-cli` e depois `npx testguard probe` |
 | pip | `pip install testguard-cli` e depois `testguard probe` (requer 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.1` |
 | 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.1/packaging/gitlab/testguard.gitlab-ci.yml` |
 
 Requisitos, instalações offline, `ENOVERSIONS` e todas as opções de CI estão
 no [guia de instalação](https://github.com/raccioly/testguard/blob/main/docs/installation.md).

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/docs/i18n/zh-CN/README.md

@@ -85,9 +85,9 @@ expect(store.writeAudit).toHaveBeenCalledWith(
 | npm | `npm i -D testguard-cli`，然后 `npx testguard probe` |
 | pip | `pip install testguard-cli`，然后 `testguard probe`（需要 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.1` |
 | pre-commit | `repo: https://github.com/raccioly/testguard`，钩子 `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.1/packaging/gitlab/testguard.gitlab-ci.yml` |
 
 环境要求、离线安装、`ENOVERSIONS` 以及所有 CI 选项，见
 [安装指南](https://github.com/raccioly/testguard/blob/main/docs/installation.md)。

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/docs/installation.md

@@ -31,9 +31,9 @@ packages in total.
 | npm devDependency | `npm i -D testguard-cli` then `npx testguard probe` | a JavaScript or TypeScript project: version pinned in the lockfile, and the local install the agent layer prefers |
 | pip | `pip install testguard-cli` then `testguard probe` | a Python team that does not want to touch npm directly (still needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` | a machine-wide `testguard` on `PATH` |
-| GitHub Action | `uses: raccioly/testguard@v0.19.0` | CI on GitHub |
+| GitHub Action | `uses: raccioly/testguard@v0.20.1` | CI on GitHub |
 | pre-commit | `repo: https://github.com/raccioly/testguard` with a release tag as `rev:` ([below](#pre-commit)) | local hooks on commit and push |
-| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.19.0/packaging/gitlab/testguard.gitlab-ci.yml` | CI on GitLab |
+| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.20.1/packaging/gitlab/testguard.gitlab-ci.yml` | CI on GitLab |
 
 ### npx
 
@@ -114,7 +114,7 @@ tarball, checked against a `sha256` recorded at release time.
 ```yaml
 - uses: actions/checkout@v7
   with: { fetch-depth: 0 }
-- uses: raccioly/testguard@v0.19.0
+- uses: raccioly/testguard@v0.20.1
   with: { command: gate }
 ```
 
@@ -128,7 +128,7 @@ and complete pull-request and main-branch workflows, are in
 ```yaml
 repos:
   - repo: https://github.com/raccioly/testguard
-    rev: v0.19.0
+    rev: v0.20.1
     hooks:
       - id: testguard-claims
       - id: testguard-gate
@@ -144,7 +144,7 @@ three hooks, their stages and their arguments are in
 
 ```yaml
 include:
-  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.19.0/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.20.1/packaging/gitlab/testguard.gitlab-ci.yml'
     inputs: { dir: . }
 ```
 

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/docs/testguard-explained.html

@@ -144,7 +144,7 @@
 <div class="page">
   <div class="masthead">
     <div class="wordmark">Test<span class="mark">Guard</span></div>
-    <div class="meta">Technical Brief · v0.19.0 · MIT</div>
+    <div class="meta">Technical Brief · v0.20.1 · MIT</div>
   </div>
 
   <h1>Your tests pass. That is not the same as your tests working.</h1>

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "testguard-cli",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "testguard-cli",
-      "version": "0.19.0",
+      "version": "0.20.1",
       "license": "MIT",
       "dependencies": {
         "ajv": "8.20.0"

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "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",

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/packaging/gitlab/testguard.gitlab-ci.yml

@@ -3,7 +3,7 @@
 # Include it from a project's .gitlab-ci.yml, pinned to a release:
 #
 #   include:
-#     - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.19.0/packaging/gitlab/testguard.gitlab-ci.yml'
+#     - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.20.1/packaging/gitlab/testguard.gitlab-ci.yml'
 #       inputs:
 #         dir: backend            # where testguard.claims.json lives (default ".")
 #         post_note: true         # post the brief as a merge-request note (needs TESTGUARD_GITLAB_TOKEN, api scope)
@@ -33,7 +33,7 @@ spec:
   inputs:
     version:
       description: testguard-cli version to run
-      default: "0.19.0"
+      default: "0.20.1"
     dir:
       description: directory whose test runner is invoked (where testguard.claims.json lives)
       default: "."

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/packaging/homebrew/testguard.rb

@@ -15,8 +15,8 @@
 class Testguard < Formula
   desc "Proves a test suite defends the claims a project makes"
   homepage "https://github.com/raccioly/testguard"
-  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.19.0.tgz"
-  sha256 "15ed175733cb66aa3ae5e5ee5ea1465d035c99280989bf4c15256a97ec3beb83"
+  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.20.1.tgz"
+  sha256 "fe8c6f147c301c579da51006c5ccdcc5281058e9df3ca3fa70781011cde7c13c"
   license "MIT"
 
   depends_on "node"

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "testguard-cli"
-version = "0.19.0"
+version = "0.20.1"
 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. A wrapper that runs the Node.js CLI (requires Node.js 20+): a project-local node_modules/testguard-cli when present, otherwise the npm release of this same version through npx."
 readme = "README.md"
 license = { text = "MIT" }

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/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

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/spec/conformance/origins.test.mjs

@@ -5,6 +5,7 @@ import { rank } from '../../src/probe/rank.mjs';
 import { fileURLToPath } from 'node:url';
 import { scaffoldFile } from '../../src/scaffold/scaffold.mjs';
 import { poolDrafts } from '../../src/sweep/pool.mjs';
+import { REQUIREMENT_REF_PATTERN, requirementRef } from '../lib/origins.mjs';
 
 const kinds = ['spec', 'adr', 'annotation', 'comment', 'manual', 'doc', 'bug', 'incident', 'review', 'inferred'];
 const example = (kind) => JSON.parse(readFileSync(new URL(`./examples/${kind}.json`, import.meta.url), 'utf8'));
@@ -64,3 +65,59 @@ describe('declared claim origins — vocabulary, not authenticated independence'
     expect(kinds.slice(5).map(score)).toEqual([0.9, 0.9, 0.9, 0.9, 0.9]);
   });
 });
+
+// The contract table in GATE-SEMANTICS.md "Declared claim origins": the schema
+// and requirementRef() must accept exactly the same structured references.
+describe('structured requirement references — req:<spec-id>#<requirement-id>', () => {
+  const rows = [
+    [{ kind: 'spec', ref: 'req:acme.billing#FR-003' }, true, { specId: 'acme.billing', requirementId: 'FR-003' }],
+    [{ kind: 'spec', ref: 'req:Acme_Billing-2#NFR-01.2' }, true, { specId: 'Acme_Billing-2', requirementId: 'NFR-01.2' }],
+    [{ kind: 'spec', ref: `req:${'a'.repeat(128)}#${'R'.repeat(64)}` }, true, { specId: 'a'.repeat(128), requirementId: 'R'.repeat(64) }],
+    [{ kind: 'spec', ref: 'specs/001/spec.md#FR-003' }, true, null],
+    [{ kind: 'spec', ref: 'requirement FR-003' }, true, null],
+    [{ kind: 'spec' }, true, null],
+    [{ kind: 'doc', ref: 'docs/spec.md#req:acme#FR-1' }, true, null],
+    [{ kind: 'spec', ref: 'req:acme.billing' }, false, null],
+    [{ kind: 'spec', ref: 'req:#FR-1' }, false, null],
+    [{ kind: 'spec', ref: 'req:acme#' }, false, null],
+    [{ kind: 'spec', ref: 'req:acme billing#FR-1' }, false, null],
+    [{ kind: 'spec', ref: 'req:a/b#FR-1' }, false, null],
+    [{ kind: 'spec', ref: 'req:acme#FR-1#x' }, false, null],
+    [{ kind: 'spec', ref: 'req:acme#1FR' }, false, null],
+    [{ kind: 'spec', ref: 'req:acme:x#FR-1' }, false, null],
+    [{ kind: 'spec', ref: 'req:.acme#FR-1' }, false, null],
+    [{ kind: 'spec', ref: 'req:acme#FR-1\n' }, false, null],
+    [{ kind: 'spec', ref: `req:${'a'.repeat(129)}#FR-1` }, false, null],
+    [{ kind: 'spec', ref: `req:acme#R${'0'.repeat(64)}` }, false, null],
+    [{ kind: 'doc', ref: 'req:acme#FR-1' }, false, null],
+    [{ kind: 'inferred', ref: 'req:acme#FR-1' }, false, null],
+  ];
+  for (const format of ['claims', 'evidence']) {
+    it.each(rows)(`${format}: %o is valid=%s`, (source, valid) => {
+      const doc = example(format);
+      const target = sourceOf(format, doc);
+      for (const key of Object.keys(target)) delete target[key];
+      Object.assign(target, source);
+      const result = validate(format, doc);
+      expect(result.ok, JSON.stringify(result.errors)).toBe(valid);
+      if (!valid) expect(result.errors.some((e) => /\/source(?:\/(?:ref|kind))?$/.test(e.path ?? e.instancePath ?? ''))).toBe(true);
+    });
+  }
+  it.each(rows)('requirementRef(%o) parses only what the schema admits as structured', (source, valid, parsed) => {
+    expect(requirementRef(source)).toEqual(parsed);
+    if (parsed) expect(valid).toBe(true);
+  });
+  it('exports one pattern the schema shares', () => {
+    const common = JSON.parse(readFileSync(new URL('../schemas/common.schema.json', import.meta.url), 'utf8'));
+    const ref = common.$defs.claimSource.properties.ref;
+    expect(ref.pattern).toContain(REQUIREMENT_REF_PATTERN.source.replace(/^\^/, '').replace(/\$$/, ''));
+    for (const schema of ['claims', 'evidence']) {
+      expect(readFileSync(new URL(`../schemas/${schema}.schema.json`, import.meta.url), 'utf8')).toContain('urn:claimspec:v1:common#/$defs/claimSource');
+    }
+  });
+  it('rejects malformed or non-object sources without guessing', () => {
+    for (const source of [undefined, null, 'req:acme#FR-1', { ref: 'req:acme#FR-1' }, { kind: 'spec', ref: 42 }]) {
+      expect(requirementRef(source)).toBe(null);
+    }
+  });
+});

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/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

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/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"

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/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",

{testguard_cli-0.19.0 → testguard_cli-0.20.1}/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"