fix(specs): update three stale Known gaps in meta-and-quality-tooling.md - #1074
Conversation
Why: three Known gaps bullets described validator checks as missing or pending when all three have shipped (validate_capability_taxonomy_coverage, validate_modes_doc_consistency, and the HARD tool-prerequisites-fields check). The spec-loop plan beat reads Known gaps to choose the next work item, so stale gaps send the loop at finished work. Each rewritten bullet now names the check that closed it and its enforcement level. Closes apache#938 Generated-by: Claude Code (Fable 5)
potiuk
left a comment
potiuk
left a comment
There was a problem hiding this comment.
LGTM. Every claim checks out against the validator source, including the
severity levels — which is the part most likely to be wrong in a change like
this, and isn't.
validate_capability_taxonomy_coverageexists and yields
CAPABILITY_TAXONOMY_CATEGORY, which is inSOFT_CATEGORIES. ✓ SOFTvalidate_modes_doc_consistencyyieldsMODES_DOC_CATEGORY, also in
SOFT_CATEGORIES. ✓ SOFTtool-prerequisites-fieldsisTOOL_PREREQUISITES_FIELDS_CATEGORY, which is
inHARD_CATEGORIES. ✓ HARD
The "four SOFT checks" breakdown for docs/modes.md is also exact — the
docstring enumerates missing skill, mode mismatch, count mismatch, and unlisted
skill, in that order, matching the bullet.
Naming the closing check and its enforcement level (rather than just deleting
the bullet) is the right shape for these: a reader now knows what to grep for
if the gap ever reopens.
This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.More on how Apache Magpie handles maintainer review:
CONTRIBUTING.md § Opening a pull request.
2 participants
Summary
Three
Known gapsbullets intools/spec-loop/specs/meta-and-quality-tooling.mddescribed validator checks as missing or pending when all three have shipped. Each bullet is rewritten to name the check that closed it and its enforcement level, so the spec-loop plan beat stops steering at finished work:validate_capability_taxonomy_coverage(SOFT advisories; (reserved) / (future) rows exempt; also cross-checks theSKILL_CAPABILITIES/TOOL_CAPABILITIESconstants)docs/modes.mdsync →validate_modes_doc_consistency(four SOFT checks: missing skill, mode mismatch, count mismatch, unlisted skill)tool-prerequisites-fieldscheck (bold sub-field labels or the pure-contract delegation shorthand), so the normalize-then-tighten ordering the old bullet tracked is doneType of change
tools/spec-loop/specs/)Test plan
uv run --project tools/spec-validator spec-validate tools/spec-loop/specs/— OK, no violationsprek run --all-files— all 23 hooks passvalidate_capability_taxonomy_coverageat__init__.pyL2283,validate_modes_doc_consistencyat L2821,tool-prerequisites-fieldsinHARD_CATEGORIES), per the issue's "verify by finding the call site" noteRFC-AI-0004 compliance
No runtime behaviour or state-changing workflow is changed — spec prose only.
Linked issues
Closes #938
Generative AI disclosure
Prepared with Claude Code (Fable 5). The commit carries a
Generated-by:trailer and no AICo-Authored-By:trailer.