Story Statement
As a Pair maintainer/reviewer
I want the mirror-equality guard to also assert dataset↔root equality for the companion .md docs that live inside a skill directory (not only SKILL.md)
So that drift in those auxiliary composed files is caught by CI instead of by hand, closing the residual gap left by #352.
Context / Origin
Found during independent review of PR #377 (story #352). PR #377 added packages/knowledge-hub/src/tools/skill-md-mirror.{ts,test.ts}, a data-driven guard asserting every root .claude/skills/<prefixed>/SKILL.md equals the real pair update copy-pipeline transform of its dataset source. That guard is intentionally scoped to SKILL.md only (matches #352's ACs).
However, several skill directories also ship companion .md docs that are mirrored into root and transformed by the same pipeline (link-depth + /command rewrites), yet are guarded by no dataset↔root equality test:
.claude/skills/pair-process-review/degradation-levels.md, merge-and-cascade.md
.claude/skills/pair-process-bootstrap/assess-orchestration.md
.claude/skills/pair-process-implement/post-review-merge.md
(skills-conformance-check.ts scans these dataset files for frontmatter/link invariants but does not assert their root-mirror equality.)
These files carry the identical drift risk that #352 closed for SKILL.md and #350 fixed by hand.
Acceptance Criteria
- Given the dataset
.skills tree and the root .claude/skills tree are in sync, When the guard runs, Then for every .md file in every dataset skill dir (SKILL.md and companions) it asserts the root mirror is byte-for-byte the real copy-pipeline transform.
- Given a companion doc's root mirror drifts (link-depth or
/command not rewritten) or is missing, When the guard runs, Then it FAILS loudly naming the offending file + pair update regenerate hint.
- Data-driven: a new companion doc is covered automatically with no test edit.
Notes
- The existing
buildInstalledSkillMd in skill-md-mirror.ts already runs the full tree through the real pipeline in-memory — extending from "read the one SKILL.md per prefixed dir" to "read every produced .md per prefixed dir" is the natural implementation seam.
- R7.2 tech-debt: additive, non-blocking.
Priority: P2 (tech-debt)
Story Statement
As a Pair maintainer/reviewer
I want the mirror-equality guard to also assert dataset↔root equality for the companion
.mddocs that live inside a skill directory (not onlySKILL.md)So that drift in those auxiliary composed files is caught by CI instead of by hand, closing the residual gap left by #352.
Context / Origin
Found during independent review of PR #377 (story #352). PR #377 added
packages/knowledge-hub/src/tools/skill-md-mirror.{ts,test.ts}, a data-driven guard asserting every root.claude/skills/<prefixed>/SKILL.mdequals the realpair updatecopy-pipeline transform of its dataset source. That guard is intentionally scoped to SKILL.md only (matches #352's ACs).However, several skill directories also ship companion
.mddocs that are mirrored into root and transformed by the same pipeline (link-depth +/commandrewrites), yet are guarded by no dataset↔root equality test:.claude/skills/pair-process-review/degradation-levels.md,merge-and-cascade.md.claude/skills/pair-process-bootstrap/assess-orchestration.md.claude/skills/pair-process-implement/post-review-merge.md(
skills-conformance-check.tsscans these dataset files for frontmatter/link invariants but does not assert their root-mirror equality.)These files carry the identical drift risk that #352 closed for
SKILL.mdand #350 fixed by hand.Acceptance Criteria
.skillstree and the root.claude/skillstree are in sync, When the guard runs, Then for every.mdfile in every dataset skill dir (SKILL.md and companions) it asserts the root mirror is byte-for-byte the real copy-pipeline transform./commandnot rewritten) or is missing, When the guard runs, Then it FAILS loudly naming the offending file +pair updateregenerate hint.Notes
buildInstalledSkillMdinskill-md-mirror.tsalready runs the full tree through the real pipeline in-memory — extending from "read the one SKILL.md per prefixed dir" to "read every produced .md per prefixed dir" is the natural implementation seam.Priority: P2 (tech-debt)