add reveal-gated canon (spoiler scoping) + continuity.premature-reveal check

Canon context is injected into every issue's drafting prompt, so a
withheld character secret or late-story twist could leak into the prose
long before its reveal. Canon entries now carry optional reveal gating:
revealIssue (hide before that issue), spoiler (hard-hide from all
drafting), and surfaceDescriptor (the spoiler-free pre-reveal stand-in).

buildStageContext and the alternate-POV rewrite cast filter canon to each
issue's reveal horizon; the judge and editorial checks keep the full canon
so they can verify hint placement. Absent gate fields = always visible, so
existing entries and federation peers round-trip unchanged.

Adds a reveal-timing editor + spoiler badge to every canon-entry card, and
a continuity.premature-reveal editorial check (gated on any reveal-gated
canon existing) that flags a gated fact leaked before its reveal issue,
distinguishing a leak from deliberate foreshadowing. The reveal issue also
feeds the Chekhov setups-payoffs check as an authored payoff.

Migration 168 seeds the new stage prompt into existing installs.

Closes #2178

Author: atomantic

.changelog/NEXT.md

@@ -26,6 +26,7 @@
 - **[issue-2170] A simulated four-persona reader panel now reads your whole series and shows you where the readers disagree.** Convene the panel from a new **Reader Panel** tab on the Reader Map page (deep-linkable via `?tab=panel`) and four distinct readers — The Editor (prose texture, subtext, over-explaining), The Genre Reader (pacing and page-turn pull, "gets bored by beautiful prose that doesn't GO anywhere"), The Writer (structure, beats, foreshadowing payoff, whose worst insult is "I can see the outline"), and The First Reader (pure emotional response, no craft vocabulary) — each read a condensed, content-hash-pinned arc digest of the series (per-issue summary, opening/closing excerpts, and notable dialogue) and answer the same ten qualitative questions (where momentum is lost, is the ending earned, what to cut, a missing scene, the thinnest character, best/worst scene, would-recommend, what haunts you, would-read-the-next-book), citing specific issue numbers. The editorial signal is where they *disagree*: an issue flagged by 3+ personas is routed straight into your editorial-findings triage flow as a consensus concern; softer some-flagged-some-didn't calls and "polarizing" issues (one persona's best scene is another's worst) are surfaced for your judgment. One LLM call per persona, run only from the explicit Convene button — nothing fires on its own.
 - **[issue-2175] Worldbuilding craft doctrine now shapes universe generation up-front, and two new editorial checks verify it.** The universe-expansion prompt now injects Sanderson's-Laws craft doctrine before the writer model drafts — limitations over powers, costs that drive plot decisions, solutions foreshadowed before they resolve, iceberg depth, interconnected systems, 2–3 societal implications per major system, and a sensory signature per location — so autonomous and interactive runs alike start from a lived-in world instead of decorative set dressing (Series Autopilot calls the same stages, so autonomous mode is upgraded automatically). Two new series-scope editorial checks close the loop on the review side: `world.unforeshadowed-solution` (a plot problem solved by a rule/power the reader was never shown — the worldbuilding sibling of the deus ex machina) and `world.cost-free-power` (an ability used at a decisive moment with no cost or limitation on the page). Both reconcile the prose against the established world canon and the continuity-bible world-rule facts, so a rule that WAS planted earlier is not flagged. (First slice of #2175 — the character-framework and structure-rule pillars ship separately.)
 - **[issue-2179] A series style guide can now carry concrete voice exemplar and anti-exemplar passages — "the tuning fork" — that get injected into every draft and revision prompt.** Adjective lists ("witty, atmospheric") anchor prose voice far more weakly than an actual passage does, so the series style guide gains two new fields: `voiceExemplars` (1–3 short passages that nail the target voice, each with an optional one-line note on what it demonstrates) and `voiceAntiExemplars` (passages in the wrong register kept as negative examples, noted with what's wrong — "too ornate", "wrong emotional temperature"). Add and edit them inline on the series style-guide editor. On generation they render into the house-style block as a "MATCH this voice — echo their rhythm, diction, and register" block and a "NEVER drift toward this" block — conditional, so a guide with no passages injects nothing. They ride the existing `{{series.styleNotes}}` template variable (via `composeStyleNotes`), so prose drafting, revision, arc planning, and episode-seed passes all honor them with no new prompt-template variable and no migration. The sanitizer drops empty passages, trims each to ~2000 chars, and caps the list at 3 so the fixed per-call prompt overhead stays tight. (First slice of #2179 — the AI-assisted voice-discovery flow, Writers Room parity, and the voice-fingerprint baseline hook ship separately.)
+- **[issue-2178] Canon can now be reveal-gated so a mystery or twist doesn't leak into the prose before it's due.** Canon context — including character secrets and late-story facts — was injected into every issue's drafting prompt, so the writer model could (and would) spill a reveal issues early. Each canon entry (character, place, or object) now carries optional reveal gating: a `revealIssue` number hides the fact from any issue before it; a `spoiler` flag hard-hides it from all drafting context; and an optional `surfaceDescriptor` is the spoiler-free stand-in shown before the reveal ("the locked east wing" instead of "the wing where the heir is imprisoned"). The drafting/rewrite prompts (`buildStageContext`, the alternate-POV rewrite cast) filter canon to each issue's reveal horizon, while the judge and editorial checks still receive the full canon so they can verify hint placement. Absent gate fields mean "always visible," so every existing canon entry and every federation peer round-trips unchanged. A reveal-timing editor with a spoiler badge lands on every canon-entry card (universe + series). A new `continuity.premature-reveal` editorial check (gated on the series having authored any reveal-gated canon) scans drafted prose for a gated fact stated or unambiguously implied before its reveal issue, distinguishing a genuine leak from deliberate foreshadowing — and its reveal issue feeds the Chekhov setups-payoffs check as an authored payoff so an orphaned reveal is flagged too.
 
 ## Human Activity Tracking
 

client/src/components/pipeline/CanonCard.jsx

@@ -23,6 +23,7 @@ import CharacterDetailEditor from '../universe/CharacterDetailEditor';
 import ObjectAttachmentsEditor from '../universe/ObjectAttachmentsEditor';
 import CharacterReferenceSheetPanel from '../universe/CharacterReferenceSheetPanel';
 import CharacterLoraChip from '../loraTraining/CharacterLoraChip';
+import Pill from '../ui/Pill';
 import { BIBLE_LIMITS } from '../../lib/bibleLimits';
 
 // Place metadata enums — kept in lock-step with `PLACE_INT_EXT` and
@@ -98,6 +99,113 @@ function ReadonlyChip({ children }) {
   );
 }
 
+// A canon entry is reveal-gated (#2178) when it carries a hard `spoiler` flag
+// or a numeric `revealIssue`. Mirrors the server's `isEntryRevealGated`.
+const isEntryGated = (entry) => entry?.spoiler === true || Number.isInteger(entry?.revealIssue);
+
+// Spoiler badge shown in the card title when an entry is reveal-gated (#2178).
+// Purely informational; the gating itself happens server-side in
+// `buildStageContext`. Uses the shared `Pill` primitive (warning tone).
+function SpoilerBadge({ entry }) {
+  if (!isEntryGated(entry)) return null;
+  const label = entry.spoiler === true ? 'spoiler' : `reveal #${entry.revealIssue}`;
+  const title = entry.spoiler === true
+    ? 'Hard spoiler — hidden from every issue’s drafting prompt'
+    : `Hidden from drafting context until Issue ${entry.revealIssue}`;
+  return (
+    <Pill tone="warning" size="xs" title={title} className="rounded-full uppercase tracking-wider">
+      {label}
+    </Pill>
+  );
+}
+
+// Reveal-timing editor (#2178) — sets when a canon fact may enter a drafting
+// prompt. Applies to every kind. `revealIssue` (int) hides the entry from
+// issues before that number; `spoiler` hard-hides it from all drafting;
+// `surfaceDescriptor` is the pre-reveal stand-in substituted into context.
+// Absent = always visible (backward-compatible default). Labels are
+// `htmlFor`/`id` paired per the accessibility convention.
+function RevealTimingField({ entry, editable, onPatch }) {
+  const idBase = `reveal-${entry.id}`;
+  const surfaceDraft = useFieldDraft(
+    typeof entry.surfaceDescriptor === 'string' ? entry.surfaceDescriptor : '',
+    (v) => onPatch({ surfaceDescriptor: v || null }),
+  );
+  const gated = isEntryGated(entry);
+  if (!editable) {
+    if (!gated) return null;
+    return (
+      <div className="mt-2 flex flex-wrap items-center gap-2 text-[10px] text-gray-500">
+        <span className="uppercase tracking-wider">Reveal:</span>
+        {entry.spoiler === true
+          ? <ReadonlyChip>hard spoiler</ReadonlyChip>
+          : <ReadonlyChip>Issue {entry.revealIssue}</ReadonlyChip>}
+        {entry.surfaceDescriptor
+          ? <span className="italic text-gray-500">surface: {entry.surfaceDescriptor}</span>
+          : null}
+      </div>
+    );
+  }
+  return (
+    <details className="mt-2 group">
+      <summary className="cursor-pointer list-none flex items-center gap-1 text-[10px] uppercase tracking-wider text-gray-500 hover:text-gray-300">
+        <ChevronRight size={11} className="group-open:hidden" />
+        <ChevronDown size={11} className="hidden group-open:inline" />
+        Reveal timing (spoiler scoping)
+        {gated ? <span className="ml-1 text-port-warning normal-case tracking-normal">· gated</span> : null}
+      </summary>
+      <div className="mt-1.5 space-y-2 pl-3 border-l border-port-border">
+        <div className="flex flex-wrap items-center gap-3">
+          <div className="flex flex-col gap-0.5">
+            <label htmlFor={`${idBase}-issue`} className="text-[10px] uppercase tracking-wider text-gray-500">
+              Reveal in issue #
+            </label>
+            <input
+              id={`${idBase}-issue`}
+              type="number"
+              min={1}
+              max={BIBLE_LIMITS.REVEAL_ISSUE_MAX}
+              value={Number.isInteger(entry.revealIssue) ? entry.revealIssue : ''}
+              onChange={(e) => {
+                const v = e.target.value.trim();
+                const n = v === '' ? null : Math.trunc(Number(v));
+                onPatch({ revealIssue: Number.isInteger(n) && n >= 1 ? n : null });
+              }}
+              placeholder="—"
+              className="w-20 px-2 py-1 text-xs bg-port-bg border border-port-border rounded text-gray-200"
+            />
+          </div>
+          <label htmlFor={`${idBase}-spoiler`} className="flex items-center gap-1.5 text-[11px] text-gray-400 mt-3">
+            <input
+              id={`${idBase}-spoiler`}
+              type="checkbox"
+              checked={entry.spoiler === true}
+              onChange={(e) => onPatch({ spoiler: e.target.checked })}
+              className="accent-port-warning"
+            />
+            Hard spoiler (never in drafting)
+          </label>
+        </div>
+        <div className="flex flex-col gap-0.5">
+          <label htmlFor={`${idBase}-surface`} className="text-[10px] uppercase tracking-wider text-gray-500">
+            Surface descriptor (pre-reveal stand-in)
+          </label>
+          <textarea
+            id={`${idBase}-surface`}
+            value={surfaceDraft.value}
+            onChange={surfaceDraft.onChange}
+            onBlur={surfaceDraft.onBlur}
+            rows={2}
+            maxLength={BIBLE_LIMITS.SURFACE_DESCRIPTOR_MAX}
+            placeholder="What the world looks like BEFORE the reveal (e.g. &quot;the locked east wing&quot;). Substituted into drafting context until the reveal issue."
+            className="w-full px-2 py-1 text-xs bg-port-bg border border-port-border rounded text-gray-200 whitespace-pre-wrap"
+          />
+        </div>
+      </div>
+    </details>
+  );
+}
+
 // Collapsible wrapper for the universe-only character details panel
 // (CharacterDetailEditor + CharacterReferenceSheetPanel). Single toggle so the
 // card stays terse by default — the user opens it only when filling in
@@ -346,6 +454,7 @@ export default function CanonCard({
           seriesName={seriesNameMap?.[entry.sourceSeriesId]}
         />
       ) : null}
+      <SpoilerBadge entry={entry} />
     </div>
   );
 
@@ -390,6 +499,13 @@ export default function CanonCard({
           {entry.timeOfDay ? <ReadonlyChip>{entry.timeOfDay}</ReadonlyChip> : null}
         </div>
       ) : null}
+      {/* Reveal-gated canon / spoiler scoping (#2178) — every kind. Editable
+          when a PATCH channel exists and the entry isn't locked. */}
+      <RevealTimingField
+        entry={entry}
+        editable={!!onPatchEntry && !locked}
+        onPatch={(patch) => onPatchEntry?.(entry.id, patch)}
+      />
       {kind.key === 'characters' ? (
         <WardrobeSection
           wardrobes={Array.isArray(entry.wardrobes) ? entry.wardrobes : []}

client/src/components/pipeline/CanonCard.test.jsx

@@ -154,6 +154,69 @@ describe('CanonCard — inline description editor', () => {
   });
 });
 
+describe('CanonCard — reveal timing / spoiler scoping (#2178)', () => {
+  const editableKind = {
+    key: 'characters', label: 'Characters',
+    descFor: (e) => e.physicalDescription || e.description || '',
+    descField: 'physicalDescription', descFieldFallback: 'description', descFieldMax: 2000,
+  };
+
+  it('shows a spoiler badge when the entry has a revealIssue', () => {
+    render_({ entry: { ...baseEntry, revealIssue: 8 } });
+    expect(screen.getByText('reveal #8')).toBeInTheDocument();
+  });
+
+  it('shows a hard-spoiler badge when the entry has spoiler: true', () => {
+    render_({ entry: { ...baseEntry, spoiler: true } });
+    expect(screen.getByText('spoiler')).toBeInTheDocument();
+  });
+
+  it('omits the badge for an ungated entry', () => {
+    render_();
+    expect(screen.queryByText(/^reveal #/)).not.toBeInTheDocument();
+    expect(screen.queryByText('spoiler')).not.toBeInTheDocument();
+  });
+
+  it('PATCHes revealIssue from the number input when editable', () => {
+    const onPatchEntry = vi.fn();
+    render(
+      <CanonCard kind={editableKind} entry={baseEntry} onRender={() => {}} onPatchEntry={onPatchEntry} />,
+    );
+    fireEvent.click(screen.getByText(/Reveal timing/));
+    const input = screen.getByLabelText(/Reveal in issue/);
+    fireEvent.change(input, { target: { value: '8' } });
+    expect(onPatchEntry).toHaveBeenCalledWith('ent-1', { revealIssue: 8 });
+  });
+
+  it('PATCHes spoiler from the checkbox and surfaceDescriptor on blur', () => {
+    const onPatchEntry = vi.fn();
+    render(
+      <CanonCard kind={editableKind} entry={baseEntry} onRender={() => {}} onPatchEntry={onPatchEntry} />,
+    );
+    fireEvent.click(screen.getByText(/Reveal timing/));
+    fireEvent.click(screen.getByLabelText(/Hard spoiler/));
+    expect(onPatchEntry).toHaveBeenCalledWith('ent-1', { spoiler: true });
+
+    const surface = screen.getByLabelText(/Surface descriptor/);
+    fireEvent.change(surface, { target: { value: 'a quiet neighbor' } });
+    fireEvent.blur(surface);
+    expect(onPatchEntry).toHaveBeenCalledWith('ent-1', { surfaceDescriptor: 'a quiet neighbor' });
+  });
+
+  it('renders read-only reveal info when locked (no editor inputs)', () => {
+    render(
+      <CanonCard
+        kind={editableKind}
+        entry={{ ...baseEntry, revealIssue: 5, locked: true }}
+        onRender={() => {}}
+        onPatchEntry={vi.fn()}
+      />,
+    );
+    expect(screen.getByText('Issue 5')).toBeInTheDocument();
+    expect(screen.queryByLabelText(/Reveal in issue/)).not.toBeInTheDocument();
+  });
+});
+
 describe('CanonCard — wardrobe pending-row promotion', () => {
   const renderEditable = (onPatchEntry) => render(
     <CanonCard

client/src/lib/bibleLimits.js

@@ -78,6 +78,9 @@ export const BIBLE_LIMITS = Object.freeze({
   SOURCE_SERIES_ID_MAX: 64,
   VOICE_ID_MAX: 200,
   INGREDIENT_ID_MAX: 64,
+  // Reveal-gated canon / spoiler scoping (#2178).
+  SURFACE_DESCRIPTOR_MAX: 2000,
+  REVEAL_ISSUE_MAX: 100000,
 });
 
 // Client-only helper (the cap *value* IMAGE_REFS_PER_ENTRY_MAX is mirrored from

data.reference/prompts/stage-config.json

@@ -548,6 +548,13 @@
       "returnsJson": true,
       "variables": []
     },
+    "pipeline-editorial-premature-reveal": {
+      "name": "Pipeline — Editorial Check: Premature reveal (spoiler leak)",
+      "description": "Editorial check (#2178): the information-economy guard for reveal-gated canon — flags a deliberately-withheld fact (character secret, late-story twist, hidden identity) that the prose states or unambiguously implies BEFORE its reveal issue, so a first-time reader learns it too early. Reconciles the stitched manuscript against the reveal-gated canon entries (reveal issue / hard-spoiler flag, spoiler-free surface descriptor, and the underlying gated fact) and distinguishes a genuine leak from deliberate foreshadowing, flagging only leaks. Returns issue-anchored findings.",
+      "model": "default",
+      "returnsJson": true,
+      "variables": []
+    },
     "pipeline-editorial-world-unforeshadowed-solution": {
       "name": "Pipeline — Editorial Check: Unforeshadowed solution",
       "description": "Editorial check (#2175): the worldbuilding sibling of the deus ex machina — flags a story problem resolved by a rule, power, property, or artifact the reader was never shown before it saved the day (Sanderson's First Law). Reconciles the stitched manuscript against the established world canon (artifacts/objects + places) and the continuity-bible world-rule facts, so a rule that WAS planted earlier is not flagged; the whole-arc verdict lands on the final part with earlier plants carried in the setup digest. Returns issue-anchored findings.",