docs: define reusable repository README quality standard

[seonghobae]

Outcome

Add one organization-level README quality standard while preserving the existing ownership rule that each product repository owns its own README prose.

The standard captures the recurring high-leverage pattern discovered across active README lanes:

• product promise before implementation inventory;
• explicit product/non-goal and neighboring-authority boundaries;
• code-current install and quickstart;
• public usage/API before internal modules;
• durable status and quality signals rather than mutable PR snapshots;
• documentation, support, and contribution navigation;
• source, inherited-code, dependency, asset, and provider license due diligence;
• GPL-family commercial-intake handling without falsely describing GPL as noncommercial;
• a no-duplicate, exact-head integration loop.

Review repairs

The initial review found that the new standard was not discoverable from the repository documentation map and was missing from release history. The current head:

• links docs/repository-readme-quality-standard.md from the root README's Related documents table; and
• records the policy under CHANGELOG.md → Unreleased.

The informational copyleft-policy review is preserved: inherited obligations remain in force until sufficient relicensing rights or a safe replacement exists.

Ownership and licensing boundary

This is a review/checklist contract, not a copy-and-paste template or README generator. Repository-specific product language, security boundaries, installation reality, release state, support path, and licensing obligations remain authoritative in the owning repository.

The .github repository already carries a ContextualWisdomLab MIT root license. This documentation change introduces no dependency, copied third-party source, asset, model, or new license grant, and does not change sibling-repository licensing.

Current exact authority — 2026-09-07

• protected main: c9052e607e5f3cc76e73207e7786b21500721b79;
• exact head: bd56a9cc599e60be1b5d2a9729dea36b0e215e9f;
• ancestry: ahead 2 / behind 0, with protected main as merge base;
• changed files: README.md, CHANGELOG.md, and docs/repository-readme-quality-standard.md;
• reconciliation: normal two-parent merge commit; no force-push or destructive rebase;
• mechanically mergeable at this snapshot;
• zero unresolved inline review threads.

Exact-head CodeQL PR 34066085855, Security Scan 34066085856, SAST Semgrep 34066085876, Python Security 34066085882, OpenCode coverage jobs, and current-head admission completed successfully.

Required noema-review job 101592715849 failed only after orchestrator/free returned HTTP 502 following 780.1 seconds while serving deepseek-ai/deepseek-v4-flash-0731; it produced no README-standard finding. The transient transport failure was rerun without source churn, and replacement job 101609741798 is queued on the unchanged exact head.

Required opencode-review job 101592718134 failed closed because no authenticated opencode-agent verdict existed when it checked. Dispatch succeeded and created central owner run 34075986499, which completed failure: the free model pool was exhausted and produced no authenticated current-head verdict. Do not classify either reviewer/runtime state as a README source failure, and do not transfer predecessor evidence.

Merge boundary

Merge only through ordinary protected governance after the unchanged exact head has terminal-success applicable checks, authenticated exact-head reviewer verdicts, all valid current-head findings and threads resolved, base ancestry remains current, and the then-live review/ruleset requirements are satisfied. No self-approval, routine administrator bypass, gate weakening, source-neutral retrigger churn, or predecessor-evidence transfer.

Current review-runtime blocker — 2026-09-08

A newer exact-head admission refresh supersedes the earlier queued/retry snapshot. Noema job 101915615008 reached orchestrator/free on unchanged head bd56a9cc599e60be1b5d2a9729dea36b0e215e9f but failed closed with HTTP 429 after 47.1 seconds while serving deepseek-ai/deepseek-v4-flash-0731; its preflight evidence also records exhausted 429, 404, and timeout candidates. Current OpenCode job 101918287128 admitted the same head and failed closed because no authenticated verdict was published, while both coverage jobs succeeded. These are review-runtime failures, not README/source findings. Gateway-owned failover remains proposed on contextual-orchestrator#1049 and is not integrated or released. Do not perform further source-neutral retries or admit this README head as successful until the immutable owner fix is integrated and the unchanged head receives fresh authenticated verdicts.

This PR is Ready for review admission. The owner transport repair and authenticated current-head reviewer verdicts remain merge gates, not reasons to suppress review by keeping this documentation PR Draft.

[coderabbitai]

Warning

Review limit reached

Next included review available in 29 seconds.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 109f28c8-3730-42f4-b140-ab45ded318e5

📥 Commits

Reviewing files that changed from the base of the PR and between c9052e6 and bd56a9c.

📒 Files selected for processing (3)

• CHANGELOG.md
• README.md
• docs/repository-readme-quality-standard.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

Devin Review found 3 potential issues.

[opencode-agent]

Pull request overview

OpenCode could not approve from deterministic current-head evidence because GitHub Checks have failed.

Findings

1. HIGH Current-head GitHub Checks - Fix failed required checks before approval

• Problem: Failed same-head checks remain for bd56a9cc599e60be1b5d2a9729dea36b0e215e9f.
• Root cause: The model-unavailable evidence fallback is allowed only when peer GitHub Checks are complete and clean.
• Fix: Read and fix the failed check logs below, then rerun the current-head checks.
• Regression test: Keep the model-unavailable fallback gated on an empty failed-check rollup.

Failed checks:

• Required Noema Review/noema-review: FAILURE (https://github.com/ContextualWisdomLab/.github/actions/runs/34179093452/job/101915615008)
• noema-review check run: failure (https://github.com/ContextualWisdomLab/.github/actions/runs/34179093452/job/101915615008)

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Repository file: CHANGELOG.md"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Repository file: CHANGELOG.md"]
  R1 --> V1["required checks"]
  Evidence --> S2["Repository file: README.md"]
  S2 --> I2["repository behavior"]
  I2 --> R2["Review risk: Repository file: README.md"]
  R2 --> V2["required checks"]
  Evidence --> S3["Docs: repository-readme-quality-standard.md"]
  S3 --> I3["operator or user guidance"]
  I3 --> R3["Review risk: Docs: repository-readme-quality-standard.md"]
  R3 --> V3["docs review"]

Loading

[opencode-agent]

OpenCode Review Overview

• Head SHA: bd56a9cc599e60be1b5d2a9729dea36b0e215e9f
• Workflow run: 34181065121
• Workflow attempt: 1
• Gate result: REQUEST_CHANGES
• Coverage gate: success
• Model pool: exhausted
• Verdict: REQUEST_CHANGES
• Formal review: docs: define reusable repository README quality standard #1694 (review)