Redline: Claude Code project guide

Read docs/ first. Start with docs/architecture.md, then the doc that matches your task. The seam contract between build agents is docs/build/INTERFACES.md and it is authoritative. The Zod types in packages/contracts/src/* are the source of truth for every shape; import them from @redline/contracts, never redefine them.

What Redline is

A statistical-rigor auditor for single-cell RNA-seq. A scientist hands it their data (an AnnData .h5ad) and the analysis they ran. Redline re-runs the load-bearing statistics itself and marks the false discoveries on the scientist's own figures, before the analysis becomes a paper. Every finding names the failure mode, cites the method paper that fixes it, and rewrites the conclusion in defensible language.

It is not QC (solved and commoditized) and not a generic manuscript reviewer (reads finished papers). It is the specialized layer that catches the statistical reasoning errors nothing else does: pseudoreplication, double dipping, clustering fragility, and technical-biological confounding. Positioning line: break your own analysis before Reviewer 2 does.

One engine, every surface. The same core runs as a plots-first web workbench (apps/web), an MCP server (services/rigor), and a Claude Skill (services/skill) that drops into Claude Science.

Layout

apps/web            Next.js 16 App Router (React 19). The demo workbench. Deploys to Vercel.
packages/contracts  @redline/contracts: the Zod shapes every surface speaks. Built. Import, don't edit.
packages/ui         @redline/ui: tokens (C, FONT, stateColor, stateLabel) + primitives. Built. Import, don't edit.
packages/engine     @redline/engine: the ComputeTarget seam (inferFields + inspect + computeCheck), fixtures, inventories, per-scenario claims, DEFAULT_CONFIG, SCENARIOS.
packages/reasoning  @redline/reasoning: Claude (first-party API or Bedrock) + curated fallback; narrate, proposeFields, extractClaims, mapClaim.
services/rigor      Python engine (scanpy / decoupler / PyDESeq2 / numpy) + the thin inspect step: MCP server + GCP Cloud Run job.
  redline/modules/  The CheckModule registry: eight checks, each with detect/prove/correct/
                    preview/recommend. Single source of truth for the check set.
  redline/correction/ The corrected-code emitter: static per-check templates, the render/slot
                    machinery, the BH stats fallback, and the downloadable bundle builder.
services/skill      The same engine packaged as a Claude Skill.
docs/               Architecture, the front door (intake + claims), honesty rules, correction layer, dataset, storyboard, deploy. Read first.

The eight checks: 1 pseudoreplication, 2 double dipping, 3 fragility, 4 confounding (the founding pillars, group core); 5 multiple testing, 6 unmodeled covariate, 7 resolution choice, 8 test assumptions (the rigor checks on the same interface, group rigor). The correction shapes (CorrectedCode, Recommendation, PreviewArtifact, CorrectedBundle, Knob) live in packages/contracts/src/correction.ts, mirrored in services/rigor/redline/contracts.py.

The docs/ index:

The finding shape (internalize this)

Every finding is numbers, prose, and correction that meet in the contract:

• ComputeResult = { checkId, state, headline, stats, chart }. The statistics, from a ComputeTarget (the locked fixture or the real Python engine). Deterministic.
• Narrative = { error, citation, original, corrected, missing? }. The prose, from the reasoning layer (Claude via Bedrock) or its curated fallback.
• Correction = { correctedCode?, recommendations?, preview? }. The correction half, from the same deterministic module. A ComputeTarget returns EngineResult = ComputeResult.extend(Correction.shape).
• CheckResult = ComputeResult.merge(Narrative).extend(Correction.shape) is what the UI renders per check.
• state is flagged | clean | flag_only | hard_stop. ready and running are UI-only and are not part of the engine's return contract.

The ComputeTarget seam decides where the statistics run (fixture default, then local, cloudrun, endpoint) behind one return shape. The UI never changes when the target changes. A target that is not wired reports available: false and its control renders disabled and labeled.

Honesty invariants (enforce in code and copy)

These are the product. Full detail in docs/honesty-rules.md.

1. Correct, and show your work. Redline corrects the analysis and previews the corrected result. Everything it asserts, recommends, or corrects is shown, reproducible, and cited: the code is downloadable and runs, the preview is its output, the recommendation names the method. No fabricated fixes: an unsalvageable finding shows no corrected result anywhere (PreviewArtifact refuses an after when unsalvageable).
2. Never cry wolf. A passed check reports clean, confidently, in green. Never manufacture a flag.
3. Pillar 2 is evidence, not a certified FDR correction. Name ClusterDE as the stronger method.
4. The grouping variable is configurable, never hardcoded to "cell type." Pillars operate on resolved FieldRoles.
5. The Marson scenario audits a naive foil, never the authors' rigorous analysis. Copy must never imply the authors erred.
6. A compute control only renders live once its target is wired. Configurable is honest; unwired targets stay disabled and clearly labeled.

Prose voice rules (any user-facing English)

This includes report copy, reasoning lines, headlines, captions, and these docs.

• No em dashes. Use commas, periods, parentheses, or "and."
• No "not X, but Y" reframes.
• No AI-tell vocabulary. Direct and concrete. Say the thing.
• Accessibility is part of the voice: real semantic elements, aria-label on icon buttons, focus-visible rings, keyboard-operable controls, prefers-reduced-motion respected for the rl-* animations.

Build rules

• Bedrock only for Claude calls. Via @aws-sdk/client-bedrock-runtime, model id from REDLINE_BEDROCK_MODEL_ID, region from AWS_REGION. Never the direct Anthropic API. On any missing credential or error, fall back to curated copy so the app always renders.
• Import conventions. @redline/contracts for shapes, @redline/ui for tokens and primitives, @/… inside apps/web. ESM everywhere. In packages/* use explicit .js extensions on relative imports and import type for type-only imports (verbatimModuleSyntax is on). apps/web relaxes both.
• Pixel-faithful design. Match the design source: same spacing, radii, fonts (IBM Plex Sans and Mono, Source Serif 4), colors (cream desk, one editorial red at #CE2A1E, quiet green and amber for clean and needs-input), and copy.
• Open source, no hidden paths. No hardcoded credentials, no environment-specific secrets, no surface-specific paths. Everything configurable through env vars.
• Portable as a Skill from day one.

Build order

1. Design resolution (the foundation; everything depends on it).
2. Pillar 1 (the keystone; the one that can assert; validate against the pseudobulk oracle in docs/dataset.md).
3. Pillar 2 (highest-impact catch; most implementation risk in the re-test).
4. Pillar 4 (cheap once the design is resolved; legible).
5. Pillar 3 (cheapest; best interactive surface).
6. The reasoning layer and report assembly, including the clean-verdict path.

The four founding pillars come first. The rigor checks (5 to 8) and the correction capabilities (corrected code, recommendations, fix-and-preview) hang off the same CheckModule interface and the registry, so they are added as modules without touching the driver. See docs/correction-layer.md.

The UI is built last, but every check exposes its knobs so the UI can surface and tune each one.

Git

• No Co-Authored-By lines on commits. None.
• Do not commit unless asked. The main session integrates and commits; parallel build agents write only the files they own and leave verification and commits to the integrator.