testguard-cli 0.10.2 → 0.10.4

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.4] - 2026-09-21
+
+Automated weekly release — everything merged since `v0.10.3`.
+
+### Changed
+
+- chore(homebrew): sha256 for v0.10.3 (#147)
+
+
+## [0.10.3] - 2026-09-20
+
+Automated weekly release — everything merged since `v0.10.2`.
+
+### Changed
+
+- fix(gate): infer safe local change base (#145)
+- chore(homebrew): sha256 for v0.10.2 (#144)
+
+
+### Fixed
+
+- Bare `testguard gate` now discovers an ordinary clone's remote default
+  branch and reports how it chose the comparison. It still fails closed on
+  ambiguous Git state: the default branch is not compared to itself, and a
+  feature branch's same-name tracking ref is never accepted as its base.
+
 ## [0.10.2] - 2026-09-20
 
 Automated weekly release — everything merged since `v0.10.1`.

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.10.2` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.10.4` — 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.10.2/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.4/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
@@ -460,9 +460,17 @@ state when an exact fault anchor is missing or ambiguous, and points at the
 fault definition to repair. Repair preserves the fault's meaning and requires
 a re-probe; there is deliberately no `--fix`.
 
-**In CI the base is detected** — GitHub Actions (`GITHUB_BASE_REF`) and GitLab
+**The base is detected when Git records it.** An explicit `--changed` wins,
+then `TESTGUARD_CHANGED_REF`, GitHub Actions (`GITHUB_BASE_REF`) and GitLab
 merge request pipelines (`CI_MERGE_REQUEST_DIFF_BASE_SHA`, then
-`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`); `TESTGUARD_CHANGED_REF` overrides both.
+`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`). In an ordinary clone on a feature
+branch, bare `testguard gate` uses the configured remote's symbolic default
+branch (normally `origin/main`) and says how it chose it. If that symbolic ref
+is absent, a configured upstream is used only when its branch name differs
+from the current branch. A feature branch's same-name tracking ref and the
+default branch itself are never selected: either could produce a misleading
+empty diff. In those ambiguous cases, pass `--changed` explicitly.
+
 The base must exist locally: GitHub — `actions/checkout` with `fetch-depth: 0`;
 GitLab — the diff base sha needs nothing extra on a merge request pipeline,
 the branch name needs `GIT_DEPTH: 0` or a `git fetch origin <target>`. A
@@ -473,12 +481,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.10.2
+- uses: raccioly/testguard@v0.10.4
   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.10.2/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.10.4/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
 ```
 

package/package.json

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

@@ -402,9 +402,14 @@ Rules:
 4. **Never a silent pass on nothing.** A non-empty change whose files were
    all excluded passes with an explicit "0 evaluated" line; a tool offers a
    strict mode that fails it instead. An empty change is an honest `0`.
-5. **The reference is never guessed.** An explicit flag, or a CI-provided base
-   branch, or an error. An upstream that already contains the change has an
-   empty diff and would pass trivially.
+5. **The reference is inferred only from recorded intent.** Resolution stops
+   at the first available source: an explicit flag, `TESTGUARD_CHANGED_REF`, a
+   CI-provided base, the configured remote's symbolic default branch, then a
+   configured upstream whose branch name differs from the current branch.
+   Local discovery never compares a branch to its same-name remote-tracking
+   ref: that ref may already contain the whole change and yield a false empty
+   diff. It also declines to compare the default branch to itself. When Git
+   records no safe local base, the gate exits `3` and asks for `--changed`.
 6. **Unclaimed changes precede every evidence state.** When the status
    document knows a reference and finds uncovered files, its state is
    `unclaimed-changes` and its next action is to write the claim, before any

package/src/commands/brief.mjs

@@ -13,7 +13,7 @@ export async function briefCommand({ projectDir, values, version }, io) {
     // A detected base that does not resolve is silent here: the brief is a
     // session-start hook's output and must never add noise; `status` and
     // `gate` are where that warning is printed.
-    status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: values.evidence ? evPath : undefined }));
+    status = withChangedRef(resolveChangedRef({ explicit: values.changed, projectDir }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: values.evidence ? evPath : undefined }));
   } catch {
     status = undefined; // a brief must never fail because status could not be computed
   }

package/src/commands/gate.mjs

@@ -16,14 +16,14 @@ export async function gateCommand({ projectDir, values, version }, io) {
     io.out('Non-source files (anything but .js .mjs .cjs .ts .mts .cts .jsx .tsx) are excluded before these patterns apply.');
     return 0;
   }
-  const resolved = resolveChangedRef({ explicit: values.changed });
+  const resolved = resolveChangedRef({ explicit: values.changed, projectDir });
   if (!resolved) {
-    io.err('gate needs a reference to measure the change against: --changed <ref> (e.g. origin/main), or set TESTGUARD_CHANGED_REF. In GitHub Actions and GitLab CI the base branch is detected automatically.');
+    io.err('gate needs a reference to measure the change against: --changed <ref> (e.g. origin/main), or set TESTGUARD_CHANGED_REF. CI bases and a safe local remote default or differently named upstream are detected automatically.');
     return 3;
   }
   const ref = resolved.ref;
   // The gate itself never degrades: a detected reference that does not resolve is exit 2 here, because the gate's whole job is the measurement.
-  if (!resolved.required && !values.json && !values.quiet) io.err(`--changed not given; using ${ref} from ${resolved.from}`);
+  if (!resolved.required && !values.json && !values.quiet) io.err(`gate: comparing against ${ref} (${resolved.from})`);
   const doc = computeChangedGate({
     projectDir,
     ref,

package/src/commands/probe.mjs

@@ -106,7 +106,7 @@ export async function probeCommand({ projectDir, values, version }, io) {
   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);
+    const status = withChangedRef(resolveChangedRef({ explicit: values.changed, projectDir }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: outPath }), io.err);
     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('; ')}`);

package/src/commands/status.mjs

@@ -5,7 +5,7 @@ import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
 
 export async function statusCommand({ projectDir, values, version }, io) {
   const evidence = values.evidence ? resolve(values.evidence) : undefined;
-  const doc = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence }), io.err);
+  const doc = withChangedRef(resolveChangedRef({ explicit: values.changed, projectDir }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence }), io.err);
   const result = validate('status', doc);
   if (!result.ok) throw new Error(`status document does not conform: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
   io.out(values.json ? JSON.stringify(doc, null, 2) : renderStatus(doc));

package/src/gate/changed.mjs

@@ -50,10 +50,10 @@ export const isDefaultExcluded = (file) => DEFAULT_EXCLUDE_RES.some((re) => re.t
 export const defaultIgnorePath = (projectDir) => join(projectDir, 'testguard.ignore.json');
 
 /**
- * The reference the change is measured against. Explicit flag first, then the
- * environments CI sets, then nothing: a wrong default would make the gate pass
- * trivially (an upstream that already contains the change has an empty diff),
- * so no ref is an error the caller reports, never a silent guess.
+ * The reference the change is measured against. Environment overrides and CI
+ * bases are handled here; local Git discovery is separate because it needs a
+ * project directory and must distinguish a base branch from a feature branch's
+ * same-name tracking ref.
  */
 export function detectChangedRef(env = process.env) {
   if (env.TESTGUARD_CHANGED_REF) return { ref: env.TESTGUARD_CHANGED_REF, from: 'TESTGUARD_CHANGED_REF' };
@@ -68,18 +68,63 @@ export function detectChangedRef(env = process.env) {
   return null;
 }
 
+const tryGit = (args, cwd) => {
+  try {
+    return git(args, cwd) || null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Infer a local change base only when Git records enough intent to do so
+ * without turning an empty feature-branch tracking diff into a false pass.
+ *
+ * The configured upstream selects the remote whose symbolic HEAD we inspect.
+ * Without one, exactly one remote HEAD is unambiguous. A branch never compares
+ * against that remote's same-named branch: on the default branch that asks no
+ * useful question, and on a feature branch its tracking ref may already contain
+ * the entire change. An upstream is a safe fallback only when its branch name
+ * differs from the local branch name (for example topic -> origin/main).
+ */
+export function detectLocalChangedRef(projectDir) {
+  if (!projectDir) return null;
+  const root = tryGit(['rev-parse', '--show-toplevel'], projectDir);
+  if (!root) return null;
+  const branch = tryGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], root);
+  if (!branch) return null;
+
+  const tracking = tryGit(['for-each-ref', '--format=%(upstream:short)%00%(upstream:remotename)', `refs/heads/${branch}`], root);
+  const [upstream, upstreamRemote] = tracking?.split('\0') ?? [];
+  let remote = upstreamRemote && upstreamRemote !== '.' ? upstreamRemote : null;
+
+  const remoteHeads = (tryGit(['for-each-ref', '--format=%(refname)', 'refs/remotes'], root) ?? '')
+    .split('\n')
+    .filter((ref) => ref.endsWith('/HEAD'));
+  if (!remote && remoteHeads.length === 1) remote = remoteHeads[0].slice('refs/remotes/'.length, -'/HEAD'.length);
+
+  const defaultRef = remote
+    ? tryGit(['symbolic-ref', '--quiet', '--short', `refs/remotes/${remote}/HEAD`], root)
+    : null;
+  if (defaultRef && headSha(root, defaultRef) && defaultRef !== `${remote}/${branch}`) return { ref: defaultRef, from: 'remote default branch' };
+  if (upstream && headSha(root, upstream) && upstream !== `${upstreamRemote}/${branch}`) return { ref: upstream, from: 'branch upstream' };
+  return null;
+}
+
 /**
  * Resolve the reference a command should measure against, and whether it may
  * be dropped on failure. An explicit `--changed` is the user's word: if it
- * does not resolve, that is an error. A reference detected from CI variables
- * is a convenience: if it does not resolve (shallow clone, temp directory,
- * no remote) the command says so on stderr and continues without a change
- * measurement, because `status` and `brief` must keep working everywhere.
+ * does not resolve, that is an error. An automatically detected reference is
+ * a convenience: if it does not resolve (shallow clone, stale local metadata,
+ * or a temp directory) the command says so on stderr and continues without a
+ * change measurement, because `status` and `brief` must keep working everywhere.
  */
-export function resolveChangedRef({ explicit, env = process.env } = {}) {
+export function resolveChangedRef({ explicit, env = process.env, projectDir } = {}) {
   if (explicit) return { ref: explicit, from: '--changed', required: true };
   const d = detectChangedRef(env);
-  return d ? { ...d, required: false } : null;
+  if (d) return { ...d, required: false };
+  const local = detectLocalChangedRef(projectDir);
+  return local ? { ...local, required: false } : null;
 }
 
 /**

package/src/init/templates/SKILL.md

@@ -21,7 +21,7 @@ which files exist. `state` is one of:
 | state | meaning | you do |
 |---|---|---|
 | `no-claims` | no `testguard.claims.json` | `testguard scaffold <file>` for a file with guards; replace every `TODO:` statement with what the code guarantees; keep or drop each proposal; move the claims into `testguard.claims.json` |
-| `unclaimed-changes` | files you changed carry no claim (only when a reference is known: `--changed <ref>`, or CI's base branch) | `next.file` names the first; `testguard scaffold <file>` and state the claim, or add a `testguard.ignore.json` path entry with a reason a reviewer will accept. **Before** writing more code. |
+| `unclaimed-changes` | files you changed carry no claim (when a reference is explicit, supplied by CI, or safely inferred from local Git's remote default/upstream metadata) | `next.file` names the first; `testguard scaffold <file>` and state the claim, or add a `testguard.ignore.json` path entry with a reason a reviewer will accept. **Before** writing more code. |
 | `invalid-anchors` | an exact fault anchor moved or became ambiguous | run `testguard claims --check-anchors`; repair `next.target` in the claims file without changing what the fault means, then re-probe. Never guess or auto-fix an anchor. |
 | `unprobed` | claims never probed | `testguard probe` |
 | `evidence-stale` | code, tests or claims changed since the evidence | `testguard probe --include-dirty` (or `--claim <ID>` for one) |

package/src/mcp/tools.mjs

@@ -29,7 +29,7 @@ const CHANGED = { type: 'string', description: 'A git reference to measure the c
 
 const statusFor = (args) => {
   const projectDir = projectOf(args);
-  return withChangedRef(resolveChangedRef({ explicit: args?.changed }), (changedRef) =>
+  return withChangedRef(resolveChangedRef({ explicit: args?.changed, projectDir }), (changedRef) =>
     computeStatus({ projectDir, toolVersion: args?.__version ?? '0.0.0', changedRef, evidence: evidenceOf(args) }));
 };