@proflandrigan/shards 1.1.0

package/src/agents/specific_instructions/researcher/review_checklist.md

@@ -0,0 +1,67 @@
+# Statistical Review Checklist
+
+When reviewing any analysis, systematically check these areas:
+
+## Distributions
+- What distribution does the data follow? (normal, log-normal, Poisson,
+  exponential, power law, mixture)
+- Has normality been tested if the method assumes it? (Shapiro-Wilk,
+  Q-Q plot, skewness/kurtosis)
+- Are there multiple modes suggesting subpopulations?
+
+## Assumptions
+- **Independence:** Are observations independent? (no clustering, no
+  time-series autocorrelation, no hierarchical structure unaccounted for)
+- **Homoscedasticity:** Is variance constant across groups/levels?
+- **Linearity:** If regression-based, is the relationship actually linear?
+- **Stationarity:** If time series, is the process stationary?
+- **Random sampling:** Is the sample representative of the population?
+
+## Outliers
+- How were outliers identified? (IQR, z-score, domain knowledge, visual)
+- What is the outlier handling strategy?
+- Have results been checked with and without outliers (sensitivity analysis)?
+- Are "outliers" actually a meaningful subpopulation?
+
+## Sample Size & Power
+- Is the sample large enough for the chosen method?
+- What effect size can this sample detect at 80% power?
+- For comparisons: are group sizes balanced enough?
+- For regression: is the observation-to-predictor ratio adequate? (minimum
+  10:1, preferably 20:1)
+
+## Methodology Appropriateness
+- Does the method match the data type? (continuous, categorical, count,
+  ordinal, survival)
+- Does the method match the question? (descriptive, inferential, predictive,
+  causal)
+- Are there better alternatives given the data characteristics?
+- Has multiple testing been addressed? (Bonferroni, FDR, etc.)
+
+## Practical Significance
+- Is statistical significance confused with practical significance?
+- What is the effect size, and is it meaningful in business context?
+- Are confidence intervals reported alongside p-values?
+
+## Report-Specific Checks (apply when reviewing a written report)
+- **Claim–evidence match:** does each stated conclusion logically follow
+  from the cited statistical result? Or is the conclusion stronger /
+  weaker than the evidence warrants?
+- **Causal language audit:** does the report use causal language ("X causes
+  Y", "X drives Y", "X leads to Y") when the design was correlational or
+  observational?
+- **Statistical vs. practical significance:** is significance reported with
+  effect size and CI, not just a p-value? Is the effect size practically
+  meaningful in the report's domain context?
+- **Limitations section:** does the report acknowledge sample limitations,
+  methodological caveats, assumption violations, and scope conditions
+  proportional to their actual size?
+- **Reproducibility cues:** are sample sizes, exclusion criteria, the
+  analysis software / version, and the random seed (where relevant) stated
+  in enough detail that the analysis could be re-run?
+- **Multiple-testing handling:** if many tests / metrics / subgroups are
+  reported, is multiple-testing addressed (Bonferroni, FDR, pre-registration
+  of primary outcomes)?
+- **Cherry-picking and selective reporting:** does the report present a
+  comprehensive set of metrics, or does it foreground favorable ones while
+  burying or omitting unfavorable ones?

package/src/agents/specific_instructions/researcher/service_mode.md

@@ -0,0 +1,224 @@
+---
+name: researcher-service-mode
+description: Service mode instructions for the Researcher when consulted by other agents via Task
+type: reference
+---
+
+# Service Mode — Being Consulted by Other Agents
+
+When invoked by another agent via the Task tool, you receive a description
+of their analysis plan, methodology, or approach. Your job is to provide a
+structured statistical review.
+
+1. Read their request carefully
+2. If they reference specific data files, queries, or notebooks, use Glob,
+   Grep, and Read to examine them
+3. If you need data model context to assess statistical validity (e.g.,
+   understanding grain for independence assumptions), consult the Data
+   Modeller:
+
+   ```
+   Task(
+     subagent_type="data-modeller",
+     description="Understand data structure for statistical review",
+     prompt="I am the Researcher shard reviewing an analysis about [topic].
+     I need to understand: [specific data structure question relevant to
+     the statistical assessment]. Please explore and return the grain,
+     key relationships, and any quality concerns."
+   )
+   ```
+
+   Only do this if the data structure is genuinely relevant to the
+   statistical assessment. Most reviews won't need it.
+
+4. Return your review using the structured format below
+5. Keep personality light in service mode — be helpful, not performative
+6. Do NOT create any files — this is pure information transfer
+
+## Response Format
+
+```
+## Statistical Review: <topic>
+
+### Distribution Assessment
+- <findings about data distributions relevant to the chosen methodology>
+- <normality concerns, skewness, multimodality, etc.>
+
+### Assumption Check
+- <methodology assumptions and whether they hold>
+- <e.g., independence, homoscedasticity, linearity, stationarity>
+- <what happens if assumptions are violated>
+
+### Outlier Considerations
+- <outlier detection recommendations>
+- <impact of outliers on the proposed methodology>
+- <handling strategy: robust methods, winsorization, exclusion criteria>
+
+### Sample Size & Power
+- <adequacy of sample for the proposed method>
+- <power considerations — can this analysis detect the expected effect?>
+- <minimum detectable effect size given the sample>
+
+### Methodology Verdict
+- **Verdict:** Sound | Consider Alternatives | Revise
+- **Key concerns:** <list of issues, ordered by severity>
+- **Recommendations:** <specific, actionable suggestions>
+- **Alternative methods:** <if applicable — what else could work>
+- **Plain-language summary:** <1-2 sentences explaining implications
+  for a non-technical audience>
+```
+
+**Verdict definitions:**
+- **Sound** — methodology is appropriate, assumptions hold (or violations
+  are minor), proceed with confidence
+- **Consider Alternatives** — methodology is reasonable but has issues that
+  should be acknowledged or mitigated; proceed with caveats
+- **Revise** — significant methodological problems; the approach needs
+  changes before execution
+These map to the universal Proceed / Proceed-with-caveats / Halt tiers used by calling specialists.
+
+---
+
+## Panel Review Mode (SERVICE MODE — PANEL REVIEW)
+
+When invoked via Task with `SERVICE MODE — PANEL REVIEW` in the prompt, you are
+participating in Syn's `[PR]` Panel Review — a multi-specialist review of a
+target directory. Your role is the statistical methodology lens. Other
+specialists in the panel cover code discipline, infrastructure, and domain
+correctness; stay in your lane.
+
+### Inputs the prompt will include
+
+- **Target directory** — full path
+- **Content tags** — what the user declared the directory contains (e.g.,
+  `ml-model`, `statistical-analysis`, `llm-ai`)
+- **Notebooks (.ipynb) to review** — list of paths, or "none"
+- **Analysis SQL (.sql) to review** — list of paths, or "none"
+- **Reports & specs to review** — list of paths, or "none"
+
+You may receive any combination of these three artifact types. Skip any bucket
+listed as "none".
+
+### What to do
+
+1. Read `.claude/agents/specific_instructions/researcher/review_checklist.md`
+   in full and apply every section systematically.
+2. **Notebooks** — read each `.ipynb` cell-by-cell via the `Read` tool
+   (`.ipynb` is supported by `Read`). Apply the checklist as if reviewing a
+   complete analysis: distributions, assumptions, outliers, sample size,
+   methodology, practical significance.
+3. **Analysis SQL** — read each `.sql` file. Apply the checklist with the
+   following lens:
+   - **Cohort definition** — does the cohort cleanly define a population for
+     the downstream test? Are inclusion/exclusion criteria documented?
+   - **Sample size adequacy** — is the resulting sample large enough for the
+     intended analysis at reasonable power?
+   - **Group balance** — for comparison queries, are the groups balanced or
+     is one group much larger?
+   - **Independence** — does the SQL produce one row per independent
+     observation? Are there clustering effects (multiple rows per user, etc.)
+     unaccounted for?
+   - **Filter implications** — do `WHERE` / `HAVING` clauses introduce
+     selection bias? Survivorship? Future leakage (filtering on
+     post-treatment outcomes)?
+   - Stay out of: grain, joins, dbt model structure, model conventions,
+     performance, indexing, dbt tests. Those belong to the Analytics
+     Engineer's separate review and Syn's coalescence step keeps them
+     distinct.
+4. **Reports & specs** — read each report markdown file. Look for
+   methodological claims, hypothesis statements, statistical procedures
+   described, results interpretation. Apply the checklist to whatever
+   methodology the report claims.
+
+### Response format (Panel Review variant)
+
+Use the standard Response Format above, then append two subsections **only if
+the corresponding bucket was present in the prompt**:
+
+```markdown
+### Per-notebook concerns
+
+#### `<notebook path>`
+- **Cell <N>:** <concern> (severity: High/Medium/Low)
+- **Cell <N>:** <concern>
+- ...
+
+(repeat per notebook)
+```
+
+```markdown
+### Per-SQL concerns
+
+#### `<sql path>`
+- **Issue:** <statistical concern>
+- **Lines:** <line range, if relevant>
+- **Severity:** High / Medium / Low
+- **Recommendation:** <one-liner>
+
+(repeat per file)
+```
+
+If a bucket was empty, omit its subsection entirely — do not write
+"none found" placeholders.
+
+### Hard rules in Panel Review mode
+
+- **No Edit. No Write. No NotebookEdit.** You are a reviewer, not a fixer.
+  Your tools list does not include Edit/Write/NotebookEdit by design — Syn's
+  Phase 5 dispatch will route your recommendations to the bucket's domain
+  reviewer (Data Scientist, ML Engineer, Applied ML Scientist, Deep Learning
+  Engineer, or Analytics Engineer) for application.
+- **Severity tagging is mandatory.** Syn's coalescence step uses your severity
+  tags to build the consolidated findings table. Do not return findings
+  without High/Medium/Low.
+- **Be specific about location.** Notebook + cell number, or SQL file + line
+  range. Generic findings ("the methodology is questionable") are not
+  actionable.
+- **Stay in lane on SQL.** Methodological concerns only. Grain, joins, model
+  conventions, performance, dbt structure are out of scope.
+
+---
+
+## Report Review Mode (`SERVICE MODE — REPORT REVIEW`)
+
+When invoked via Task with `SERVICE MODE — REPORT REVIEW` in the prompt, you
+are doing a single-report statistical critique on behalf of a calling agent
+(Syn, Data Scientist, ML Engineer, etc.). This is the service-mode variant
+of the `[CR]` Critical Review menu mode.
+
+### Inputs the prompt will include
+
+- **Report path** — full path to the `.md` report under review
+- **Review lens** — Accuracy | Thoroughness | Fairness | all
+- **Optional referenced artifacts** — data files, SQL, notebooks the report
+  cites (the calling agent may want you to spot-read them)
+- **Calling context** — why the review was requested
+
+### What to do
+
+1. Read the target report at the provided path.
+2. Read `.claude/agents/specific_instructions/researcher/critical_review.md`
+   and apply Phases 2–4 (Read & Extract Methodological Claims → Apply
+   Statistical Checklist → Three-Lens Critical Assessment) to the report.
+3. Spot-read any referenced artifacts the calling agent listed.
+4. Return findings **inline** using the Critical Review output template
+   from Phase 5 of `critical_review.md`. **Do NOT write a file** in service
+   mode — the calling agent decides what to persist. The Write tool exists
+   in your frontmatter only for direct-invocation `[CR]` mode and must not
+   be used here.
+5. Severity-tag every finding (High / Medium / Low).
+6. If a Data Modeller consultation is genuinely needed for an
+   independence / grain question that the report and its referenced
+   artifacts can't answer, announce it before issuing the Task.
+
+### Hard rules in Report Review mode
+
+- **No Write. No Edit.** Service mode never writes files — even though your
+  tools list includes Write/Edit for the direct-invocation `[CR]` opt-in.
+- **Severity tagging is mandatory.** Calling agents may coalesce your
+  findings into a wider review.
+- **Be specific about location.** Quote the report's section / paragraph /
+  sentence where the issue lives. Generic critiques are not actionable.
+- **Stay in your statistical lane.** Ethical, behavioral-mechanism, and
+  domain-correctness concerns belong to other agents — flag them and
+  recommend escalation rather than reviewing them yourself.

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

@@ -0,0 +1,141 @@
+---
+name: auto-verify-mode
+description: Shared protocol — bracket bulk read-only verification work in a marker pair so the gate hook auto-approves the curated safe ops without spamming permission prompts
+type: reference
+---
+
+# Auto-Verify Mode
+
+When a phase requires running many similar read-only verification queries in a row (per-model grain checks, fan-out before/after counts, null-rate scans, freshness checks, dbt show/ls/parse, package metadata, sample inspections), each one normally fires a permission prompt. The user clicks through twenty near-identical "allow" prompts and gradually loses the ability to spot the one prompt that matters.
+
+This protocol bounds those stretches with a marker pair. While the block is open, the gate hook (`gate-hook.js`) auto-approves tool calls that match a hardcoded read-only allowlist. Everything outside the allowlist still prompts. Phase and checkpoint gates always win — when a real `::GATE::` is open, auto-verify is suspended.
+
+This is **not** `--dangerously-skip-permissions`. The allowlist is hardcoded, the budget is bounded, the user can halt with one word, and every approval is logged.
+
+## When to Enter
+
+Enter auto-verify only when **both** of these are true:
+
+1. The next stretch of work is exclusively read-only verification — running queries to check shapes, counts, nulls, fan-out, freshness, sample rows, or invoking read-only CLI subcommands (`dbt show`, `dbt ls`, `dbt parse`, `dbt compile`, `git status`, `git diff`).
+2. You expect to issue **3 or more** similar tool calls in sequence. Below that threshold, the prompt friction isn't worth the cognitive overhead of opening a block.
+
+Concrete fits:
+
+| Situation | Why |
+|---|---|
+| Data Modeller post-build phase running grain + fan-out + null + sample on N models | Repeats N×4 queries; classic prompt-spam pattern |
+| Analytics Engineer per-layer checkpoint validation | Identical sweep across staging → intermediate → mart |
+| ML Engineer / Data Scientist Phase 6 verifying feature query joins | Tier 2/3 join verification per join |
+| Data Modeller service-mode consultation running PK/null/fan-out/freshness on the requested tables | The most common "I just clicked allow on the same thing 8 times" path |
+| Join path protocol Tier 2/3 verification (count-before / count-after at every join) | Repeated count comparisons |
+
+## When NOT to Enter
+
+Do not enter auto-verify when **any** of these is true:
+
+- The work writes to disk (`Write`, `Edit`, `NotebookEdit`) — these are never auto-approved regardless of the block, and entering the block signals the wrong intent.
+- The work mutates external state — `dbt run`, `dbt build`, `dbt seed`, `dbt snapshot`, INSERT/UPDATE/DELETE/MERGE, `git push`, `git commit`, package installs, deployments, API calls that mutate.
+- The work involves a user-facing decision point (a phase gate, a checkpoint gate, a clarification question, a methodology choice).
+- A handoff is in progress (Task call to another specialist). The other specialist runs in its own context — your auto-verify state doesn't follow.
+- You're in a build phase. Builds are punctuated by `kind=checkpoint` gates, which suspend auto-verify anyway. Don't open auto-verify during a build phase — it won't help.
+- The work is exploratory in nature (Data Modeller `[X] Explore` track) and the user is reading along. Auto-verify makes sense for *bulk* verification, not interactive exploration where each query is part of the conversation.
+
+If you're unsure whether the next stretch fits, do not enter auto-verify. The default behavior (per-call prompts) is fine.
+
+## Marker Syntax
+
+Open with a single line at the top of the message that begins the verification stretch:
+
+```
+::AUTO-VERIFY:: agent=<your-name> phase=<N> tool_budget=<N> ttl_minutes=<N>
+```
+
+| Attribute | Required | Default | Bounds | Meaning |
+|---|---|---|---|---|
+| `agent` | yes | — | kebab-case agent name | For audit log |
+| `phase` | yes | — | phase number | For audit log |
+| `tool_budget` | no | 20 | 1–50 | Max auto-approvals before block auto-closes |
+| `ttl_minutes` | no | 10 | 1–30 | Wall-clock expiry from open |
+
+Both `tool_budget` and `ttl_minutes` are clamped to their max — requesting `tool_budget=999` gets you 50, not 999.
+
+Close with a bare line at the end of the verification stretch:
+
+```
+::ENDAUTO::
+```
+
+Example:
+
+```
+::AUTO-VERIFY:: agent=data-modeller phase=6 tool_budget=12 ttl_minutes=5
+
+Running per-model validation for the customers / orders / order_items models.
+
+[runs `dbt show --select customers --limit 5`]
+[runs `psql -c "SELECT count(*), count(distinct customer_id) FROM stg.customers"`]
+[runs `psql -c "SELECT count(*) FROM int.orders"`]
+[runs `psql -c "SELECT count(*) FROM (int.orders JOIN stg.customers USING (customer_id))"`]
+... (12 more queries) ...
+
+::ENDAUTO::
+```
+
+## What Gets Auto-Approved
+
+While the block is open, the hook auto-approves tool calls that match the hardcoded allowlist:
+
+- **Always-safe tools**: `Read`, `Glob`, `Grep`, `WebSearch`
+- **Read-only Bash prefixes**: `git status/log/diff/show/branch/rev-parse/remote -v/remote show`, `ls`, `cat`, `head`, `tail`, `wc`, `file`, `stat`, `pip list/show/freeze`, `npm ls/list/outdated/view`
+- **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 hook 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.
+
+## What Never Gets Auto-Approved
+
+These always fall through to the normal prompt, even inside auto-verify:
+
+- `Write`, `Edit`, `NotebookEdit`
+- `Bash(rm:*)`, `Bash(mv:*)`, `Bash(sudo …)`, anything with shell redirects (`>`, `>>`), pipe-to-shell, command substitution (`$(...)` or backticks)
+- Compound commands joined with `&&`, `||`, `;`, `|` at the shell level (a single `dbt show` is fine; `dbt show && rm -rf` is not)
+- `dbt run`, `dbt build`, `dbt seed`, `dbt snapshot` — even with `--select`, these write
+- `git push`, `git commit`, `git merge`, `git rebase`
+- `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE`, `DROP`, `ALTER`, `TRUNCATE`, `GRANT`, `REVOKE`, `COPY` via warehouse CLI
+- Anything matching the user's `permissions.deny[]` list (Claude Code enforces this; the hook cannot override it)
+- MCP tools (auto-verify only matches built-in tools)
+
+If a tool call falls outside the allowlist, the prompt fires normally — **do not interpret a single prompt as a signal to abandon the block**. Answer the prompt and continue. The block stays open.
+
+## How the Block Closes
+
+The block closes — and auto-approval ends — when any of these happens:
+
+1. You emit `::ENDAUTO::` in a later message
+2. The tool budget hits zero (every auto-approval decrements it)
+3. The TTL elapses (wall-clock from open)
+4. The user submits a prompt containing "stop", "halt", "pause", "cancel", "abort", "wait", "hold on", "no thanks", "nope", or "don't" — these halt immediately
+5. A real `::GATE::` opens (auto-verify is *suspended* during gate, not closed; it resumes when the gate confirms — but in practice phase boundaries are where you `::ENDAUTO::` anyway)
+
+After close, the next non-allowlisted tool call prompts as normal.
+
+## Discipline
+
+- **Open exactly when the bulk work starts.** Don't open at the top of the phase and let it run for the whole phase — the budget runs out, the TTL expires, and you've signaled to the user that you intend to do bulk read-only work when actually you're going to write code.
+- **Close exactly when the bulk work ends.** A trailing `::ENDAUTO::` before any prose, decision, or write makes the boundary visible.
+- **Don't re-open within the same message.** If you need a second block, finish the message, get user input, and open a new block in a later turn.
+- **Don't use auto-verify to skip a checkpoint or phase gate.** Gates always win. If you find yourself wanting auto-verify to "make this gate go away," you are misusing it.
+
+## What the User Sees
+
+Auto-verify is visible to the user — every approval is logged to `.shards/auto/history.jsonl` with timestamp, agent, phase, tool, and command. The user can `tail` it to see exactly what got approved. The audit trail is non-negotiable; if a future change tries to remove it, that change is wrong.
+
+## Composition with Other Protocols
+
+- **Gate pattern** — gates always win. A `kind=phase` or `kind=checkpoint` gate suspends auto-verify; the gate's allow-list (Read/Glob/Grep) takes over until the gate confirms.
+- **Validation protocol** — auto-verify does not satisfy validation evidence. The validation `## Evidence` table still requires real measured facts, recorded in `project-specs.md`, before the phase gate.
+- **Incremental testing** — checkpoint gates fire *between* components in a build phase. Don't try to span a build phase with auto-verify; the checkpoint will suspend it anyway.
+- **Join path protocol** — Tier 2/3 verification queries are exactly the use case auto-verify is for. Open the block, run the count-before / count-after queries, close the block, then write the join.
+
+## Escape Hatch
+
+`SHARDS_AUTO_VERIFY=0` disables the auto-verify branch entirely. Markers are still parsed (so they don't appear as raw text in transcripts) but no state is written and no tool calls are auto-approved. Use this if a downstream tool integration is misbehaving — not as a default. Without auto-verify, the prompt-spam problem returns.