@proflandrigan/shards 1.1.0

package/src/agents/specific_instructions/shared/reviewer_verdict_protocol.md

@@ -0,0 +1,74 @@
+---
+name: reviewer-verdict-protocol
+description: Universal three-tier reviewer verdict mapping and escalation script for specialist agents
+type: reference
+---
+
+When a consulted reviewer returns a verdict, map it to one of three universal tiers and act accordingly:
+
+| Tier | Reviewer verdicts that map here | Action |
+|------|---------------------------------|--------|
+| **Proceed** | Sound · Approved · Aligned | Document verdict in specs. Continue. |
+| **Proceed with caveats** | Concerns · Consider Alternatives | Document the concern verbatim in specs. Tell the user what was flagged. Gate: "Reviewer noted: [X] — documented in specs. Confirm to continue?" Proceed on user confirmation. |
+| **Halt and fix** | Revise | Halt. Document the issue in specs. Fix it. Resubmit to the same reviewer ONCE. If still Halt on resubmission, escalate. |
+
+## Reviewer Vocabulary
+
+Each reviewer agent returns verdicts in a fixed vocabulary. The table below lists the canonical verdicts per reviewer and their tier mapping. Specialists consulting a reviewer do not need to restate this vocabulary in their phase instructions — they only need to invoke this protocol.
+
+| Reviewer (subagent_type) | Verdict vocabulary | Tier mapping |
+|--------------------------|--------------------|--------------|
+| `researcher` | Sound / Consider Alternatives / Revise | Sound → Proceed · Consider Alternatives → Proceed with caveats · Revise → Halt and fix |
+| `applied-ml-scientist` | Sound / Consider Alternatives / Revise | same as above |
+| `data-modeller` (service mode) | Sound / Concerns / Revise | Sound → Proceed · Concerns → Proceed with caveats · Revise → Halt and fix |
+| `analytics-engineer` (service mode) | Sound / Concerns / Revise | same as above |
+| `backend-engineer` (service mode) | Sound / Concerns / Revise | same as above |
+| `data-analyst` (reviewer role) | Aligned / Concerns raised | Aligned → Proceed · Concerns raised → Proceed with caveats |
+| `data-engineer` (reviewer role) | Sound / Concerns | Sound → Proceed · Concerns → Proceed with caveats |
+| `bi-engineer` (reviewer role) | Suitable / Concerns / Redesign | Suitable → Proceed · Concerns → Proceed with caveats · Redesign → Halt and fix |
+| `deep-learning-engineer` (reviewer role) | Approved / Concerns / Redesign needed | Approved → Proceed · Concerns → Proceed with caveats · Redesign needed → Halt and fix |
+| `mlops-engineer` (reviewer role) | Approved / Concerns / Redesign needed | same as above |
+| `ml-engineer` (reviewer role) | DEPLOY / OPTIMIZE / REDESIGN | DEPLOY → Proceed · OPTIMIZE → Proceed with caveats · REDESIGN → Halt and fix |
+| `academic` | Clear / Nuanced / Concerns | Clear → Proceed · Nuanced → Proceed with caveats · Concerns → Halt and fix |
+
+If a reviewer returns a verdict not listed here, record it verbatim and default to the tier that most closely matches the semantic meaning (ask the user if ambiguous).
+
+**Escalation script (use verbatim when a second Halt verdict is returned):**
+> "[Reviewer] has flagged a concern twice. Here is the conflict:
+> - Reviewer's concern: [verbatim from second review]
+> - Current plan: [one-sentence summary of what exists]
+>
+> How would you like to proceed?
+> (a) Revise further — tell me what to change.
+> (b) Override and proceed — I'll document the disagreement in specs.
+> (c) Stop the project."
+
+Document the resolution in specs:
+`**Reviewer resolution:** Approved | Approved on resubmit | User override — <rationale> | Project stopped`
+
+**Resubmission cap:** Never resubmit to the same reviewer more than once per phase. After one resubmission, the path is always user escalation — never another Task call.
+
+**Multi-reviewer arbitration:** When two reviewers in the same phase return conflicting tier verdicts, do not resolve unilaterally. Present both verdicts verbatim to the user with a one-sentence summary of the conflict. Ask which direction to take before making any changes. Document the user's decision in specs.
+
+## Final Review (Syn Sign-Off) — Validation Section Check
+
+When a specialist invokes Syn via `Task(subagent_type="syn", ...)` for final sign-off on a validation-eligible phase, Syn's review must explicitly inspect the `## Validation` section in `project-specs.md` per `shared/validation_protocol.md`. This is distinct from the gate hook's structural check — Syn performs the *semantic* check the hook cannot.
+
+Syn's validation review looks for:
+
+- **Evidence, not assertion.** Does every check row record a measured value, or is the Observed cell filled with prose that could be true of a broken implementation?
+- **Coverage matching Track / Mode.** Did the specialist run the checks its declared `(Track, Mode)` requires, or did it skip checks with `n/a` without real justification?
+- **Downstream impact honest.** Is "verified intact" supported by an actual check, or is it a claim?
+- **Open Issues not hiding failures.** Unresolved `✗` rows and unacceptable residual risks should be surfaced, not quietly deprioritized.
+- **Summary matches evidence.** Does the Summary paragraph describe what actually happened, or does it paper over failed checks?
+
+Syn's verdict mapping:
+
+| Validation state | Verdict |
+|------------------|---------|
+| Section populated, evidence is real, coverage appropriate, risks surfaced | APPROVED |
+| Section populated but evidence is thin on 1-2 checks, coverage mostly correct | NEEDS REVISION — specific checks called out |
+| Section missing checks from required list, or evidence is theater (assertions masquerading as measurements), or failed checks are hidden | NEEDS REVISION — point the specialist back to the protocol and checklist |
+| Section claims `n/a` on clearly applicable checks with vague justifications | NEEDS REVISION — demand the actual check or a real justification |
+
+A structurally-complete but semantically-empty Validation section is the most common failure mode. Syn is the last line of defense against it before a reviewer verdict is issued.

package/src/agents/specific_instructions/shared/swarm_protocol.md

@@ -0,0 +1,97 @@
+# Swarm Protocol — Decompose Large Work into Parallel Slices
+
+This protocol defines Syn's **default behavior for genuinely large tasks**:
+decompose the work into bounded, independently verifiable slices and run them
+as multiple same-type subagents in parallel, then merge the results. It applies
+whenever Syn orchestrates — PM Mode, Free Form, or general routing. It is the
+default, not an opt-in mode. Syn is never limited to one instance of an agent
+per project.
+
+## When to swarm
+
+Swarm when the task is genuinely large:
+
+- The task touches many files, modules, or independent components.
+- It contains several clearly separable sub-problems that can be worked in
+  parallel.
+- One subagent would be carrying far more work than a single spawned task
+  should.
+- The natural seams (data partitions, file sets, sub-questions, end-to-end
+  layers) allow slices to be worked independently.
+
+Do NOT swarm when the task is small:
+
+- A single SQL query, no matter how involved.
+- A one-file change, small fix, or trivial update.
+- Anything one agent completes cleanly in a single turn's work.
+- Work whose only splits would force the slices to write to the same paths and
+  collide.
+
+When in doubt, do not swarm. A single agent is the default; a swarm is a
+deliberate response to genuine scale.
+
+## Slice heuristics
+
+Each slice must be:
+
+- **Bounded** — one clearly-scoped sub-task, expressible in a short brief.
+- **Independently verifiable** — it has its own definition of done.
+- **Collision-free** — it writes to its own output paths (e.g.
+  `studies/<name>/slice-<n>/`), so parallel slices never overwrite each other.
+- **Mergeable** — its outputs can be read from disk and integrated by Syn.
+
+Slice names are short kebab-case slugs. If a slice is still too big after
+slicing, slice it again rather than letting any subagent grind on an oversized
+chunk.
+
+## Spawn mechanics
+
+Spawn all slices in a single parallel fan-out: one Task call per slice, all in
+the same message. The `subagent_type` repeats across the calls — that is
+expected and correct; same-type instances simply get different slice briefs.
+
+```
+Task(
+  subagent_type="<specialist>",
+  description="Slice: <slice-slug>",
+  prompt="""
+SWARM SLICE — You are one of N parallel same-type subagents executing a slice
+of a larger task that Syn orchestrated.
+
+**Slice:** <slice-slug>
+**Slice directory:** <path>
+**Scope:** <what this slice specifically builds or analyzes>
+**Inputs:** <what upstream slices or existing systems provide>
+**Outputs:** <what this slice must produce, and where on disk>
+**Definition of done:** <one sentence>
+
+Work autonomously. Do not wait for user gates. When a phase file would stop
+and emit a `::GATE::` fence waiting for user confirmation, do NOT stop and do
+NOT emit the fence — document your decision for the merge step and continue to
+the next phase. Skip your activation menu and Phase 0 — Syn has already scoped
+your work. Do not invoke Syn for review. Return a concise report: artifacts
+produced, key decisions, issues, confidence, and anything the merge step needs
+to know.
+  """
+)
+```
+
+## Review and merge
+
+- **Review each slice** as its Task returns, against the slice's definition of
+  done: APPROVED / NEEDS REVISION / BLOCKED. Send a slice back for revision
+  with specific feedback when needed (same cap as PM Mode revisions).
+- **Merge** after (some or all) slices pass: read each slice's artifacts from
+  disk, reconcile interfaces and outputs, write any glue, and produce the
+  workstream's single coherent deliverable. Record the merge in
+  `project-specs.md` or `project-plan.md` as appropriate.
+- **Re-slice** if you find a slice was mis-sized: split it further and spawn
+  again rather than letting one agent grind.
+
+## Cross-cutting rules
+
+- Announce swarming to the user: how many slices, which types, what paths.
+- Prefer parallel spawns — do not await one slice before dispatching the next.
+- Guard your own context: read slice outputs from disk, not from Task output.
+- Never degrade to a single massive workstream task when the work is large —
+  decompose is the default.

package/src/agents/specific_instructions/shared/validation_protocol.md

@@ -0,0 +1,139 @@
+---
+name: validation-protocol
+description: Shared validation contract — every specialist produces evidence of output correctness before closing build/execute phases
+type: reference
+---
+
+# Validation Protocol
+
+Validation is a universal contract across all specialist agents. Before closing any phase whose `kind` is `execute` or `phase` and whose work produces new or modified artifacts (marts, models, notebooks, services, datasets, pipelines, dashboards), the agent must produce **evidence** that the outputs are correct — not merely an assertion that they are.
+
+This protocol defines *what* validation means and *where* evidence lands. Each specialist has a domain-specific `validation_checklist.md` that defines *which* checks apply. A separate gate-hook extension enforces that the evidence is present before the gate closes.
+
+## The Contract
+
+Every validation-eligible phase produces three things:
+
+1. **A populated `## Validation` section in `project-specs.md`** — the bridge between soft protocol and hard enforcement.
+2. **At least one evidence artifact on disk** — a file the user or a reviewer can open to inspect the results. This includes test files (preferred where applicable), metric dumps, plots, config snapshots, model artifacts, or verification query outputs. Prose in specs is context, not evidence.
+3. **A named checklist version** — which agent checklist was applied, so coverage is auditable.
+
+If any of the three is missing, the gate does not close.
+
+## Evidence vs Assertion
+
+The protocol requires *outputs*, not *claims*. Numbers and file paths are harder to hallucinate than prose.
+
+| Evidence (accept) | Assertion (reject) |
+|-------------------|--------------------|
+| `rows_observed: 48,211 (source: 48,211)` | "Row counts look right" |
+| `pk_distinct == pk_total (verified)` | "Grain is correct" |
+| `tests/test_churn_model.py::test_probs_sum_to_one PASSED` | "Tested the probabilities" |
+| `category_counts: {A: 12.3k, B: 9.8k, C: 401}` | "Distributions look healthy" |
+| `downstream mart `fct_revenue` rebuilt OK` | "Shouldn't affect anything downstream" |
+
+When the observed value cannot be measured (e.g., a qualitative downstream check), name *what* was inspected and *who* confirmed, not just that it was "fine."
+
+## Specs Section Schema
+
+Render this section into `project-specs.md`. The gate hook parses it — schema drift will cause enforcement failures, so follow the format exactly.
+
+```markdown
+## Validation
+
+**Track:** quick | deep | fixer
+**Mode:** <agent-specific, e.g. greenfield | iteration | experiment | adhoc | build | ...>  ← optional
+**Checklist:** <agent_name>/validation_checklist.md
+**Applied at:** Phase <N> — <phase name>
+
+### Evidence
+
+| Check | Expected | Observed | Pass/Fail | Notes |
+|-------|----------|----------|-----------|-------|
+| <check-id from checklist> | <predicted value or condition> | <measured value> | ✓ / ✗ / n/a | <one-line context; required non-empty when Pass/Fail = n/a> |
+
+### Artifacts
+- `<path/to/evidence-file>` — <what it shows>
+
+### Downstream Impact
+- `<dependent-model-or-consumer>` — verified intact | not applicable | broken → fixed in <commit/file>
+
+### Open Issues
+- <issue the user should know about> | none
+
+### Summary
+<Two-to-four sentences: what was validated, what failed and was fixed, what residual risk remains. This is the "what do I tell my boss" paragraph.>
+```
+
+### Track vs Mode
+
+Two orthogonal fields describe a validation instance:
+
+- **Track** — depth indicator. Universal vocabulary: `quick | deep | fixer`. The hook validates this strictly. It controls which checks are required (via each checklist's Track Calibration table).
+- **Mode** — flavor of work. Agent-specific, free-form string. Optional — omit the line entirely if not meaningful for the agent. The hook does not validate Mode values; it exists for audit/telemetry and to help the agent pick the right Track Calibration row.
+
+Examples:
+- ML Engineer building a new recommender from scratch → `Track: deep`, `Mode: greenfield`
+- ML Engineer retuning an existing churn model → `Track: deep`, `Mode: iteration`
+- ML Engineer `[X]` experiment iteration that kept its change → `Track: quick`, `Mode: experiment`
+- Analytics Engineer shipping a new mart → `Track: deep` (Mode omitted or `build`)
+- Analytics Engineer adhoc refund-attribution tweak → `Track: quick`, `Mode: adhoc`
+- Any Fixer-mode fix (`[F]`) → `Track: fixer`
+
+### Pass/Fail Values
+
+- **✓** — check ran, result met the expected value or condition.
+- **✗** — check ran, result did not meet expectation. The failure must be resolved (record the fix in Notes or surface in Open Issues) before the gate closes.
+- **n/a** — the check is not applicable to this work (e.g., calibration on a non-probabilistic model; refresh-mode parity on a view). The Notes cell **must** contain a non-empty justification. The hook blocks `n/a` with an empty Notes cell.
+
+Unresolved checks ("I'm not sure if this passed") are not a valid Pass/Fail state. Mark them `✗` in the row and move the unresolved question to Open Issues — validation uncertainty is a project state, not an evidence state.
+
+### Multi-Instance Checks
+
+Some checks measure many things at once — feature distributions across dozens of features, model performance across many slices, row-count sanity across many columns. Rendering one evidence row per instance would crowd out the rest of the table.
+
+Pattern: **one summary row in the Evidence table + a full breakdown artifact linked from `### Artifacts`.**
+
+- The summary row's Observed cell captures the headline ("47/47 within tolerance | 2 flagged") and points to the artifact file.
+- The artifact (JSON, CSV, notebook cell output, plot) holds the per-instance detail.
+- If the check has both a universal component (does it pass?) and an instance breakdown (which ones failed?), the row answers the first and the artifact answers the second.
+
+This pattern is first-class — it satisfies the Contract's "evidence artifact on disk" requirement even for checks where the evidence is a data dump rather than a test file.
+
+## When the Protocol Applies
+
+| Track | Application | Checklist depth |
+|-------|-------------|-----------------|
+| **deep** | Dedicated Validate phase (preferred) or validation block inside the final execute phase. All required checks for the declared Mode. | Full checklist |
+| **quick** | Inline validation block inside the execute phase. | Checklist's Quick subset |
+| **fixer** | Minimal validation block — what changed, what didn't break, and any check the change could have regressed. | Checklist's Fixer subset |
+
+Mode selects *which row of the checklist's Track Calibration table* applies within the declared Track (e.g., `Track: deep`, `Mode: iteration` for ML uses the Iteration row's required-checks list, which differs from Greenfield's).
+
+**Not validation-eligible:**
+- Review / Advise / Explain / Update modes — no new artifacts produced.
+- Review-only agents (Researcher, Academic) — no artifacts produced.
+- Planning / exploration phases that produce only specs or research notes.
+
+**A phase is validation-eligible** if it writes, modifies, or regenerates a durable artifact that downstream consumers depend on.
+
+## Composition with Other Protocols
+
+- **Gate pattern:** The Validate step sits before the gate fence. Write the `## Validation` section → re-read it to the user → emit the gate fence. Same discipline as every other phase.
+- **Join path protocol:** Join-path issues found during validation are recorded under **Notes** in the evidence table and, if unresolved, escalated to **Open Issues**.
+- **Knowledge retrieval:** If the Knowledge Ledger has a relevant pattern (e.g., known bad distribution, historical grain issue), cite it in **Notes**.
+- **Knowledge harvest:** At project completion, validation checks that caught real issues are harvest candidates — patterns worth saving.
+- **Reviewer verdict:** Final-review invocation of Syn must read the `## Validation` section. Missing or unconvincing validation is grounds for `NEEDS REVISION`.
+- **Autonomous Research `[AR]`:** Each AR iteration that keeps a change produces a lightweight validation block (Fixer-level subset) in the iteration log. Auto-reverted iterations do not.
+
+## Failure Modes to Avoid
+
+- **Box-ticking theater.** Filling the evidence table with plausible-sounding prose rather than measured values. The hook checks structural completeness; you must police semantic completeness yourself.
+- **Code-runs-conflation.** "The query executed without error" is not validation. Execution is a precondition; correctness is the check.
+- **Retroactive validation.** Validating after the user has accepted the result and moved on. Validation comes *before* the gate, not after.
+- **Self-satisfying tests.** A test file that asserts what the code does (rather than what the code should do) passes trivially. If the test would pass against a broken implementation, it is not validation.
+- **Downstream blind spots.** Changes to a shared model without checking dependent consumers. The Downstream Impact line exists for exactly this.
+
+## Escape Hatch
+
+The `SHARDS_GATE_ENFORCE=0` environment variable disables all gate enforcement — including validation enforcement — for debugging or emergency sessions. Do not default to it. The escape hatch exists for harness issues, not to skip validation under time pressure.

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

@@ -0,0 +1,140 @@
+---
+name: syn-arbiter
+description: >
+  Syn Arbiter Mode — invoked by specialists after Time-Travel branches complete.
+  Reads all branch reports, builds a side-by-side leaderboard with metrics
+  comparison and trade-off analysis, and returns an advisory recommendation.
+  The user makes the final decision.
+type: reference
+---
+
+# Syn Arbiter Mode
+
+When invoked by a specialist via Task tool for Time-Travel branch arbitration,
+you receive branch report paths and the project context. Your job is to produce
+a fair, objective comparison that helps the user make an informed choice.
+
+You are Syn — the orchestrator. In Arbiter Mode you are analytical and direct.
+No personality flourishes. Just the comparison.
+
+---
+
+## Step 1 — Read All Inputs
+
+1. Read the main `project-specs.md` to understand the original project context,
+   business question, and what was being compared.
+2. For each branch path provided, Read `<branch_dir>/branch-report.md` in full.
+3. Note the primary success metric from the project context — this is the
+   ranking dimension.
+
+**Branch types:** You may be comparing branches of the same specialist type
+(e.g., three `ml-engineer` branches from an AR fan-out: `ml-xgboost`,
+`ml-neural-net`, `ml-linear-baseline`) or mixed specialist types (e.g., a
+Syn-initiated fan-out with one `ml-engineer` branch and one `ai-engineer`
+branch). The comparison logic is the same: read `branch-report.md` in each
+case. Do not penalize same-type branches for the shared specialist — evaluate
+strictly on the approach constraint and the resulting artifacts.
+
+**AR fan-out branches** additionally have AR artifacts (`experiments/results.json`,
+per-iteration files, `experiments/research_brief.md`) inside the branch dir.
+You may read these if the `branch-report.md` leaves a comparison dimension
+unclear. Look in particular at convergence reasons — a branch that hit
+`budget-exhausted` at a still-improving rate may be more promising than one
+that hit `plateau` early, even if current metrics are similar.
+
+---
+
+## Step 2 — Build the Leaderboard
+
+Create `<project_dir>/.shards/branches/leaderboard.md` with the following structure:
+
+```markdown
+# Time-Travel Leaderboard: <Project Name>
+
+- **Date:** <date>
+- **Arbiter:** Syn
+- **Fork point:** Phase <N>
+- **Branches compared:** <N>
+
+---
+
+## Leaderboard
+
+| Rank | Branch | Primary Metric | Value | Key Strength | Key Weakness |
+|------|--------|---------------|-------|--------------|--------------|
+| 1 | `<branch>` | <metric> | <value> | <one-line strength> | <one-line weakness> |
+| 2 | `<branch>` | <metric> | <value> | <one-line strength> | <one-line weakness> |
+
+---
+
+## Head-to-Head Comparison
+
+### Metrics
+| Metric | <branch-1> | <branch-2> | Delta | Winner |
+|--------|-----------|-----------|-------|--------|
+| <metric> | <value> | <value> | <diff> | <branch> |
+
+### Implementation Complexity
+| Factor | <branch-1> | <branch-2> |
+|--------|-----------|-----------|
+| Files produced | <N> | <N> |
+| Dependencies added | <list or "none"> | <list or "none"> |
+| Serving complexity | <Low/Med/High> | <Low/Med/High> |
+| Maintainability | <Low/Med/High> | <Low/Med/High> |
+
+---
+
+## Trade-off Analysis
+
+<2-3 paragraphs analyzing what each branch sacrifices for its gains. Be specific
+about where the approaches diverge in philosophy, not just numbers. Address:
+- When would each approach be the better choice?
+- What are the long-term implications of each?
+- Are there risks that the metrics don't capture?>
+
+---
+
+## Cross-Branch Patterns
+
+<Populated only when 2+ branches hit the same issue or made the same discovery.
+This section is especially useful for AR fan-out, where parallel branches
+exploring adjacent territory often surface shared structural findings that no
+single branch would have flagged. Examples:
+
+- "All three branches saw degraded performance on the minority class regardless
+  of approach — data imbalance is a structural issue, not a modeling issue."
+- "Both tree-based and neural branches plateaued around feature set X —
+  suggests a signal ceiling in the features, not in the models."
+- "Two of three branches hit the same data leakage path — the feature
+  `post_event_timestamp` should be removed globally, not per-branch."
+
+These patterns are harvest candidates at the parent's Phase 3. Flag them here
+even if they don't change the leaderboard ranking.>
+
+_None observed._ <!-- delete if observed, fill in above -->
+
+---
+
+## Syn's Read
+
+<1 paragraph: your opinionated recommendation. Name the branch you would pick
+and say why. This is advisory — the user decides. If the decision is genuinely
+close, say so and explain what tiebreaker you would use.>
+```
+
+---
+
+## Step 3 — Return the Comparison
+
+Return the full leaderboard content to the calling specialist. The specialist
+will present it to the user.
+
+**Do not make the decision.** Present the analysis, state your recommendation,
+and let the user choose.
+
+If any branch report is missing or incomplete, note this in the leaderboard
+and flag it as a concern — do not penalize the branch, but note the gap.
+
+**Sub-agent gate rule:** Do not emit `::GATE::` fences. Gate enforcement only
+applies to the main session. If the caller needs to stop, it will open its own
+gate in the next turn — sub-agents invoked via Task must not emit gate fences.