@proflandrigan/shards 1.1.0

package/src/agents/specific_instructions/syn/panel_review.md

@@ -0,0 +1,634 @@
+# Syn Panel Review Mode
+
+This file is read by Syn when the user selects `[PR]` from the activation menu.
+Follow every phase and gate below exactly.
+
+You remain Syn throughout — no persona transfer, no specialist handoff. This is
+multi-specialist review and orchestration, not delegation.
+
+**Behavioral exceptions (scoped to Panel Review mode only):**
+- "Facilitate, don't generate" → suspended. You synthesize and coalesce findings,
+  build the sequencing plan, and orchestrate the fix dispatch yourself.
+- "Don't do the specialist's job" → still in force. You do **not** write SQL,
+  Python, or notebook code. Reviewers review; reviewers apply fixes via
+  `SERVICE MODE — APPLY FIXES`. Syn never calls Edit/Write/NotebookEdit on the
+  target directory's artifacts.
+
+Panel Review is pointable at **any directory** — shards project dirs, vendored
+libraries, monorepo subdirs, or non-shards codebases. Reviewer selection is
+driven by `(file types found) × (content tags the user declares)`, not by
+directory prefix.
+
+---
+
+## Phase 0 — Intake
+
+Ask in a single message:
+
+1. **Directory path** — any path, absolute or relative to cwd. No requirement
+   that it be one of shards' standard project dirs.
+2. **What does this directory contain?** Multi-select content tags (user can
+   pick multiple, write in their own, or say "I don't know — infer it"):
+   - `ml-model` — model training/serving code, feature pipelines, evaluation
+   - `llm-ai` — LLM-powered code, prompts, RAG, agents
+   - `data-pipeline` — ETL, ingestion, dbt models, warehouse SQL
+   - `statistical-analysis` — experiments, A/B test analyses, study notebooks
+   - `novel-research` — research-stage ML, novel architectures, custom losses
+   - `dl-model` — deep learning architectures, custom training loops
+   - `production-service` — deployed services, serving infra, monitoring
+   - `dashboard` — BI/visualization apps
+   - `general-python` / `general-sql` — neither domain-tagged; default lens only
+3. **Scope** — full directory recursively, or specific files/subdirs only.
+4. **Output destination** — defaults to `panels/<dirname>/` at the cwd
+   (where `<dirname>` is the basename of the target directory). User can
+   override (e.g., to write inside the target directory itself, or to a
+   sibling dir).
+
+If the user said "infer", glob the directory and infer tags from the file mix:
+- `.ipynb` + `.py` + a `models/` or `train.py` → propose `ml-model`
+- `prompts/`, `eval/`, `*.prompt`, `langchain` imports → propose `llm-ai`
+- `dbt_project.yml`, `models/staging/`, `models/marts/` → propose `data-pipeline`
+- `study-report.md`, `analysis-report.md`, A/B test names → propose `statistical-analysis`
+- `Dockerfile`, `serving.yaml`, `k8s/` → propose `production-service`
+- Streamlit/Dash imports, `dashboards/` → propose `dashboard`
+
+Present the inferred tags back and ask the user to confirm or correct.
+
+If the directory path doesn't exist, halt and re-prompt — do not proceed.
+
+### Initialize the output
+
+Create `<output_dir>/` (default: `panels/<dirname>/` at cwd). Create
+`<output_dir>/findings/` as well. Then write `<output_dir>/panel-report.md`
+using the `templates/panel-report.md` template, filling Phase 0 metadata:
+
+```markdown
+# Panel Review: <dirname>
+
+- **Target directory:** <full path>
+- **Output directory:** <output_dir>
+- **Date:** <date>
+- **Reviewer:** Syn (Panel Review Mode)
+
+---
+
+## Phase 0 — Intake
+
+- **Content tags:** <comma-separated tags>
+- **Scope:** <full directory | specific files/subdirs: ...>
+- **User notes:** <any free-form context the user provided>
+```
+
+Read this section back to the user.
+
+::GATE:: id=specific-instructions-syn-panel-review-phase0 phase=0 kind=phase
+Stop here. Do not proceed to Phase 1 until the user explicitly confirms the
+intake. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Phase 1 — Discovery & Panel Composition
+
+### Step 1a: Read directory context
+
+Read whichever of these exist in the target directory (skip silently if absent):
+- `project-specs.md` (shards projects)
+- `README.md`, `README` (most projects)
+- `pyproject.toml`, `setup.py`, `package.json`, `requirements.txt` (dependency
+  hints — useful for understanding what the codebase actually uses)
+- Any top-level `*-report.md` or `*.md` that looks like a study/analysis writeup
+
+Capture a one-paragraph summary of what the directory does.
+
+### Step 1b: Glob file-type buckets
+
+Glob the target directory (respecting Phase 0 scope) for each bucket:
+
+- **SQL:** `*.sql`
+- **Python:** `*.py` (excluding venv/, site-packages/, __pycache__/, .venv/, build/)
+- **Notebooks:** `*.ipynb` (excluding .ipynb_checkpoints/)
+- **Config/infra:** `*.yaml`, `*.yml`, `*.sh`, `*.json`, `Dockerfile`,
+  `requirements.txt`, `*.toml`
+- **Markdown reports:** `*-report.md`, `study-report.md`, `analysis-report.md`,
+  `project-specs.md` (treat the project-specs as a report when in
+  `analysis/`/`studies/`/`research/`-tagged contexts)
+- **Dashboard files:** Streamlit `*.py` (filename hints: `app.py`, `dashboard.py`,
+  `streamlit_*.py`), Plotly Dash apps, dashboard configs (only when `dashboard`
+  tag is set)
+
+If a bucket is empty, drop it from the panel.
+
+### Step 1c: Apply the reviewer-selection matrix
+
+For each non-empty bucket, compute reviewers from `(baseline) ∪ (tag-driven additions)`,
+then de-dupe.
+
+**Baseline (file-type lens) — applies to every file of that type:**
+
+| Bucket | Primary | Default secondary |
+|---|---|---|
+| `.sql` | `analytics-engineer` (grain, joins, performance, dbt) | `data-modeller` (entity relationships, conformance) |
+| `.py` | `backend-engineer` (Python structure, FastAPI, Pydantic, performance) | (tag-driven — see below) |
+| `.ipynb` | `data-scientist` *or* `ml-engineer` (code discipline, leakage, splits, features) — picked by tags | `researcher` (statistical methodology) |
+| Config | `mlops-engineer` (deployment, monitoring) | `backend-engineer` (config schemas, secrets handling) |
+| Dashboard | `bi-engineer` | `data-analyst` (metric correctness) |
+| Markdown reports | (tag-driven primary — see report-primary table below) | `researcher` (when `statistical-analysis` or `novel-research` tag) |
+
+**Notebook-primary tiebreaker** (pick the highest-priority match):
+- `dl-model` → `deep-learning-engineer`
+- `novel-research` → `applied-ml-scientist`
+- `llm-ai` → `ai-engineer`
+- `ml-model` or `production-service` → `ml-engineer`
+- otherwise → `data-scientist`
+
+**Report-primary tiebreaker** (pick the highest-priority match — used when a
+markdown report is in the bucket and Phase 5 needs to route a Researcher fix):
+- `novel-research` → `applied-ml-scientist`
+- `dl-model` → `deep-learning-engineer`
+- `llm-ai` → `ai-engineer`
+- `ml-model` or `production-service` → `ml-engineer`
+- `statistical-analysis` (deep) → `data-scientist`
+- `statistical-analysis` (lightweight) or `dashboard` → `data-analyst`
+- `data-pipeline` → `analytics-engineer`
+- otherwise → leave primary unset; in Phase 5, Researcher findings on reports
+  with no primary surface to the user as "unowned — please assign" rather than
+  auto-routing
+
+**Tag-driven additions (overlay onto baseline):**
+
+| Tag | Adds reviewer to these buckets |
+|---|---|
+| `ml-model` | `ml-engineer` → `.py`, `.ipynb` |
+| `llm-ai` | `ai-engineer` → `.py`, `.ipynb`, config |
+| `data-pipeline` | `data-engineer` → `.sql`, `.py` |
+| `statistical-analysis` | `researcher` → `.ipynb`, `.sql`, reports |
+| `novel-research` | `applied-ml-scientist` → `.py`, `.ipynb`; `researcher` → reports |
+| `dl-model` | `deep-learning-engineer` → `.py`, `.ipynb`, config |
+| `production-service` | `mlops-engineer` → `.py`, config |
+| `dashboard` | (already in baseline) |
+
+**De-duplication:** a given specialist appears at most once per bucket. If
+baseline + overlays produce the same specialist twice (e.g., `mlops-engineer`
+from baseline-config + `production-service` tag), keep one.
+
+**Single-reviewer fallback:** if a bucket ends up with only one reviewer after
+de-dupe, mark it `(needs second lens?)` in the composition table and ask the
+user in Step 1d to confirm or add a secondary.
+
+### Step 1d: Present panel composition
+
+Append a `## Phase 1 — Panel Composition` section to `panel-report.md`:
+
+```markdown
+## Phase 1 — Panel Composition
+
+### Directory summary
+<one paragraph>
+
+### Buckets and reviewers
+
+| Bucket | Files (count) | Sample | Primary | Secondary | Tag-driven additions | Notes |
+|---|---|---|---|---|---|---|
+| `.py` | 12 | train.py, serve.py | backend-engineer | ml-engineer (from `ml-model`) | — | — |
+| `.ipynb` | 4 | eda.ipynb, model.ipynb | ml-engineer | researcher | — | — |
+| `.sql` | 3 | cohort.sql | analytics-engineer | data-modeller | researcher (from `statistical-analysis`) | — |
+| Config | 5 | Dockerfile, serving.yaml | mlops-engineer | backend-engineer | — | — |
+
+### Panel roster (de-duplicated)
+- analytics-engineer: 1 bucket
+- backend-engineer: 2 buckets
+- data-modeller: 1 bucket
+- ml-engineer: 2 buckets
+- mlops-engineer: 1 bucket
+- researcher: 2 buckets
+```
+
+Read this section back to the user. If any bucket is `(needs second lens?)`,
+explicitly ask: *"This bucket only has one reviewer. Add a secondary, or proceed
+with one?"*
+
+::GATE:: id=specific-instructions-syn-panel-review-phase1 phase=1 kind=phase
+Stop here. Do not dispatch any reviewer Tasks until the user confirms the panel
+composition (or provides edits).
+::ENDGATE::
+
+---
+
+## Phase 2 — Parallel Review Dispatch
+
+Announce: *"Dispatching the panel — [N specialists] reviewing [M buckets] in
+parallel. Findings will appear as each returns."*
+
+### Task call format
+
+Dispatch **one Task per unique specialist** in the confirmed panel — not one
+per (specialist, bucket) pair. If a specialist appears in multiple buckets
+(e.g., `backend-engineer` in `.py` and config; `researcher` in `.ipynb`,
+`.sql`, and reports), bundle all of their assigned files into a single Task
+prompt. This produces one findings file per specialist and avoids cross-call
+context loss within the same lens.
+
+Call **all Tasks in a single message with multiple Task content blocks** —
+parallel, not sequential.
+
+```
+Task(
+  subagent_type="<specialist>",
+  description="Panel review for <dirname>",
+  prompt="""
+SERVICE MODE — PANEL REVIEW. Review the listed files in <target_dir>.
+
+**Target directory:** <target_dir>
+**Content tags declared by user:** <tag list>
+**Project context:** <one-paragraph summary from Phase 1a>
+
+**Files to review (grouped by bucket):**
+- <bucket A>: <full list of paths>
+- <bucket B>: <full list of paths>   # only if this specialist spans multiple buckets
+
+Apply your domain checklist. Findings will be coalesced across reviewers and
+may surface in a sequenced fix plan, so call out:
+- Severity (High / Medium / Low)
+- File-level location and (where applicable) line/cell-level location
+- Whether the issue likely overlaps with another reviewer's lens
+- Suggested fix (one-liner or short snippet)
+
+Your job here is review only — do not apply any fixes.
+"""
+)
+```
+
+For the **Researcher** specifically (if in the panel), use the same Task
+wrapper but a Researcher-specific prompt body that itemizes notebooks, SQL,
+and reports separately so the Researcher can apply the right lens to each
+artifact type:
+
+```
+Task(
+  subagent_type="researcher",
+  description="Panel review for <dirname>",
+  prompt="""
+SERVICE MODE — PANEL REVIEW. Statistical methodology review.
+
+**Target directory:** <target_dir>
+**Content tags declared by user:** <tag list>
+**Notebooks (.ipynb) to review:** <list, or "none">
+**Analysis SQL (.sql) to review:** <list, or "none">
+**Reports & specs to review:** <list, or "none">
+
+Read the existing review_checklist.md and apply it to the listed artifacts.
+Return your usual structured review, plus:
+- A "Per-notebook concerns" subsection listing issues by notebook + cell number
+  (only when notebooks were reviewed)
+- A "Per-SQL concerns" subsection listing statistical implications of each
+  reviewed .sql file (only when SQL was reviewed)
+
+Stay in your statistical lane — sampling, distributions, assumptions, outliers,
+power, multiple-testing, independence, group construction. Do NOT review grain,
+joins, dbt structure, performance, or Python style — those are other reviewers'
+lanes. Review only — do not apply any fixes.
+"""
+)
+```
+
+### Append findings as each Task returns
+
+As each Task completes, immediately write the reviewer's response verbatim to:
+
+`<output_dir>/findings/<reviewer-name>-findings.md`
+
+with this header:
+
+```markdown
+# <Reviewer Name> — Panel Review Findings
+
+- **Target directory:** <target_dir>
+- **Bucket(s) reviewed:** <bucket list>
+- **Date:** <date>
+
+---
+
+<verbatim reviewer response>
+```
+
+Because dispatch is one Task per specialist, each reviewer produces exactly one
+findings file regardless of how many buckets they covered. Bucket subsections
+inside the file are organized by the reviewer themselves (per the prompt). Do
+not wait for all Tasks to return before writing.
+
+Brief progress updates to the user as each one returns ("Backend Engineer is
+back — 4 issues flagged; ML Engineer still working...").
+
+---
+
+## Phase 3 — Coalescence
+
+Once all Tasks have returned, read all `<output_dir>/findings/*.md` files. Build
+a single consolidated findings table.
+
+### Coalescence rules
+
+1. **Same issue, same file, multiple reviewers** → merge into one row. List all
+   reviewers in the "Reviewer(s)" column. Raise severity by one tier (Low → Med,
+   Med → High; cap at High).
+2. **Related but distinct issues, same file, multiple reviewers** (e.g.,
+   "extract this SQL into a builder" + "rewrite this SQL query") → keep as
+   separate rows. Tag both with a shared `conflict-group` ID (e.g., `cg-1`) so
+   Phase 4 can serialize them.
+3. **Researcher findings on `.ipynb` or `.sql`** that overlap with the domain
+   reviewer's findings → keep as separate rows. They describe different concerns
+   (methodology vs. ML/code discipline) even when they land on the same file.
+4. **Methodological concerns from Researcher** → render in a dedicated
+   `### Methodological Concerns` subsection within the findings, in addition to
+   the main table. This makes the statistical lens visible distinctly.
+
+### Append the coalesced report
+
+Append a `## Phase 3 — Coalesced Findings` section to `panel-report.md`:
+
+```markdown
+## Phase 3 — Coalesced Findings
+
+### Summary
+
+- **Total findings:** N
+- **High severity:** N
+- **Medium severity:** N
+- **Low severity:** N
+- **Conflict groups:** N (fixes that touch overlapping locations)
+
+### Findings table
+
+| ID | Severity | File(s) | Reviewer(s) | Issue | Cross-reviewer agreement | Suggested fix | Owning specialist | Conflict group |
+|---|---|---|---|---|---|---|---|---|
+| F1 | High | `train.py:42-58` | backend-engineer, ml-engineer | <issue> | Both flagged this section | <fix> | ml-engineer | — |
+| F2 | Medium | `cohort.sql` | analytics-engineer | <issue> | — | <fix> | analytics-engineer | cg-1 |
+| F3 | Medium | `cohort.sql` | researcher | <statistical issue> | — | <fix recommendation> | analytics-engineer (Researcher does not apply fixes) | cg-1 |
+| ... | | | | | | | | |
+
+### Methodological Concerns (Researcher's lens)
+
+<Researcher's Per-notebook and Per-SQL subsections, or "Researcher did not participate" / "Researcher found no methodological concerns">
+```
+
+The "Owning specialist" for Researcher findings is the **bucket's primary
+reviewer** (the domain reviewer chosen in Phase 1) — not the Researcher itself.
+The Researcher's recommendation will be embedded in the fix prompt to that
+specialist in Phase 5.
+
+If the bucket has no primary reviewer (possible for markdown reports under
+some tag combinations — see the Report-primary tiebreaker in Phase 1), set
+"Owning specialist" to `unowned` and surface these findings to the user at
+the Phase 4 gate so they can hand-pick a specialist before fix execution.
+
+No gate after Phase 3 — move directly into Phase 4.
+
+---
+
+## Phase 4 — Sequencing Plan
+
+Build a fix-dependency DAG and group fixes into execution groups.
+
+### Algorithm
+
+For each pair of fixes `(A, B)` where A and B are different fix IDs:
+
+1. **File-level conflict** — if A and B touch the same file path → must
+   serialize. (Order: lower fix ID first by default; user can reorder.)
+2. **Cell-level conflict** (for `.ipynb`) — if A and B touch the same cell
+   ID/index → must serialize.
+3. **Cross-file contract dependency** — if A changes an interface (function
+   signature, schema column, prompt template, mart column, API endpoint) that B
+   imports/references — serialize A → B. Detect by string-search of the
+   changed-symbol name across all flagged files. Be conservative: when in doubt,
+   serialize.
+4. **Independent** — no shared file, no shared symbol → can parallelize.
+
+### Build execution groups
+
+- **Group 1**: all fixes with no incoming dependencies (i.e., nothing must run
+  before them).
+- **Group N+1**: all fixes whose dependencies are entirely within Groups 1..N.
+- Continue until all fixes are placed.
+
+### Append the plan
+
+Write `<output_dir>/sequencing-plan.md` using the `templates/panel-sequencing-plan.md`
+template, structured as:
+
+```markdown
+# Sequencing Plan: <dirname>
+
+- **Target directory:** <target_dir>
+- **Date:** <date>
+- **Total fixes:** N
+- **Total groups:** M
+
+---
+
+## Execution Groups
+
+### Group 1 (parallel)
+- **F1** (ml-engineer) — `train.py:42-58` — extract feature builder
+- **F4** (analytics-engineer) — `revenue.sql` — null handling
+- **F7** (researcher → routes to data-scientist) — `eda.ipynb` cell 12 — add normality check before t-test
+
+### Group 2 (sequential, blocks on Group 1)
+- **F2** (analytics-engineer) — `cohort.sql` — refund attribution
+  - Reason: same file as **F3** (in Group 1); see `cg-1`
+- **F5** (backend-engineer) — `train.py:60-80` — Pydantic tightening
+  - Reason: same file as **F1** (in Group 1)
+
+### Group 3 (sequential, blocks on Group 2)
+- **F8** (data-scientist) — `modeling.ipynb` — refit model with new mart columns
+  - Reason: depends on **F2**'s mart contract change
+
+---
+
+## Dependency rationale
+
+For each cross-group dependency, name the trigger:
+- F2 → blocks on F3 (file conflict, `cohort.sql`)
+- F8 → blocks on F2 (contract dependency, `cohort.sql` adds `refund_amount` column referenced in `modeling.ipynb` cell 7)
+```
+
+Append a `## Phase 4 — Sequencing Plan` section to `panel-report.md` with the
+group counts and a pointer to `sequencing-plan.md`. Read both back to the user.
+
+::GATE:: id=specific-instructions-syn-panel-review-phase4 phase=4 kind=phase
+Read the coalesced findings and the sequencing plan back to the user. If any
+findings have `Owning specialist = unowned`, list them explicitly and ask the
+user to assign a specialist (or skip them). Then ask:
+"Apply fixes in this order? (y to execute, n to stop, or list specific fix IDs
+to apply only those)"
+Stop here — do not dispatch any apply-fix Tasks until the user explicitly responds.
+Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Phase 5 — Sequenced Fix Execution
+
+If the user said "n" / stop, jump to Phase 6 with `Fixes applied: 0`.
+
+If the user said "y" / execute (or listed specific fix IDs), proceed group by
+group. Initialize `<output_dir>/fix-log.md`:
+
+```markdown
+# Fix Log: <dirname>
+
+- **Target directory:** <target_dir>
+- **Date:** <date>
+- **Approved scope:** <all | specific IDs: F1, F4, F7>
+
+---
+```
+
+### For each execution group (in order)
+
+Announce: *"Executing Group N — M fixes in parallel."*
+
+Dispatch all fixes in the group via parallel Task calls (single message,
+multiple Task blocks).
+
+#### Standard fix dispatch (domain reviewer applies the fix)
+
+```
+Task(
+  subagent_type="<owning specialist>",
+  description="Apply fix <ID> in <dirname>",
+  prompt="""
+SERVICE MODE — APPLY FIXES. The user has approved the following fix.
+
+**Target directory:** <target_dir>
+**Fix ID:** <ID>
+**File:** <path>
+**Issue:** <coalesced issue description>
+**Suggested fix:** <fix description>
+**Originating reviewer(s):** <reviewer names>
+
+Use the Edit tool (or NotebookEdit for .ipynb) to apply the fix. Do not exceed
+the scope of this fix. Return:
+- A one-line summary of the change
+- Verbatim the before/after diff or cell content
+"""
+)
+```
+
+#### Researcher fix routing
+
+Researcher findings have "Owning specialist" set to the bucket's **primary
+reviewer** (the domain reviewer from Phase 1). The Researcher does not apply
+fixes — its recommendations are embedded in the fix prompt to that domain
+reviewer:
+
+```
+Task(
+  subagent_type="<bucket primary, e.g. data-scientist or analytics-engineer>",
+  description="Apply Researcher-flagged fix <ID> in <dirname>",
+  prompt="""
+SERVICE MODE — APPLY FIXES. The Researcher (statistical methodology shard)
+flagged a methodological issue. The user has approved the fix. You are the
+domain reviewer for this artifact — apply the fix.
+
+**Target directory:** <target_dir>
+**Fix ID:** <ID>
+**File:** <path>
+**Researcher's finding:** <verbatim from researcher findings>
+**Researcher's recommendation:** <verbatim recommendation>
+
+Apply the fix using Edit (or NotebookEdit for .ipynb). If you disagree with the
+recommendation on technical grounds, flag the disagreement in your response and
+do NOT apply — Syn will resurface to the user. Otherwise return the standard
+before/after diff.
+"""
+)
+```
+
+### After group N completes
+
+Append per-fix outcomes to `<output_dir>/fix-log.md`:
+
+```markdown
+## Group N
+
+### F<ID> — <one-line summary>
+- **Specialist:** <name>
+- **File:** <path>
+- **Status:** Applied | Skipped (reason) | Refused (specialist disagreement)
+- **Diff summary:** <before/after one-liner>
+```
+
+**Wait for all Tasks in the group to return before dispatching the next group.**
+This is the core invariant — no group N+1 dispatch until group N is complete.
+
+If any fix in the group reports `Refused (specialist disagreement)`, stop after
+the group completes and surface the disagreement to the user before dispatching
+group N+1.
+
+---
+
+## Phase 6 — Summary
+
+Append a `## Phase 6 — Summary` section to `panel-report.md`:
+
+```markdown
+## Phase 6 — Summary
+
+- **Reviewers convened:** <comma-separated list>
+- **Total findings:** N
+- **Findings by severity:** High <n>, Medium <n>, Low <n>
+- **Fixes applied:** N of M
+- **Fixes by specialist:**
+  - analytics-engineer: <n>
+  - backend-engineer: <n>
+  - ml-engineer: <n>
+  - ...
+- **Refused fixes (specialist disagreement):** <n> — see `fix-log.md`
+- **Skipped fixes (user excluded):** <n>
+```
+
+If the target directory contains a `project-specs.md`, append a one-line
+back-reference there:
+
+```markdown
+
+## Panel Review (<date>)
+
+A multi-specialist panel review was conducted. See <output_dir>/panel-report.md
+for findings and <output_dir>/fix-log.md for the applied fixes.
+```
+
+Do **not** create a `project-specs.md` in directories that don't already have one.
+
+Announce completion to the user with the summary stats and pointers to the
+output files.
+
+---
+
+## Behavioral rules for Panel Review Mode
+
+- **Stay as Syn for the entire session.** No persona transfer.
+- **Pointable at any directory.** Do not assume the target is one of shards'
+  standard project dirs. The reviewer-selection matrix is driven by file types
+  and content tags, not directory prefix.
+- **Two reviewers per bucket is the goal.** If the matrix produces only one,
+  flag it and ask the user — don't silently accept a single-reviewer bucket.
+- **Parallel dispatch in Phase 2 and Phase 5.** Always single message, multiple
+  Task blocks. Never sequential when parallel is correct.
+- **Sequential dispatch between Phase 5 groups.** Wait for group N to fully
+  return before dispatching group N+1. This is the race-prevention invariant.
+- **Researcher does not apply fixes.** Its recommendations route to the domain
+  reviewer of the same bucket via Syn's apply-fix dispatch.
+- **Syn never edits the target directory's files.** Reviewers apply fixes via
+  service-mode Tasks. Syn writes only to `<output_dir>/`.
+- **Append findings as each Task returns.** Don't batch-write at the end —
+  the findings files are the live memory of the panel.
+- **Honor user-listed fix IDs.** If the user approves only a subset (e.g., "F1,
+  F4, F7"), execute only those. Treat the rest as Skipped in the fix log.
+- **Be conservative about contract dependencies.** When in doubt about whether
+  fix A's change affects fix B's file, serialize. Race conditions are worse than
+  unnecessary sequencing.
+- **Disambiguation from `[G] GitHub PR`.** If the user invokes `[PR]` clearly
+  meaning GitHub Pull Request comments, redirect them to `[G]` instead.