Skip to content

tech-debt: extend mirror-equality guard to per-skill companion .md docs (not just SKILL.md) #380

Description

@rucka

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

  1. 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.
  2. 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.
  3. 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)

Metadata

Metadata

Assignees

No one assigned

    Labels

    tech-debtTracked technical debt (living backlog, R7.2 — never blocks a PR)

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions