docs: README overhaul + documentation restructure#16
Merged
Conversation
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
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). Quorum Self-Validation: 3 HIGH findings accepted (false positives) on validate-docs.py
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
marked this pull request as ready for review
March 12, 2026 23:00
This was referenced Mar 12, 2026
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).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
README.md rewritten as a focused landing page (~120 lines, down from ~400):
Documentation reorganized by intent:
docs/getting-started/docs/configuration/docs/guides/docs/architecture/docs/critics/docs/reviews/New files:
docs/getting-started/QUICK_START.md— first validation in 60 secondsdocs/README.md— navigation hub with categorized linksAll internal cross-references updated across 30+ files. Git rename tracking preserved for all moved files.