nold-ai · djm81 · Feb 19, 2026 · Jan 27, 2026 · Jan 27, 2026 · Jan 27, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,42 @@ All notable changes to this project will be documented in this file.
 
 **Important:** Changes need to be documented below this block as this is the header section. Each section should be separated by a horizontal rule. Newer changelog entries need to be added on top of prior ones to keep the history chronological with most recent changes first.
 
+---
+## [0.34.1] - 2026-02-18
+
+### Fixed
+
+- `specfact backlog refine --auto-bundle` no longer persists bundle mapping history into bundle manifest files (for example `.specfact/bundle.yaml`); mapping history remains in dedicated mapping config state.
+- Bundle ID candidate derivation no longer falls back to the manifest filename stem (`bundle.yaml` -> `bundle`), preventing false rejection of valid explicit `bundle:<id>` tags.
+- OpenSpec change order/archive tracking was synchronized for Wave 1 closure (`verification-01-wave1-delta-closure`) and related archived status markers.
+
+---
+## [0.34.0] - 2026-02-18
+
+### Added
+
+- **Thorough codebase validation** (validation-01, [#163](https://github.com/nold-ai/specfact-cli/issues/163))
+  - `specfact repro --crosshair-per-path-timeout N` to run CrossHair with a higher per-path timeout (deep validation).
+  - Reference doc [Thorough Codebase Validation](docs/reference/thorough-codebase-validation.md) covering quick check (`specfact repro`), thorough contract-decorated (`hatch run contract-test-full`), sidecar for unmodified code, and dogfooding (repro + contract-test-full on specfact-cli).
+  - Unit test and TDD evidence for CrossHair per-path timeout passthrough.
+- **Init module discovery alignment** (backlog-core-01): `specfact init` now uses the same module discovery roots as command registration (`discover_all_package_metadata()`), so `--list-modules`, `--enable-module`, and `--disable-module` operate on all discovered modules including workspace-level ones (e.g. `modules/backlog-core/`). Closes [#116](https://github.com/nold-ai/specfact-cli/issues/116) scope for init-module-discovery-alignment.
+- **Patch mode module** (patch-mode-01, [#177](https://github.com/nold-ai/specfact-cli/issues/177)): `specfact patch apply <patchfile>` for local apply with preflight; `specfact patch apply --write --yes` for explicit upstream write orchestration and idempotency (`check_idempotent` / `mark_applied`).
+
+### Changed
+
+- `specfact init` module state and validation now build from `discover_all_package_metadata()` instead of `discover_package_metadata(get_modules_root())`, aligning enable/disable and list-modules with runtime command discovery.
+
+### Fixed
+
+- `specfact repro --crosshair-per-path-timeout 0` (or negative) now fails with a clear error instead of being silently ignored; CLI rejects non-positive CrossHair per-path timeout values.
+
+---
+## [Unreleased]
+
+### Added
+
+- None yet.
+
 ---
 
 ## [0.33.0] - 2026-02-17

diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -171,6 +171,7 @@ <h2 class="docs-sidebar-title">
               <ul>
                 <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>
                 <li><a href="{{ '/reference/authentication/' | relative_url }}">Authentication</a></li>
                 <li><a href="{{ '/architecture/' | relative_url }}">Architecture</a></li>
                 <li><a href="{{ '/modes/' | relative_url }}">Operational Modes</a></li>

diff --git a/docs/index.md b/docs/index.md
@@ -99,6 +99,7 @@ Why this matters:
 - **[Extending ProjectBundle](guides/extending-projectbundle.md)** - Add namespaced custom fields to Feature/ProjectBundle (arch-07)
 - **[Using Module Security and Extensions](guides/using-module-security-and-extensions.md)** - Use arch-06 (module security) and arch-07 (schema extensions) from CLI and as a module author
 - **[Sidecar Validation](guides/sidecar-validation.md)** 🆕 - Validate external codebases without modifying source
+- **[Thorough Codebase Validation](reference/thorough-codebase-validation.md)** - Quick check, contract-full, sidecar, dogfooding
 - **[UX Features](guides/ux-features.md)** - Progressive disclosure, context detection, intelligent suggestions
 - **[Use Cases](guides/use-cases.md)** - Real-world scenarios and workflows
 - **[IDE Integration](guides/ide-integration.md)** - Set up slash commands in your IDE

diff --git a/docs/reference/README.md b/docs/reference/README.md
@@ -11,6 +11,7 @@ Complete technical reference for SpecFact CLI.
 ## Available References
 
 - **[Commands](commands.md)** - Complete command reference with all options
+- **[Thorough Codebase Validation](thorough-codebase-validation.md)** - Quick check, contract-decorated, sidecar, and dogfooding
 - **[Command Syntax Policy](command-syntax-policy.md)** - Source-of-truth argument syntax conventions for docs
 - **[Authentication](authentication.md)** - Device code auth flows and token storage
 - **[Architecture](architecture.md)** - Technical design, module structure, and internals

diff --git a/docs/reference/commands.md b/docs/reference/commands.md
@@ -4098,6 +4098,39 @@ specfact backlog refine ado \
   --iteration "Project\\Release 1\\Sprint 1"
 ```
 
+#### `patch apply`
+
+Apply a unified diff patch locally with preflight validation, or run explicit upstream-write orchestration.
+
+```bash
+specfact patch apply <PATCH_FILE> [OPTIONS]
+```
+
+**Options:**
+
+- `--dry-run` - Validate patch applicability only; do not apply locally
+- `--write` - Run upstream write orchestration path (requires confirmation)
+- `--yes`, `-y` - Confirm `--write` operation explicitly
+
+**Behavior:**
+
+- Local mode (`specfact patch apply <file>`) runs preflight then applies the patch to local files.
+- `--write` never runs unless `--yes` is provided.
+- Repeated `--write --yes` invocations for the same patch are idempotent and skip duplicate writes.
+
+**Examples:**
+
+```bash
+# Apply patch locally after preflight
+specfact patch apply backlog.diff
+
+# Validate patch only
+specfact patch apply backlog.diff --dry-run
+
+# Run explicit upstream write orchestration
+specfact patch apply backlog.diff --write --yes
+```
+
 **Pre-built Templates:**
 
 - `user_story_v1` - User story format (As a / I want / So that / Acceptance Criteria)

diff --git a/docs/reference/thorough-codebase-validation.md b/docs/reference/thorough-codebase-validation.md
@@ -0,0 +1,104 @@
+---
+layout: default
+title: Thorough Codebase Validation
+permalink: /reference/thorough-codebase-validation/
+description: How to run in-depth validation (quick check, contract-decorated, sidecar, dogfooding).
+---
+
+# Thorough Codebase Validation
+
+This reference describes how to run thorough in-depth validation in different modes: quick check, contract-decorated codebases, sidecar for unmodified code, and dogfooding SpecFact CLI on itself.
+
+## Validation Modes
+
+| Mode | When to use | Primary command(s) |
+|------|-------------|---------------------|
+| **Quick check** | Fast local/CI gate (lint, type-check, CrossHair with default budget) | `specfact repro --repo <path>` |
+| **Thorough (contract-decorated)** | Repo already uses `@icontract` / `@beartype`; run full contract stack | `hatch run contract-test-full` |
+| **Sidecar (unmodified code)** | Third-party or legacy repo; no edits to target source | `specfact repro --repo <path> --sidecar --sidecar-bundle <bundle>` |
+| **Dogfooding** | Validate the specfact-cli repo with the same pipeline | `specfact repro --repo .` + `hatch run contract-test-full` (optional sidecar) |
+
+## 1. Quick check (`specfact repro`)
+
+Run the standard reproducibility suite (ruff, semgrep if config exists, basedpyright, CrossHair, optional pytest contracts/smoke):
+
+```bash
+specfact repro --repo .
+specfact repro --repo /path/to/external/repo --verbose
+```
+
+- **Time budget**: Default 120s; use `--budget N` (advanced) to change.
+- **Deep CrossHair**: To increase per-path timeout for CrossHair (e.g. for critical modules), use `--crosshair-per-path-timeout N` (seconds; N must be positive). Default behavior is unchanged when not set.
+
+```bash
+specfact repro --repo . --crosshair-per-path-timeout 60
+```
+
+Required env: none. Optional: `[tool.crosshair]` in `pyproject.toml` (e.g. from `specfact repro setup`).
+
+## 2. Thorough validation for contract-decorated codebases
+
+When your repo already has `@icontract` and `@beartype` on public APIs, use the full contract-test stack:
+
+```bash
+hatch run contract-test-full
+```
+
+This runs:
+
+- Runtime contract validation (`contract-test-contracts`)
+- CrossHair exploration (`contract-test-exploration`)
+- Scenario tests with contract references (`contract-test-scenarios`)
+
+Exploration timeout can be configured via `[tool.crosshair]` or env (e.g. `STANDARD_CROSSHAIR_TIMEOUT`). For deeper CrossHair analysis on critical paths, run CrossHair directly with a higher per-path timeout:
+
+```bash
+crosshair check --per_path_timeout=60 src/your_critical_module/
+```
+
+Document this as the recommended thorough path for contract-decorated code; CI can invoke `hatch run contract-test-full` for PR validation.
+
+## 3. Sidecar validation (unmodified code)
+
+For repositories you cannot or do not want to modify (no contract decorators added):
+
+```bash
+specfact repro --repo <path> --sidecar --sidecar-bundle <bundle-name>
+```
+
+- Main repro checks run first (lint, semgrep, type-check, CrossHair if available).
+- Then sidecar validation runs: unannotated detection, harness generation, CrossHair/Specmatic on generated harnesses. No files in the target repo are modified.
+- If CrossHair is not installed or the bundle is invalid, sidecar is skipped or partial with clear messaging; non-zero exit only for main check failures (sidecar can be advisory).
+
+See [Sidecar Validation Guide](/guides/sidecar-validation/) for setup and bundle configuration.
+
+## 4. Dogfooding (SpecFact CLI on itself)
+
+Maintainers can validate the specfact-cli repository with the same pipeline:
+
+1. **Repro + contract-test-full** (recommended minimum):
+
+   ```bash
+   specfact repro --repo .
+   hatch run contract-test-full
+   ```
+
+2. **Optional sidecar** (to cover unannotated code in specfact-cli):
+
+   ```bash
+   specfact repro --repo . --sidecar --sidecar-bundle <bundle-name>
+   ```
+
+Use the same commands in a CI job or release checklist so specfact-cli validates itself before release. No repo-specific code is required beyond existing repro and contract-test tooling.
+
+## Copy-paste summary
+
+| Goal | Commands |
+|------|----------|
+| Quick gate | `specfact repro --repo .` |
+| Deep CrossHair (repro) | `specfact repro --repo . --crosshair-per-path-timeout 60` |
+| Full contract stack | `hatch run contract-test-full` |
+| Unmodified repo | `specfact repro --repo <path> --sidecar --sidecar-bundle <name>` |
+| Dogfooding | `specfact repro --repo .` then `hatch run contract-test-full`; optionally add `--sidecar --sidecar-bundle <name>` to repro |
+
+Required env/config: optional `[tool.crosshair]` in `pyproject.toml`; for sidecar, a valid sidecar bundle and CrossHair installed when sidecar CrossHair is used.
diff --git a/modules/bundle-mapper/module-package.yaml b/modules/bundle-mapper/module-package.yaml
@@ -0,0 +1,22 @@
+name: bundle-mapper
+version: "0.1.0"
+commands: []
+pip_dependencies: []
+module_dependencies: []
+core_compatibility: ">=0.28.0,<1.0.0"
+tier: community
+schema_extensions:
+  project_bundle: {}
+  project_metadata:
+    bundle_mapper.mapping_rules:
+      type: "list | None"
+      description: "Persistent mapping rules from user confirmations"
+    bundle_mapper.history:
+      type: "dict | None"
+      description: "Auto-populated historical mappings (item_key -> bundle_id counts)"
+publisher:
+  name: nold-ai
+  url: https://github.com/nold-ai/specfact-cli-modules
+integrity:
+  checksum_algorithm: sha256
+dependencies: []
diff --git a/modules/bundle-mapper/src/bundle_mapper/__init__.py b/modules/bundle-mapper/src/bundle_mapper/__init__.py
@@ -0,0 +1,7 @@
+"""Bundle mapper module: confidence-based spec-to-bundle assignment with interactive review."""
+
+from bundle_mapper.mapper.engine import BundleMapper
+from bundle_mapper.models.bundle_mapping import BundleMapping
+
+
+__all__ = ["BundleMapper", "BundleMapping"]
diff --git a/modules/bundle-mapper/src/bundle_mapper/commands/__init__.py b/modules/bundle-mapper/src/bundle_mapper/commands/__init__.py
@@ -0,0 +1 @@
+"""Command hooks for backlog refine/import --auto-bundle (used when module is loaded)."""
diff --git a/modules/bundle-mapper/src/bundle_mapper/mapper/__init__.py b/modules/bundle-mapper/src/bundle_mapper/mapper/__init__.py
@@ -0,0 +1,7 @@
+"""Bundle mapper engine and history."""
+
+from bundle_mapper.mapper.engine import BundleMapper
+from bundle_mapper.mapper.history import save_user_confirmed_mapping
+
+
+__all__ = ["BundleMapper", "save_user_confirmed_mapping"]
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		"""Command hooks for backlog refine/import --auto-bundle (used when module is loaded)."""