release: merge dev into main (v0.36.1)

.gitignore

@@ -101,13 +101,13 @@ docs/internal/
 # Ignore specfact-cli prompt templates
 .cursor/commands/specfact.*.md
 .cursor/commands/opsx-*.md
-
 .cursor/skills/openspec-*/
 
 .github/prompts/specfact.*.md
 .github/prompts/opsx-*.md
 
 .claude/commands/opsx/
+.claude/commands/specfact.*.md
 .claude/skills/openspec-*/
 !.claude/skills/openspec-workflows/
 

CHANGELOG.md

@@ -8,6 +8,15 @@ 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.36.1] - 2026-02-23
+
+### Fixed
+
+- Installed runtime module discovery now includes `cwd/modules` when present, restoring command-surface parity (including `specfact backlog add`) between PyPI-installed and development runtimes when invoked from a repository checkout.
+- Added and auto-installed `resources/prompts/specfact.backlog-add.md` via IDE setup command templates (`specfact init ide`) for consistent backlog workflow slash prompts.
+
 ---
 
 ## [0.36.0] - 2026-02-21

openspec/CHANGE_ORDER.md

@@ -97,6 +97,7 @@ These are derived extensions of the same 2026-02-15 plan and are required to ope
 |--------|-------|---------------|----------|------------|
 | backlog-core | 01 | backlog-core-01-dependency-analysis-commands ✅ (implemented 2026-02-18; archived) | [#116](https://github.com/nold-ai/specfact-cli/issues/116) | — |
 | backlog-core | 02 | backlog-core-02-interactive-issue-creation (implemented 2026-02-22; archived) | [#173](https://github.com/nold-ai/specfact-cli/issues/173) | #116 (optional: #176, #177) |
+| backlog-core | 04 | backlog-core-04-installed-runtime-discovery-and-add-prompt | TBD | #173 |
 
 ### backlog-scrum
 

openspec/changes/archive/2026-02-23-backlog-core-04-installed-runtime-discovery-and-add-prompt/CHANGE_VALIDATION.md

@@ -0,0 +1,15 @@
+# Change Validation Report: backlog-core-04-installed-runtime-discovery-and-add-prompt
+
+## Validation Command
+
+- `openspec validate backlog-core-04-installed-runtime-discovery-and-add-prompt --strict`
+
+## Result
+
+- **Status**: Pass
+- **Output**: `Change 'backlog-core-04-installed-runtime-discovery-and-add-prompt' is valid`
+
+## Notes
+
+- OpenSpec telemetry flush reported network/DNS errors in this environment, but validation result completed successfully.
+- Validation re-run after implementation remained `Pass`.

openspec/changes/archive/2026-02-23-backlog-core-04-installed-runtime-discovery-and-add-prompt/TDD_EVIDENCE.md

@@ -0,0 +1,21 @@
+# TDD Evidence: backlog-core-04-installed-runtime-discovery-and-add-prompt
+
+## Pre-implementation failing run
+
+- **Timestamp**: 2026-02-23T09:25:01+01:00
+- **Command**:
+  - `hatch run pytest tests/unit/specfact_cli/registry/test_module_packages.py::test_get_modules_roots_includes_cwd_modules_when_present tests/unit/utils/test_ide_setup.py::test_specfact_commands_includes_backlog_add_prompt -q`
+- **Result**: Failed (expected)
+- **Failure summary**:
+  - `get_modules_roots()` did not include `cwd/modules`.
+  - `SPECFACT_COMMANDS` did not include `specfact.backlog-add`.
+
+## Post-implementation passing run
+
+- **Timestamp**: 2026-02-23T09:26:02+01:00
+- **Command**:
+  - `hatch run pytest tests/unit/specfact_cli/registry/test_module_packages.py::test_get_modules_roots_includes_cwd_modules_when_present tests/unit/utils/test_ide_setup.py::test_specfact_commands_includes_backlog_add_prompt -q`
+- **Result**: Pass
+- **Summary**:
+  - `get_modules_roots()` now includes `cwd/modules` when present.
+  - IDE setup command list includes `specfact.backlog-add`.

openspec/changes/archive/2026-02-23-backlog-core-04-installed-runtime-discovery-and-add-prompt/design.md

@@ -0,0 +1,31 @@
+# Design: Installed Runtime Discovery Parity and Backlog Add Prompt
+
+## Overview
+
+This change addresses two consistency gaps:
+
+1. Installed runtime (`pip`/PyPI) misses workspace modules such as `modules/backlog-core` in some invocation contexts, causing command-surface drift from development runtime.
+2. `backlog add` has no dedicated slash prompt while neighboring backlog workflows do.
+
+## Discovery strategy
+
+- Keep existing discovery order:
+  - packaged modules (`specfact_cli/modules`)
+  - optional roots from `SPECFACT_MODULES_ROOTS`
+- Add a safe fallback root:
+  - `Path.cwd() / "modules"` when the directory exists
+  - deduplicated by resolved path, preserving deterministic ordering
+- Goal: when users run installed `specfact` from repo root, workspace modules are discoverable without manual env overrides.
+
+## Prompt strategy
+
+- Add `resources/prompts/specfact.backlog-add.md` following current frontmatter + `$ARGUMENTS` pattern.
+- Include command purpose, required adapter context, core flags, and execution workflow.
+- Register command name in `SPECFACT_COMMANDS` so `specfact init ide` copies it into IDE-specific command folders.
+
+## Risks
+
+- Discovery fallback could include unintended `modules/` folder in unrelated directories.
+  - Mitigation: only add when directory exists; no behavior change when absent.
+- Prompt installation drift across IDE formats.
+  - Mitigation: reuse existing `SPECFACT_COMMANDS` + template processing path; cover with unit tests.

openspec/changes/archive/2026-02-23-backlog-core-04-installed-runtime-discovery-and-add-prompt/proposal.md

@@ -0,0 +1,31 @@
+# Change: Backlog Core — Installed Runtime Discovery Parity and Backlog Add Prompt
+
+## Why
+
+
+`specfact backlog add` and related backlog-core commands are available in development (`hatch run specfact`) but can be missing from PyPI-installed runtime command surfaces, even at the same version. This creates a production usability regression where documented commands are unavailable after upgrade.
+
+Additionally, `backlog add` currently lacks a dedicated slash-command prompt in `resources/prompts/`, resulting in inconsistent IDE workflow coverage compared to `backlog refine` and `backlog daily`.
+
+## What Changes
+
+
+- **MODIFY**: Module discovery root fallback logic so installed runtime can discover workspace-level `modules/` when invoked from a repo checkout, restoring parity with development command surfaces.
+- **MODIFY**: Add tests for installed-runtime discovery path behavior and command-surface parity assumptions.
+- **NEW**: Add `resources/prompts/specfact.backlog-add.md` slash prompt for the new `backlog add` workflow.
+- **MODIFY**: Extend IDE setup command list so the new backlog-add prompt is installed automatically into IDE command folders.
+- **MODIFY**: Add/update tests that verify IDE template installation includes backlog-add prompt.
+
+## Capabilities
+- **backlog-core** (extended): Installed runtime command-surface parity for workspace module discovery.
+- **backlog** (extended): Backlog add slash-command prompt parity with existing backlog prompt workflows.
+
+---
+
+## Source Tracking
+
+<!-- source_repo: nold-ai/specfact-cli -->
+- **GitHub Issue**: #295
+- **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/295>
+- **Last Synced Status**: proposed
+- **Sanitized**: false

openspec/changes/archive/2026-02-23-backlog-core-04-installed-runtime-discovery-and-add-prompt/specs/backlog-add-slash-prompt/spec.md

@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: Backlog Add Slash Prompt
+
+The system SHALL provide and install a slash prompt for `backlog add` consistent with other backlog workflows.
+
+#### Scenario: Prompt file exists for backlog add
+
+- **GIVEN** prompt templates in `resources/prompts/`
+- **WHEN** templates are validated or inspected
+- **THEN** `resources/prompts/specfact.backlog-add.md` exists
+- **AND** it includes frontmatter description and `$ARGUMENTS` input placeholder.
+
+#### Scenario: IDE setup installs backlog add prompt
+
+- **GIVEN** `specfact init ide` (or equivalent IDE setup path) copies SpecFact templates
+- **WHEN** template copying runs for an IDE target
+- **THEN** a `specfact.backlog-add` prompt file is created in the IDE-specific destination
+- **AND** installation behavior matches existing prompt commands.

openspec/changes/archive/2026-02-23-backlog-core-04-installed-runtime-discovery-and-add-prompt/specs/installed-runtime-module-discovery/spec.md

@@ -0,0 +1,20 @@
+## ADDED Requirements
+
+### Requirement: Module Discovery Roots
+
+The system SHALL discover module packages consistently between development and installed runtime contexts when invoked from a repository checkout.
+
+#### Scenario: Installed runtime discovers workspace modules from repo root
+
+- **GIVEN** `specfact` is installed from PyPI/site-packages
+- **AND** the current working directory contains `modules/` with valid module packages
+- **WHEN** module discovery runs
+- **THEN** discovery includes the current working directory `modules/` root
+- **AND** commands contributed by those modules are available without requiring `SPECFACT_MODULES_ROOTS`.
+
+#### Scenario: No cwd modules directory keeps existing behavior
+
+- **GIVEN** the current working directory does not contain a `modules/` directory
+- **WHEN** module discovery runs
+- **THEN** discovery roots remain limited to packaged modules and explicitly configured roots
+- **AND** no extra discovery errors are introduced.

openspec/changes/archive/2026-02-23-backlog-core-04-installed-runtime-discovery-and-add-prompt/tasks.md

@@ -0,0 +1,45 @@
+# Tasks: backlog-core-04-installed-runtime-discovery-and-add-prompt
+
+## TDD / SDD order (enforced)
+
+Per `openspec/config.yaml`, tests before code for behavior changes.
+
+1. Update spec deltas first.
+2. Add tests mapped to scenarios.
+3. Run tests and capture failing results in `TDD_EVIDENCE.md`.
+4. Implement production code.
+5. Re-run tests and quality checks; capture passing evidence in `TDD_EVIDENCE.md`.
+
+## 1. Branch and scope
+
+- [x] 1.1 Work on `bugfix/backlog-core-04-installed-runtime-discovery-and-add-prompt` (or active equivalent) before implementation changes.
+- [x] 1.2 Confirm scope is limited to runtime module discovery parity and backlog-add prompt installation parity.
+
+## 2. Specs first
+
+- [x] 2.1 Finalize `specs/installed-runtime-module-discovery/spec.md` scenarios for installed runtime discovery fallback.
+- [x] 2.2 Finalize `specs/backlog-add-slash-prompt/spec.md` scenarios for prompt file + IDE setup installation behavior.
+
+## 3. Tests first (must fail before implementation)
+
+- [x] 3.1 Add/extend unit tests in `tests/unit/specfact_cli/registry/test_module_packages.py` for installed-runtime fallback discovery behavior.
+- [x] 3.2 Add/extend unit tests in `tests/unit/utils/test_ide_setup.py` to require backlog-add prompt installation.
+- [x] 3.3 Run targeted tests and record failing results in `TDD_EVIDENCE.md`.
+
+## 4. Implementation
+
+- [x] 4.1 Update `src/specfact_cli/registry/module_packages.py` to include repo-local module root fallback for installed runtime (without requiring `SPECFACT_MODULES_ROOTS`).
+- [x] 4.2 Add `resources/prompts/specfact.backlog-add.md` with workflow guidance matching existing prompt style.
+- [x] 4.3 Update `src/specfact_cli/utils/ide_setup.py` (`SPECFACT_COMMANDS`) to include `specfact.backlog-add`.
+
+## 5. Validation and docs
+
+- [x] 5.1 Re-run targeted tests and record passing results in `TDD_EVIDENCE.md`.
+- [x] 5.2 Run quality gates for touched scope (`hatch run format`, targeted tests, and any required checks for modified files).
+- [x] 5.3 Update affected docs if command prompt references changed. (No docs updates required after review; prompt is bundled and auto-installed via IDE setup list.)
+- [x] 5.4 Run `openspec validate backlog-core-04-installed-runtime-discovery-and-add-prompt --strict` and update `CHANGE_VALIDATION.md`.
+
+## 6. Delivery
+
+- [x] 6.1 Update `openspec/CHANGE_ORDER.md` status and placement.
+- [x] 6.2 Prepare PR with clear runtime parity verification notes (installed vs hatch behavior).

openspec/specs/backlog-add-slash-prompt/spec.md

@@ -0,0 +1,23 @@
+# backlog-add-slash-prompt Specification
+
+## Purpose
+TBD - created by archiving change backlog-core-04-installed-runtime-discovery-and-add-prompt. Update Purpose after archive.
+## Requirements
+### Requirement: Backlog Add Slash Prompt
+
+The system SHALL provide and install a slash prompt for `backlog add` consistent with other backlog workflows.
+
+#### Scenario: Prompt file exists for backlog add
+
+- **GIVEN** prompt templates in `resources/prompts/`
+- **WHEN** templates are validated or inspected
+- **THEN** `resources/prompts/specfact.backlog-add.md` exists
+- **AND** it includes frontmatter description and `$ARGUMENTS` input placeholder.
+
+#### Scenario: IDE setup installs backlog add prompt
+
+- **GIVEN** `specfact init ide` (or equivalent IDE setup path) copies SpecFact templates
+- **WHEN** template copying runs for an IDE target
+- **THEN** a `specfact.backlog-add` prompt file is created in the IDE-specific destination
+- **AND** installation behavior matches existing prompt commands.
+

openspec/specs/installed-runtime-module-discovery/spec.md

@@ -0,0 +1,24 @@
+# installed-runtime-module-discovery Specification
+
+## Purpose
+TBD - created by archiving change backlog-core-04-installed-runtime-discovery-and-add-prompt. Update Purpose after archive.
+## Requirements
+### Requirement: Module Discovery Roots
+
+The system SHALL discover module packages consistently between development and installed runtime contexts when invoked from a repository checkout.
+
+#### Scenario: Installed runtime discovers workspace modules from repo root
+
+- **GIVEN** `specfact` is installed from PyPI/site-packages
+- **AND** the current working directory contains `modules/` with valid module packages
+- **WHEN** module discovery runs
+- **THEN** discovery includes the current working directory `modules/` root
+- **AND** commands contributed by those modules are available without requiring `SPECFACT_MODULES_ROOTS`.
+
+#### Scenario: No cwd modules directory keeps existing behavior
+
+- **GIVEN** the current working directory does not contain a `modules/` directory
+- **WHEN** module discovery runs
+- **THEN** discovery roots remain limited to packaged modules and explicitly configured roots
+- **AND** no extra discovery errors are introduced.
+

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.36.0"
+version = "0.36.1"
 description = "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases."
 readme = "README.md"
 requires-python = ">=3.11"

resources/prompts/specfact.backlog-add.md

@@ -0,0 +1,84 @@
+---
+description: "Create backlog items with guided interactive flow and hierarchy checks"
+---
+
+# SpecFact Backlog Add Command
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Create a new backlog item in GitHub or Azure DevOps using the `specfact backlog add` workflow. The command supports interactive prompts, parent hierarchy validation, DoR checks, and provider-specific fields.
+
+**When to use:** Adding new work items (epic/feature/story/task/bug) with consistent quality and parent-child structure.
+
+**Quick:** `/specfact.backlog-add --adapter github --project-id owner/repo --type story --title "..."`
+
+## Parameters
+
+### Required
+
+- `--adapter ADAPTER` - Backlog adapter (`github`, `ado`)
+- `--project-id PROJECT` - Project context
+  - GitHub: `owner/repo`
+  - ADO: `org/project`
+
+### Common options
+
+- `--type TYPE` - Backlog item type (provider/template specific)
+- `--title TITLE` - Item title
+- `--body BODY` - Item body/description
+- `--parent PARENT_ID` - Optional parent issue/work item id
+- `--non-interactive` - Disable prompt flow and require explicit inputs
+- `--check-dor` - Run Definition of Ready checks before create
+- `--template TEMPLATE` - Optional backlog template override
+- `--custom-config PATH` - Optional mapping/config override file
+
+### Adapter-specific options
+
+- GitHub:
+  - `--repo-owner OWNER`
+  - `--repo-name NAME`
+  - `--github-token TOKEN` (or `GITHUB_TOKEN`)
+- Azure DevOps:
+  - `--ado-org ORG`
+  - `--ado-project PROJECT`
+  - `--ado-token TOKEN` (or `AZURE_DEVOPS_TOKEN`)
+  - `--ado-base-url URL` (optional)
+
+## Workflow
+
+### Step 1: Execute command
+
+Run the CLI command with user arguments:
+
+```bash
+specfact backlog add [OPTIONS]
+```
+
+### Step 2: Interactive completion (if inputs are missing)
+
+- Prompt for missing required fields.
+- Prompt for optional quality fields (acceptance criteria, points, priority) when supported.
+- Validate parent selection and allowed hierarchy before create.
+
+### Step 3: Confirm and create
+
+- Show planned create payload summary.
+- Execute provider create operation.
+- Return created item id/key/url.
+
+## CLI Enforcement
+
+- Always execute `specfact backlog add` for creation.
+- Do not create provider issues/work items directly outside CLI unless user explicitly requests a manual path.
+
+## Context
+
+{ARGS}

setup.py

@@ -7,7 +7,7 @@
 if __name__ == "__main__":
     _setup = setup(
         name="specfact-cli",
-        version="0.36.0",
+        version="0.36.1",
         description=(
             "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with "
             "validation and contract enforcement for new projects and long-lived codebases."

src/__init__.py

@@ -3,4 +3,4 @@
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.36.0"
+__version__ = "0.36.1"

src/specfact_cli/__init__.py

@@ -8,6 +8,6 @@
 - Supporting agile ceremonies and team workflows
 """
 
-__version__ = "0.36.0"
+__version__ = "0.36.1"
 
 __all__ = ["__version__"]