docs: URL contract, legacy /guides/ redirects, and docs-06 follow-up#109
Merged
docs: URL contract, legacy /guides/ redirects, and docs-06 follow-up#109
Conversation
Add authoritative reference/documentation-url-contract, design notes, §7 tasks, modules-docs-publishing spec updates, and redirect_from for guides whose canonical permalink is outside /guides/ so legacy modules /guides/ URLs keep working. Made-with: Cursor
📝 WalkthroughSummary by CodeRabbitRelease Notes
WalkthroughAdds a published URL contract page for core↔modules docs, links it in navigation and reference README, updates many guide pages with Jekyll front-matter (permalinks and Changes
Sequence Diagram(s)Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
- Document canonical modules.specfact.io paths for docs-07-core-handoff-conversion - Clarify mixed permalink styles (guides vs site root vs bundles) - Fix docs index Architecture link to /architecture/ - Point README and reference index at the contract for maintainers Made-with: Cursor
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openspec/CHANGE_ORDER.md`:
- Line 57: The table row starting with "| docs | 06 |
docs-06-modules-site-ia-restructure |
[`#95`](https://github.com/nold-ai/specfact-cli-modules/issues/95) | docs-01 ✅;
docs-cli-command-alignment ✅ | ✅ implemented (pending archive; §7 URL contract)
|" has one too many cells for the header; edit the row in CHANGE_ORDER.md so it
has exactly five pipe-separated columns (either remove the extra trailing cell
or merge the status note into the preceding column) so the row matches the table
header and renders correctly.
In `@openspec/changes/docs-06-modules-site-ia-restructure/tasks.md`:
- Around line 48-52: Tests do not validate task 7.4 (the requirement that pages
in docs/guides/*.md whose canonical permalink is outside /guides/ must include a
redirect_from: /guides/<basename>/), so add/update a unit test in
tests/unit/docs/test_docs_review.py to assert that for any docs/guides/*.md with
a canonical permalink not under /guides/ the frontmatter contains a
redirect_from entry matching /guides/<basename>/; implement the check by reusing
the existing test helper and fixtures around the docs review (the block around
lines 234-275) and add a failing case (and a passing case) to ensure the rule is
enforced automatically in CI.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 54b48ff5-775b-498f-9c76-6ef4a588d122
📒 Files selected for processing (29)
CHANGELOG.mddocs/_layouts/default.htmldocs/guides/ai-ide-workflow.mddocs/guides/brownfield-engineer.mddocs/guides/brownfield-faq.mddocs/guides/brownfield-journey.mddocs/guides/brownfield-roi.mddocs/guides/common-tasks.mddocs/guides/competitive-analysis.mddocs/guides/contract-testing-workflow.mddocs/guides/copilot-mode.mddocs/guides/dual-stack-enrichment.mddocs/guides/integrations-overview.mddocs/guides/migration-0.16-to-0.19.mddocs/guides/migration-cli-reorganization.mddocs/guides/migration-guide.mddocs/guides/specmatic-integration.mddocs/guides/team-collaboration-workflow.mddocs/guides/testing-terminal-output.mddocs/guides/troubleshooting.mddocs/guides/use-cases.mddocs/guides/ux-features.mddocs/guides/workflows.mddocs/reference/README.mddocs/reference/documentation-url-contract.mdopenspec/CHANGE_ORDER.mdopenspec/changes/docs-06-modules-site-ia-restructure/design.mdopenspec/changes/docs-06-modules-site-ia-restructure/tasks.mdopenspec/specs/modules-docs-publishing/spec.md
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/reference/documentation-url-contract.md`:
- Around line 31-36: Rule 4 is too strict: it currently mandates a same-basename
alias under redirect_from, but some legacy pages were renamed and need a
different slug (e.g., handoff table example devops-adapter-integration vs
devops-adapter-overview). Update the documentation text for Rule 4 to allow a
legacy alias that maps any previous guide slug to the canonical page rather than
requiring the exact same basename; reword the paragraph to say "include one or
more redirect_from entries for any legacy /guides/<old-slug>/ aliases (not
necessarily the same basename as the filename)" and keep the YAML example but
indicate that <old-slug> may differ from the current filename.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 795b357c-3ea3-4243-a725-04f72456eb71
📒 Files selected for processing (4)
README.mddocs/index.mddocs/reference/README.mddocs/reference/documentation-url-contract.md
djm81
added
documentation
…s-06 §7.4) - Merge docs-06 status into Blocked by column (five columns) - Add _list_redirect_from_routes and _guides_legacy_redirect_violation helpers - Enforce /guides/<basename>/ redirect for guides/*.md when canonical not under /guides/ - Add passing/failing unit examples plus repo-wide assertion Made-with: Cursor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@tests/unit/docs/test_docs_review.py`:
- Around line 374-396: The _list_redirect_from_routes function currently scans
the whole document and can match a "redirect_from:" in the body; restrict
parsing to YAML front-matter by first locating the front-matter block (detect a
leading '---' start delimiter near the top, find the next '---' end delimiter)
and only iterate the lines between those delimiters when searching for
"redirect_from:". Update the function to skip processing if no front-matter
block is found, and then perform the existing inner parsing logic
(_normalize_route and the "- " handling) on that sliced front-matter lines
segment.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 2e17b484-4f9b-496d-b6e0-3c2276533666
📒 Files selected for processing (2)
openspec/CHANGE_ORDER.mdtests/unit/docs/test_docs_review.py
This was referenced Mar 26, 2026
This was referenced Apr 15, 2026
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
1 participant
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.
Summary
Adds the authoritative
docs/reference/documentation-url-contract.mdon the modules site,redirect_fromentries for legacy/guides/<basename>/URLs where canonical permalinks live outside/guides/,openspec/changes/docs-06-modules-site-ia-restructuredesign + §7 tasks,modules-docs-publishingspec updates, sidebar + reference index links, andCHANGE_ORDERstatus for docs-06. Changelog[Unreleased]updated.Refs:
Scope
packages/registry/index.json,packages/*/module-package.yaml).github/workflows/*)docs/*,README.md,AGENTS.md)scripts/sign-modules.py,scripts/verify-modules-signature.py)Bundle Impact
List impacted bundles and version updates:
Validation Evidence
bundle exec jekyll buildrecommended locally indocs/afterbundle install(not run in CI agent environment).Required local gates
hatch run formathatch run type-checkhatch run linthatch run yaml-linthatch run check-bundle-importshatch run contract-testhatch run smart-test(orhatch run test)Docs-only PR; run applicable gates as needed before merge.
Signature + version integrity (required)
CI and Branch Protection
verify-module-signaturesquality (3.11)quality (3.12)quality (3.13)Docs / Pages
docs/)docs-pages.yml, if changed)specfact-clidocs updated (if applicable) — paired PR adds core summary pointing hereChecklist
/guides/URLs on modules