---
title: "Upgrade Assessment"
description: "Evaluates platform upgrade readiness across Claude model versions, CC releases, and OrchestKit updates with 6-dimensional assessment. Researches target versions, detects current environment, produces structured migration plan with risk scores. Use when planning major version transitions or evaluating upgrade impact."
---

<span className="badge badge-gray">Reference</span> <span className="badge badge-red">max</span>

> **Auto-activated** — this skill loads automatically when Claude detects matching context.

<ContextualSkillSidebar slug="upgrade-assessment" />


# Upgrade Assessment

Evaluate platform upgrade readiness for Claude model transitions, Claude Code version bumps, and OrchestKit plugin updates. Produces a structured JSON assessment report with a 0-10 readiness score across 6 dimensions.

## When to Use

- Before upgrading the Claude model (e.g., Sonnet 4 to Opus 4.6)
- Before upgrading Claude Code to a new major/minor version
- Before upgrading OrchestKit to a new major version
- When evaluating whether a team environment is ready for a platform change
- As part of release planning for model or platform migrations

## Quick Start

```bash
/ork:upgrade-assessment           # Interactive assessment
/ork:upgrade-assessment --json    # Machine-readable output
```

---

## 6-Phase Workflow

### Phase 0: Scope Definition

**Tool:** `AskUserQuestion`

Determine the assessment scope before scanning. Ask the user:

> What type of upgrade are you assessing?
> 1. **Full platform** - Model + CC version + OrchestKit (comprehensive)
> 2. **Model only** - Switching Claude model (e.g., Sonnet 4.5 to Opus 4.6)
> 3. **CC version only** - Claude Code version bump (e.g., 2.1.32 to 2.1.33)
> 4. **OrchestKit only** - Plugin version upgrade (e.g., 5.x to 6.x)

Record the scope and target versions. If the user does not specify target versions, research the latest available in Phase 2.

---

### Phase 1: Detection

**Tools:** `Bash`, `Read`, `Grep`, `Glob`

Run precondition checks and environment detection. Load details: `Read("$\{CLAUDE_SKILL_DIR\}/rules/detection-checks.md")` for verification scripts and expected output format.

---

### Phase 2: Research

**Tools:** `WebSearch`, `WebFetch`

Research the target versions for new capabilities and breaking changes:

1. **Model changes:** Search for target model capabilities, breaking changes, new tool support
2. **CC version changes:** Search for changelog, new hook types, skill format changes, deprecated fields
3. **OrchestKit changes:** Read CHANGELOG.md, identify new/removed/renamed skills, hook migration needs

**Research queries:**
```
"Claude {target_model} capabilities release notes"
"Claude Code {target_version} changelog breaking changes"
"Claude {target_model} vs {current_model} differences"
```

---

### Phase 3: Codebase Scan

**Tools:** `Grep`, `Glob`, `Read`

Scan the codebase for patterns affected by the upgrade. Load details: `Read("$\{CLAUDE_SKILL_DIR\}/rules/codebase-scan-patterns.md")` for grep patterns and severity classification.

---

### Phase 4: Scoring

Rate readiness 0-10 across 6 dimensions using the scoring rubric from `platform-upgrade-knowledge`. Load details: `Read("$\{CLAUDE_SKILL_DIR\}/references/scoring-rubric.md")` for per-dimension thresholds, weights, and score interpretation.

---

### Phase 5: Recommendations

Generate prioritized action items based on Phase 3 findings and Phase 4 scores. Load details: `Read("$\{CLAUDE_SKILL_DIR\}/references/recommendation-format.md")` for priority assignment algorithm, effort estimation, and recommendation structure.

---

## Output Format

The assessment produces a structured JSON report. Load details: `Read("$\{CLAUDE_SKILL_DIR\}/references/output-format.md")` for the full schema and example.

---

## Execution Notes

### For Model-Only Upgrades
Focus on Phases 1, 2, and 3. Key areas:
- Agent `model:` fields
- Context window / output token assumptions
- Capability-dependent skill content (e.g., vision, audio)

### For CC Version Upgrades
Focus on hook compatibility and skill format:
- Hook type registry changes
- Skill frontmatter field additions/removals
- Permission rule format changes
- New built-in tools or removed tools

### For OrchestKit Upgrades
Focus on plugin structure:
- Manifest schema changes
- Build system changes
- Skill/agent rename or removal
- Hook source reorganization

---

## Rules Quick Reference

Load on demand with `Read("$\{CLAUDE_SKILL_DIR\}/rules/&lt;file&gt;")`:

| Rule | Impact | What It Covers |
|------|--------|----------------|
| `detection-checks.md` | HIGH | Precondition checks, environment detection scripts |
| `codebase-scan-patterns.md` | HIGH | Grep patterns, severity classification |
| `knowledge-evaluation.md` | HIGH | 6-dimension scoring rubric, severity classification |
| `knowledge-compatibility.md` | HIGH | Version compatibility matrix, breaking change detection |

## Related Skills

- `platform-upgrade-knowledge` - Scoring rubric details and compatibility matrix
- `ork:doctor` - Post-upgrade health validation
- `ork:explore` - Codebase exploration for impact analysis
- `ork:verify` - Verification of changes after migration
- `ork:devops-deployment` - CI/CD pipeline updates

## References

Load on demand with `Read("$\{CLAUDE_SKILL_DIR\}/references/&lt;file&gt;")`:

| File | Content |
|------|---------|
| `scoring-rubric.md` | Detailed dimension scoring thresholds |
| `recommendation-format.md` | Priority assignment and effort estimation |
| `output-format.md` | JSON report schema and example |

- See `platform-upgrade-knowledge/references/scoring-rubric.md` for additional scoring details
- See `platform-upgrade-knowledge/references/compatibility-matrix.md` for version compatibility tracking


---

## Rules (4)

### Use grep patterns and severity classification to detect upgrade-breaking code changes — HIGH


# Codebase Scan Patterns

Grep patterns and severity classification for Phase 3 of upgrade assessment.

## Scan Patterns

```bash
# 1. Model references (hardcoded model IDs)
grep -r "claude-opus-4\b\|claude-sonnet-4\b\|claude-haiku-3\b" src/ --include="*.md" --include="*.ts" --include="*.json"

# 2. Deprecated API patterns
grep -r "max_tokens_to_sample\|stop_sequences\|model.*claude-2" src/ --include="*.ts" --include="*.py"

# 3. CC version-gated features
grep -r "CC 2\.1\.\|claude-code.*2\.1\." src/ --include="*.md"

# 4. Hook compatibility (check for removed or renamed hook types)
grep -r "PreToolUse\|PostToolUse\|PermissionRequest\|Stop\|Notification" src/hooks/ --include="*.ts" --include="*.json"

# 5. Context window assumptions
grep -r "200000\|200_000\|128000\|128_000\|context.*window\|max_context" src/ --include="*.ts" --include="*.md" --include="*.py"

# 6. Output token assumptions
grep -r "max_tokens.*4096\|max_tokens.*8192\|max_output\|output.*limit" src/ --include="*.ts" --include="*.py"
```

## Severity Classification

Classify each finding by severity:

- **CRITICAL**: Hardcoded model IDs, removed API fields, breaking hook changes
- **WARNING**: Outdated context window assumptions, deprecated patterns
- **INFO**: Version references in documentation, optional feature flags

**Incorrect — Generic grep without severity classification creates unactionable scan reports:**
```bash
grep -r "claude" src/
# 2000 matches with no classification or context
```

**Correct — Targeted grep with severity classification produces actionable findings:**
```bash
# CRITICAL: Hardcoded model IDs
grep -r "claude-opus-4\b\|claude-sonnet-4\b" src/ --include="*.ts"
# WARNING: Context window assumptions
grep -r "200000\|200_000" src/ --include="*.ts" --include="*.md"
# Each finding gets severity label for prioritization
```


### Run precondition verification and environment detection before starting upgrade scans — HIGH


# Detection Checks

Precondition checks and environment detection for Phase 1 of upgrade assessment.

## Precondition Checks

Before scanning, verify the environment is assessable:

```bash
# Verify we're in an OrchestKit project
[ -f CLAUDE.md ] || { echo "ERROR: No CLAUDE.md found — not an OrchestKit project"; exit 1; }
[ -d src/skills ] || { echo "ERROR: No src/skills/ directory"; exit 1; }
[ -d src/agents ] || { echo "ERROR: No src/agents/ directory"; exit 1; }
[ -f src/hooks/hooks.json ] || { echo "WARNING: No hooks.json — hook assessment will be skipped"; }
```

If any required directory is missing, abort with a clear error. If optional components (hooks) are missing, continue with reduced scope and note it in the report.

## Environment Detection

Detect the current environment state:

```bash
# 1. Current Claude model
# Check CLAUDE.md, settings, or environment for model references
grep -r "claude-" CLAUDE.md .claude/ 2>/dev/null | head -20

# 2. Claude Code version
claude --version 2>/dev/null || echo "CC version not detectable from CLI"

# 3. OrchestKit version
# Check CLAUDE.md or package.json for version field
grep "Current.*:" CLAUDE.md | head -5

# 4. Hooks configuration
cat src/hooks/hooks.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Hooks: {len(d.get(\"hooks\",[]))} entries')" 2>/dev/null

# 5. Skill and agent counts
ls src/skills/ | wc -l
ls src/agents/ | wc -l
```

## Expected Output

Environment snapshot including:
- Current model ID (e.g., `claude-sonnet-4-6`)
- Current CC version (e.g., `2.1.33`)
- Current OrchestKit version (e.g., `6.0.0`)
- Hook count and bundle count
- Skill count and agent count

**Incorrect — Running scans without precondition checks produces invalid results:**
```bash
# No environment verification
grep -r "claude-" src/  # Scans in non-OrchestKit project
# False positives and missed files
```

**Correct — Precondition checks ensure valid assessment environment:**
```bash
# Verify OrchestKit project structure
[ -f CLAUDE.md ] && [ -d src/skills ] || exit 1
# Only scan if structure is valid
grep -r "claude-" src/skills/ --include="*.md"
```


### Check platform compatibility for model IDs, API changes, and format changes before upgrading — HIGH


## Platform Compatibility Knowledge

Track compatibility across three independent upgrade axes: Claude model, Claude Code version, and OrchestKit version.

### Model ID Breaking Pattern

Model ID format changed from `claude-\{version\}-\{variant\}` to `claude-\{variant\}-\{version\}` starting with Claude 4:

| From | To | Key Changes |
|------|----|-------------|
| `claude-3-5-sonnet-20241022` | `claude-sonnet-4-20250514` | ID format change, +extended thinking |
| `claude-sonnet-4-20250514` | `claude-sonnet-4-5-20250916` | +1M context |
| `claude-sonnet-4-5-20250916` | `claude-sonnet-4-6` | Performance improvements |
| `claude-opus-4-20250514` | `claude-opus-4-6-20260115` | +1M context, +128K output, +files API |
| `claude-opus-4-6-20260115` | `claude-opus-4-6` | Opus 4.6 1M context GA (no premium, no beta header) |
| `claude-opus-4-6` | `claude-opus-4-7` | Opus 4.7 — xhigh effort (CC 2.1.111+), 3× vision resolution (2,576 px), substantially better filesystem memory + instruction following, updated tokenizer (same pricing as 4.6) |
| `claude-sonnet-4-5-20250929` | `claude-sonnet-4-6` | Sonnet 4.6 (current latest — aliases to this automatically) |

### Common Breaking Changes

| Change | Detection Pattern | Severity |
|--------|-------------------|----------|
| Hardcoded model ID | `grep "claude-.*-\d"` | CRITICAL |
| Context window assumption | `grep "200000\|200_000"` | WARNING |
| Output token assumption | `grep "max_tokens.*4096\|8192"` | WARNING |
| Removed hook type | hooks.json references | CRITICAL |
| Changed hook signature | Hook handler functions | CRITICAL |
| New required frontmatter | Skill/agent YAML | WARNING |
| Deprecated config field | `.claude/settings.json` | WARNING |
| New env var disables 1M | `grep "CLAUDE_CODE_DISABLE_1M_CONTEXT"` | WARNING |
| New hook event types | WorktreeCreate/WorktreeRemove in hooks.json | INFO |
| New agent frontmatter field | `isolation: worktree` | INFO |

### Migration Effort Estimation

| Category | Low (&lt; 1 hour) | Medium (1-4 hours) | High (4+ hours) |
|----------|----------------|--------------------|-----------------|
| Model refs | Find-and-replace IDs | Update conditional logic | Rewrite capability code |
| Hooks | Update registration | Migrate handler signatures | Rewrite hook logic |
| Skills | Add missing frontmatter | Restructure content | Create new skills |
| Agents | Update model field | Update tool/skill refs | Rewrite directives |

### Effort Formula

```
total_hours = sum(
  count[CRITICAL] * 2.0 +
  count[WARNING]  * 0.5 +
  count[INFO]     * 0.1
)
```

### Key Rules

- **Scan first, upgrade second** — run codebase scan before making any changes
- Hardcoded model IDs are **always CRITICAL** — use aliases where possible
- Context window and output limits change across models — **never hardcode**
- Hook type and format changes can **silently break** — test all hooks after upgrade
- Use the **detection patterns** above as a pre-upgrade checklist
- Track each axis **independently** — model, CC version, and OrchestKit can upgrade separately
- **CC 2.1.50** includes 8 memory leak fixes — long sessions (4+ hours) that previously degraded should be retested after upgrading
- **CC 2.1.63** adds HTTP hooks, worktree config sharing, `/simplify`, `/batch`, teammate memory fix, and `ENABLE_CLAUDEAI_MCP_SERVERS` env var
- See the [full CC version matrix](../../doctor/references/version-compatibility.md) for feature-by-feature compatibility

**Incorrect — Hardcoded model ID breaks when upgrading to new Claude version:**
```typescript
const response = await anthropic.messages.create({
  model: "claude-opus-4-20250514",  // Breaks when 4.6 becomes default
  max_tokens: 4096,
});
```

**Correct — Model alias and variable config survives upgrades:**
```typescript
const response = await anthropic.messages.create({
  model: process.env.CLAUDE_MODEL || "claude-opus-latest",
  max_tokens: settings.maxOutputTokens,
});
```


### Evaluate platform upgrades with structured analysis to catch breaking changes before production — HIGH


## Platform Upgrade Evaluation

Score upgrade readiness 0-10 across 6 weighted dimensions. Produces a composite score that determines go/no-go.

### Scoring Dimensions

| Dimension | Weight | What It Measures |
|-----------|--------|------------------|
| Model Compatibility | 0.25 | Hardcoded model refs, capability assumptions, output limits |
| Hook Compatibility | 0.20 | Hook type changes, async patterns, lifecycle changes |
| Skill Coverage | 0.15 | Skill format changes, deprecated skills, new requirements |
| Agent Readiness | 0.15 | Agent format changes, model field validity, tool availability |
| Memory Architecture | 0.10 | Memory tier changes, storage format, migration needs |
| CI/CD Pipeline | 0.15 | Test compatibility, build system, deployment config |

### Score Interpretation

| Range | Label | Action |
|-------|-------|--------|
| 9-10 | Ready | Upgrade with confidence |
| 7-8 | Low Risk | Minor adjustments needed |
| 5-6 | Moderate Risk | Plan a migration sprint |
| 3-4 | High Risk | Significant rework needed |
| 1-2 | Critical Risk | Consider phased migration |
| 0 | Blocked | Cannot upgrade without fundamental changes |

### Severity Classification

| Level | Criteria | Required Action |
|-------|----------|-----------------|
| CRITICAL | Functionality breaks on upgrade | Must fix before upgrade |
| WARNING | Degraded behavior, works incorrectly | Fix in same sprint |
| INFO | Documentation outdated, no functional impact | Update when convenient |

### Priority Assignment

```
dimension_score <= 2:  priority = P0 (Blocker)    — Before upgrade
dimension_score <= 4:  priority = P1 (Critical)   — Same sprint
dimension_score <= 6:  priority = P2 (Important)  — Next sprint
dimension_score <= 8:  priority = P3 (Nice-to-Have) — Backlog
dimension_score > 8:   No action needed
```

### Key Rules

- Score **every dimension** even if it seems fine — assumptions hide breaking changes
- CRITICAL findings are **blockers** — do not upgrade until resolved
- Weighted composite score determines **overall readiness**
- P0 items must be addressed **before** starting the upgrade
- Re-score after addressing findings to **verify improvement**

**Incorrect — Upgrading without evaluation causes production breakage:**
```bash
# Just upgrade without assessment
npm install @anthropic-ai/claude@latest
git commit -m "upgrade claude"
# Production breaks: hardcoded model IDs, hook changes, context limits
```

**Correct — Structured evaluation identifies blockers before upgrade:**
```bash
# Phase 1: Detect environment
./detect-environment.sh
# Phase 2: Score dimensions (finds 3 CRITICAL issues)
./score-compatibility.sh
# Phase 3: Fix P0 blockers BEFORE upgrade
./fix-model-refs.sh && ./migrate-hooks.sh
# Then upgrade safely
```



---

## References (4)

### Cc 2.1.47 Upgrade Guide

# CC 2.1.47 Upgrade Guide

## What Changed

CC 2.1.47 is the new minimum version for OrchestKit 6.0.x. This release includes platform fixes, new hook fields, and UX improvements.

## Breaking Changes

None. CC 2.1.47 is backwards-compatible with all OrchestKit hooks and skills.

## New Hook Input Fields

| Field | Event | Description |
|-------|-------|-------------|
| `last_assistant_message` | Stop, SubagentStop | Final assistant message text from the session/agent |
| `added_dirs` | All events | List of directories added via `--add-dir` or `/add-dir` |

These fields are optional — hooks should always use `input.field ?? fallback` patterns.

## Platform Fixes

### Windows Support
- Hooks now execute on Windows via Git Bash (previously silently failed)
- Windows worktree session matching fixed (drive letter casing)
- PR #645 added Windows-safe spawning to prevent console flashing

### Worktree Support
- Skills and agents are now discovered from worktrees (previously main checkout only)
- Background tasks (`Task` tool) complete successfully from worktrees
- Heartbeat and cleanup hooks work reliably in worktrees

### SessionStart Deferral
- SessionStart hooks now fire ~500ms after session init
- All OrchestKit SessionStart hooks are compatible with this deferral
- Async hooks (`unified-dispatcher`, `pr-status-enricher`) are unaffected (already fire-and-forget)
- Sync hooks (`session-context-loader`, `prefill-guard`, `mcp-health-check`) still run before first prompt

## UX Improvements

| Feature | Shortcut | Description |
|---------|----------|-------------|
| Find in output | `Ctrl+F` | Search through all session output |
| Multi-line input | `Shift+Down` | Enter multi-line prompts without sending |

## Agent Teams Improvements

- `model` field in agent frontmatter is now respected in team spawns
- Improved agent memory provides larger context for spawned agents
- `TeammateIdle` and `TaskCompleted` events available since CC 2.1.33

## OrchestKit Adoption Summary

### Hooks Updated
- `monorepo-detector`: Skips `--add-dir` suggestion when `added_dirs` already active
- `session-summary`: Tracks `added_dirs_count` and classifies `session_outcome`
- `session-tracking`: Passes `added_dirs_count` to session context
- `session-cleanup`: Includes `last_msg_len` and `added_dirs_count` in analytics
- `session-context-loader`: Scans added directories for context files
- `subagent-stop/unified-dispatcher`: Tracks `last_msg_len` in agent analytics
- `auto-approve-project-writes`: Already supports `added_dirs` (reference implementation)

### Skills Updated
- `doctor`: Version compatibility matrix with all CC 2.1.47 features
- `configure`: Team plugin distribution docs
- `worktree-coordination`: CC 2.1.47 platform support table
- `help`: CC keyboard shortcuts reference

### Runtime Utilities
- `cc-version-matrix.ts`: 18-feature matrix with version comparison and query helpers
- `hasFeature(version, feature)`: Check if a feature is available at a given CC version

## Verification

Run the doctor skill to verify your CC version:

```bash
/ork:doctor
```

Check 10 (Claude Code Version) validates CC >= 2.1.47 and reports missing features for older versions.

## Rollback

If you need to downgrade below CC 2.1.47:
- OrchestKit hooks will continue to work in degraded mode
- `added_dirs` and `last_assistant_message` fields will be undefined (hooks handle this gracefully)
- Windows hook execution will fail silently
- Worktree discovery will not find skills/agents from worktrees


### Output Format

# Output Format

The upgrade assessment produces a structured JSON report with the following schema.

## JSON Report Schema

```json
{
  "assessment": {
    "id": "upgrade-assessment-{timestamp}",
    "scope": "full|model-only|cc-only|ork-only",
    "timestamp": "2026-02-06T12:00:00Z"
  },
  "environment": {
    "current": {
      "model": "claude-sonnet-4-6",
      "ccVersion": "2.1.32",
      "orkVersion": "6.0.0",
      "hooks": 121,
      "skills": 199,
      "agents": 38
    },
    "target": {
      "model": "claude-opus-4-6",
      "ccVersion": "2.1.33",
      "orkVersion": "6.1.0"
    }
  },
  "scores": {
    "overall": 7.4,
    "dimensions": {
      "modelCompatibility": { "score": 8, "weight": 0.25, "weighted": 2.0 },
      "hookCompatibility": { "score": 9, "weight": 0.20, "weighted": 1.8 },
      "skillCoverage": { "score": 7, "weight": 0.15, "weighted": 1.05 },
      "agentReadiness": { "score": 7, "weight": 0.15, "weighted": 1.05 },
      "memoryArchitecture": { "score": 6, "weight": 0.10, "weighted": 0.6 },
      "cicdPipeline": { "score": 6, "weight": 0.15, "weighted": 0.9 }
    }
  },
  "findings": [
    {
      "severity": "CRITICAL",
      "dimension": "modelCompatibility",
      "description": "Hardcoded model ID 'claude-sonnet-4' in 3 agent files",
      "files": ["src/agents/code-reviewer.md", "src/agents/architect.md"],
      "recommendation": "Update model field to 'claude-opus-4-6' or use 'sonnet' alias"
    },
    {
      "severity": "WARNING",
      "dimension": "skillCoverage",
      "description": "Context window references assume 200K tokens, Opus 4.6 supports 1M",
      "files": ["src/skills/context-engineering/SKILL.md"],
      "recommendation": "Update token budget calculations for 1M context window"
    }
  ],
  "recommendations": [
    {
      "priority": "P0",
      "action": "Update hardcoded model references",
      "effort": "low",
      "files": ["src/agents/*.md"],
      "steps": [
        "Grep for 'claude-sonnet-4' and 'claude-opus-4' in src/",
        "Replace with target model ID or use alias",
        "Run npm run test:agents to validate"
      ]
    },
    {
      "priority": "P2",
      "action": "Update context budget calculations",
      "effort": "medium",
      "files": ["src/skills/context-engineering/SKILL.md"],
      "steps": [
        "Update MAX_CONTEXT values for new model",
        "Adjust compression triggers if context window changed",
        "Update documentation examples"
      ]
    }
  ],
  "summary": {
    "readiness": "Low Risk",
    "overallScore": 7.4,
    "blockers": 0,
    "criticalItems": 1,
    "totalFindings": 5,
    "estimatedEffort": "4-6 hours"
  }
}
```


### Recommendation Format

# Recommendation Format

Priority assignment, effort estimation, and recommendation structure for Phase 5 of upgrade assessment.

## Priority Assignment Algorithm

Map dimension scores to priority levels:

```
For each finding from Phase 3:
  dimension_score = Phase 4 score for the finding's dimension

  if dimension_score <= 2:  priority = "P0"  # Blocker
  if dimension_score <= 4:  priority = "P1"  # Critical
  if dimension_score <= 6:  priority = "P2"  # Important
  if dimension_score <= 8:  priority = "P3"  # Nice-to-Have
  if dimension_score > 8:   # No action needed
```

## Priority Levels

| Priority | Criteria | Timeline |
|----------|----------|----------|
| **P0 - Blocker** | Score 0-2 in any dimension; will break on upgrade | Before upgrade |
| **P1 - Critical** | Score 3-4; degraded functionality post-upgrade | Same sprint |
| **P2 - Important** | Score 5-6; works but suboptimal | Next sprint |
| **P3 - Nice-to-Have** | Score 7-8; minor improvements available | Backlog |

## Effort Estimation

```
effort = "low"     # Single file, < 5 lines changed
effort = "medium"  # 2-5 files, or schema migration
effort = "high"    # 6+ files, or architectural change
```

## Recommendation Structure

Each recommendation includes:
1. **What**: Description of the change needed
2. **Why**: Impact if not addressed
3. **How**: Specific steps or code changes
4. **Effort**: Low (&lt; 1 hour), Medium (1-4 hours), High (4+ hours)
5. **Files**: List of affected files


### Scoring Rubric

# Scoring Rubric

Detailed per-dimension scoring thresholds for Phase 4 of upgrade assessment.

## Dimensions and Weights

| Dimension | Weight | What It Measures |
|-----------|--------|------------------|
| **Model Compatibility** | 0.25 | Hardcoded model refs, capability assumptions, output limit assumptions |
| **Hook Compatibility** | 0.20 | Hook type changes, async pattern changes, lifecycle changes |
| **Skill Coverage** | 0.15 | Skill format changes, deprecated skills, new required skills |
| **Agent Readiness** | 0.15 | Agent format changes, model field validity, tool availability |
| **Memory Architecture** | 0.10 | Memory tier changes, storage format changes, migration needs |
| **CI/CD Pipeline** | 0.15 | Test compatibility, build system changes, deployment config |

## Score Interpretation

| Range | Label | Meaning |
|-------|-------|---------|
| 9-10 | Ready | Upgrade with confidence, minimal changes needed |
| 7-8 | Low Risk | Minor adjustments required, safe to proceed |
| 5-6 | Moderate Risk | Several changes needed, plan a migration sprint |
| 3-4 | High Risk | Significant rework required, thorough testing needed |
| 1-2 | Critical Risk | Major incompatibilities, consider phased migration |
| 0 | Blocked | Cannot upgrade without fundamental changes |

## Weighted Score Calculation

```
overall_score = sum(dimension_score * weight for each dimension)
```

## Per-Dimension Scoring Thresholds

Score each dimension 0-10 based on Phase 3 findings:

**Model Compatibility (weight: 0.25)**
- 10: No hardcoded model IDs, no capability assumptions
- 8: Documentation-only model references (non-functional)
- 6: 1-3 hardcoded model IDs in functional code
- 4: Output token limits or context window hardcoded
- 2: Model-specific API patterns (e.g., prefilling for Claude, function calling format)
- 0: Core logic depends on model-specific behavior

**Hook Compatibility (weight: 0.20)**
- 10: All hooks use current event types and async patterns
- 8: Minor deprecation warnings, no functional impact
- 6: 1-3 hooks use deprecated event types
- 4: Hook input/output schema changed
- 2: Hook lifecycle order changed
- 0: Hook system replaced or fundamentally restructured

**Skill Coverage (weight: 0.15)**
- 10: All skills use current frontmatter format, no stale references
- 8: Minor version references outdated in skill content
- 6: 1-5 skills reference deprecated features or removed capabilities
- 4: Skill frontmatter schema changed (new required fields)
- 2: Skill loading mechanism changed
- 0: Skill format incompatible

**Agent Readiness (weight: 0.15)**
- 10: All agents use valid model aliases, tools, and frontmatter
- 8: 1-2 agents reference removed tools or deprecated fields
- 6: Agent model field values changed meaning
- 4: Agent frontmatter schema requires migration
- 2: Agent tool availability significantly changed
- 0: Agent system incompatible

**Memory Architecture (weight: 0.10)**
- 10: Memory tiers unchanged, storage format stable
- 8: New optional memory tier available
- 6: Memory storage format changed (migration available)
- 4: Memory tier behavior changed (e.g., scope semantics)
- 2: Memory migration required with data transformation
- 0: Memory system replaced

**CI/CD Pipeline (weight: 0.15)**
- 10: All tests pass, build system unchanged
- 8: Minor test assertion updates needed
- 6: Test framework or runner version update needed
- 4: Build configuration changes required
- 2: CI pipeline restructure needed
- 0: Build system incompatible

