Authoring Conventions
The authoring contract for the Rhythm 2.0 specification corpus (rhythm-v2-docs). It implements the lean artifact catalog approved by Andrew on 2026-10-22 ("Forge 2.0: Artifact Architecture and Development Pipeline Redesign", section D). Where this document is silent, that proposal governs; where a kind defined there is not yet in use here, it is listed in section 9 as deferred.
Every file in this corpus is one of three things: a decision a person made, a contract a check can enforce, or evidence a run produced. Anything else is generated or does not exist.
1. Units: Product Area and Module
| Unit | Meaning | Example |
|---|---|---|
| Product Area | An application of Rhythm 2.0 as Product Management names it. One directory under specs/. | crm, platform, accounting |
| Module | A bounded capability group inside a product area, usually one modules/<name>/ directory of the owning macroservice, sometimes a split or a merge of them decided by behaviour. One directory under the product area. | crm/entities, platform/llm, accounting/transactions |
The registry of product areas, their codes, their modules and the repositories and paths each module reads is PRODUCT-AREAS.md. A module code is permanent once it appears there.
The hosted-screen rule. A screen belongs to the module that owns the records it administers. The React Console hosts it; it does not own it. The console's contact and organization screens are specified under crm/entities.
One home per fact. A business rule lives in exactly one capability. A journey cites rules by id and never restates them. A scenario proves rules and journey assertions by id and never restates them.
2. Directory Layout
specs/
README.md the corpus home
CONVENTIONS.md this document
PRODUCT-AREAS.md the registry of product areas, modules, codes and source paths
templates/ one template per authored kind
<product-area>/
<module>/
MODULE.md the module charter (what it owns, what it does not, where it lives)
ID_REGISTRY.md every id allocated in this module and the next free number per series
FINDINGS.md findings and open questions for the module (one table each)
planning/
features/FEAT-<PA>-<MOD>-NN-<slug>.md the parent: names and groups its concepts, actors, capabilities and journeys
concepts/CON-<PA>-<MOD>-NNN-<slug>.md one per noun, in product language
capabilities/CAP-<PA>-<MOD>-NNN-<slug>.md
journeys/JNY-<PA>-<MOD>-NNN-<slug>.md
acceptance/FAS-<PA>-<MOD>-NN-<slug>.md Feature Acceptance Suite, the same number as its feature
ACTORS.md the product area's actors (one table; ids ACT-<PA>-NNN), shared by its modules
design/ §9: objects/, state-models/, workflows/, contracts/, screens/, decisions/, inference/
tests/ATS-<PA>-<MOD>-NNN-<slug>.md Capability Test Specification, the same number as its capability (§9.10)
implementation/ §10: plans/ per ticket, screens/ (SCI), tests/TST-<PA>-<MOD>-NNN-<slug>.md executable suites
qa/ §10: TER- test execution reports and DQR- delivery qualification reports per ticket
acceptance/PAS-<PA>-NNN-<slug>.md Product Acceptance Suites of the product area (§5.0d)A file's directory and its frontmatter must agree: product_area and module name the directories it sits in.
3. Identifiers
<PA> is the product-area code and <MOD> the module code from PRODUCT-AREAS.md.
| Artifact | Id | Example |
|---|---|---|
| Module charter | MOD-<PA>-<MOD> | MOD-CRM-ENT |
| Feature | FEAT-<PA>-<MOD>-NN | FEAT-CRM-ENT-02 |
| Key Concept | CON-<PA>-<MOD>-NNN | CON-CRM-ENT-003 |
| Actor (row in the product area's ACTORS.md) | ACT-<PA>-NNN | ACT-CRM-002 |
| Capability Specification | CAP-<PA>-<MOD>-NNN | CAP-CRM-ENT-004 |
| Business rule (row inside a capability) | BR-<CAP id>-NN | BR-CAP-CRM-ENT-004-03 |
| Scenario or edge case (row inside a capability) | SC-<CAP id>-NN | SC-CAP-CRM-ENT-004-02 |
| Journey | JNY-<PA>-<MOD>-NNN | JNY-CRM-ENT-002 |
| Journey assertion (row inside a journey) | AS-<JNY id>-NN | AS-JNY-CRM-ENT-002-01 |
| Acceptance Test Set | ATS-<PA>-<MOD>-NNN | ATS-CRM-ENT-004 |
| Acceptance scenario (row inside a set) | ATS-<PA>-<MOD>-NNN-NN | ATS-CRM-ENT-004-07 |
| Finding | FND-<PA>-<MOD>-NNN | FND-CRM-ENT-012 |
| Open question | OQ-<PA>-<MOD>-NNN | OQ-CRM-ENT-003 |
Rules:
- Ids are permanent and never renumbered or reused. During reverse engineering there is no history (Andrew, 2026-10-23): an artifact that turns out to be wrong, misplaced or not a real concept is deleted, its references removed and its id retired in
ID_REGISTRY.mdwith one word (deleted); nosupersededordeprecatedstatus, nosupersedesfield, no change history. Versioning (revision bumps,changefields, superseded chains) begins only after Andrew locks and approves the corpus. - Numbers are assigned in discovery order within a series, starting at 001, and recorded in the module's
ID_REGISTRY.mdbefore the file is written. - Earlier corpora are not referenced. A capability that replaces one in docs-2 or the console acceptance inventory does not name it; the reverse-engineered corpus describes the product as it is now (Andrew, 2026-10-23; the
supersedes:field of 2026-10-22 is withdrawn and removed). - File name:
<ID>-<kebab-slug>.md, lowercase slug cut at a word boundary, at most 60 characters.
4. Provenance and Status
During reverse engineering status is draft or approved (proposed for the testing kinds), revision is 1 on every artifact, and nothing records history (§3). Revision bumps, change fields and the "back to draft" rule of §11 apply only after Andrew locks and approves the corpus (Andrew, 2026-10-23).
Every artifact carries three independent fields. Never collapse them.
status: draft # document maturity: draft | approved (proposed for the testing kinds); no other value during reverse engineering
product_intent: proposed # product authority: confirmed | proposed | assumed | open | out-of-scope
implementation_evidence: observed # what the code shows: observed | partially-observed | not-implemented | inconsistent | not-investigatedstatus is set to approved only by Product (Andrew). Authoring never advances it.
product_intent is confirmed only when a product record confirms it: a milestone record decision, an approved milestone plan, a standard, or Andrew's recorded ruling, cited by path and decision id. Finding behaviour implemented is never enough. A behaviour the code shows with no record behind it is proposed; a behaviour that had to be assumed to make the artifact coherent is assumed; a material question Product must answer first is open and gets an OQ- row.
Every statement, not only every document, carries provenance. Rule rows, scenario rows, journey steps and assertions each have a provenance value and a source:
| provenance | Meaning | source holds |
|---|---|---|
observed | Verified from code or executed behaviour | repo:path:symbol or repo:path:line |
test | Stated by an existing automated test | repo:path#test title |
documented | Stated by a record, plan, standard or architecture document | repo:path#heading or decision id |
inferred | Deduced; the reasoning is in note | the artifacts or code the inference rests on |
unknown | Could not be established; a finding or open question exists | the FND- or OQ- id |
Every artifact carries source_sha per repository it was read from. A later delta pass re-reads only what changed since those commits.
5. The Planning Kinds
The planning layer is a tree (Andrew, 2026-10-22): a module holds Features; a feature names its Key Concepts (the nouns), the Actors that use it, its Capabilities (with the business rules inside them) and its Journeys; each capability has an Acceptance Test Set. Product reasons feature by feature: here are the things, here are the people, here is what the people can do with the things and under which rules, here is how they get things done, here is how we prove it. Design then adds how each concept is realised (Domain Object, State Model, Workflow) and who is responsible for what.
5.0 Feature (FEAT)
One per named part of the product that staff would recognise (Contact Records, Affiliations and Roles, Organization Compliance). Three to eight per module. A feature explains a cohesive part of the product and groups its children; the children hold the authoritative detail (Andrew, 2026-10-23, superseding the 2026-10-22 "names and groups only" rule). Its body never carries a rule statement, a scenario or a requirement the children do not carry; it summarizes, motivates and illustrates them. Required frontmatter: id, title, product_area, module, revision, status, product_intent, source_sha, purpose (two or three sentences for the customer), outcomes, concepts (CON ids), actors (ACT ids), capabilities (CAP ids), journeys (JNY ids). Optional: supersedes, release, delivery_status (planned | built | verified | accepted, written by the pipeline). Every capability and journey belongs to exactly one feature; the checker refuses an orphan. Body sections, in order: ## Overview, ## Why It Exists, ## Who Uses It, ## How It Works, ## Examples, ## Decisions and Tradeoffs (optional), ## Scope and Boundaries, ## Outcomes, ## Its Capabilities (one sentence per child capability, every title named). What each must answer, and how it is judged, is EXPLANATORY-STANDARD.md §6.1. Optional frontmatter: narrative, narrative_sources[] (§6 rule 8).
5.0a Key Concept (CON)
A Key Concept is every business idea a reader must understand to use the module (Andrew, 2026-10-23, superseding the 2026-10-22 "three to six broad nouns" rule): the broad nouns (contact, organization, affiliation) and also the classification types, roles, statuses and policies that change how the product behaves or displays (a contact type, an organization type, an affiliation type, a contact role, organization compliance, the module's settings). Each has its own artifact that explains what it is and what effect it has on the system. Not a concept: a storage row or mechanism inside a concept (a role period, a lock change, a reprocess run, a default link are facets), and a noun another module owns (custom field definitions and values, page layouts, form definitions, files and managed assets, users, e-mail templates are Platform's): the module's text names the owning module's concept in words and, if that module lacks it, files a finding there. Typically six to fifteen per module. Body sections (EXPLANATORY-STANDARD §6.3): What It Is, Why It Exists, What It Is Not, What It Controls (required: the behaviour, display and rules it drives), How It Is Used, Example, Its Facets (optional), Its Lifecycle (optional), How It Relates, What It Could Become (optional).
Required frontmatter: id, name, feature, product_area, module, revision, status, product_intent, implementation_evidence, source_sha, definition (one or two sentences), owned_by (the module id that owns the record), facets[] { name, meaning, used_for }. Optional: synonyms, not_to_be_confused_with, relationships[] { to, statement, provenance, source }, lifecycle[] { state, meaning, how_it_changes } in product words (the formal state model is Design's), acted_on_by (CAP ids), visible_to (ACT ids), evidence[] (what was read, by repository), supersedes.
Body, in this order, typically 500 to 1,200 words, written for a product manager who has never read the code: ## What It Is, ## Why It Exists, ## What It Is Not, ## How It Is Used, ## Example, ## Its Facets, ## Its Lifecycle (optional, only where one exists), ## How It Relates, ## What It Could Become. The responsibility of each section is in EXPLANATORY-STANDARD §6.3; the first six keep the meaning given here on 2026-10-22. ## Why It Exists: the business need the concept answers and what breaks without it. ## Example: a concrete instance of the concept in a realistic situation. ## Its Lifecycle: where the concept has one, its states in product words and what moves it between them; the formal state model is Design's.
## What It Is: what the thing is to the customer's staff, how it comes into being, what it carries, how it is identified; compare it to how the same idea is handled elsewhere (Rhythm 1.0, a common CRM) where that helps.## What It Is Not: the neighbouring ideas it is often confused with, and the line between them.## How It Is Used: who works with it, in which situations, through which capabilities and journeys (named in words, not ids), what good use looks like and what goes wrong.## Its Facets: each facet in a short paragraph: the classification types, roles, sub-records and settings that belong to this concept, what each means and why it exists.## How It Relates: its relationships to the other broad concepts of the module and of other modules, in words.## What It Could Become: the open edges: behaviour the product has not decided, likely extensions, questions Product may want to answer.
The prose carries no source paths, commit hashes, rule or scenario ids, or the word "tenant" (say the customer, the workspace or the organization). Evidence lives in frontmatter.
5.0b Actor (ACT)
The product area's actors live in one file, specs/<product-area>/ACTORS.md, as a table: id, name, who (one sentence), goals, can_broadly, represented_by (permission keys or roles), surfaces. Features, capabilities and journeys cite actors by id. Three to eight per product area.
5.0c Product Area Overview and Architecture (AREA-<PA>)
One per product area, specs/<product-area>/AREA.md, the page a reader lands on before any module (Tribal's AREA documents; Andrew, 2026-10-23). It is the area's final architecture document (Andrew, 2026-10-23, 11:40 ET: the deep architecture artifacts leave Claude and live here, combined with the area overview into one document): the overview sections first, then the architecture chapters composed from the area's architecture records (§14), then the invariants, decisions and open questions. Required frontmatter: id (AREA-<PA>), title, product_area, revision, status, product_intent, source_sha, modules[] (MOD ids in reading order), architecture[] (the ARCH ids the chapters were composed from), owns[] (what the area is responsible for, in product words), does_not_own[] (with who does), handoffs[] { to, what }, invariants[] (area-level statements that every module honours), evidence[], narrative_sources[] (one row per architecture chapter naming the record parts it was composed from). Body, in this order: ## Purpose and Outcomes (what the area does for a customer, 200 to 500 words), ## Who Uses It (the area's actors in words and what each accomplishes here), ## Key Business Processes (the major workflows the area carries, pointing in words at the product acceptance suites that prove them), ## Scope and Boundaries (owns, does not own, handoffs, in sentences), ## How the Area Is Divided (one short paragraph per module saying what it is for and when a reader should open it); then the architecture chapters, one H2 per chapter in the order the architecture reads best (vision and principles; the domain model; the functional architecture; services and contracts; lifecycles and safeguards; the console and portal experience; data operations; security, audit and privacy; cross-application contracts; each topic architecture such as households or enrichment as its own chapter), each composed by OpenAI from the records' architecture parts, saying for every statement whether it is built, decided or proposed (EXPLANATORY-STANDARD §5) and citing the parts in narrative_sources; then ## Area-Level Invariants, ## Decisions (the standing and recorded decisions and those still needing Andrew, by name, with their outcome), ## Open Ownership Questions. The records' research, evidence, review, gap-matrix and roadmap parts are not composed into the page; they remain in the records as the evidence behind it. Written by OpenAI from the registry row, the records, the modules' charters, the actors and the responsibilities; it never restates a module's capabilities. An area whose charter carries explanatory_standard: 1 has these sections enforced by npm run check.
5.0d Product Acceptance Suite (PAS-<PA>-NNN)
One per complete business process of a product area (establish a business unit, invoice, collect, credit, refund, reconcile, report, close the period, prove the closed period is protected), under specs/<product-area>/acceptance/; several per area (Andrew, 2026-10-23: tests mirror the specification hierarchy, Product Area → Feature → Capability, and grow cumulatively with it). Required frontmatter: id, title, product_area, revision, status (proposed | approved | superseded), product_intent, source_sha, covers[] (FEAT ids, in every module the process crosses), executable_by (agent | manual | mixed), estimated_minutes, isolation (what the run owns: a workspace of its own, a business unit, seeded records), scenarios[], evidence[]. Each scenarios[] row: id (PAS-<PA>-NNN-NN), title, preconditions, steps[] (ordered; each step { do, exercises[] (CAP ids), expect }), verification (what is checked at the end: balances, ledger lines, states, records), data_needs, negative, provenance, source. Body: ## The Business Process (what a customer is doing and why the whole chain must hold), ## What the Suite Proves, ## What It Does Not Prove, ## Regression Record (one line per revision: what scenario changed, which ticket, why). A product acceptance scenario is never a copy of a feature scenario: it proves the chain across features; it names the feature scenarios it relies on in exercises[] through their capabilities. These suites are the delivery qualification corpus: they accumulate, they are never deleted (a retired scenario stays with status: superseded and the reason), and every ticket that touches the area runs the applicable ones before delivery.
5.1 Capability Specification (CAP)
One per thing a user or system can do with the feature's concepts. Target 10 to 20 per module. Variants of one capability are rule rows, not capabilities. A capability is not a table, a route, a screen, or a CRUD verb; it is an outcome someone wants (record who works where; archive an organization and keep its history; find the people beneath an organization).
Required frontmatter: id, title, feature, product_area, module, revision, status, product_intent, implementation_evidence, source_sha, purpose, outcomes, concepts (CON ids it acts on), actors (ACT ids), surfaces, permissions, rules. Optional: supersedes, preconditions, postconditions, scenarios, edge_cases, constraints, depends_on, related, journeys, open_questions, intent_sources.
A rule's product intent is derived, never authored (Andrew, OQ-CRM-ENT-003, 2026-10-22): a rule whose origin names a product decision (a milestone decision id, or an answered open question such as OQ-CRM-ENT-001 decided 2026-10-22: A) is confirmed; any other rule inherits its capability's product_intent. The reader shows the derived value; a walkthrough answer is recorded as the origin of every rule it covers.
Each rules[] row: id, statement (one sentence, in product language, testable), kind (validation | policy | calculation | permission | invariant | lifecycle), enforced_at (any of api, service, database, console), must_prove (true when a scenario must exist before the capability can be approved), provenance, source, origin (the decision id, ticket or incident that explains why, or none), examples (optional positive and negative one-liners).
Each scenarios[] and edge_cases[] row: id, given, when, then, provenance, source. These illustrate; they do not prove. Proof is the Acceptance Test Set.
Each permissions[] row: key, where_checked (api | service | console | database), scope (tenant | record | global).
Body sections, in order: ## Purpose (the problem it solves inside its feature), ## How It Works (the operating model in coherent prose), ## Example (one realistic walkthrough), ## Variations (optional; only the applicable ones), ## Why It Works This Way (which invariant each significant rule protects and why the simpler alternative is wrong; interpretation labelled), ## Relationships (interactions and dependencies, where authority resides, contract or event or registry rather than direct dependence). EXPLANATORY-STANDARD §6.2 says what each must answer. No ## Evidence body section (evidence is frontmatter), no change-history table, no template tails. The formal contract stays in frontmatter; the reader renders it after the narrative under a visible divider.
5.2 Journey (JNY)
One per actor outcome that crosses capabilities, screens or applications. Three to six per module is typical. Required frontmatter: id, title, feature, product_area, module, revision, status, product_intent, implementation_evidence, source_sha, actor (an ACT id), goal, steps, e2e_policy. Optional: alternates, failures, rules_in_play, assertions, capabilities, screens.
Each steps[] row: n, surface (route or API operation), action, capability (a CAP- id), expected, provenance, source. alternates[] and failures[] rows: from_step, condition, path, outcome, provenance, source. assertions[] rows: id, statement, provenance, source. e2e_policy is required, optional or none, with e2e_reason saying why.
Body: ## Story (the whole process from the actor's side), ## Before It Starts (optional: who starts it, what triggers it, what must be true), ## What Can Go Differently (optional: alternates and exceptions in prose), ## What Is True Afterwards (the resulting state and who is affected). EXPLANATORY-STANDARD §6.4.
5.3 Feature Acceptance Suite (FAS)
One per feature, the same number (FAS-<PA>-<MOD>-NN for FEAT-<PA>-<MOD>-NN), under planning/acceptance/: the cumulative acceptance coverage of the feature as a whole, broader than one capability and narrower than a product process (Andrew, 2026-10-23). Required frontmatter: id, feature, product_area, module, revision, status (proposed | approved | superseded), product_intent, source_sha, capabilities[] (every capability of the feature), scenarios[], evidence[]. Each scenarios[] row: id (FAS-<PA>-<MOD>-NN-NN), title, kind (behaviour | interaction | lifecycle | permission | regression), exercises[] (CAP ids, two or more for an interaction scenario), relies_on[] (ATS scenario ids whose outcomes this scenario assumes), preconditions, steps, expected, negative, data_needs, provenance, source. Body: ## What the Feature Must Do as a Whole, ## Interactions Between Capabilities (the scenarios that exist because capabilities meet: a partial payment changes settlement, refund, balance and reporting scenarios), ## Regression Record. When a capability joins a feature, its suite is re-read and extended, never merely appended to; when a capability's behaviour changes, the scenarios that rely on it are revisited; a scenario is retired only with status: superseded and a reason.
The former Acceptance Test Set (ATS) is now the Capability Test Specification of the design stage (§9.10); its ids are unchanged.
5.4 Module charter (MODULE.md)
Frontmatter: id, title, product_area, module, revision, status, source_sha, repositories (name and paths), owns (concepts and records), does_not_own (with who does), hosted_screens (console routes), supersedes (docs-2 areas or acceptance inventory areas it replaces). Body: ## Purpose (the domain, the business problem, the users and the processes, 200 to 500 words), ## Who Uses It, ## How It Is Organized (one paragraph per feature: what it is for and when to open it), ## Boundary, ## Features (a table of every FEAT- with its concepts, capabilities and journeys counted), ## Capabilities (a table of every CAP- with feature, title and intent), ## Journeys. Optional frontmatter explanatory_standard: 1, set by the landing of the module's narrative stage (EXPLANATORY-STANDARD §7), after which the conformance check enforces the explanatory sections on the module's artifacts.
5.5 Findings and open questions (FINDINGS.md)
Two tables. Findings: id, severity (critical | high | medium | low), statement, affects (ids), evidence (source), kind (defect | inconsistency | undocumented | debt). Open questions: id, question, why_it_matters, options, recommendation, affects. An open question is only for a material product decision; routine choices are made and recorded as assumed.
6. Document Form
YAML frontmatter as above, the structured content first.
An H1 that is the title, never the id.
The body sections the kind defines, in order. Sections with nothing to say are omitted, never filled with "None".
Headings in Title Case; identifiers and code never recased.
Prose in product language: what a person can do and what happens, in the present tense. No file paths, commit hashes, rule or scenario ids, or GUID-like references in prose, and never the word tenant (Andrew, 2026-10-22). Evidence goes in frontmatter (
source_sha, per-rowsource, an optionalevidence[]list of what was read); artifacts carry no## Evidencebody section. The reader shows evidence only behind a toggle that is off by default.Statements that describe the code as it is are labelled by their
provenance; a sentence that recommends a product obligation the code appears to serve says so ("The product should …" withproduct_intent: proposed).The published text is written by an OpenAI model (Andrew's rule, 2026-10-22, for all of Forge). A Claude job may discover, structure, source and draft an artifact; before it lands, an OpenAI job verifies it against the code and rewrites every sentence a person reads in its own words, keeping ids, structure, sources, provenance and intent values exactly. Nothing a person reads is landed in Claude's wording.
Explanatory completeness (Andrew, 2026-10-23). Every feature, capability, key concept, journey, module charter and product area overview explains, not only indexes: why it exists, who uses it, how it works, with examples, the decisions behind it and its boundaries, in the sections and to the depth
EXPLANATORY-STANDARD.mddefines for its kind. Narrative summarizes and illustrates the formal contract and never restates a rule as a second contract (one home per fact). Six kinds of knowing are kept apart in the prose and innarrative_sources[](verified intent, verified implementation, documented motivation, interpreted rationale labelled "Our reading is …", proposed behaviour "The product should …", unknown with an open question); writing the prose never changesstatus,product_intentordesign_intent. Each such artifact carriesnarrative { revision, status (enriched | verified | needs-revision | stale), review, stale_since }; a module whose charter carriesexplanatory_standard: 1has the standard enforced bynpm run check.
7. What Is Not Written
Requirement documents, feature documents, per-criterion test documents, per-table, per-function, per-resource or per-screen-field catalogues, authorization prose, change-history tables, and any status field the build does not write. The Zod schema is the field specification; the test file is the test case; the route declaration is the operation catalogue. These are indexed, in the implementation stage, by a generated code map.
8. Conformance
npm run check at the repository root validates every artifact: frontmatter fields by kind, id against file name and directory, uniqueness across the corpus, every referenced id resolvable (capabilities, rules, assertions, journeys, scenarios, findings, open questions), every must_prove rule of a capability covered by a scenario or named in a finding, and source_sha present. CI runs it on every push and pull request. A corpus that fails the check does not deploy, and, for a module whose charter carries explanatory_standard: 1, the explanatory sections of its features, capabilities, concepts, journeys and charter (presence, order, a forty-word floor, every child capability named by the feature, no rule statement repeated in prose, no identifiers or paths in prose, narrative_sources for the motivation and rationale sections, no filler phrases, a known narrative.status; EXPLANATORY-STANDARD §8.1).
9. The Design Kinds
Design answers how the product works: which objects exist and how they behave, what each module is responsible for, how multi-step flows run, what each screen must do, and which decisions constrain all of that. Architecture owns it, with UX for screens. Design is authored for a module after its planning layer is approved, by the same pipeline (a Claude draft, an OpenAI verification and final text), and approved by the architect (Andrew today). Layout:
specs/<product-area>/RESPONSIBILITIES.md RESP-<PA>: what each module of the product area is responsible for
specs/<product-area>/AREA.md AREA-<PA>: the product area overview (purpose, scope, boundaries, module map)
specs/<product-area>/AUTHORIZATION.md AUTH-<PA>: the product area's authorization model (roles, permission keys, how they compose)
specs/CONTROLS.md the corpus control catalogue (TC-<FAMILY>-NNN), one for all product areas
specs/<product-area>/<module>/design/
objects/DOM-<PA>-<MOD>-NNN-<slug>.md Domain Object, the same number as its Key Concept
state-models/STATE-<PA>-<MOD>-NNN-<slug>.md State Model, one per real lifecycle
workflows/WF-<PA>-<MOD>-NNN-<slug>.md Workflow Specification, one per multi-step or asynchronous flow
contracts/SVC-<PA>-<MOD>-<slug>.md Service Contract, one per macroservice module the corpus module covers
screens/SCR-<PA>-<MOD>-NNN-<slug>.md Screen Contract, one per console or portal screen
decisions/ADR-<PA>-<MOD>-NNN-<slug>.md Decision Record
inference/IOP-<PA>-<MOD>-NNN-<slug>.md Inference Operation, one per question the product asks a model
tests/ATS-<PA>-<MOD>-NNN-<slug>.md Capability Test Specification, the same number as its capabilityThe prose rules of §6 apply unchanged: product language first, no paths, hashes or ids in sentences, evidence in frontmatter. Design prose may name components, operations and tables because that is its subject, but it says what they are for before what they are.
9.1 Domain Object (DOM)
The design of one Key Concept, same number. Required frontmatter: id, title, realises (the CON id), product_area, module, revision, status, design_intent (confirmed | proposed | assumed | open), implementation_evidence, source_sha, owned_by (SVC id), attributes[] { name, kind, required, computed, notes } (logical, never columns), identity, relationships[] { to (DOM id), cardinality, ownership, cross_service }, invariants[] { id INV-<DOM id>-NN, statement, enforced_at, provenance, source }. Optional: lifecycle (STATE id), custom_fields (declared | none), readable_by[] (SVC ids), physical (the tables that hold it, by name, for the Code Map), evidence[]. Body: ## What It Models, ## Identity and Attributes, ## Relationships, ## Invariants, ## How It Is Stored and Shared (which service owns it, who may read it, what crosses a service boundary), ## Open Design Questions.
9.2 State Model (STATE)
The lifecycle of a Domain Object, only where one really exists. Required: id, title, object (DOM id), product_area, module, revision, status, design_intent, implementation_evidence, source_sha, states[] { name, meaning }, transitions[] { from, to, trigger, guard, side_effects[], who, provenance, source }, invalid[] { from, to, why }. Optional: concurrency, invariants[] (INV ids), evidence[]. Body: ## The Lifecycle (a Mermaid state diagram), ## Transitions Explained, ## What Cannot Happen, ## Concurrency and Timing.
9.3 Workflow Specification (WF)
Every multi-step, asynchronous or compensating flow. Required: id, title, trigger, product_area, module, revision, status, design_intent, implementation_evidence, source_sha, implements[] (CAP ids), hops[] { n, actor_or_service, action, anchor, seam (sync | queue | state_machine | event | schedule), on_failure, left_inconsistent, observer, provenance, source }, idempotency, concurrency. Optional: moves[] (STATE ids), crosses[] (SVC ids), branches[], waits[], evidence[]. Body: ## What It Does, ## The Flow (a Mermaid sequence or flowchart), ## When Something Fails (what is retried, compensated, or left inconsistent, and who notices), ## Open Design Questions. Also required: inference[], the Inference Operations (IOP ids) it calls, or an empty list meaning it performs no inference (§9.8).
9.4 Responsibilities (RESP-<PA>)
One per product area, specs/<product-area>/RESPONSIBILITIES.md. Required: id, title, product_area, revision, status, design_intent, source_sha, modules[] { module (MOD id), owns[] (DOM ids), exposes { operations[], events[] }, delegates[] { concern, to }, guarantees[] (INV ids) }. Body: ## How the Product Area Is Divided, one ## <Module> section per module in plain words, ## What Is Delegated to Platform and Other Areas. The Service Contracts must agree with it; the checker refuses a DOM owned by a module whose Responsibilities row does not list it.
9.5 Service Contract (SVC)
What a macroservice module owns and exposes. Required: id, title, product_area, module, repository, source_module (the modules/<name> directory), revision, status, design_intent, implementation_evidence, source_sha, owns[] (DOM ids), operations[] { operation_id, intent, access, permission, realises[] (CAP ids), published_to_submissions (contract version or 'not published: <reason>') }, events[] { name, direction (produced | consumed), when, payload_summary }, consistency[] { rule, kind (transactional | eventual), compensation }. Optional: jobs[], integrations[] { system, direction, contract }, does_not_own[], evidence[]. Operations are generated from the route declarations and annotated by hand with intent and capabilities; R2-ARCH-002 compliance is visible here. Body: ## What This Service Is For, ## Boundary, ## Operations in Words (grouped by capability), ## Events and Jobs, ## Consistency Guarantees. Also required: inference[], the Inference Operations (IOP ids) it calls, or an empty list meaning it performs no inference (§9.8).
9.6 Screen Contract (SCR)
What a screen must accomplish, never how it looks. Required: id, title, route, surface (console | portal), product_area, module, revision, status, design_intent, implementation_evidence, source_sha, purpose, supports[] (JNY and CAP ids), permission, entry_from[], exits_to[], displays[] { field, source }, actions[] { label, operation_id, permission, confirm }, states[] (empty, loading, error, read-only, inactive), validation[] (BR ids), patterns[] (design-system components, order composer, contact selector, Standard or Full layout). Optional: component (the console component today, for the Code Map), evidence[]. Body: ## What the Screen Is For, ## What It Shows and Lets People Do, ## States and Errors, ## Patterns It Must Respect. The Screen Implementation Specification (SCI, same number) and the v0 design belong to the implementation and build stages. Also required: inference[], the Inference Operations (IOP ids) it calls, or an empty list meaning it performs no inference (§9.8).
9.7 Decision Record (ADR)
A material architectural or product choice that outlives one Change. Required: id, title, product_area, module, revision, status (proposed | approved | superseded), design_intent, source_sha, decision (one sentence), constrains[] (DOM, SVC, WF, RESP, SCR ids), alternatives[] { option, why_not }, consequences[]. Optional: origin (the milestone decision, open question or ticket that made it), supersedes, evidence[]. Body: ## Context, ## Decision, ## Alternatives Considered, ## Consequences. An ADR is immutable once approved; a new one supersedes it.
9.8 Inference Operation (IOP)
One question the product asks a model, as Tribal records it (Andrew, 2026-10-22). Where a service, workflow or screen hands a model inputs and uses its answer, the question is its own artifact so the responsibilities, contract, failure handling and proof are stated once and every caller names it. Required: id (IOP-<PA>-<MOD>-NNN), title, product_area, module, revision, status, design_intent, implementation_evidence, source_sha, ai_task (the stable task name the code uses), provider, model, reasoning_effort (or none), called_by[] (SVC, WF and SCR ids), realises[] (CAP ids), smoke_suite (the test file, or 'not implemented'), evaluation_suite (the same), controls[] (the AI controls that apply, or empty), evidence[]. Optional: lifecycle_suite, related_decisions[]. Body sections, in this order: ## 1. Purpose; ## 2. Application and Model Responsibilities (what the application decides deterministically and what the model is asked; nothing the model returns selects a stage or persists by itself); ## 3. Inputs and Context (what the model is given and what it is deliberately not given); ## 4. Output Contract; ## 5. Model and Provider; ## 6. Prompt Contract (the shape and rules of the prompt, never the prompt text); ## 7. Validation, Failure and Fallback; ## 8. Smoke Tests (one ### IOS-<PA>-<MOD>-NNN-NN — <title> per scenario: input, expected answer, what a wrong answer looks like); ## 9. Evaluation Corpus (how quality is measured, or why it is not yet); ## 10. Call Shape and Batching (cost, limits, retries); ## 11. Controls; ## 12. Open Design Decisions. A module whose services, workflows and screens all carry an empty inference[] has no inference/ directory and its MODULE.md says so in one sentence.
9.9 Authorization Model (AUTH-<PA>)
One per product area, specs/<product-area>/AUTHORIZATION.md (Tribal's AUTH documents; Andrew, 2026-10-23): the single statement of who may do what in the area, from which every capability's permissions[] and every service operation's permission are drawn. Required frontmatter: id (AUTH-<PA>), title, product_area, revision, status, design_intent, implementation_evidence, source_sha, scopes[] { name, meaning } (the levels at which access is granted: workspace, organizational unit, record), roles[] { id (ROLE-<PA>-NNN), name, who, grants[] (permission keys) }, permissions[] { key, intent (one sentence), operations[] (operation ids), surfaces[], guarded_by[] (BR ids of rules that further restrict the operation beyond the permission) }, staff_access (how Rhythm staff enter the area, or none), evidence[]. Body: ## Authorization Boundary (what is public, what is customer-scoped, what is staff-only), ## Scopes, ## Roles, ## Permission Catalogue, ## Role Entitlement Matrix (roles by permissions), ## Protected Actions (the operations that need more than a permission: a guard, a second approval, a staff grant), ## Guards Distinguished From Permissions, ## What People See When Refused. The checker warns when a capability or service operation names a permission key the area's model does not list, and when the model lists a key no artifact uses.
9.10 Capability Test Specification (ATS, under design/tests/)
One per capability, the same number, formerly the planning-stage Acceptance Test Set (ids kept; moved here on 2026-10-23 at Andrew's direction because it defines detailed expected behaviour, which is design). Required frontmatter: id, scope (the CAP- id), product_area, module, revision, status (proposed | approved | superseded), source_sha, coverage (a map of the ten categories below to covered | not-applicable | gap: FND-…), scenarios[], evidence[]. Each scenarios[] row: id, title, category (rule | transition | validation | permission | edge | failure | boundary | concurrency | invariant | interaction), level (unit | api | browser | inference), proves (BR-, AS-, INV- or IOS- ids; at least one), preconditions, steps, expected, negative, data_needs, bound_to (TST suite ids or existing test files that already prove it), provenance (test when bound, else proposed), source. Every category applies unless not-applicable says why; every rule marked must_prove, every state transition of the capability's objects, every permission it names and every interaction with a related capability has a scenario or a finding. Body: ## Coverage (one line per rule marked must_prove), ## Interactions With Related Capabilities, ## Evidence. A scenario never restates a rule; it names the rule it proves. When a rule is added, the specification expands; when a rule changes, the scenarios that prove it are revisited in the same ticket.
10. Implementation and QA Kinds
The implementation stage adds, per module under implementation/: the Implementation Plan per ticket (plans/PLAN-RS-nnn.md, §11), the Screen Implementation Specification per screen (screens/SCI-…, below), and the executable test suites tests/TST-<PA>-<MOD>-NNN-<slug>.md: one artifact per executable suite with id, title, kind (api-lifecycle | browser-lifecycle | inference | unit | integration), product_area, module, revision, status, source_sha, repository, files[] (the test files), implements[] (ATS, FAS and PAS scenario ids the suite executes; many-to-many), environment (deployed-dev | local | mock), implementation_state (not-started | partial | implemented), latest_result (not-run | passed | failed | flaky, with latest_run_at and latest_run_ref), conformance (not-verified | verified), estimated_minutes, isolation (what the run owns), evidence[]; body ## Verification Boundary, ## What This Suite Proves, ## What It Does Not Prove, ## Real Dependencies and Test Doubles, ## Must Not Be Doubled. API-lifecycle and browser-lifecycle suites are first-class and exercise complete workflows through the public APIs and the console; unit and integration suites are registered so coverage can be counted but are engineering detail, never planning or design artifacts.
The QA stage adds, per module under qa/: the Test Execution Report TER-RS-nnn-NN.md per qualification run (id, change, run_at, commit and deployment per repository, suites[] { id, result, duration, worker, evidence }, failures[] { suite, scenario, classification (product-defect | test-defect | infrastructure | environment | flaky), defect }, retries[]) and the Delivery Qualification Report DQR-RS-nnn.md (id, change, qualified_at, the exact commits, build and deployment qualified, required_suites[] with each one's result, coverage (specification coverage, executable coverage, execution coverage), unexecuted[] with the evidence policy applied to each, decision (qualified | blocked) and why; optional, from the engineering operating model: fingerprint { before, after } (the corpus and code fingerprints the run was pinned to), environment_mode, selected[] (the suites chosen and why), remediation[] (what was repaired between runs), exploratory (manual exploratory testing performed and its outcome), corrections[] (test-defect corrections made during qualification)). Both are written by the pipeline, kept as evidence, and never edited afterwards; a material code change after qualification invalidates the report and a new one is produced.
10a. Deferred Kinds
The Implementation Plan, Work Plan, Code Map, Build Record and QA Report belong to the implementation and later stages, as does the Screen Implementation Specification (SCI-<PA>-<MOD>-NNN, the same number as its Screen Contract): one labelled Markdown artifact per screen, ledgered like Tribal's screen previews (id, status header, the v0 screenshot committed beside it, named in the delivery record), carrying the v0 design, the reusable components, what the screen loads, every action and the operation it calls, save behaviour, events, error handling, the rules it enforces, what it deliberately does not do, permissions, states, and pseudocode where the logic is not trivial, and an Inference section naming every Inference Operation the screen calls and what the person sees while the model answers, fails or is refused; never field-level mappings (Andrew, 2026-10-22). A screen that already exists in the console is never regenerated: its Screen Contract and Screen Implementation Specification describe the built screen as it is, with implementation_evidence: observed and the component named, and v0 is used only for a screen that does not exist yet or for the part of an existing screen a ticket changes (Andrew, 2026-10-22). Their templates are added when their stage starts.
11. Ticket Deltas: How a Change Lands in the Corpus
A Forge Change (a Linear or Jira ticket, RS-nnn, RX-nnn) lands its artifact deltas in this corpus on the ticket's branch, and the branch is one proposed future of the corpus. Added 2026-10-22 for the first Forge-authored tickets; the hash-bound Change Set and the delivery record that the Forge 2.0 architecture specifies arrive with the Forge binding and do not change what is written here.
- Planning delta: the new or changed Feature, Key Concept, Capability, Journey and Acceptance Test Set files under the owning module (
specs/<pa>/<module>/planning/…), withrevisionbumped on every changed artifact and achange: RS-nnnfield added (a list when several tickets touched it:changes: [RS-16, RS-21]). A changed rule row carriesorigin: RS-nnn(and the decision it implements, if any).statusof a changed approved artifact goes back todraftuntil the gate approves it;product_intentis unchanged unless the ticket carries a product decision. - Design delta: the changed Screen Contract, Service Contract, Domain Object, State Model, Workflow and Decision Record files under
specs/<pa>/<module>/design/…, the same way; a new material choice is a newADR-that namesorigin: RS-nnn. - Implementation delta:
specs/<pa>/<module>/implementation/plans/PLAN-RS-nnn.md(the Implementation Plan, frontmatter:id: PLAN-RS-nnn,change,product_area,module,base_shaper repository,status,work_items[]as the architecture defines them) and one Screen Implementation Specificationspecs/<pa>/<module>/implementation/screens/SCI-<PA>-<MOD>-NNN-<slug>.mdper screen the ticket touches (the same number as the Screen Contract; v0 design reference, components, loads, actions, save, events, errors, rules enforced, non-behaviours, states, permissions, pseudocode only where non-trivial). The plan is retained after merge as evidence and never edited afterwards. - A delta never edits another module's artifacts; a cross-module effect is a finding in the other module's
FINDINGS.mdnaming the ticket. - Ids are allocated in the owning module's
ID_REGISTRY.mdbefore writing, as always. - Acceptance:
npm run checkat the repository root passes on the branch; a Change whose branch fails it is not ready for its gate. The conformance check is the corpus's gate leg; Forge's own specification check does not run on this corpus. - Landing: by pull request or fast-forward onto
masteronce the gate approved the delta; the tip commit must carry a Vercel team member's author identity or the reader does not redeploy (a corpus master that is ahead of the reader is still the record).
12. Controls
Security, privacy, availability and AI obligations are requirements, not audit paperwork (Forge's control catalogue, adopted for Rhythm; Andrew, 2026-10-23). The corpus carries one control catalogue, specs/CONTROLS.md: frontmatter controls[] { id (TC-<FAMILY>-NNN, the families Forge uses: IAM, AZ, TEN, SEC, CRY, DAT, LOG, MON, AVL, CHG, VEN, PRV, PI, AI, ORG), title, family, class (preventive | detective | corrective, and manual | automated), applies_when, verification, evidence_source }, and a body that states each control in one paragraph. The ids are Forge's so that Forge's control scan, applicability triggers and release gate read this corpus unchanged; the wording is Rhythm's (workspace, never the forbidden word).
Every Capability, Workflow, Screen Contract, Service Contract and Inference Operation carries controls[]: the catalogue ids that apply to it, derived from what it touches (a permission, a workspace boundary, a secret, classified data, a model call, a privileged action, a lifecycle transition), or an empty list with controls_note saying why none applies. The checker refuses a control id that is not in the catalogue, and warns when an artifact that names a permission or a model carries no control. A control that applies but is not satisfied is a finding (kind: control-gap) in the module's FINDINGS.md, never silently dropped. Proof that a control operates lives where the control says it does (the acceptance scenarios and, later, the test suites and evidence register of the implementation stage).
13. The Narrative Stage
Every module passes through a narrative stage after its testing stage lands (Andrew, 2026-10-23): a Claude job assembles the evidence dossier (reports/NARRATIVE-EVIDENCE-<date>.md, machine-shaped), an OpenAI job writes every explanatory section of the module's features, capabilities, concepts, journeys and charter to EXPLANATORY-STANDARD §6 and records narrative_sources, and a second OpenAI job in fresh context reviews each artifact against EXPLANATORY-STANDARD §8 and the evidence, corrects what it can, and writes reports/NARRATIVE-REVIEW-<date>.md with a verdict per artifact (verified or needs-revision with reasons). Landing sets explanatory_standard: 1 on the charter. The stage is run by tools/fleet/corpus-run.py (loop narrative), tracked in tools/fleet/state.json and the reverse-engineering dashboard, with brief templates briefs/templates/narrative-*.brief.md; every planning, design, examination and ticket-delta brief carries the same standard through the shared fragment briefs/templates/fragments/explanatory-standard.md. When a capability's rules change, node tools/narrative-impact.mjs --since <sha> lists the narratives that depend on it; the change revises them or marks them stale (§6 rule 8).
14. Product Area Architecture Records (ARCH-<PA>-NN)
Every product area's architecture was decided in Claude artifacts before reverse engineering began (the Rhythm 2.0 Architecture Library, https://claude.ai/artifact/F1CnoVHxwPNka8Rc2crgbX). Those decisions belong in the corpus, not in a chat tool (Andrew, 2026-10-23): a reader who opens an area sees its architecture before its modules, and a job that reverse engineers an area reads the architecture it was built to.
Registry. specs/PRODUCT-AREAS.md carries an ## Architecture Artifacts table: one row per architecture artifact per product area (Area, Artifact title, URL, Library status as the library shows it, Record id once converted). An area may have several (CRM: the CRM architecture, Households, Data Enrichment). Superseded artifacts are not registered unless the superseding one is missing.
Records. Each registered artifact becomes one record specs/<pa>/architecture/ARCH-<PA>-NN-<slug>.md (the index) with its parts under specs/<pa>/architecture/ARCH-<PA>-NN-<slug>/NN-<slug>.md, one part per part of the artifact, in the artifact's order, converted verbatim from the artifact's HTML to Markdown (headings, prose, tables, lists, code; Mermaid as fenced mermaid; mockups as their figure captions plus a note that the mockup lives in the artifact). The conversion changes no sentence: an architecture record is evidence of what was decided, and OpenAI rewrites nothing in it. Index frontmatter: id, title, product_area, revision, status (proposed | approved | superseded, as the library shows it), source { artifact_url, artifact_title, library_group, library_status, artifact_version (when known), converted_at, converted_by }, parts[] { n, file, title }, decisions[] (optional: the artifact's decision ids and their recorded outcome, copied from its decisions part), modules[] (MOD ids the record governs, once they exist). Each part file carries part_of, part, title. The index body is ## What This Record Is (three to five sentences, written by OpenAI, saying what the artifact decided and for whom) and ## Parts (the parts in order with one line each, from each part's lede). AREA.md carries architecture[] (the ARCH ids) and the reader shows them under "Architecture" on the area page, before the modules.
The area page is the final document. The records are the verbatim sources; the reader reads the architecture on AREA.md (§5.0c), where OpenAI has composed the records' architecture chapters with the area overview into one document (Andrew, 2026-10-23). The runner's area_architecture <pa> job composes it once every registered artifact of the area has a record, and recomposes it when a record changes; AREA.md names the parts each chapter rests on in narrative_sources[].
Stage and automation. Architecture records are planning-stage artifacts and precede every module of the area: tools/fleet/corpus-run.py refuses to submit a planning draft for a module whose area has a registered artifact without a record (arch_missing), and the planning and design brief templates list the area's records as evidence to read first. Conversion is local work (the fleet cannot read Claude artifacts): node tools/arch-import.mjs <pa> <saved artifact html> --title … --url … writes the index and the parts from an artifact saved with the Artifact tool; the person or session that registers an artifact converts it in the same change. When Andrew publishes a new version of an artifact, the record's revision increments and source.artifact_version and converted_at move; a superseded artifact's record is marked superseded with superseded_by.
15. Traceability: Where a Capability Lives and What Proves It
Rhythm 1.0's capability specifications related every capability to the services that implemented it, and that single field was what let the Rhythm Investigator answer "which repository does this live in" without reading code. The 2.0 corpus keeps that and adds the proof link (Andrew, 2026-10-23).
Where it lives. Every Capability carries repositories[], one row per repository that implements any part of it: { repo, role (owner | console | library | consumer | job), paths[] }, where paths are the directories or files under which the behaviour lives (from the rule and scenario source fields, the module's registered source scope and the console routes). owner is the service repository whose module holds the rules; console is react-console; library is macroservice-libraries when a rule is enforced there; consumer is another service that calls it; job is a repository whose scheduled or event-driven code performs it. The drafter writes repositories[]; the checker warns when a repository named in a rule or scenario source is missing from it and errors once the module's charter carries traceability: 1. Service Contracts already carry repository; Screen Contracts carry route; Workflows carry hops[] with their repositories; nothing changes there.
What proves it. Proof is authored on the test side and only there (one home per fact): a Capability Test Specification scenario proves[] rule ids, a Feature Acceptance Suite scenario exercises[] capability ids, a Product Acceptance Suite step exercises[] capability ids, an Executable Test Suite implements[] scenario ids. From those, node tools/trace-sync.mjs [<pa>/<module>] derives and writes, at every landing, the reverse index on the planning side: each rules[] row gains proved_by[] (the ATS scenario ids that prove it and the TST ids that implement those scenarios); each Capability gains exercised_by[] (FAS and PAS scenario ids) and suites[] (TST ids); each Feature gains acceptance_suite (its FAS id); each Journey gains proved_by[] (PAS scenario ids whose steps cover its capabilities). These derived fields are never hand-written: the tool rewrites them from the authoritative links, and the checker reports a derived field that disagrees with the links as an error. The same tool writes specs/<pa>/<module>/TRACEABILITY.md: one table per capability (rule → proving scenarios → suites → latest result from the suites' latest_result), a repositories table (capability → repositories and paths), and the gaps (must_prove rules with no proof, capabilities with no suite). The reader renders it as the module's "Traceability" page, and a Capability page shows "Where it lives" and, per rule, its proof.
Why on the rule row and not a requirement kind. A business requirement in the 2.0 corpus is a rule row on its capability (§5.1): the rule's statement is the requirement, must_prove says a proof is owed, and proved_by names the proof. A separate requirement document would be a second home for the same sentence.