Cross-repo dispatch + spec-lint CI

- run-overnight.sh: auto-detect **Repo:** headers and dispatch each spec to its target
  repo (sage/MSD/pear/nightcto/self) on a results/<program> branch, one draft PR per
  touched repo. Single-repo per-wave behavior preserved when no **Repo:** headers exist.
  Repo paths overridable via PROJECTS_ROOT / REPO_<slug>.
- Add **Repo:** slug to all 14 specs.
- scripts/lint-specs.sh + .github/workflows/lint-specs.yml: fail if any numbered spec is
  missing required sections or a valid **Repo:** header.
- README: document dispatch routing + the lint/CI guard.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: khaliqgant

.github/workflows/lint-specs.yml

@@ -0,0 +1,23 @@
+name: lint-specs
+
+# Guards the spec format the overnight runner + reviewer depend on: every numbered
+# spec must carry the required sections and a valid **Repo:** dispatch header.
+
+on:
+  push:
+    paths:
+      - 'specs/**'
+      - 'scripts/lint-specs.sh'
+      - '.github/workflows/lint-specs.yml'
+  pull_request:
+    paths:
+      - 'specs/**'
+      - 'scripts/lint-specs.sh'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Lint specs
+        run: bash scripts/lint-specs.sh

README.md

@@ -72,17 +72,44 @@ Flags / env:
 - `MAX_REVIEW_ITERS` (default 3) — review/fix loop cap
 - `REVIEW_CMD` / `FIX_CMD` — override the reviewer/fixer invocation (default: Ricky local with `_review.md` / `_fix.md`)
 
-### Cross-repo execution (important)
+### Cross-repo dispatch (automatic)
 
-The runner commits in whichever repo it is invoked from. Because storybook is cross-repo:
+Storybook is cross-repo, so each spec declares a machine-readable **`**Repo:**` slug** in its
+header. The runner auto-detects these and switches to **dispatch mode**: each spec is
+implemented in its **target repo** on a `results/storybook` branch, and a draft PR is opened
+**per touched repo** — no manual repo-hopping.
 
-- Build the **shared pieces first** (`@code-story/schema`, `@code-story/skill`, `@code-story/react`)
-  from waves 0–1 and the extract in `030`, publish the package, **then** run the per-product
-  emit/mount specs (waves 2–3) from each target repo — or via Ricky cloud with that repo materialized.
-- The target repo for each spec is in its header and in `PROGRAM.md`'s cross-repo plan.
+Slugs resolve to local repo paths (sibling clones assumed):
 
-Treat each wave (or each target repo's slice of a wave) as a separate Ricky handoff; let the
-review cycle gate each before moving on.
+| slug | resolves to | holds |
+|---|---|---|
+| `code-storybook` | this repo | the shared `@code-story` package (schema, skill, `react` renderer, helper personas) |
+| `sage` | `$PROJECTS_ROOT/sage` | `020` planning story |
+| `my-senior-dev` | `$PROJECTS_ROOT/../My-Senior-Dev/app` | `021` review story, `030` extract, `032` webapp surface |
+| `nightcto` | `$PROJECTS_ROOT/nightcto` | `022` runtime story |
+| `pear` | `$PROJECTS_ROOT/pear` | `031` story view |
+
+`PROJECTS_ROOT` defaults to this repo's parent; override any path with `REPO_<slug>` env
+(e.g. `REPO_my_senior_dev=/path/to/app`). Inspect routing first with `--dry-run`:
+
+```bash
+./scripts/run-overnight.sh storybook --dry-run   # prints START <spec> -> <slug> (<repo>)
+```
+
+Because of dependencies, the shared pieces (waves 0–1 + the `030` extract) build first in
+`code-storybook`; publish `@code-story`, then the per-product specs consume it. The runner
+walks them in order and the review cycle gates each before moving on.
+
+## Spec format & CI
+
+Every numbered spec must carry the sections the runner + reviewer rely on
+(`Goal / In scope / Out of scope / Acceptance / Review / Handoff`) and a valid `**Repo:**`
+slug. `scripts/lint-specs.sh` enforces this and runs in CI (`.github/workflows/lint-specs.yml`)
+on every push/PR touching `specs/`:
+
+```bash
+./scripts/lint-specs.sh        # OK — N specs, all have required sections + a valid **Repo:** header
+```
 
 ## Related
 

scripts/lint-specs.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -uo pipefail
+# Lint every numbered spec for the structure the overnight runner + reviewer rely on.
+# Fails (exit 1) if any spec is missing a required section or the **Repo:** dispatch header.
+# Usage: ./scripts/lint-specs.sh [specs-glob-root]   (default: ./specs)
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SPECS_ROOT="${1:-$ROOT/specs}"
+
+REQUIRED_SECTIONS=("## Goal" "## In scope" "## Out of scope" "## Acceptance" "## Review" "## Handoff")
+REQUIRED_HEADERS=("**Repo:**")   # machine-readable dispatch target
+
+fail=0
+count=0
+# numbered specs only; skip _review.md/_fix.md/PROGRAM.md
+while IFS= read -r f; do
+  count=$((count+1))
+  missing=""
+  for s in "${REQUIRED_SECTIONS[@]}"; do
+    grep -qF "$s" "$f" || missing="${missing}\n    missing section: ${s}"
+  done
+  for h in "${REQUIRED_HEADERS[@]}"; do
+    grep -qF "$h" "$f" || missing="${missing}\n    missing header: ${h}"
+  done
+  # the Repo header must resolve to a known slug
+  if grep -qF "**Repo:**" "$f"; then
+    slug="$(grep -m1 -oE '\*\*Repo:\*\* [A-Za-z0-9_-]+' "$f" | awk '{print $2}')"
+    case "$slug" in
+      code-storybook|sage|nightcto|pear|my-senior-dev) : ;;
+      *) missing="${missing}\n    unknown **Repo:** slug: '${slug}' (allowed: code-storybook|sage|nightcto|pear|my-senior-dev)" ;;
+    esac
+  fi
+  if [ -n "$missing" ]; then
+    fail=1
+    printf 'FAIL %s%b\n' "${f#"$ROOT"/}" "$missing"
+  fi
+done < <(find "$SPECS_ROOT" -type f -name '[0-9][0-9][0-9]-*.md' | sort)
+
+if [ "$count" -eq 0 ]; then echo "No numbered specs found under $SPECS_ROOT"; exit 1; fi
+if [ "$fail" -eq 0 ]; then
+  echo "OK — $count specs, all have required sections + a valid **Repo:** header."
+else
+  echo
+  echo "Spec lint failed. Each numbered spec needs: ${REQUIRED_SECTIONS[*]} and a **Repo:** <slug> header."
+fi
+exit "$fail"