Rework to hybrid: self-contained Phase 1 + deferred Phase 2

Phase 1 (specs/storybook/, single-repo, no product edits):
- pull/watch instead of push: a story-builder watcher persona (020) synthesizes
  planning/review/runtime stories (021/022/023) from artifacts products already write to
  relayfile (/notion,/linear, /github/**/reviews, /nightcto/signals) — zero changes to
  sage/MSD/nightcto/pear.
- renderer @code-story/react (030) vendored from MSD's tokenizer/diffUtils/PRStory (one-time
  copy, no MSD import); standalone web viewer (031) + guided tour (032) as the Phase 1 surface.
- drop the per-repo **Repo:** slugs from Phase 1 -> single-repo per-wave mode.

Phase 2 (specs/storybook-phase2/, DEFERRED, cross-repo dispatch):
- per-product emit hooks for richer stories (sage 010, MSD 020, nightcto 030) and inline
  embeds (MSD webapp 021, Pear 040), each with a **Repo:** slug.

Also: lint treats **Repo:** as optional (validated only if present); README + PROGRAM updated.

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

Author: khaliqgant

README.md

@@ -8,46 +8,51 @@ metrics (churn, hotspots, coverage). Agents do the writing; humans read and stay
 This repo holds the **spec program** and the **runbook**. It is built spec-by-spec by Ricky
 (the workflow agent) via an overnight runner — not hand-written all at once.
 
-## How it works
+## Two phases
 
-```
-Sage / MSD / NightCTO workflows
-   │  (call the shared story-writer skill as a side-effect of their work)
-   ▼
-@code-story/skill  ──writes──▶  relayfile  /stories/<type>/<id>.json   (the artifact)
-                                    ▲   ▲
-              code-narrator persona ┘   └ code-health persona (churn/hotspots/coverage)
-                                    │
-                    @code-story/react  (one shared, artifact-driven, read-only renderer,
-                       ▲ extracted from MSD's renderer + PRStory)
-        ┌──────────────┼───────────────┐
-   MSD webapp      Pear `story`     web guided tour (stepped)
-   (primary web)   view mode        hosted by MSD webapp + Pear
-```
+- **Phase 1 — self-contained (default).** Everything lives in this repo. A **watcher** persona
+  synthesizes stories from artifacts products *already* write to relayfile (pull, not push), and
+  a **standalone web viewer** renders them. **Zero changes to sage/MSD/nightcto/pear.** One repo,
+  one deploy, per-wave PRs. → `specs/storybook/`
+- **Phase 2 — deferred, cross-repo (optional).** When you want *richer* stories (products emit
+  with their internal context) or stories rendered *inline* inside Pear/MSD, edit those repos.
+  Cross-repo, so it runs via dispatch mode. → `specs/storybook-phase2/`
+
+Start with Phase 1; reach for Phase 2 only where the extra richness/inline-surface pays off.
 
-- **relayfile** is the artifact substrate — stories are JSON files; "the filesystem is the protocol."
-- The **renderer is extracted from MSD** (custom tokenizer highlighting, `diffUtils`, and the
-  `PRStory` slide-deck), generalized into one backend-free `@code-story/react` package that MSD's
-  webapp, Pear, and the web tour all consume — so no surface reimplements code rendering.
-- Two helper **personas** (narrator, health) enrich stories; the three product agents emit them.
+## How Phase 1 works
 
-See [`specs/storybook/PROGRAM.md`](specs/storybook/PROGRAM.md) for the full architecture and
-[`docs/storybook-boundary.md`] (produced by spec `000`) for the frozen scope.
+```
+products already write to relayfile (no storybook code in them):
+   Sage → /notion,/linear   MSD → /github/**/reviews   NightCTO → /nightcto/signals
+                       │ (the watcher OBSERVES these)
+                       ▼
+   personas/story-builder ─synthesize→ @code-story/skill ─writes→ /stories/<type>/<id>.json
+                                            ▲   ▲
+                      code-narrator persona ┘   └ code-health persona (churn/hotspots/coverage)
+                                            │
+                                 @code-story/react (read-only renderer, vendored from MSD)
+                                            │
+                                 web/ standalone viewer + guided tour   ◀── the Phase 1 surface
+```
 
-## Why its own repo
+- **relayfile** is the substrate *and* the integration: the watcher reads files products already
+  produce, so Phase 1 touches no other repo. "The filesystem is the protocol."
+- The renderer is **vendored from MSD** (its tokenizer highlighting, `diffUtils`, and the `PRStory`
+  slide-deck) into one backend-free `@code-story/react` — a one-time copy, no MSD import/edit.
 
-Storybook spans repos — Sage, MSD, Pear, and a shared `@code-story` package all participate.
-It does not belong inside any one of them, so the spec program + orchestration live here.
+See [`specs/storybook/PROGRAM.md`](specs/storybook/PROGRAM.md) for the architecture and
+`docs/storybook-boundary.md` (produced by spec `000`) for the frozen scope.
 
-## Spec program (14 specs, 5 waves)
+## Phase 1 spec program (14 specs, 5 waves — all in this repo)
 
-| Wave | Specs | Target |
-|---|---|---|
-| 0 — Contract | `000` boundary · `001` `CodeStory` schema | shared `@code-story` |
-| 1 — Writer | `010` story-writer skill · `011` index + ACL | shared `@code-story` |
-| 2 — Emit | `020` Sage planning · `021` MSD review · `022` NightCTO runtime | sage · My-Senior-Dev/app · nightcto |
-| 3 — Renderer | `030` extract `@code-story/react` from MSD · `031` Pear mount · `032` MSD webapp surface · `033` web tour | My-Senior-Dev/app → shared · pear |
-| 4 — Narrate/health/proof | `040` narrator persona · `041` health persona · `042` e2e proof | shared (cross-repo e2e) |
+| Wave | Specs |
+|---|---|
+| 0 — Contract | `000` boundary · `001` `CodeStory` schema |
+| 1 — Library | `010` story-writer skill · `011` index + ACL |
+| 2 — Watcher | `020` story-builder · `021` planning synthesis · `022` review synthesis · `023` runtime synthesis |
+| 3 — Renderer + viewer | `030` `@code-story/react` (vendored) · `031` standalone viewer · `032` guided tour |
+| 4 — Narrate/health/proof | `040` narrator persona · `041` health persona · `042` e2e proof |
 
 Each spec is bounded (`Goal / Context / In scope / Out of scope / Acceptance / Review / Handoff`)
 and ends with a reviewer-checkable PASS gate.
@@ -59,60 +64,47 @@ Specs are implemented one at a time by Ricky, in dependency order, with an
 `specs/storybook/_review.md` / `_fix.md`).
 
 ```bash
-# inspect the plan (no side effects)
-./scripts/run-overnight.sh storybook --dry-run
-
-# run it: implement → review → fix each spec, commit, open a draft PR per wave
-./scripts/run-overnight.sh storybook
+# Phase 1 (self-contained, single repo, per-wave PRs)
+./scripts/run-overnight.sh storybook --dry-run    # inspect the plan (no side effects)
+./scripts/run-overnight.sh storybook              # implement → review → fix, commit, PR per wave
 ```
 
 Flags / env:
 - `--from <spec-id>` — resume from a spec (e.g. `--from 030`)
 - `--no-pr` — skip per-wave draft PRs
 - `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 dispatch (automatic)
-
-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.
-
-Slugs resolve to local repo paths (sibling clones assumed):
+- `REVIEW_CMD` / `FIX_CMD` — override the reviewer/fixer invocation
 
-| 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 |
+### Phase 2 (deferred, cross-repo dispatch)
 
-`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`:
+Phase 2 specs declare a machine-readable `**Repo:**` slug; the runner auto-detects these and
+switches to **dispatch mode** — each spec is implemented in its target repo on a
+`results/storybook-phase2` branch, one draft PR **per touched repo**.
 
 ```bash
-./scripts/run-overnight.sh storybook --dry-run   # prints START <spec> -> <slug> (<repo>)
+./scripts/run-overnight.sh storybook-phase2 --dry-run   # prints START <spec> -> <slug> (<repo>)
+./scripts/run-overnight.sh storybook-phase2
 ```
 
-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.
+Slugs resolve to local repo paths (sibling clones assumed): `sage`, `nightcto`, `pear` →
+`$PROJECTS_ROOT/<slug>`; `my-senior-dev` → `$PROJECTS_ROOT/../My-Senior-Dev/app`. `PROJECTS_ROOT`
+defaults to this repo's parent; override any path with `REPO_<slug>` (e.g. `REPO_my_senior_dev=…`).
+Phase 2 depends on Phase 1 being merged and `@code-story` published.
 
 ## 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/`:
+(`Goal / In scope / Out of scope / Acceptance / Review / Handoff`). A `**Repo:**` slug is
+**optional** (Phase 1 omits it; Phase 2 requires it for dispatch) and, when present, must be a
+valid slug. `scripts/lint-specs.sh` enforces this 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
+./scripts/lint-specs.sh        # OK — N specs, all have required sections (and any **Repo:** slug is valid)
 ```
 
 ## Related
 
 - `AgentWorkforce/nightcto` → `specs/persona-migration/` — the reference persona migration this
-  storybook program assumes (NightCTO emits runtime stories from its migrated watch handler).
+  program assumes (NightCTO writes the `/nightcto/signals/**` the runtime synthesizer reads).
 - `AgentWorkforce/nightcto` → `specs/INVENTORY.md` — front door indexing both programs.

scripts/lint-specs.sh

@@ -8,7 +8,8 @@ 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
+# **Repo:** is OPTIONAL: single-repo (Phase 1) specs omit it; cross-repo (Phase 2) specs
+# carry it for dispatch. When present it must resolve to a known slug (checked below).
 
 fail=0
 count=0
@@ -19,10 +20,7 @@ while IFS= read -r f; do
   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
+  # **Repo:** is optional; if present it 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
@@ -38,9 +36,9 @@ 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."
+  echo "OK — $count specs, all have required sections (and any **Repo:** slug is valid)."
 else
   echo
-  echo "Spec lint failed. Each numbered spec needs: ${REQUIRED_SECTIONS[*]} and a **Repo:** <slug> header."
+  echo "Spec lint failed. Each numbered spec needs: ${REQUIRED_SECTIONS[*]}. (A **Repo:** slug is optional but must be valid if present.)"
 fi
 exit "$fail"

specs/storybook-phase2/010-sage-planning-emit.md

@@ -0,0 +1,34 @@
+# 010 — Sage planning emit (richer)
+
+**Status:** DEFERRED | **Phase:** 2 | **Repo:** sage | **Depends on:** Phase 1 (`@code-story` published)
+
+## Goal
+Make Sage emit a planning `CodeStory` directly from its issue pipeline, carrying its **internal**
+S/M/L rationale and reuse/conflict analysis as first-class data — richer than what Phase 1's
+watcher can synthesize by observing Sage's relayfile outputs.
+
+## Context
+Phase 1 (`specs/storybook/021`) already produces a planning story by reading Sage's spec/Linear/
+Notion artifacts. This spec upgrades that for Sage specifically: Sage calls the `@code-story`
+writer at proposal time with data it has in-process but doesn't fully persist (sizing rationale,
+candidate reuse targets). When Sage emits, the watcher defers to the emitted story (dedupe by subject).
+
+## In scope
+- Add `@code-story` (skill) as a sage dependency.
+- After Sage synthesizes a proposal, build + `.write()` a planning story with: narrative (proposal + S/M/L rationale), ascii arch diagram, code refs for reuse candidates, links (Slack/Linear/Notion).
+- Mark the story so the Phase 1 watcher skips synthesizing a duplicate for that subject.
+- Test: a fixture Sage proposal emits a schema-valid planning story richer than the observed-synthesis baseline.
+
+## Out of scope
+- Changing Sage's planning logic. Rendering. Other layers.
+
+## Acceptance
+- Sage's planning-emit test passes; story validates against `@code-story/schema`.
+- The watcher does not also synthesize a duplicate planning story for the same subject.
+
+## Review
+Reviewer confirms emission is best-effort (never breaks the proposal), the dedupe prevents
+double stories, and the emitted story is genuinely richer than the Phase 1 baseline. PASS on green tests.
+
+## Handoff
+Supersedes Phase 1 `021` for Sage-originated planning stories.

specs/storybook-phase2/020-msd-review-emit.md

@@ -0,0 +1,33 @@
+# 020 — MSD review emit (richer)
+
+**Status:** DEFERRED | **Phase:** 2 | **Repo:** my-senior-dev | **Depends on:** Phase 1 (`@code-story` published)
+
+## Goal
+Make MSD emit a review `CodeStory` from its review flow, carrying its own prioritized findings,
+merge-readiness verdict, and blocker explanations — richer than Phase 1's watcher synthesis from
+`/github/**/reviews/**`.
+
+## Context
+Phase 1 (`specs/storybook/022`) synthesizes a review story by observing PR reviews in relayfile.
+MSD has more in-process (finding priority, merge-readiness, autofix eligibility); this spec emits
+that directly. When MSD emits, the watcher defers (dedupe by PR subject).
+
+## In scope
+- Add `@code-story` (skill) as an MSD dependency.
+- After a review completes, build + `.write()` a review story: diff sections, prioritized findings narrative, merge-readiness verdict, code refs, links (PR + upstream planning story if traced).
+- Mark the story so the Phase 1 watcher skips the observed-synthesis duplicate.
+- Test: a fixture review emits a schema-valid review story richer than the baseline.
+
+## Out of scope
+- Changing MSD's review/autofix logic. The webapp embed (`021`). Other layers.
+
+## Acceptance
+- MSD's review-emit test passes; story validates against `@code-story/schema`.
+- No duplicate observed-synthesis story for the same PR.
+
+## Review
+Reviewer confirms emission reuses MSD's existing findings (no re-review), is best-effort, dedupe
+holds, and the emitted story is richer than the Phase 1 baseline. PASS on green tests.
+
+## Handoff
+Supersedes Phase 1 `022` for MSD-originated review stories; `021` can surface them in MSD's webapp.

specs/storybook-phase2/021-msd-webapp-embed.md

@@ -0,0 +1,33 @@
+# 021 — MSD webapp inline embed
+
+**Status:** DEFERRED | **Phase:** 2 | **Repo:** my-senior-dev | **Depends on:** Phase 1 (`@code-story/react` published)
+
+## Goal
+Mount `@code-story/react` inside MSD's webapp so stories render **inline** in MSD's product UI,
+not only in the standalone viewer — and link a PR's review story from MSD's existing PR view.
+
+## Context
+The renderer was vendored *from* MSD in Phase 1 (`specs/storybook/030`), so MSD re-consuming it
+as a package keeps its review UI and the storybook DRY. MSD webapp: React 18 + Vite + `vite-react-ssg`
++ Tailwind 4. Stories load from relayfile (read scope), so planning/runtime stories render too.
+
+## In scope
+- Add `@code-story/react` + `@relayfile/sdk` to the webapp.
+- A `/stories` route: list (via `listStories`) + a story page mounting `<StoryView>` / `<StoryTour>`.
+- `onOpenRef` opens the file read-only via MSD's existing file viewer (reuse, don't rebuild).
+- Link the review story from the existing PR view when one exists.
+- Test: `/stories` renders a fixture story of each type via the shared renderer.
+
+## Out of scope
+- Refactoring MSD's `FileDetailModal`/backend. The standalone viewer (Phase 1 `031`). Auth beyond the relayfile read scope.
+
+## Acceptance
+- MSD webapp builds with `@code-story/react`; `/stories` renders one story of each type.
+- Stories load from relayfile, not the MSD backend API.
+
+## Review
+Reviewer confirms the webapp consumes the shared package (no second renderer), stories load via
+relayfile (decoupled from MSD's PR backend), and read-only holds. PASS on green build + test.
+
+## Handoff
+MSD users get inline storybooks; the standalone viewer remains the cross-product surface.

specs/storybook-phase2/030-nightcto-runtime-emit.md

@@ -0,0 +1,34 @@
+# 030 — NightCTO runtime emit (richer)
+
+**Status:** DEFERRED | **Phase:** 2 | **Repo:** nightcto | **Depends on:** Phase 1 (`@code-story` published)
+
+## Goal
+Make NightCTO emit a runtime `CodeStory` from its incident handler at incident time, carrying
+triage internals (rationale, urgency, hotfix reasoning) — richer than Phase 1's watcher synthesis
+from `/nightcto/signals/**`.
+
+## Context
+Phase 1 (`specs/storybook/023`) synthesizes a runtime story by observing the signals/feature-log
+NightCTO already writes (per the persona-migration). This spec emits a richer story inline in the
+watch handler, with data it has at triage time. When NightCTO emits, the watcher defers (dedupe by incident).
+
+## In scope
+- Add `@code-story` (skill) as a nightcto dependency (its `personas/watch` handler).
+- In the high-urgency incident path, build + `.write()` a runtime story: incident + triage rationale narrative, implicated code refs, hotfix diff if any, links (source alert, hotfix PR, upstream review/feature).
+- Mark the story so the Phase 1 watcher skips the observed-synthesis duplicate.
+- Test: a fixture incident emits a schema-valid runtime story richer than the baseline; correlated incident links the upstream review.
+
+## Out of scope
+- Changing triage/hotfix logic (the persona-migration owns it). Rendering. Other layers.
+
+## Acceptance
+- NightCTO's runtime-emit test passes; story validates against `@code-story/schema`.
+- No duplicate observed-synthesis story for the same incident.
+
+## Review
+Reviewer confirms emission reuses the migration's incident/triage output (no re-derivation), is
+best-effort (never blocks the alert), dedupe holds, and the emitted story is richer than the
+Phase 1 baseline. PASS on green tests.
+
+## Handoff
+Supersedes Phase 1 `023` for NightCTO-originated runtime stories; closes the richest plan→review→runtime loop.