feat(skills): orchestrator tier 2 — multi-model routing, DAG, domain memory, follow-up Q&A

[vanterx]

Summary

Stacked on tier 1 (PR #5). Adds four cost-and-intelligence primitives without changing the trust model (strictly offline preserved).

Primitive	What it does
V5 Multi-model cost routing	Haiku for triage/classification/Q&A, Sonnet for synthesis and deep dive, Opus for the adversarial pass. Cuts cost ~40% vs all-Sonnet at no quality loss on high-stakes phases. Override via `--model-tier {economy|standard|maximum}` and `--no-adversarial`.
V6 Skill-graph DAG	Replaces fixed phase ordering with a dynamic dependency DAG built from artifact types and probe findings. Probes that depend on each other sequence correctly; everything else runs in parallel. Dynamic edges open during the walk based on findings (e.g., S9 sniffing in sqlplan-review opens an edge to query-store-review).
V9 Domain memory	Per-instance facts (MAXDOP, cores, AG topology, partitioning, RCSI status, trace flags) loaded from `~/.mssql-perf-review/instances/.json`. Validates every recommendation against the facts: redundant recommendations rejected, environment-aware escalators applied. Orchestrator never writes facts.json silently.
V10 Follow-up Q&A	After the report, the orchestrator stays in the session to answer questions ("why this index ordering?", "why was MAXDOP not recommended?"). Most follow-ups are free — they read from the in-context evidence chain. Five-category question taxonomy with when-to-probe rules.

Changes

New references (4):

• `skills/mssql-performance-review/references/model-routing.md` — tier-to-phase mapping, override flags, cost profile
• `skills/mssql-performance-review/references/skill-dag.md` — DAG construction rules, walk algorithm, dynamic edge catalogue
• `skills/mssql-performance-review/references/domain-memory.md` — facts.json schema, rejection/escalation catalogue, staleness handling
• `skills/mssql-performance-review/references/followup-qa.md` — question taxonomy, refusal patterns, answer format

Updated:

• `skills/mssql-performance-review/SKILL.md` — primitive list grows from 4 to 8; new sections describe DAG dispatch, model routing, domain memory loading, follow-up Q&A behavior. 363 lines (under 1000-line cap).
• `skills/mssql-performance-review/references/README.md` — index entries for all 4 new references.

Trust model unchanged

• Strictly offline — no SQL Server contact
• Domain memory is user-managed (read-only from orchestrator)
• Multi-model routing affects cost only, not trust surface

Test plan

• `bash scripts/verify-docs.sh` — 31 PASS, 0 WARN, 0 FAIL
• SKILL.md within 1000-line cap (363 lines)
• All 4 new references linked from references/README.md with load-when guidance
• Adversarial pass remains mandatory even on `--model-tier economy` (downgrades only to Sonnet, never to Haiku)

Base branch

This PR targets `feat/perf-review-orchestrator-v4-tier1` (stacked). After tier 1 (PR #5) merges to main, retarget this PR to main and merge.

Roadmap

Tier	Status
tier 1	PR #5 — open
tier 2	this PR
tier 3	(next PR — stacked on this branch)

🤖 Generated with Claude Code

[vanterx]

Spec contradiction: adversarial pass minimum model tier

In references/model-routing.md, three statements disagree on whether the adversarial pass can use Sonnet:

• Line 80 (Override rules): "Adversarial pass is always at least Sonnet..."
• Line 106 (Safeguard 2): "...the adversarial pass (always Opus or higher)..."
• Line 108 (Safeguard 3): "Adversarial pass cannot be downgraded. Even on --model-tier economy, the adversarial check runs on Opus."

Safeguards 2 and 3 agree (Opus minimum). The override rules line permits Sonnet. SKILL.md line 126 also agrees with the safeguards: "Opus 4.7 (cannot be downgraded even on --model-tier economy — quality-critical)".

Severity: Medium — if the LLM follows the override rules section rather than the safeguards section, it will use Sonnet for the adversarial pass on economy tier, breaking the stated quality guarantee.

Fix: Change line 80 from "at least Sonnet" to "at least Opus" to match the rest of the specification.

[vanterx]

Fixed in commit afa8241. Line 80 of model-routing.md now says "Adversarial pass is always Opus (Haiku and Sonnet miss counterfactuals reliably); cannot be downgraded by any tier flag — this is the most important quality guarantee." Consistent with lines 106, 108, and SKILL.md line 126.

[vanterx]

Stale forward-reference to domain memory

references/risk-rubric.md line 57:

Domain memory escalators are checked once tier-2 introduces facts.json (see backlog plan v4). In tier 1, assume defaults from this table apply.

This PR introduces domain-memory.md in the same references/ directory, making this line stale. It describes domain memory as a future tier-2 feature when the file it references is now present. The risk-rubric should mention references/domain-memory.md by name (similar to how SKILL.md loads domain-memory.md when a facts file is present).

Severity: Low — the LLM loading risk-rubric.md will still apply the escalator table (line 55 already covers domain memory); this is a forward-reference that's now incorrect since the referenced feature has landed.

Fix: Replace the sentence with something like "Domain memory escalators are checked against references/domain-memory.md when a facts file is loaded for the target instance."

[vanterx]

Fixed in commit b891d6f. risk-rubric.md line 57 now reads:

Domain memory escalators are checked against references/domain-memory.md when a facts file is loaded for the target instance (~/.mssql-perf-review/instances/<server>.json). When no facts file is present, the defaults in this table apply.

This matches how SKILL.md loads the file (now-present, no longer a forward-reference) and gives the canonical facts.json path.

[vanterx]

Tautological model routing description

model-routing.md line 53:

| User reports "previous review missed the obvious problem" | maximum (escalates the adversarial pass to Opus from Opus, plus all reasoning to Opus) |

The adversarial pass already runs on Opus in --model-tier standard (line 14). The parenthetical "to Opus from Opus" is a tautology — it describes no actual escalation. The intent of --model-tier maximum is to escalate synthesis and deep-dive phases to Opus (correctly described on line 24 as "Sonnet for triage; Opus for all reasoning phases").

Severity: Low — documentation, no runtime impact.

Fix: Rewrite the parenthetical to describe what maximum tier adds vs standard (e.g., "adversarial already runs Opus; also escalates synthesis and deep dive to Opus") or simply omit the redundant phrase.

[vanterx]

Bogus flag syntax in follow-up Q&A reference

followup-qa.md line 152:

`--model-tier maximum --no-adversarial=false`

--no-adversarial is defined as a boolean flag (no value) throughout model-routing.md (line 25: "Skip the Opus adversarial pass"). --no-adversarial=false is not valid syntax for a flag — this looks like a --flag=<value> pattern but --no-adversarial was never defined to take a value. The adversarial pass is on by default; re-dispatching a follow-up probe without --no-adversarial would already run it.

Severity: Low — if an LLM tries to parse this literally and passes --no-adversarial=false as a single flag token, it may not match any defined flag. In practice, the Q&A instructions say "dispatch a targeted adversarial probe" — so the flag isn't actually needed for behavior.

Fix: Change to just --model-tier maximum (since --no-adversarial was never passed and adversarial is on by default).

[vanterx]

Both nits fixed in commit 62badd8:

1. Tautological description — model-routing.md line 53 now reads: "maximum (adversarial already runs Opus on standard; this also escalates synthesis and deep dive to Opus)" — describes what maximum actually adds instead of the no-op "to Opus from Opus".

2. Bogus flag syntax — followup-qa.md line 152 simplified to just --model-tier maximum (with a parenthetical noting adversarial is on by default). Dropped the invalid --no-adversarial=false token.

Tier 2 merged forward into tier 3 (db2947e) so PR #7 stays consistent.

[vanterx]

Off-by-one error in skills-skipped count

skill-dag.md line 148 in Example 2 states "10 skills skipped. 4 ran." but the count is wrong. There are 15 sub-skills total. The explicit "Skills NOT run" list covers 9 skills. Two additional skills — sqlstats-review and sqlplan-batch — are also not run in this scenario but are omitted from the listing. The correct count is 11 skills skipped, 4 ran.

Severity: Low — documentation inconsistency; doesn't affect runtime behavior.