@oneie/claude 0.1.0

package/rules/astro.md

@@ -0,0 +1,206 @@
+---
+paths:
+  - "**/*.astro"
+---
+
+# Astro Rules
+
+Apply to `*.astro`
+
+---
+
+## Structure
+
+```
+src/pages/       # Routes
+src/layouts/     # Layouts
+src/components/  # Components
+```
+
+---
+
+## Frontmatter
+
+```astro
+---
+interface Props {
+  title: string
+}
+const { title } = Astro.props
+---
+```
+
+Always TypeScript. Always typed.
+
+---
+
+## Hydration
+
+```
+┌────────────────────┬─────────────────────────────────────┐
+│ client:load        │ Critical, above-fold, interactive   │
+├────────────────────┼─────────────────────────────────────┤
+│ client:visible     │ Below-fold, lazy                    │
+├────────────────────┼─────────────────────────────────────┤
+│ client:idle        │ Non-critical widgets                │
+├────────────────────┼─────────────────────────────────────┤
+│ client:only="react"│ Client-only, skip SSR               │
+└────────────────────┴─────────────────────────────────────┘
+```
+
+---
+
+## Islands
+
+```astro
+<!-- Static — no JS shipped -->
+<AgentCard agent={agent} />
+
+<!-- Interactive — hydrates -->
+<AgentCard client:load agent={agent} onClick={handle} />
+
+<!-- Lazy — hydrates when visible -->
+<ColonyGraph client:visible highways={highways} />
+```
+
+Only add `client:*` when interactivity is needed.
+
+---
+
+## Imports
+
+```astro
+---
+// Good — path aliases
+import Layout from "@/layouts/Layout.astro"
+import { ColonyEditor } from "@/components/graph/ColonyEditor"
+
+// Bad — relative paths
+import Layout from "../../../layouts/Layout.astro"
+---
+```
+
+---
+
+## Styles
+
+```astro
+<!-- Scoped -->
+<style>
+  .container { ... }
+</style>
+
+<!-- Global (sparingly) -->
+<style is:global>
+  .colony-graph { ... }
+</style>
+
+<!-- Tailwind (preferred) -->
+<div class="bg-[#0a0a0f] p-4 rounded-lg">
+```
+
+---
+
+## With Substrate
+
+```astro
+---
+import Layout from "@/layouts/Layout.astro"
+import { ColonyEditor } from "@/components/graph/ColonyEditor"
+---
+
+<Layout title="Colony">
+  <ColonyEditor client:load />
+</Layout>
+```
+
+- `client:load` — interactive graph needs JS
+- Colony state lives in React component
+- Astro handles routing, layout, SSR shell
+
+---
+
+---
+
+## Performance — lazy imports inside islands
+
+**Every `client:*` island ships its entire static import graph on first load.**
+Any component not needed for the initial render that is statically imported will
+block FCP/LCP.
+
+**Rule:** Any heavy component inside a hydrated island that is NOT required for
+first render MUST use `lazy()` + `Suspense`.
+
+### `inlineStylesheets` — LOCKED to `'auto'` on Workers
+
+`astro.config.mjs` MUST set `build: { inlineStylesheets: 'auto' }` (Astro's
+default). **Never `'always'`.** Under the Cloudflare adapter, `'always'`
+inlines the full stylesheet into every route's serialized manifest entry —
+with N routes, the worker-entry chunk grows by N × stylesheet size. On a
+~100-route site that single config flag adds ~8 MiB and breaks the 3 MiB
+gzipped upload limit. Diagnose by checking for a multi-MB string literal in
+worker-entry: `awk 'length > 100000 { print NR, length }' dist/server/chunks/worker-entry_*.mjs`.
+
+**Known heavy modules to always lazy-import inside islands:**
+
+| Module | Why |
+|--------|-----|
+| `@/components/ai-elements/attachments` | ~281 KB — file-picker, previews |
+| `@/components/ai-elements/speech-input` | mic/audio APIs |
+| `@/components/ai-elements/voice-menu` | voice controls |
+| `@/components/pay/PayPanel` | payment UI |
+| `@/components/chat/MessageList` | scroll list |
+
+```tsx
+// ✅ Correct — deferred until user action
+const AttachmentsPreview = lazy(() =>
+  import('@/components/chat/AttachmentsPreview')
+    .then(m => ({ default: m.AttachmentsPreview })))
+
+// Inside JSX:
+<Suspense fallback={null}>
+  <AttachmentsPreview />
+</Suspense>
+
+// ❌ Wrong — pulls 281 KB into the initial island bundle
+import { Attachments } from '@/components/ai-elements/attachments'
+```
+
+**Testing:** run `npx lighthouse <url> --chrome-flags="--headless --no-sandbox" --output=json`
+then check `audits['unused-javascript'].details.items` — items > 50 KB are candidates
+for lazy conversion.
+
+---
+
+## Dark mode — WCAG AA contrast invariant
+
+**Default:** `<html class="dark">` — Lighthouse always runs in dark mode
+(no `localStorage`). All contrast checks happen against dark tokens.
+
+**Dark mode brand token rule:**  
+Brand fills lighten to L≥65% in dark mode (so they're visible on dark
+backgrounds). At L≥65%, `#fff` text fails WCAG AA. `on-*` labels MUST flip
+to `#000` in `html.dark`.
+
+In `Layout.astro` `html.dark` block, always include:
+
+```css
+html.dark {
+  --color-primary: hsl(216 55% 65%);     /* L=65 — needs dark label */
+  --color-secondary: hsl(219 14% 65%);   /* L=65 — needs dark label */
+  --color-tertiary: hsl(105 22% 65%);    /* L=65 — needs dark label */
+  --color-on-primary: #000;              /* ← REQUIRED for WCAG AA */
+  --color-on-secondary: #000;            /* ← REQUIRED for WCAG AA */
+  --color-on-tertiary: #000;             /* ← REQUIRED for WCAG AA */
+}
+```
+
+**The JS `onLabel()` function in Layout.astro handles theme overrides** (stored
+themes from the editor). The CSS defaults above handle the no-localStorage case
+(Lighthouse, first visit, SSR).
+
+Threshold: `L < 60 → #fff`, `L ≥ 60 → #000`. Default dark brand L=65, so always `#000`.
+
+---
+
+*Astro 6. Islands. Fast. 100% Lighthouse.*

package/rules/design.md

@@ -0,0 +1,221 @@
+---
+paths:
+  - "one.ie/web/**/*.tsx"
+  - "one.ie/web/**/*.astro"
+  - "one.ie/web/**/*.css"
+---
+
+# Design System Rules
+
+Apply to `one.ie/web/**/*.tsx`, `one.ie/web/**/*.astro`, `one.ie/web/**/*.css`
+
+The design system is **6 tokens**. Spec: [`design.md`](../../design.md). Showcase: `/design`.
+The build itself enforces this — `--color-*: initial` in `Layout.astro` strips Tailwind's
+default palette so wrong colors emit no CSS. Don't fight the enforcement.
+
+---
+
+## The 6 editable tokens (the only colors a user can pick)
+
+| Token | Use for |
+| --- | --- |
+| `background` | Card surfaces, sidebars, page-level panels |
+| `foreground` | Inner content rectangles inside cards |
+| `font` | All body text |
+| `primary` | Main CTAs, brand accents, focus rings |
+| `secondary` | Supporting actions, secondary buttons |
+| `tertiary` | Highlights, success checks, accents |
+
+## Plus 5 invariants (never editable)
+
+`white` · `black` · `transparent` · `destructive` (errors/deletes) · `success` (confirms).
+
+## Plus derived helpers (auto-computed — don't set directly)
+
+Color: `on-primary` · `on-secondary` · `on-tertiary` (auto-contrast labels for brand fills) · `border` (= font @ 10%) · `border-strong` (= font @ 20%) · `muted` (= font @ 60%) · `faint` (= font @ 40%) · `ring` (= primary) · `page` (= background mixed with 4% font — L0 page shell).
+
+Polish constants (baked, not exposed): `--radius-sm` 6px · `--radius-md` 10px · `--radius-lg` 16px · `--shadow-card` · `--shadow-pop` · `--ease` 120ms.
+
+## Three depth levels
+
+| Level | Surface | Where |
+| --- | --- | --- |
+| L0 page | `--color-page` | `<body>`, full-bleed shell |
+| L1 card | `--color-background` | Cards, sidebar, popovers, dropdowns |
+| L2 content | `--color-foreground` | Card body, inputs, code blocks |
+
+Sidebar = L1. Inputs = L2. There is no L3. A card header/footer shares the card surface; never tint them separately.
+
+---
+
+## Allowed utilities
+
+```
+bg-{background|foreground|primary|secondary|tertiary|destructive|success|white|black|transparent}
+text-{font|primary|secondary|tertiary|on-primary|on-secondary|on-tertiary|destructive|success|white|black}
+border-{font|primary|secondary|tertiary}
+ring-{primary|secondary|tertiary}
+```
+
+**Use the auto-contrast `on-*` labels on brand fills** — they stay readable when the user picks any color:
+
+```tsx
+<button className="bg-primary text-on-primary">Primary</button>
+<button className="bg-tertiary text-on-tertiary">Tertiary</button>
+```
+
+For muted text, borders, and focus rings, use alpha modifiers or `var()` — these are CSS-only helpers, not Tailwind utilities:
+
+```tsx
+text-font/60                                        // muted body text
+text-font/40                                        // disabled / placeholder
+border-font/10                                      // subtle borders
+bg-primary/20                                       // tinted brand backgrounds
+style={{ borderColor: 'var(--color-border)' }}      // when alpha modifier won't fit
+```
+
+The `--color-{border,muted,ring}` CSS vars exist (defined in `Layout.astro`) but are not Tailwind tokens — Tailwind v4 chokes on `var()` references inside `@theme`. Use them via `var()` only when needed.
+
+---
+
+## Banned
+
+- ❌ Any Tailwind palette class: `bg-zinc-*`, `text-indigo-*`, `border-slate-*`, `text-emerald-*`, etc.
+- ❌ Hex literals in JSX/CSS: `#fff`, `#0a0a0f`, `style={{ color: '#abc' }}`
+- ❌ Raw `hsl(...)` / `rgb(...)` outside `Layout.astro` (token source) and `design.astro` (showcase)
+- ❌ Adding a 7th token. Derive with alpha modifiers or `color-mix()`.
+- ❌ Mixing icon sets. Lucide only — via `<Icon>` / `<IconBadge>` (in `web/src/components/ui/`).
+- ❌ Inline SVG icons in React components. Import from `lucide-react` and wrap.
+- ❌ Unicode icon glyphs (☀ ☾ ▾ ✓ ✗). They render differently across OSes — use lucide.
+
+---
+
+## Patterns
+
+### Card (header · body · footer)
+
+One shape, three slots. Header and footer share the card surface; only the body switches to `foreground`.
+
+```tsx
+<article
+  className="bg-background border rounded-2xl flex flex-col"
+  style={{ borderColor: 'var(--color-border)', boxShadow: 'var(--shadow-card)' }}
+>
+  <header className="flex items-start justify-between gap-4 px-5 pt-5">
+    <div>
+      <h3 className="text-base font-bold">Title</h3>
+      <p className="text-font/60 text-sm">Meta</p>
+    </div>
+    <span className="px-2.5 py-1 rounded-full text-xs bg-foreground text-font/60 border" style={{ borderColor: 'var(--color-border)' }}>badge</span>
+  </header>
+
+  <div className="mx-5 mt-4 p-4 bg-foreground rounded-xl border" style={{ borderColor: 'var(--color-border)' }}>
+    {/* L2 — data, inputs, charts */}
+  </div>
+
+  <footer
+    className="flex items-center justify-between gap-3 px-5 py-4 mt-4 border-t"
+    style={{ borderColor: 'var(--color-border)' }}
+  >
+    <span className="text-font/60 text-sm">Updated 2m ago</span>
+    <div className="flex gap-2">
+      <button className="px-4 py-2 rounded-lg text-font">Cancel</button>
+      <button className="px-4 py-2 rounded-lg bg-primary text-on-primary">Save</button>
+    </div>
+  </footer>
+</article>
+```
+
+### Icons
+
+One source: `lucide-react`. Two wrappers in `web/src/components/ui/`:
+
+```tsx
+import { Send, Zap } from 'lucide-react'
+import { Icon } from '@/components/ui/Icon'
+import { IconBadge } from '@/components/ui/IconBadge'
+
+// Inline — inherits parent color via currentColor
+<Icon icon={Send} size="md" />
+
+// Colored badge — feature grids, list rows, profile blocks
+<IconBadge icon={Zap} tone="primary" size="md" />
+```
+
+`Icon` sizes: `sm` 14 · `md` 16 · `lg` 20 · `xl` 24. Stroke is locked to 1.5.
+`IconBadge` tones: `primary` · `secondary` · `tertiary` · `neutral`. Surface is `color-mix(tone 14%, foreground)` — brighter than the card outer, tinted toward the tone color.
+
+In Astro pages where you can't easily import React, use inline SVG with `viewBox="0 0 24 24"`, `stroke="currentColor"`, `stroke-width="1.5"`, `stroke-linecap="round"`, `stroke-linejoin="round"`. Copy paths from `lucide.dev`. Never use unicode glyphs.
+
+### Form fields
+
+Inputs use `background` (sunken), not `foreground` (raised). The card body is `foreground`; inputs sink back to `background` so they stand out as interactive surfaces against the body.
+
+```tsx
+<div className="flex flex-col gap-1.5">
+  <label htmlFor="name" className="text-sm font-medium">Name</label>
+  <input
+    id="name"
+    type="text"
+    className="px-3.5 py-2.5 rounded-lg bg-background text-font border focus:outline-none"
+    style={{ borderColor: 'var(--color-border)' }}
+    placeholder="Ada Lovelace"
+  />
+  <span className="text-xs text-font/60">Shown on your public profile</span>
+</div>
+```
+
+Focus uses `--color-ring` border + 3px `ring/25` glow. Error uses `aria-invalid='true'` → border `destructive`. Placeholder uses `--color-muted`. Checkbox/radio also use `bg-background` so they pop against the body.
+
+### Buttons (6 variants)
+
+```tsx
+<button className="bg-primary text-white rounded-lg px-4 py-2 hover:brightness-110">Primary</button>
+<button className="bg-secondary text-white rounded-lg px-4 py-2 hover:brightness-110">Secondary</button>
+<button className="bg-tertiary text-white rounded-lg px-4 py-2 hover:brightness-110">Tertiary</button>
+<button className="border border-primary text-font rounded-lg px-4 py-2">Outline</button>
+<button className="text-font rounded-lg px-4 py-2">Ghost</button>
+<button className="bg-font text-foreground rounded-lg px-4 py-2 hover:brightness-95">Inverse</button>
+```
+
+### Muted text
+
+```tsx
+<p className="text-font/60">Secondary copy</p>
+<p className="text-font/40">Disabled / hint</p>
+```
+
+---
+
+## Enforcement
+
+Three layers, all automatic:
+
+1. **Build-time kill** — `Layout.astro` declares `--color-*: initial` in `@theme`,
+   wiping Tailwind's default palette. `bg-zinc-950` produces no CSS.
+2. **PostToolUse hook** — `.claude/hooks/design-check.sh` greps every Write/Edit
+   to `one.ie/web/**/*.{tsx,astro,css}` for banned patterns. Exit 2 on violation feeds
+   the diff back to Claude as a tool error; the model self-corrects next turn.
+3. **This rule** — auto-loaded on the same files via `.claude/settings.json`,
+   so the constraints are in context before the first character is written.
+
+The hook allowlists `Layout.astro` (token source) and `design.astro` (showcase).
+There is no opt-out for other files.
+
+---
+
+## Don't
+
+- Don't introduce a 7th token. Derive instead.
+- Don't use `text-zinc-*` etc. — they emit no CSS, but stop the next reader from trusting the codebase.
+- Don't write `style={{ color: '...' }}` — break the token enforcement.
+- Don't use shadcn's `accent` name; it's `tertiary` here.
+- Don't flip brand colors with mode — only surfaces flip.
+- Don't add a 4th depth level. Page → card → content. A card header is not a 4th surface.
+- Don't pick off-scale radii or spacing. Snap to `radius-sm/md/lg` (6/10/16) and 4/8/12/16/20/24/32.
+- Don't animate longer than 200ms. Use `var(--ease)` (120ms) for color/border/filter.
+- Don't tint a card's header or footer with a different background — they share the card surface.
+
+---
+
+*6 tokens. 3 depths. 1 card. 1 input. 6 button variants. The build refuses to compile anything else.*

package/rules/documentation.md

@@ -0,0 +1,218 @@
+# Documentation Rules
+
+Apply to all TODOs and `/do` workflows.
+
+**Principle:** Document BEFORE implementation (W2), edit alongside code (W3), verify consistency (W4).
+
+---
+
+## The Three Phases
+
+### **W2 — Planning Phase: Document the Plan**
+
+Before any code is written, explicitly list which docs will change:
+
+```markdown
+### Documentation Updates (W2)
+
+**New docs:**
+- `docs/feature.md` — {purpose}
+
+**Docs modified:**
+- `docs/dictionary.md` — add term {name}
+- `docs/routing.md` — update loop L{N}
+- `docs/rubrics.md` — add dimension {name}
+
+**Schema changes:**
+- New TypeDB entities, D1 migrations, TypeQL functions
+```
+
+**Why:** Naming decisions, API design, and lifecycle implications must be documented before code is written. The docs ARE the spec.
+
+---
+
+### **W3 — Edit Phase: Update Docs + Code in Parallel**
+
+**For every code file edited, edit the corresponding doc:**
+
+| Code File | Related Doc |
+|-----------|-------------|
+| `nanoclaw/src/types.ts` | `docs/dictionary.md` — add new type terms |
+| `src/engine/world.ts` | `docs/DSL.md` — update signal grammar |
+| `src/engine/loop.ts` | `docs/routing.md` — update L1-L7 loops |
+| `src/pages/api/*.ts` | `docs/lifecycle.md` — update lifecycle stage |
+| `src/schema/*.tql` | `docs/one-ontology.md` — update dimension/entity |
+| Feature-specific file | `docs/feature.md` — update feature spec |
+
+**Pattern:** If you're adding a new field to a TypeScript interface, add it to the doc that defines that interface. If you're changing a loop, update the loop diagram in the doc.
+
+---
+
+### **W4 — Verify Phase: Check Docs Match Code**
+
+**Docs consistency checklist:**
+
+1. **Terminology** — All renamed concepts updated everywhere
+   ```bash
+   grep -r "old-name" docs/ -- ignore new-name where intentional (dead names)
+   ```
+
+2. **Examples** — Code examples in docs match actual implementation
+   ```
+   - TypeScript interfaces in examples match src/types.ts
+   - TypeQL in examples match src/schema/*.tql
+   - Function signatures match actual exports
+   ```
+
+3. **Cross-references** — Links don't 404
+   ```
+   - [dictionary.md](dictionary.md) exists and links back to source
+   - Code file references match real paths (no moved files)
+   ```
+
+4. **Metaphor consistency** — 7-skin mappings still valid
+   ```
+   - Ant: pheromone/strength/resistance → brain: synapse/weight
+   - Team: signal/mark → org: decision/approval
+   - Check metaphors.md if touching path/signal semantics
+   ```
+
+5. **Rubric dimensions** — New quality scoring documented
+   ```
+   - If W4 adds a rubric dimension (e.g., "documentation"), it goes in rubrics.md
+   - Scoring rules and edge cases documented
+   ```
+
+---
+
+## Which Docs Are Always in Scope
+
+These six docs are the **source of truth** and must stay in sync with code:
+
+| Doc | Locks | Update when |
+|-----|-------|-------------|
+| **dictionary.md** | Canonical names, types, entities | Any naming change |
+| **DSL.md** | Signal grammar, mark/warn/fade verbs | Signal behavior changes |
+| **one-ontology.md** | 6 dimensions, actor/group/thing/path/signal/hypothesis | Type system changes |
+| **routing.md** | L1-L7 loops, signal flow, priority formula | Loop/routing changes |
+| **lifecycle.md** | Agent journey stages, revenue flow | Lifecycle/economic changes |
+| **rubrics.md** | Code rubric (security/stability/simplicity/speed) + agent rubric (fit/form/truth/taste) | Rubric changes or new dimensions |
+
+**Feature-specific docs** (rich-messages.md, webhooks.md, etc.) are updated per feature. Always link back to the six core docs.
+
+---
+
+## The Workflow Integration
+
+### Hook: Pre-W2 — Load Source Docs
+
+When a TODO is created, auto-load relevant source docs:
+
+```
+/do {name}-todo.md
+├─ [Hook] Load: dictionary.md, DSL.md, rubrics.md
+├─ [W1] Recon code (reads files)
+├─ [W2] Decide code + **document changes needed in docs**
+│       (explicit list: what terms change, what loops change, what's new)
+├─ [W3] Edit code (spawns Sonnet agents)
+│       + [Hook] Suggest: "Also edit X doc for {Y change}"
+└─ [W4] Verify code + **verify docs match** (cross-check task)
+```
+
+### Hook: Post-W4 — Validate Doc Consistency
+
+After W4 completes, auto-run consistency checks:
+
+```bash
+# Terminology consistency
+grep -r "old-term" docs/ | flag if > 0 (not on deadname list)
+
+# Cross-references
+markdown-link-check docs/*.md
+
+# Metaphor alignment (if touching signal/path semantics)
+grep -l "signal\|strength\|resistance" src/changed-files.txt | xargs -I {} \
+  check if metaphors.md still applies
+
+# Rubric scoring (if W4 added dimensions)
+grep "rubric\|dimension" src/changed-files.txt | flag for rubrics.md review
+```
+
+---
+
+## Example: rich-messages-todo (Retrospective)
+
+**What should have happened (W2):**
+
+```markdown
+### Documentation Updates (W2)
+
+**New docs:**
+- None (extends existing types)
+
+**Docs modified:**
+- `docs/dictionary.md` — add "Rich Messages" section, explain `data.rich` convention
+- `docs/rich-messages.md` — add PaymentMetadata type, Payment flow section
+- `docs/template-todo.md` — add "Documentation Updates (W2 + W4)" section
+
+**Schema changes:**
+- `nanoclaw/src/types.ts` — RichMessage.thread, RichMessage.payment added (Cycle 1 & 3)
+- `migrations/0010_payment_columns.sql` — new D1 columns for payment tracking
+```
+
+**What actually happened:**
+
+- ✅ Docs updated (rich-messages.md, dictionary.md, template-todo.md) — **AFTER W4**
+- ⚠️ Should have been planned in W2, preventing surprises in W3
+
+**Lesson:** Next TODO follows: document in W2, edit in W3, verify in W4. No surprises.
+
+---
+
+## Rules for `/do` (The Command)
+
+When running `/do {name}-todo.md`, the workflow enforces:
+
+1. **W2 must explicitly call out doc changes** — no surprise doc edits in W3
+2. **W3 spawns edit agents for both code AND docs** — parallel edits
+3. **W4 includes doc consistency check** — not just code tests
+4. **The code rubric (security/stability/simplicity/speed) applies to docs too** — simplicity means fewer words; stability means no broken links; security means no sensitive data exposed; speed means lean docs = fewer tokens to read
+
+---
+
+*Documentation is not a post-mortem. It's the blueprint. Build it first. Verify it matches.*
+
+---
+
+## Loop Close — propagate matrix (inlined, no separate file)
+
+`/close` runs this matrix automatically after rubric + feedback signal. Each row is a bash + Edit-tool dispatch, zero agent spawns.
+
+| Trigger (detected from W3 diff) | Target doc | Edit |
+|---|---|---|
+| any change | source-of-truth doc(s) from plan frontmatter | always — even if only touch-verified |
+| 6-dim, L1-L8, or locked-rule change | root `CLAUDE.md` | edit the relevant section |
+| directory contract change (new component family, new pattern) | nearest `CLAUDE.md` (e.g., `one.ie/web/src/components/CLAUDE.md`) | append / edit section |
+| public surface change (new CLI verb, API route family, SDK export, MCP tool) | root `README.md` + feature doc | append row(s) |
+| feature doc named in plan | feature doc | sync verb/component/endpoint counts |
+| rename across W3 | every `**/*.md` containing old name | inline replace (auto-grep) |
+
+Anchor mismatch → log to `docs/improvements.md` for manual W2 next cycle (no halt — the cycle still closes; the propagate task surfaces next iteration).
+
+**Learnings entry** (append to `docs/learnings.md` on each close):
+
+```
+- YYYY-MM-DD · cycle N · wave N|gate · {one sentence} · rubric=0.NN · source=w1|w2|w3|w4|cycle
+```
+
+W4 code rubric applies to docs too: security (no sensitive data), stability (no broken links, accurate references), simplicity (fewer words, no bloat), speed (lean = fewer tokens to read).
+
+### W4 doc-sync hard gate (zero LLM)
+
+W4 must pass three bash checks before the rubric runs. Detail in `.claude/commands/do.md` W4 section. Summary:
+
+1. **stale-name check** — every old identifier in W3's rename list has 0 hits in `**/*.md`
+2. **broken-link check** — `markdown-link-check` on every touched doc returns 0 broken
+3. **contract-staleness check** — every dir whose code was touched has `CLAUDE.md` mtime ≥ newest code mtime
+
+Any fail → cycle does NOT close. No rubric until docs match code.