Skip to content

tech-debt: extend mirror-equality guard to all root skill artifacts (sub-docs + references) #384

Description

@rucka

Story Statement

As a maintainer of the Pair knowledge base
I want the mirror-equality guard to assert every root skill artifact (not just each skill's SKILL.md)
So that a hand-edit to any root sub-doc or references/* that should be regenerated by pair update is caught in CI, not silently drifted.

Epic Context

Parent Epic: KB / mirror integrity (Integration & Process Standardization bounded context)
Status: Todo
Priority: P2 (Could-Have)

User Value

User Benefit: Complete drift protection for the root skills mirror — no artifact can silently diverge from its dataset source.
Business Impact: Extends the per-SKILL.md invariant delivered by #352 to full per-skill artifact coverage, closing the residual scope gap.

Context / Origin

Follow-up from PR #377 (#352) review. #352's guard (packages/knowledge-hub/src/tools/skill-md-mirror.ts) deliberately asserts mirror-equality only for each skill's SKILL.md. Other artifacts under a skill dir that flow through the same pair update transform — sub-docs (e.g. process-review's merge-and-cascade.md, degradation-levels.md, post-review-merge.md) and references/* — are copied and rewritten by the pipeline but are not asserted, so a hand-edit to a root sub-doc drifts undetected.

This is a broader, distinct guard: multiple files per skill and a different assertion surface (directory-tree equality rather than a single named file), large enough to warrant its own story rather than being folded into #352.

Rough Sizing

Story Points: M(3)
Confidence: Medium
Reasoning: Reuses the existing real-pipeline composition; new work is enumerating all transformed artifacts per skill and asserting tree-level equality.

Acceptance Criteria (draft)

Metadata

Metadata

Assignees

No one assigned

    Labels

    tech-debtTracked technical debt (living backlog, R7.2 — never blocks a PR)user storyWork item representing a user story

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions