Dogfood: migrate pair itself via the published prompt (states, context, working/)

[rucka]

Story Statement

As a pair maintainer
I want pair itself migrated to the new structure (canonical states mapping, context-map, .pair/working/) by executing the published migration prompt
So that the migration recipe is validated end-to-end by dogfooding before being distributed

Where: pair repo (.pair/ adoption + WoW) + validation feedback into the docs migration page

Epic Context

Parent Epic: Versioning & migrazione adoption/KB #214
Status: Refined
Priority: P1 (Should-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given the published migration page for the structural release
   When its copy-paste prompt is executed on the pair repo itself
   Then the migration completes using ONLY the prompt (no undocumented manual steps) — any gap found is fixed in the page first, then re-run

2. Given the migrated repo
   When inspecting adoption
   Then WoW carries the state-mapping section (legacy Refined ⇒ Ready), adoption/product/context-map.md exists with pair's canonical terms (Macrostato, State mapping, DoR/DoS, Risk Tier, Risk Matrix, DDR, Context Map, Checkpoint/Handoff, Macro-fase, Supervisore, Working area, Report consolidato, Marketplace, Quickstart, Process profile), and .pair/working/ exists and is excluded from KB registries

3. Given the migrated repo
   When the KB version check runs and a skill session starts
   Then the check reports clean and skills resolve states via the mapping (no regression on the current flow)

Business Rules

• The published prompt is the single migration path — divergence = bug in the page, not a local workaround (D20)
• Migration touches adoption/config only; no skill or KB logic changes in this story

Edge Cases and Error Handling

• Prompt partially applied then interrupted: re-run must resume idempotently (verifies the page's resume guidance)
• Artifacts not yet delivered by Canonical states, n-m mapping, DoR/DoD, refine=Draft→Ready #202/Domain model: context map, DDR, analysis log #203/Split implement: checkpoint + publish-pr via subagent #206: story HALTs on missing prerequisites, not worked around

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Code review completed and approved
• Documentation updated — docs site (apps/website): migration page corrected with dogfood findings
• CLI (apps/pair-cli): version check passes on the migrated repo (no CLI changes expected)

Quality Assurance

• Full skill smoke session on the migrated repo (pair-next, refine, implement entry points)
• Idempotency re-run of the prompt verified

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 5 (L)
Confidence Level: Medium
Sizing Justification: execution is cheap but validation is broad (states, context, working/, registries, skill smoke) and feeds page fixes — confirmed L(5)

Sprint Capacity Validation

Sprint Fit Assessment: yes, once prerequisites land
Total Effort Assessment: fits — Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: migration page (sibling, executes its prompt); version check (sibling, used to verify); structural artifacts from #202 (states/mapping), #203 (context-map), #206 (.pair/working/ + registry exclusion)
Dependent Stories: none — closes the epic loop (recipe distributed after this)

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: scripted agent run of the published prompt; adoption-file inspection checklist; skill smoke session; re-run for idempotency
Test Data Requirements: pair repo pre-migration snapshot (branch) for comparison/rollback

Notes and Additional Context

Refinement Session Insights: D20 — "pair itself = first structured migration test; dogfooding, then the recipe ships"; canonical-terms list from the domain-model annotation (Spec G4)
Documentation Links: D20 · Spec G4 (canonical terms) · epic AC1–AC3

Technical Analysis

Implementation Approach

Technical Strategy: branch → execute published prompt with a clean agent session → inspect against checklist → fix page where the prompt fell short → re-run from snapshot → merge migrated adoption
Key Components: migration branch, adoption checklist, page feedback loop
Integration Points: docs migration page, kb-info version check, WoW state-mapping consumers

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Prerequisites slip (#202/#203/#206)	Medium	Medium	story scheduled last in epic; HALT rule on missing artifacts
Prompt works on pair but not on consumer layouts	Medium	Low	fixture consumer run already covered by the pages story; divergences noted on the page

Task Breakdown

Checklist

• T1 — Pre-migration snapshot branch + adoption checklist
• T2 — Execute published prompt (clean session) + record gaps
• T3 — Page fixes + idempotent re-run from snapshot
• T4 — Skill smoke session + version-check verification + merge

Dependency Graph

T1 → T2 → T3 → T4

AC Coverage

Task	AC1	AC2	AC3
T1		✓
T2	✓	✓
T3	✓
T4		✓	✓