# 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//` 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`](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 ```text 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 / / 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---NN-.md the parent: names and groups its concepts, actors, capabilities and journeys concepts/CON---NNN-.md one per noun, in product language capabilities/CAP---NNN-.md journeys/JNY---NNN-.md acceptance/FAS---NN-.md Feature Acceptance Suite, the same number as its feature ACTORS.md the product area's actors (one table; ids ACT--NNN), shared by its modules design/ §9: objects/, state-models/, workflows/, contracts/, screens/, decisions/, inference/ tests/ATS---NNN-.md Capability Test Specification, the same number as its capability (§9.10) implementation/ §10: plans/ per ticket, screens/ (SCI), tests/TST---NNN-.md executable suites qa/ §10: TER- test execution reports and DQR- delivery qualification reports per ticket acceptance/PAS--NNN-.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 `` is the product-area code and `` the module code from `PRODUCT-AREAS.md`. | Artifact | Id | Example | |---|---|---| | Module charter | `MOD--` | `MOD-CRM-ENT` | | Feature | `FEAT---NN` | `FEAT-CRM-ENT-02` | | Key Concept | `CON---NNN` | `CON-CRM-ENT-003` | | Actor (row in the product area's ACTORS.md) | `ACT--NNN` | `ACT-CRM-002` | | Capability Specification | `CAP---NNN` | `CAP-CRM-ENT-004` | | Business rule (row inside a capability) | `BR--NN` | `BR-CAP-CRM-ENT-004-03` | | Scenario or edge case (row inside a capability) | `SC--NN` | `SC-CAP-CRM-ENT-004-02` | | Journey | `JNY---NNN` | `JNY-CRM-ENT-002` | | Journey assertion (row inside a journey) | `AS--NN` | `AS-JNY-CRM-ENT-002-01` | | Acceptance Test Set | `ATS---NNN` | `ATS-CRM-ENT-004` | | Acceptance scenario (row inside a set) | `ATS---NNN-NN` | `ATS-CRM-ENT-004-07` | | Finding | `FND---NNN` | `FND-CRM-ENT-012` | | Open question | `OQ---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.md` with one word (`deleted`); no `superseded` or `deprecated` status, no `supersedes` field, no change history. Versioning (revision bumps, `change` fields, 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.md` before 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: `-.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. ```yaml 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-investigated ``` `status` 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`](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//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-`) One per product area, `specs//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-`), `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--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//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--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---NN` for `FEAT---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---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), `## Permissions` (the permission keys the module's capabilities, screens and operations use, what each protects, which roles of the area's authorization model grant them and where they are checked; the one place a reader learns who may do what in this module, pointing at the area model in words; Andrew, 2026-10-23), `## 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 1. YAML frontmatter as above, the structured content first. 2. An H1 that is the title, never the id. 3. The body sections the kind defines, in order. Sections with nothing to say are omitted, never filled with "None". 4. Headings in Title Case; identifiers and code never recased. 5. 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-row `source`, an optional `evidence[]` list of what was read); artifacts carry no `## Evidence` body section. The reader shows evidence only behind a toggle that is off by default. 6. 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 …" with `product_intent: proposed`). 7. **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. 8. **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.md`](EXPLANATORY-STANDARD.md) defines 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 in `narrative_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 changes `status`, `product_intent` or `design_intent`. Each such artifact carries `narrative { revision, status (enriched | verified | needs-revision | stale), review, stale_since }`; a module whose charter carries `explanatory_standard: 1` has the standard enforced by `npm 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: ```text specs//RESPONSIBILITIES.md RESP-: what each module of the product area is responsible for specs//AREA.md AREA-: the product area overview (purpose, scope, boundaries, module map) specs//AUTHORIZATION.md AUTH-: the product area's authorization model (roles, permission keys, how they compose) specs/CONTROLS.md the corpus control catalogue (TC--NNN), one for all product areas specs///design/ objects/DOM---NNN-.md Domain Object, the same number as its Key Concept state-models/STATE---NNN-.md State Model, one per real lifecycle workflows/WF---NNN-.md Workflow Specification, one per multi-step or asynchronous flow contracts/SVC---.md Service Contract, one per macroservice module the corpus module covers screens/SCR---NNN-.md Screen Contract, one per console or portal screen decisions/ADR---NNN-.md Decision Record inference/IOP---NNN-.md Inference Operation, one per question the product asks a model tests/ATS---NNN-.md Capability Test Specification, the same number as its capability ``` The 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. **Depth** (Andrew, 2026-10-23, after reading the Entities design: "the screen designs look naked; the domain object should have its key properties; where is my permission model"): design artifacts carry the level of detail Tribal's specifications carry. A domain object names and explains every key property; a state model says what each state means, what is allowed in it and who may move it; a screen contract says who can reach it, what it shows field by field, what every action does and how it is refused, and what the person sees in every state; a workflow explains every hop; a service contract explains every operation and its permission. EXPLANATORY-STANDARD §6.7 gives the sections and what each must answer; a module whose charter carries `explanatory_standard: 1` has them enforced. ### 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, set_by (staff | system | integration | import), rules (limits, formats, uniqueness, defaults, in words), example, notes }` (logical, never columns; every key property the product exposes, not a sample), `identity`, `relationships[] { to (DOM id), cardinality, ownership, cross_service, on_archive_or_delete (what happens to the link) }`, `invariants[] { id INV--NN, statement, protects (what breaks if it fails), enforced_at, provenance, source }`, `permissions[] { action (read | create | update | archive | delete | …), permission (the key from the area's authorization model), by_state (optional) }`. 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` (every key property in prose or a table: what it means to the business, who sets it, its rules and an example; the reader learns the object's shape here), `## Relationships` (each one explained: cardinality, ownership, what happens when one side is archived or deleted), `## Lifecycle` (where one exists, in words, pointing at the state model), `## Invariants` (each explained: what it protects and what would go wrong without it), `## Permissions` (who may read, create, change, archive and delete it, by state where that varies, from the area's authorization model), `## 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; the single authority for that object's states (no feature, capability, journey or screen defines one inline). Required: `id`, `title`, `object` (DOM id), `product_area`, `module`, `revision`, `status`, `design_intent`, `implementation_evidence`, `source_sha`, `states[] { name, meaning, entry_conditions, allowed_actions[], terminal, reversible }`, `transitions[] { from, to, trigger, guard, side_effects[], who, audit_event, provenance, source }`, `invalid[] { from, to, why, response (what the person or caller gets) }`, `concurrency`. Optional: `automatic[] { from, to, when (the time or event that moves it without a person) }`, `permissions_by_state[] { state, action, permission }`, `invariants[]` (INV ids), `ai_may_recommend`, `ai_may_execute`, `evidence[]`. Body: `## Purpose` (why this object has a lifecycle and which outcomes depend on explicit states), `## Ownership and Authority` (who may request each transition, which events may, whether a model may recommend or execute one), `## The Lifecycle` (a Mermaid state diagram), `## States` (each state explained: what it means to staff, what is allowed and forbidden in it, what people see), `## Transitions Explained` (each transition: what starts it, what must be true, what else changes, what is recorded), `## What Cannot Happen` (each refused transition and the response), `## Permissions by State` (where who-may-do-what depends on the state), `## Concurrency and Timing` (two actors at once; automatic transitions and their timing), `## Invariants` (each explained). ### 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`, `## What Starts It` (the trigger, who or what, and the preconditions), `## The Flow` (a Mermaid sequence or flowchart), `## Hop by Hop` (each hop explained: who or what acts, what happens, the seam it crosses, what is written), `## When Something Fails` (per hop: what is retried, compensated, or left inconsistent, what the person sees and who notices), `## Repeats and Races` (idempotency and concurrency in words), `## What Is Observable` (what the person sees while it runs and when it ends; what operators see), `## 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-`) One per product area, `specs//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 `## ` 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/` 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: ') }`, `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`, `## What It Owns` (each owned object and what ownership means for callers), `## Operations in Words` (grouped by capability: each operation, who calls it, what it does, what it refuses and why, and the permission it checks), `## Permissions` (the permission keys the operations check, from the area's authorization model, and who holds them), `## 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; to the depth of Tribal's screen specifications (Andrew, 2026-10-23). 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` (the entry permission key, or `none` with why), `actors[] { actor (ACT id), access (view | edit | admin | deny), conditions }`, `entry_from[]`, `exits_to[]`, `layout[]` (the information hierarchy: the regions of the screen in reading order, each with what it holds), `displays[] { field, type, required, editable, validation (formatting or the rule, in words), source (DOM attribute or operation) }`, `actions[] { label, actor, operation_id, permission, availability (hidden | disabled | refused when not permitted, and any state condition), result, confirm, failure (what the person sees when it fails) }`, `states[] { state, experience }` for every state that applies of: initial, empty, loading, partial, success, validation error, system error, permission denied, expired or unavailable, stale or concurrent, offline or interrupted, read-only, `refusals[] { condition, sees, goes }` (not permitted; session expired; resource not visible), `sensitive_display { classified[], withheld[], never_rendered[], confirmation[], reauthentication[] }` or `sensitive_display: none` with why, `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), `accessibility` (what a screen reader is told, keyboard paths, responsive behaviour), `evidence[]`. Body: `## What the Screen Is For`, `## Who Can Reach It` (actors and access; screen access is not authorization: every action is refused server-side by its operation whatever the screen shows), `## Layout and Information Hierarchy`, `## What It Shows` (field by field: what it means, where it comes from, how it is formatted, what is editable), `## What People Can Do` (each action: who, what happens, how it is offered to someone without the permission, confirmation, failure), `## States and Errors` (what the person sees in every state), `## Sensitive Display and Refusals`, `## Patterns It Must Respect`, `## Accessibility and Responsive Behavior`. 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---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---NNN-NN — ` 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**, where a suite is one runner invocation or one cohesive group of test files (a Playwright project or journey area, a service's integration suite for one concept, an e2e suite), never one file (Andrew, 2026-10-23: a module registered one artifact per spec file with identical prose; a module has typically three to fifteen suites and each register's prose is specific to that 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/…`), with `revision` bumped on every changed artifact and a `change: RS-nnn` field added (a list when several tickets touched it: `changes: [RS-16, RS-21]`). A changed rule row carries `origin: RS-nnn` (and the decision it implements, if any). `status` of a changed approved artifact goes back to `draft` until the gate approves it; `product_intent` is 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 new `ADR-` that names `origin: 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_sha` per repository, `status`, `work_items[]` as the architecture defines them) and one **Screen Implementation Specification** `specs/<pa>/<module>/implementation/screens/SCI-<PA>-<MOD>-NNN-<slug>.md` per 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.md` naming the ticket. - **Ids** are allocated in the owning module's `ID_REGISTRY.md` before writing, as always. - **Acceptance**: `npm run check` at 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 `master` once 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.