Skip to content

[tech-debt] Extend mirror-equality guard to non-SKILL.md skill artifacts #383

Description

@rucka

Context

Follow-up from PR #377 (story #352). The mirror-equality guard added in #352 asserts dataset→root equality only for each skill's SKILL.md. Other artifacts under a skill dir that flow through the same pair update transform are copied and link-rewritten by the pipeline but are not asserted, so a hand-edit to a root sub-doc drifts undetected.

Examples of currently-unguarded artifacts:

  • process-review sub-docs: merge-and-cascade.md, degradation-levels.md, post-review-merge.md
  • any references/* under a skill dir

This was deliberately out of scope for #352 (per-skill SKILL.md, single assertion surface). Extending to all skill artifacts is a distinct guard: multiple files per skill and a different assertion surface (enumerate every transformed file per skill dir, not just SKILL.md).

User story

As a maintainer, I want the mirror-equality invariant extended to every pair update-transformed skill artifact (not just SKILL.md) so that a hand-edit to any root skill sub-doc / reference is caught by CI.

Acceptance criteria

  • Guard asserts dataset→root equality for all files each skill dir emits through the copy pipeline, not only SKILL.md.
  • Data-driven: new artifacts covered automatically, no hardcoded file lists.
  • Directional (dataset→root); root-only files with no dataset source are not flagged.
  • Loud failure names the skill + offending file and shows the diff.

Notes

Reuse the existing buildInstalledSkillMd / real-pipeline approach in packages/knowledge-hub/src/tools/skill-md-mirror.ts; broaden the per-skill enumeration from SKILL.md to the full transformed file set.

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