chore: sync .cursor skills from suite

.cursor/skills/refactor/SKILL.md

@@ -24,6 +24,7 @@ Phase details live in `phases/` — read the relevant file before executing each
 - **Save immediately**: write artifacts to disk after each phase
 - **Delegate execution**: all code changes go through the implement skill via task files
 - **Ask, don't assume**: when scope or priorities are unclear, STOP and ask the user
+- **Exact-fit recommendations**: do not recommend a replacement pattern, library, service, architecture, algorithm, or "modern approach" merely because it improves structure or solves a similar class of problem. It must fit confirmed product constraints, acceptance criteria, operating context, integration boundaries, and current code realities. Otherwise reject it, mark it experimental, or ask the user before adding it to the roadmap.
 
 ## Context Resolution
 

.cursor/skills/refactor/phases/02-analysis.md

@@ -7,14 +7,17 @@
 ## 2a. Deep Research
 
 1. Analyze current implementation patterns
-2. Research modern approaches for similar systems
-3. Identify what could be done differently
-4. Suggest improvements based on state-of-the-art practices
+2. Extract the **Project Constraint Matrix** from `problem.md`, `restrictions.md`, `acceptance_criteria.md`, current architecture/docs, and actual code constraints. Include required inputs/outputs, operating context, lifecycle assumptions, integration boundaries, non-functional targets, and hard disqualifiers.
+3. Research modern approaches for similar systems
+4. For each alternative pattern/library/service/architecture/algorithm, research intrinsic implementation constraints: required inputs/outputs, runtime assumptions, supported deployment modes, resource needs, operational limits, licensing/security constraints, and known failure reports.
+5. Identify what could be done differently
+6. Suggest improvements only when they fit the Project Constraint Matrix. A cleaner or more modern approach that violates product constraints must be marked `Rejected` or `Experimental only`, not added as a roadmap recommendation.
 
 Write `RUN_DIR/analysis/research_findings.md`:
 - Current state analysis: patterns used, strengths, weaknesses
 - Alternative approaches per component: current vs alternative, pros/cons, migration effort
 - Prioritized recommendations: quick wins + strategic improvements
+- Constraint-fit table: recommendation, constraints checked, evidence, mismatches/disqualifiers, status (`Selected` / `Rejected` / `Experimental only` / `Needs user decision`)
 
 ## 2b. Solution Assessment & Hardening Tracks
 
@@ -22,6 +25,7 @@ Write `RUN_DIR/analysis/research_findings.md`:
 2. Identify weak points in codebase, map to specific code areas
 3. Perform gap analysis: acceptance criteria vs current state
 4. Prioritize changes by impact and effort
+5. Reject or escalate any proposed refactor that improves code structure while weakening required behavior, integration contracts, runtime constraints, safety/security posture, or acceptance criteria
 
 Present optional hardening tracks for user to include in the roadmap:
 
@@ -47,6 +51,9 @@ Write `RUN_DIR/analysis/refactoring_roadmap.md`:
 - Gap analysis: what's missing, what needs improvement
 - Phased roadmap: Phase 1 (critical fixes), Phase 2 (major improvements), Phase 3 (enhancements)
 - Selected hardening tracks and their items
+- Applicability gate: each roadmap item must state constraint fit, mismatches, required evidence, and status (`Selected` / `Rejected` / `Experimental only` / `Needs user decision`)
+
+**BLOCKING applicability gate**: Before 2c and 2d, every recommendation in the roadmap must be `Selected`. Items marked `Rejected` are excluded. Items marked `Experimental only` or `Needs user decision` require a user decision before task creation.
 
 ## 2c. Create Epic
 
@@ -79,6 +86,9 @@ Convert the finalized `RUN_DIR/list-of-changes.md` into implementable task files
 **Self-verification**:
 - [ ] All acceptance criteria are addressed in gap analysis
 - [ ] Recommendations are grounded in actual code, not abstract
+- [ ] Every recommendation has been checked against the Project Constraint Matrix
+- [ ] No recommendation violates product restrictions, acceptance criteria, documented architecture decisions, or actual code integration boundaries
+- [ ] Rejected and experimental approaches are documented but not converted into implementation tasks without user approval
 - [ ] Roadmap phases are prioritized by impact
 - [ ] Epic created and all tasks linked to it
 - [ ] Every entry in list-of-changes.md has a corresponding task file in TASKS_DIR

.cursor/skills/refactor/templates/list-of-changes.md

@@ -23,6 +23,7 @@ Save as `RUN_DIR/list-of-changes.md`. Produced during Phase 1 (Discovery).
 - **Problem**: [what makes this problematic / untestable / coupled]
 - **Change**: [what to do — behavioral description, not implementation steps]
 - **Rationale**: [why this change is needed]
+- **Constraint Fit**: [which product constraints / acceptance criteria / integration boundaries this preserves; or "Rejected — violates ..."]
 - **Risk**: [low | medium | high]
 - **Dependencies**: [other change IDs this depends on, or "None"]
 
@@ -31,6 +32,7 @@ Save as `RUN_DIR/list-of-changes.md`. Produced during Phase 1 (Discovery).
 - **Problem**: [description]
 - **Change**: [description]
 - **Rationale**: [description]
+- **Constraint Fit**: [description]
 - **Risk**: [low | medium | high]
 - **Dependencies**: [C01, or "None"]
 ```
@@ -44,6 +46,8 @@ Save as `RUN_DIR/list-of-changes.md`. Produced during Phase 1 (Discovery).
 - **File(s)** must reference actual files verified to exist in the codebase
 - **Problem** describes the current state, not the desired state
 - **Change** describes what the system should do differently — behavioral, not prescriptive
+- **Constraint Fit** proves the change preserves confirmed product requirements, restrictions, acceptance criteria, architecture decisions, and integration contracts
+- Do not include changes whose only benefit is structural cleanliness if they weaken required behavior or violate constraints; record those as rejected in analysis instead
 - **Dependencies** reference other change IDs within this list; cross-run dependencies use tracker IDs
 - In guided mode, the input file entries are validated against actual code and enriched with file paths, risk, and dependencies before writing
 - In automatic mode, entries are derived from Phase 1 component analysis and Phase 2 research findings