pan-wizard 3.35.0 → 3.37.0

package/docs/specs/git_integration_overhaul_featureai.md

@@ -0,0 +1,326 @@
+# featureAI Spec: Git Integration Overhaul for PAN Wizard
+
+**Date:** 2026-03-07
+**Status:** Proposed
+**Scope:** Focus system, build system, phase lifecycle, and commit infrastructure
+
+---
+
+## Phase 0: Problem Framing & Demand Validation
+
+### 0.1 Problem Statement
+PAN Wizard's git integration is a facade — the reference docs (`git-integration.md`, `git-planning-commit.md`) describe a comprehensive per-task commit strategy, rollback snapshots, and git-aware lifecycle gates, but the code implements almost none of it. Focus-exec runs batches without checking git state. Phase completion doesn't create commits. The auto-runner accumulates cycles of uncommitted changes. The result: users' git history is a mess of manual afterthought commits instead of the clean, bisectable, per-task changelog PAN promises.
+
+### 0.2 Demand Evidence
+
+| Evidence Type | Source | Finding |
+|--------------|--------|---------|
+| Internal audit (session 29) | Codebase analysis | 10 critical gaps: focus-exec ignores git, phase-complete doesn't commit, auto-runner has no git interaction, panmonty git gates are procedural-only |
+| Competitor gap | Aider (gold standard) | Auto-commits per change + `/undo` = clean reversible history. PAN has neither. |
+| Competitor gap | Copilot Workspace | Issue -> Plan -> Implement -> Validate -> PR flow. PAN's focus-exec does Plan -> Execute with no git bookends. |
+| Architecture debt | git-integration.md vs code | Doc says "Task completed = YES commit" (line 20). Code: `cmdPhaseComplete()` never calls `cmdCommit()`. |
+
+### 0.3 Success Criteria
+
+```
+SC-1: focus-exec checks git cleanliness before processing any batch item
+SC-2: Phase completion creates an atomic commit with conventional message
+SC-3: focus-auto creates checkpoint commits between cycles
+SC-4: /commit skill handles all 7 scenarios (quick, selective, phase, amend, planning, wip, dry-run)
+SC-5: execGit returns explicit 'not_a_git_repo' when .git doesn't exist
+SC-6: No regression in 1557+ existing tests
+SC-7: Works identically on Windows, Mac, Linux (CI matrix: 3 OS x 3 Node)
+```
+
+---
+
+## Phase 1: Internal Reconnaissance — Current State
+
+### What Works (keep)
+| Capability | Location | Status |
+|-----------|----------|--------|
+| `execGit(cwd, args)` | core.cjs:217-232 | Solid — safe `execFileSync`, structured return |
+| `isGitIgnored(cwd, path)` | core.cjs:199-209 | Works |
+| `runCommitSafetyChecks()` | commands.cjs:318-356 | Good — deleted files, sensitive patterns |
+| `cmdCommit()` | commands.cjs:358-409 | Works for `.planning/` commits |
+| `cmdRollbackSnapshot()` | commands.cjs:851-886 | Works — tag-based rollback points |
+| `cmdPreflight()` git_clean check | verify.cjs:1038-1050 | Works — counts uncommitted changes |
+| `cmdVerifyCommits()` | verify.cjs:52-70 | Works — batch hash verification |
+
+### What's Missing (the 10 gaps)
+
+| Gap | Severity | Where It Should Be |
+|-----|----------|-------------------|
+| **G1: Focus-exec doesn't verify git cleanliness** | HIGH | `focus.cjs:cmdFocusExec()` |
+| **G2: No git init for new projects** | MEDIUM | `init.cjs:cmdInitNewProject()` |
+| **G3: Panmonty git checks are doc-only** | HIGH | No code enforces panmonty_protocol.md gates |
+| **G4: Phase completion doesn't commit** | HIGH | `phase.cjs:cmdPhaseComplete()` |
+| **G5: No push automation** | LOW | By design — keep manual |
+| **G6: Focus-auto has no git interaction** | HIGH | `focus.cjs:focusAutoUpdate/Continue` |
+| **G7: Preflight exists but exec doesn't call it** | HIGH | `focus.cjs:cmdFocusExec()` |
+| **G8: No 'not_a_git_repo' explicit error** | MEDIUM | `commands.cjs:cmdCommit()` |
+| **G9: No batch commit helper** | MEDIUM | Missing from `commands.cjs` |
+| **G10: Milestone operations don't commit** | MEDIUM | `milestone.cjs:cmdMilestoneComplete()` |
+
+---
+
+## Phase 2: Competitive Intelligence Summary
+
+### Gold Standards to Learn From
+
+**Aider (per-change commits):**
+- Auto-commit after every AI edit — git history = changelog
+- `/undo` reverses last commit (`git reset`)
+- `--dirty-commits` separates user changes from AI changes
+- `--test-cmd` runs tests before committing, auto-fixes failures
+
+**Copilot Workspace (workflow integration):**
+- Issue -> Spec -> Plan -> Implement -> Validate -> PR
+- Auto-branching per task, auto-linked PRs
+- Cloud-based validation step before commit
+
+### What PAN Should NOT Copy
+- Auto-commit on every file change (too noisy for PAN's batch model)
+- Auto-branching (PAN users work on single branch, feature branches are user choice)
+- Cloud validation (PAN is zero-dep, local-only)
+
+### What PAN Should CREATE (Blue Ocean)
+- **Batch-aware commits**: One commit per focus-exec item, with phase-scoped messages
+- **Lifecycle git gates**: Preflight before execution, commit after completion, tag at milestones
+- **WIP checkpoints**: Auto-runner creates `wip:` commits between cycles
+- **Commit-or-warn paradigm**: Never silently accumulate uncommitted work
+
+---
+
+## Phase 3: Strategic Design
+
+### Architecture: Git Integration Layers
+
+```
+Layer 4: Skills (.claude/commands/commit.md)        ← User-facing, AI-interpreted
+Layer 3: Orchestrators (focus-exec, panmonty, etc.) ← Call Layer 2 at lifecycle points
+Layer 2: Commands (cmdCommit, cmdRollbackSnapshot)   ← High-level git operations
+Layer 1: Primitives (execGit, isGitIgnored)          ← Safe git execution
+```
+
+**Principle: Git logic lives in Layer 2-3, never Layer 4 alone.** The current commit.md (Layer 4) describes git checks that should be ENFORCED in code (Layer 2-3), not just suggested to an AI.
+
+### Implementation Plan: 8 Work Items
+
+---
+
+### Item 1: `isGitRepo(cwd)` helper + explicit error in cmdCommit
+**Size:** XS (1 pt) | **Priority:** P1 | **Track:** stability
+**Files:** `core.cjs`, `commands.cjs`
+
+Add to `core.cjs`:
+```javascript
+function isGitRepo(cwd) {
+  const result = execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+  return result.exitCode === 0;
+}
+```
+
+Update `cmdCommit()` to return `{ committed: false, reason: 'not_a_git_repo' }` explicitly when `isGitRepo()` returns false. Currently it returns a vague `commit_failed`.
+
+Export `isGitRepo` for use by other modules.
+
+**Tests:** 3 unit (isGitRepo true/false/non-dir), 2 integration (cmdCommit in non-git dir)
+
+---
+
+### Item 2: Git cleanliness gate in focus-exec
+**Size:** S (3 pts) | **Priority:** P1 | **Track:** stability
+**Files:** `focus.cjs`
+
+Before `cmdFocusExec()` processes any batch item, check:
+```javascript
+const { execGit } = require('./core.cjs');
+const status = execGit(cwd, ['status', '--porcelain']);
+if (status.exitCode === 0 && status.stdout) {
+  // Dirty working tree
+  return output({ error: 'dirty_working_tree', uncommitted_count: status.stdout.split('\n').filter(Boolean).length, hint: 'Commit or stash changes before running focus-exec' }, raw, 'blocked');
+}
+```
+
+Add `--force` flag to bypass (for users who know what they're doing).
+
+**Tests:** 4 unit (clean/dirty/non-git/force-override), 2 integration
+
+---
+
+### Item 3: Phase completion auto-commit
+**Size:** S (3 pts) | **Priority:** P1 | **Track:** feature
+**Files:** `phase.cjs`, `commands.cjs`
+
+When `cmdPhaseComplete()` succeeds (roadmap + state updated), call `cmdCommit()` internally:
+```javascript
+// After roadmap/state updates succeed:
+const commitMsg = `docs(${phaseId}): complete phase — ${phaseName}`;
+cmdCommit(cwd, commitMsg, [PLANNING_DIR + '/'], false, false, { type: 'docs' });
+```
+
+This only commits `.planning/` files (metadata). Code commits are the user's responsibility during task execution.
+
+Add `--no-commit` flag to skip if user doesn't want auto-commit.
+
+**Tests:** 3 unit (commit created, no-commit flag, non-git graceful), 2 integration
+
+---
+
+### Item 4: Milestone completion auto-commit + tag
+**Size:** S (2 pts) | **Priority:** P2 | **Track:** feature
+**Files:** `milestone.cjs`, `commands.cjs`
+
+When `cmdMilestoneComplete()` succeeds:
+1. Commit `.planning/` with `docs: milestone vX.Y complete`
+2. Create tag: `milestone-vX.Y`
+
+**Tests:** 3 unit, 1 integration
+
+---
+
+### Item 5: Focus-auto cycle checkpoint commits
+**Size:** M (5 pts) | **Priority:** P2 | **Track:** feature
+**Files:** `focus.cjs`
+
+After each auto-runner cycle completes (`focusAutoUpdate`):
+1. Check if there are uncommitted `.planning/` changes
+2. If yes, create: `docs: focus-auto cycle N — processed M items`
+3. Update auto-run.json with last_commit_hash
+
+This prevents multi-cycle runs from accumulating unbounded uncommitted metadata.
+
+Add config option `focus.auto_commit: true|false` (default: true).
+
+**Tests:** 4 unit (commit-per-cycle, no-change skip, config disable, non-git), 2 integration
+
+---
+
+### Item 6: Batch commit helper for focus-exec results
+**Size:** S (3 pts) | **Priority:** P2 | **Track:** feature
+**Files:** `commands.cjs`
+
+New function `cmdBatchCommit(cwd, items, raw)`:
+- Takes array of completed batch items
+- Creates single commit: `docs: focus-exec batch — N items completed`
+- Body lists item titles
+- Only commits `.planning/` metadata, not code
+
+This is called by orchestrators (focus-exec, execplan) after processing a batch, not by users directly.
+
+**Tests:** 3 unit, 2 integration
+
+---
+
+### Item 7: `git init` in new project initialization
+**Size:** XS (1 pt) | **Priority:** P3 | **Track:** stability
+**Files:** `init.cjs`
+
+In `cmdInitNewProject()`, after creating `.planning/` structure:
+```javascript
+if (!isGitRepo(cwd)) {
+  execGit(cwd, ['init']);
+  // Don't fail if git init fails — it's a convenience, not a requirement
+}
+```
+
+Match what `git-integration.md` line 32 promises: "PAN projects always get their own repo."
+
+**Tests:** 2 unit (init creates repo, existing repo untouched)
+
+---
+
+### Item 8: Build/check skills git status integration
+**Size:** XS (1 pt) | **Priority:** P3 | **Track:** quality
+**Files:** `.claude/commands/check.md`, `.claude/commands/build.md`
+
+Update `/check` to include git status in health report:
+```
+Git: main (clean) | 3 ahead, 0 behind
+```
+
+Update `/build` to warn if building with uncommitted changes.
+
+These are skill-level changes only (Layer 4) — no code changes needed.
+
+**Tests:** None (skill files, not code)
+
+---
+
+## Implementation Order & Dependencies
+
+```
+Item 1: isGitRepo helper (no deps)
+  ├─→ Item 2: focus-exec git gate (needs isGitRepo)
+  ├─→ Item 3: phase-complete auto-commit (needs isGitRepo)
+  ├─→ Item 4: milestone-complete auto-commit (needs isGitRepo)
+  └─→ Item 7: git init in new project (needs isGitRepo)
+
+Item 6: batch commit helper (no deps)
+  └─→ Item 5: focus-auto cycle commits (needs batch commit)
+
+Item 8: skill updates (no deps, no code)
+```
+
+**Wave 1 (P1, parallel):** Items 1 + 6 + 8
+**Wave 2 (P1, needs Wave 1):** Items 2 + 3
+**Wave 3 (P2):** Items 4 + 5
+**Wave 4 (P3):** Item 7
+
+### Effort Summary
+| Wave | Items | Points | Tests |
+|------|-------|--------|-------|
+| 1 | 1, 6, 8 | 4 pts | 10 |
+| 2 | 2, 3 | 6 pts | 11 |
+| 3 | 4, 5 | 7 pts | 10 |
+| 4 | 7 | 1 pt | 2 |
+| **Total** | **8 items** | **18 pts** | **33 tests** |
+
+---
+
+## Risk Register
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| Auto-commits annoy users | Medium | Medium | All auto-commits have `--no-commit` bypass + config toggle |
+| Non-git repos break | Low | High | `isGitRepo()` gate on every git path; graceful fallback |
+| Focus-exec git gate blocks CI | Low | Medium | `--force` flag bypasses; CI can set config |
+| Phase-complete commit fails (disk) | Low | Medium | try-catch, surface warning, don't fail the phase completion |
+| Windows path issues in git add | Low | Medium | Already using `execFileSync('git', args)` — no shell interpolation |
+
+---
+
+## What This Does NOT Include (Intentionally)
+
+- **Auto-branching / PR creation** — Out of scope. PAN is branch-agnostic by design.
+- **Push automation** — Intentionally manual. Too dangerous to automate.
+- **Merge conflict resolution** — No AI tool does this well. Leave to user.
+- **Undo/rollback command** — `cmdRollbackSnapshot()` already exists. Could be enhanced later.
+- **Per-task commits during execution** — This is the EXECUTOR agent's responsibility, not infrastructure. The reference doc (`git-integration.md`) guides the agent.
+
+---
+
+## ADR: Git Lifecycle Gates in PAN Wizard
+
+### Status
+Proposed
+
+### Context
+PAN Wizard's documentation describes comprehensive git integration (per-task commits, git cleanliness gates, rollback snapshots), but the code only implements the primitives (`execGit`, `cmdCommit`). Orchestrators (focus-exec, auto-runner, phase lifecycle) have zero git awareness. This creates a gap where users follow PAN's workflow but end up with messy git history because the system never enforces its own git strategy.
+
+### Decision
+Add git lifecycle gates at orchestrator boundaries (before/after focus-exec, on phase/milestone completion, between auto-runner cycles). Keep gates soft (bypassable with flags/config) but default to enforcing clean git discipline.
+
+### Consequences
+**Positive:**
+- Git history reflects PAN's per-task commit philosophy automatically
+- Focus-exec won't silently accumulate uncommitted work
+- Phase/milestone completions are tracked in git, not just STATE.md
+
+**Negative:**
+- Users with non-git workflows will see warnings (mitigated by `--force` + config)
+- Slight overhead on each orchestrator call (one `git status` check)
+
+**Neutral:**
+- Existing `cmdCommit()` API unchanged — new callers added, not new API

package/docs/specs/glm_zai_provider_featureai.md

@@ -0,0 +1,200 @@
+# /featureAI — GLM (z.ai) Provider Support & ZCode Interop
+
+**Status:** Proposed — not implemented; ZCode Surface B superseded by [`docs/specs/pan_zcode_mcp_bridge_featureai.md`](pan_zcode_mcp_bridge_featureai.md) / ADR-0041.
+**Source:** User request — "make PAN work with ZCode / GLM."
+**Lineage:** Concrete, shippable instance of [`multi_model_routing_featureai.md`](multi_model_routing_featureai.md) (that spec anticipated non-Anthropic providers; this one lands the first real one). Reuses the existing `PROVIDER_MODELS` / `detectProvider` / `resolveTierToModel` seam.
+
+> GLM = Zhipu AI's model family, sold internationally as **z.ai**. The **GLM Coding Plan** is a flat-fee subscription exposing an **Anthropic-compatible** endpoint (`https://api.z.ai/api/anthropic`). GLM-5.2 (16 Jun 2026, MIT-licensed, 1M ctx) benches ~between Opus 4.7 and 4.8 on agentic coding. **ZCode** is z.ai's *own* coding-agent harness (a Claude-Code peer) built on GLM-5.2.
+
+---
+
+## Phase 0: Problem Framing
+
+### 0.1 Problem Statement
+
+PAN's bot army is powerful but, in practice, Anthropic-priced. Users on z.ai's flat-fee GLM Coding Plan (a fraction of Claude Code Pro, ~parity on coding benchmarks) currently get PAN *accidentally* working under Claude Code — because Claude Code itself remaps `opus/sonnet/haiku` → GLM via `ANTHROPIC_DEFAULT_*_MODEL` env vars, and PAN already emits those tier tokens rather than hardcoded IDs. But that "accidental" path is unmanaged: PAN believes it's on Anthropic, the installer **false-warns** that the model lacks 1M-context/thinking, the cost ledger fabricates per-token dollars against a flat-fee plan, and there is **zero** provisioning help (the user hand-edits `settings.json`). PAN should make GLM a *first-class, provisioned, honestly-labelled* backend across the runtimes that actually support it — and give an honest answer on ZCode.
+
+### 0.2 Scope
+
+| In Scope | Out of Scope |
+|----------|--------------|
+| GLM/z.ai as a recognized **backend** + `zhipu` tier-provider | PAN making direct API calls to z.ai (PAN always delegates to the host CLI) |
+| Provisioning z.ai config into **Claude Code** (`.claude/settings.json` env) and **OpenCode** (`opencode.json` provider) | Persisting the z.ai **API token** in any committed file (security — token stays in shell env / gitignored local settings) |
+| `detectProvider` recognizing GLM (config / `PAN_PROVIDER` / `ANTHROPIC_BASE_URL`) | A generic "any OpenAI/Anthropic-compatible endpoint" wizard (GLM is the concrete target; generic BYO-endpoint is a follow-up) |
+| GLM branch in `detectModelCapabilities` (stop the false 1M-ctx/thinking warning) | Benchmarking or auto-selecting GLM vs Claude per task |
+| Cost honesty for flat-fee plans (no fabricated `$`) | Token/quota metering of the z.ai subscription |
+| `/pan:provider` command + `pan-tools provider` verb | Codex / Gemini / Copilot GLM paths (not z.ai-blessed targets — see matrix) |
+| **ZCode**: honest feasibility verdict + a *partial* `~/.zcode/agents/` agent-pack path | ZCode as a full 6th runtime (blocked — ZCode has no custom slash-commands / project config / hooks today) |
+
+### 0.3 Success Criteria (Measurable)
+
+```
+SC-1: `routing.provider: "zhipu"` (aliases glm/zai) resolves — no silent downgrade to 'default'.
+SC-2: PROVIDER_MODELS gains a `zhipu` entry; resolveTierToModel('mid','zhipu') → a GLM id; reasoning stays 'inherit'.
+SC-3: detectProvider recognizes GLM via (a) config.routing.provider, (b) PAN_PROVIDER=glm, (c) ANTHROPIC_BASE_URL containing an allowlisted z.ai host.
+SC-4: detectModelCapabilities('glm-5.2' / 'GLM-4.7' / 'glm-4.5-air') returns has_1m_ctx/has_thinking correctly; the installer E-9 warning no longer fires for GLM.
+SC-5: `pan-tools provider set glm` provisions Claude Code (.claude/settings.json env block: ANTHROPIC_BASE_URL, ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL, API_TIMEOUT_MS) — and NEVER writes the auth token to a tracked file.
+SC-6: `pan-tools provider set glm` provisions OpenCode (opencode.json custom @ai-sdk/anthropic provider, baseURL …/anthropic/v1, GLM models).
+SC-7: `pan-tools provider show` reports the active backend + effective tier→model mapping; `provider clear` reverts.
+SC-8: Cost surfaces (cost.cjs / hud / report) show tokens + a "flat-fee plan" note instead of a fabricated $0.00 when backend=zai.
+SC-9: Running `pan-tools provider set glm` for Codex/Gemini/Copilot prints a clear "not a supported z.ai target" message and makes no changes.
+SC-10: Unit + scenario tests cover provider resolution, capability branch, provisioning (both runtimes), secret-safety, and the unsupported-runtime guard (≥10 cases, incl. 2 runtime-specific + 2 error).
+SC-11: No regression; existing behavior identical when no GLM backend is configured (default path untouched).
+```
+
+### 0.4 User Stories
+
+```
+US-1: As a GLM Coding Plan subscriber, I want `pan-tools provider set glm` to wire up
+      Claude Code for me, so the whole PAN bot army runs on GLM at flat-fee cost,
+      instead of hand-editing settings.json and guessing the env var names.
+
+US-2: As an OpenCode user, I want PAN to register z.ai as a custom provider and emit
+      real glm-* model ids, so my agents actually route to GLM,
+      instead of OpenCode choking on the bare tier token "sonnet".
+
+US-3: As any GLM user, I want PAN to stop telling me my model "lacks 1M context and
+      extended thinking" and stop inventing a $0.00 spend, so the HUD/report tell the
+      truth about a flat-fee GLM plan.
+
+US-4: As a ZCode user, I want an honest answer on whether PAN runs inside ZCode today,
+      and the closest thing that does work, instead of a half-broken install.
+```
+
+---
+
+## Phase 1: Internal Reconnaissance (findings)
+
+PAN already has the *exact* abstraction this needs; it just has no notion of a custom **endpoint/backend**.
+
+| Seam | Location | Today | GLM change |
+|------|----------|-------|-----------|
+| Tier→ID map | `core.cjs:35-40` `PROVIDER_MODELS` | `anthropic/openai/google/default` | **add `zhipu`** `{ reasoning:'inherit', mid:'glm-4.6', fast:'glm-4.5-air' }` |
+| Legacy aliases | `core.cjs:43` `LEGACY_ALIASES` | opus/sonnet/haiku → reasoning/mid/fast | unchanged (GLM inherits the same tiers) |
+| Provider detect | `core.cjs:714-735` `detectProvider` | config → `PAN_PROVIDER` → runtime-dir | **add** glm/zai alias acceptance + `ANTHROPIC_BASE_URL` z.ai sniff |
+| Tier resolve | `core.cjs:743-747` `resolveTierToModel` | unknown provider → default; unknown tier → mid | unchanged (graceful; no allowlist to fight) |
+| Agent model decl | `agents/*.md` frontmatter | tier alias only (`model: opus` on 3 security agents); **never full IDs** | unchanged — this is *why* GLM already flows under Claude Code |
+| Installer model writes | `install.js:2337-2451` | **never writes model/provider/endpoint**; only *reads* `.claude` `model` for E-9 warn (`install.js:2477-2501`) | **new**: opt-in provider provisioning path |
+| Capability classifier | `install-lib.cjs:1013-1071` `detectModelCapabilities` | no GLM branch → GLM falls to `unknown` (all caps false) → false warning | **add GLM branch** |
+| Config defaults | `config.cjs:42-95` `buildConfigDefaults` | emits `routing{strategy,provider:'auto',…}`; **not** in `templates/config.json` | add optional `routing.backend`; (note the template/loader divergence) |
+| Cost | `cost.cjs` per-token pricing + `ledgerReliability()` honesty | prices by model id; GLM unpriced | **flat-fee mode** when backend=zai (reuse honesty pattern) |
+| Model catalog | — | **none** — no allowlist anywhere | nothing to gate; only `PROVIDER_MODELS` + `detectModelCapabilities` enumerate identity |
+
+**Decisive fact:** PAN emits *tier tokens*, and Claude Code remaps them to GLM via env vars. So GLM already works under Claude Code — the feature is about *managing, provisioning, and telling the truth about* that path, plus adding the OpenCode path.
+
+---
+
+## Phase 2: Competitive Analysis
+
+`docs/COMPARISON.md:24` already claims *"Multi-model routing (tier aliases + provider mapping)"* as a PAN differentiator — GLM makes that claim real for the value-leader backend of 2026. Peers: OpenCode/Cline/Kilo expose raw provider config (powerful, but the user assembles the JSON themselves); Claude Code takes env vars (no product-level notion of "provider = GLM"). **PAN's differentiation:** a one-command, tier-aware, *honest* GLM switch that carries the whole bot-army model policy (profiles, per-agent pins, effort) across the swap — and refuses to fake costs on a flat-fee plan.
+
+---
+
+## Phase 3: Design
+
+### 3.1 Two integration surfaces
+
+**Surface A — GLM through PAN's existing runtimes (primary, feasible now).**
+Point Claude Code / OpenCode at z.ai's Anthropic-compatible endpoint. This is where ~all the value is and where the work lands.
+
+**Surface B — ZCode as a runtime (deferred/partial).**
+ZCode's documented extensibility = subagents in `~/.zcode/agents/` (Markdown, `@name`), MCP, and a nascent skills/plugin system. It has **no** custom slash-commands, **no** project-level config dir, **no** hooks, **no** headless mode. PAN is command- and hook-heavy (58 commands, 5 hooks), so a *full* PAN-on-ZCode install is **not possible today**. Feasible subset: a "ZCode agent pack" — install PAN's `agents/*.md` into `~/.zcode/agents/` (they're already Markdown) + optionally register `pan-tools` as an MCP server. Recommendation: **ship Surface A now; track ZCode's roadmap** (gate the pack behind ZCode gaining command/config extensibility).
+
+### 3.2 The key abstraction: separate **tier-provider** from **backend**
+
+- `routing.provider` (existing) answers *"what model token do I emit?"* — for **Claude-Code-on-GLM** it stays `anthropic` (the host remaps sonnet/haiku→GLM); for **OpenCode-on-GLM** it becomes `zhipu` (emit real `glm-*` ids).
+- `routing.backend` (**new**, e.g. `"zai"`) answers *"what service actually answers?"* — this single marker drives capability detection, cost honesty, telemetry labels, and provisioning, **without** contorting the tier map. Absent/`null` = today's behavior exactly.
+
+### 3.3 Architecture decisions
+
+1. **`PROVIDER_MODELS.zhipu`** (`core.cjs`): `{ reasoning:'inherit', mid:'glm-4.6', fast:'glm-4.5-air' }`. Model ids sourced from a single `GLM_MODELS` constant so a version bump is one edit. `reasoning:'inherit'` lets the host pick its top GLM (via `ANTHROPIC_DEFAULT_OPUS_MODEL` under Claude Code, or the provider's default under OpenCode).
+2. **`detectProvider`** (`core.cjs`): accept `glm`/`zai` as aliases of `zhipu`; add an env sniff — if `ANTHROPIC_BASE_URL` matches an **allowlisted** z.ai host (exact host compare, not substring), infer backend=zai. (Host allowlist constant, not a regex over user input — avoids the taint-barrier pitfalls from the report/hud work.)
+3. **`detectModelCapabilities`** (`install-lib.cjs`): add a `glm` branch → `{ has_1m_ctx:true, has_thinking:true, has_cache:true, tier: <by name> }` for glm-5._/glm-4.7; and when `backend=zai`, suppress the E-9 warning entirely.
+4. **Provisioning** — new module `provider.cjs` + dispatcher verb `provider set|show|clear <name>` and command `commands/pan/provider.md`:
+   - **Claude Code:** merge an `env` block into `.claude/settings.json`: `ANTHROPIC_BASE_URL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `API_TIMEOUT_MS`. **Never** `ANTHROPIC_AUTH_TOKEN` in a tracked file — instead (a) instruct the user to `export ANTHROPIC_AUTH_TOKEN=…`, or (b) with explicit `--persist-token`, write it only to `.claude/settings.local.json` (gitignored). Proto-pollution-safe merge (reuse `config.cjs` guard).
+   - **OpenCode:** merge a custom provider into `opencode.json`: `@ai-sdk/anthropic`, `options.baseURL = https://api.z.ai/api/anthropic/v1`, `models: { "glm-4.6": {…}, "glm-4.5-air": {…} }`. Set `routing.provider=zhipu` so PAN emits real ids.
+   - **Codex/Gemini/Copilot:** no-op + a clear message: *"GLM via <runtime> isn't a supported z.ai target — use `--claude` or `--opencode`."*
+5. **Cost honesty** (`cost.cjs` + `hud.cjs`/`phase-report.cjs` consumers): when `backend=zai`, route through the existing `ledgerReliability()` degradation — show token volume + a "flat-fee GLM Coding Plan (per-token cost N/A)" advisory instead of a dollar figure.
+6. **Installer flag** (`bin/install.js`): `--provider <name>` (and convenience `--zai`) calls the same `provider.cjs` provisioning against the runtimes being installed. Purely additive; no change to the default install.
+
+### 3.4 Implementation plan
+
+```
+1. pan-wizard-core/bin/lib/core.cjs
+   - GLM_MODELS constant; PROVIDER_MODELS.zhipu; detectProvider glm/zai alias + z.ai host sniff;
+     thread routing.backend through loadConfig fallback + buildConfig.
+2. pan-wizard-core/bin/lib/config.cjs
+   - buildConfigDefaults: routing.backend default (null); document key. (Also close the
+     template↔loader routing divergence flagged in recon.)
+3. bin/install-lib.cjs
+   - detectModelCapabilities: GLM branch (pure fn, easy to unit test).
+4. pan-wizard-core/bin/lib/provider.cjs   (NEW)
+   - setProvider/showProvider/clearProvider; per-runtime writers (claude settings.json env,
+     opencode.json provider); secret-safety; unsupported-runtime guard.
+5. pan-wizard-core/bin/pan-tools.cjs
+   - `provider` dispatch case → provider.cjs.
+6. bin/install.js
+   - `--provider`/`--zai` → provider provisioning after runtime install; teach E-9 warn about backend=zai.
+7. pan-wizard-core/bin/lib/cost.cjs (+ hud/report consumers)
+   - flat-fee branch when backend=zai.
+8. commands/pan/provider.md   (NEW, runtime-agnostic)
+9. pan-wizard-core/references/glm-provider.md   (NEW agent-loaded reference)
+10. Docs: CLI-REFERENCE (provider cmd + routing.backend + config row), USER-GUIDE (config table),
+    COMPARISON (GLM as the proven backend), FAQ (how do I run PAN on GLM?), README (qualitative).
+```
+
+### 3.5 Test plan (≥10; 3 happy / 3 edge / 2 error / 2 runtime-specific)
+
+```
+tests/provider.test.cjs (NEW)
+  happy:   set glm on claude writes the 5 env keys (not the token); show reports backend+mapping; clear reverts.
+  happy:   set glm on opencode writes @ai-sdk/anthropic provider + routing.provider=zhipu.
+  resolve: resolveTierToModel('mid','zhipu') → glm-4.6; ('reasoning','zhipu') → 'inherit'; glm/zai alias == zhipu.
+  caps:    detectModelCapabilities glm-5.2 / GLM-4.7 / glm-4.5-air → 1m/thinking true; unknown-glm-x graceful.
+  edge:    settings.json already has an env block → merge, don't clobber; proto-pollution key rejected.
+  edge:    ANTHROPIC_BASE_URL=z.ai host → detectProvider infers backend=zai; look-alike host NOT matched.
+  edge:    cost with backend=zai → no $ fabricated (tokens + advisory) via ledgerReliability.
+  error:   `provider set glm` on codex/gemini/copilot → unsupported message, zero writes.
+  error:   `--persist-token` writes ONLY to .claude/settings.local.json (assert not settings.json, and gitignored).
+  runtime: full matrix — claude ✅, opencode ✅, others guarded.
+tests/scenarios/provider-install.test.cjs (NEW)
+  `install.js --claude --zai` end-to-end → settings.json env present, token absent, install verifies.
+```
+
+---
+
+## Phase 4: Specification Output
+
+### Files to Create/Modify
+- **New:** `pan-wizard-core/bin/lib/provider.cjs`, `commands/pan/provider.md`, `pan-wizard-core/references/glm-provider.md`, `tests/provider.test.cjs`, `tests/scenarios/provider-install.test.cjs`.
+- **Modify:** `core.cjs`, `config.cjs`, `install-lib.cjs`, `install.js`, `pan-tools.cjs`, `cost.cjs` (+ hud/report consumers), `templates/config.json`; docs (CLI-REFERENCE, USER-GUIDE, COMPARISON, FAQ, README qualitative); CLAUDE.md counts refresh.
+
+### Runtime Matrix
+| Runtime | GLM Supported | Mechanism / Notes |
+|---------|:---:|---|
+| Claude Code | ✅ Full | `.claude/settings.json` `env`: base URL + `ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL`; host remaps PAN's tier tokens → GLM. Token via shell env. |
+| OpenCode | ✅ Full | `opencode.json` custom `@ai-sdk/anthropic` provider (baseURL `…/anthropic/v1`); PAN emits real `glm-*` ids (`routing.provider=zhipu`). |
+| Codex | ⚠️ Not a z.ai target | OpenAI-compatible override is technically possible but unsupported by z.ai; guarded no-op + message. |
+| Gemini | ❌ | Google-native; no BYO Anthropic endpoint. |
+| GitHub Copilot | ❌ | GitHub-managed models; no custom endpoint. |
+| **ZCode** (new) | ⚠️ Deferred/partial | Agent-pack into `~/.zcode/agents/` + optional MCP only; no commands/hooks/config → not a full runtime yet. |
+
+---
+
+## Phase 5: Risk Assessment
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| **Secret leakage** — z.ai token written to a committed `settings.json` | High | Never persist the token by default; non-secret env only; `--persist-token` writes solely to gitignored `settings.local.json`; test asserts token absent from tracked files. |
+| Clobbering a user's existing `settings.json`/`opencode.json` | High | Deep-merge with proto-pollution guard; `provider clear` restores; snapshot the pre-write file. |
+| GLM model ids drift (4.6 → 5.2 → …) | Medium | Single `GLM_MODELS` constant; `reasoning:'inherit'` defers top-tier choice to the host/plan; document that ids track the plan. |
+| Base-URL string reaching a shell / taint barrier | Medium | Fixed allowlisted host constant + exact-host compare; no user string interpolated into any exec (reuse the report/hud opener discipline). |
+| False cost data on flat-fee plan | Medium | `backend=zai` → flat-fee branch via `ledgerReliability()`; never emit a per-token `$`. |
+| Users expect full ZCode support | Low | Spec + docs state the honest partial verdict and the blocking reason up front. |
+| Regression for non-GLM users | Low | Entire path is opt-in behind `backend`/`--provider`; default resolution untouched; SC-11 guards it. |
+
+---
+
+## Recommendation
+
+Ship **Surface A** in milestones: **M1** provider awareness (core.cjs + capability branch — GLM stops being mislabelled), **M2** provisioning (`provider.cjs` + `/pan:provider` + `--zai`), **M3** cost honesty + docs. Treat **ZCode** (Surface B) as a tracked, gated follow-up pending ZCode extensibility. Net: PAN's whole bot army runs on the 2026 value-leader backend with one command, and never lies about cost or capability.