wxcli 1.2.0__py3-none-any.whl

wxcli/main.py

@@ -0,0 +1,210 @@
+import typer
+from datetime import datetime, timezone
+
+from wxcli import __version__
+from wxcli.auth import get_api, resolve_token, WebexApi, WebexSession
+from wxcli.config import get_expires_at, get_org_id, get_org_name, save_org
+
+app = typer.Typer(
+    name="wxcli",
+    help="Webex Calling CLI — provision and manage Webex Calling from the terminal.",
+    no_args_is_help=True,
+)
+
+
+def version_callback(value: bool):
+    if value:
+        typer.echo(f"wxcli {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(False, "--version", callback=version_callback, is_eager=True),
+):
+    pass
+
+
+@app.command()
+def whoami(
+    debug: bool = typer.Option(False, "--debug", help="Show debug output"),
+):
+    """Show current authenticated user and org."""
+    api = get_api(debug=debug)
+    me = api.session.rest_get("https://webexapis.com/v1/people/me")
+
+    display_name = me.get("displayName", "")
+    email = (me.get("emails") or ["unknown"])[0]
+    org_id = me.get("orgId", "")
+    typer.echo(f"User:  {display_name} ({email})")
+    typer.echo(f"Org:   {org_id}")
+
+    target_org_id = get_org_id()
+    target_org_name = get_org_name()
+    if target_org_id:
+        typer.echo(f"Target: {target_org_id}  ({target_org_name})")
+
+    roles = me.get("roles")
+    if roles:
+        typer.echo(f"Roles: {', '.join(roles)}")
+
+    expires = get_expires_at()
+    if expires:
+        try:
+            exp_dt = datetime.fromisoformat(expires)
+            now = datetime.now(timezone.utc)
+            remaining = exp_dt - now
+            if remaining.total_seconds() > 0:
+                hours = int(remaining.total_seconds() // 3600)
+                minutes = int((remaining.total_seconds() % 3600) // 60)
+                if hours < 2:
+                    typer.echo(f"Token: expires in {hours}h {minutes}m — consider refreshing soon")
+                else:
+                    typer.echo(f"Token: expires in {hours}h {minutes}m")
+        except ValueError:
+            pass
+
+
+@app.command("switch-org")
+def switch_org(
+    org_id: str = typer.Argument(None, help="orgId to switch to (skip interactive prompt)"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Switch target organization for partner multi-org tokens."""
+    token = resolve_token()
+    if not token:
+        typer.echo("Error: No token found. Run 'wxcli configure' first.", err=True)
+        raise typer.Exit(1)
+
+    api = WebexApi(WebexSession(token))
+
+    if org_id:
+        # Direct switch — resolve org name
+        try:
+            org = api.session.rest_get(f"https://webexapis.com/v1/organizations/{org_id}")
+            org_name = org.get("displayName", "Unknown")
+        except Exception:
+            org_name = "Unknown"
+        save_org(org_id, org_name)
+        typer.echo(f"Target org set: {org_name} ({org_id})")
+        return
+
+    # Interactive — list orgs
+    try:
+        result = api.session.rest_get("https://webexapis.com/v1/organizations")
+        items = result.get("items", []) if isinstance(result, dict) else []
+    except Exception as e:
+        typer.echo(f"Error listing organizations: {e}", err=True)
+        raise typer.Exit(1)
+
+    if len(items) <= 1:
+        typer.echo("Single-org token — no org switching needed.")
+        return
+
+    typer.echo(f"\nAvailable organizations:\n")
+    for i, org in enumerate(items, 1):
+        name = org.get("displayName", "Unknown")
+        oid = org.get("id", "")
+        typer.echo(f"  {i}. {name:<30s} ({oid})")
+
+    typer.echo()
+    choice = typer.prompt(f"Select target org [1-{len(items)}]", type=int)
+    if choice < 1 or choice > len(items):
+        typer.echo("Invalid selection.", err=True)
+        raise typer.Exit(1)
+
+    selected = items[choice - 1]
+    save_org(selected.get("id"), selected.get("displayName"))
+    typer.echo(f"\nTarget org set: {selected.get('displayName')} ({selected.get('id')})")
+
+
+@app.command("clear-org")
+def clear_org():
+    """Clear target organization — commands will target your own org."""
+    save_org(None, None)
+    typer.echo("Cleared target org. Commands will now target your own organization.")
+
+
+@app.command("set-cc-region")
+def set_cc_region(
+    region: str = typer.Argument(
+        help="Contact Center region: us1, eu1, eu2, anz1, ca1, jp1, sg1"
+    ),
+):
+    """Set the Contact Center API region for cc-* commands."""
+    from wxcli.config import CC_REGIONS, save_cc_region
+    if region not in CC_REGIONS:
+        typer.echo(f"Error: Unknown region '{region}'. Valid: {', '.join(sorted(CC_REGIONS))}", err=True)
+        raise typer.Exit(1)
+    save_cc_region(region)
+    typer.echo(f"CC region set: {region} ({CC_REGIONS[region]})")
+
+
+# Hand-coded modules. locations.py/numbers.py are no longer registered here —
+# they turned out to be generator-owned on disk (regenerated byte-identical at
+# the 2026-07-01 spec sync). licenses.py was the last hand-written legacy
+# module, retired 2026-07-02 (S3.1) after a live-verified parity check with
+# the generated twin — `licenses` is now generated and manifest-registered.
+from wxcli.commands.update import app as update_app
+from wxcli.commands.configure import app as configure_app
+from wxcli.commands.cucm import app as cucm_app
+
+app.add_typer(update_app, name="update")
+app.add_typer(configure_app, name="configure")
+app.add_typer(cucm_app, name="cucm")
+
+from wxcli.commands.cleanup import app as cleanup_app
+app.add_typer(cleanup_app, name="cleanup")
+
+from wxcli.commands.org_health_cli import app as org_health_app
+app.add_typer(org_health_app, name="org-health")
+
+from wxcli.commands.init_playbook import init as init_command
+app.command(name="init")(init_command)
+
+# Auto-generated groups — registration manifest emitted by tools/generate_commands.py.
+# Explicit registrations above/below this loop are reserved for hand-written
+# seams, aliases, and the guarded dev-only fs_* block.
+from importlib import import_module
+from wxcli.commands._registry import GENERATED_GROUPS
+
+_generated_apps = {}
+for _module, _group in GENERATED_GROUPS:
+    _generated_apps[_group] = import_module(f"wxcli.commands.{_module}").app
+    app.add_typer(_generated_apps[_group], name=_group)
+
+# Hand-written download/export mounted onto the generated converged-recordings group
+from wxcli.commands import converged_recordings_export
+converged_recordings_export.register(_generated_apps["converged-recordings"])
+
+# Aliases
+app.add_typer(_generated_apps["customer-assist"], name="cx-essentials")  # alias: cx-essentials → customer-assist
+app.add_typer(_generated_apps["people"], name="users")  # alias: users → people (replaced hand-coded users.py)
+app.add_typer(_generated_apps["licenses"], name="licenses-api")  # alias for one release: licenses-api → licenses (S3.1, 2026-07-02)
+
+# Dev-only: Flow Store CLI (gitignored, generated from specs/webex-flow-store.json)
+try:
+    from wxcli.commands.fs_flows import app as fs_flows_app
+    app.add_typer(fs_flows_app, name="fs-flows")
+    from wxcli.commands.fs_resources import app as fs_resources_app
+    app.add_typer(fs_resources_app, name="fs-resources")
+    from wxcli.commands.fs_templates import app as fs_templates_app
+    app.add_typer(fs_templates_app, name="fs-templates")
+    from wxcli.commands.fs_tracing import app as fs_tracing_app
+    app.add_typer(fs_tracing_app, name="fs-tracing")
+    from wxcli.commands.fs_flows_v2 import app as fs_flows_v2_app
+    app.add_typer(fs_flows_v2_app, name="fs-flows-v2")
+    from wxcli.commands.fs_user_prefs import app as fs_user_prefs_app
+    app.add_typer(fs_user_prefs_app, name="fs-user-prefs")
+    from wxcli.commands.fs_connectors import app as fs_connectors_app
+    app.add_typer(fs_connectors_app, name="fs-connectors")
+    from wxcli.commands.fs_expression_test import app as fs_expression_test_app
+    app.add_typer(fs_expression_test_app, name="fs-expression-test")
+    from wxcli.commands.fs_flow_props import app as fs_flow_props_app
+    app.add_typer(fs_flow_props_app, name="fs-flow-props")
+    from wxcli.commands.fs_flow_versions import app as fs_flow_versions_app
+    app.add_typer(fs_flow_versions_app, name="fs-flow-versions")
+    from wxcli.commands.fs_projects import app as fs_projects_app
+    app.add_typer(fs_projects_app, name="fs-projects")
+except ImportError:
+    pass

wxcli/migration/CLAUDE.md

@@ -0,0 +1,106 @@
+# migration/ — CUCM→Webex Migration Tool
+
+All 11 phases complete. **2535 tests passing.** Wired into the CLI as `wxcli cucm <command>`. Does NOT use the auto-generator.
+
+## File Map
+
+| Path | Purpose |
+|------|---------|
+| `docs/plans/cucm-migration-roadmap.md` | **Master roadmap** — what's done, what's ready, what's next. Start here. |
+| `docs/plans/cucm-pipeline-architecture.md` | Pipeline architecture summary — SQLite store, two-pass ELT, linter-pattern analyzers, NetworkX DAG |
+| `docs/plans/cucm-pipeline/01-07 + 03b` | 8 detailed architecture docs |
+| `src/wxcli/commands/cucm.py` | Phases 08+10 — CLI: 16 commands (init, discover, normalize, map, analyze, plan, preflight, decisions, decide, export, inventory, status, config, user-diff, user-notice, report) |
+| `src/wxcli/commands/cucm_config.py` | Phase 08 — Config management helpers |
+| `models.py` | Canonical data models — 38 types, DecisionType (27 values), Decision, MapperResult, TransformResult |
+| `store.py` | SQLite-backed store — objects, cross_refs, decisions, journal, merge_log, merge_decisions() |
+| `cucm/` | Phase 03 — AXL connection, 14 extractors, discovery pipeline |
+| `transform/normalizers.py` | Phase 04 — 42 Pass 1 normalizers |
+| `transform/cross_reference.py` | Phase 04 — CrossReferenceBuilder (31 relationships + 3 enrichments) |
+| `transform/pipeline.py` | Phase 04 — `normalize_discovery()` entry point |
+| `transform/mappers/` | Phase 05 — 26 mappers + base.py (announcement, button_template, call_forwarding, call_settings, css, dect, device, device_layout, device_profile, e911, ecbn, executive_assistant, feature, line, location, moh, monitoring, receptionist, routing, snr, softkey, user, voicemail, voicemail_group, workspace, device_settings) |
+| `transform/analyzers/` | Phase 06 — 13 analyzers (css_permission, css_routing, device_compatibility, dn_ambiguity, duplicate_user, extension_conflict, feature_approximation, layout_overflow, location_ambiguity, missing_data, shared_line, voicemail_compatibility, workspace_license) |
+| `transform/analysis_pipeline.py` | Phase 06 — Orchestrator: run analyzers → merge → auto-rules + resolve_and_cascade() |
+| `execute/` | Phase 07 — planner.py, dependency.py (NetworkX DAG), batch.py |
+| `export/` | Phase 09 — deployment_plan.py, json/csv exports (command_builder.py removed in Phase 12b) |
+| `preflight/` | Phase 10 — checks.py (9 preflight checks), runner.py (orchestrator), CLI `wxcli cucm preflight` |
+| `advisory/` | Phase 13 — Advisory system: per-decision recommendations (19 rules) + cross-cutting advisor (30 patterns) |
+| `report/` | Assessment report generator — complexity score, SVG charts, executive summary + appendix → HTML/PDF. See its CLAUDE.md. |
+| `.claude/skills/cucm-migrate/SKILL.md` | Phase 11 — 6-step execution skill: preflight → plan summary → batch execute → delegate → report |
+
+**Where the design spec and pipeline architecture docs conflict, the pipeline architecture docs are authoritative.**
+
+Each subdirectory has its own CLAUDE.md (local context) and TODO.md (outstanding work).
+See `docs/plans/cucm-migration-roadmap.md` for the master project status.
+
+## Known Issues
+
+1. **CUCM CallPickupGroup creation with members fails on CUCM 15.0.** The AXL `addCallPickupGroup` operation with `<members>` containing `<directoryNumber>` fails with a null priority foreign key constraint (`pickupgroupmember.priority`). Workaround: create the pickup group empty, then use `updateLine` with `callPickupGroupName` to assign members at the line level. Affects both wxcadm and raw AXL calls. <!-- Verified on CUCM 15.0.1.13901(2), 2026-03-24 -->
+
+## Pipeline Commands
+
+## Feature Forwarding / Holiday / Night Service Migration
+
+The `FeatureMapper` extracts CUCM hunt pilot forwarding destinations
+(`forwardHuntNoAnswer`, `forwardHuntBusy`) and queue overflow targets
+(`queueCalls.queueFullDestination`, `queueCalls.maxWaitTimeDestination`,
+`queueCalls.noAgentDestination`) onto the canonical hunt group / call queue
+objects, and CTI Route Point `callForwardAll` onto the canonical auto attendant.
+The planner emits 6 tier-5 `configure_*` ops (`hunt_group:configure_forwarding`,
+`call_queue:configure_forwarding`, `call_queue:configure_holiday_service`,
+`call_queue:configure_night_service`, `call_queue:configure_stranded_calls`,
+`auto_attendant:configure_forwarding`) that PUT the new settings via per-feature
+endpoints once the feature has been created. Empty / None data short-circuits
+the planner so unaffected features produce no extra ops. Schedules referenced
+by holiday or night service are resolved by name + level (LOCATION /
+ORGANIZATION) — operating modes and location schedules are already created at
+tier 1, so no additional dependency edges are needed. Spec at
+`docs/superpowers/specs/2026-04-10-feature-forwarding-night-service.md`.
+
+## Hoteling / Hot Desking Migration
+
+The `DeviceProfileMapper` produces execution-ready hoteling data alongside the
+existing `FEATURE_APPROXIMATION` decisions. For each CUCM Extension Mobility
+device profile it sets `hoteling_guest_enabled=True` (when the user is resolved),
+populates `location_canonical_id` (from device_pool → location cross-ref), and
+creates a `hoteling_location:{loc_cid}` MigrationObject for each unique location
+with EM phones. Three new execution handlers (`enable_hoteling_guest`,
+`enable_hoteling_host`, `enable_hotdesking`) configure Webex hoteling guest,
+device host, and location-level voice portal sign-in respectively. Advisory
+pattern 20 (`detect_extension_mobility_usage`) escalates severity to MEDIUM when
+profiles contain multi-line or BLF features that Webex hot desking cannot
+replicate, and `recommend_feature_approximation` always recommends "accept" for
+EM decisions (no alternative architecture exists). Spec at
+`docs/superpowers/specs/2026-04-10-hoteling-migration.md`.
+
+## Voicemail Groups Migration
+
+Unity Connection shared/group mailboxes (department voicemail — sales@, support@,
+billing@ — typically reachable via a hunt pilot) are extracted via a new
+`UnityConnectionClient.extract_shared_mailboxes()` method and normalized into
+`voicemail_group:{name}` MigrationObjects. `VoicemailGroupMapper` (tier 4,
+depends on `location_mapper` + `feature_mapper`) resolves each mailbox's
+location (user extension match first, then single-location fallback;
+multi-location without match → `LOCATION_AMBIGUOUS`),
+generates a placeholder passcode (`MISSING_DATA`), flags custom greetings
+(`AUDIO_ASSET_MANUAL`), and detects extension conflicts (`EXTENSION_CONFLICT`).
+The `handle_voicemail_group_create` handler POSTs to
+`/telephony/config/locations/{id}/voicemailGroups`. Overflow linkage (Phase C):
+the `FeatureMapper` writes `feature_forwards_to_voicemail_group` cross-refs
+when a hunt group/call queue forwarding destination matches a VM group extension,
+and `dependency.py` enforces `voicemail_group:create` before
+`hunt_group:configure_forwarding` / `call_queue:configure_forwarding` /
+`call_queue:configure_stranded_calls`. The forwarding handlers already PUT the
+destination extension — the dependency edge ensures the VM group exists first.
+Spec at `docs/superpowers/specs/2026-04-10-voicemail-groups.md`.
+
+## DECT Migration
+
+CUCM DECT handsets (6823, 6825, 6825ip) are classified as `DeviceCompatibilityTier.DECT` by `DeviceMapper` — they are neither incompatible nor convertible, just require DECT network provisioning. `normalize_dect_group()` (Pass 1) groups DECT handsets by CUCM device pool into `dect_network:` MigrationObjects, each carrying a `handset_assignments` list. `DECTMapper` (Phase 05, depends on `location_mapper`, `device_mapper`, `user_mapper`) resolves each network's location via `device_pool_to_location` cross-refs, auto-selects the Webex model (`DBS-110` for ≤30 handsets, `DBS-210` for >30), enriches handset assignments with owner canonical IDs, and generates `DECT_NETWORK_DESIGN` (missing location, no base station inventory, or multi-zone ambiguity) and `DECT_HANDSET_ASSIGNMENT` (unowned handsets) decisions. Base station MAC addresses are supplied via `--dect-inventory <csv>` on `wxcli cucm discover` (columns: `coverage_zone`, `base_station_mac`, `base_station_model`); without them, `DECT_NETWORK_DESIGN` is raised at MEDIUM severity. The planner expands each `dect_network` into 3 ops: `create` → `create_base_stations` → `assign_handsets`, each with proper dependency edges. Three handlers in `execute/handlers.py` implement these ops: `handle_dect_network_create` (POST `/dectNetworks`), `handle_dect_base_station_create` (POST `/dectNetworks/{id}/baseStations`), `handle_dect_handset_assign` (POST `/dectNetworks/{id}/handsets/bulk`). DECT is not supported for FedRAMP tenants. Spec at `docs/superpowers/specs/2026-04-10-dect-migration.md`.
+
+**To run a migration:** `wxcli cucm init` → `discover` → `normalize` → `map` → `analyze` → `decisions` → `plan` → `preflight` → `export` → then invoke `/cucm-migrate`.
+
+**To generate an assessment report:** `wxcli cucm init` → `discover` (or `discover --from-file`) → `normalize` → `map` → `analyze` → `report --brand "..." --prepared-by "..."`. Does not require plan/preflight/export — the report reads directly from the post-analyze store.
+
+**To generate a per-user diff:** `wxcli cucm init` → `discover` → `normalize` → `map` → `analyze` → `user-diff`. Does not require plan/preflight/export.
+
+**To generate a user communication notice:** `wxcli cucm init` → `discover` → `normalize` → `map` → `analyze` → `user-notice --brand "..." --migration-date "..." --helpdesk "..."`. Does not require plan/preflight/export. Generates an email-ready notice covering detected scenarios.

wxcli/migration/__init__.py

@@ -0,0 +1 @@
+"""CUCM-to-Webex Calling migration tool."""

wxcli/migration/advisory/CLAUDE.md

@@ -0,0 +1,196 @@
+# Migration Advisory System
+
+Practitioner-level architectural advisory for CUCM-to-Webex Calling migrations. Two layers that add judgment to the pipeline's mechanical decision-making.
+
+## Architecture
+
+```
+analysis_pipeline.py run()
+    │
+    ├── Phase 1: 12 existing analyzers → merge decisions into store
+    │
+    ├── Phase 2: ArchitectureAdvisor → reads merged decisions + full inventory
+    │            → produces ARCHITECTURE_ADVISORY decisions → merge (separate stage)
+    │
+    └── Phase 3: populate_recommendations() → enriches ALL decisions with recommendations
+                 │
+                 ▼
+         advisory/
+            ├── recommendation_rules.py  (Layer 1: per-decision)
+            ├── advisory_patterns.py     (Layer 2: cross-cutting)
+            └── advisor.py               (ArchitectureAdvisor class)
+```
+
+**Layer 1 — Per-Decision Recommendations.** Every decision the pipeline produces (from mappers and analyzers) gets an optional `recommendation` field: which option the system advises, and `recommendation_reasoning`: why. Populated by `populate_recommendations()` which calls into `recommendation_rules.py`. One function per DecisionType (16 total). Returns `(option_id, reasoning)` or `None` for genuinely ambiguous cases.
+
+**Layer 2 — Cross-Cutting Advisor.** The `ArchitectureAdvisor` runs after all 13 analyzers have merged their decisions. It reads the full canonical model plus all prior decisions and produces `ARCHITECTURE_ADVISORY` decisions for patterns spanning multiple objects — things like "6 of your 14 CSSes are restriction-only and should be calling permissions, not dial plans" or "your trunk topology indicates Local Gateway, not Cloud Connected PSTN." 33 pattern detector functions total.
+
+## Why Two Phases
+
+The ArchitectureAdvisor needs to read decisions from the first 13 analyzers (e.g., Pattern 4 groups DEVICE_INCOMPATIBLE decisions by model for bulk upgrade planning). In a single-phase design, analyzer decisions aren't in the store until after ALL analyzers run — so the ArchitectureAdvisor would see nothing. The two-phase approach merges Phase 1 decisions first, then runs Phase 2 against the populated store.
+
+Advisory decisions are merged separately using `decision_types=[ARCHITECTURE_ADVISORY]` and `stage="advisory"` so they don't stale-mark the Phase 1 decisions.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `__init__.py` | Exports `populate_recommendations()` and `ArchitectureAdvisor` |
+| `recommendation_rules.py` | 21 recommendation functions (one per DecisionType) + `RECOMMENDATION_DISPATCH` dict |
+| `advisory_patterns.py` | 34 cross-cutting pattern detectors + `AdvisoryFinding` dataclass + `ALL_ADVISORY_PATTERNS` list |
+| `advisor.py` | `ArchitectureAdvisor` class (extends Analyzer ABC) |
+
+## Decision Model Fields
+
+Two fields added to `Decision` in `models.py`:
+- `recommendation: str | None` — the `id` of the recommended option (e.g., `"call_queue"`, `"convert"`)
+- `recommendation_reasoning: str | None` — 1-3 sentences explaining why
+
+Both are display-only — NOT part of the fingerprint. They can change across runs without invalidating resolved decisions. Stored in the `decisions` table as nullable TEXT columns.
+
+One enum value added: `DecisionType.ARCHITECTURE_ADVISORY`
+
+## Per-Decision Recommendations (Layer 1)
+
+`recommendation_rules.py` has one function per DecisionType:
+
+```python
+def recommend_{type_name}(context: dict, options: list[dict]) -> tuple[str, str] | None:
+```
+
+The `RECOMMENDATION_DISPATCH` dict maps type strings to functions. `populate_recommendations()` iterates all decisions in the store, calls the dispatch function, and writes results via `store.update_recommendation()`.
+
+**Key rules by type:**
+- `FEATURE_APPROXIMATION`: Queue features enabled → Call Queue. >8 agents → Call Queue. ≤4 agents top-down → Hunt Group. 5-8 ambiguous → None.
+- `DEVICE_INCOMPATIBLE`: Model-to-replacement lookup (7811→9841, 7832→room device, ATA 190→ATA 192). Includes firmware type (MPP vs RoomOS) in reasoning.
+- `CSS_ROUTING_MISMATCH`: Partition ordering dependency → "manual" with explanation. Scope difference → "use_union" unless it creates conflicts.
+- `MISSING_DATA`: Almost always "skip" with remediation guidance. Trunk password → "generate".
+
+Ambiguous cases return `None`. Honest uncertainty is a feature.
+
+## Cross-Cutting Advisory Patterns (Layer 2)
+
+`advisory_patterns.py` has 33 pattern detector functions. Each takes a `MigrationStore` and returns `list[AdvisoryFinding]`.
+
+**Critical patterns (highest migration impact):**
+1. **Partition Ordering Loss** — CSSes that depend on partition ordering to resolve overlapping patterns. Webex uses longest-match routing — no ordering equivalent. Calls may route differently after migration.
+2. **CPN Transformation Chain** — Route patterns and trunks with calling/called party transformations. CUCM chains transformations across 5 levels. Webex has flat caller ID per user/location.
+3. **PSTN Connection Type** — Classifies trunk topology into Local Gateway, Cloud Connected PSTN, or Premises-based PSTN. Drives the entire Webex routing architecture.
+
+**Eliminate patterns (CUCM workarounds to remove):**
+4. Restriction CSS Consolidation — CSSes with only blocking patterns → calling permission policies
+5. Translation Pattern Elimination — Digit normalization handled natively by Webex location settings
+6. Partition-Based Time Routing — Time schedule→partition→CSS chain → AA business hours schedule
+7. Over-Engineered Dial Plan — Patterns matching Webex's built-in extension routing
+8. Voicemail Pilot Simplification — Multiple pilots to same VM system → Webex location-level voicemail
+
+**Rebuild patterns (use Webex-native approach):**
+9. Hunt Pilot Behavioral Reclassification — HGs with queue-like behavior → Call Queues
+10. Location Consolidation — Multiple device pools same tz+region → fewer Webex locations
+11. Shared Line Simplification — Monitoring-only appearances → virtual extensions
+12. Trunk Destination Consolidation — Multiple trunks same destination → single Webex trunk
+
+**Informational / out-of-scope:**
+13. Device Bulk Upgrade Planning — Groups incompatible devices by model with replacement options
+14. Globalized vs. Localized Dial Plan — Detects dial plan style to guide migration approach
+15. Media Resource Scope Removal — MRGLs, conference bridges, transcoders → cloud-managed, skip
+16. E911/CER Migration Flag — Emergency services require separate workstream
+
+**Tier 4 feature gap patterns:**
+17. Recording Enabled Users — phones with recordingFlag enabled → configure Webex recording
+18. SNR Configured Users — remote destination profiles → manual Webex SNR setup
+19. Transformation Patterns — calling/called party transformations → manual caller ID review
+20. Extension Mobility Usage — device profiles → Webex hot desking configuration
+21. Call Intercept Candidates — heuristically detected blocked partitions + CFA-to-voicemail → manual Webex intercept setup
+22. Selective Call Handling Opportunities — CSS/partition patterns suggesting per-caller routing → Webex Selective Forward / Accept / Reject (admin) or Priority Alert (user-only)
+
+**Gap patterns (silent failures / platform limits):**
+23. Mixed CSS — CSSes mixing routing and restriction partitions (silent gap in Pattern 1)
+24. Cumulative Virtual Line Consumption — count VLs recommended across all decisions, warn if approaching limits
+25. User OAuth Required — features that require per-user OAuth (admin tokens can't set them)
+26. Trunk Type Selection — trunk type (REGISTERING vs CERTIFICATE_BASED) is immutable post-creation
+27. Intercluster Trunks — CUCM ICT disposition decision (no Webex equivalent)
+28. Legacy Gateway Protocols — MGCP and H.323 gateways need SIP conversion before migration
+
+**User communication:**
+29. Voicemail Greeting Re-Recording — counts users with custom greetings, produces user communication template
+
+**Audio migration:**
+30. Custom Audio Assets — custom MoH sources + announcements requiring manual download/upload
+
+**Feature migration gaps:**
+31. DECT Deployment — DECT networks present without base station inventory → operator must supply MAC CSV
+32. Feature Forwarding Gaps — hunt groups / call queues / AAs with CUCM forwarding destinations that aren't mapped to Webex forwarding fields (MEDIUM/rebuild)
+33. Workspace Call Settings Gaps — workspaces with empty call_settings but CUCM device had custom caller ID, forwarding, or DND config (LOW/migrate_as_is)
+
+## AdvisoryFinding Dataclass
+
+```python
+@dataclass
+class AdvisoryFinding:
+    pattern_name: str           # "restriction_css_consolidation"
+    severity: str               # "CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"
+    summary: str                # One-liner for decision summary
+    detail: str                 # 2-5 sentences of reasoning
+    affected_objects: list[str] # canonical_ids
+    recommendation: str         # Always "accept" for advisories
+    recommendation_reasoning: str
+    category: str               # "migrate_as_is" | "rebuild" | "eliminate" | "out_of_scope"
+```
+
+The `category` field classifies advisories into the migration decision framework: migrate as-is, rebuild using Webex-native patterns, eliminate (CUCM workaround), or out-of-scope (separate workstream).
+
+## Implementation Notes
+
+**Pattern 1 uses `blockEnable`, not `classify_block_pattern()`.** The spec says to use `classify_block_pattern()` from `cucm_pattern.py`, but that function requires a `category_rules` list from the migration config. Using `pre_migration_state.blockEnable` is more direct and robust — it detects blocking patterns without config dependency. Code review approved this deviation.
+
+**Pattern 9 groups by voicemail system before firing.** Uses the first 3 digits of pilot number + CSS name as a grouping key. Only fires when all pilots share the same key (i.e., point to the same VM system). Prevents false positives on deployments with genuinely independent voicemail systems.
+
+**Pattern 11 `affected_objects` includes CSS + partition + route pattern IDs.** Not just CSS IDs — the partitions and route patterns involved in ordering conflicts are also tracked for traceability.
+
+**Pattern 16 (E911) always fires**, even on empty stores. When no E911 signals are detected, it produces a warning that CER data may not be visible via AXL. This is by design per the spec's "if detection data is sparse" guidance. Pattern 16 now includes quantified ECBN readiness counts (DIRECT_LINE / LOCATION_ECBN / ambiguous / mismatch).
+
+**Test count:** 87 tests (35 pattern + 7 advisor + 45 new-pattern/rule tests). The prompt estimated ~50; the actual count is lower because some patterns share positive/negative cases and the simpler patterns need fewer test scenarios. Pattern 27 (voicemail greeting re-recording) added 6 tests.
+
+## Pipeline Integration (Phase 13d — COMPLETE)
+
+In `analysis_pipeline.py`, the `run()` method has steps 5-6 after the original 4:
+1. Run 12 existing analyzers (unchanged)
+2. Convert to store dicts and merge (unchanged)
+3. Apply auto-rules (unchanged)
+4. Apply auto-resolution rules (unchanged)
+5. Run ArchitectureAdvisor → merge advisory decisions separately (`decision_types=[ARCHITECTURE_ADVISORY]`, `stage="advisory"`)
+6. `populate_recommendations()` → enrich all decisions
+
+Advisory decisions do NOT trigger cascades. Resolving an advisory does not re-run any analyzer. Stats dict includes `architecture_advisor` key.
+
+## CLI Integration (Phase 13d — COMPLETE)
+
+- `wxcli cucm decisions` shows `[REC: option]` tag on decisions with recommendations (in a Recommendations section below the table)
+- `wxcli cucm decisions --type advisory` filters to ARCHITECTURE_ADVISORY only (shorthand mapping)
+- JSON export includes `recommendation` and `recommendation_reasoning` fields
+
+## Skill Integration (Phase 13d — COMPLETE)
+
+The `cucm-migrate` skill's decision review has two phases:
+- **Phase A:** Present advisories grouped by category (eliminate, rebuild, out_of_scope, migrate_as_is) with bulk accept
+- **Phase B:** Present per-decision items as auto_apply, recommended (with bulk accept and reasoning), or needs_input
+
+## Adding New Patterns
+
+To add a new advisory pattern:
+1. Write a function `detect_{name}(store: MigrationStore) -> list[AdvisoryFinding]` in `advisory_patterns.py`
+2. Register it in `ALL_ADVISORY_PATTERNS`
+3. Add tests in `tests/migration/advisory/test_advisory_patterns.py`
+
+To add a new recommendation rule:
+1. Add logic to the existing function for that DecisionType in `recommendation_rules.py`
+2. Add tests in `tests/migration/advisory/test_recommendation_rules.py`
+
+No framework changes needed for either. The knowledge base grows by adding functions.
+
+## Design Spec
+
+Full design: `docs/superpowers/specs/2026-03-24-migration-advisory-design.md`
+
+Build prompts: `docs/prompts/phase-13a` through `phase-13d`

wxcli/migration/advisory/__init__.py

@@ -0,0 +1,46 @@
+"""Migration advisory system — practitioner-level recommendations.
+
+Layer 1 (recommendation_rules): per-decision recommendations
+Layer 2 (advisory_patterns + advisor): cross-cutting observations
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.advisory.advisor import ArchitectureAdvisor
+from wxcli.migration.advisory.recommendation_rules import RECOMMENDATION_DISPATCH
+from wxcli.migration.store import MigrationStore
+
+logger = logging.getLogger(__name__)
+
+
+def populate_recommendations(store: MigrationStore) -> int:
+    """Enrich all decisions in the store with recommendations.
+
+    Iterates all decisions, calls the recommendation function for each type,
+    and writes results via store.update_recommendation().
+
+    Returns count of recommendations added.
+    """
+    all_decisions = store.get_all_decisions()
+    count = 0
+    for dec in all_decisions:
+        if dec.get("chosen_option") == "__stale__":
+            continue
+        dec_type = dec.get("type", "")
+        fn = RECOMMENDATION_DISPATCH.get(dec_type)
+        if fn is None:
+            continue
+        context = dec.get("context", {})
+        options = dec.get("options", [])
+        try:
+            result = fn(context, options)
+        except Exception as exc:
+            logger.warning("Recommendation %s failed: %s", fn.__name__, exc)
+            continue
+        if result is not None:
+            option_id, reasoning = result
+            store.update_recommendation(dec["decision_id"], option_id, reasoning)
+            count += 1
+    return count