testguard-cli 0.9.4 → 0.10.1

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-09-19
+
+Automated weekly release — everything merged since `v0.10.0`.
+
+### Changed
+
+- fix(probe): preserve repeated claim selections (#139)
+- chore(homebrew): sha256 for v0.10.0 (#138)
+
+
+### Fixed
+
+- Repeated `probe --claim` flags no longer collapse silently to the last value.
+  Repeated and comma-separated ids are flattened in first-seen order,
+  duplicates are collapsed, empty selections fail, and both human and JSON
+  partial-run output show requested versus probed ids and counts. Probe JSON is
+  now validated against the published status schema before it is emitted. The
+  singular `scaffold` and `admit` forms reject ambiguous repeated values.
+
+## [0.10.0] - 2026-09-19
+
+Automated weekly release — everything merged since `v0.9.4`.
+
+### Changed
+
+- feat(status): expose claimed source surface (#135)
+- chore(homebrew): sha256 for v0.9.4 (#136)
+
+
+### Added
+
+- `status` now makes the claim denominator visible: claimed versus current
+  source modules, coverage of the 20 highest-churn modules over a bounded
+  200-commit window, and specific unclaimed modules ranked by churn with
+  explicit path-risk signals. A clean project whose majority of modules are
+  still unclaimed is directed to scaffold the highest-churn gap. The existing
+  co-authorship caveat is also printed by both `status` and `probe`, rather
+  than remaining available only in JSON and the agent brief.
+
 ## [0.9.4] - 2026-09-19
 
 Automated weekly release — everything merged since `v0.9.3`.

package/README.md

@@ -127,9 +127,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.9.4` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.10.1` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
-| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.9.4/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
+| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.10.1/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
 less than that many days ago (`ENOVERSIONS`); install that one with
@@ -279,8 +279,12 @@ npx testguard-cli admit test/x.test.ts --claim X   # is this test green on HEAD
    because it fails when the claim is false.
 
    Practical loop: first pass `--no-escalate` (escalation re-runs the whole
-   suite N times per survivor); iterate on one claim with `--claim <ID>` and
-   either `--include-dirty` or `--in-place` (only fault target files must be
+   suite N times per survivor); iterate on one claim with `--claim <ID>`, or
+   select a batch with commas or repeated flags (`--claim A,B --claim C`).
+   Every occurrence is retained in first-seen order, duplicates are collapsed,
+   and partial human/JSON output names both the requested and probed counts, so
+   a green subset cannot masquerade as the selection the operator asked for.
+   Use either `--include-dirty` or `--in-place` (only fault target files must be
    clean there; test files may be dirty), optionally `--confirm 1` for a fast
    **provisional** signal — verdicts print with a `?`, evidence goes to
    `evidence-provisional.json`, and `baseline` refuses it; final pass with
@@ -469,12 +473,12 @@ detected base that does not resolve is a warning for `status` and `brief`
 # GitHub Actions
 - uses: actions/checkout@v4
   with: { fetch-depth: 0 }
-- uses: raccioly/testguard@v0.9.4
+- uses: raccioly/testguard@v0.10.1
   with: { command: gate }
 
 # GitLab CI — the component-shaped template: gate + probe, brief as an artifact and, opted in, as a merge-request note
 include:
-  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.9.4/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.10.1/packaging/gitlab/testguard.gitlab-ci.yml'
     inputs: { dir: backend, post_note: true }   # post_note needs TESTGUARD_GITLAB_TOKEN (api scope); one note, updated in place
 ```
 
@@ -633,9 +637,17 @@ things make that safe:
   *should* ship with its regression test — but a repository where every kill
   is co-authored has no independent verification, whatever its claim
   verification rate says. It is a **signal**: ranking reads it, verdicts never
-  do, and the brief says it in one line. Nothing else in this category
+  do, and `probe`, `status` and the brief all say it in one line. Nothing else in this category
   measures it, and agents saturate the tests they can see
   ([SpecBench](https://arxiv.org/abs/2605.21384)).
+- **Claimed surface is visible.** A clean probe is only about claims that
+  exist. `status` therefore reports claimed source modules over the current
+  module denominator, how many of the 20 highest-churn modules are claimed,
+  and the concrete unclaimed modules worth examining next over a bounded
+  200-commit window. Churn and path-risk signals stay separate; there is no
+  synthetic health score. When most modules remain unclaimed and the existing
+  evidence is clean, the next action expands the denominator instead of
+  congratulating the same small set of claims again.
 - **Gaming is visible.** The cheapest way to make a survivor disappear is to
   weaken its fault, not to write a test. Evidence records every fault's
   content hash; `status` lists any fault edited after it survived, with its

package/package.json

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

package/spec/GATE-SEMANTICS.md

@@ -344,6 +344,27 @@ the suppress-up-to-count semantics are identical.
   hidden. A file that mocks the subject is never a discovered defender: a
   mock cannot detect a fault in what it replaced.
 
+## Claimed source surface
+
+`status` reports the denominator that `probe` cannot: current, non-test source
+modules with a supported extension and outside the change gate's documented
+default exclusions. A module is claimed when at least one fault anchors to it.
+The document carries the claimed, unclaimed and total module counts.
+
+The report also names concrete unclaimed modules. It counts touches over at
+most the latest 200 commits, reports how many of the 20 highest-churn modules
+are claimed, and lists up to ten unclaimed modules in descending churn order.
+Security- and money-shaped path names are explicit tie-breaking signals, never
+semantic claims about a file. Churn, path risk and claim coverage remain raw
+facts: they are never collapsed into one health score.
+
+When existing evidence is clean but more source modules are unclaimed than
+claimed, the next action is to scaffold the highest-churn unclaimed module.
+Earlier correctness states still win: invalid anchors, stale evidence and
+unproven faults are repaired before expanding the denominator. Without git
+history the counts and concrete files remain available, while the document
+says history is unavailable and reports zero commits read.
+
 ## Claim coverage of a change
 
 `probe` asks whether the tests defend the claims that exist. It says nothing
@@ -415,6 +436,16 @@ new anchor is a semantic edit to the claim and must be reviewed and re-probed.
 `unclaimed-changes`, when a change reference is known). Its next action is
 `repair-fault`, naming the first fault and `testguard claims --check-anchors`.
 
+## Partial probe scope
+
+Every `--claim` occurrence contributes to the selection. Comma-separated ids
+inside each occurrence are flattened in first-seen order and duplicates are
+collapsed. An explicitly empty selection is a usage error, never a successful
+zero-record probe. Partial human output and the `probe --json` run wrapper name
+the requested and actually probed claim ids and counts. Commands whose
+`--claim` is singular (`scaffold` and `admit`) reject repeated or comma-separated
+values instead of silently choosing one.
+
 ## Severity floor
 
 `--severity <level>` gates only findings whose claim severity is at or above

package/spec/lib/validate.mjs

@@ -244,6 +244,19 @@ const semantic = {
     if (doc.invalidFaults?.length > 0 && doc.state !== 'invalid-anchors') errors.push({ path: '/state', message: 'invalid fault anchors are hidden behind a later state; invalid-anchors precedes every evidence state' });
     if (doc.evidenceSource && !doc.evidenceHead) errors.push({ path: '/evidenceHead', message: 'evidence was read, so the commit it describes must be recorded' });
     if (doc.changes && doc.changes.uncovered.length > 0 && !['no-claims', 'unclaimed-changes'].includes(doc.state)) errors.push({ path: '/state', message: 'uncovered changed files are hidden behind a later state; unclaimed-changes precedes every evidence state' });
+    if (doc.surface) {
+      if (doc.surface.claimedModules + doc.surface.unclaimedModules !== doc.surface.sourceModules) errors.push({ path: '/surface', message: 'claimedModules + unclaimedModules must equal sourceModules' });
+      if (doc.surface.highChurn.claimed > doc.surface.highChurn.modules) errors.push({ path: '/surface/highChurn/claimed', message: 'claimed high-churn modules cannot exceed the high-churn window' });
+      if (!doc.surface.history.available && doc.surface.history.commitsRead !== 0) errors.push({ path: '/surface/history/commitsRead', message: 'unavailable history must report zero commits read' });
+      if (new Set(doc.surface.rankedUnclaimed.map((item) => item.file)).size !== doc.surface.rankedUnclaimed.length) errors.push({ path: '/surface/rankedUnclaimed', message: 'ranked unclaimed modules must be unique' });
+    }
+    if (doc.run?.scope) {
+      const scope = doc.run.scope;
+      if (scope.requestedCount !== scope.requestedClaims.length) errors.push({ path: '/run/scope/requestedCount', message: 'requestedCount must equal requestedClaims.length' });
+      if (scope.probedCount !== scope.probedClaims.length) errors.push({ path: '/run/scope/probedCount', message: 'probedCount must equal probedClaims.length' });
+      const requested = new Set(scope.requestedClaims);
+      if (scope.probedClaims.some((id) => !requested.has(id))) errors.push({ path: '/run/scope/probedClaims', message: 'every probed claim must have been requested' });
+    }
     return errors;
   },
 

package/spec/schemas/status.schema.json

@@ -102,6 +102,130 @@
     "provisional": {
       "type": "boolean"
     },
+    "surface": {
+      "description": "The current claim denominator. A source module is a non-test file with a supported source extension that is not covered by the documented default exclusions. Churn is bounded recent git history and remains separate from path-risk signals; neither is collapsed into a score.",
+      "type": "object",
+      "required": ["sourceModules", "claimedModules", "unclaimedModules", "history", "highChurn", "rankedUnclaimed"],
+      "properties": {
+        "sourceModules": { "type": "integer", "minimum": 0 },
+        "claimedModules": { "type": "integer", "minimum": 0 },
+        "unclaimedModules": { "type": "integer", "minimum": 0 },
+        "history": {
+          "type": "object",
+          "required": ["available", "maxCommits", "commitsRead"],
+          "properties": {
+            "available": { "type": "boolean" },
+            "maxCommits": { "type": "integer", "minimum": 1 },
+            "commitsRead": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "highChurn": {
+          "description": "How many of the up-to-20 most changed source modules carry a claim.",
+          "type": "object",
+          "required": ["modules", "claimed"],
+          "properties": {
+            "modules": { "type": "integer", "minimum": 0, "maximum": 20 },
+            "claimed": { "type": "integer", "minimum": 0, "maximum": 20 }
+          },
+          "additionalProperties": false
+        },
+        "rankedUnclaimed": {
+          "description": "Up to ten concrete unclaimed modules, ordered by changes in the bounded history window; path-risk signals break ties and are reported explicitly.",
+          "type": "array",
+          "maxItems": 10,
+          "items": {
+            "type": "object",
+            "required": ["file", "changes", "riskSignals"],
+            "properties": {
+              "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
+              "changes": { "type": "integer", "minimum": 0 },
+              "riskSignals": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": { "enum": ["security", "money"] }
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "run": {
+      "description": "Present on probe --json: the validated status document plus the completed invocation's result. scope is present only for a partial --claim run.",
+      "type": "object",
+      "required": ["id", "evidence", "provisional", "records", "newSinceBaseline", "exitCode"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "evidence": { "type": "string", "minLength": 1, "maxLength": 4096 },
+        "provisional": { "type": "boolean" },
+        "records": { "type": "integer", "minimum": 0 },
+        "newSinceBaseline": { "type": "integer", "minimum": 0 },
+        "exitCode": { "enum": [0, 1] },
+        "scope": {
+          "type": "object",
+          "required": ["requestedClaims", "requestedCount", "probedClaims", "probedCount"],
+          "properties": {
+            "requestedClaims": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" }
+            },
+            "requestedCount": { "type": "integer", "minimum": 1 },
+            "probedClaims": {
+              "type": "array",
+              "uniqueItems": true,
+              "items": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" }
+            },
+            "probedCount": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "cost": {
+      "description": "Present when probe --json --cost is requested; derived only from the runs in the emitted evidence.",
+      "type": "object",
+      "required": ["totalMs", "totalRuns", "reusedRecords", "records", "claims", "defenders", "sharedDefenders"],
+      "properties": {
+        "totalMs": { "type": "number", "minimum": 0 },
+        "totalRuns": { "type": "integer", "minimum": 0 },
+        "reusedRecords": { "type": "integer", "minimum": 0 },
+        "records": { "type": "integer", "minimum": 0 },
+        "claims": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["claimId", "ms", "runs", "faults", "reused", "defenders"],
+            "properties": {
+              "claimId": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" },
+              "ms": { "type": "number", "minimum": 0 },
+              "runs": { "type": "integer", "minimum": 0 },
+              "faults": { "type": "integer", "minimum": 0 },
+              "reused": { "type": "integer", "minimum": 0 },
+              "defenders": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" }
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "defenders": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/costDefender" }
+        },
+        "sharedDefenders": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/costDefender" }
+        }
+      },
+      "additionalProperties": false
+    },
     "counts": {
       "type": "object",
       "required": [
@@ -349,5 +473,23 @@
       "$ref": "urn:claimspec:v1:common#/$defs/gitSha"
     }
   },
-  "additionalProperties": false
+  "additionalProperties": false,
+  "$defs": {
+    "costDefender": {
+      "type": "object",
+      "required": ["file", "ms", "runs", "claims"],
+      "properties": {
+        "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
+        "ms": { "type": "number", "minimum": 0 },
+        "runs": { "type": "integer", "minimum": 0 },
+        "claims": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
 }

package/src/brief/brief.mjs

@@ -1,5 +1,5 @@
 import { gate } from '../baseline/baseline.mjs';
-import { summarize, formatVerdict } from '../render.mjs';
+import { coAuthorshipWarning, summarize, formatVerdict } from '../render.mjs';
 
 export const HEADING = '## TEST BLINDSPOT CONTEXT';
 /** First line of every markdown brief, so a poster can find and update its own note instead of adding another. */
@@ -98,7 +98,7 @@ export function renderBriefText(brief, { hasBaseline, total, independence }) {
   }
   // L3: a kill written in the same change as the code it guards is not
   // independent evidence. One line, no per-item noise.
-  if (independence?.coAuthored) lines.push('', `${independence.coAuthored} of ${independence.kills} kills are co-authored with the code they defend — the test and the code were written in the same change, so those kills are not independent evidence.`);
+  if (independence?.coAuthored) lines.push('', coAuthorshipWarning(independence.coAuthored, independence.kills));
   if (brief.next) lines.push('', `NEXT [${brief.next.action}]: ${brief.next.command}`, `  why: ${brief.next.why}`);
   if (brief.items.length === 0) {
     lines.push('', 'Every probed claim is defended. Keep it that way: new claims need a fault and a test that fails on it.');

package/src/cli.mjs

@@ -46,7 +46,7 @@ probe
   --ref <commit>       probe this commit in the scratch worktree (default: HEAD). An explicit --ref is honoured even when
                        defender/target files are dirty: a warning names them, the evidence records them (repo.ignoredDirty)
   --ignore-dirty       probe HEAD as committed although defender/target files are dirty (same warning and record)
-  --claim <ID,ID>      probe only these claims; writes .testguard/evidence-partial.json
+  --claim <ID,ID>      probe only these claims; repeatable, order-preserving, and writes .testguard/evidence-partial.json
   --include-dirty      probe the working tree (a snapshot commit) instead of HEAD; uncommitted tests count
                        (without it, a dirty defender/target with the implicit HEAD is refused: the silent-mismatch trap)
   --verbose            also print each killed fault (default: only unproven ones, plus a count)
@@ -137,7 +137,7 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         ref: { type: 'string' },
         'ignore-dirty': { type: 'boolean', default: false },
         serial: { type: 'boolean', default: false },
-        claim: { type: 'string' },
+        claim: { type: 'string', multiple: true },
         fault: { type: 'string' },
         'include-dirty': { type: 'boolean', default: false },
         changed: { type: 'string' },

package/src/commands/admit.mjs

@@ -29,10 +29,19 @@ function findProjectDir(testAbs, claimsFlag) {
  * decision here can never disagree with the gate.
  */
 export async function admitCommand({ file, values, version }, io) {
-  if (!file || !values.claim) {
+  if (!file || !values.claim?.length) {
     io.err('usage: testguard admit <test-file> --claim <ID> [--fault <FID>] [--confirm <n>] [--json]');
     return 3;
   }
+  if (values.claim.length > 1 || values.claim[0].includes(',')) {
+    io.err('admit accepts exactly one --claim <ID>');
+    return 3;
+  }
+  const claimId = values.claim[0].trim();
+  if (!claimId) {
+    io.err('--claim must name one claim id');
+    return 3;
+  }
   const confirmRuns = Number(values.confirm);
   const budgetMs = Number(values.budget);
   if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
@@ -46,7 +55,6 @@ export async function admitCommand({ file, values, version }, io) {
   if (testRel.startsWith('..')) throw new PreconditionError(`${file} is outside the project directory ${projectDir}`);
 
   const all = loadClaims(values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir));
-  const claimId = values.claim.trim();
   const claim = all.claims.find((c) => c.id === claimId);
   if (!claim) throw new PreconditionError(`--claim: unknown claim id ${claimId}`);
   const faults = values.fault ? claim.faults.filter((f) => f.id === values.fault) : claim.faults;

package/src/commands/probe.mjs

@@ -9,11 +9,30 @@ import { computeStatus } from '../status/status.mjs';
 import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
 import { costReport, renderCost } from '../probe/cost.mjs';
 import { progressMode, stageReporter, clearStageLine, recordEvent, isProgressMode, progressStream } from '../probe/progress.mjs';
+import { validate } from '../../spec/lib/validate.mjs';
 export const provisionalEvidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence-provisional.json');
 
 export const evidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence.json');
 export const baselinePath = (projectDir) => join(projectDir, '.testguard', 'baseline.json');
 
+/** Every repeated/comma-separated --claim value, in first-seen order. */
+export function claimSelection(values) {
+  if (values === undefined) return undefined;
+  return [...new Set(values.flatMap((value) => value.split(',')).map((id) => id.trim()).filter(Boolean))];
+}
+
+/** Scope is invocation metadata, kept outside the evidence contract. */
+export function partialScope(only, records) {
+  if (!only) return undefined;
+  const probedClaims = [...new Set(records.map((record) => record.claim.id))];
+  return {
+    requestedClaims: only,
+    requestedCount: only.length,
+    probedClaims,
+    probedCount: probedClaims.length,
+  };
+}
+
 export async function probeCommand({ projectDir, values, version }, io) {
   const confirmRuns = Number(values.confirm);
   const budgetMs = Number(values.budget);
@@ -34,7 +53,11 @@ export async function probeCommand({ projectDir, values, version }, io) {
     io.err('claims file declares no claims; nothing to verify');
     return 2;
   }
-  const only = values.claim ? values.claim.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+  const only = claimSelection(values.claim);
+  if (only?.length === 0) {
+    io.err('--claim must name at least one claim id');
+    return 3;
+  }
   // A --claim run is partial evidence; keep it away from the canonical file unless --out says otherwise.
   const provisional = confirmRuns < 3;
   // Provisional and partial runs never overwrite the canonical evidence: only confirmed, complete runs may feed a baseline.
@@ -81,9 +104,13 @@ export async function probeCommand({ projectDir, values, version }, io) {
   writeSpecDoc('evidence', outPath, evidence);
 
   const g = gate(evidence.records, baseline, { severityFloor: values.severity });
+  const scope = partialScope(only, evidence.records);
   if (values.json) {
     const status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: outPath }), io.err);
-    io.out(JSON.stringify({ ...status, run: { id: evidence.run.id, evidence: outPath, provisional, records: evidence.records.length, newSinceBaseline: g.new.length, exitCode: g.new.length > 0 ? 1 : 0 }, ...(values.cost ? { cost: costReport(evidence.records) } : {}) }, null, 2));
+    const doc = { ...status, run: { id: evidence.run.id, evidence: outPath, provisional, records: evidence.records.length, newSinceBaseline: g.new.length, exitCode: g.new.length > 0 ? 1 : 0, ...(scope ? { scope } : {}) }, ...(values.cost ? { cost: costReport(evidence.records) } : {}) };
+    const result = validate('status', doc);
+    if (!result.ok) throw new Error(`probe JSON document does not conform: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
+    io.out(JSON.stringify(doc, null, 2));
     return g.new.length > 0 ? 1 : 0;
   }
   if (!values.quiet && baseline) {
@@ -102,7 +129,7 @@ export async function probeCommand({ projectDir, values, version }, io) {
     io.out(renderCost(costReport(evidence.records)));
     io.out('');
   }
-  io.out(`evidence: ${outPath}${only ? ` (partial: --claim ${only.join(',')}; not the canonical evidence file)` : provisional ? ' (provisional; not the canonical evidence file)' : ''}`);
+  io.out(`evidence: ${outPath}${scope ? ` (partial: ${scope.requestedCount} claim${scope.requestedCount === 1 ? '' : 's'} requested, ${scope.probedCount} probed: --claim ${scope.requestedClaims.join(',')}; not the canonical evidence file)` : provisional ? ' (provisional; not the canonical evidence file)' : ''}`);
   if (provisional && !values.quiet) io.err(PROVISIONAL_WARNING(confirmRuns));
   return g.new.length > 0 ? 1 : 0;
 }

package/src/commands/scaffold.mjs

@@ -10,6 +10,15 @@ export async function scaffoldCommand({ projectDir, file, values, version }, io)
     io.err('usage: testguard scaffold <source-file> [--claim <ID>] [--out <path>] [--json]');
     return 3;
   }
+  if (values.claim?.length > 1 || values.claim?.[0]?.includes(',')) {
+    io.err('scaffold accepts exactly one --claim <ID>');
+    return 3;
+  }
+  const claimId = values.claim?.[0]?.trim();
+  if (values.claim && !claimId) {
+    io.err('--claim must name one claim id');
+    return 3;
+  }
   const abs = resolve(file);
   if (!existsSync(abs)) throw new PreconditionError(`no such file: ${file}`);
   const rel = relative(projectDir, abs);
@@ -17,7 +26,7 @@ export async function scaffoldCommand({ projectDir, file, values, version }, io)
 
   const claimsPath = values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir);
   const existingClaims = existsSync(claimsPath) ? loadClaims(claimsPath) : undefined;
-  const { doc, stats } = scaffoldFile({ projectDir, file: rel, claimId: values.claim, existingClaims, toolVersion: version });
+  const { doc, stats } = scaffoldFile({ projectDir, file: rel, claimId, existingClaims, toolVersion: version });
 
   if (values.json) {
     io.out(JSON.stringify(doc, null, 2));

package/src/gate/changed.mjs

@@ -28,7 +28,7 @@ import { globToRegExp } from '../util/glob.mjs';
 export const SOURCE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py']);
 const TEST_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
 // Python names tests by file, not by a dotted suffix: `test_foo.py`, `foo_test.py`.
-const isTestFile = (f) => TEST_RE.test(f) || IS_PY_TEST.test(f);
+export const isTestFile = (f) => TEST_RE.test(f) || IS_PY_TEST.test(f);
 
 /** Files that are source by extension but never carry claims. Printed by --explain. */
 export const DEFAULT_EXCLUDES = Object.freeze([
@@ -42,6 +42,10 @@ export const DEFAULT_EXCLUDES = Object.freeze([
   '**/__snapshots__/**',
   '.testguard/**',
 ]);
+const DEFAULT_EXCLUDE_RES = DEFAULT_EXCLUDES.map(globToRegExp);
+
+/** Whether a source-shaped path is outside TestGuard's claimable module surface. */
+export const isDefaultExcluded = (file) => DEFAULT_EXCLUDE_RES.some((re) => re.test(file));
 
 export const defaultIgnorePath = (projectDir) => join(projectDir, 'testguard.ignore.json');
 
@@ -158,7 +162,7 @@ export function computeChangedGate({ projectDir, ref, includeDirty = false, excl
 
   const pathEntries = ignore.entries.filter((e) => e.kind === 'path').map((e) => ({ entry: e, re: globToRegExp(e.pattern), expired: isExpired(e, now), files: [] }));
   const userExcludes = exclude.map((g) => ({ glob: g, re: globToRegExp(g) }));
-  const defaultExcludes = DEFAULT_EXCLUDES.map((g) => ({ glob: g, re: globToRegExp(g) }));
+  const defaultExcludes = DEFAULT_EXCLUDES.map((g, i) => ({ glob: g, re: DEFAULT_EXCLUDE_RES[i] }));
 
   const excluded = [];
   const covered = [];

package/src/probe/probe.mjs

@@ -40,6 +40,16 @@ function readRunnerVersion(projectDir, name = 'vitest') {
   }
 }
 
+/** Validate and order a partial claim selection without losing caller order. */
+export function selectClaims(claims, only) {
+  if (!only) return claims;
+  if (only.length === 0) throw new PreconditionError('--claim must name at least one claim id');
+  const byId = new Map(claims.map((claim) => [claim.id, claim]));
+  const unknown = only.filter((id) => !byId.has(id));
+  if (unknown.length) throw new PreconditionError(`--claim: unknown claim id(s) ${unknown.join(', ')}`);
+  return only.map((id) => byId.get(id));
+}
+
 /**
  * Probe every fault of every claim. Returns a spec-conformant evidence
  * document; writing it is the caller's job.
@@ -76,18 +86,13 @@ export async function probe({
   const head = headSha(root, ref);
   if (!head) throw new PreconditionError(ref === 'HEAD' ? 'repository has no commits; every verdict is tied to a commit' : `ref ${ref} does not resolve to a commit`);
 
-  const targets = [...new Set(claims.claims.flatMap((c) => c.faults.map((f) => relative(root, join(projectDir, f.file)))))];
+  const scopedClaims = selectClaims(claims.claims, only);
+  const targets = [...new Set(scopedClaims.flatMap((c) => c.faults.map((f) => relative(root, join(projectDir, f.file)))))];
   if (mode === 'in-place' && isDirty(root, targets)) {
     throw new PreconditionError(`uncommitted changes in fault target files (${targets.join(', ')}); commit or stash them, or drop --in-place. Only the files faults are applied to must be clean — test files may be dirty, which is what makes --in-place usable while writing tests.`);
   }
   if (includeDirty && mode !== 'worktree') throw new PreconditionError('--include-dirty applies to worktree mode; drop --in-place');
   if (includeDirty && ref !== 'HEAD') throw new PreconditionError('--include-dirty snapshots the working tree; it cannot be combined with --ref');
-  const selected = only ? new Set(only) : null;
-  if (selected) {
-    const known = new Set(claims.claims.map((c) => c.id));
-    const unknown = [...selected].filter((id) => !known.has(id));
-    if (unknown.length) throw new PreconditionError(`--claim: unknown claim id(s) ${unknown.join(', ')}`);
-  }
 
   // Worktree mode probes a commit, not the working tree. Uncommitted defender
   // or target edits would be silently absent — the same survivors, no hint why.
@@ -103,8 +108,7 @@ export async function probe({
       if (isDirty(root)) snapshot = snapshotWorkingTree(root);
     } else {
       const watched = new Set(targets);
-      for (const claim of claims.claims) {
-        if (selected && !selected.has(claim.id)) continue;
+      for (const claim of scopedClaims) {
         const declared = claim.defendedBy?.length ? resolveDefenders(projectDir, claim.defendedBy) : claim.faults.flatMap((f) => discoverDefenders(projectDir, f.file));
         for (const d of declared) watched.add(relative(root, join(projectDir, d)));
         for (const g of claim.defendedBy ?? []) if (!g.includes('*')) watched.add(relative(root, join(projectDir, g)));
@@ -193,8 +197,7 @@ export async function probe({
       return Object.fromEntries([...groups].map(([r, group]) => [labelOf(r), group]));
     };
 
-    for (const claim of claims.claims) {
-      if (selected && !selected.has(claim.id)) continue;
+    for (const claim of scopedClaims) {
       const declared = claim.defendedBy?.length ? resolveDefenders(iso.projectDir, claim.defendedBy) : null;
       for (const fault of claim.faults) {
         // Mock-awareness: a discovered file that mocks the target is not a

package/src/render.mjs

@@ -5,6 +5,8 @@ export const formatVerdict = (v, provisional = false) => (v === 'killed' ? 'kill
 
 export const PROVISIONAL_WARNING = (n) => `PROVISIONAL — confirmRuns ${n} (< 3): nothing below is confirmed. Verdicts carry a "?"; this evidence cannot be frozen into a baseline. Re-run with --confirm 3 before trusting it.`;
 
+export const coAuthorshipWarning = (coAuthored, kills) => `${coAuthored} of ${kills} kills are co-authored with the code they defend — the test and the code were written in the same change, so those kills are not independent evidence.`;
+
 export function renderRecord(r, { provisional = false, showDiscovered = true } = {}) {
   const head = `${formatVerdict(r.verdict, provisional).padEnd(15)} ${r.claim.id}/${r.subject.id}`.padEnd(38);
   let why = '';
@@ -32,7 +34,10 @@ export function renderSummary(records, run) {
   const unproven = records.filter((r) => r.verdict !== 'killed');
   const claims = new Set(unproven.map((r) => r.claim.id)).size;
   const where = run ? ` Probed ${run.repo.snapshot ? `working tree (snapshot ${run.repo.snapshot.slice(0, 7)} of ${run.repo.head.slice(0, 7)})` : run.mode === 'in-place' ? `in place at ${run.repo.head.slice(0, 7)}${run.repo.dirty ? ' (dirty)' : ''}` : run.repo.head.slice(0, 7)}.` : '';
-  return `${run?.provisional ? 'PROVISIONAL: ' : ''}${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.${where}`;
+  const kills = records.filter((r) => r.verdict === 'killed');
+  const coAuthored = kills.filter((r) => r.detail.independence?.class === 'co-authored').length;
+  const quality = coAuthored ? `\n${coAuthorshipWarning(coAuthored, kills.length)}` : '';
+  return `${run?.provisional ? 'PROVISIONAL: ' : ''}${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.${where}${quality}`;
 }
 
 /** Survivors first, then by rank score; killed last. */

package/src/status/status.mjs

@@ -6,13 +6,18 @@ import { gate } from '../baseline/baseline.mjs';
 import { hashFile, sha256 } from '../util/hash.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
-import { sortForReport } from '../render.mjs';
+import { coAuthorshipWarning, sortForReport } from '../render.mjs';
 import { computeChangedGate, defaultIgnorePath } from '../gate/changed.mjs';
 import { headSha, isAncestor } from '../git.mjs';
 import { checkAnchorLocations } from '../claims/anchors.mjs';
+import { computeClaimedSurface, needsClaimExpansion } from './surface.mjs';
 
 export const faultContentHash = (fault) => sha256(`${fault.find}\n${fault.replace}`);
 
+const candidateReason = (surface, candidate) => surface.history.available
+  ? `${candidate.file}, the highest-churn unclaimed module in the last ${surface.history.commitsRead} commit${surface.history.commitsRead === 1 ? '' : 's'}`
+  : `${candidate.file}, the first unclaimed module by path because git history is unavailable`;
+
 const P = (projectDir) => ({
   claims: defaultClaimsPath(projectDir),
   evidence: join(projectDir, '.testguard', 'evidence.json'),
@@ -68,6 +73,11 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   };
 
   if (!existsSync(paths.claims)) {
+    doc.surface = computeClaimedSurface({ projectDir });
+    const candidate = doc.surface.rankedUnclaimed[0];
+    if (candidate && !changes?.uncovered.length) {
+      doc.next = { action: 'scaffold', command: `testguard scaffold ${candidate.file}`, why: `${doc.surface.sourceModules} source module${doc.surface.sourceModules === 1 ? '' : 's'} exist and none carries a claim. Start with ${candidateReason(doc.surface, candidate)}.`, file: candidate.file };
+    }
     if (changes?.uncovered.length) {
       const u = changes.uncovered[0];
       doc.next = { action: 'scaffold', command: `testguard scaffold ${u.file}`, why: `No testguard.claims.json in this project, and ${unclaimedWhy()}`, file: u.file };
@@ -79,6 +89,7 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   const claims = loadClaims(paths.claims);
   doc.counts.claims = claims.claims.length;
   doc.counts.faults = claims.claims.reduce((n, c) => n + c.faults.length, 0);
+  doc.surface = computeClaimedSurface({ projectDir, claims });
   const faultIndex = new Map();
   for (const c of claims.claims) for (const f of c.faults) faultIndex.set(`${c.id}/${f.id}`, { claim: c, fault: f });
 
@@ -236,6 +247,15 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   } else {
     doc.next = { action: 'none', command: 'testguard probe', why: unprovenTotal ? `${unprovenTotal} baselined finding${unprovenTotal === 1 ? '' : 's'} remain; nothing new. Re-probe after changing code, tests or claims.` : 'Every claim is defended. Re-probe after changing code, tests or claims; add a claim for every new invariant.' };
   }
+  if (needsClaimExpansion(doc.surface)) {
+    const candidate = doc.surface.rankedUnclaimed[0];
+    doc.next = {
+      action: 'claim',
+      command: `testguard scaffold ${candidate.file}`,
+      why: `The existing claims are defended, but only ${doc.surface.claimedModules} of ${doc.surface.sourceModules} source modules carry a claim. Expand the denominator at ${candidateReason(doc.surface, candidate)}.`,
+      file: candidate.file,
+    };
+  }
   return doc;
 }
 
@@ -246,6 +266,15 @@ export function renderStatus(doc) {
   }
   lines.push(`state: ${doc.state}${doc.provisional ? ' (provisional)' : ''} — ${doc.counts.claims} claims / ${doc.counts.faults} faults` + (doc.counts.byVerdict ? `; ${Object.entries(doc.counts.byVerdict).map(([k, v]) => `${v} ${k}`).join(', ')}; ${doc.counts.new ?? 0} new, ${doc.counts.baselined ?? 0} baselined` : '')
   );
+  if (doc.surface) {
+    const s = doc.surface;
+    const history = s.history.available ? `last ${s.history.commitsRead} commit${s.history.commitsRead === 1 ? '' : 's'}` : 'git history unavailable';
+    lines.push(`surface:  ${s.claimedModules} of ${s.sourceModules} source modules carry a claim; ${s.highChurn.claimed} of ${s.highChurn.modules} highest-churn modules claimed (${history})`);
+    for (const item of s.rankedUnclaimed.slice(0, 3)) lines.push(`UNCLAIMED ${item.file} — ${item.changes} change${item.changes === 1 ? '' : 's'} in history window${item.riskSignals.length ? `; path risk: ${item.riskSignals.join(', ')}` : ''}`);
+  }
+  const coAuthored = doc.counts.killedCoAuthored ?? 0;
+  const kills = doc.counts.byVerdict?.killed ?? 0;
+  if (coAuthored) lines.push(`evidence: ${coAuthorshipWarning(coAuthored, kills)}`);
   if (doc.changes) {
     const c = doc.changes;
     lines.push(`changes:  ${c.changed} file${c.changed === 1 ? '' : 's'} since ${c.ref}; ${c.evaluated} evaluated, ${c.excluded} excluded, ${c.uncovered.length} unclaimed`);

package/src/status/surface.mjs

@@ -0,0 +1,72 @@
+import { existsSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { git } from '../git.mjs';
+import { SOURCE_EXT, isDefaultExcluded, isTestFile } from '../gate/changed.mjs';
+import { walk } from '../util/glob.mjs';
+
+export const HISTORY_COMMITS = 200;
+export const HIGH_CHURN_MODULES = 20;
+export const RANKED_UNCLAIMED = 10;
+
+const RISK_SIGNALS = Object.freeze([
+  ['security', /(^|[._/-])(auth|authn|authz|authorization|credential|crypto|login|password|permission|rbac|secret|security|session|token)([._/-]|$)/i],
+  ['money', /(^|[._/-])(billing|checkout|invoice|money|payment|payout|price|pricing|refund)([._/-]|$)/i],
+]);
+
+const pathRiskSignals = (file) => RISK_SIGNALS.filter(([, re]) => re.test(file)).map(([name]) => name);
+
+function listedFiles(projectDir) {
+  try {
+    return git(['ls-files', '-co', '--exclude-standard', '-z', '--', '.'], projectDir).split('\0').filter(Boolean);
+  } catch {
+    return walk(projectDir);
+  }
+}
+
+function claimableModules(projectDir) {
+  return listedFiles(projectDir).filter((file) =>
+    existsSync(join(projectDir, file)) &&
+    SOURCE_EXT.has(extname(file)) &&
+    !isTestFile(file) &&
+    !isDefaultExcluded(file));
+}
+
+function recentChanges(projectDir, sourceModules) {
+  const counts = new Map();
+  try {
+    const commitsRead = Number(git(['rev-list', '--count', `--max-count=${HISTORY_COMMITS}`, 'HEAD', '--', '.'], projectDir));
+    const paths = git(['log', '--relative', '-n', String(HISTORY_COMMITS), '--pretty=format:', '--name-only', '-z', '--', '.'], projectDir).split('\0').filter(Boolean);
+    for (const file of paths) if (sourceModules.has(file)) counts.set(file, (counts.get(file) ?? 0) + 1);
+    return { available: true, commitsRead, counts };
+  } catch {
+    return { available: false, commitsRead: 0, counts };
+  }
+}
+
+/**
+ * The denominator `probe` cannot provide: current source modules carrying at
+ * least one fault, plus concrete unclaimed modules ranked by bounded git
+ * history. Churn and path-risk remain separate facts; there is no score.
+ */
+export function computeClaimedSurface({ projectDir, claims }) {
+  const modules = new Set(claimableModules(projectDir));
+  const claimedFiles = new Set((claims?.claims ?? []).flatMap((claim) => claim.faults.map((fault) => fault.file)));
+  const claimed = new Set([...modules].filter((file) => claimedFiles.has(file)));
+  const history = recentChanges(projectDir, modules);
+  const describe = (file) => ({ file, changes: history.counts.get(file) ?? 0, riskSignals: pathRiskSignals(file) });
+  const ranked = [...modules].map(describe).sort((a, b) =>
+    b.changes - a.changes || b.riskSignals.length - a.riskSignals.length || a.file.localeCompare(b.file));
+  const highChurn = ranked.slice(0, Math.min(HIGH_CHURN_MODULES, ranked.length));
+  const rankedUnclaimed = ranked.filter((item) => !claimed.has(item.file)).slice(0, RANKED_UNCLAIMED);
+  return {
+    sourceModules: modules.size,
+    claimedModules: claimed.size,
+    unclaimedModules: modules.size - claimed.size,
+    history: { available: history.available, maxCommits: HISTORY_COMMITS, commitsRead: history.commitsRead },
+    highChurn: { modules: highChurn.length, claimed: highChurn.filter((item) => claimed.has(item.file)).length },
+    rankedUnclaimed,
+  };
+}
+
+/** Expand the claim surface only when most current source modules are unseen. */
+export const needsClaimExpansion = (surface) => surface.unclaimedModules > surface.claimedModules && surface.rankedUnclaimed.length > 0;