From ce9556d793659e6b5957f54591292ace25841568 Mon Sep 17 00:00:00 2001 From: Anthony James Padavano <24796448+4444J99@users.noreply.github.com> Date: Mon, 31 Aug 2026 20:05:37 -0400 Subject: [PATCH] docs: adopt reader-mode repository policy --- CHANGELOG.md | 4 ++ README_STANDARDS.md | 156 +++++++++++++++++++++++++++++++++++++------- 2 files changed, 137 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5cf2bfb..b5e875f 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README_STANDARDS.md b/README_STANDARDS.md index 384cb4b..edea0ae 100644 --- a/README_STANDARDS.md +++ b/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.