@proflandrigan/shards 1.1.0

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

@@ -0,0 +1,184 @@
+---
+name: experiment-versioning
+description: >
+  Versioning protocol for experiment mode. Detects DVC or git availability
+  and creates checkpoints after each experiment result. Referenced by all
+  experiment-capable agents during their Phase 2 loop.
+type: reference
+---
+
+# Experiment Versioning Protocol
+
+This protocol governs artifact versioning during experiment mode. It is
+referenced by all experiment-capable agents (ML Engineer, AI Engineer, Data
+Scientist) at specific points in their experiment workflow.
+
+---
+
+## Section A — Detection
+
+Run this section once during Setup, after establishing the `experiments/`
+subdirectory and before agreeing on experiment parameters with the user.
+
+1. Run `dvc version` via Bash. If it succeeds, check whether `.dvc/` exists at
+   the repository root (`ls -d .dvc/ 2>/dev/null`).
+   - If both succeed: versioning mode is **dvc**.
+   - If `dvc version` fails or `.dvc/` does not exist: proceed to step 2.
+
+2. Run `git rev-parse --is-inside-work-tree` via Bash.
+   - If it succeeds: versioning mode is **git**.
+   - If it fails: versioning mode is **none**.
+
+3. Announce the result to the user:
+   - **dvc:** "Experiment versioning enabled via DVC. Checkpoints will be
+     created after each experiment — you can restore any previous state."
+   - **git:** "Experiment versioning enabled via git. Tags and commits will be
+     created after each experiment — you can restore any previous state with
+     `git checkout <tag>`."
+   - **none:** "No DVC or git detected. Experiment versioning is disabled —
+     results will be tracked in markdown and JSON only. To enable versioning,
+     initialize a git repo (`git init`) before running experiments."
+
+4. If versioning mode is **dvc** or **git**: run `git status --porcelain` and
+   check for uncommitted changes outside the experiment directory. If there are
+   uncommitted changes, warn the user:
+   "There are uncommitted changes in this repo. Experiment checkpoints will
+   commit experiment files only — your other changes will remain unstaged.
+   Consider committing or stashing your work before starting experiments."
+
+Record the versioning mode internally — you will reference it in Section B
+and Section E.
+
+---
+
+## Section B — Checkpoint Creation
+
+Run this section after each experiment's results are written (after updating
+`experiments/results.json` and writing the experiment result file), and before
+consulting the reviewer (Data Scientist or Researcher).
+
+### If versioning mode is `none`:
+
+Skip this section silently. Do not print anything.
+
+### If versioning mode is `git`:
+
+Run the following commands via Bash. If any command fails, follow Section C
+(Error Handling) and continue.
+
+```bash
+# Stage experiment files and any files modified during this experiment
+git add experiments/
+
+# Also stage any other files you modified during this experiment's
+# implementation step (Step 2). You know which files you changed —
+# add them explicitly by path.
+git add <paths of files modified in Step 2>
+
+# Commit with standardized message
+git commit -m "experiment: <N> <name> — <outcome_metric> delta: <delta>"
+
+# Create annotated tag with metrics in the message
+git tag -a "exp/<project_name>/<N>-<name>" \
+  -m "Experiment <N>: <name> | <outcome_metric>: <before> -> <after> (delta: <delta>)"
+```
+
+After a successful checkpoint, capture the commit SHA:
+```bash
+git rev-parse HEAD
+```
+
+Record the tag name and commit SHA — you will write them to `results.json`.
+
+### If versioning mode is `dvc`:
+
+Run the same git commands as above (stage, commit, tag). Additionally, before
+staging:
+
+1. Check if any large artifacts were produced by this experiment (model files,
+   serialized objects, datasets > 10MB). If so, run `dvc add <artifact_path>`
+   for each large artifact before `git add`.
+
+2. After the git commit and tag, attempt `dvc push` via Bash. If it fails
+   (no remote configured), print a one-line note: "DVC push skipped — no
+   remote configured." Do not treat this as an error.
+
+Record the tag name and commit SHA as with git mode.
+
+---
+
+## Section C — Error Handling
+
+If any git or dvc command fails during checkpoint creation:
+
+1. Print a warning: "Checkpoint creation failed: `<error message>`.
+   Continuing without versioning for this experiment."
+2. Do **NOT** stop the experiment loop.
+3. Do **NOT** retry the failed command.
+4. In the experiment result file (`experiments/experiment_<N>_<name>.md`),
+   append a section:
+
+```markdown
+## Versioning
+- **Status:** Failed
+- **Reason:** <error message>
+```
+
+5. Set the `checkpoint` field in `results.json` to:
+```json
+{
+  "type": null,
+  "tag": null,
+  "commit": null,
+  "error": "<error message>"
+}
+```
+
+---
+
+## Section D — JSON Schema Additions
+
+### Top-level field (add during results.json initialization in Phase 1)
+
+Add this field to the root of `results.json`:
+
+```json
+"versioningMode": "dvc" | "git" | "none"
+```
+
+### Per-experiment field (add to each experiment entry in Phase 2 Step 5)
+
+Add this field to each experiment object in the `experiments` array:
+
+```json
+"checkpoint": {
+  "type": "git" | "dvc" | null,
+  "tag": "exp/<project_name>/<N>-<name>" | null,
+  "commit": "<sha>" | null
+}
+```
+
+If versioning mode is `none`, set the entire `checkpoint` object to:
+```json
+"checkpoint": { "type": null, "tag": null, "commit": null }
+```
+
+---
+
+## Section E — Summary Enhancement
+
+In Phase 3, after writing `experiments/experiment_summary.md`, append this
+section if versioning mode is not `none`:
+
+```markdown
+## Versioning
+
+- **Mode:** <DVC | git>
+- **Checkpoints created:** <count of experiments with successful checkpoints>
+- **Failed checkpoints:** <count, or "none">
+- **Tag prefix:** `exp/<project_name>/`
+- **To restore experiment N:** `git checkout exp/<project_name>/<N>-<name>`
+- **To list all experiment tags:** `git tag -l "exp/<project_name>/*" -n1`
+```
+
+If versioning mode is `none`, do not append this section.

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

@@ -0,0 +1,187 @@
+---
+name: goal-mode-protocol
+description: Shared protocol — opt-in /goal activation for gate-free autonomous loops (AR Phase 2 and Experiment Phase 2)
+type: reference
+---
+
+# `/goal` Mode Protocol
+
+`/goal <condition>` (Claude Code v2.1.139+) is a session-scoped, prompt-based
+Stop hook. After every turn, a small fast model (Haiku by default) reads the
+condition + the conversation transcript and decides yes/no. "No" feeds the
+reason back as next-turn guidance; "yes" clears the goal and logs the
+achievement.
+
+This protocol governs how Shards specialists *propose* a `/goal` to drive their
+**gate-free autonomous loops**:
+
+- AR Phase 2 (per `shared/autonomous_research.md` Section B)
+- Experiment Phase 2 (per each agent's `experiment.md`)
+
+The agent never runs `/goal` itself — slash commands are user-typed. The agent
+composes a sound condition, prints it as a copy-paste block at the pre-loop
+gate, and the user decides whether to activate it.
+
+Outside the two phases listed above, gates fire on every turn anyway, so
+`/goal` would have no effect.
+
+## Eligibility
+
+Before proposing a goal, confirm all of:
+
+1. **Mode.** AR Phase 2 or Experiment Phase 2. Not Phase 0/1/3 — those are gated.
+2. **Versioning.** AR requires git/DVC for auto-revert (already enforced at Phase 0). `/goal` does not change this.
+3. **Hooks enabled.** `/goal` is unavailable when `disableAllHooks` or `allowManagedHooksOnly` is set anywhere in settings. If the user reports the command is rejected, accept that and proceed — §E convergence and §G safety rails still terminate the loop.
+4. **Claude Code version.** v2.1.139 or later. If the user's Code is older, skip the proposal silently.
+
+If any condition fails, the loop runs exactly as designed without `/goal` —
+this is a quality-of-life layer, not a hard dependency.
+
+## Activation flow
+
+The agent **cannot** issue `/goal` itself. The flow is:
+
+1. At the pre-loop gate (AR Phase 1 or Experiment Phase 1), compose the goal
+   condition from the Phase 0 parameters: primary/outcome metric, target,
+   iteration/experiment budget, metric floor, cost ceiling.
+2. Print the candidate condition in a copy-paste block **before** emitting
+   the Phase 1 gate fence.
+3. Tell the user the activation is optional — autonomy quality-of-life on top
+   of the existing stop logic.
+4. The user either pastes the `/goal …` command (autonomous mode) or skips
+   (the existing in-loop convergence/stop logic alone drives the loop).
+5. After the Phase 1 gate confirms, proceed to Phase 2 normally.
+
+`/goal` clears itself when the condition holds — the agent's Phase 3 summary
+turn is the natural "yes" boundary. If the user wants to abort early, they run
+`/goal clear`. Steering Notes "STOP" (AR §B.1) still works regardless.
+
+## Writing a sound condition
+
+The evaluator has **no tools** — it only reads the conversation transcript. A
+condition that depends on a file the agent never echoes will never resolve.
+Three rules:
+
+1. **Anchor every clause to evidence surfaced inline.** Phrase clauses as
+   "the most recent inline iteration summary shows …", not "the file
+   contains …". The transcript-discipline echoes (see below) are the substrate.
+2. **Always include a turn bound as a backstop.** `Or stop after <budget+5>
+   turns` prevents a malformed condition from looping forever.
+3. **Keep it under 4,000 characters.** Concise conditions evaluate faster
+   and more reliably.
+
+### Template — AR (autonomous research)
+
+```text
+/goal The AR loop is complete when ANY of the following is true:
+  (a) the most recent inline iteration summary shows <primary_metric_name>
+      has <crossed target value X in the maximize direction |
+      dropped below target value X in the minimize direction>;
+  (b) the most recent iteration summary or status line contains
+      "Convergence detected" with reason in {plateau, diminishing-returns,
+      budget-exhausted, cost-ceiling, consecutive-failures,
+      metric-floor-breach, user-interrupt, reviewer-pause,
+      scope-violation, error-limit, timeout-limit};
+  (c) the agent has begun writing the Phase 3 research summary (look for
+      "Phase 3" or "research_summary.md").
+Or stop after <budget+5> turns.
+```
+
+### Template — Experiment
+
+```text
+/goal The experiment run is complete when ANY of the following is true:
+  (a) the most recent inline experiment summary shows <outcome_metric>
+      has <reached or exceeded <success_threshold> if the metric is being
+       maximized | dropped to or below <success_threshold> if the metric is
+       being minimized>;
+  (b) the agent has printed "Experiment <N> complete" with N == <planned_count>;
+  (c) the agent has begun writing the Phase 3 summary (look for
+      "experiment_summary.md" or "Phase 3").
+Or stop after <planned_count+3> turns.
+```
+
+If no success threshold was set, drop clause (a) and rely on (b) and (c).
+
+## Transcript discipline (required when `/goal` is active)
+
+The evaluator only reads the conversation. Each iteration the agent already
+announces and writes a per-iteration file. With `/goal` active, the agent
+**must** also print an inline iteration summary in the same assistant turn
+that closes the iteration. The required shape:
+
+For AR iterations:
+
+```text
+[AR] Iteration N complete.
+  Primary metric: <metric_name> <before> → <after> (delta: <+/->)
+  Auto-decision: <GREEN | RED | YELLOW> — <one-sentence reason>
+  Action: <Kept | Reverted | Kept with next-steps>
+```
+
+For Experiment iterations:
+
+```text
+Experiment N complete.
+  Outcome metric: <metric_name> <before> → <after> (<+/->)
+  Outcome: <Improvement | Regression | Neutral>
+  Recommendation: <Adopt | Revert | Refine>
+```
+
+When a §E stop condition fires (AR) or a Phase 2 stop condition fires
+(Experiment), additionally print on the same turn:
+
+```text
+Convergence detected: <reason>
+```
+
+These echoes are on top of `results.json` and the per-iteration markdown, not
+instead of them. Files remain the system of record; the inline copy makes the
+run readable in the transcript and lets the goal evaluator decide.
+
+## Interaction with the gate hook
+
+`/goal` and Shards' gate hook (`.shards/hooks/gate-hook.js`) both register on
+Stop. Behavior:
+
+- **Gates always win.** When a `::GATE::` fence is open (`kind=phase`,
+  `kind=execute`, `kind=final`, or `kind=checkpoint`), the gate hook blocks
+  the next turn. The `/goal` evaluator does not bypass that.
+- **Phase 2 is gate-free.** That's where `/goal` does real work — turn-by-turn
+  evaluation without per-iteration prompts.
+- **`/goal` does not suppress the Phase 3 gate.** When the loop exits and
+  Phase 3 starts, the gate fires, the user is asked the standard
+  "what do you want to adopt" question, and `/goal` clears on the summary turn.
+
+If the gate hook and `/goal` evaluator misbehave together in practice, the
+escape hatch is `/goal clear` — the loop still has its own convergence and
+stop logic.
+
+## Failure modes to avoid
+
+- **File-only conditions.** "`results.json` shows `status=complete`" will
+  never fire — the evaluator can't read files. Anchor to inline transcript
+  phrases.
+- **Unbounded conditions.** A condition without "or stop after N turns" can
+  loop until the user intervenes. Always include the bound.
+- **Goal bound tighter than §E.** If the goal says "stop at 20" but the
+  iteration budget is 100, `/goal` stops the run before §E does — and you
+  may miss real signal. Set the goal bound to `budget + small buffer`, so
+  §E does the real stopping and the goal bound is just a backstop.
+- **Setting `/goal` outside Phase 2.** The proposal happens at the Phase 1
+  gate. Setting it during Phase 0 means the evaluator runs during setup
+  turns and may stop the session before the loop starts.
+- **Forgetting transcript discipline.** Writing the iteration to file but
+  not echoing inline means the evaluator never sees the metric move, so the
+  goal never resolves except by hitting the turn bound.
+
+## Escape hatch
+
+If `/goal` is unavailable for any reason, the existing stop logic still
+terminates the loop:
+
+- AR: `autonomous_research.md` §E (convergence) and §G (safety rails)
+- Experiment: each `experiment.md` Phase 2 stop conditions
+
+`/goal` is an autonomy quality-of-life layer on top of those — it removes
+the per-turn prompts, not the underlying stop logic.

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

@@ -0,0 +1,139 @@
+---
+name: incremental-testing
+description: Shared protocol — test each component as you build it and emit a checkpoint gate before writing the next one
+type: reference
+---
+
+# Incremental Testing Protocol
+
+When building notebooks, pipelines, or multi-step scripts, you do not write more than one component ahead of your last passing test. After each component, you execute it in isolation, record the evidence (shape, row count, error or success), and emit a machine-enforced **checkpoint gate** for the user to confirm before you write the next component.
+
+This is what stops a notebook from "hanging" in cell 12 when it actually died silently in cell 2, and what prevents a bad join from running for ten minutes before you realize it needs a `LIMIT`. Run-all is not a development technique — it is the last step after every component has already passed in isolation.
+
+## The Contract
+
+Every build phase eligible for this protocol produces:
+
+1. **One tested component at a time.** You do not write component N+1 until component N has been executed, produced observable evidence, and been confirmed at a checkpoint gate.
+2. **A visible test command.** The exact command you ran to exercise the component is recorded in the checkpoint readback. No "I tested it in my head."
+3. **Evidence, not assertion.** Shape, row count, loss value, returned status code, sample output — a measured fact, not a claim. (Mirrors the evidence discipline in `validation_protocol.md`.)
+4. **A `kind=checkpoint` gate fence.** Machine-enforced — the gate hook blocks all tools except Read/Glob/Grep until the user confirms.
+
+If any of the four is missing, you are not following the protocol — you are writing-then-running, which is the failure mode this protocol exists to prevent.
+
+## What Counts as a Component
+
+A component is the smallest self-contained unit whose correctness you can check independently. Examples:
+
+| Artifact | Component examples |
+|---|---|
+| Jupyter notebook | Data load + sanity-print; EDA cell group; feature transform; baseline fit + eval; candidate fit + eval |
+| SQL pipeline | One staging model; one intermediate model; one mart model; a join between two CTEs |
+| Training script | Dataset loader; model forward pass; single-batch training step; multi-epoch loop |
+| Serving code | One endpoint handler; one auth path; one monitoring hook |
+| dbt project | One model + its tests; one seed; one snapshot |
+
+A component is **not** the same as "one line of code" or "one cell." A tight group of 2-5 cells that share a single purpose (load data + describe + assert shape) is one component. Breaking too fine defeats the point; leaving too coarse produces the run-all pathology.
+
+When in doubt: **if this piece fails, what would I need to debug in isolation?** That is the component.
+
+## How to Test — Techniques by Artifact Type
+
+### Notebook cells
+
+- **Execute cells programmatically** via Bash rather than eyeballing a run-all. Use `jupyter execute <notebook> --inplace --kernel-name=<kernel>` with a per-cell timeout (`--ExecutePreprocessor.timeout=60`). Inspect the resulting `.ipynb` outputs or check the exit code.
+- **Print shapes and heads** immediately after every data load or transform: `print(df.shape); df.head()`. If the shape isn't what Phase 3 predicted, stop.
+- **Never introduce a new cell that depends on an untested cell.** If cell 3 hasn't been exercised, do not write cell 4.
+- **Watch for the silent-fail pattern.** A cell that runs without raising but whose output is empty (`df` with 0 rows, a plot with no data) counts as a failure — assert row count `> 0` explicitly.
+- **Keep cell outputs clean.** Never print secrets, API keys, tokens, or passwords into a cell — load them from the environment (`os.environ` / a `.env` file) and never echo them; they get committed into the `.ipynb` and, in walkthrough mode, streamed into agent context. Prefer summaries (`df.head()`, `df.shape`, `df.describe()`, `.value_counts().head()`) over dumping a full DataFrame — a full dump bloats the notebook and, because the kernel writes outputs back into the `.ipynb` *and* into the agent's context, is a token cost paid on every state read.
+- **Install with `%pip` / `%conda`, not `!pip`.** The magics install into the running kernel's own environment; `!pip` shells out and may target a different interpreter, leaving imports silently failing on the live kernel.
+- **Never modify or delete raw data in place.** Read source/raw data read-only; write every derived or cleaned artifact to a separate path (`data/derived/`, `results/`). A transform that overwrites its own input is unrecoverable and destroys reproducibility.
+
+### SQL
+
+- **Develop with `LIMIT 100`.** Every query in development carries a limit. Only remove it after the shape, sample, and `EXPLAIN` plan all look right.
+- **Run `EXPLAIN` / `EXPLAIN ANALYZE` on any join of 3+ tables** before running the real query. If the plan shows a cross-join or an unbounded scan, stop.
+- **Check count-before vs count-after** at every join (see `join_path_protocol.md`). A 10x fan-out that you didn't predict is a component failure, not a "the query took a while."
+- **Time out long-running queries.** If a dev query hasn't returned in 60 seconds, interrupt it and diagnose — don't assume it will "finish eventually."
+
+### ML training
+
+- **Smoke-fit on ≤1% of data for 1-2 epochs** before touching the full dataset. Confirm loss decreases. If loss is flat or NaN, stop.
+- **Forward-pass one batch** before starting any training loop: feed a single batch through the untrained model, confirm the output shape and dtype match expectation.
+- **Overfit a tiny batch on purpose** as a sanity check — if the model cannot memorize 8 examples, the setup is broken and full training will waste hours.
+- **Checkpoint after each smoke test passes.** The checkpoint gate is separate from `experiment_versioning.md` DVC/git snapshots — one logs the incremental build, the other logs experiment results.
+
+### Transforms / feature engineering
+
+- **Assert invariants after every transform.** Shape, dtype, non-null rate, unique-key count — whatever the transform should preserve. One line of `assert` costs nothing and catches silent drops.
+- **Materialize intermediate outputs** for the first pass. You can stream through at the end; while building, write each stage's output to disk and inspect it.
+
+### Pipeline / service code
+
+- **Dry-run each step in isolation** before chaining. A pipeline that works end-to-end only works if each step works in isolation.
+- **Hit new endpoints with `curl` / `httpie` once each** before wiring them into client code.
+
+## Checkpoint Gate Usage
+
+After every component passes its test, emit a checkpoint gate. Format:
+
+```
+::GATE:: id=<agent-name>-phase-<N>-checkpoint-<component> phase=<N> kind=checkpoint
+Component: <human-readable name>
+Test command: <exact command you ran>
+Evidence:
+  - <measured fact 1, e.g. "df.shape = (48211, 47)">
+  - <measured fact 2, e.g. "null rate on join key = 0.00%">
+  - <measured fact 3, e.g. "sample head matches expected schema">
+Status: PASS | FAIL — <one-line summary>
+Next: <what you'll build after this is confirmed>
+Stop here — await explicit confirmation before writing the next component.
+::ENDGATE::
+```
+
+**Gate ID scheme.** Kebab-case, agent name + phase number + short component slug:
+- `ml-engineer-phase-6-checkpoint-data`
+- `data-scientist-phase-6-checkpoint-notebook`
+- `analytics-engineer-phase-7-checkpoint-staging`
+- `deep-learning-engineer-phase-4-checkpoint-smoke-fit`
+
+The `phase=<N>` attribute matches the current phase number (checkpoints live *within* a phase — they do not advance it). The `kind=checkpoint` attribute is what distinguishes this from a `kind=phase` transition gate.
+
+**What to read back to the user.** The fence body itself — component name, test command, evidence, status, next step. No additional prose outside the fence. The user confirms with any standard affirmative ("ok", "yes", "proceed") or explicitly via `::GATE-CONFIRM:: <id>`.
+
+**When a checkpoint fails.** If Status is FAIL, do not write the next component. Diagnose, fix, re-run the test, and re-emit the checkpoint with the updated evidence. A FAIL checkpoint is a stopping point, not a formality to announce before pressing on.
+
+**How many checkpoints per phase.** Usually 2-5. Fewer than 2 means you are batching too much and will rediscover the run-all pathology. More than 5 usually means you are checkpointing individual cells rather than components — combine them.
+
+## Composition with Other Protocols
+
+- **Validation protocol** (`validation_protocol.md`) — still required at the phase gate. Checkpoint evidence feeds the final `## Validation` evidence table but does not replace it.
+- **Join path protocol** (`join_path_protocol.md`) — still required *before* writing any join. The checkpoint fires *after* the join has been executed and verified.
+- **Experiment versioning** (`experiment_versioning.md`) — checkpoints are build-time; experiment snapshots are result-time. In `[X]` or `[AR]` modes both apply: snapshot after each experiment result, checkpoint after each component within each experiment.
+- **Gate pattern** — the phase-level `kind=phase` gate still fires at the end of the phase. Checkpoints do not replace it; they punctuate the build leading up to it.
+- **Knowledge checkpoint** (`knowledge_checkpoint.md`) — if a checkpoint surfaces a pattern (known bad distribution, known grain issue), cite it in the Evidence block.
+
+## Restart & Run All — the Final Reproducibility Check
+
+Incremental testing proves each component works *in isolation*. It does **not** prove the notebook runs clean top-to-bottom on a fresh kernel — cells can pass out of order, depend on state left by a since-edited cell, or rely on a variable that no longer exists after a restart. A notebook only truly works if **"Restart Kernel & Run All" completes without error**.
+
+This check runs **once, at the end** — after every component has already passed its checkpoint. It is the final step, never the first execution (see the "Run-all is not a development technique" framing above and the failure mode below).
+
+- **In Notebook Walkthrough mode**, run it via the kernel helper: `python .shards/ui/notebook-kernel.py run-all <session_id>`. The helper restarts the kernel, executes every code cell in order against the fresh kernel, stops at the first failing cell, and returns a per-cell pass/fail roll-up with the first error (`firstError`). Surface the result to the user; on a failure, stop and diagnose — do not declare the notebook done.
+- **Standalone** (no walkthrough session), run `jupyter nbconvert --execute --to notebook --inplace <notebook>` (or `jupyter execute <notebook> --inplace`) and confirm a zero exit code.
+- **Set seeds** (`numpy`, `random`, and any framework — `sklearn`, `torch`) so the fresh run is deterministic and headline metrics reproduce. A run-all that "works" but produces different numbers each time is not reproducible.
+
+For the Data Scientist this is the **DS-11** validation check (`Restart & Run All: N cells, no errors | seed=42 | log: results/notebook_rerun.log`); the `run-all` subcommand is how that evidence is produced. Other notebook-producing agents apply the same check at their final notebook validation.
+
+## Failure Modes to Avoid
+
+- **Write-whole-notebook-then-run-all.** The pathology this protocol exists to prevent. If your first execution of the notebook is `Restart & Run All`, you are doing it wrong — the hanging-on-cell-12 behavior will return.
+- **Unbounded SELECT in development.** A query without `LIMIT` during dev is a time bomb. Keep the limit on until the shape is confirmed.
+- **Training on full data before a smoke fit.** "It'll probably work" is how you discover at hour three that the loss has been NaN since step 1.
+- **Swallowing exceptions with bare `try/except`.** A cell that catches everything and prints "done" is indistinguishable from a cell that silently failed. Let errors propagate during development.
+- **Skipping checkpoints because "this one's obviously fine."** The checkpoint that feels unnecessary is often the one that catches the bug. If it's truly trivial, combine it with the next component — don't skip it.
+- **Emitting a checkpoint without running the test.** The fence's Evidence block must reflect a real execution. Writing "Evidence: looks good" makes the checkpoint theater.
+
+## Escape Hatch
+
+The `SHARDS_CHECKPOINT_ENFORCE=0` environment variable downgrades checkpoint gates to advisory — they are printed but do not block tool use. The `SHARDS_GATE_ENFORCE=0` variable continues to disable all gate enforcement (phase gates included). Do not default to either. The escape hatches exist for harness issues, not for skipping incremental testing under time pressure — skipping is exactly how you end up debugging at 2am.