Merge pull request #112 from nold-ai/dev

Release dev to main

Author: djm81

AGENTS.md

@@ -42,6 +42,8 @@ pre-commit install
 pre-commit run --all-files
 ```
 
+Staged `*.py` files trigger `hatch run lint` (includes pylint) via `scripts/pre-commit-quality-checks.sh`, matching `.github/workflows/pr-orchestrator.yml`.
+
 ## Development workflow
 
 ### Branch protection

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this repository will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows SemVer for bundle versions.
 
+## [Unreleased]
+
+### Added
+
+- Documentation: authoritative `docs/reference/documentation-url-contract.md` for core vs modules URL ownership; `redirect_from` aliases for legacy `/guides/<basename>/` on pages whose canonical path is outside `/guides/`; sidebar link to the contract page.
+
 ## [0.44.0] - 2026-03-17
 
 ### Added

README.md

@@ -8,6 +8,7 @@ This repository hosts official nold-ai bundles only.
 - Official bundles are maintained under `packages/`.
 - Third-party bundles are published from third-party repositories and are not hosted here.
 - Bundle and module documentation changes are made in this repository under `docs/`.
+- Cross-site linking rules and canonical paths for core→modules handoffs: `docs/reference/documentation-url-contract.md` (published: `https://modules.specfact.io/reference/documentation-url-contract/`).
 - GitHub Pages documentation target: `https://nold-ai.github.io/specfact-cli-modules/`.
 
 ## Local development (IDE / Cursor)
@@ -53,6 +54,7 @@ pre-commit run --all-files
 ```
 
 Scope notes:
+- Pre-commit runs `hatch run lint` when any staged file is `*.py`, matching the CI quality job (Ruff alone does not run pylint).
 - `ruff` runs on the full repo.
 - `basedpyright` and `pylint` are scoped to `src/`, `tests/`, and `tools/` for modules-repo infrastructure parity.
 - Bundle-package behavioral validation is covered through `test`, `contract-test`, and migration-specific suite additions under `tests/`.

docs/_layouts/default.html

@@ -222,6 +222,7 @@ <h2 class="docs-sidebar-title">
 
               <p class="docs-nav-section">Reference</p>
               <ul>
+                <li><a href="{{ '/reference/documentation-url-contract/' | relative_url }}">Core vs modules URL contract</a></li>
                 <li><a href="{{ '/reference/' | relative_url }}">Reference Documentation</a></li>
                 <li><a href="{{ '/reference/commands/' | relative_url }}">Command Reference</a></li>
                 <li><a href="{{ '/reference/thorough-codebase-validation/' | relative_url }}">Thorough Codebase Validation</a></li>

docs/guides/ai-ide-workflow.md

@@ -2,6 +2,8 @@
 layout: default
 title: AI IDE Workflow Guide
 permalink: /ai-ide-workflow/
+redirect_from:
+  - /guides/ai-ide-workflow/
 ---
 
 # Legacy Workflow Note

docs/guides/brownfield-engineer.md

@@ -2,6 +2,8 @@
 layout: default
 title: Modernizing Legacy Code (Brownfield Engineer Guide)
 permalink: /brownfield-engineer/
+redirect_from:
+  - /guides/brownfield-engineer/
 ---
 
 # Legacy Workflow Note

docs/guides/brownfield-faq.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Brownfield Modernization FAQ
+permalink: /brownfield-faq/
+redirect_from:
+  - /guides/brownfield-faq/
+---
+
 # Brownfield Modernization FAQ
 
 > **Frequently asked questions about using SpecFact CLI for legacy code modernization**

docs/guides/brownfield-journey.md

@@ -2,6 +2,8 @@
 layout: default
 title: Brownfield Modernization Journey
 permalink: /brownfield-journey/
+redirect_from:
+  - /guides/brownfield-journey/
 ---
 
 # Legacy Workflow Note

docs/guides/brownfield-roi.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Brownfield Modernization ROI with SpecFact
+permalink: /brownfield-roi/
+redirect_from:
+  - /guides/brownfield-roi/
+---
+
 # Brownfield Modernization ROI with SpecFact
 
 > **Calculate your time and cost savings when modernizing legacy Python code**

docs/guides/common-tasks.md

@@ -2,6 +2,8 @@
 layout: default
 title: Common Tasks Quick Reference
 permalink: /common-tasks/
+redirect_from:
+  - /guides/common-tasks/
 ---
 
 # Legacy Workflow Note