Atlas — the master plan (live)

STATUS: 🟢 ACTIVE · Live window + roadmap = POINTERS (DN-145): the window-id lives in the docs/INDEX.md §2 ATLAS row; the FULL remaining roadmap lives in docs/atlas/HANDOFF.md §Forward-plan — this file is the lane's stable plan record, not the live board. Through ATLAS-AUG16-01 (2026-08-16) the walk phase ran the RECONCILIATION ARC: the family-reconciliation surface + schema view + decision gallery; the family MECHANISM taken provisionally; DN-223 (performance ad re-homed · public-service ad retired) + DN-224 (2026-08-17: 'Brand & Identity' named · recruitment ad dropped → 64 ratified types · identity review live) · the Works & Groupings pillar is RENAMED Groupings (2026-08-17, Joe's lean). · Boot: docs/atlas/HANDOFF.md or /resume-session ATLAS · Decisions of record: DN-213 (the lane + deploy) · DN-214 (plain language, Vale-enforced) · DN-215 (lane-generic guards · diagrams-not-components · generated examples) · DN-217 (both page shapes — superseded by DN-220/Q17: the SPLIT won, the combined page + its generator are deleted) · DN-218 (the FOUR SURFACES — a model page carries no open question and no bare number) · DN-219/DN-220 (the two walk rounds — all 25 questions + the three preliminary calls RULED) · DN-221 (both vocabularies RATIFIED — content types + the channel stack). Every line in this file is current. The superseded planning narrative (the pre-rename phase list, the abandoned separate-Vercel-project runbook, the old "W2 fold-in" framing) is preserved verbatim at _research/PLAN-HISTORY.md — read it only for provenance. There is deliberately no "ignore everything below" banner here: a plan you have to mentally filter is the drift problem, not a fix for it.

What Atlas is, and why it exists

BrandTrackers is a library of brand and marketing work. The logic of how its pieces fit together — what a company is versus a product, what a campaign gathers, what a "moment" is — lived in scattered documents and in Joe's head, and kept getting re-explained. Atlas is the one place that logic lives, written so that both a person and an LLM can read it, with every fact traceable to the live database.

Founding brief: docs/reference/2026-07/2026-07-24/bigprompt-arch.md.

★ What the model is designed against (Joe — governs every pillar)

We design for the shape we are scaling to, not around the gaps in today's data. Only one pipeline exists and it handles content; the entity, campaign and brand-and-identity pipelines are implied by the model and unbuilt, which is where most apparent thinness comes from. "There are ghost rows, you'll break the wiring" and "campaigns are barely tagged" are both true and both about work we have already decided to redo. Structure is the expensive thing to change later; data is the cheap thing to backfill.

A failing conformance check is one of three things: the model is wrong · the build is wrong · the work has not been done yet. Only the first two are defects.

§0 REDLINES — locked by Joe (apply throughout, every pillar)

• ACTORS → ENTITIES (Joe's word + the table name).
• "ontological family" vs "group-by lens" — family = what a thing IS (Entities · Works · Groupings · Concepts); lens = how the product SLICES (by industry/audience/channel/campaign/discipline). Keep distinct.
• Placement: Audience, positioning (sector/industry/category), channel = Concepts (axes + lenses), NOT containers. Groupings = real-world containers you can point at (campaign · project · event · brand-identity). Test: Grouping = "a thing that happened/exists"; Concept = "an axis you classify against."

How Atlas is written (binding)

docs/atlas/STYLE.md is the standard and Vale enforces it at commit on reader pages (index.md + pillars/**): plain language, full sentences, define terms, no internal codes, no raw database ids, no file:line citations. Exact machine facts go in the data reference. Internal notes (this file, PRD, README, _research/) keep their shorthand and are quarantined in the site's "Internal notes" section.

FOUR SURFACES (DN-218) — the binding rule. A page answers exactly one kind of question. The test for any sentence you write is "what would have to happen for this to change?": a decision is ratified → the model page · the pipeline runs → scripts/atlas-state.py (generated) · model and reality disagree → scripts/atlas-conformance.py (a CHECK, not prose) · not yet settled → docs/atlas/decisions/open-questions.md. So a model page contains no unresolved question and no bare number. scripts/atlas-canon-check.sh enforces it and names the offending line; it runs in close-check.sh.

Every pillar follows the Entities pattern (docs/atlas/pillars/entities.md is the exemplar), which is now five parts: plain definition → clickable mermaid relationship map → the vocabulary and the rules (what the values ARE, never how many) → a real worked example generated from live data (scripts/atlas-examples.py) → "where to look next": the four pointers (state of the data · conformance · open questions · data reference). Relationships are mermaid diagrams, never Vue components — llms-full.txt is generated from the markdown, so a component would be invisible to the LLM reader. Keep every diagram node label to at most two lines; a third renders clipped.

⚠ This paragraph previously described a superseded pattern ("where it breaks today" → "what's still open"), which DN-218 removed from model pages. It is corrected here because a stale instruction propagates: the next window reads this file as the live roadmap and would have rebuilt what the split just dismantled — and then failed its own close gate.

Where we are

Phase	State
W1 — foundation (folder · live census · corpus-mine reconciliation · regenerator)	✅ done
W1.5 — boot chain wired · site live at atlas.brandtrackers.xyz · drift-check · PRD · recovery hook	✅ done
ATLAS-JUL24-02 — legibility standard + Vale gate · clickable maps · generated real examples · Entities pillar · lane-generic close guards	✅ done
ATLAS-JUL24-03 — W2a Content & Moments, written BOTH ways (two pillar pages + a GENERATED one-page view; Joe picks at the review)	✅ done
ATLAS-JUL29-01 — the nine-report external audit ADJUDICATED (every claim probed live; Q20–Q24 appended; conformance 11 checks; walk brief + dictation scaffold shipped)	✅ done
ATLAS-AUG02-01 — prep-only: review surface re-verified end to end (Joe chose async review)	✅ done
ATLAS-AUG10-01 — W3 THE REVIEW: all 25 questions + R1–R3 RULED across two dictated walk rounds (banked verbatim → decisions/decided.md + DN-219/DN-220); Q17 EXECUTED (split wins, combined page + generator deleted); both vocabularies RATIFIED same-session (DN-221)	✅ done
ATLAS-AUG10-02 — W2b Works & Groupings pillar + the first-jobs (conformance C12/C13/C14 → 14 checks · the Q10 moment-type promotion list as a third PROPOSED page · entities-page ruling folds)	✅ done
W2c — Concepts (owes the craft-rulebook GENERATED page + the audience definitions list)	▶ next
W2d–W2f — relationship matrix · pipelines page · use-case walkthroughs	pending, in order
W4 — un-pause PIPE	pending the 24-card substrate console (the Atlas-rulings gate is largely MET)
W5 — harden	pending W4
W6 — daily curation loop	parked

The roadmap

W2 — one pillar per window (Joe's sequencing call, 2026-07-24). Each window: write the pillar to the Entities pattern, re-probe every number live, pass Vale, close at a verified milestone.

• W2a — Content & Moments. ✅ DONE (ATLAS-JUL24-03; Q17 ruled 2026-08-10). Written both ways on Joe's call, then the SPLIT won at the review — the combined page and scripts/atlas-combine.py are deleted (DN-220), and the battery step went with them. Channel is written as a lens, not a container per the redline, and the locked moments taxonomy is described, not re-opened. scripts/atlas-examples.py serves multiple pillars.
• W2b — Works & Groupings. ✅ DONE (ATLAS-AUG10-02). Campaigns, events, projects, brand-identity on the ruled ground (the four grouping kinds · events contain campaigns · grouping ≠ company · one-work-many-appearances · vendor work first-class). Generated example shows the end-to-end brand→container→piece→credit chain from real rows; --pillar works registered; conformance C14. Families 9/10 naming rides open in the ledger.
• W2c — Concepts. ▶ NEXT. The classification vocabulary: industry, audience, channel, occasion, craft discipline. Must state plainly which axes have no storage yet. Owes two named artifacts: the craft-rulebook GENERATED page (the discipline registry's hand-authored inclusion/exclusion/confusable/examples columns, rendered as a review queue — Joe: "I want this in our canonical Atlas docs") + the audience definitions list (audience is a real object per the walk).
• W2d — the relationship matrix. One page: every allowed edge as source → verb → target → what writes it. Each edge must trace to a real foreign key in the census.
• W2e — the pipelines page. SCOPE IS WIDER THAN THE NAME SUGGESTS. Not "how the content pipeline works" — the pipelines the MODEL IMPLIES, most of which do not exist. Today there is one pipeline and it handles content (and it needs work). An entity pipeline, a campaign pipeline and a brand-and-identity pipeline are all implied by the model and none of them exist — which is where most of the apparent thinness in the data actually comes from (open question Q18). The page must name what is missing as plainly as it describes what runs. It must also carry the onboarding-versus-daily distinction (Q19): a backlog lets you see a campaign cluster all at once, while a live daily feed may not reveal a campaign until several pieces have landed or an outside signal arrives — a press release on the company's own newsroom, a trade article. Must also state the split-brain vocabulary plainly as a live defect.
• W2f — the use-case walkthroughs (Joe's acceptance test). His own examples traced end-to-end through the model — that is how we prove it works rather than asserting it: IBM × US Open (event + sponsorship + campaigns + vendor credits + cross-channel content + moments) · McDonald's × Minecraft (a partnership across two brands, product/feature, press-release trigger) · OpenAI launch + the model-card PDF (the routing question: is a research artifact "content"?) · the vendor case-study scrape (credits + disciplines) · the newsroom link (a real-time campaign trigger). If a walkthrough needs an edge the matrix does not allow, that is a finding to rule on — never a workaround.

W3 — the review. ✅ DONE (ATLAS-AUG10-01, two dictated walk rounds 2026-08-04 + 2026-08-10). All 25 questions + the three preliminary calls RULED; every answer banked verbatim in docs/reference/2026-07/2026-07-26/atlas-review-responses.md before analysis, then processed exactly as this paragraph prescribed: decision entries (DN-219/DN-220), plain-language rulings with reasoning in decisions/decided.md, present-tense statements folded onto the model pages, and conformance checks where a ruling implies something must be true of the data (C12/C13 landed in ATLAS-AUG10-02). Both proposed vocabularies were then RATIFIED same-session (DN-221). The review is now a RECURRING gate, not a finished event: each remaining pillar raises its questions into the ledger and Joe rules them in batches (currently open: the promotion-list marks · crew-role · families 9/10 naming).

W4 — un-pause PIPE (see the return chain below).

W5 — harden. Adversarial conflict-verification across the whole model → resolve + archive the entity 6-doc chain → execute the doc demotions (§6 concept→home routing: keep TAXONOMY-CANON, CLASSIFICATION-PIPELINES, MOMENTS-V1-BETA, SCHEMA.md, CAMPAIGN-DEFINITION, CREATIVE-TAXONOMY-MASTER; resolve+archive the conflicting entity chain) → re-audit the pipelines against the finished model.

W6 — (PARKED) daily human-in-the-loop curation loop. The empirical validator (theory-from-docs ↔ practice-from-real-content). Scoped daily trickle (one brand · few channels · ~5–10 items/day): LOOK in the grid, DECIDE via CLI, STORE in a review_decisions log feeding the open-decisions register + classifier prompts + registry examples. Guardrails: no Label Studio rebuild · master switch FALSE + ~$100/24h · classify in the REVIEW step, not the broken pipeline. Timing: a repeatable machine only after the model stabilises.

The open questions — ONE HOME

They live in docs/atlas/decisions/open-questions.md, and nowhere else. All 25 numbered questions are now RULED (decisions/decided.md carries each with its reasoning); the ledger currently holds the still-open threads — the per-shot crew-role vocabulary, the names of content-type families 9 and 10, and the moment-type promotion round awaiting marks — and receives each new pillar's questions as they arise. The agenda used to be listed here AND in the handoff AND as bullets on the pillar pages — three copies whose numbering had already drifted apart (this file's #1 was the ledger's Q13). Duplicating a decision agenda is how you lose one. The carry-manifest gate searches the ledger as well as the handoff, so a thread cannot be dropped from either.

Known live defects (named, not forgotten)

• ⚠ The split-brain vocabulary. Emit-time vocabulary is hardcoded literals per format; validate-time reads the database registry; the two are kept in sync by hand. This is the mechanical root of "we authored a vocabulary and it does nothing" — authoring into the registry has zero emit effect until the hardcoded literals are replaced. Unifying it is an open question above.
• ✅ RESOLVED — the promote out-of-memory (F-169). Fixed by capping the V8 heap (--max-old-space-size=4096 in frontend/package.json build): 7.29 GB → 5.73 GB, ~2.3 GB headroom. The old note only ruled out raising the heap; nobody had tried lowering it. Kept here because the failure mode is the lesson: a failed promote is silent — the previous build keeps serving, so the site looks healthy while nothing ships. Always verify a promote by fetching content that only the new build has.
• ⚠ The moment shelf list is hardcoded in the classifier prompt (a second, concrete face of the split-brain vocabulary — probed this window). backend/routers/pipeline_scene_classify.py:189-202 enumerates 13 shelves as literal prompt text; schema_enums moment_category holds 14 active. pricing_cta is registered, is a real ratified lens, and the classifier is never shown it — so nothing can ever be filed there, however well it is described. Validate-time does read the registry (_load_enum_values at :895-909), which is exactly the asymmetry: the registry can reject a word, but it can never cause one to be emitted. The FIX is now RULED (Q23, 2026-08-10): the registry is the single governed surface and classifier prompts are GENERATED from it, with a taxonomy-version stamp on every classification — build work queued in the handoff carry #16, executes in the PIPE lane.

↩ Return to the main pipeline (the endgame — this lane is NOT the destination)

Atlas exists so that when we get to PIPE — implementing across every pipeline, updating the existing ones, creating new ones, the workflows, the classifications, the prompts, the relationships — there is one human- and machine-readable definition of the logic to point at, instead of re-deriving it from Joe's head every window. It is a multi-window program, one pillar per window, and each pillar gets a full window.

1. The remaining pillars, one per window: Groupings ✅ (renamed from Works & Groupings 2026-08-17) → Concepts → the relationship matrix → the pipelines section ✅ (shipped 2026-08-17: 6 verified have-vs-need pages) → Joe's five use-case walkthroughs.
2. The review — ✅ DONE for the numbered agenda (all 25 + R1–R3 ruled; both vocabularies ratified). It continues as a recurring gate: each pillar's new questions get ruled in batches, marks always banked verbatim under docs/reference/<date>/ first.
3. Then back to PIPE. docs/INDEX.md §2 is the board that says so; PIPE's boot doc is docs/sessions/PIPE-JUL21-05/HANDOFF.md. Flip its §2 row back to active and resume there.

⚠ CORRECTION (2026-07-25) — the Atlas review alone does NOT unblock PIPE. This section previously claimed "the Atlas review PRODUCES those marks". Audited: PIPE's build is gated on the 24-card substrate console (docs/reference/2026-07/2026-07-21/w2-substrate-console.html), which is still un-walked and has no banked export. Its cards overlap only about four of the Atlas open questions, because Atlas asks what things mean and that console asks what to build. Two gates, not one. Rule the Atlas questions first — several substrate cards are downstream and will resolve or change shape once the meaning is settled — then walk whatever survives. The manifest now carries this thread so it cannot be dropped by a future rewrite.

Scope boundaries (don't collide)

Moments = the Moments pillar; platform coverage (Instagram / TikTok / YouTube) = the Content / Channels pillars (the moments taxonomy is already locked). Wiring moments into admin, and the FE modal/layout, are DOWNSTREAM — and the FE-modal is a PARALLEL session. Atlas does not touch it, and does not edit other lanes' boot docs.

Operating loop — how we run this across windows

• Continuity: /resume-session ATLAS → work → /handoff. The HANDOFF + this plan are the durable state; re-probe every number, never trust a frozen one.
• Compaction/thread rule: close at a VERIFIED milestone BEFORE compaction (target ≤~55% context per window); ONE phase-chunk per window; start a fresh thread at each phase boundary and before any big fan-out.
• The handoff is a CARRY-FORWARD, never a fresh document. Every close diffs the previous carries in and either restates them or marks them resolved. (This rule exists because ATLAS-JUL24-02 rewrote the handoff from scratch and silently dropped eight threads — F-171.)
• WORK-MODE GUIDE — when to reach for each (and tell Joe before spending big):
  • Plan mode → start of every window that touches multiple files or makes a design call. Skip for a single mechanical edit.
  • Workflow (multi-agent fan-out) → verify-heavy breadth where missing one item is costly (mapping the ~136 core tables to pillars; the W5 conflict-verification). Trigger = "map/verify N things, N large, completeness > tokens." Flag Joe first — it spawns many agents and spends real tokens.
  • ultracode → the exhaustive, cost-no-object pass (a whole-model adversarial audit; any "don't miss a single X"). Trigger = Joe says ultracode, or the task is an exhaustive audit. Announce it.
  • /loop + /schedule → recurring work only: the W6 curation loop, /nightly-verify. Guardrails = master FALSE + ~$100/24h + human gate on architecture.
  • Goal tracking → this file (the roadmap) + the HANDOFF + the INDEX §2 lane row. Update all three at close; that is how the goal survives a lost context.
  • /handoff + /resume-session = continuity · hooks = enforcement. Every window, non-negotiable.
• Full-trace verification for any code the model eventually drives (database → backend → pipeline → functions → hooks → frontend): a green unit is not a working chain.

Guardrails (binding)

master_enabled stays FALSE · $0 AI / zero pipeline runs (the census, drift and example scripts are read-only) · no schema/data changes from this lane · per-file git add (never -A; the tree carries other windows' work) · ground-truth-first: every count re-probed in the session that writes it.

Why this sticks (the anti-rot thesis)

Not memory — generated and enforced: the source is git markdown (can't be lost) · the site builds from it (can't drift from the source) · scripts/atlas-drift.py fails when the database moves under the docs · scripts/atlas-examples.py --check fails when a worked example stops matching real rows · Vale fails the commit when a reader page slips back into jargon · and the lane is registered in the hook-enforced boot chain, so every /resume-session ATLAS lands on it.