Skip to content

docs: README overhaul + documentation restructure#16

Merged
dacervera merged 3 commits into
mainfrom
docs/readme-and-structure-overhaul
Mar 12, 2026
Merged

docs: README overhaul + documentation restructure#16
dacervera merged 3 commits into
mainfrom
docs/readme-and-structure-overhaul

Conversation

@dacervera

Copy link
Copy Markdown
Contributor

What changed

README.md rewritten as a focused landing page (~120 lines, down from ~400):

  • Kept the 1st-person Quorum voice and compelling narrative
  • Quick demo → comparison table → installation options
  • Platform ports section (Copilot CLI, Claude Code)
  • Model tiers (trimmed)
  • Documentation table linking to organized docs

Documentation reorganized by intent:

Directory Contents
docs/getting-started/ Installation, Quick Start, For Beginners, Tutorial, Model Requirements
docs/configuration/ Config Reference
docs/guides/ Rubric Building Guide, Cross-Artifact Design
docs/architecture/ The Nine Critics, Implementation Notes
docs/critics/ Security, Code Hygiene, Tester, SEC-02 through SEC-07, PowerShell
docs/reviews/ External Reviews

New files:

  • docs/getting-started/QUICK_START.md — first validation in 60 seconds
  • docs/README.md — navigation hub with categorized links

All internal cross-references updated across 30+ files. Git rename tracking preserved for all moved files.

Akkari added 3 commits March 12, 2026 13:40
README.md rewritten as a focused landing page:
- Kept the 1st-person Quorum voice
- Compelling narrative → quick demo → comparison → install
- Platform ports section (Copilot CLI, Claude Code)
- ~120 lines vs ~400 lines before

Documentation reorganized by intent:
- docs/getting-started/ — install, quick start, beginners, models
- docs/configuration/ — config reference
- docs/guides/ — rubric building, cross-artifact design
- docs/architecture/ — spec, the nine, implementation
- docs/critics/ — security, code hygiene, tester, SEC-02 through SEC-07
- docs/reviews/ — external reviews

New files:
- docs/getting-started/QUICK_START.md — first validation in 60 seconds
- docs/README.md — navigation hub with categorized links

All internal cross-references updated across 30+ files.
- Fixed 7 broken relative links from docs restructure (CONFIG_REFERENCE, SPEC, CONTRIBUTING, reference-implementation paths)
- SKILL.md: '4 independent AI critics' → '6' (matches 6 shipped critics)
- README.md: version badge v0.7.0 → v0.7.2
- Version bump in critic-status.yaml + pyproject.toml
- CHANGELOG v0.7.2 entry added
@dacervera

Copy link
Copy Markdown
Contributor Author

Docs restructure + README rewrite. 23 docs reorganized into 6 categorized subdirectories. 7 broken relative links found and fixed during Quorum self-validation. 2 pre-existing stale references corrected (SKILL.md critic count, README version badge). validate-docs.py exclusion updated for new docs/reviews/ path. Version bumped to v0.7.2.

Quorum Self-Validation: 3 HIGH findings accepted (false positives) on validate-docs.py

  • HIGH (completeness, PC-002): "read_file_lines returns None but callers don't check" — False positive. Both call sites in validate_docs() and main() explicitly check if lines is None: continue.
  • HIGH (correctness, PC-004): "read_file_lines returns None on size check, inconsistent behavior" — Intentional design. Documented in docstring: "Skips files exceeding MAX_FILE_SIZE_BYTES." Callers handle None.
  • HIGH (correctness, PC-012): "External file input without content validation" — Not applicable. Developer CLI tool reading known repo files via read_text().splitlines(). No eval/exec/untrusted parsing.

3 MEDIUM (function length, code duplication, docstring mismatch) and 2 LOW (magic numbers, file handle lifecycle) are pre-existing code quality notes, not introduced by this PR. 3 additional findings excluded by Tester (L1 contradicted).

@dacervera
dacervera marked this pull request as ready for review March 12, 2026 23:00
@dacervera
dacervera merged commit de96b3c into main Mar 12, 2026
6 of 7 checks passed
@dacervera
dacervera deleted the docs/readme-and-structure-overhaul branch March 12, 2026 23:00
dacervera pushed a commit that referenced this pull request Mar 13, 2026
- Add _find_repo_root() to both prescreen implementations (ref-impl + Copilot CLI port)
- Fix traversal guard: resolve relative links against repo root (.git boundary),
  not file parent dir. Allows ../../target.md within repo while blocking escape.
- Add --scan-links [DIR] batch mode to Copilot CLI prescreen (walks all .md files)
- Add check_framework_version_strings() to validate-docs.py (flags stale version
  headers in framework docs vs critic-status.yaml)
- 9 new tests (4 ref-impl traversal + 5 batch scan)

Self-test: 0 broken links across 62 .md files.
Full suite: 883 passed, 6 skipped.

Origin: PS-007 task (2026-03-12), PR #16 retro (broken links from file moves).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant