Publication Pipeline

How truth becomes published destination data. Read with the Publication Model and the Data Contract. The pipeline is deterministic, gated, and versioned — it obeys the same phase-gated, human-approved discipline as the rest of the ecosystem (Principle 10, O2/O8).

1 · The stages

graph TD
  R["① Source repositories"] --> D["② Digests (markdown estate)"]
  IP["① Intelligence Platform (FIP)"] -. awaiting .-> D
  D --> G["③ Portfolio Graph — build-graph.mjs"]
  G --> H["④ Health Engine — build-health.mjs"]
  G --> P["⑤ Publication generators"]
  H --> P
  ED["② Editorial Source Layer<br/>content/editorial/** (Claude-owned)"] --> P
  P --> V{"⑥ Validation gate"}
  V -->|fail| P
  V -->|pass| CLASS{"⑦ Approval routing<br/>by publicationClass"}
  CLASS -->|reference / generated<br/>(no new claims)| AUTO["⑦a Auto-publishable"]
  CLASS -->|editorial / claim-bearing| HUM{"⑦b Human approval"}
  CLASS -->|structural| ADR{"⑦c Human + ADR"}
  HUM -->|changes| P
  AUTO --> PUB["⑧ Publish — versioned publication/**"]
  HUM -->|approved| PUB
  ADR -->|accepted| PUB
  PUB --> LOV["⑨ Lovable consumes (version-pinned)"]
  LOV --> SITE["⑩ Published site"]
  LIVE["live/** (RESERVED)<br/>mutable · TTL · unattended"] -. future .-> LOV
  classDef g fill:#eee,stroke:#bbb,stroke-dasharray:4 3,color:#333;
  class IP,LIVE g;

Editorial Source Layer is now a first-class input at stage ②, a sibling of the estate (model §7). Authored narrative is Claude-owned; it is never authored in Lovable.

2 · Triggers (when the pipeline runs)

Regeneration rule: generators are pure functions of their inputs. Re-running with an unchanged estate commit + graph hash yields byte-identical feeds (no Date.now(); generatedAt is stamped only at ⑧). This makes diffs meaningful and caching safe.

Dependency order (never skip): estate → graph → health → feeds. A feed is never generated from an estate that hasn’t been re-graphed; the manifest records the graphHash/estateCommit each feed was built from.

3 · Approval gates (routed by publication class)

The validation gate is always mandatory; the approval gate depends on the feed’s publicationClass (model §8). This lets deterministic no-claim feeds publish unattended (enabling scheduled publishing) while every claim-bearing/editorial feed still requires a human — nothing customer-facing auto-ships.

1. Validation gate (⑥, automated, always). All acceptance tests in Publication Validation must pass. A single failure blocks publish, regardless of class.
2. Approval routing (⑦):
   • ⑦a Auto-publishable — publicationClass ∈ {reference, generated} (pure projections, no new claims: reference-library, navigation, routes, canonical/spine, health snapshot, engineering-manual). Publishes on trigger without per-run human sign-off — the contract was approved once; the data adds no claim. This is the hook for scheduled publishing.
   • ⑦b Human-approved — publicationClass ∈ {editorial, claim-bearing} (arrival, story, flagship-experiences, evidence-plates, intelligence-products). The founder reviews the diff and approves. Mirrors “nothing auto-sent” (O2); AI drafts, a human accepts (AI Governance).
   • ⑦c Human + ADR — publicationClass:"structural" (tier promotion, new feed, schema shape change) requires an ADR before publish (ADR practice).
3. Live feeds (reserved). A future feedClass:"live" feed has its contract human-approved once; individual updates then flow unattended under a TTL — it is not part of the immutable publication/ publish cycle and lives under live/. None exist today.

4 · Publish steps (⑧)

1. Freeze inputs — record estateCommit, graphHash, healthHash.
2. Generate every feed into a staging publication/ tree.
3. Validate (gate ⑥). Abort on any failure.
4. Version — bump each changed feed’s version (semver); publication set version bumps. Versions are immutable — a published version is never rewritten; a change is a new version (supersede, never mutate — Principle 3, O9).
5. Stamp generatedAt and compute each feed’s hash.
6. Write manifest.json with all feed versions/statuses/hashes.
7. Approve (gate ⑦) — the founder signs off the staged set.
8. Publish — the approved publication/** becomes the canonical set Lovable pins.
9. Log — append a changelog entry (current-state/changelog).

5 · How Lovable consumes (⑨)

• Lovable loads manifest.json, then the feeds it needs, pinned to the published version.
• It renders only what the feeds contain, honouring status/missing (placeholders for awaiting/planned).
• It resolves all links through routes.json (no hard-coded URLs).
• It never writes back — the boundary is one-way (truth → presentation).

6 · Failure & rollback

• Validation failure: publish aborts; the previous published version remains canonical (Lovable unaffected).
• Bad data discovered post-publish: correct the estate → regenerate → publish a new version; never edit a published version in place. Lovable re-pins when ready.
• Awaiting feed goes stale: an awaiting feed is valid indefinitely (empty + status). No failure; it simply hasn’t been promoted.

7 · What the pipeline must never do

• Generate a feed from unreviewed estate, or skip the graph step.
• Publish without validation + human approval.
• Mutate a published version in place.
• Emit a claim without provenance, or upgrade a planned/awaiting item to live without its source landing.