What's being proposed
32 concrete proposals across 7 dimensions, designed against 11 named principles (7 BA, 4 ACID). The goal: take the current AS-IS folder (157 files, 145 ACID entities, 12 meta docs) and evolve it into a system where coverage is self-declaring, lifecycle is explicit, campaigns are first-class entities, ownership is named per artefact, and Werner's parser gets richer signal without losing backward compatibility.
The four design moves
| Move | What changes | Why | Risk |
|---|---|---|---|
| 1. Make context first-class | Add 4 new folders: 09_strategy, 10_methodology, 11_campaigns, 12_indexes | Strategy docs that authorise ACUs live elsewhere; methodology frameworks are buried; campaigns are inferred; indexes are computed but treated as content. All four need a home. | Low |
| 2. Make the funnel routable | Split channel into surface + moment; query funnel on moment | Today 90 entities classify as cross-funnel because Pack 2 IIM is whitepaper-surface but demo-moment. Conflating them breaks the funnel. | High |
| 3. Make backing self-declaring | Every Tier A entity declares backed_by; methodology declares cascades_into | Coverage gap analysis is currently inferred. Self-declaration lets Tom do impact-analysis pre-edit and Werner build full provenance from a single Supabase view. | Medium |
| 4. Make lifecycle explicit | Add lifecycle_stage field with 5 states (concept, drafted, ratified, deployed, retired) | Status (LOCKED/APPROVED) conflates immutability with deployment-state. A LOCKED ACU can still be retired. Separate the axes. | Low |
Werner's verdict (29 May)
Backward compatibility guarantees
Every proposal is designed non-breaking:
- New frontmatter fields are optional; existing entities continue to work
- New folders add; existing folders don't move (with one exception: 00_PERSONA_FRAMEWORK to 10_methodology/, signposted by a redirect)
- Naming convention is opt-in for new files; existing filenames stay;
class_code:frontmatter field is added for self-declaration without rename - Werner's parser keeps reading current fields; new fields are additive, no breaking change
- Migration is phased (Werner's 6 phases + gate over multiple sessions); each phase is reversible
Categorisation . folder structure
The folder model determines what goes where. Today, 8 ACID-row subfolders + ad-hoc root files. Proposed: 8 ACID + 4 meta + standardised utility folders.
Tagging . frontmatter schema V2
ADR-014 gave us identity, versioning, provenance, audit. V2 adds 5 new layers: lifecycle, routing, backing, ownership, quality. All new fields are optional and additive; existing entities continue to work.
Full proposed schema V2
Filing . where new content lands
Folder structure (categorisation) tells you the buckets. Filing rules tell you which bucket a new piece of content goes into, what naming pattern it follows, and how supersession + drafts + archives work.
Naming convention
Today's naming is class-specific (acu_, comp_, recipe_, PascalCase pillars, kebab-case channels). Proposal: class-code prefix scheme adopted opt-in for new files; existing files unchanged but carry a class_code: frontmatter field for self-declaration. Mass-rename available later via wikilink-rewriter utility.
Lifecycle model
Status (LOCKED, APPROVED, etc) tracks immutability and curation. Lifecycle is a separate axis: where in the build-deploy pipeline does this entity sit? Adding lifecycle_stage lets Tom + Werner answer that without conflation.
Proposed 5-state lifecycle
Campaigns as first-class entities
Today the EIS Oct 2026 campaign exists only as inference (pillars + belief-stages + channels). Make it explicit: 11_campaigns/eis-oct-2026.md declares the campaign with funnel rules and entity-inclusion logic. Entities carry in_campaigns: to opt-in.
Proposed campaign-file schema
Cross-tier backing
BA discipline: every artefact links upward to the doc that authorised it; upstream docs declare what they cascade into. Closes the Layer 1c coverage gap from the AS-IS audit (12 Tier B docs with zero declared backing-citations).
Migration plan . Werner's revised 6-phase plan
Werner replaced the original 7-phase plan. Key changes: Phase 1 combines original M1 + M2 (run in parallel); Q1 worked-example gate inserted between Phase 2 and Phase 3; parser updates distributed across phases rather than saved for a final Werner re-seed. No phase can start until Phase 0 (Q1-Q7 answers) is complete.
Reversibility notes
- Phase 1 (schema + folder additions): fully reversible. New fields are optional; empty folders remove without data loss.
- Phase 2 (backing pass): reversible by clearing backed_by + cascades_into fields.
- Phase 3 (surface + moment): partially reversible. Once Werner's parser reads surface + moment, rollback requires parser revert. ADR required before starting.
- Phase 4 (lifecycle): reversible. lifecycle_stage field removable without data loss.
- Phase 5 (naming): class_code: frontmatter-only phase is reversible. Filename rename phase is one-way but preceded by reversible frontmatter pass.
- Phase 6 (campaigns): Supabase versioning preserves prior seed. Table add is reversible.
Werner Review . 29 May 2026
Werner Snyman's architectural review of the V2 design proposal. Read the verdict, check the authority lines for what you can do alone vs what needs joint approval, review the folder canonicalisation calls, and work through Q1-Q7 to unlock the gated proposals. V2 cannot lock until all 7 questions are answered.
Authority lines . what Tom can do unilaterally vs what needs joint approval
Folder canonicalisation . Werner's call on each new folder
Seven open questions . all OPEN, Tom to answer
These questions gate specific proposals and migration phases. Don't answer them here . work through them with Werner. The answer slots below are placeholders for when the answers are known.
Werner's revised migration plan (replacing original 7-phase)
This supersedes the original M1-M7 plan. Parser updates are distributed across phases; the Q1 worked-example gate sits between Phase 2 and Phase 3.
Open Scope . Section 8
Work that the V2 design has locked but hasn't started. Sequencing: ADRs + architecture doc updates go first (before any code or schema changes). BS cards go in sync with each migration phase. Target: design locked + ADRs drafted within the first week after Q1-Q7 answered. Phase 1 migration starts mid-June 2026.