Adopt the reader-mode documentation policy across ORGANVM

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to the meta-organvm org-level community health files.
 ## [Unreleased]
 
 ### Added
+- Reader-mode documentation classes, progressive-disclosure sequence, canonical
+  project/evidence boundaries, and enforcement guidance in `README_STANDARDS.md`
+- Explicit authority split between fleet policy, editorial templates, and
+  machine contracts; minimal project records for deployment/archive classes
 - Initial community health files (README, CONTRIBUTING, CODE_OF_CONDUCT, templates)
 - Organization-level CI workflow templates
 - organ-aesthetic.yaml visual identity cascade

README_STANDARDS.md

@@ -1,12 +1,15 @@
 # README Standards
 
-Canonical README policy for all ORGANVM repositories across all organs.
+Organization-wide adoption policy for README and reader-mode documentation
+across all ORGANVM repositories.
 
 ## Scope
 
-This file is the source of truth for:
+This file defines fleet adoption requirements for:
 
 - README structure and depth by tier
+- applying reader-mode repository classes and required audience routes;
+- requiring the canonical project-record and evidence contracts;
 - Organ-specific required sections
 - Minimum quality rubric used for audits
 - Minimum community-health and root-hygiene requirements tied to README quality
@@ -19,21 +22,88 @@ Derived from the system corpus standards:
 
 ## Universal README Model
 
-Every README should follow progressive disclosure:
-
-1. Hero: title, key badges, one-line hook, quick navigation
-2. Value: problem statement / purpose
-3. Action: setup, usage, examples
-4. Context: cross-references, contributing, license, author
-
-## Tier Requirements
-
-| Tier | Target | Minimum |
-|------|--------|---------|
-| Flagship | 3,000+ words | 12+ sections, complete 4-layer model |
-| Standard | 1,000+ words | 8+ sections, complete 4-layer model |
-| Stub | 200+ words | title, purpose, status, parent links |
-| Archive | 50+ words | archive notice + redirect |
+Every README should follow progressive disclosure. The reader should receive
+orientation before being asked to interpret mechanism or proof:
+
+1. **Recognition:** what this is, in ordinary language
+2. **Relevance:** problem, user, present state, and one concrete example
+3. **Route:** audience-specific inspection paths appropriate to the repository
+4. **Mechanism:** architecture, method, operation, or formal construction
+5. **Evidence:** status, authorship, tests, provenance, and limitations
+6. **Depth:** the canonical long-form intellectual and technical treatment
+
+The README remains the hub and principal exhibition. It does not need to contain
+every edition in one linear sequence.
+
+## Reader-mode contract
+
+One factual project may have several audience-specific editions. They may change
+order, terminology, examples, assumed knowledge, and evidence emphasis. They may
+not change project status, authorship, capabilities, limitations, deployment,
+adoption, outcomes, or evidence state.
+
+Definitions do not originate here. The canonical editorial specification and
+templates live in
+[`organvm/editorial-standards`](https://github.com/organvm/editorial-standards).
+Machine-readable project and evidence contracts live in
+[`organvm-iv-taxis/schema-definitions`](https://github.com/organvm-iv-taxis/schema-definitions):
+
+- [reader-mode standard](https://github.com/organvm/editorial-standards/blob/main/docs/reader-mode-documentation.md)
+- [project-record schema](https://github.com/organvm-iv-taxis/schema-definitions/blob/main/schemas/project-record-v1.schema.json)
+- [assertion-evidence schema](https://github.com/organvm-iv-taxis/schema-definitions/blob/main/schemas/assertion-evidence.v1.schema.json)
+- [README v2 template](https://github.com/organvm/editorial-standards/blob/main/templates/repository-readme-v2.md)
+- [audit rubric](https://github.com/organvm/editorial-standards/blob/main/schemas/reader-mode-rubric.yaml)
+
+### Repository classes
+
+Documentation class describes repository function, not quality or prestige.
+Promotion tier and documentation class are separate fields.
+
+| Class | Repository function | Contract |
+|---|---|---|
+| A | Flagship system spanning several audiences | README v2, five audience editions, evidence record, project record |
+| B | Major project with two or three material audiences | README v2, 2–3 audience editions, evidence record, project record |
+| C | Supporting component, library, schema, or infrastructure | Technical route, interfaces/status/evidence, project record |
+| D | Deployment artifact, player, mirror, or delivery shell | Minimal use/deployment README, project record, and canonical-project redirect |
+| E | Research, theory, scholarship, or artistic corpus | Humanities/scholarly route, mechanism, sources/provenance, project record |
+| F | Archive, superseded surface, contribution record, or reference | Project record, immutable status, provenance, successor/redirect when one exists; no SEO expansion |
+
+Do not inflate deployments and mirrors into independent projects. Do not require
+commercial framing from art/theory repos or multi-audience bloat from supporting
+components.
+
+### Class A/B first screen
+
+Before the inherited long-form README, establish:
+
+1. title and one ordinary-language sentence;
+2. verified artifact, demo, documentation, and evidence links;
+3. a short “What am I looking at?” explanation;
+4. a “Choose your reading path” table;
+5. a current-state table with users, contribution, evidence, and limitations.
+
+Long READMEs are allowed. Difficult language is allowed. The contract controls
+the order in which complexity becomes visible; it does not flatten the work.
+
+## Canonical project record
+
+All classes maintain `project-record.yml`; classes D and F use the smallest
+class-valid record. It is the factual substrate for repeated status,
+contribution, evidence, industry, and link blocks. Generated blocks may be
+surrounded by hand-written audience analysis, but may not be edited
+independently.
+
+Every material claim resolves to `assertion-evidence.v1`, whose canonical
+`verification_state` is `unverified`, `verified`, `stale`, or `disputed`.
+Project records separately carry a reader-facing claim posture such as
+`implemented`, `partial`, `proposed`, `unknown`, or `contradicted`; posture never
+substitutes for verification state. A proposed industry application is not a
+deployment. A source path is not evidence of adoption, scale, performance, or
+business outcome.
+
+Canonical ownership must be resolved before generation. A personal mirror and an
+organization repository may not both present themselves as the same canonical
+project.
 
 ## Organ-Specific Required Sections
 
@@ -103,7 +173,7 @@ Every README should follow progressive disclosure:
 - Publishing Calendar
 - Templates or Playbooks
 
-## README Quality Rubric (0-100)
+## README quality and reader-mode rubric
 
 ### Existence and Accessibility (0-20)
 - README exists in root
@@ -130,6 +200,20 @@ Every README should follow progressive disclosure:
 - features/value proposition clear
 - evidence or impact signals present
 
+The historical 0–100 README rubric remains a coarse completeness check. Reader-
+mode conversion uses a separate 0–4 diagnostic across:
+
+1. orientation;
+2. technical depth;
+3. conceptual depth;
+4. commercial/operational relevance;
+5. evidence and claim boundaries;
+6. legitimate search-intent surface;
+7. cross-linking.
+
+Scores describe the documentation interface, not project worth. Rank conversion
+by value, documentation gap, and reuse leverage—not by lowest score alone.
+
 ## Root Hygiene and Community Files
 
 At minimum, each active repo should include:
@@ -146,6 +230,16 @@ Flagship and Standard repos should also include:
 - pull request template
 - issue templates for bug and feature/documentation requests
 
+All reader-mode classes should also include:
+
+- `project-record.yml`
+- a claim-level evidence path
+
+Classes A–C and E additionally include the required `docs/audiences/*.md`
+routes for their declared class. Classes D and F keep their minimal usage,
+redirect, archive, provenance, and status material in the root README; they do
+not create a nominal audience edition merely to satisfy structure.
+
 ## Local Overlay Policy
 
 Each organ may keep an overlay standards file in its `.github` repository:
@@ -157,14 +251,30 @@ Each organ may keep an overlay standards file in its `.github` repository:
 
 ## Enforcement
 
-Each organ superproject should provide a local audit script:
+The executable reference implementation lives in
+[`organvm/organvm-engine`](https://github.com/organvm/organvm-engine):
 
-- recommended path: `tools/audit_platform_standards.sh`
+```bash
+organvm docs validate project-record.yml --schema path/to/project-record-v1.schema.json
+organvm docs audit . --format markdown
+organvm docs audit --workspace "$ORGANVM_WORKSPACE_DIR" --format json
+```
+
+Each organ superproject may retain `tools/audit_platform_standards.sh`, but it
+should delegate reader-mode checks to the reference implementation rather than
+reimplementing status or scoring vocabularies.
 
 Each audit should check, at minimum:
 
-1. required standards files exist
-2. README has minimum section structure for its tier/profile
-3. local overlay links to this canonical policy
+1. required standards files exist;
+2. README supplies the orientation appropriate to its class;
+3. `project-record.yml` validates and its audience paths exist;
+4. claim IDs, status vocabularies, and evidence references are internally sound;
+5. local overlay links to this canonical policy.
+
+Factual integrity errors fail CI. Editorial opportunities—thin orientation,
+orphan docs, low rubric dimensions, duplicated prose, or missing semantic
+cross-links—warn and enter the conversion queue. A rubric score alone never
+blocks publication.
 
 Any exception must be tracked via issue with owner + due date.