testguard-cli 0.16.0 → 0.18.0

package/spec/lib/validate.mjs

@@ -4,10 +4,13 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { fingerprint } from './fingerprint.mjs';
 import { reproduces, decimals, MAX_PLACES } from './wilson.mjs';
+import { isDeepStrictEqual } from 'node:util';
+import { recordedOriginSummary } from './origins.mjs';
+import { authoringInputErrors } from './authoring-input.mjs';
 
 const schemaDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'schemas');
 
-export const KINDS = Object.freeze(['claims', 'evidence', 'baseline', 'ignore', 'calibration', 'brief', 'status', 'gate', 'replay', 'sweep', 'concerns']);
+export const KINDS = Object.freeze(['claims', 'evidence', 'baseline', 'ignore', 'calibration', 'brief', 'status', 'gate', 'replay', 'sweep', 'concerns', 'annotations', 'authoring-input']);
 /**
  * How a document says it tried to falsify its claims. Absent means
  * `fault-injection`, so every document written before the field existed is
@@ -46,8 +49,113 @@ const nestedErrors = (nested = [], prefix = '/nested', occupied = []) => {
   return errors;
 };
 
+// A projected summary is not source authority. Only evidence retains the
+// complete claim projections needed to reproduce each kind and mixed count.
+function originPolicyErrors(kind, doc) {
+  const errors = [];
+  const policies = [[doc.originPolicy, '/originPolicy'], [kind === 'status' ? doc.run?.originPolicy : undefined, '/run/originPolicy']];
+  const identities = (rows) => rows.map((r) => JSON.stringify([r.claimId, r.faultId])).sort();
+  for (const [p, path] of policies) {
+    if (!p) continue;
+    const fail = (message) => errors.push({ path, message });
+    for (const field of ['eligibleKinds', 'ineligibleClaims', 'unavailableReasons']) {
+      if (!isDeepStrictEqual(p[field], [...p[field]].sort())) fail(`${field} must be normalized in sorted order`);
+    }
+    const failures = p.ineligibleClaims.length + p.nonKilledFaults.length;
+    const expectedState = p.unavailableReasons.length ? 'unavailable' : failures ? 'failed' : 'passed';
+    if (p.state !== expectedState) fail('policy state must match refusal reasons and unsuppressed failures');
+    if (p.state !== 'unavailable' && (!p.claims || !p.faults)) fail('an evaluated policy requires a nonempty claim and fault universe');
+    if (p.ineligibleClaims.length > p.claims) fail('ineligible claims exceed the current claim denominator');
+    if (p.state !== 'unavailable' && p.nonKilledFaults.length > p.faults) fail('non-killed faults exceed the complete fault denominator');
+    if (kind === 'evidence') {
+      const actual = [...new Set(doc.records.filter((r) => r.verdict !== 'killed').map((r) => JSON.stringify([r.claim.id, r.subject.id])))].sort();
+      if (!isDeepStrictEqual(identities(p.nonKilledFaults), actual)) fail('policy must retain every actual non-killed fault identity');
+      if (p.state !== 'unavailable') {
+        const claims = new Set(doc.records.map((r) => r.claim.id));
+        const faults = new Set(doc.records.map((r) => JSON.stringify([r.claim.id, r.subject.id])));
+        if (p.claims !== claims.size || p.faults !== faults.size || faults.size !== doc.records.length) fail('evaluated policy denominators require complete unique recorded identities');
+        const ineligible = [...new Set(doc.records.filter((r) => !p.eligibleKinds.includes(r.claim.source.kind)).map((r) => r.claim.id))].sort();
+        if (!isDeepStrictEqual(p.ineligibleClaims, ineligible)) fail('policy eligibility must match recorded declarations');
+        if (!isInjection(doc.run) || doc.run.provisional || doc.run.confirmRuns < 3) fail('evaluated policy requires confirmed fault-injection evidence');
+        if (recordedOriginSummary(doc.records).claims.mixed) fail('evaluated policy cannot use mixed recorded origins');
+      }
+    }
+    if (kind === 'status' && (p.claims !== doc.counts.claims || p.faults !== doc.counts.faults)) fail('policy denominators must match current status claims and faults');
+    if (kind === 'brief' && p.state !== 'unavailable' && (p.claims !== doc.summary.claims || p.faults !== Object.values(doc.summary.byVerdict).reduce((a, b) => a + b, 0))) fail('recorded policy denominators must match the uncapped brief summary');
+  }
+  if (kind === 'status' && doc.run) {
+    const p = doc.run.originPolicy;
+    const expected = p?.state === 'unavailable' ? 2 : p?.state === 'failed' || doc.run.newSinceBaseline > 0 ? 1 : 0;
+    if (p && doc.run.exitCode !== expected) errors.push({ path: '/run/exitCode', message: 'exit code must preserve policy refusal/failure before baseline findings' });
+    if (!p && doc.run.exitCode === 2) errors.push({ path: '/run/exitCode', message: 'completed probe exit 2 requires an unavailable origin policy' });
+    if (p && (doc.run.scope || doc.run.provisional)) errors.push({ path: '/run/originPolicy', message: 'origin policy cannot certify a partial or provisional invocation' });
+  }
+  return errors;
+}
+
+function originErrors(kind, doc) {
+  if (!doc.origins) return [];
+  const errors = [], o = doc.origins;
+  const fail = (message) => errors.push({ path: '/origins', message });
+  const sum = (counts) => Object.values(counts).reduce((a, b) => a + b, 0);
+  if (sum(o.claims.byKind) + o.claims.mixed !== o.claims.total) fail('claim origin buckets plus mixed must equal the distinct claim total');
+  if (o.records && sum(o.records.byKind) !== o.records.total) fail('record origin buckets must equal the record total');
+  if (kind === 'status') {
+    if (o.basis !== 'declared' || o.records || o.claims.mixed !== 0) fail('status origins must describe unmixed current declarations without recorded counts');
+    if (o.claims.total !== doc.counts.claims) fail('declared origin total must equal current claim count');
+  } else {
+    if (o.basis !== 'recorded' || !o.records) fail('evidence and brief origins require recorded basis and record counts');
+    if (kind === 'evidence' && !isDeepStrictEqual(o, recordedOriginSummary(doc.records))) fail('recorded origins must reproduce every actual record and distinct claim declaration');
+    if (kind === 'brief' && (o.claims.total !== doc.summary.claims || o.records?.total !== sum(doc.summary.byVerdict))) fail('brief origin totals must match the complete summary, not capped items');
+  }
+  return errors;
+}
+
 // Rules JSON Schema cannot express. Each returns an array of {path, message}.
 const semantic = {
+  'authoring-input': authoringInputErrors,
+  annotations(doc) {
+    const errors = [];
+    const fail = (path, message) => errors.push({ path, message });
+    const selected = new Set(doc.selected), seenFiles = new Set(), seenIds = new Set();
+    for (const [bucket, entries] of [['targets', doc.targets], ['refused', doc.refused]]) {
+      for (const [i, entry] of entries.entries()) {
+        if (seenFiles.has(entry.file)) fail(`/${bucket}/${i}/file`, 'target must occur in exactly one admission bucket');
+        if (bucket === 'targets' && (entry.file.includes('\\') || /^[A-Za-z]:/.test(entry.file) || entry.file.split('/').some((part) => !part || part === '.' || part === '..'))) fail(`/${bucket}/${i}/file`, 'admitted target must be a canonical relative path');
+        seenFiles.add(entry.file);
+        for (const id of entry.claimIds) {
+          if (!selected.has(id)) fail(`/${bucket}/${i}/claimIds`, 'target claim must be selected');
+          seenIds.add(id);
+        }
+      }
+    }
+    if (doc.selected.some((id) => !seenIds.has(id))) fail('/selected', 'every selected claim must have a target or explicit refusal');
+    if (doc.mode === 'preview') {
+      if (doc.outcome) fail('/outcome', 'preview never has a write outcome');
+      if (doc.state !== (doc.refused.length ? 'refused' : 'preview')) fail('/state', 'preview state must reflect all admission refusals');
+      return errors;
+    }
+    if (!doc.outcome) { fail('/outcome', 'apply requires a write outcome'); return errors; }
+    if (doc.refused.length && doc.state !== 'refused') fail('/state', 'any admission refusal blocks all writes');
+    const o = doc.outcome;
+    const adds = doc.targets.filter((t) => t.action === 'add').map((t) => t.file);
+    const unchanged = doc.targets.filter((t) => t.action === 'unchanged').map((t) => t.file);
+    const same = (a, b) => a.length === b.length && a.every((x) => b.includes(x));
+    if (o.touched.some((file) => !adds.includes(file))) fail('/outcome/touched', 'only admitted add targets can be touched');
+    if (o.changed.some((file) => !o.touched.includes(file))) fail('/outcome/changed', 'verified changes must be touched');
+    if (!same(o.unchanged, unchanged)) fail('/outcome/unchanged', 'unchanged files must match unchanged targets');
+    for (const [i, failure] of o.failed.entries()) {
+      if (failure.file !== null && !doc.targets.some((t) => t.file === failure.file)) fail(`/outcome/failed/${i}/file`, 'failed file must be an admitted target or null');
+    }
+    if (doc.state === 'applied') {
+      if (doc.refused.length || o.failed.length || !same(o.changed, adds) || !same(o.touched, adds) || !o.recoveryDir || o.lockRelease?.released !== true) fail('/state', 'applied requires every admitted target verified, no refusals/failures, recovery and released owned lock');
+    } else if (doc.state === 'refused') {
+      if (o.touched.length || o.changed.length || (!doc.refused.length && !o.failed.length)) fail('/state', 'refused requires no touched files and an explicit refusal/failure');
+    } else if (doc.state === 'partial') {
+      if (!o.touched.length || !o.failed.length || !o.recoveryDir) fail('/state', 'partial requires touched files, explicit failure and retained recovery');
+    } else fail('/state', 'apply cannot be a preview');
+    return errors;
+  },
   claims(doc) {
     const errors = [];
     const seenClaim = new Set();
@@ -75,6 +183,14 @@ const semantic = {
 
   evidence(doc) {
     const errors = [];
+    if (doc.run.runner?.source === 'builtin' && (doc.run.runner.name !== 'node-test' || !/^(?:[2-9]\d|[1-9]\d{2,})\.\d+\.\d+(?:[-+].+)?$/.test(doc.run.runner.version ?? ''))) {
+      errors.push({ path: '/run/runner', message: 'builtin source requires node-test and its actual Node version (20 or newer)' });
+    }
+    if (doc.run.measurements) {
+      const m = doc.run.measurements;
+      if (Math.abs(m.elapsedMs - m.runnerMs - m.overheadMs) > 0.001) errors.push({ path: '/run/measurements', message: 'elapsedMs must equal runnerMs plus overheadMs' });
+    }
+    if (doc.run.serial && doc.run.workers !== undefined && doc.run.workers !== 1) errors.push({ path: '/run/workers', message: 'serial execution requires one worker' });
     const injection = isInjection(doc.run);
     const n = doc.run.confirmRuns;
     // N-run agreement is what fault injection means by "confirmed". A method
@@ -270,6 +386,10 @@ const semantic = {
 
   status(doc) {
     const errors = [];
+    if (doc.cost?.measurements) {
+      const m = doc.cost.measurements;
+      if (Math.abs(m.elapsedMs - m.runnerMs - m.overheadMs) > 0.001) errors.push({ path: '/cost/measurements', message: 'elapsedMs must equal runnerMs plus overheadMs' });
+    }
     if (doc.changes?.nested) {
       errors.push(...nestedErrors(doc.changes.nested, '/changes/nested', doc.changes.uncovered.map((file) => file.file)));
       const nestedCount = doc.changes.nested.reduce((count, entry) => count + entry.files.length, 0);
@@ -472,5 +592,7 @@ export function validate(kind, doc) {
     };
   }
   const errors = semantic[kind] ? semantic[kind](doc) : [];
+  errors.push(...originErrors(kind, doc));
+  errors.push(...originPolicyErrors(kind, doc));
   return { ok: errors.length === 0, errors };
 }

package/spec/schemas/annotations.schema.json

@@ -0,0 +1,65 @@
+{
+  "$id": "urn:claimspec:v1:annotations",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "claimspec v1 — annotation authoring",
+  "description": "File-level authoring only. Not verification or intent authentication. No source contents or reusable approval token.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "tool", "mode", "state", "selected", "targets", "refused"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "tool": { "$ref": "urn:claimspec:v1:common#/$defs/tool" },
+    "mode": { "enum": ["preview", "apply"] },
+    "state": { "enum": ["preview", "applied", "refused", "partial"] },
+    "selected": { "$ref": "#/$defs/ids" },
+    "targets": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false, "required": ["file", "claimIds", "action"],
+        "properties": {
+          "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
+          "claimIds": { "type": "array", "$ref": "#/$defs/ids", "minItems": 1 },
+          "action": { "enum": ["add", "unchanged"] }
+        }
+      }
+    },
+    "refused": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false, "required": ["file", "claimIds", "reason"],
+        "properties": {
+          "file": { "type": "string", "minLength": 1 },
+          "claimIds": { "type": "array", "$ref": "#/$defs/ids", "minItems": 1 },
+          "reason": { "enum": ["unsupported-claim-id", "unsupported-method", "unsafe-path", "excluded-target", "unsupported-source", "symlink-target", "not-regular-file", "nested-project", "source-too-large", "target-missing", "target-unreadable", "target-changed", "invalid-encoding", "mixed-newlines", "plan-source-budget", "proposed-source-too-large", "anchor-missing", "anchor-ambiguous"] }
+        }
+      }
+    },
+    "outcome": {
+      "type": "object", "additionalProperties": false, "required": ["changed", "touched", "unchanged", "failed"],
+      "properties": {
+        "changed": { "$ref": "#/$defs/files" },
+        "touched": { "$ref": "#/$defs/files" },
+        "unchanged": { "$ref": "#/$defs/files" },
+        "failed": {
+          "type": "array", "items": {
+            "type": "object", "additionalProperties": false, "required": ["file", "stage", "reason"],
+            "properties": {
+              "file": { "type": ["string", "null"] },
+              "stage": { "enum": ["preparation", "all-target-preflight", "started-journal", "target-preflight", "source-write", "write-verification", "completion-journal", "lock-release", "result-journal"] },
+              "reason": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "recoveryDir": { "type": "string", "minLength": 1 },
+        "lockRelease": {
+          "type": "object", "additionalProperties": false, "required": ["released"],
+          "properties": { "released": { "type": "boolean" }, "reason": { "type": "string", "minLength": 1 } }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "ids": { "type": "array", "uniqueItems": true, "items": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" } },
+    "files": { "type": "array", "uniqueItems": true, "items": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" } }
+  }
+}

package/spec/schemas/authoring-input.schema.json

@@ -0,0 +1,67 @@
+{
+  "$id": "urn:claimspec:v1:authoring-input",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "claimspec v1 — read-only authoring input",
+  "description": "Metadata-only input handoff. Not claims, verification, freshness authority or authenticated intent. No source text or absolute roots.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "tool", "purpose", "verification", "next", "input"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "tool": { "$ref": "urn:claimspec:v1:common#/$defs/tool" },
+    "purpose": { "const": "authoring-input" },
+    "verification": { "const": "not-performed" },
+    "next": { "const": "supply-independent-intent" },
+    "input": { "oneOf": [{ "$ref": "#/$defs/document" }, { "$ref": "#/$defs/fix" }] }
+  },
+  "$defs": {
+    "objectId": { "type": "string", "pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$" },
+    "document": {
+      "type": "object", "additionalProperties": false,
+      "required": ["kind", "file", "hash", "bytes"],
+      "properties": {
+        "kind": { "const": "document" },
+        "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
+        "hash": { "$ref": "urn:claimspec:v1:common#/$defs/sha256" },
+        "bytes": { "type": "integer", "minimum": 0, "maximum": 2097152 }
+      }
+    },
+    "fix": {
+      "type": "object", "additionalProperties": false,
+      "required": ["kind", "commit", "parent", "subject", "scope", "paths", "counts"],
+      "properties": {
+        "kind": { "const": "fix" },
+        "commit": { "$ref": "#/$defs/objectId" },
+        "parent": { "$ref": "#/$defs/objectId" },
+        "subject": { "type": "string", "maxLength": 1024 },
+        "scope": { "enum": ["project-root", "selected-nested-project"] },
+        "paths": { "type": "array", "maxItems": 256, "items": { "$ref": "#/$defs/path" } },
+        "counts": {
+          "type": "object", "additionalProperties": false,
+          "required": ["total", "supported", "deleted", "unsupported", "excluded"],
+          "properties": {
+            "total": { "$ref": "#/$defs/count" },
+            "supported": { "$ref": "#/$defs/count" },
+            "deleted": { "$ref": "#/$defs/count" },
+            "unsupported": { "$ref": "#/$defs/count" },
+            "excluded": { "$ref": "#/$defs/count" }
+          }
+        }
+      }
+    },
+    "count": { "type": "integer", "minimum": 0, "maximum": 256 },
+    "path": {
+      "type": "object", "additionalProperties": false,
+      "required": ["file", "status", "oldMode", "newMode", "oldId", "newId", "disposition"],
+      "properties": {
+        "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
+        "status": { "enum": ["A", "M", "D", "T"] },
+        "oldMode": { "type": "string", "pattern": "^[0-7]{6}$" },
+        "newMode": { "type": "string", "pattern": "^[0-7]{6}$" },
+        "oldId": { "$ref": "#/$defs/objectId" },
+        "newId": { "$ref": "#/$defs/objectId" },
+        "disposition": { "enum": ["supported", "deleted", "unsupported"] }
+      }
+    }
+  }
+}

package/spec/schemas/brief.schema.json

@@ -6,6 +6,8 @@
   "type": "object",
   "required": ["schemaVersion", "tool", "generatedAt", "heading", "summary", "items", "text"],
   "properties": {
+    "originPolicy": { "$ref": "urn:claimspec:v1:common#/$defs/originPolicy" },
+    "origins": { "$ref": "urn:claimspec:v1:common#/$defs/originSummary" },
     "$schema": { "type": "string" },
     "schemaVersion": { "const": 1 },
     "tool": { "$ref": "urn:claimspec:v1:common#/$defs/tool" },

package/spec/schemas/claims.schema.json

@@ -46,20 +46,14 @@
           "maxLength": 2000
         },
         "source": {
-          "description": "Where the claim comes from. Spec- and ADR-sourced claims are human-governed; annotation- and comment-sourced claims may have been written by the same agent that wrote the tests, and should be ranked accordingly.",
+          "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": {
-              "enum": [
-                "spec",
-                "adr",
-                "annotation",
-                "comment",
-                "manual"
-              ]
+              "$ref": "urn:claimspec:v1:common#/$defs/claimSourceKind"
             },
             "ref": {
               "type": "string",

package/spec/schemas/common.schema.json

@@ -4,6 +4,79 @@
   "title": "claimspec v1 \u2014 shared definitions",
   "description": "Definitions shared by every Guard-spec format. Referenced as urn:claimspec:v1:common#/$defs/<name>.",
   "$defs": {
+    "originPolicy": {
+      "description": "An explicitly selected declared-origin policy, not authenticated independence. Stored results describe their run, not current freshness authority.",
+      "type": "object",
+      "required": ["state", "eligibleKinds", "claims", "faults", "ineligibleClaims", "nonKilledFaults", "unavailableReasons"],
+      "properties": {
+        "state": { "enum": ["passed", "failed", "unavailable"] },
+        "eligibleKinds": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "$ref": "#/$defs/claimSourceKind" } },
+        "claims": { "$ref": "#/$defs/originCount" },
+        "faults": { "$ref": "#/$defs/originCount" },
+        "ineligibleClaims": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/identifier" } },
+        "nonKilledFaults": {
+          "type": "array", "uniqueItems": true,
+          "items": {
+            "type": "object", "required": ["claimId", "faultId"],
+            "properties": { "claimId": { "$ref": "#/$defs/identifier" }, "faultId": { "$ref": "#/$defs/identifier" } },
+            "additionalProperties": false
+          }
+        },
+        "unavailableReasons": {
+          "type": "array", "uniqueItems": true,
+          "items": { "enum": ["invalid-claims", "invalid-evidence", "empty-universe", "stale-inputs", "provisional-evidence", "incompatible-method", "missing-record", "extra-record", "duplicate-record", "claim-metadata-mismatch", "fault-mismatch"] }
+        }
+      },
+      "additionalProperties": false
+    },
+    "originCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+    "originCounts": {
+      "type": "object",
+      "required": ["spec", "adr", "annotation", "comment", "manual", "doc", "bug", "incident", "review", "inferred"],
+      "properties": {
+        "spec": { "$ref": "#/$defs/originCount" },
+        "adr": { "$ref": "#/$defs/originCount" },
+        "annotation": { "$ref": "#/$defs/originCount" },
+        "comment": { "$ref": "#/$defs/originCount" },
+        "manual": { "$ref": "#/$defs/originCount" },
+        "doc": { "$ref": "#/$defs/originCount" },
+        "bug": { "$ref": "#/$defs/originCount" },
+        "incident": { "$ref": "#/$defs/originCount" },
+        "review": { "$ref": "#/$defs/originCount" },
+        "inferred": { "$ref": "#/$defs/originCount" }
+      },
+      "additionalProperties": false
+    },
+    "originSummary": {
+      "description": "Declared origins, not authenticated independence. Distinct claim identities and actual recorded projections have separate denominators. Evidence validation recomputes this from every record; projected status/brief documents can only bind arithmetic and totals.",
+      "type": "object",
+      "required": ["basis", "claims"],
+      "properties": {
+        "basis": { "enum": ["declared", "recorded"] },
+        "claims": {
+          "type": "object", "required": ["total", "byKind", "mixed"],
+          "properties": {
+            "total": { "$ref": "#/$defs/originCount" },
+            "byKind": { "$ref": "#/$defs/originCounts" },
+            "mixed": { "$ref": "#/$defs/originCount" }
+          },
+          "additionalProperties": false
+        },
+        "records": {
+          "type": "object", "required": ["total", "byKind"],
+          "properties": {
+            "total": { "$ref": "#/$defs/originCount" },
+            "byKind": { "$ref": "#/$defs/originCounts" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "claimSourceKind": {
+      "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"]
+    },
     "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

@@ -11,6 +11,8 @@
     "records"
   ],
   "properties": {
+    "originPolicy": { "$ref": "urn:claimspec:v1:common#/$defs/originPolicy" },
+    "origins": { "$ref": "urn:claimspec:v1:common#/$defs/originSummary" },
     "$schema": {
       "type": "string"
     },
@@ -79,10 +81,11 @@
               "maxLength": 64
             },
             "source": {
-              "description": "`project`: the runner package resolved from the project and its own bin script ran. `path`: no such package in the project; an executable of that name on PATH ran instead (a legitimate monorepo setup, but not the project's pinned version).",
+              "description": "`project`: the runner package resolved from the project. `path`: an executable on PATH ran instead. `builtin`: the explicitly selected node-test engine uses the Node executable running TestGuard; its version is required.",
               "enum": [
                 "project",
-                "path"
+                "path",
+                "builtin"
               ]
             }
           },
@@ -168,6 +171,39 @@
         },
         "method": {
           "$ref": "urn:claimspec:v1:common#/$defs/method"
+        },
+        "measurements": {
+          "type": "object",
+          "required": [
+            "elapsedMs",
+            "runnerMs",
+            "overheadMs",
+            "runnerInvocations"
+          ],
+          "properties": {
+            "elapsedMs": {
+              "type": "number",
+              "minimum": 0
+            },
+            "runnerMs": {
+              "type": "number",
+              "minimum": 0
+            },
+            "overheadMs": {
+              "type": "number",
+              "minimum": 0
+            },
+            "runnerInvocations": {
+              "type": "integer",
+              "minimum": 0
+            }
+          },
+          "additionalProperties": false
+        },
+        "workers": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Requested built-in runner worker ceiling; Python is serial. Absent for custom commands, whose concurrency is user-managed."
         }
       },
       "additionalProperties": false,
@@ -309,13 +345,7 @@
               ],
               "properties": {
                 "kind": {
-                  "enum": [
-                    "spec",
-                    "adr",
-                    "annotation",
-                    "comment",
-                    "manual"
-                  ]
+                  "$ref": "urn:claimspec:v1:common#/$defs/claimSourceKind"
                 },
                 "ref": {
                   "type": "string",
@@ -664,7 +694,7 @@
           "additionalProperties": false
         },
         "reusedFrom": {
-          "description": "Run id whose verdict was reused because `inputs` were unchanged.",
+          "description": "Run id whose verdict was reused because fault, defender and recorded claim metadata inputs were unchanged. A changed claim statement, severity, source or producer requires a fresh probe.",
           "$ref": "urn:claimspec:v1:common#/$defs/identifier"
         },
         "rank": {

package/spec/schemas/status.schema.json

@@ -13,6 +13,8 @@
     "counts"
   ],
   "properties": {
+    "originPolicy": { "$ref": "urn:claimspec:v1:common#/$defs/originPolicy" },
+    "origins": { "$ref": "urn:claimspec:v1:common#/$defs/originSummary" },
     "$schema": {
       "type": "string"
     },
@@ -157,12 +159,13 @@
       "type": "object",
       "required": ["id", "evidence", "provisional", "records", "newSinceBaseline", "exitCode"],
       "properties": {
+        "originPolicy": { "$ref": "urn:claimspec:v1:common#/$defs/originPolicy" },
         "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] },
+        "exitCode": { "enum": [0, 1, 2] },
         "scope": {
           "type": "object",
           "required": ["requestedClaims", "requestedCount", "probedClaims", "probedCount"],
@@ -191,6 +194,7 @@
       "type": "object",
       "required": ["totalMs", "totalRuns", "reusedRecords", "records", "claims", "defenders", "sharedDefenders"],
       "properties": {
+        "measurements": {"type": "object", "required": ["elapsedMs", "runnerMs", "overheadMs", "runnerInvocations"], "properties": {"elapsedMs": {"type": "number", "minimum": 0}, "runnerMs": {"type": "number", "minimum": 0}, "overheadMs": {"type": "number", "minimum": 0}, "runnerInvocations": {"type": "integer", "minimum": 0}}, "additionalProperties": false},
         "totalMs": { "type": "number", "minimum": 0 },
         "totalRuns": { "type": "integer", "minimum": 0 },
         "reusedRecords": { "type": "integer", "minimum": 0 },
@@ -301,7 +305,7 @@
       }
     },
     "notes": {
-      "description": "Informational lines that never change `state`: e.g. a baseline frozen from a snapshot whose head predates the commit that carries its tests, with the way to re-stamp it.",
+      "description": "Informational lines that never change state or next verification action: e.g. annotation-link advice (not verification or authenticated provenance), or a baseline snapshot with the way to re-stamp it.",
       "type": "array",
       "items": { "type": "string", "minLength": 1, "maxLength": 512 }
     },

package/src/brief/brief.mjs

@@ -1,5 +1,6 @@
 import { gate } from '../baseline/baseline.mjs';
-import { coAuthorshipWarning, summarize, formatVerdict } from '../render.mjs';
+import { coAuthorshipWarning, summarize, formatVerdict, renderOrigins, renderOriginPolicy } from '../render.mjs';
+import { recordedOriginSummary } from '../../spec/lib/origins.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. */
@@ -72,10 +73,12 @@ export function buildBrief(evidence, baseline, { max = 20, generatedAt = new Dat
     new: g.new.length + g.belowFloor.length,
     baselined: g.baselined.length,
   };
+  const origins = recordedOriginSummary(evidence.records);
   const kills = evidence.records.filter((r) => r.verdict === 'killed');
   const coAuthored = kills.filter((r) => r.detail.independence?.class === 'co-authored').length;
   const unclaimed = changes?.uncovered?.length ? { ref: changes.ref, files: changes.uncovered } : undefined;
-  const doc = { schemaVersion: 1, tool: evidence.tool, generatedAt, head: evidence.run.repo.head, heading: HEADING, summary, ...(next ? { next: { action: next.action, command: next.command, why: next.why } } : {}), ...(unclaimed ? { unclaimed } : {}), items, text: '' };
+  const doc = { schemaVersion: 1, tool: evidence.tool, generatedAt, head: evidence.run.repo.head, heading: HEADING, summary, origins, ...(next ? { next: { action: next.action, command: next.command, why: next.why } } : {}), ...(unclaimed ? { unclaimed } : {}), items, text: '' };
+  if (evidence.originPolicy) doc.originPolicy = structuredClone(evidence.originPolicy);
   doc.text = renderBriefText({ ...doc, provisional: Boolean(evidence.run.provisional), install }, { hasBaseline: Boolean(baseline), total: evidence.records.length, independence: kills.length ? { coAuthored, kills: kills.length } : undefined });
   return doc;
 }
@@ -89,6 +92,8 @@ export function renderBriefText(brief, { hasBaseline, total, independence }) {
     `testguard ${brief.tool.version}${brief.install ? ` (${brief.install})` : ''}${brief.head ? ` @ ${brief.head.slice(0, 12)}` : ''} — ${brief.summary.claims} claims, ${total} faults probed, ${unproven} unproven` +
       (unproven === 0 ? '.' : hasBaseline ? ` (${brief.summary.new} new since baseline).` : ' (no baseline; everything is new).'),
   ];
+  if (brief.origins) lines.push(renderOrigins(brief.origins));
+  if (brief.originPolicy) lines.push(renderOriginPolicy(brief.originPolicy));
   // Unclaimed changes come before everything else: the claim is written
   // before more code, and TestGuard is silent about unclaimed code otherwise.
   if (brief.unclaimed) {
@@ -101,7 +106,7 @@ export function renderBriefText(brief, { hasBaseline, total, independence }) {
   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.');
+    lines.push('', unproven === 0 ? 'Every probed claim is defended. Keep it that way: new claims need a fault and a test that fails on it.' : `${unproven} unproven faults remain; no items shown at the current cap. See the full evidence file.`);
     return lines.join('\n') + '\n';
   }
   lines.push(
@@ -149,6 +154,8 @@ export function renderBriefMarkdown(brief, { hasBaseline, total, install } = {})
   if (brief.provisional) lines.push('**PROVISIONAL** — fewer than three confirmation runs; nothing below is confirmed. Re-probe with `--confirm 3`.', '');
   lines.push(`\`testguard ${brief.tool.version}${install ? ` (${install})` : ''}\`${brief.head ? ` @ \`${brief.head.slice(0, 12)}\`` : ''} — **${brief.summary.claims}** claims, **${total}** faults probed, **${unproven}** unproven` +
     (unproven === 0 ? '.' : hasBaseline ? ` (**${brief.summary.new}** new since baseline).` : ' (no baseline; everything is new).'));
+  if (brief.origins) lines.push('', renderOrigins(brief.origins));
+  if (brief.originPolicy) lines.push('', renderOriginPolicy(brief.originPolicy));
   if (brief.unclaimed) {
     const n = brief.unclaimed.files.length;
     lines.push('', `### Unclaimed changes since \`${brief.unclaimed.ref}\``, '', `${n} changed file${n === 1 ? '' : 's'} carr${n === 1 ? 'ies' : 'y'} no claim. State the claim first; nothing below can see this code.`, '');
@@ -156,7 +163,7 @@ export function renderBriefMarkdown(brief, { hasBaseline, total, install } = {})
   }
   if (brief.next) lines.push('', `**Next** \`[${brief.next.action}]\`: \`${brief.next.command}\``, '', `> ${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.');
+    lines.push('', unproven === 0 ? 'Every probed claim is defended. Keep it that way: new claims need a fault and a test that fails on it.' : `${unproven} unproven faults remain; no items shown at the current cap. See the full evidence file.`);
     return lines.join('\n') + '\n';
   }
   lines.push('', 'Where the test suite is blind, ranked. A **SURVIVED** fault means its defenders stayed green while the claim was false. Do not close these by asserting current behaviour; write a test that fails on the described fault and passes on HEAD.', '');