nold-ai · djm81 · Feb 18, 2026 · Feb 18, 2026 · Feb 18, 2026 · Feb 18, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,7 @@ All notable changes to this project will be documented in this file.
   - 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
 
@@ -27,24 +28,11 @@ All notable changes to this project will be documented in this file.
 - `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
 
-- **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 upstream write with confirmation and idempotency. Pipeline: `generate_unified_diff`, `apply_patch_local`, `apply_patch_write`, `check_idempotent` / `mark_applied`.
-
----
-
-## [0.34.0] - 2026-02-18
-
-### Added
-
-- **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.
-
-### 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.
+- None yet.
 
 ---
 

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/openspec/changes/verification-01-wave1-delta-closure/CHANGE_VALIDATION.md b/openspec/changes/verification-01-wave1-delta-closure/CHANGE_VALIDATION.md
@@ -0,0 +1,63 @@
+# Change Validation: verification-01-wave1-delta-closure
+
+- **Validated on (UTC):** 2026-02-18T21:34:59Z
+- **Workflow:** /wf-validate-change (proposal-stage dry-run validation)
+- **Strict command:** `openspec validate verification-01-wave1-delta-closure --strict`
+- **Result:** PASS
+
+## Scope Summary
+
+- **Change type:** Delta verification closure for previously merged Wave 1 scope.
+- **Modified capabilities:** `bundle-mapping`, `patch-mode`, `cli-output`.
+- **Declared dependencies:** existing Wave 1 changes `#177`, `#163`, `#116`, `#121`.
+- **Primary targets:**
+  - `src/specfact_cli/modules/backlog/src/commands.py`
+  - `modules/bundle-mapper/src/bundle_mapper/*`
+  - `src/specfact_cli/modules/patch_mode/src/patch_mode/*`
+  - `docs/reference/commands.md`
+  - `docs/guides/backlog-refinement.md`
+  - `CHANGELOG.md`
+
+## Dependency and Integration Analysis (Dry-Run)
+
+### 1) bundle-mapper runtime integration
+
+- `--auto-bundle` is exposed in backlog refine command options, but runtime currently ends with a pending integration message instead of executing mapping hooks.
+- Evidence:
+  - option exists: `src/specfact_cli/modules/backlog/src/commands.py:2658`
+  - pending placeholder path: `src/specfact_cli/modules/backlog/src/commands.py:3600`
+  - hooks module is currently a stub docstring: `modules/bundle-mapper/src/bundle_mapper/commands/__init__.py:1`
+- Integration impact: refine/import orchestration, OpenSpec bundle assignment flow, mapping history persistence.
+
+### 2) patch-mode behavioral completion
+
+- CLI command surface is present and discoverable, but applier implementation currently behaves as a stub success path.
+- Evidence:
+  - command entrypoint exists: `src/specfact_cli/modules/patch_mode/src/patch_mode/commands/apply.py`
+  - local apply returns `True` after read/validation without patch execution: `src/specfact_cli/modules/patch_mode/src/patch_mode/pipeline/applier.py:14`
+  - write apply returns `True` after read/confirmation without provider write orchestration: `src/specfact_cli/modules/patch_mode/src/patch_mode/pipeline/applier.py:31`
+- Integration impact: patch pipeline trust model, adapter writeback orchestration, idempotency marker semantics.
+
+### 3) release docs/changelog parity
+
+- Documentation currently states auto-bundle behavior as operational while runtime is pending.
+- `CHANGELOG.md` has duplicate `0.34.0` sections and patch-mode details placed under `Unreleased`.
+- Evidence:
+  - docs claim auto-bundle import: `docs/reference/commands.md:3986`, `docs/guides/backlog-refinement.md:438`
+  - runtime pending message: `src/specfact_cli/modules/backlog/src/commands.py:3600`
+  - duplicate release headings: `CHANGELOG.md:11`, `CHANGELOG.md:39`
+
+## Breaking-Change Risk Assessment
+
+- **Proposal-stage only:** no production code modifications were performed during validation.
+- **Expected implementation risk:** medium.
+  - `bundle-mapper` completion changes refine/import behavior paths but should be additive when `--auto-bundle` is explicitly requested.
+  - `patch-mode` completion may alter command side-effects; confirmation/idempotency contracts must remain explicit to avoid accidental writes.
+  - docs/changelog updates are non-runtime but release-governance critical.
+- **Compatibility posture:** target behavior is extension/completion of existing command contracts; no mandatory public signature removals are proposed.
+
+## Strict Validation Outcome
+
+- Required artifacts present: `proposal.md`, `tasks.md`, and `specs/*/spec.md`.
+- Strict OpenSpec validation passed for `verification-01-wave1-delta-closure`.
+- Change is ready for implementation-phase intake after TDD-first execution.
diff --git a/openspec/changes/verification-01-wave1-delta-closure/TDD_EVIDENCE.md b/openspec/changes/verification-01-wave1-delta-closure/TDD_EVIDENCE.md
@@ -0,0 +1,27 @@
+# TDD Evidence - verification-01-wave1-delta-closure
+
+## Pre-Implementation Failing Run
+
+- Timestamp: 2026-02-18 23:00:00 UTC
+- Command:
+  - `hatch run pytest tests/unit/specfact_cli/modules/test_patch_mode.py tests/unit/commands/test_backlog_bundle_mapping_delta.py tests/unit/docs/test_release_docs_parity.py -q`
+- Result: **FAILED** (9 failed, 12 passed)
+
+### Failure Summary
+
+- Patch local apply is still a stub path:
+  - valid unified diff did not modify target file
+  - invalid patch returned success instead of failure
+- Patch write path did not fail for invalid patch orchestration preflight.
+- Backlog bundle-mapper runtime hooks were missing (`_route_bundle_mapping_decision`, `_apply_bundle_mappings_for_items`, dependency loader).
+- Changelog/docs parity issues remained:
+  - duplicate `0.34.0` headers in `CHANGELOG.md`
+  - patch-mode entry remained in `Unreleased`
+  - command reference lacked `specfact patch apply` documentation.
+
+## Post-Implementation Passing Run
+
+- Timestamp: 2026-02-18 23:06:00 UTC
+- Command:
+  - `hatch run pytest tests/unit/specfact_cli/modules/test_patch_mode.py tests/unit/commands/test_backlog_bundle_mapping_delta.py tests/unit/docs/test_release_docs_parity.py -q`
+- Result: **PASSED** (21 passed)
diff --git a/openspec/changes/verification-01-wave1-delta-closure/proposal.md b/openspec/changes/verification-01-wave1-delta-closure/proposal.md
@@ -0,0 +1,52 @@
+# Change: Wave 1 Delta Closure for Verification Gaps
+
+## Why
+
+Wave 1 changes were merged into `dev` for release `v0.34.0`, but post-merge verification identified implementation-to-spec and docs-to-reality gaps that affect trust and adoption:
+
+- `bundle-mapper-01` engine code exists, but `--auto-bundle` flow is not wired end-to-end in backlog refine/import runtime paths.
+- `patch-mode-01` command surface exists, but local/apply and upstream/write paths are still lightweight stubs rather than operational patch pipeline behavior.
+- release documentation is out of sync with runtime: duplicate `0.34.0` changelog entries and missing `specfact patch` reference coverage.
+
+This delta closes those gaps so shipped behavior, OpenSpec requirements, and user-facing documentation are aligned.
+
+## What Changes
+
+- **EXTEND** `bundle-mapper` integration so `--auto-bundle` activates real mapping flow in backlog refine/import paths (confidence routing, interactive fallback, persistence of learned mappings).
+- **EXTEND** `patch-mode` apply/write pipeline so `specfact patch apply <patchfile>` performs effective local patch application and `--write` performs explicit, confirmed upstream write orchestration with idempotency safeguards.
+- **EXTEND** documentation and changelog governance so command/reference docs and `CHANGELOG.md` reflect shipped command surfaces and release entries without duplication.
+- **EXTEND** verification evidence for this delta with strict OpenSpec validation and dependency impact analysis report.
+
+## Capabilities
+
+- **bundle-mapping**: Runtime hook completion for `--auto-bundle` in backlog refine/import with confidence-based routing and mapping persistence.
+- **patch-mode**: Operational local apply and explicit upstream write behavior (confirmed + idempotent) aligned with patch-mode acceptance scenarios.
+- **cli-output**: Release/changelog/documentation parity for shipped command surfaces (including patch command and corrected release sectioning).
+
+## Impact
+
+- **Affected specs**:
+  - `bundle-mapping` (modified)
+  - `patch-mode` (modified)
+  - `cli-output` (modified)
+- **Affected code**:
+  - `modules/bundle-mapper/src/bundle_mapper/*`
+  - `src/specfact_cli/modules/backlog/src/commands.py`
+  - `src/specfact_cli/modules/patch_mode/src/patch_mode/*`
+  - `docs/reference/commands.md`
+  - `docs/guides/backlog-refinement.md`
+  - `CHANGELOG.md`
+- **Integration points**:
+  - Backlog ceremony/refine/import flows
+  - Patch-mode command pipeline
+  - OpenSpec/doc release reporting and command reference parity
+
+---
+
+## Source Tracking
+
+<!-- source_repo: nold-ai/specfact-cli -->
+- **GitHub Issue**: #276
+- **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/276>
+- **Last Synced Status**: proposed
+- **Sanitized**: false
diff --git a/openspec/changes/verification-01-wave1-delta-closure/specs/bundle-mapping/spec.md b/openspec/changes/verification-01-wave1-delta-closure/specs/bundle-mapping/spec.md
@@ -0,0 +1,13 @@
+## MODIFIED Requirements
+
+### Requirement: Confidence-Based Routing
+
+The system SHALL route bundle mappings based on confidence thresholds: auto-assign (>=0.8), prompt user (0.5-0.8), require explicit selection (<0.5).
+
+#### Scenario: Refine/import `--auto-bundle` executes runtime mapping flow
+
+- **GIVEN** `bundle-mapper` module is installed and a user runs backlog refine/import with `--auto-bundle`
+- **WHEN** items are processed for OpenSpec bundle assignment
+- **THEN** `BundleMapper` confidence scoring is executed for each item
+- **AND** confidence routing behavior is enforced (auto/prompt/explicit selection) instead of placeholder or no-op import messaging
+- **AND** resulting mapping decision is persisted via configured mapping history/rules storage.
diff --git a/openspec/changes/verification-01-wave1-delta-closure/specs/cli-output/spec.md b/openspec/changes/verification-01-wave1-delta-closure/specs/cli-output/spec.md
@@ -0,0 +1,23 @@
+## MODIFIED Requirements
+
+### Requirement: Command Reference Completeness
+
+The system SHALL keep command reference documentation aligned with shipped CLI command surfaces for each release.
+
+#### Scenario: Shipped patch command documented in command reference
+
+- **GIVEN** `specfact patch` command group is available in release builds
+- **WHEN** command reference documentation is published for that release
+- **THEN** reference docs include `specfact patch apply` options and usage semantics
+- **AND** docs do not describe unavailable command variants as fully implemented behavior.
+
+### Requirement: Changelog Release Integrity
+
+The project SHALL maintain one canonical section per released version and accurate placement of released capabilities.
+
+#### Scenario: Release section has no duplicate version headers
+
+- **GIVEN** release `v0.34.0` is merged and published
+- **WHEN** maintainers review `CHANGELOG.md`
+- **THEN** there is a single `0.34.0` section
+- **AND** features shipped in that release are listed under that release (not left under `Unreleased`).
diff --git a/openspec/changes/verification-01-wave1-delta-closure/specs/patch-mode/spec.md b/openspec/changes/verification-01-wave1-delta-closure/specs/patch-mode/spec.md
@@ -0,0 +1,25 @@
+## MODIFIED Requirements
+
+### Requirement: Apply locally with preflight
+
+The system SHALL provide `specfact patch apply <patchfile>` that applies the patch locally with a preflight check; user confirmation or explicit flag required.
+
+#### Scenario: Local apply performs real patch operation
+
+- **GIVEN** a valid unified diff patch file
+- **WHEN** the user runs `specfact patch apply <patchfile>`
+- **THEN** preflight validation runs before apply
+- **AND** the patch is actually applied to local target files (not a stub success path)
+- **AND** command exits non-zero on patch apply failure.
+
+### Requirement: Write upstream with explicit confirmation
+
+The system SHALL provide `specfact patch apply --write` (or equivalent) that updates upstream (GitHub/ADO) only with explicit user confirmation; idempotent for posted comments/updates (no duplicates).
+
+#### Scenario: Write orchestration is explicit, confirmed, and idempotent
+
+- **GIVEN** upstream write mode is requested
+- **WHEN** the user runs `specfact patch apply <patchfile> --write --yes`
+- **THEN** upstream write path executes only after confirmation
+- **AND** repeated invocation with the same operation key does not create duplicate writes/comments
+- **AND** failures in write orchestration surface clear non-zero error outcomes.
diff --git a/openspec/changes/verification-01-wave1-delta-closure/tasks.md b/openspec/changes/verification-01-wave1-delta-closure/tasks.md
@@ -0,0 +1,34 @@
+## 1. Git Workflow and Scope Lock
+
+- [ ] 1.1 Create worktree branch `feature/verification-01-wave1-delta-closure` from `origin/dev` and run all implementation steps in that worktree.
+- [x] 1.2 Confirm this change only covers Wave 1 delta-closure gaps (bundle-mapper wiring, patch-mode behavior completion, docs/changelog parity).
+
+## 2. Spec and Validation Baseline
+
+- [x] 2.1 Validate OpenSpec change artifacts: `openspec validate verification-01-wave1-delta-closure --strict`.
+- [x] 2.2 Produce/update `openspec/changes/verification-01-wave1-delta-closure/CHANGE_VALIDATION.md` with dependency and breaking-change analysis.
+
+## 3. Tests First (TDD Hard Gate)
+
+- [x] 3.1 Add/extend tests for bundle-mapper runtime hook behavior in backlog refine/import (`--auto-bundle` confidence routing and user fallback behavior).
+- [x] 3.2 Add/extend tests for patch-mode local apply and upstream write orchestration (confirmation gate + idempotency behavior).
+- [x] 3.3 Add/extend docs/changelog parity tests or lint guards where applicable.
+- [x] 3.4 Run targeted tests and capture a failing pre-implementation run in `TDD_EVIDENCE.md`.
+
+## 4. Implement Delta Scope
+
+- [x] 4.1 Implement bundle-mapper hook wiring for backlog refine/import runtime paths.
+- [x] 4.2 Implement patch-mode local apply semantics and explicit upstream write path aligned with acceptance criteria.
+- [x] 4.3 Update docs and changelog to match actual shipped command behavior and remove duplicate release sections.
+
+## 5. Verify and Quality Gates
+
+- [x] 5.1 Re-run targeted tests and capture passing post-implementation evidence in `TDD_EVIDENCE.md`.
+- [ ] 5.2 Run quality gates in order: `hatch run format`, `hatch run type-check`, `hatch run lint`, `hatch run yaml-lint`, `hatch run contract-test`, `hatch run smart-test`.
+- [x] 5.3 Re-run `openspec validate verification-01-wave1-delta-closure --strict` and ensure no errors.
+
+## 6. Sync and Delivery
+
+- [ ] 6.1 Sync proposal updates to GitHub issue in `nold-ai/specfact-cli` and ensure required labels (`enhancement`, `openspec`, `change-proposal`).
+- [ ] 6.2 Update `openspec/CHANGE_ORDER.md` entry status/metadata for this change.
+- [ ] 6.3 Open PR to `dev` with validation evidence and test results.