fix(cli): blame a mismatched fixture id only when it hid every fixture

`sg-fixture-id-matches-rule` was attributed from `fixturesExcludedById`
alone. That flag is rule-wide — true if ANY discovered test file was
skipped for carrying another rule's `id:` — while the shortfall it was
gating is a per-coverage-state fact summed over every file the rule
owns. A rule-wide boolean cannot decide a per-coverage-state question,
and the two come apart as soon as a rule ships more than one test file.

The reachable case: `<id>-a-test.yml` with the right id but only a
`valid:` bucket, beside `<id>-b-test.yml` with a wrong id, also
`valid:`-only. Combined coverage is `valid-only`, so the shortfall is
"has only valid: fixtures — half a claim", and the exclusion flag
attached that message to the id constraint. The author would have been
sent to fix an id in a file they may not have been thinking about, and
fixing it would not have moved the shortfall at all: neither file has an
`invalid:` case. The real defect — that nothing shows the rule fires —
goes unmentioned behind an unrelated diagnosis.

The gate now also requires `fixtures === "none"`, which is the state the
constraint's own rationale describes: an exclusion making a rule read as
having shipped no fixtures. Both halves are needed, and each rules out a
different wrong answer — without the flag, a rule with no cases is told
to hunt for a mismatched id; without the coverage check, a rule with a
partial-but-counted fixture is told the same thing.

Author: theCodeDrift

openspec/changes/reference-fixture-cases/design.md

@@ -192,6 +192,9 @@ honestly. It surfaces as the same "has no fixtures" shortfall a rule with no
 cases at all produces, and those two want different advice: one author has
 written nothing, the other has a file sitting right there that is silently not
 counted. `fixtureCoverage` already skips a test file whose own `id:` names
-another rule, so it now reports that it did, and only that case is attributed.
-Without it the constraint could only have been attributed by guessing, which
-this design rejects everywhere else.
+another rule, so it now reports that it did. That report is rule-wide, so it is
+required alongside a coverage of `none` rather than on its own: an excluded file
+sitting beside a counted one leaves a `valid-only` shortfall that fixing the id
+would not repair, and naming the constraint there would send the author to an
+unrelated mismatch. Without both, the constraint could only have been attributed
+by guessing, which this design rejects everywhere else.

packages/cli/src/rules/inspect.ts

@@ -356,11 +356,28 @@ export async function testOneRule(
       ":"
     );
     if (shortfall !== undefined) {
-      // Attributed only when a fixture file was actually excluded by its own
-      // `id:`. The same shortfall is produced by a rule that simply has no
-      // cases, and calling that `sg-fixture-id-matches-rule` would send an
-      // author looking for a mismatched id in a file they never wrote.
-      if (result.tests.fixturesExcludedById === true) {
+      // Both halves are required, because each rules out a different way of
+      // being wrong about the same shortfall.
+      //
+      // `fixturesExcludedById` says a file the rule owns by NAME was skipped
+      // for carrying another rule's `id:`. Without it, a rule that simply has
+      // no cases would be told to look for a mismatched id in a file it never
+      // wrote.
+      //
+      // `fixtures === "none"` says the shortfall is the one this constraint
+      // describes: exclusion making a rule read as having shipped NOTHING. The
+      // flag alone cannot say that, because it is rule-wide while coverage is
+      // the sum over every discovered file. A rule shipping `<id>-a-test.yml`
+      // with the right id but only a `valid:` bucket, beside an excluded
+      // `<id>-b-test.yml` that is also `valid:`-only, lands on `valid-only`
+      // with the flag set — and fixing the id would not fix that shortfall,
+      // since neither file has an `invalid:` case. Attributing it would send
+      // the author to an unrelated id mismatch and leave the missing half of
+      // the claim unmentioned.
+      if (
+        result.tests.fixturesExcludedById === true &&
+        result.tests.fixtures === "none"
+      ) {
         violate(
           { errors, violations },
           "sg-fixture-id-matches-rule",

packages/cli/src/rules/verify.ts

@@ -105,6 +105,12 @@ export interface TestLayerResult extends LayerResult {
    * different advice, and only this can tell them apart — so the attribution
    * `test` reports is decided here rather than guessed from a shortfall
    * message that both states produce.
+   *
+   * Necessary for that attribution but not sufficient for it. This is
+   * rule-wide, while `fixtures` is the sum over every discovered file, so an
+   * excluded file can sit beside a counted one and leave coverage at
+   * `valid-only` — a shortfall fixing the id would not repair. `test` requires
+   * `fixtures === "none"` alongside this before naming the constraint.
    */
   fixturesExcludedById?: boolean;
 }

packages/cli/test/constraints.test.ts

@@ -293,6 +293,39 @@ describe("every documented constraint is a check that still fires", () => {
     ).not.toContain("sg-fixture-id-matches-rule");
   });
 
+  it("does not blame an id mismatch for a shortfall fixing the id would not fix", async () => {
+    // `fixturesExcludedById` is rule-wide, but coverage is the sum over every
+    // discovered file, so the two can disagree. Here one file carries the right
+    // id and one carries the wrong one, and NEITHER has an `invalid:` bucket:
+    // combined coverage is `valid-only`, not `none`. Correcting the id would
+    // leave that shortfall exactly where it is, so attributing it to
+    // `sg-fixture-id-matches-rule` would send the author to an unrelated
+    // mismatch while the missing half of the claim goes unmentioned. This test
+    // catches a gate that reads only the flag.
+    const ruleId = "probe-rule";
+    const directory = join(project, ".taskless/rules/sg", ruleId);
+    await mkdir(join(directory, ".tests"), { recursive: true });
+    await writeFile(join(directory, `${ruleId}.yml`), stringify(VALID_RULE));
+    // Both filenames match the `<ruleId>-*-test.yml` discovery pattern, so both
+    // are found; only the second is excluded, and only by its `id:`.
+    await writeFile(
+      join(directory, ".tests", `${ruleId}-a-test.yml`),
+      "id: probe-rule\nvalid:\n  - const a = 1;\n"
+    );
+    await writeFile(
+      join(directory, ".tests", `${ruleId}-b-test.yml`),
+      "id: some-other-rule\nvalid:\n  - const b = 2;\n"
+    );
+
+    const result = await testOneRule(project, { engine: "sg", ruleId });
+    expect(result.ok, result.errors.join("; ")).toBe(false);
+    expect(result.errors.join("\n")).toMatch(/only valid: fixtures/);
+    expect(result.errors.join("\n")).toMatch(/half a claim/);
+    expect(
+      result.violations.map((violation) => violation.constraintId)
+    ).not.toContain("sg-fixture-id-matches-rule");
+  });
+
   it("says which command enforces each, since that decides eval order", () => {
     for (const constraint of RULE_CONSTRAINTS) {
       expect(["verify", "test"]).toContain(constraint.enforcedBy);