Release: merge dev into main (code review pylint, docs, agent-rules)

docs/agent-rules/20-repository-context.md

@@ -13,7 +13,7 @@ tracks:
   - packages/**
   - registry/index.json
   - pyproject.toml
-last_reviewed: 2026-04-12
+last_reviewed: 2026-04-16
 exempt: false
 exempt_reason: ""
 id: agent-rules-repository-context
@@ -50,7 +50,8 @@ hatch run verify-modules-signature --payload-from-filesystem --enforce-version-b
 hatch run contract-test
 hatch run smart-test
 hatch run test
-hatch run specfact code review run --json --out .specfact/code-review.json
+# manual code review: always include --bug-hunt (CrossHair longer budgets; see bundle docs)
+hatch run specfact code review run --bug-hunt --json --out .specfact/code-review.json
 ```
 
 ## Architecture

docs/agent-rules/50-quality-gates-and-review.md

@@ -13,7 +13,7 @@ tracks:
   - scripts/pre_commit_code_review.py
   - scripts/verify-modules-signature.py
   - docs/agent-rules/**
-last_reviewed: 2026-04-12
+last_reviewed: 2026-04-16
 exempt: false
 exempt_reason: ""
 id: agent-rules-quality-gates-and-review
@@ -47,7 +47,7 @@ depends_on:
 7. `hatch run contract-test`
 8. `hatch run smart-test`
 9. `hatch run test`
-10. `hatch run specfact code review run --json --out .specfact/code-review.json` (full-repo scope when required: add `--scope full`; machine-readable evidence lives at `.specfact/code-review.json` and unresolved findings block merge unless an explicit exception is documented)
+10. `hatch run specfact code review run --bug-hunt --json --out .specfact/code-review.json` (always pass **`--bug-hunt`** on manual runs so CrossHair uses bug-hunt timeouts; full-repo scope when required: add **`--scope full`**; machine-readable evidence lives at `.specfact/code-review.json` and unresolved findings block merge unless an explicit exception is documented)
 
 ## Pre-commit order
 
@@ -66,7 +66,7 @@ Run the full pipeline manually with `./scripts/pre-commit-quality-checks.sh` or
 
 ## Clean-code review gate
 
-The repository enforces the clean-code charter through `specfact code review run`. Zero regressions in `naming`, `kiss`, `yagni`, `dry`, and `solid` are required before merge.
+The repository enforces the clean-code charter through `specfact code review run`. When agents or developers invoke the review manually (outside the pre-commit helper), include **`--bug-hunt`** so the contract runner gives CrossHair the longer bug-hunt budgets documented in the code-review bundle. Zero regressions in `naming`, `kiss`, `yagni`, `dry`, and `solid` are required before merge.
 
 ## Module signature gate
 

docs/bundles/code-review/overview.md

@@ -12,7 +12,7 @@ expertise_level: [beginner, intermediate]
 
 The **Code Review** bundle (`nold-ai/specfact-code-review`) extends the shared **`specfact code`** command group with **`review`** workflows: governed review runs, **reward ledger** history, and **house-rules** skill management.
 
-Use it together with the [Codebase](../codebase/overview/) bundle (`import`, `analyze`, `drift`, `validate`, `repro`) on the same `code` surface.
+Use it together with the [Codebase](/bundles/codebase/overview/) bundle (`import`, `analyze`, `drift`, `validate`, `repro`) on the same `code` surface.
 
 ## Prerequisites
 
@@ -63,5 +63,5 @@ specfact code review rules show --help
 - [Code review run](../run/)
 - [Code review ledger](../ledger/)
 - [Code review rules](../rules/)
-- [Code review module](../../modules/code-review/)
-- [Codebase bundle overview](../codebase/overview/) — import, drift, validation, repro
+- [Code review module](/modules/code-review/)
+- [Codebase bundle overview](/bundles/codebase/overview/) — import, drift, validation, repro

docs/bundles/code-review/run.md

@@ -16,6 +16,8 @@ expertise_level: [intermediate, advanced]
 
 The command prints **progress** to the terminal (spinner/status while the pipeline prepares and runs). With **`--json`**, it writes a machine-readable **`ReviewReport`** JSON file (defaulting to **`review-report.json`** in the working directory when **`--out`** is omitted).
 
+The pipeline reviews **`.py`** and **`.pyi`** only. The **`--focus docs`** facet selects Python files whose path contains a **`docs/`** directory segment (for example tooling beside the Jekyll site), not Markdown documentation pages. For published-site link, front matter, and command-example checks on the modules docs tree, run **`python scripts/check-docs-commands.py`** in this repository (see CI and contributing docs).
+
 ## Command
 
 - `specfact code review run [FILES...]`
@@ -29,7 +31,7 @@ The command prints **progress** to the terminal (spinner/status while the pipeli
 | `--include-tests`, `--exclude-tests` | Control whether changed test files participate in auto-scope review |
 | `--focus <facet>` | Limit auto-discovered scope to **`source`**, **`tests`**, and/or **`docs`** (repeatable); mutually exclusive with `--include-tests` / `--exclude-tests` |
 | `--mode shadow\|enforce` | **`shadow`** surfaces findings without failing the exit code for policy violations; **`enforce`** applies normal gating (default **`enforce`**) |
-| `--level error\|warning` | Optional reporting level override for the review run |
+| `--level error\|warning` | Optional reporting level override before scoring: **`error`** keeps errors only (drops warnings and info); **`warning`** keeps errors and warnings (drops info only); omit to keep all severities (JSON, verdict, and `ci_exit_code` use the filtered list) |
 | `--bug-hunt` | Enable exploratory / bug-hunt style heuristics in the review pipeline |
 | `--include-noise`, `--suppress-noise` | Keep or suppress known low-signal findings |
 | `--json` | Emit a `ReviewReport` JSON file |
@@ -55,12 +57,63 @@ The Typer entrypoint validates **review flags** first: it raises **`typer.BadPar
 
 ## Examples
 
+### Auto-discovered scope (omit positional files)
+
 ```bash
+# Tracked + untracked changes; tests excluded by default for auto-scope
 specfact code review run --scope changed
+
+# Same, with bug-hunt heuristics on the discovered file set
+specfact code review run --scope changed --bug-hunt
+
+# Full index, limited to one package (repeat --path for more repo-relative prefixes)
 specfact code review run --scope full --path packages/specfact-code-review
+
+# Package sources plus that package’s unit tests
+specfact code review run --scope full --path packages/specfact-code-review --path tests/unit/specfact_code_review
+
+# Errors only before scoring — warnings and info omitted from JSON, verdict, and ci_exit_code
+specfact code review run --scope changed --level error
+
+# Longer CrossHair budgets for exploratory bug-hunt pass (with explicit files)
+specfact code review run --bug-hunt --json --out /tmp/review-bughunt.json packages/specfact-code-review/src/specfact_code_review/run/commands.py
+```
+
+### Shadow mode and JSON to a file
+
+**`--mode shadow`** runs the full toolchain but forces process exit code **`0`** and JSON **`ci_exit_code`** **`0`** so callers can ingest reports without failing a step; **`overall_verdict`** still reflects the real outcome.
+
+```bash
+specfact code review run --scope changed --mode shadow --json --out /tmp/review-report.json
+```
+
+### `--focus` facets (repeatable)
+
+Use **`--focus`** with **`source`**, **`tests`**, and/or **`docs`** (union of facets, then intersect with scope). Do not combine **`--focus`** with **`--include-tests`** or **`--exclude-tests`**.
+
+```bash
+specfact code review run --scope changed --focus tests
+specfact code review run --scope full --path packages/specfact-code-review --focus source
+specfact code review run --scope full --focus docs
+```
+
+### Positional files (explicit Python paths)
+
+Do not pass **`--scope`** or **`--path`** when **`FILES...`** are present.
+
+```bash
 specfact code review run --json --out /tmp/review-report.json packages/specfact-code-review/src/specfact_code_review/run/commands.py
 specfact code review run --score-only packages/specfact-code-review/src/specfact_code_review/run/commands.py
 specfact code review run --fix packages/specfact-code-review/src/specfact_code_review/run/commands.py
+specfact code review run --no-tests packages/specfact-code-review/src/specfact_code_review/run/commands.py
+```
+
+### Noise and interactive test inclusion
+
+```bash
+specfact code review run --scope changed --include-noise
+specfact code review run --scope changed --suppress-noise
+specfact code review run --scope changed --interactive
 ```
 
 ## Bundle-owned resources
@@ -71,4 +124,4 @@ The review pipeline uses rules, skills, and policy payloads shipped with the ins
 
 - [Code review ledger](/bundles/code-review/ledger/)
 - [Code review rules](/bundles/code-review/rules/)
-- [Code review module guide](../../modules/code-review/)
+- [Code review module guide](/modules/code-review/)

docs/bundles/codebase/overview.md

@@ -12,7 +12,7 @@ expertise_level: [beginner, intermediate]
 
 The **Codebase** bundle (`nold-ai/specfact-codebase`) mounts under `specfact code` alongside the Code Review bundle. It focuses on **brownfield import**, **contract coverage analysis**, **drift detection**, **sidecar validation**, and **reproducible validation suites**.
 
-For automated review runs (Ruff, Semgrep, ledger, rules), see [Code Review](../code-review/overview/) — also on the `code` command group.
+For automated review runs (Ruff, Semgrep, ledger, rules), see [Code Review](/bundles/code-review/overview/) — also on the `code` command group.
 
 ## Prerequisites
 
@@ -28,7 +28,7 @@ For automated review runs (Ruff, Semgrep, ledger, rules), see [Code Review](../c
 | `specfact code import` (default) | Import a repository into a project bundle (`from-code` behavior; see `--help`) |
 | `specfact code import from-bridge` | Import from an external bridge/export flow |
 
-Advanced import topics: [Project import command features](../project/import-migration/) (cross-bundle).
+Advanced import topics: [Project import command features](/bundles/project/import-migration/) (cross-bundle).
 
 ### `analyze` — structure and contracts
 

docs/bundles/govern/overview.md

@@ -47,4 +47,4 @@ specfact govern patch apply --help
 
 - [Govern enforce](../enforce/)
 - [Govern patch](../patch/)
-- [Command reference](../../reference/commands/) — nested `govern` commands
+- [Command reference](/reference/commands/) — nested `govern` commands

docs/bundles/project/overview.md

@@ -16,7 +16,7 @@ The **Project** bundle (`nold-ai/specfact-project`) manages SpecFact **project b
 
 - SpecFact CLI and a repository with `.specfact/` layout
 - Bundle installed: `specfact module install nold-ai/specfact-project`
-- For backlog-linked flows: install [Backlog](../backlog/overview/) and link a provider
+- For backlog-linked flows: install [Backlog](/bundles/backlog/overview/) and link a provider
 
 ## Command families
 
@@ -76,7 +76,7 @@ Use the top-level group (`specfact sync --help`).
 
 ## Related: codebase import
 
-Brownfield **code import** (`specfact code import`, `specfact import …`) lives in the [Codebase](../codebase/overview/) bundle; it often feeds project bundles. See [Import command features](../import-migration/) for behavior that spans both bundles.
+Brownfield **code import** (`specfact code import`, `specfact import …`) lives in the [Codebase](/bundles/codebase/overview/) bundle; it often feeds project bundles. See [Import command features](../import-migration/) for behavior that spans both bundles.
 
 ## Bundle-owned prompts and plan templates
 

docs/bundles/spec/overview.md

@@ -71,8 +71,8 @@ specfact spec generate contracts --help
 
 ## See also
 
-- [Command reference](../../reference/commands/) — bundle-to-command mapping
+- [Command reference](/reference/commands/) — bundle-to-command mapping
 - [Spec validate and backward compatibility](/bundles/spec/validate/)
 - [Generate Specmatic tests](/bundles/spec/generate-tests/)
 - [Run a mock server](/bundles/spec/mock/)
-- [Contract testing workflow](../../guides/contract-testing-workflow/)
+- [Contract testing workflow](/contract-testing-workflow/)

docs/modules/code-review.md

@@ -44,9 +44,10 @@ Options (aligned with `specfact code review run --help`):
   full toolchain and preserves `overall_verdict` in JSON, but forces
   `ci_exit_code` and the process exit code to `0` so CI or hooks can log signal
   without blocking
-- `--level error|warning`: drop findings below the chosen severity **before**
-  scoring and report construction so JSON, tables, score, verdict, and
-  `ci_exit_code` all match the filtered list. Omit to keep all severities
+- `--level error|warning`: filter findings **before** scoring so JSON, tables,
+  score, verdict, and `ci_exit_code` match the filtered list: **`error`**
+  keeps errors only (warnings and info dropped); **`warning`** keeps errors and
+  warnings (info dropped). Omit to keep all severities
 - `--bug-hunt`: enable the bug-hunt pass (CrossHair uses longer budgets: per-path
   timeout **10s**, subprocess budget **120s**; other tools keep normal speed)
 - `--include-noise` / `--suppress-noise`: include or suppress known low-signal
@@ -101,6 +102,11 @@ specfact code review run --scope full --path packages/specfact-code-review
 specfact code review run --scope changed --path packages/specfact-code-review --path tests/unit/specfact_code_review
 ```
 
+Copy-pastable recipes for **shadow mode**, **JSON `--out`**, **`--focus`**
+(`source` / `tests` / `docs` Python only), **noise flags**, and **interactive**
+test prompts live in the [Code review run](/bundles/code-review/run/) bundle
+guide (same Typer surface as this section).
+
 Positional `FILES...` cannot be mixed with **`--scope`** or **`--path`** (see
 **Invalid combinations** above).
 

openspec/changes/governance-04-deterministic-agent-governance-loading/tasks.md → openspec/changes/archive/2026-04-16-governance-04-deterministic-agent-governance-loading/tasks.md

@@ -7,7 +7,7 @@
 - [x] 1.3 In the worktree: `hatch env create` and `hatch run dev-deps` so `specfact` CLI is available for code-review dogfood tasks.
 - [x] 1.4 Pre-flight from worktree: `hatch run smart-test-status` and `hatch run contract-test-status` (or full quick sanity per AGENTS.md if those targets differ).
 - [x] 1.5 Run `openspec validate governance-04-deterministic-agent-governance-loading --strict` and capture output in `CHANGE_VALIDATION.md`; fix artifact issues until green.
-- [ ] 1.6 After PR merges: `git worktree remove`, `git branch -d`, `git worktree prune` for the feature branch; remove worktree-local `.venv` if unused.
+- [x] 1.6 After PR merges: `git worktree remove`, `git branch -d`, `git worktree prune` for the feature branch; remove worktree-local `.venv` if unused.
 
 ## 2. Spec-first and test-first preparation
 
@@ -28,12 +28,12 @@
 ## 4. Validation and documentation
 
 - [x] 4.1 Run quality gates from the worktree until green: `hatch run format`, `hatch run type-check`, `hatch run lint`, `hatch run yaml-lint`, `hatch run contract-test`, `hatch run smart-test`, `hatch run test` (add signature verify if any `module-package.yaml` / registry payload changes).
-- [ ] 4.2 **SpecFact code review JSON**: ensure `.specfact/code-review.json` exists and is fresh per `openspec/config.yaml` rules; remediate all findings or document a rare justified exception in the proposal; record commands and timestamp in `TDD_EVIDENCE.md`.
+- [x] 4.2 **SpecFact code review JSON**: ensure `.specfact/code-review.json` exists and is fresh per `openspec/config.yaml` rules; remediate all findings or document a rare justified exception in the proposal; record commands and timestamp in `TDD_EVIDENCE.md`.
 - [x] 4.3 If contributor-facing docs under `docs/` must mention the new layout (e.g. onboarding, nav, frontmatter schema), update them without breaking Jekyll front matter or `documentation-url-contract.md` permalinks.
 - [x] 4.4 Re-run `openspec validate governance-04-deterministic-agent-governance-loading --strict` and update `CHANGE_VALIDATION.md`.
 
 ## 5. Delivery
 
 - [x] 5.1 Refresh `TDD_EVIDENCE.md` with passing-after commands and timestamps.
-- [ ] 5.2 Open a PR from `feature/governance-04-deterministic-agent-governance-loading` to `dev` with summary linking modules issue, #163, #494, and #178.
-- [ ] 5.3 After merge, run `openspec archive governance-04-deterministic-agent-governance-loading` from repo root (no manual folder moves) and confirm **openspec/CHANGE_ORDER.md** reflects archived status.
+- [x] 5.2 Open a PR from `feature/governance-04-deterministic-agent-governance-loading` to `dev` with summary linking modules issue, #163, #494, and #178.
+- [x] 5.3 After merge, run `openspec archive governance-04-deterministic-agent-governance-loading` from repo root (no manual folder moves) and confirm **openspec/CHANGE_ORDER.md** reflects archived status.

openspec/changes/marketplace-06-ci-module-signing/tasks.md → openspec/changes/archive/2026-04-16-marketplace-06-ci-module-signing/tasks.md

@@ -5,7 +5,7 @@
 - [x] 1.1 Create `feature/marketplace-06-ci-module-signing` in a dedicated worktree from `origin/dev`;
   run pre-flight status checks.
 - [x] 1.2 ~~Create a GitHub User Story issue~~ Issue created: [specfact-cli-modules#185](https://github.com/nold-ai/specfact-cli-modules/issues/185); `proposal.md` Source Tracking updated. Paired core issue: [specfact-cli#500](https://github.com/nold-ai/specfact-cli/issues/500). *(done)*
-- [ ] 1.3 Confirm `SPECFACT_MODULE_PRIVATE_SIGN_KEY` and `SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE`
+- [x] 1.3 Confirm `SPECFACT_MODULE_PRIVATE_SIGN_KEY` and `SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE`
   are set as repository secrets in `specfact-cli-modules` (should already be present via
   publish-modules.yml). *(human)*
 
@@ -73,5 +73,5 @@
   require `--require-signature`). PR: [specfact-cli-modules#188](https://github.com/nold-ai/specfact-cli-modules/pull/188).
 - [x] 6.2 Link the PR to the GitHub issue created in 1.2 and to the paired specfact-cli PR.
   *(Closes #185 in PR body; link specfact-cli PR manually when it exists.)*
-- [ ] 6.3 After merge: remove the worktree, delete the local branch, run `git worktree prune`.
-- [ ] 6.4 Record cleanup completion in `TDD_EVIDENCE.md`.
+- [x] 6.3 After merge: remove the worktree, delete the local branch, run `git worktree prune`.
+- [x] 6.4 Record cleanup completion in `TDD_EVIDENCE.md`.

openspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.md

@@ -9,6 +9,7 @@
 ## OpenSpec
 
 - `openspec validate docs-15-code-review-validation-guardrails --strict` — passing.
+- 2026-04-16: Spec delta headers normalized (`## MODIFIED Requirements`, `### Requirement:`, `#### Scenario:`) under `openspec/changes/docs-15-code-review-validation-guardrails/specs/**/spec.md` so strict validation and future `openspec archive` succeed; `openspec validate docs-15-code-review-validation-guardrails --strict` — passing.
 
 ## Format / lint
 
@@ -17,3 +18,16 @@
 ## SpecFact code review
 
 - `hatch run specfact code review run --json --out .specfact/code-review.json --scope changed` — passing (2026-04-15); evidence at `.specfact/code-review.json`.
+
+## Code Review run guide examples (2026-04-16)
+
+- Expanded `docs/bundles/code-review/run.md` with worked examples (auto-scope, `--path`, shadow + `--json` + `--out`, `--focus`, positional files, `--level`, `--bug-hunt`, noise/interactive); clarified Python-only scope vs Markdown docs validation (`scripts/check-docs-commands.py`). Cross-links on bundle overview fixed to root-absolute routes. `docs/modules/code-review.md` points readers to the bundle guide for recipes.
+- `hatch run pytest tests/unit/docs/test_code_review_docs_parity.py …` and `python scripts/check-docs-commands.py` — passing.
+
+## Follow-up: bundle permalink vs. `..` links (2026-04-16)
+
+- `hatch run pytest tests/unit/scripts/test_docs_site_validation_link_agreement.py tests/unit/docs/test_docs_review.py::test_authored_internal_docs_links_resolve_to_published_docs_targets -q` — passing.
+- `python scripts/check-docs-commands.py` — passing (no findings).
+- `hatch run format`, `hatch run lint`, `hatch run type-check` — passing.
+- `hatch run contract-test` — passing (624 tests).
+- `hatch run specfact code review run --json --out /tmp/code-review-docs15.json scripts/docs_site_validation.py tests/unit/scripts/test_docs_site_validation_link_agreement.py` — **PASS** (`overall_verdict` PASS, `ci_exit_code` 0; report outside gitignored `.specfact/` for inspection).