testguard-cli 0.16.0 → 0.17.0

package/spec/README.md

@@ -1,7 +1,14 @@
 # claimspec — the contract spine
 
-Nine formats for declaring what must be true about a codebase, recording the
-evidence that tried to falsify it, and gating only what is new.
+The candidate optional `originPolicy` result is a closed declared-origin policy
+audit on evidence/status/brief. It is not independent-origin authentication or
+current freshness authority. `probe --require-origin` explicitly evaluates it
+against current native/input bindings. Offline status recomputes declarations
+without certifying freshness; brief preserves labeled recorded-run policy
+before filtering/caps. See GATE-SEMANTICS.md.
+
+Shared formats for declaring what must be true about a codebase, recording the
+evidence that tried to falsify it, gating only what is new, and explicit authoring.
 
 They are shared as *formats*, not as code. The first tools to adopt them are
 [`docguard-cli`](https://www.npmjs.com/package/docguard-cli) (Node ESM) and
@@ -33,6 +40,8 @@ that carry claims, baselines, scoping and briefs do not care.
 | `status` | [`schemas/status.schema.json`](schemas/status.schema.json) | Where the project is and what happens next — the single machine-readable truth every human rendering derives from. Surfaces faults whose content changed since they were probed, and changed files that carry no claim. |
 | `replay` | [`schemas/replay.schema.json`](schemas/replay.schema.json) | Would this suite have caught the bugs that already escaped? Replays real fix commits: revert the source, remove the test the fix shipped, run what remains. A replayed bug is ground truth — a human already confirmed it was a defect — which is what a fault model is calibrated against. |
 | `gate` | [`schemas/gate.schema.json`](schemas/gate.schema.json) | Claim coverage of one change: which changed files carry a claim, which are excused (and by which ignore entry), which are unclaimed. The delta gate for code that has no claim yet. |
+| `annotations` | [`schemas/annotations.schema.json`](schemas/annotations.schema.json) | Explicit file-header authoring preview/apply, refusals and recoverable partial failures. Never verification, a probe verdict, or authentication of intent; internal source contents are excluded. |
+| `authoring-input` | [`schemas/authoring-input.schema.json`](schemas/authoring-input.schema.json) | Candidate metadata-only document/fix input handoff. No source text, origin assignment, claims or verification; historical partitions retain excluded/deleted/unsupported counts. CLI exposure remains pending. |
 
 Shared definitions (verdicts, fault classes, provenance, annotations) live in
 [`schemas/common.schema.json`](schemas/common.schema.json). Gate behaviour —
@@ -48,6 +57,22 @@ rule is in `GATE-SEMANTICS.md`.
 
 Schemas are JSON Schema 2020-12 and identified as `urn:claimspec:v1:<kind>`.
 
+Claim sources share `common#/$defs/claimSourceKind`: `spec`, `adr`, `annotation`,
+`comment`, `manual`, `doc`, `bug`, `incident`, `review`, `inferred`. They declare
+intent origin, not authenticated independence or an evidence-strength ranking.
+References remain opaque metadata; producer provenance is separate. Existing
+documents remain readable, but old closed-schema readers reject the new kinds.
+Optional `origins` contracts on status, evidence and brief separate distinct
+claim counts from record counts. Evidence validation recomputes every kind and
+mixed declaration from all records; status/brief can validate only arithmetic
+and document totals because source projections are omitted. References are
+never echoed in these summaries. Legacy documents without them remain valid;
+older closed readers reject the additive field. Status emits current declared
+origins; probe evidence and evidence-backed briefs emit recorded origins before
+filtering/caps. Human renderings label these declarations as unauthenticated.
+Opt-in origin policy is available on complete confirmed candidate probes;
+offline projections remain audits, never current native freshness. See `GATE-SEMANTICS.md`.
+
 ## Conformance
 
 `lib/validate.mjs` validates a document of any kind: JSON Schema first, then

package/spec/lib/authoring-input.mjs

@@ -0,0 +1,40 @@
+import { extname } from 'node:path';
+
+const PRIVATE = new Set(['.local', '.wolf', '.git', '.testguard', 'graphify-out']);
+const SOURCE = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py']);
+
+/** Shape validation runs first. These checks cannot authenticate the actual input. */
+export function authoringInputErrors(doc) {
+  const errors = [];
+  const fail = (path, message) => errors.push({ path, message });
+  const checkPath = (file, path) => {
+    if (Buffer.byteLength(file) > 4096 || file.includes('\\') || /[\x00-\x1f\x7f-\x9f]/.test(file) || /^[A-Za-z]:/.test(file) || file.split('/').some(part => !part || part === '.' || part === '..' || PRIVATE.has(part))) fail(path, 'input path must be bounded, canonical and outside private/tooling namespaces');
+  };
+  if (Buffer.byteLength(JSON.stringify(doc)) > 1024 * 1024) fail('/', 'authoring input report exceeds byte limit');
+  const input = doc.input;
+  if (input.kind === 'document') {
+    checkPath(input.file, '/input/file');
+    if (!['.md', '.txt', '.rst', '.adoc'].includes(extname(input.file))) fail('/input/file', 'document format is unsupported');
+    return errors;
+  }
+  if (input.commit.length !== input.parent.length || input.commit === input.parent) fail('/input/parent', 'fix requires a distinct same-width parent identity');
+  if (Buffer.byteLength(input.subject) > 1024 || /[\x00-\x1f\x7f-\x9f]/.test(input.subject)) fail('/input/subject', 'commit subject must be bounded untrusted single-line text');
+  const { total, supported, deleted, unsupported, excluded } = input.counts;
+  if (total !== supported + deleted + unsupported + excluded || input.paths.length !== supported + deleted + unsupported) fail('/input/counts', 'complete path partition must retain excluded/deleted/unsupported denominators');
+  const seen = new Set(), actual = { supported: 0, deleted: 0, unsupported: 0 };
+  input.paths.forEach((row, i) => {
+    const path = `/input/paths/${i}`;
+    checkPath(row.file, `${path}/file`);
+    if (seen.has(row.file)) fail(`${path}/file`, 'visible path is duplicated');
+    seen.add(row.file);
+    if (row.oldId.length !== input.commit.length || row.newId.length !== input.commit.length) fail(path, 'path object identities must match commit width');
+    const oldZero = /^0+$/.test(row.oldId), newZero = /^0+$/.test(row.newId);
+    if ((row.oldMode === '000000') !== oldZero || (row.newMode === '000000') !== newZero ||
+      (row.status === 'A' ? !oldZero || newZero : row.status === 'D' ? oldZero || !newZero : oldZero || newZero)) fail(path, 'mode, status and zero identity must agree');
+    const disposition = row.status === 'D' ? 'deleted' : !['100644', '100755'].includes(row.newMode) || !SOURCE.has(extname(row.file)) ? 'unsupported' : 'supported';
+    if (row.disposition !== disposition) fail(`${path}/disposition`, 'disposition must derive from actual status, mode and supported extension');
+    actual[row.disposition]++;
+  });
+  if (actual.supported !== supported || actual.deleted !== deleted || actual.unsupported !== unsupported) fail('/input/counts', 'visible disposition counts must reproduce every path');
+  return errors;
+}

package/spec/lib/origins.mjs

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+
+// One vocabulary for admission and reporting; never an evidence-strength order.
+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);
+const counts = () => Object.fromEntries(CLAIM_SOURCE_KINDS.map((kind) => [kind, 0]));
+
+// Consumers validate their full document first. These narrow guards prevent
+// malformed direct calls from silently manufacturing a meaningful summary.
+function declaration(claim) {
+  const source = claim?.source;
+  if (typeof claim?.id !== 'string' || !claim.id || !kindSet.has(source?.kind)
+    || Object.keys(source).some((key) => key !== 'kind' && key !== 'ref')
+    || (Object.hasOwn(source, 'ref') && (typeof source.ref !== 'string' || source.ref.length > 512))) {
+    throw new TypeError('origin summary needs valid claim identities and declared sources');
+  }
+  return { kind: source.kind, ...(Object.hasOwn(source, 'ref') ? { ref: source.ref } : {}) };
+}
+
+/** Current declarations only: fault multiplicity cannot inflate claim counts. */
+export function declaredOriginSummary(claims) {
+  const byKind = counts();
+  const seen = new Set();
+  for (const claim of claims) {
+    const source = declaration(claim);
+    if (seen.has(claim.id)) throw new TypeError('duplicate declared claim identity');
+    seen.add(claim.id);
+    byKind[source.kind]++;
+  }
+  return { basis: 'declared', claims: { total: seen.size, byKind, mixed: 0 } };
+}
+
+/** Actual recorded projections only; no current-claims relabeling or filtering. */
+export function recordedOriginSummary(records) {
+  const recordKinds = counts();
+  const claims = new Map();
+  for (const record of records) {
+    const source = declaration(record.claim);
+    recordKinds[source.kind]++;
+    const previous = claims.get(record.claim.id);
+    if (!previous) claims.set(record.claim.id, { source, mixed: false });
+    else if (!isDeepStrictEqual(previous.source, source)) previous.mixed = true;
+  }
+  const byKind = counts();
+  let mixed = 0;
+  for (const claim of claims.values()) {
+    if (claim.mixed) mixed++;
+    else byKind[claim.source.kind]++;
+  }
+  return {
+    basis: 'recorded', claims: { total: claims.size, byKind, mixed },
+    records: { total: records.length, byKind: recordKinds },
+  };
+}

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,11 @@ const semantic = {
 
   evidence(doc) {
     const errors = [];
+    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 +383,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 +589,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"
     },
@@ -168,6 +170,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 +344,7 @@
               ],
               "properties": {
                 "kind": {
-                  "enum": [
-                    "spec",
-                    "adr",
-                    "annotation",
-                    "comment",
-                    "manual"
-                  ]
+                  "$ref": "urn:claimspec:v1:common#/$defs/claimSourceKind"
                 },
                 "ref": {
                   "type": "string",
@@ -664,7 +693,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": {