Skip to content

fix: widen the matrix-count guard past the shape it missed - #777

Merged
endavis merged 1 commit into
mainfrom
fix/774-matrix-count-guard
Aug 29, 2026
Merged

fix: widen the matrix-count guard past the shape it missed#777
endavis merged 1 commit into
mainfrom
fix/774-matrix-count-guard

Conversation

@endavis

@endavis endavis commented Aug 29, 2026

Copy link
Copy Markdown
Owner

Description

#754 added test_only_the_matrix_doc_states_counts so a matrix count could not be written into
prose where nothing checks it. Its pattern required a qualifying noun — \d+ distinct files
matched, a bare \d+ files did not — so this line in .copilot/README.md, inside a file the test
explicitly scans
, passed:

- `.github/skills/<target>-<action>/SKILL.md` — Copilot-host workflow skills (16 files).

The number was right. That is the point: it is the same state the five wrong counts were in before
#754 — accurate, in prose, and unguarded while believed to be guarded. A guard trusted more than
it deserves is worse than no guard, because it stops anyone looking.

Related Issue

Addresses #774

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Code refactoring
  • Test improvement

Changes Made

Both halves, as the issue set out.

  1. The line is now structural — "one self-action skill per action, plus one bridge per (target,
    action) pair" — which is what refactor: cross-agent matrix counts are duplicated in eight places and verified in none #754 did everywhere else. The count belongs to
    cross-agent-delegation.md's Matrix section and nowhere else.
  2. The pattern gains the bare nouns: files, entries, skills, bridges, commands.

The risk in widening, and what was done about it

The issue warned that widening has an opposite failure mode: a pattern matching ordinary prose makes
the guard noise rather than signal. So the noun set was checked against all four scanned documents
before landing
— it hits the one known line and nothing else.

Three benign strings are pinned as cases so a later widening cannot quietly start matching prose:

for benign in ("takes 1 to 3 minutes", "Python 3.14 support", "the 4 sources are listed above"):
    assert not _COUNT_IN_PROSE.search(benign)

…alongside the shape that was missed:

assert _COUNT_IN_PROSE.search("Copilot-host workflow skills (16 files)")

Testing

  • All existing tests pass
  • Added new tests for new functionality
  • Manually tested the changes

doit check and mkdocs build --strict pass; 56 matrix tests green.

Verified by mutation in both directions:

mutation result
narrow the pattern back to cells only test_the_count_checks_detect_a_planted_error fails
restore (16 files) in .copilot/README.md test_only_the_matrix_doc_states_counts[.copilot/README.md] fails

The second is the one that matters — it is the check that should have caught this the first time,
and now does.

Checklist

  • My code follows the code style of this project (ran doit format)
  • I have run linting checks (doit lint)
  • I have run type checking (doit type_check)
  • I have added tests that prove my fix is effective or that my feature works
  • All new and existing tests pass (doit test)
  • I have updated the documentation accordingly — N/A beyond the one line made structural
  • I have updated the CHANGELOG.md — N/A, generated on release (update_changelog_on_bump)
  • My changes generate no new warnings

Additional Notes

This closes the review that produced #772, #773 and #774.

Worth recording that two of the three findings were defects in guards I had written earlier the same
day — this one, and the portability trap in #773's guard that passed locally and failed all six CI
jobs. The pattern is consistent: a guard is easy to write so that it passes, and the work is in
proving it fails for the right reason. Every guard added since is mutation-tested for exactly that.

#754 added test_only_the_matrix_doc_states_counts so a matrix count could not
be written into prose where nothing checks it. Its pattern required a
qualifying noun -- `\d+ distinct files` matched, a bare `\d+ files` did not --
so this line in .copilot/README.md, inside a file the test explicitly scans,
passed:

    Copilot-host workflow skills (16 files).

The number was right. That is the point: it is the same state the five wrong
counts were in before #754 -- accurate, in prose, and unguarded while believed
to be guarded. A guard trusted more than it deserves is worse than no guard,
because it stops anyone looking.

Both halves are fixed. The line is now structural, which is what #754 did
everywhere else: the count belongs to cross-agent-delegation.md's Matrix
section and nowhere else. And the pattern gains the bare nouns -- files,
entries, skills, bridges, commands.

Widening a pattern in a guard risks the opposite failure, so the noun set was
checked against all four scanned documents before landing: it hits the one known
line and nothing else. Three benign strings are pinned as cases so a later
widening cannot quietly start matching ordinary prose, alongside the shape that
was missed.

Verified by mutation in both directions: narrowing the pattern back fails the
planted-error test, and restoring the old wording in .copilot/README.md fails
the scan that should have caught it the first time.

Addresses #774
@endavis endavis added the ready-to-merge PR is reviewed and ready to merge label Aug 29, 2026
@endavis
endavis merged commit b044134 into main Aug 29, 2026
26 of 27 checks passed
@endavis
endavis deleted the fix/774-matrix-count-guard branch August 29, 2026 20:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-to-merge PR is reviewed and ready to merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant