@proflandrigan/shards 1.1.0

package/src/docs/03-protocols/experiment-versioning.md

@@ -0,0 +1,38 @@
+# Experiment Versioning
+
+Experiment mode (`[EX]` or `[EXP]` on ML/AI/DS agents) runs fixed-N experiments with versioned checkpoints. Unlike Autonomous Research, experiment mode is human-planned: you decide what to try; the specialist runs each variant and records results.
+
+## Checkpoint mechanism
+
+After each experiment result, the protocol creates a checkpoint. Detection order:
+
+1. **DVC** — if `dvc` is available and the project uses it, the checkpoint is a DVC-tracked snapshot.
+2. **Git** — otherwise, the protocol creates a git commit tagged with the experiment name.
+3. **None** — if neither is available, the protocol warns and skips checkpointing.
+
+## Artifacts
+
+| File | Purpose |
+|---|---|
+| `experiments/<project>/runs.jsonl` | One line per experiment: config, metrics, checkpoint ref. |
+| `experiments/<project>/<run-id>/` | Per-run directory: config, outputs, logs. |
+| `project-specs.md` | Phase documentation as usual; experiment results summarized in the execute phase. |
+
+## UI integration
+
+On ML/AI agents, experiment mode pushes structured output to the UI's `experiment-dashboard` panel: runs table, metric trends, side-by-side config comparison. See [Panels](../04-ui/panels.md).
+
+## Experiment vs. AR
+
+| | Experiment mode | Autonomous Research |
+|---|---|---|
+| Planning | Human-planned (you list variants) | Specialist adapts hypotheses |
+| Stop condition | N runs complete | Budget or convergence |
+| Decision-making | Reported to user for decision | Auto-keep/revert |
+| Steering | Per-run conversation | `research_brief.md` |
+
+## See also
+
+- [Autonomous Research](autonomous-research.md)
+- [DIVERGE](diverge.md)
+- Source: `src/agents/specific_instructions/shared/experiment_versioning.md`

package/src/docs/03-protocols/gate-pattern.md

@@ -0,0 +1,65 @@
+# The Gate Pattern
+
+The single most important idea in Shards: **documentation is the gate**. Every specialist must write its decision to `project-specs.md` and get your confirmation before advancing to the next phase.
+
+## Why
+
+It's easy for an agent to rush ahead and produce code that was never aligned with what you actually wanted. The gate pattern forces alignment at every step — you see the decision in writing *before* the work is done, and you can redirect cheaply.
+
+## How it works
+
+Every phase ends with the same three-step sequence:
+
+1. The specialist writes its decisions to the phase section of `project-specs.md`, wrapped in a `::GATE:: ... ::ENDGATE::` fence.
+2. The specialist reads the section back to you.
+3. The specialist waits for your confirmation before continuing.
+
+Gates are **machine-enforced** by three Claude Code hooks installed at `.shards/hooks/gate-hook.js`:
+
+| Hook | Trigger | Effect |
+|---|---|---|
+| `Stop` | When the model stops generating | Checks for open gate fences; blocks closure until gate is resolved. |
+| `PreToolUse` | Before any tool call | Rejects tool calls that would bypass the current gate. |
+| `UserPromptSubmit` | When you submit a new prompt | Validates gate state transitions. |
+
+State is tracked in `.shards/gates/state.json`.
+
+## Gate fence syntax
+
+Inside `project-specs.md`:
+
+```
+## Phase 3: Analysis Methodology
+
+::GATE::
+**Method:** Propensity score matching.
+**Reason:** Observational data, need to control for confounders.
+**Reviewer verdict (Researcher):** SOUND.
+::ENDGATE::
+```
+
+Everything between the fences is the gate decision. The hooks parse these fences, identify which are open (no confirmation yet) vs. closed (confirmed), and enforce the flow.
+
+## Diagnostics
+
+```bash
+shards-gates status       # show current gate state
+shards-gates force-close  # unstick a session if enforcement is wedged
+```
+
+## Opting out
+
+Set `SHARDS_GATE_ENFORCE=0` in the environment to disable enforcement entirely. Use sparingly — the gate pattern is what keeps projects honest.
+
+## Exceptions
+
+Two modes suspend the gate pattern:
+
+- **Syn Fixer mode** (`[F]`) — direct fixes don't need phased gates.
+- **Explore mode** (Data Modeller `[X]`) — pure exploration produces no files, no gates.
+
+## See also
+
+- [Behavioral Rules](behavioral-rules.md)
+- [Reviewer Verdicts](reviewer-verdicts.md)
+- Source: `src/agents/specific_instructions/shared/behavioral_rules.md`

package/src/docs/03-protocols/incremental-testing.md

@@ -0,0 +1,68 @@
+# Incremental Testing
+
+A mid-build contract for specialists that produce notebooks, pipelines, or long scripts. Instead of writing the full artifact and hitting *Run All*, the agent tests each component as it is written and emits a machine-enforced checkpoint gate before starting the next one.
+
+Referenced by ML Engineer, Data Scientist, AI Engineer, Applied ML Scientist, Deep Learning Engineer, Data Engineer, Analytics Engineer, and MLOps Engineer during their build phases.
+
+## The problem it solves
+
+Agents that build Jupyter notebooks and multi-step pipelines used to write the whole artifact in one pass, then run it end-to-end. When cell 2 failed silently or a bad join stalled for minutes, the failure surfaced only at the end — often disguised as a "hang." There was no record of which components had passed before the failure point, and no way to narrow the blast radius.
+
+The incremental testing protocol enforces a tighter loop: **component written → component executed in isolation → evidence recorded → checkpoint gate → user confirms → next component**.
+
+## The check
+
+Between each component, the specialist emits a `kind=checkpoint` gate fence:
+
+```
+::GATE:: id=<agent-name>-phase-<N>-checkpoint-<component> phase=<N> kind=checkpoint
+Component: <human-readable name>
+Test command: <exact command that was run>
+Evidence:
+  - <measured fact 1>
+  - <measured fact 2>
+Status: PASS | FAIL — <one-line summary>
+Next: <what will be built after confirmation>
+Stop here — await explicit confirmation before writing the next component.
+::ENDGATE::
+```
+
+The `kind=checkpoint` attribute distinguishes these from phase-transition gates: a checkpoint closes without advancing the phase, and never carries `validates=<agent>` — validation evidence is a phase-gate concern that still runs at the end of the build.
+
+While a checkpoint is open, the gate hook blocks all non-read tools (Read/Glob/Grep only). The user confirms with any affirmative ("ok", "yes", "proceed") or explicitly via `::GATE-CONFIRM:: <id>`.
+
+## What counts as a component
+
+One notebook cell or a tight group of cells with a shared purpose, one dbt model, one pipeline step, one endpoint handler — whatever is the smallest unit you could debug in isolation. Usually 2–5 checkpoints per build phase. Fewer and you rediscover run-all; more and you're checkpointing individual lines.
+
+## Techniques per artifact type
+
+- **Notebooks** — execute cells via `jupyter execute … --inplace` with a per-cell timeout; print shapes and heads after every load/transform; never add a cell that depends on an untested predecessor. Keep outputs clean: never print secrets/tokens, prefer `.head()`/`.shape`/summaries over full DataFrame dumps (they bloat the `.ipynb` and, in walkthrough mode, burn agent context), install with `%pip`/`%conda` not `!pip` so it targets the live kernel, and never overwrite raw data in place — write derived artifacts to a separate path.
+- **SQL** — develop with `LIMIT 100`; run `EXPLAIN` on any 3+ table join; check count-before vs count-after at every join; time out dev queries at 60s.
+- **ML training** — smoke-fit on ≤1% of data for 1–2 epochs before touching the full set; forward-pass a single batch before starting the training loop; overfit a tiny batch on purpose as a sanity check.
+- **Transforms** — `assert` shape/dtype/non-null invariants after every transform.
+- **Pipeline / service code** — dry-run each step in isolation before chaining; `curl` each new endpoint before wiring it up.
+
+## Restart & Run All — the final reproducibility check
+
+Incremental testing proves each component in isolation; it does not prove the notebook runs clean top-to-bottom on a fresh kernel. The closing check — run **once, after every component has passed** — is a fresh-kernel full run. In Notebook Walkthrough mode this is `notebook-kernel.py run-all <session_id>` (restarts the kernel, runs every cell in order, stops at the first failure, returns a per-cell roll-up with the first error); standalone it's `jupyter nbconvert --execute --to notebook --inplace`. Set seeds so the run is deterministic. This is the evidence the Data Scientist's DS-11 check records. Run-all is never a *development* technique — only the final step.
+
+## Composition
+
+- Still runs **with** the validation protocol — checkpoint evidence feeds the final phase-gate evidence table but does not replace it.
+- Still runs **with** the join-path protocol — the checkpoint fires after a join has been executed and verified.
+- Separate from **experiment versioning** — DVC/git checkpoints snapshot *results*; this protocol checkpoints *build steps*. In `[X]` and `[AR]` modes both apply.
+
+## Escape hatches
+
+- `SHARDS_CHECKPOINT_ENFORCE=0` — downgrades checkpoint gates to advisory. They're still logged; they don't block tools.
+- `SHARDS_GATE_ENFORCE=0` — disables all gate enforcement (phase and checkpoint).
+
+Neither should be a default. They exist for harness issues, not time pressure — skipping incremental testing is exactly how you end up debugging at 2am.
+
+## See also
+
+- [The Gate Pattern](gate-pattern.md)
+- [Validation Protocol](validation.md)
+- [Join-Path Protocol](join-path.md)
+- Source: `src/agents/specific_instructions/shared/incremental_testing.md`

package/src/docs/03-protocols/join-path.md

@@ -0,0 +1,46 @@
+# Join-Path Protocol
+
+A self-check protocol for tracing and validating multi-table joins before writing or executing SQL. Used by Data Analyst, Data Scientist, Data Engineer, Analytics Engineer, ML Engineer, and BI Engineer.
+
+## The problem it solves
+
+Multi-table joins are the single biggest source of silent data bugs. A forgotten one-to-many explodes rows; a missed left-join drops data; a grain mismatch produces double-counting. The join-path protocol catches these before execution.
+
+## The check
+
+Before writing a multi-table query, the specialist traces the join path:
+
+1. **Enumerate tables** — list every table in the join.
+2. **Identify grain** — for each table, state its grain (one row per X).
+3. **Trace the join keys** — for each join, verify that the key enforces the intended cardinality.
+4. **Document expected cardinality** — one-to-one, one-to-many, many-to-many, filtered.
+5. **Check for grain changes** — does the join change the grain of the result? If yes, is aggregation applied?
+6. **Check for null handling** — left joins, nullable keys, implicit inner-join behavior.
+
+Output is a short block in `project-specs.md` before the query is written.
+
+## Example
+
+```
+::GATE::
+## Join Path (orders → customers → subscriptions)
+
+Tables:
+- orders: one row per order (order_id)
+- customers: one row per customer (customer_id)
+- subscriptions: one row per customer per active_from date (customer_id, active_from)
+
+Joins:
+- orders.customer_id = customers.customer_id   (many-to-one)
+- customers.customer_id = subscriptions.customer_id   (one-to-many!)
+
+Grain change: subscriptions join explodes rows.
+Mitigation: filter to active subscription first via window function before join.
+::ENDGATE::
+```
+
+## See also
+
+- [Data Modeller](../02-agents/data-modeller.md)
+- [Data Engineer](../02-agents/data-engineer.md)
+- Source: `src/agents/specific_instructions/shared/join_path_protocol.md`

package/src/docs/03-protocols/knowledge-ledger.md

@@ -0,0 +1,70 @@
+# Knowledge Ledger
+
+Persistent workspace-wide memory at `.shards/knowledge/`. Survives across projects, installs, and uninstalls. Shards uses it to remember non-obvious facts about your data, your infrastructure, and patterns that work.
+
+## Layout
+
+```
+.shards/knowledge/
+├── INDEX.md              # one-line-per-entry index (scanned for keyword matches)
+├── entities/             # data table quirks, column semantics, grain surprises
+├── infrastructure/       # warehouse/API/system behaviors
+├── patterns/             # reusable SQL/Python snippets
+└── features/             # verified ML features (Data Scientist + ML Engineer)
+```
+
+## Entry format
+
+Knowledge entries are markdown files with YAML frontmatter:
+
+```yaml
+---
+title: teacher_activity grain surprise
+domain: education
+type: entity
+confidence: high
+contributed_by: data-analyst
+date: 2025-09-12
+tags: [teacher_activity, grain, daily]
+---
+The teacher_activity table has one row per teacher per day per activity_type
+— NOT one row per teacher per day as the name suggests. Joins to teacher_day
+will explode rows if you don't aggregate first.
+```
+
+Type values: `entity`, `infrastructure`, `pattern`, `feature`.
+
+## Three protocols
+
+Three shared protocols govern the Knowledge Ledger:
+
+### 1. Retrieval
+
+Before Phase 1, specialists scan `INDEX.md` for entries relevant to the current project. Matching entries are documented in `project-specs.md` as context. See `knowledge_retrieval.md`.
+
+### 2. Checkpoint
+
+Mid-phase, specialists re-check the ledger against new findings. If a new finding contradicts an existing entry, the specialist flags the contradiction and asks the user to reconcile. See `knowledge_checkpoint.md`.
+
+### 3. Harvest
+
+After Syn's final review, specialists extract candidate knowledge from the just-completed project. Candidates are presented to the user for confirmation before writing to the ledger. See `knowledge_harvest.md`.
+
+## Browsing the ledger
+
+Three ways:
+
+1. **`/knowledge` slash command** — Syn's Knowledge mode. Seed, browse, and manage entries.
+2. **UI Knowledge Map panel** — click the brain icon in the activity bar. Card view, graph view, filters, inline edit. See [Knowledge Map](../04-ui/knowledge-map.md).
+3. **Plain files** — open the `.md` files directly in your editor.
+
+## Preservation
+
+`.shards/knowledge/` is explicitly preserved on uninstall. Re-installing does not overwrite it.
+
+## See also
+
+- [Knowledge Map panel](../04-ui/knowledge-map.md)
+- Source: `src/agents/specific_instructions/shared/knowledge_harvest.md`
+- Source: `src/agents/specific_instructions/shared/knowledge_retrieval.md`
+- Source: `src/agents/specific_instructions/shared/knowledge_checkpoint.md`

package/src/docs/03-protocols/reviewer-verdicts.md

@@ -0,0 +1,39 @@
+# Reviewer Verdicts
+
+Every reviewer — Syn, Researcher, Data Modeller, Backend Engineer, MLOps Engineer, Applied ML Scientist — returns a verdict in one of three tiers. This is the universal vocabulary.
+
+## The three tiers
+
+| Tier | Meaning | Caller action |
+|---|---|---|
+| **APPROVED** / SOUND / CLEAN | No issues. | Proceed as planned. |
+| **NEEDS REVISION** / CONSIDER ALTERNATIVES / MINOR ISSUES | Valid but improvable. Reviewer provides specific suggestions. | Caller decides: address suggestions or proceed with justification. |
+| **BLOCKED** / REVISE / REFACTOR REQUIRED | Critical issues that must be fixed. | Caller must address before advancing. |
+
+Different reviewers use different labels (the Researcher says SOUND / CONSIDER ALTERNATIVES / REVISE; Syn says APPROVED / NEEDS REVISION / BLOCKED; the Backend Engineer says CLEAN / MINOR ISSUES / REFACTOR REQUIRED / BLOCKED) but the semantics are the same.
+
+## How verdicts are used
+
+Specialists write the reviewer verdict into the relevant phase section of `project-specs.md`:
+
+```
+## Phase 3: Analysis Methodology
+
+::GATE::
+**Method:** Propensity score matching.
+**Reviewer verdict (Researcher):** SOUND.
+**Reviewer notes:** Propensity overlap looks good; recommend sensitivity analysis.
+::ENDGATE::
+```
+
+The specialist then acts on the verdict per the table above.
+
+## Escalation
+
+When multiple reviewers are consulted in a phase (e.g., ML Engineer Phase 7 has Backend + MLOps + Syn), the specialist aggregates verdicts. Any `BLOCKED` blocks the phase. Any `NEEDS REVISION` is documented and addressed or justified.
+
+## See also
+
+- [The Gate Pattern](gate-pattern.md)
+- [Behavioral Rules](behavioral-rules.md)
+- Source: `src/agents/specific_instructions/shared/reviewer_verdict_protocol.md`

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

@@ -0,0 +1,40 @@
+# Decompose & Swarm — Parallel Slices for Large Work
+
+When Syn (PM Mode, Free Form, or general orchestration) faces a genuinely large
+task, it defaults to decomposing the work into bounded slices and executing them
+with **multiple same-type subagents running in parallel** — then Syn merges the
+slice results into one deliverable. This is the default for large work, not an
+opt-in mode.
+
+## When to swarm
+
+Good swarm candidates:
+
+- A task with many independent files or modules.
+- Several different sub-problems that can be worked in parallel.
+- More work than one subagent should carry in a single spawned task.
+
+Poor swarm candidates:
+
+- A single SQL query, no matter how involved.
+- A one-file change or small fix.
+- Anything a single agent completes cleanly in one turn.
+- Work where slices would write to the same paths and collide.
+
+## Lifecycle
+
+1. **Judge the scale.** Small → one agent. Genuinely large → swarm.
+2. **Slice.** Break the task into bounded, independently verifiable units, each
+   with its own output paths and a definition of done.
+3. **Spawn.** Issue parallel Task calls of the same `subagent_type`, one per
+   slice, each with a distinct brief and distinct output directory.
+4. **Review.** Review each slice (APPROVED / NEEDS REVISION / BLOCKED).
+5. **Merge.** Syn reads the slice artifacts from disk, reconciles interfaces,
+   and produces the coherent final deliverable.
+
+Syn is never limited to one instance of an agent per project — multiple data
+scientists, ML engineers, or any specialist type may run in parallel when the
+work warrants it.
+
+Supported by `specific_instructions/shared/swarm_protocol.md` (agent-facing
+instructions).

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

@@ -0,0 +1,174 @@
+# Validation Protocol
+
+Every specialist that produces a durable artifact — a mart, a model, a notebook, a dashboard, a service, a data model, a pipeline — is required to validate that artifact before the gate closes on its build phase. The validation contract is the DNA; per-agent checklists are the flesh; a gate-hook extension is the enforcement.
+
+## Why
+
+Agents are good at producing work that *looks* correct. Validation forces evidence that the work *is* correct:
+
+- Not "row counts look right" — `rows: 48,211 (source: 48,211)`.
+- Not "tested the model" — `tests/test_model.py — 14 tests, 14 passed`.
+- Not "shouldn't affect downstream" — `fct_revenue rebuilt OK, 0 schema diff`.
+
+Numbers and file paths are harder to hallucinate than prose. The protocol's job is to keep agents honest, and the gate hook's job is to make sure the protocol actually runs.
+
+## The three-layer contract
+
+| Layer | Where it lives | What it does |
+|------|----------------|--------------|
+| **Shared protocol** | `shared/validation_protocol.md` | Defines what validation means, the specs-section schema, the evidence-vs-assertion rule, how validation composes with other protocols. Loaded by every specialist via Behavioral Rules. |
+| **Domain checklist** | `<agent>/validation_checklist.md` | Defines *which* checks apply for this agent's work. Stable check IDs (AE-01, ML-03, DS-12, etc.). Track Calibration table picks the required subset per `(Track, Mode)`. |
+| **Gate hook enforcement** | `tools/gate-hook/validation.js` | Parses the `## Validation` section, checks the schema is complete, blocks the gate if evidence is missing. Opt-in via `SHARDS_VALIDATION_ENFORCE=1`. |
+
+Soft protocol defines the intent. Hard enforcement makes it stick.
+
+## The specs section schema
+
+Every validation-eligible phase writes this into `project-specs.md` before emitting its gate fence:
+
+```markdown
+## Validation
+
+**Track:** quick | deep | fixer
+**Mode:** <agent-specific — optional>
+**Checklist:** <agent_name>/validation_checklist.md
+**Applied at:** Phase <N> — <phase name>
+
+### Evidence
+
+| Check | Expected | Observed | Pass/Fail | Notes |
+|-------|----------|----------|-----------|-------|
+| <id> | <predicted> | <measured value> | ✓ / ✗ / n/a | <required if n/a> |
+
+### Artifacts
+- `<path/to/evidence-file>` — <what it shows>
+
+### Downstream Impact
+- `<consumer>` — verified intact | not applicable | broken → fixed in <ref>
+
+### Open Issues
+- <issue> | none
+
+### Summary
+<2-4 sentences: what was validated, what failed and was fixed, residual risk>
+```
+
+### Track vs Mode
+
+- **Track** (universal, strict vocabulary: `quick | deep | fixer`) controls depth. The hook validates this.
+- **Mode** (agent-specific, free-form, optional) describes the flavor of work — `greenfield`, `iteration`, `experiment`, `adhoc`, `build`. The hook does not validate Mode values; it's an auditing aid. Omit the line entirely if not meaningful.
+
+Examples:
+- ML Engineer, new recommender → `Track: deep`, `Mode: greenfield`
+- Analytics Engineer, small mart tweak → `Track: quick`, `Mode: adhoc` (or omit Mode)
+- Any `[F]` Fixer fix → `Track: fixer`
+
+### Pass/Fail values
+
+- **✓** — check ran, result met expectation.
+- **✗** — check ran, result failed. Document the fix in Notes or surface in Open Issues before closing the gate.
+- **n/a** — genuinely inapplicable to this work (e.g., calibration on a regression model). Requires a non-empty Notes cell; `n/a` without justification is a gate-block.
+
+Unresolved checks are not a valid state. Mark them `✗` and move the uncertainty to Open Issues.
+
+### Multi-instance checks
+
+Checks that measure many things (feature distributions across 47 features, per-slice model performance, per-column null rates) use a summary-row-plus-artifact pattern: one row captures the headline (`47/47 within tolerance | 2 flagged`), the full breakdown lives in an artifact file referenced under `### Artifacts`.
+
+## Track depth
+
+| Track | When | What's expected |
+|-------|------|-----------------|
+| `deep` | Full build phases — new mart, new model, new service, new pipeline, new dashboard | Full checklist per the agent's Track Calibration table |
+| `quick` | Adhoc analyses, schema tweaks, experiment iterations, prompt-lab versions | Subset — usually 4-6 of the most impactful checks |
+| `fixer` | `[F]` Fixer-mode fixes | Minimal — "what changed, what didn't break" + 1-2 smoke checks |
+
+Each agent's checklist defines exactly which checks belong to which Track.
+
+## How to enable enforcement
+
+The hook ships with enforcement **off** by default — validation sections are parsed and logged, but gates are not blocked on missing validation. This soft-launch mode lets agents and users adjust to producing the section without friction.
+
+To turn enforcement on:
+
+```bash
+export SHARDS_VALIDATION_ENFORCE=1
+```
+
+With enforcement on, a gate fence carrying `validates=<checklist>` will be blocked if the specs file's `## Validation` section is missing, incomplete, or malformed. The error message names the specific problems and points to the protocol.
+
+To disable all gate enforcement (including validation) for debugging:
+
+```bash
+export SHARDS_GATE_ENFORCE=0
+```
+
+There is no validation-only escape hatch. If a particular phase should not require validation, remove the `validates=...` attribute from its gate fence (or set `validates=none`), rather than turning off enforcement globally.
+
+## How the hook finds your specs file
+
+The hook resolves `project-specs.md` in priority order:
+
+1. `SHARDS_PROJECT_SPECS_PATH` env var if set — absolute path, overrides everything.
+2. `project-specs.md` at the CWD if it exists.
+3. The most recently modified `project-specs.md` under any conventional project directory: `analysis/<name>/`, `studies/<name>/`, `models/<name>/`, `data_models/<name>/`, `services/<name>/`, `research/<name>/`, `dashboards/<name>/`, `brainstorm/<name>/`, `fixes/<name>/`. Only immediate subdirectories are searched (one level deep).
+
+If you work on multiple projects in the same session, the "most recently modified" rule keeps validation pointed at the active project. To pin the hook to a specific file (e.g. for testing), set `SHARDS_PROJECT_SPECS_PATH` explicitly.
+
+## What the hook checks
+
+Structural only — the hook does not (and cannot) judge whether your evidence is *real*. That's Syn's job during final review.
+
+| Check | Error code |
+|-------|------------|
+| `## Validation` section exists | `MISSING_SECTION` |
+| `**Track:**` is `quick`, `deep`, or `fixer` | `MISSING_TRACK` |
+| `**Mode:**` line, if present, has a non-empty value | `EMPTY_MODE` |
+| `**Checklist:**` line references a `validation_checklist.md` | `MISSING_CHECKLIST` |
+| Evidence table has ≥1 data row | `NO_EVIDENCE_ROWS` |
+| Every row has non-empty Check, Expected, Observed | `INCOMPLETE_EVIDENCE_ROW` |
+| Every row's Pass/Fail is `✓`, `✗`, or `n/a` | `INVALID_PASS_FAIL` |
+| `n/a` rows have non-empty Notes | `NA_WITHOUT_JUSTIFICATION` |
+| Artifacts section has ≥1 bullet | `NO_ARTIFACTS` |
+| Downstream Impact has ≥1 bullet | `NO_DOWNSTREAM` |
+| Summary has ≥20 non-whitespace chars | `SUMMARY_TOO_SHORT` |
+
+## How validation composes with final review
+
+When a specialist invokes Syn for sign-off via `Task(subagent_type="syn", ...)`, Syn reads the `## Validation` section and checks the *semantic* quality the hook can't:
+
+- Is the Observed value measurable, or prose that could be true of a broken implementation?
+- Did the specialist run the checks its declared Track requires, or skip them with vague `n/a` justifications?
+- Are failed checks hidden or surfaced in Open Issues?
+- Does the Summary match the evidence?
+
+A structurally-complete but semantically-empty validation section returns `NEEDS REVISION` from Syn. See `reviewer-verdicts.md` for the verdict flow.
+
+## Common failure modes
+
+- **Box-ticking theater.** Filling the evidence table with plausible prose rather than measured values. Defense: Syn's semantic review, plus your own review at the gate.
+- **Code-runs conflation.** "The query executed" is not evidence. Execution is a precondition; correctness is the check.
+- **Retroactive validation.** Validating after you've accepted the gate and moved on. Validation comes *before* the gate, not after.
+- **Self-satisfying tests.** A test 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's not validation.
+- **Downstream blind spots.** Changes to a shared model without checking dependent consumers. The Downstream Impact line exists for exactly this.
+
+## Writing your own checklist (for extending Shards)
+
+To add a validation checklist for a new agent:
+
+1. Create `src/agents/specific_instructions/<agent>/validation_checklist.md`.
+2. Pick a stable prefix for check IDs (e.g., `XX-01`).
+3. Define the checks, each with: name, purpose, `Observed format:` line.
+4. Write a Track Calibration table indexed by `(Track, Mode)`.
+5. List expected artifacts and downstream-impact concerns.
+6. List escalation triggers.
+7. Add `validates=<agent_name>` to the agent's final build-phase gate fence in the appropriate `phases/phase-<N>.md` file (or `phases_deep/phase-<N>.md` for dual-track agents).
+
+Use `analytics_engineer/validation_checklist.md` or `ml_engineer/validation_checklist.md` as a reference shape.
+
+## Related
+
+- [Gate Pattern](gate-pattern.md) — the enforcement substrate validation builds on
+- [Behavioral Rules](behavioral-rules.md) — where the validation reference lands in each agent
+- [Reviewer Verdicts](reviewer-verdicts.md) — Syn's semantic check on the validation section
+- [Knowledge Ledger](knowledge-ledger.md) — validation findings are a primary harvest source

package/src/docs/04-ui/activity-bar.md

@@ -0,0 +1,70 @@
+# Activity Bar
+
+The vertical strip of icons on the left edge of the UI. Switches what appears in the sidebar pane to its right.
+
+## Buttons
+
+| Icon | View | What it shows |
+|---|---|---|
+| Folder | Explorer | Project file tree |
+| Clock | Session Files | Files referenced or opened during this chat session |
+| Bookmark | Bookmarks | Files, lines, and symbols you've pinned |
+| Branch | Source Control | Git status, changes, diff and PR views |
+| Brain | Knowledge Map | Knowledge Ledger entries, graph + card view |
+| Book | Guide | This developer guide |
+
+The active button is highlighted. Clicking a button when its view is already active toggles the sidebar collapsed state.
+
+## Explorer
+
+- File tree with lazy-loaded folders.
+- Search filters the listing live.
+- Switch between tree view and flat list (top-right toggle).
+- Click a file to open in the right pane; Cmd+click (or middle-click) opens in a new tab.
+- Right-click for context menu: reveal in Finder, copy path, bookmark.
+
+## Session Files
+
+- Populated as the chat agent references files.
+- Fastest way to jump back to "the file we were just talking about".
+- Shows file path and last-touched timestamp.
+
+## Bookmarks
+
+- Add bookmarks from the editor (star icon on gutter), from the command palette, or via `Cmd+D`.
+- Supports file-level, line-level, and symbol-level bookmarks.
+- Persists in `.shards/bookmarks.json`.
+
+## Source Control
+
+- Lists changed files with status badges (M / A / D / U).
+- Branch name and remote status at the top.
+- Click any file to open a diff view.
+- PR review: when a PR is checked out, inline comment threads appear.
+- See [Git](git.md).
+
+## Knowledge Map
+
+- Card view: one card per ledger entry.
+- Graph view: entries clustered by tag and entity references.
+- Click a card to open the raw markdown in the editor.
+- See [Knowledge Map](knowledge-map.md).
+
+## Guide
+
+- TOC tree on the left of the panel, page content on the right.
+- Live search across all guide pages.
+- Remembers last-viewed page across browser reloads.
+- Also browsable as plain markdown in `docs/shards-guide/`.
+
+## Keybindings
+
+- `Cmd+B` — toggle the sidebar (collapses activity bar view pane).
+- `Cmd+Shift+E` — focus Explorer.
+- `Cmd+Shift+G` — focus Source Control.
+- `Cmd+Shift+B` — focus Bookmarks.
+
+## See also
+
+- [Overview](overview.md)
+- [Keybindings](keybindings.md)