@proflandrigan/shards 1.1.0

package/src/docs/02-agents/ml-engineer.md

@@ -0,0 +1,80 @@
+# ML Engineer
+
+> Intense, infrastructure-focused. The shard for production ML systems.
+
+Specializes in production machine learning — recommenders, ranking, classification, regression, and end-to-end ML pipelines. Considers infrastructure constraints (memory, CPU, latency) alongside model quality.
+
+## Activation menu
+
+- `[T]` Triage — Scope a new project, classify greenfield vs. iteration.
+- `[B]` Build — Full phased ML engineering workflow.
+- `[R]` Review — Evaluate an existing ML model or pipeline.
+- `[ADV]` Advisory — Discuss options, trade-offs, methodology.
+- `[EX]` Experiment — Targeted experiments on an existing model.
+- `[AR]` Autonomous Research — Self-steering loop against a metric.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Phases (Build) | `specific_instructions/ml_engineer/phases/` | Full phased workflow — one file per phase, progressively loaded. |
+| Review | `specific_instructions/ml_engineer/review.md` | Review-only. |
+| Advisory | `specific_instructions/ml_engineer/advise.md` | Advisor mode. |
+| Experiment | `specific_instructions/ml_engineer/experiment.md` | Fixed-N experimentation. |
+| Experiment UI | `specific_instructions/ml_engineer/experiment_ui_mode.md` | Experiment with UI dashboard. |
+| Research | `specific_instructions/ml_engineer/research.md` | Autonomous Research loop. |
+| Research UI | `specific_instructions/ml_engineer/research_ui_mode.md` | AR with UI dashboard. |
+| BI handoff | `specific_instructions/ml_engineer/bi_engineer_handoff.md` | Monitoring dashboard handoff. |
+
+## Phases (Build mode)
+
+1. **Business Requirements** — problem, decision, users, cost of error.
+2. **Scope and Constraints** — serving mode, latency, throughput, fallback.
+3. **Data and Feature Discovery** — Data Modeller consult; label definition; feature candidates.
+4. **Model Design** — baseline/candidates, evaluation strategy; optional cross-specialist review.
+5. **Infrastructure Design** — training pipeline, serving, monitoring, rollback.
+6. **Execute** — build feature queries, training notebook, `eval-results.json`.
+7. **Review and Handoff** — Backend Engineer code review, MLOps Engineer infrastructure review, Syn final review, model card, report.
+
+## Consultants
+
+- **Data Engineer** — Phase 2, Phase 5.
+- **Data Modeller** — Phase 3, Phase 5, Phase 6.
+- **Data Scientist** — Phase 4 when productionizing a study.
+- **Applied ML Scientist** — Phase 4 when non-standard methodology is needed.
+- **Deep Learning Engineer** — Phase 4 when a DL approach is warranted.
+- **Data Analyst** — Phase 4 when high interpretability is required.
+- **Researcher** — Phase 4 when statistical inference matters.
+- **Backend Engineer** — Phase 7 code review.
+- **MLOps Engineer** — Phase 7 serving/infrastructure review.
+- **Academic** — Phase 7 model card ethics review.
+- **Syn** — Phase 7 final review.
+
+## Output directory
+
+`models/<project_name>/` (greenfield) or the existing service directory (iteration).
+
+```
+models/<project>/
+├── project-specs.md
+├── queries/
+├── notebooks/
+├── eval-results.json
+├── model-card.json
+├── report.md
+└── bi_engineer_handoff.md   (optional)
+```
+
+## Entry points
+
+- Slash command: `/ml-engineer`
+- Skill: `ml-engineer`
+- Through Syn triage (`/shards`)
+
+## See also
+
+- [MLOps Engineer](mlops-engineer.md)
+- [Applied ML Scientist](applied-ml-scientist.md)
+- [Deep Learning Engineer](deep-learning-engineer.md)
+- [Autonomous Research](../03-protocols/autonomous-research.md)
+- Source: `src/agents/ml-engineer.md`

package/src/docs/02-agents/mlops-engineer.md

@@ -0,0 +1,59 @@
+# MLOps Engineer
+
+> Perpetually stressed. Cares about reliability, observability, and scalability.
+
+Specializes in deploying, monitoring, and maintaining ML systems in production. Handles model serving (BentoML, TorchServe, Triton), training pipeline orchestration (Kubeflow, Vertex AI Pipelines, SageMaker Pipelines, Airflow), model registries, feature stores, drift detection, and retraining automation. Deep expertise in AWS SageMaker and GCP Vertex AI.
+
+## Activation menu
+
+- `[T]` Triage — Greenfield, iteration, or model handoff?
+- `[B]` Build — Full operationalization workflow.
+- `[R]` Review — Evaluate an existing ML deployment or training pipeline.
+- `[ADV]` Advisory — Discuss MLOps design options.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Phases (Build) | `specific_instructions/mlops_engineer/phases/` | Full operationalization workflow — one file per phase, progressively loaded. |
+| Review | `specific_instructions/mlops_engineer/review.md` | Deployment review. |
+| Advisory | `specific_instructions/mlops_engineer/advise.md` | Advisor mode. |
+| Service Mode | `specific_instructions/mlops_engineer/service_mode.md` | Service consultation mode (invoked by ML Engineer or AI Engineer for deployment review). |
+
+## Phases
+
+1. **Requirements** — serving pattern (batch/real-time/streaming), SLOs, scale.
+2. **Platform Selection** — AWS/GCP/on-prem, model serving framework, orchestrator.
+3. **Serving Design** — endpoint contract, autoscaling, fallback, versioning.
+4. **Training Pipeline** — orchestration, data validation, retraining triggers.
+5. **Monitoring** — metrics, drift detection, alerting.
+6. **Build** — terraform/helm/config files, CI/CD.
+7. **Review** — Syn final review.
+
+## Consultants
+
+- **ML Engineer** — model architecture constraints and infrastructure design review.
+- **AI Engineer** — LLM-specific deployment requirements.
+- **Syn** — final review.
+
+## Consulted by
+
+- **ML Engineer** — Phase 7 serving/infrastructure review.
+- **AI Engineer** — Phase 7 deployment review.
+
+## Output directory
+
+`services/<project_name>/` — terraform, helm charts, pipeline configs, serving configs.
+
+## Entry points
+
+- Slash command: `/mlops-engineer`
+- Skill: `mlops-engineer`
+- Through Syn triage (`/shards`)
+- Via Task from ML Engineer or AI Engineer
+
+## See also
+
+- [ML Engineer](ml-engineer.md)
+- [AI Engineer](ai-engineer.md)
+- Source: `src/agents/mlops-engineer.md`

package/src/docs/02-agents/overview.md

@@ -0,0 +1,62 @@
+# Agent Taxonomy
+
+Shards ships 15 agents: one orchestrator (Syn), 12 specialists with phased workflows, and 2 review-only advisors.
+
+## By type
+
+| Type | Agents | Characteristics |
+|---|---|---|
+| **Orchestrator** | Syn | Triage, delegation, final review. No phased workflow of its own. |
+| **Specialist — analysis** | Data Analyst, Data Scientist | Produce analysis artifacts (SQL, notebooks, reports). |
+| **Specialist — data** | Data Engineer, Data Modeller, Analytics Engineer | Build pipelines, model entities, design transformation layers. |
+| **Specialist — ML/AI** | ML Engineer, AI Engineer, Applied ML Scientist, Deep Learning Engineer, MLOps Engineer | Design, build, and deploy ML and AI systems. |
+| **Specialist — visualization** | BI Engineer | Dashboards and data visualization. |
+| **Specialist — code** | Backend Engineer | Python code review and cleanup. |
+| **Review-only** | Researcher, Academic | Consulted by other specialists; no projects of their own. |
+
+## By "quick vs. deep"
+
+Some specialists support two tracks:
+
+- **Quick Track** — 2-3 phases for tactical work (a bug fix, a single query, a mart iteration).
+- **Deep Track** — 6-8 phases for greenfield or multi-week projects.
+
+Quick/Deep agents: Data Engineer, Data Modeller, Analytics Engineer.
+
+The Data Analyst is quick-only by design (escalates to Data Scientist for deep work).
+
+## Picking the right shard
+
+| If you want to... | Use |
+|---|---|
+| Answer a quick business question with SQL | [Data Analyst](data-analyst.md) |
+| Investigate causally, model, or build a study | [Data Scientist](data-scientist.md) |
+| Build a production ranking/classification model | [ML Engineer](ml-engineer.md) |
+| Build an LLM, RAG, or agent system | [AI Engineer](ai-engineer.md) |
+| Design or debug a neural architecture | [Deep Learning Engineer](deep-learning-engineer.md) |
+| Propose a novel ML method | [Applied ML Scientist](applied-ml-scientist.md) |
+| Deploy/monitor/retrain a model | [MLOps Engineer](mlops-engineer.md) |
+| Build a data pipeline or dbt model | [Data Engineer](data-engineer.md) |
+| Design a schema or resolve grain issues | [Data Modeller](data-modeller.md) |
+| Build a mart or transformation layer | [Analytics Engineer](analytics-engineer.md) |
+| Build a dashboard | [BI Engineer](bi-engineer.md) |
+| Review Python code for quality | [Backend Engineer](backend-engineer.md) |
+| Validate statistical methodology | [Researcher](researcher.md) |
+| Assess safety, ethics, or behavioral efficacy | [Academic](academic.md) |
+| Not sure? | [Syn](syn.md) — run `/shards` and it'll triage |
+
+## How shards talk to each other
+
+Shards consult each other via the Claude Code **Task tool** at defined points in their phased workflows. Common patterns:
+
+- The Data Scientist consults the **Researcher** for statistical methodology review.
+- The ML Engineer consults the **Data Modeller** for feature source understanding.
+- The AI Engineer consults the **Academic** for safety and ethics assessment.
+- Every specialist's final phase invokes **Syn** for sign-off.
+
+Consultations happen in-phase and do not transfer context permanently — the consulted shard returns a verdict and exits.
+
+## See also
+
+- One page per agent in this section (see left sidebar).
+- [Example Workflows](../07-workflows/quick-analysis.md) — real projects showing how shards chain together.

package/src/docs/02-agents/researcher.md

@@ -0,0 +1,73 @@
+# Researcher
+
+> Nerdy. Asks hard questions about assumptions and validity.
+
+Specializes in reviewing statistical methodology, distribution assumptions, outlier detection, and analytical rigor. A consultative agent — does not produce project files or documentation, with a single narrowly-scoped exception: the `[CR]` Critical Review mode lets the user opt into a written review file.
+
+## Activation menu
+
+- `[R]` Review — Review an analysis plan or methodology.
+- `[D]` Distributions — Help assess what distribution your data follows.
+- `[O]` Outliers — Advise on outlier detection and handling.
+- `[A]` Assumptions — Check statistical assumptions for a method.
+- `[S]` Sample Size — Power analysis and sample adequacy.
+- `[M]` Method Pick — Help choose the right statistical method.
+- `[E]` Explain — Explain a statistical concept in plain language.
+- `[CR]` Critical Review — Critically audit a written report for accuracy, thoroughness, fairness.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Service Mode | `specific_instructions/researcher/service_mode.md` | Service consultation mode invoked by other specialists for methodology review. Includes a `SERVICE MODE — REPORT REVIEW` branch for Task-based dispatch of `[CR]` critiques. |
+| Review Checklist | `specific_instructions/researcher/review_checklist.md` | Review checklist by problem type. Includes Report-Specific Checks for `[CR]` mode. |
+| Critical Review | `specific_instructions/researcher/critical_review.md` | Audit a finished `.md` report against three lenses: Accuracy, Thoroughness, Fairness (5-phase workflow). |
+
+## Phases
+
+Most modes are service-only. When invoked, the Researcher returns a verdict:
+
+- `SOUND` — Methodology is appropriate.
+- `CONSIDER ALTERNATIVES` — Valid but alternatives might serve better.
+- `REVISE` — Methodological issues that must be addressed.
+
+### Phases (Critical Review mode)
+
+The `[CR]` mode points the Researcher at a finished `.md` report (study writeup, analysis, A/B test report, model evaluation report) and produces a structured critique against three lenses:
+
+- **Accuracy** — methods appropriate to the data and question; reported quantities follow from the methodology used.
+- **Thoroughness** — assumption checks, sensitivity analyses, multiple-testing correction, uncertainty reporting.
+- **Fairness** — statistical vs. practical significance; causal language vs. correlational design; proportional acknowledgement of limitations.
+
+1. **Scope (GATE)** — report path, lens, referenced artifacts to spot-read, output preference (inline-in-chat or file), output dir override.
+2. **Read & Extract Methodological Claims** — inventory methodology, sample, assumptions, outlier handling, reported quantities, and interpretive language.
+3. **Apply Statistical Checklist** — every section of `review_checklist.md`, including the Report-Specific Checks.
+4. **Three-Lens Critical Assessment** — Accuracy / Thoroughness / Fairness; severity-tag each finding.
+5. **Deliver Review (GATE)** — inline or file (default location: same directory as the reviewed report).
+
+Also exposed as `SERVICE MODE — REPORT REVIEW` for Task-based dispatch from Syn or other specialists (always inline, no file write).
+
+## Consulted by
+
+- **Data Analyst** — Phase 2 methodology review.
+- **Data Scientist** — Phase 3 and Phase 6 methodology / build review.
+- **ML Engineer** — Phase 4 when statistical inference matters.
+- **AI Engineer** — Phase 4 and Phase 7 evaluation framework review.
+- **Applied ML Scientist** — methodology review.
+- **Deep Learning Engineer** — statistical evaluation of benchmark results.
+
+## Output directory
+
+- **All modes except `[CR]`** — none. The Researcher produces conversational findings, not files.
+- **`[CR]` Critical Review (file output, opt-in only)** — same directory as the reviewed report, named `researcher-critical-review-of-<report-slug>.md` (user can override during Phase 1). This is the single exception to the "review, don't produce" invariant; the user must explicitly opt into a file in Phase 1, otherwise output stays inline.
+
+## Entry points
+
+- Slash command: `/researcher`
+- Skill: `researcher`
+- Via Task from other specialists
+
+## See also
+
+- [Reviewer Verdicts](../03-protocols/reviewer-verdicts.md)
+- Source: `src/agents/researcher.md`

package/src/docs/02-agents/syn.md

@@ -0,0 +1,88 @@
+# Syn — Orchestrator
+
+> Friendly, structured. The entry point to everything.
+
+Syn is the orchestrator of the Shards suite. Its job is to triage incoming requests, decide which specialist should handle the work, initialize the project directory and `project-specs.md`, and hand off. Syn also serves as the universal final reviewer — every specialist invokes Syn for sign-off before execution.
+
+## Activation menu
+
+- `[T]` **Triage** — Tell me what you need and I'll figure out who handles it.
+- `[F]` **Fix** — Quick fix or minor update on something that exists. Syn applies the fix directly, suspending the "facilitate don't generate" rule.
+- `[P]` **Project** — Multi-specialist project. Syn plans, coordinates, and reviews the whole thing.
+- `[S]` **Status** — Check on a current project.
+- `[R]` **Review** — Review a specialist's plan before execution.
+- `[B]` **Brainstorm** — Bring a problem (or nothing) and let the shards ideate.
+- `[D]` **Diff** — Compare two projects side by side.
+- `[K]` **Knowledge** — Seed, browse, or manage the Knowledge Ledger.
+- `[G]` **GitHub PR** — Walk through PR review comments and apply fixes with approval.
+- `[NW]` **Notebook** — Live cell-by-cell walkthrough of a Jupyter notebook (run, explain, ask, edit).
+- `[PR]` **Panel Review** — Convene a panel of specialists to review a directory, coalesce findings, and plan sequenced fixes.
+- `[SL]` **Slides** — Build a Google Slides deck with specialist gut-checks at outline + post-build.
+- `[FF]` **Free Form** — General assistant mode: chat or work directly, spawning shards or any installed agents/skills as subagents.
+
+## Modes
+
+Syn's mode files live at `.claude/agents/specific_instructions/syn/`:
+
+| Mode | File | Purpose |
+|---|---|---|
+| Brainstorm | `brainstorm.md` | Multi-agent ideation with parallel specialist fan-out. Pushes a live UI panel via `brainstorm/brainstorm_<project>.state.json`. Also has the `/brainstorm` command entry point. |
+| Fixer | `fixer.md` | `[F]` Direct fix mode. Syn implements minor fixes without specialist handoff. |
+| PM | `pm.md` | `[P]` Project Manager. Orchestrates a multi-specialist project from a `project-plan.md`; workstreams run via Task. |
+| Free Form | `free_form.md` | `[FF]` General assistant mode: no phases or gates, direct work plus spawning shards or any installed agents/skills as subagents. |
+| Panel Review | `panel_review.md` | `[PR]` Multi-specialist review of any directory, coalesced into a prioritized report + sequencing plan. |
+| Slides | `slides.md` | `[SL]` Google Slides deck drafting (via MCP) with specialist polls at outline + post-build. |
+| Notebook Walkthrough | `notebook_walkthrough.md` | `[NW]` Live cell-by-cell notebook walkthrough via the `notebook-kernel.py` helper. |
+| Code Review | `code_review.md` | Triggered when a specialist calls Task with `CODE REVIEW MODE`. Partitions Python vs. non-Python and dispatches to Backend Engineer / Analytics Engineer. |
+| Final Review | `final_review.md` | Read when specialists invoke Syn for sign-off. Returns `APPROVED` / `NEEDS REVISION` / `BLOCKED`. |
+| Arbiter | `arbiter.md` | Time-Travel branch comparison. Reads all branch reports, builds leaderboard, recommends a winner. |
+| Diff | `diff.md` | `[D]` Cross-project comparison. Produces structured diff report. |
+| Knowledge | `knowledge.md` | `[K]` and `/knowledge` command. Seed, browse, and manage the Knowledge Ledger. |
+| PR Review | `pr_review.md` | `[G]` and `/review-pr` command. Walks through GitHub PR comments with guided fixes. |
+
+**Swarm protocol.** For genuinely large tasks, Syn defaults to **decompose-and-
+swarm**: split the work into bounded slices and run multiple same-type
+subagents in parallel, then merge the results. See
+[Decompose & Swarm](../03-protocols/swarm.md) and
+`specific_instructions/shared/swarm_protocol.md`. Applies in PM Mode, Free
+Form, and general orchestration; small work stays on a single agent.
+
+## Phases
+
+Syn does not have phases of its own. It runs a **Phase 0 Triage** that selects a specialist, creates the project directory and `project-specs.md` scaffold, then performs an **in-session persona transfer** (Syn becomes the specialist). All subsequent phases belong to that specialist.
+
+## Consulted by
+
+Every specialist invokes Syn for final review via Task. Syn returns a three-tier verdict — see [Reviewer Verdicts](../03-protocols/reviewer-verdicts.md).
+
+## Output directory
+
+Syn doesn't have a dedicated output directory. It writes to:
+
+- `brainstorm/` for brainstorm sessions.
+- `fixes/` for the Fixer mode.
+- `projects/` for PM Mode (`project-plan.md` + `workstreams.json`).
+- `presentations/<deck_slug>/` for Slides mode.
+- `panels/<dirname>/` for Panel Review.
+- `.shards/branches/` for DIVERGE branches.
+- The target project directory when acting as final reviewer.
+- Free Form writes where the user asks (no default). Swarmed workstreams nest
+  slices under the specialist's own convention (e.g. `studies/<name>/slice-<n>/`).
+
+## Entry points
+
+| From | How |
+|---|---|
+| Slash command | `/shards` |
+| Brainstorm | `/brainstorm` |
+| Knowledge Ledger | `/knowledge` |
+| PR review | `/review-pr` |
+| UI | Any agent card labeled "Syn" in the agent picker |
+
+## See also
+
+- [The Gate Pattern](../03-protocols/gate-pattern.md)
+- [Reviewer Verdicts](../03-protocols/reviewer-verdicts.md)
+- [DIVERGE](../03-protocols/diverge.md) — Syn Arbiter mode
+- [Decompose & Swarm](../03-protocols/swarm.md) — parallel slices for large work
+- Source: `src/agents/syn.md`

package/src/docs/03-protocols/auto-verify.md

@@ -0,0 +1,82 @@
+# Auto-Verify Mode
+
+A scope-bounded auto-approval mechanism for the bulk read-only verification work that specialists do at predictable points in their phases. Brackets a stretch of safe, repetitive tool calls inside a marker pair so the gate hook auto-approves them — without weakening gates, deny rules, or the user's ability to halt.
+
+Referenced by Data Modeller, Analytics Engineer, Data Engineer, Data Analyst, ML Engineer (consultation side), Data Scientist (consultation side), and the join-path protocol.
+
+## The problem it solves
+
+Specialists run the same shape of read-only query over and over during validation:
+
+- Per-model grain checks (`count(*) vs count(distinct pk)`)
+- Join fan-out (count before / count after) at every join
+- PK/FK null checks per column
+- Sample inspections (`dbt show --select <model> --limit 5`)
+- Freshness checks per upstream table
+- Read-only dbt subcommands (`dbt show`, `dbt ls`, `dbt parse`, `dbt compile`)
+
+Each one fires its own permission prompt. A typical Data Modeller post-build sweep across five models with joins issues 15–25 prompts, all near-identical SELECTs. Users click "always allow" on the first one and lose the ability to spot the one prompt that actually matters; or they get tired of clicking and disengage.
+
+Auto-verify gives specialists a way to bracket those stretches with a marker pair. While the block is open, the gate hook auto-approves tool calls that match a hardcoded read-only allowlist. Everything outside the allowlist still prompts. Phase and checkpoint gates always win.
+
+## The marker pair
+
+Open at the start of the verification stretch:
+
+```
+::AUTO-VERIFY:: agent=<your-name> phase=<N> tool_budget=<N> ttl_minutes=<N>
+```
+
+Close at the end:
+
+```
+::ENDAUTO::
+```
+
+`agent` and `phase` are required (used in the audit log). `tool_budget` defaults to 20 and is clamped to 50; `ttl_minutes` defaults to 10 and is clamped to 30. Both bound how much can happen inside one block.
+
+## What gets auto-approved
+
+| Category | Examples |
+|---|---|
+| Always-safe tools | `Read`, `Glob`, `Grep`, `WebSearch` |
+| Read-only Bash prefixes | `git status`, `git log`, `git diff`, `ls`, `cat`, `head`, `tail`, `wc`, `pip list`, `npm ls` |
+| Read-only dbt subcommands | `dbt show`, `dbt ls`, `dbt list`, `dbt parse`, `dbt compile`, `dbt deps`, `dbt debug`, `dbt source freshness` |
+| Read-only BigQuery CLI | `bq show`, `bq ls`, `bq head`, `bq query --dry_run` |
+| SELECT-only warehouse-CLI SQL | `bq query "SELECT …"`, `psql -c "SELECT …"`, `snowsql -q "SELECT …"`, `clickhouse-client --query "SELECT …"`, `duckdb -c "SELECT …"`, `mysql -e "SELECT …"` |
+
+The SQL guard parses the SQL string, strips comments, splits on `;`, and approves only if every statement starts with `SELECT` or `WITH` and contains no DDL/DML keyword (INSERT, UPDATE, DELETE, MERGE, CREATE, DROP, ALTER, TRUNCATE, GRANT, REVOKE, COPY, etc.). Comment-smuggled DDL is rejected.
+
+## What never gets auto-approved
+
+`Write`, `Edit`, `NotebookEdit`. `dbt run`, `dbt build`, `dbt seed`, `dbt snapshot` (writes — even with `--select`). `git push`, `git commit`. `INSERT`/`UPDATE`/`DELETE`/`MERGE` via warehouse CLI. Compound shell commands joined with `&&`/`||`/`;`/`|`. Commands with shell redirects (`>`, `>>`), command substitution (`$(...)`, backticks), or pipe-to-shell (`| sh`). MCP tools. Anything matching the user's `permissions.deny[]` list (Claude Code enforces that ahead of the hook).
+
+If a tool call falls outside the allowlist, the prompt fires normally. The block stays open — a single prompt is not a signal to abandon it.
+
+## How a block closes
+
+1. The agent emits `::ENDAUTO::` in a later message
+2. The tool budget hits zero (every auto-approval decrements it)
+3. The TTL elapses
+4. The user submits a prompt containing "stop", "halt", "pause", "cancel", "abort", "wait", "hold on", "no thanks", "nope", or "don't"
+5. A real `::GATE::` opens — gates always win and suspend auto-verify
+
+## How it composes with gates
+
+Gates are unaffected by auto-verify. When a `kind=phase` or `kind=checkpoint` gate is open, the gate's allowlist (`Read`/`Glob`/`Grep`) takes over. Auto-verify state may still exist but it is suspended — no auto-approvals fire while a gate is open. After the gate closes, auto-verify resumes if its own budget/TTL haven't been exhausted (in practice, agents tend to `::ENDAUTO::` before emitting a phase gate).
+
+## Audit trail
+
+Every auto-approval is logged to `.shards/auto/history.jsonl` with timestamp, agent, phase, tool, command, and remaining budget. `tail -f` it during a session to see exactly what's being approved. The log is append-only and never auto-rotated by shards.
+
+## Escape hatch
+
+`SHARDS_AUTO_VERIFY=0` disables the auto-verify branch entirely. Markers are still parsed (so they don't appear as raw text) but no state is written and no tool calls are auto-approved.
+
+`SHARDS_GATE_ENFORCE=0` continues to disable all gate enforcement, which also disables auto-verify (auto-verify lives inside the same hook).
+
+## What this is not
+
+- Not `--dangerously-skip-permissions`. The allowlist is hardcoded; the budget is bounded; the user can halt with one word.
+- Not a replacement for the gate pattern. Gates always win.
+- Not Claude Code's native `auto` mode (which is a separate Anthropic-side feature with its own gating and falls back to manual after classifier blocks). Auto-verify is hook-driven and works orthogonally to the user's selected permission mode.

package/src/docs/03-protocols/autonomous-research.md

@@ -0,0 +1,59 @@
+# Autonomous Research (AR)
+
+A budget-bounded, self-steering research loop. The specialist proposes a change, evaluates it against a metric, auto-keeps or auto-reverts based on the result, and continues until the budget is exhausted or the metric converges.
+
+Available on: Data Scientist, ML Engineer, AI Engineer, Applied ML Scientist, Deep Learning Engineer. Activated via `[AR]` on each agent's menu.
+
+## The core loop
+
+1. **Setup** — user defines the metric, the budget (iterations or wall clock), and the starting point.
+2. **Hypothesis** — the specialist adapts a hypothesis based on prior iterations and the steering document.
+3. **Implement** — small, reversible change to the current candidate.
+4. **Evaluate** — run the eval, record the metric.
+5. **Auto-keep / auto-revert** — if the metric improved, keep the change; if not, revert.
+6. **Log** — append to `history.jsonl` and `results.json`.
+7. **Check** — budget exhausted? Converged? Steering document updated? If not, go back to step 2.
+
+## Key artifacts
+
+| File | Purpose |
+|---|---|
+| `research_brief.md` | The steering document. The user can edit it mid-loop; the specialist reads it each iteration. |
+| `history.jsonl` | Iteration-by-iteration log: hypothesis, change, metric, decision. |
+| `results.json` | Summary state — best candidate so far, convergence estimate, budget remaining. |
+| `report.md` | Phase 3 research summary written after the loop exits. |
+
+## Steering mid-loop
+
+The user can edit `.shards/research_brief.md` while the loop is running. The next iteration reads the updated brief and adjusts hypothesis generation accordingly. This is Shards' answer to "I want to let it run but keep a hand on the wheel."
+
+## Dual reviewer cadence
+
+The AR loop invokes two review cadences:
+
+- **Every iteration** — the specialist's own self-assessment (metric direction, cost).
+- **Periodic** — a reviewer (Researcher, ML Engineer, etc.) reviews convergence evidence and methodology. Cadence varies per agent.
+
+## Convergence detection
+
+The loop auto-stops if:
+
+- Budget exhausted.
+- Metric has plateaued for N iterations.
+- Specialist has produced N consecutive auto-reverts.
+- User explicitly pauses via the steering document.
+
+## AR fan-out (DIVERGE composition)
+
+Section H of the protocol covers AR fan-out: multiple parallel approach families, each running its own AR loop. Used when the approach space itself is unclear — each DIVERGE branch runs AR, and Syn Arbiter compares the best candidates across branches at the end.
+
+## UI integration
+
+On Tier-1 agents (ML/AI/DS), AR mode pushes structured output to the UI's `experiment-dashboard` panel. The renderer detects `mode: "autonomous-research"` in `results.json` and renders AR enrichments: auto-decision color coding, cost strip, convergence badge.
+
+## See also
+
+- [DIVERGE](diverge.md)
+- [Experiment Versioning](experiment-versioning.md)
+- [UI Panels](../04-ui/panels.md) — experiment-dashboard
+- Source: `src/agents/specific_instructions/shared/autonomous_research.md`

package/src/docs/03-protocols/behavioral-rules.md

@@ -0,0 +1,35 @@
+# Behavioral Rules
+
+Four cross-cutting rules every specialist must follow. Codified in `src/agents/specific_instructions/shared/behavioral_rules.md` and referenced from each agent's Behavioral Rules section.
+
+## 1. Document before advancing
+
+No phase ends until its decisions are written to `project-specs.md` inside a `::GATE:: ... ::ENDGATE::` fence. See [The Gate Pattern](gate-pattern.md).
+
+## 2. One phase at a time
+
+Specialists advance one phase at a time and wait for your confirmation. They don't batch phases, even when the next phase is obvious. This keeps alignment tight and gives you cheap redirection points.
+
+## 3. Announce cross-agent reviews
+
+When a specialist invokes another specialist via Task (Researcher, Data Modeller, Backend Engineer, etc.), it announces the consultation to you before making the call. You see: who is being consulted, why, and what they'll return. You can veto.
+
+## 4. Facilitate, don't generate
+
+Specialists facilitate decisions — they ask, propose, and document — but they don't silently generate artifacts. Code, queries, reports are only written after the gate is closed.
+
+**Exceptions:** Several Syn-native modes suspend this rule for scoped reasons:
+- **`[F]` Fixer** — direct edit with no facilitation loop.
+- **`[G]` PR Review** — Syn applies fixes directly during PR walkthrough.
+- **`[NW]` Notebook Walkthrough** — Syn explains and executes cells.
+- **`[SL]` Slides** — no specialist owns presentations; Syn drafts the outline and slide bodies and calls the Google Slides MCP directly. Polls specialists at two checkpoints (outline pre-build, post-build fidelity) for content gut-checks.
+
+## Why this matters
+
+These rules are the reason Shards projects produce auditable decision trails. Without them, agents would silently produce code you never agreed to, consult reviewers without your knowledge, and skip the documentation that makes the work auditable later.
+
+## See also
+
+- [The Gate Pattern](gate-pattern.md)
+- [Reviewer Verdicts](reviewer-verdicts.md)
+- Source: `src/agents/specific_instructions/shared/behavioral_rules.md`

package/src/docs/03-protocols/diverge.md

@@ -0,0 +1,50 @@
+# DIVERGE — Time-Travel Branches
+
+When 2-3 viable approaches exist in a planning phase, you can fork the project into parallel branches, execute them simultaneously, compare results, and promote the winner. This is Shards' answer to "I can't decide which approach will work best — let's just try all of them."
+
+## When to use it
+
+Good DIVERGE candidates:
+
+- Multiple model architectures worth comparing (tree-based vs. gradient boosting vs. neural).
+- Multiple prompt strategies (few-shot vs. chain-of-thought vs. tool use).
+- Multiple join strategies for a query.
+- Multiple transformation-layer designs.
+
+Poor DIVERGE candidates:
+
+- There's a clear right answer, you just haven't asked.
+- The approaches differ in code structure, not outcomes.
+- You only have budget for one attempt.
+
+## Lifecycle
+
+1. **Propose** — a specialist identifies 2-3 viable approaches during a planning phase and proposes DIVERGE. It names the branches, the success metric, and the budget per branch.
+2. **Confirm** — you approve or veto.
+3. **Fork** — each branch spawns as an autonomous Task. Each branch gets its own directory under `.shards/branches/<branch-slug>/`.
+4. **Execute** — branches run independently. They share the same `project-specs.md` scaffold up to the fork point, then diverge.
+5. **Report** — each branch produces a `branch-report.md` with its result and self-assessment.
+6. **Converge** — Syn Arbiter reads all branch reports, builds a side-by-side leaderboard with metrics and trade-offs, and returns an **advisory recommendation**. You make the final decision.
+7. **Promote** — the winning branch is promoted back to the main project directory.
+
+## Branch report template
+
+Each branch produces `branch-report.md` with:
+
+- Branch name and approach description.
+- Metric results (comparable across branches).
+- What worked / what didn't / what surprised the specialist.
+- Self-assessed trade-offs.
+
+Template: `src/templates/branch-report.md`.
+
+## Syn Arbiter mode
+
+When all branches complete, Syn enters Arbiter mode (`src/agents/specific_instructions/syn/arbiter.md`). It reads every `branch-report.md`, builds a leaderboard table, and produces an advisory recommendation. **The user makes the final decision.**
+
+## See also
+
+- [Autonomous Research](autonomous-research.md) — DIVERGE composes with AR (Section H: "AR fan-out").
+- [Example: DIVERGE Exploration](../07-workflows/diverge-exploration.md)
+- Source: `src/agents/specific_instructions/shared/diverge_protocol.md`
+- Source: `src/agents/specific_instructions/syn/arbiter.md`

package/src/docs/03-protocols/engineering-guidelines.md

@@ -0,0 +1,56 @@
+# Engineering Guidelines
+
+Code-craft rules every specialist applies whenever it writes or edits a durable artifact — code, SQL, notebooks, dbt models, configuration, pipelines, dashboard code. Codified in `src/agents/specific_instructions/shared/engineering_guidelines.md` and referenced from each specialist's Behavioral Rules section alongside [`behavioral_rules.md`](behavioral-rules.md).
+
+Where `behavioral_rules.md` governs *workflow discipline* (gates, phasing, escalation), this file governs *code craft* — how to produce the artifact once you're inside an execute or build phase.
+
+## 1. Think Before Coding
+
+State assumptions explicitly. Present alternative interpretations rather than picking silently. Push back when a simpler approach exists. Stop and ask when something is genuinely unclear.
+
+This extends the gate pattern from project-level decisions to line-level ones: if a build choice is contentious or opaque enough to need your input, the specialist raises it in chat before writing it, not after.
+
+## 2. Simplicity First
+
+Minimum code that solves the problem. No features, abstractions, configurability, or error handling beyond what was asked. If a 200-line implementation could be 50, rewrite it.
+
+Domain extensions:
+
+- **SQL:** no CTEs that go unreferenced, no joins that don't tighten the result, no `DISTINCT` slapped on to hide a join-path bug.
+- **Notebooks:** no exploratory cells left in a "final" notebook, no `try/except` swallowing errors that should surface.
+- **Pipelines / dbt:** no models that wrap a single `SELECT *`, no configuration knobs nobody will turn, no incremental strategies on tables small enough to refresh fully.
+- **Services:** no fallback paths for branches the surrounding code makes unreachable.
+
+## 3. Surgical Changes
+
+Touch only what the request requires. Match existing style. Don't refactor adjacent code that isn't broken. Clean up orphans the change itself created — not pre-existing dead code.
+
+The test: every changed line should trace directly to the request.
+
+Especially relevant in iteration mode (ML / AI / AE), Fixer mode, Panel Review, and any phase that edits an existing artifact. Iteration's defining failure mode is the agent that "just cleans up while it's in there." When the specialist notices unrelated issues, it logs them under `Open Issues` in `project-specs.md` (or raises them in chat for review-only flows) rather than silently fixing.
+
+## 4. Goal-Driven Execution
+
+Define verifiable success criteria *before* writing code. Transform vague tasks ("make it work") into testable goals ("write a failing test, then make it pass"). State a brief verification plan for multi-step tasks.
+
+This rule composes with two related protocols:
+
+- [Validation Protocol](validation.md) — the gate-level expression. Evidence over assertion before closing any artifact-producing phase.
+- [Incremental Testing](incremental-testing.md) — the build-loop expression. Test each component as you write it; don't batch failures to the end.
+
+Engineering guidelines cover the gap between them: at the individual-task level, the verification check is named *first*, not last.
+
+## Tradeoff
+
+These guidelines bias toward caution over speed. For trivial edits — typos, one-line config tweaks, label changes — specialists use judgment rather than ceremony.
+
+## When workflow and code-craft rules conflict
+
+Workflow rules dominate. A specialist never violates a gate, skips facilitation, or bypasses validation in order to satisfy a code-craft preference.
+
+## See also
+
+- [Behavioral Rules](behavioral-rules.md)
+- [Validation Protocol](validation.md)
+- [Incremental Testing](incremental-testing.md)
+- Source: `src/agents/specific_instructions/shared/engineering_guidelines.md`