release: merge dev into main (v0.36.1) (#296)

* perf: optimize startup performance with metadata tracking and update command (#142)

* feat: implement backlog field mapping and refinement improvements

- Add FieldMapper abstract base class with canonical field names
- Implement GitHubFieldMapper and AdoFieldMapper
- Add custom field mapping support with YAML templates
- Add field validation in refinement (story_points, business_value, priority)
- Add comprehensive unit and integration tests (42 tests)
- Add custom field mapping documentation
- Fix custom_field_mapping parameter connection
- Add early validation for custom mapping files

Implements OpenSpec change: improve-backlog-field-mapping-and-refinement

* perf: optimize startup performance with metadata tracking and update command

- Add metadata management module for tracking version and check timestamps
- Optimize startup checks to only run when needed:
  - Template checks: Only after version changes detected
  - Version checks: Limited to once per day (24h threshold)
- Add --skip-checks flag for CI/CD environments
- Add new 'specfact update' command for manual update checking and installation
- Add comprehensive unit and integration tests (35 tests, all passing)
- Update startup_checks to use metadata for conditional execution
- Ensure backward compatibility (first-time users still get all checks)

Performance Impact:
- Startup time: Reduced from several seconds to < 1-2 seconds
- Network requests: Reduced from every startup to once per day
- File system operations: Reduced from every startup to only after version changes

Fixes #140
Implements OpenSpec change: optimize-startup-performance

* feat: request offline_access scope for Azure DevOps refresh tokens

- Add offline_access scope to Azure DevOps OAuth requests
- Refresh tokens now last 90 days (vs 1 hour for access tokens)
- Automatic token refresh via persistent cache (no re-authentication needed)
- Update documentation to reflect 90-day refresh token lifetime

This addresses the issue where tokens were expiring too quickly.
Refresh tokens obtained via offline_access scope enable automatic
token renewal for 90 days without user interaction.

Fixes token lifetime limitation issue

* feat: improve CLI UX with banner control and upgrade command

- Change banner to hidden by default, shown on first run or with --banner flag
- Add simple version line (SpecFact CLI - vXYZ) for regular use
- Rename 'update' command to 'upgrade' to avoid confusion
- Update documentation for new banner behavior and upgrade command
- Update startup checks message to reference 'specfact upgrade'

* fix: suppress version line in test mode and fix field mapping issues

- Suppress version line output in test mode and for help/version commands to prevent test failures
- Fix ADO custom field mapping to honor --custom-field-mapping on writeback
- Fix GitHub issue body updates to prevent duplicate sections
- Ensure proper type handling for story points and business value calculations

* Fix failed tests

* chore: bump version to 0.26.7 and update changelog

- Fixed adapter token validation tests (ADO and GitHub)
- Resolved test timeout issues (commit history, AST parsing, Semgrep)
- Improved test file discovery to exclude virtual environments
- Added file size limits for AST parsing to prevent timeouts

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* fix: add missing ADO field mappings and assignee display (#145)

* fix: add missing ADO field mappings and assignee display

- Add Microsoft.VSTS.Common.AcceptanceCriteria to default field mappings
- Update AdoFieldMapper to support multiple field name alternatives
- Fix assignee extraction to include displayName, uniqueName, and mail
- Add assignee display in preview output
- Add interactive template mapping command (specfact backlog map-fields)
- Update specfact init to copy backlog field mapping templates
- Extend documentation with step-by-step guides

Fixes #144

* test: add unit tests for ADO field mapping and assignee fixes

- Add tests for Microsoft.VSTS.Common.AcceptanceCriteria field extraction
- Add tests for multiple field name alternatives
- Add tests for assignee extraction with displayName, uniqueName, mail
- Add tests for assignee filtering with multiple identifiers
- Add tests for assignee display in preview output
- Add tests for interactive mapping command
- Add tests for template copying in init command
- Update existing tests to match new assignee extraction behavior

* docs: update init command docstring to mention template copying

* docs: update documentation for ADO field mapping and interactive mapping features

- Update authentication guide with ADO token resolution priority
- Update custom field mapping guide with interactive mapping details
- Update backlog refinement guide with progress indicators and required field display
- Update Azure DevOps adapter guide with field mapping improvements
- Update command reference with map-fields command documentation
- Update troubleshooting guide with ADO-specific issues
- Update README files with new features
- Update getting started guide with template initialization

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: address review findings for ADO field mapping

- Prefer System.* fields over Microsoft.VSTS.Common.* when writing updates
  (fixes issue where PATCH requests could fail for Scrum templates)
- Preserve existing work_item_type_mappings when saving field mappings
  (prevents silent erasure of custom work item type mappings)

Fixes review comments:
- P1: Prefer System.AcceptanceCriteria when writing updates
- P2: Preserve existing work_item_type_mappings on save

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: mitigate code scanning vulnerabilities (#148)

* fix: mitigate code scanning vulnerabilities

- Fix ReDoS vulnerability in github_mapper.py by replacing regex with line-by-line processing
- Fix incomplete URL sanitization in github.py, bridge_sync.py, and ado.py using proper URL parsing
- Add explicit permissions blocks to 7 GitHub Actions jobs following least-privilege model

Resolves all 13 code scanning findings:
- 1 ReDoS error
- 5 URL sanitization warnings
- 7 missing workflow permissions warnings

Fixes #147

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: accept GitHub SSH host aliases in repo detection

Accept ssh.github.com (port 443) in addition to github.com when
detecting GitHub repositories via SSH remotes. This ensures
repositories using git@ssh.github.com:owner/repo.git are properly
detected as GitHub repos.

Addresses review feedback on PR #148

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: prevent async cleanup issues in test mode

Remove manual Live display cleanup that could cause EOFError.
The _safe_progress_display function already handles test mode
by skipping progress display, so direct save path is sufficient.

Fixes test_unlock_section failure with EOFError/ValueError.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: detect GitHub remotes using ssh:// and git:// URLs

Extend URL pattern matching to support ssh://git@github.com/owner/repo.git
and git://github.com/owner/repo.git formats in addition to existing
https?:// and scp-style git@host:path URLs.

This fixes a regression where these valid GitHub URL formats were not
detected, causing detect() to return false for repos using these schemes.

Addresses review feedback on PR #149

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: bump version to 0.26.9 and update changelog

- Update version from 0.26.8 to 0.26.9
- Add changelog entry for GitHub remote detection fix and code scanning fixes

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: compare GitHub SSH hostnames case-insensitively

Lowercase host_part before comparison to handle mixed-case hostnames
like git@GitHub.com:org/repo.git. This restores the case-insensitive
behavior from the previous config_content.lower() check and prevents
regression where valid GitHub repos with mixed-case hostnames would
not be detected.

Addresses review feedback on PR #150

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add openspec and workflow commands for transparency

* Add specs from openspec

* Remove aisp change which wasn't implemented

* Fix openspec gitignore pattern

* Update gitignore

* Update contribution standards to use openspec for SDD

* Migrate to new opsx openspec commands

* Migrate workflow and openspec config

* fix: bump version to 0.26.10 for PyPI publish

- Sync version across pyproject.toml, setup.py, src/__init__.py, src/specfact_cli/__init__.py
- Add CHANGELOG entry for 0.26.10 (fixes incorrect version publish issue)

Co-authored-by: Cursor <cursoragent@cursor.com>

* Update version and changelog

* Add canonical user-friendly workitem url for ado workitems

* Update to support OSPX

* feat(backlog): implement refine --import-from-tmp and fix type-check (#156)

* feat(backlog): implement --import-from-tmp for refine export/import round-trip

- Add _parse_refined_export_markdown() to parse export-format markdown (ID, Body, Acceptance Criteria, optional title/metrics)
- Import branch: read file, match by ID, update items; --write calls adapter.update_backlog_item()
- Remove 'Import functionality pending implementation' message
- Unit tests for parser (single item, AC/metrics, header-only, blocks without ID)
- Bump version to 0.26.11 and sync across pyproject.toml, setup.py, src/__init__.py, src/specfact_cli/__init__.py
- OpenSpec change: implement-backlog-refine-import-from-tmp (proposal, tasks, spec delta)

Fixes #155

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix type check issues

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: debug logs under ~/.specfact/logs and release 0.26.13 (#159)

* feat: add debug logs under ~/.specfact/logs with operation metadata

- User-level log dir: get_specfact_home_logs_dir() (~/.specfact/logs, 0o755)
- debug_print() routes to console and rotating specfact-debug.log when --debug
- debug_log_operation() for structured metadata (ADO, GitHub, backlog, init)
- CLI init_debug_log_file() when --debug; help text updated

Closes #158
OpenSpec change: add-debug-logs-specfact-home

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add debug logging for selected commands at first

* release: 0.26.13 - debug log parity for upgrade, versions and changelog

- Log upgrade success (up to date) to ~/.specfact/logs/specfact-debug.log
- Bump version to 0.26.13; sync pyproject.toml, setup.py, src/__init__.py, specfact_cli/__init__.py
- CHANGELOG: 0.26.13 Fixed entry for upgrade debug parity

Co-authored-by: Cursor <cursoragent@cursor.com>

* Remove pr markdown

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* Potential fix for pull request finding 'Empty except'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>

* Fix unused variable review

* Fix unused variable review

* Fix type and test errors

* Finalize change

* Change for debug logs archived

* fix: improve ADO backlog refine error logging and user-facing error UX (#164)

* Improving error logging capabilities

* small fix on changelog

* Archived change

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* feat: backlog refine --ignore-refined and --id, startup docs (fixes #166) (#167)

* feat: backlog refine --ignore-refined and --id, startup docs (fixes #166)

OpenSpec change: improve-backlog-refine-and-cli-startup. Adds --ignore-refined/--no-ignore-refined, --id <issue-id>; helper _item_needs_refinement; interactive refinement prompt section; version 0.26.15.

* Add change for this branch and improve change create workflow

* Improve refinement prompt and add specification feedback, update docs and add backlog refinement tutorial

* Fix spec update and tasks

* Improve pr orchestrator pipeline triggers

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* Add change proposals for full scrum support

* Add support for systematic, structured issue creation with copilot help

* feat(backlog): daily standup defaults, iteration/sprint, unassigned items view (#174)

* Issue 179 resolution (#180)

* fix(backlog): address CodeQL/Codex PR 181 findings

- Replace empty except with debug_log_operation in _load_standup_config and _load_backlog_config (correct signature: operation, target, status, error)
- Add dim console message in sprint end date parse except block
- Gate summarize prompt description/comments on --comments; add include_comments to _build_summarize_prompt_content and call site
- Add test for metadata-only summarize when include_comments=False; update existing test to pass include_comments=True

Co-authored-by: Cursor <cursoragent@cursor.com>

* Update openspec enforcement rules

* Structure openspec changes

* Fix ruff finding

* Fix linter issues with StrEnum and parameters

* Fix tests and depcreation warnings

* Improve sync script

* Add change for modular command registry

* Fix review finding on dev sync script

* Update modular change proposal

* feat: CLI modular command registry and lazy load (arch-01) (#196)

* feat: CLI modular command registry and lazy load (arch-01)

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add missing exports

* Fix lazy loading review findigns

* Removed example package and fixed tests

* Fix test failures and lazy load logic for modules

* Fix tests

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* docs: document CLI modules design; sync version and cleanup

- Add Modules design section to architecture (registry, module packages, state)
- Update module structure tree with registry/ and modules/
- Cross-reference directory-structure to architecture#modules-design
- Changelog, version, and project file updates; remove obsolete commands/prompts

Co-authored-by: Cursor <cursoragent@cursor.com>

* Archive modular change and specs

* Fix banner display on help screen

* Improve action runner on main

* Setup claude skills and instructions

* feat: module package separation for command implementations (#200)

* feat: separate module package command implementations

* docs: finalize openspec apply checklist for arch-02

* Archived arch-02 change and updated specs

* fix: restore plan sync shared compatibility import

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* fix: address CodeQL and Codex review findings from PR #201

- Fix unreachable code in contract init (Prompt.ask after raise typer.Exit)
- Replace empty except with print_warning for contract file load failures
- Fix repo-root fallback path depth in backlog commands after module migration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: module lifecycle management, init split, and interactive module UX (#204)

* Release v0.28.0: Module package separation for command implementations (#201)

* perf: optimize startup performance with metadata tracking and update command (#142)

* feat: implement backlog field mapping and refinement improvements

- Add FieldMapper abstract base class with canonical field names
- Implement GitHubFieldMapper and AdoFieldMapper
- Add custom field mapping support with YAML templates
- Add field validation in refinement (story_points, business_value, priority)
- Add comprehensive unit and integration tests (42 tests)
- Add custom field mapping documentation
- Fix custom_field_mapping parameter connection
- Add early validation for custom mapping files

Implements OpenSpec change: improve-backlog-field-mapping-and-refinement

* perf: optimize startup performance with metadata tracking and update command

- Add metadata management module for tracking version and check timestamps
- Optimize startup checks to only run when needed:
  - Template checks: Only after version changes detected
  - Version checks: Limited to once per day (24h threshold)
- Add --skip-checks flag for CI/CD environments
- Add new 'specfact update' command for manual update checking and installation
- Add comprehensive unit and integration tests (35 tests, all passing)
- Update startup_checks to use metadata for conditional execution
- Ensure backward compatibility (first-time users still get all checks)

Performance Impact:
- Startup time: Reduced from several seconds to < 1-2 seconds
- Network requests: Reduced from every startup to once per day
- File system operations: Reduced from every startup to only after version changes

Fixes #140
Implements OpenSpec change: optimize-startup-performance

* feat: request offline_access scope for Azure DevOps refresh tokens

- Add offline_access scope to Azure DevOps OAuth requests
- Refresh tokens now last 90 days (vs 1 hour for access tokens)
- Automatic token refresh via persistent cache (no re-authentication needed)
- Update documentation to reflect 90-day refresh token lifetime

This addresses the issue where tokens were expiring too quickly.
Refresh tokens obtained via offline_access scope enable automatic
token renewal for 90 days without user interaction.

Fixes token lifetime limitation issue

* feat: improve CLI UX with banner control and upgrade command

- Change banner to hidden by default, shown on first run or with --banner flag
- Add simple version line (SpecFact CLI - vXYZ) for regular use
- Rename 'update' command to 'upgrade' to avoid confusion
- Update documentation for new banner behavior and upgrade command
- Update startup checks message to reference 'specfact upgrade'

* fix: suppress version line in test mode and fix field mapping issues

- Suppress version line output in test mode and for help/version commands to prevent test failures
- Fix ADO custom field mapping to honor --custom-field-mapping on writeback
- Fix GitHub issue body updates to prevent duplicate sections
- Ensure proper type handling for story points and business value calculations

* Fix failed tests

* chore: bump version to 0.26.7 and update changelog

- Fixed adapter token validation tests (ADO and GitHub)
- Resolved test timeout issues (commit history, AST parsing, Semgrep)
- Improved test file discovery to exclude virtual environments
- Added file size limits for AST parsing to prevent timeouts

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* fix: add missing ADO field mappings and assignee display (#145)

* fix: add missing ADO field mappings and assignee display

- Add Microsoft.VSTS.Common.AcceptanceCriteria to default field mappings
- Update AdoFieldMapper to support multiple field name alternatives
- Fix assignee extraction to include displayName, uniqueName, and mail
- Add assignee display in preview output
- Add interactive template mapping command (specfact backlog map-fields)
- Update specfact init to copy backlog field mapping templates
- Extend documentation with step-by-step guides

Fixes #144

* test: add unit tests for ADO field mapping and assignee fixes

- Add tests for Microsoft.VSTS.Common.AcceptanceCriteria field extraction
- Add tests for multiple field name alternatives
- Add tests for assignee extraction with displayName, uniqueName, mail
- Add tests for assignee filtering with multiple identifiers
- Add tests for assignee display in preview output
- Add tests for interactive mapping command
- Add tests for template copying in init command
- Update existing tests to match new assignee extraction behavior

* docs: update init command docstring to mention template copying

* docs: update documentation for ADO field mapping and interactive mapping features

- Update authentication guide with ADO token resolution priority
- Update custom field mapping guide with interactive mapping details
- Update backlog refinement guide with progress indicators and required field display
- Update Azure DevOps adapter guide with field mapping improvements
- Update command reference with map-fields command documentation
- Update troubleshooting guide with ADO-specific issues
- Update README files with new features
- Update getting started guide with template initialization

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: address review findings for ADO field mapping

- Prefer System.* fields over Microsoft.VSTS.Common.* when writing updates
  (fixes issue where PATCH requests could fail for Scrum templates)
- Preserve existing work_item_type_mappings when saving field mappings
  (prevents silent erasure of custom work item type mappings)

Fixes review comments:
- P1: Prefer System.AcceptanceCriteria when writing updates
- P2: Preserve existing work_item_type_mappings on save

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: mitigate code scanning vulnerabilities (#148)

* fix: mitigate code scanning vulnerabilities

- Fix ReDoS vulnerability in github_mapper.py by replacing regex with line-by-line processing
- Fix incomplete URL sanitization in github.py, bridge_sync.py, and ado.py using proper URL parsing
- Add explicit permissions blocks to 7 GitHub Actions jobs following least-privilege model

Resolves all 13 code scanning findings:
- 1 ReDoS error
- 5 URL sanitization warnings
- 7 missing workflow permissions warnings

Fixes #147

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: accept GitHub SSH host aliases in repo detection

Accept ssh.github.com (port 443) in addition to github.com when
detecting GitHub repositories via SSH remotes. This ensures
repositories using git@ssh.github.com:owner/repo.git are properly
detected as GitHub repos.

Addresses review feedback on PR #148

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: prevent async cleanup issues in test mode

Remove manual Live display cleanup that could cause EOFError.
The _safe_progress_display function already handles test mode
by skipping progress display, so direct save path is sufficient.

Fixes test_unlock_section failure with EOFError/ValueError.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: detect GitHub remotes using ssh:// and git:// URLs

Extend URL pattern matching to support ssh://git@github.com/owner/repo.git
and git://github.com/owner/repo.git formats in addition to existing
https?:// and scp-style git@host:path URLs.

This fixes a regression where these valid GitHub URL formats were not
detected, causing detect() to return false for repos using these schemes.

Addresses review feedback on PR #149

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: bump version to 0.26.9 and update changelog

- Update version from 0.26.8 to 0.26.9
- Add changelog entry for GitHub remote detection fix and code scanning fixes

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: compare GitHub SSH hostnames case-insensitively

Lowercase host_part before comparison to handle mixed-case hostnames
like git@GitHub.com:org/repo.git. This restores the case-insensitive
behavior from the previous config_content.lower() check and prevents
regression where valid GitHub repos with mixed-case hostnames would
not be detected.

Addresses review feedback on PR #150

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add openspec and workflow commands for transparency

* Add specs from openspec

* Remove aisp change which wasn't implemented

* Fix openspec gitignore pattern

* Update gitignore

* Update contribution standards to use openspec for SDD

* Migrate to new opsx openspec commands

* Migrate workflow and openspec config

* fix: bump version to 0.26.10 for PyPI publish

- Sync version across pyproject.toml, setup.py, src/__init__.py, src/specfact_cli/__init__.py
- Add CHANGELOG entry for 0.26.10 (fixes incorrect version publish issue)

Co-authored-by: Cursor <cursoragent@cursor.com>

* Update version and changelog

* Add canonical user-friendly workitem url for ado workitems

* Update to support OSPX

* feat(backlog): implement refine --import-from-tmp and fix type-check (#156)

* feat(backlog): implement --import-from-tmp for refine export/import round-trip

- Add _parse_refined_export_markdown() to parse export-format markdown (ID, Body, Acceptance Criteria, optional title/metrics)
- Import branch: read file, match by ID, update items; --write calls adapter.update_backlog_item()
- Remove 'Import functionality pending implementation' message
- Unit tests for parser (single item, AC/metrics, header-only, blocks without ID)
- Bump version to 0.26.11 and sync across pyproject.toml, setup.py, src/__init__.py, src/specfact_cli/__init__.py
- OpenSpec change: implement-backlog-refine-import-from-tmp (proposal, tasks, spec delta)

Fixes #155

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix type check issues

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: debug logs under ~/.specfact/logs and release 0.26.13 (#159)

* feat: add debug logs under ~/.specfact/logs with operation metadata

- User-level log dir: get_specfact_home_logs_dir() (~/.specfact/logs, 0o755)
- debug_print() routes to console and rotating specfact-debug.log when --debug
- debug_log_operation() for structured metadata (ADO, GitHub, backlog, init)
- CLI init_debug_log_file() when --debug; help text updated

Closes #158
OpenSpec change: add-debug-logs-specfact-home

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add debug logging for selected commands at first

* release: 0.26.13 - debug log parity for upgrade, versions and changelog

- Log upgrade success (up to date) to ~/.specfact/logs/specfact-debug.log
- Bump version to 0.26.13; sync pyproject.toml, setup.py, src/__init__.py, specfact_cli/__init__.py
- CHANGELOG: 0.26.13 Fixed entry for upgrade debug parity

Co-authored-by: Cursor <cursoragent@cursor.com>

* Remove pr markdown

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* Potential fix for pull request finding 'Empty except'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>

* Fix unused variable review

* Fix unused variable review

* Fix type and test errors

* Finalize change

* Change for debug logs archived

* fix: improve ADO backlog refine error logging and user-facing error UX (#164)

* Improving error logging capabilities

* small fix on changelog

* Archived change

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* feat: backlog refine --ignore-refined and --id, startup docs (fixes #166) (#167)

* feat: backlog refine --ignore-refined and --id, startup docs (fixes #166)

OpenSpec change: improve-backlog-refine-and-cli-startup. Adds --ignore-refined/--no-ignore-refined, --id <issue-id>; helper _item_needs_refinement; interactive refinement prompt section; version 0.26.15.

* Add change for this branch and improve change create workflow

* Improve refinement prompt and add specification feedback, update docs and add backlog refinement tutorial

* Fix spec update and tasks

* Improve pr orchestrator pipeline triggers

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* Add change proposals for full scrum support

* Add support for systematic, structured issue creation with copilot help

* feat(backlog): daily standup defaults, iteration/sprint, unassigned items view (#174)

* Issue 179 resolution (#180)

* fix(backlog): address CodeQL/Codex PR 181 findings

- Replace empty except with debug_log_operation in _load_standup_config and _load_backlog_config (correct signature: operation, target, status, error)
- Add dim console message in sprint end date parse except block
- Gate summarize prompt description/comments on --comments; add include_comments to _build_summarize_prompt_content and call site
- Add test for metadata-only summarize when include_comments=False; update existing test to pass include_comments=True

Co-authored-by: Cursor <cursoragent@cursor.com>

* Update openspec enforcement rules

* Structure openspec changes

* Fix ruff finding

* Fix linter issues with StrEnum and parameters

* Fix tests and depcreation warnings

* Improve sync script

* Add change for modular command registry

* Fix review finding on dev sync script

* Update modular change proposal

* feat: CLI modular command registry and lazy load (arch-01) (#196)

* feat: CLI modular command registry and lazy load (arch-01)

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add missing exports

* Fix lazy loading review findigns

* Removed example package and fixed tests

* Fix test failures and lazy load logic for modules

* Fix tests

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* docs: document CLI modules design; sync version and cleanup

- Add Modules design section to architecture (registry, module packages, state)
- Update module structure tree with registry/ and modules/
- Cross-reference directory-structure to architecture#modules-design
- Changelog, version, and project file updates; remove obsolete commands/prompts

Co-authored-by: Cursor <cursoragent@cursor.com>

* Archive modular change and specs

* Fix banner display on help screen

* Improve action runner on main

* Setup claude skills and instructions

* feat: module package separation for command implementations (#200)

* feat: separate module package command implementations

* docs: finalize openspec apply checklist for arch-02

* Archived arch-02 change and updated specs

* fix: restore plan sync shared compatibility import

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* fix: address CodeQL and Codex review findings from PR #201

- Fix unreachable code in contract init (Prompt.ask after raise typer.Exit)
- Replace empty except with print_warning for contract file load failures
- Fix repo-root fallback path depth in backlog commands after module migration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add module lifecycle management and split init ide setup

* docs: update arch-03 tasks after pr creation

* docs: update init help text for module lifecycle and ide split

* Format missing

* fix: tighten ado assignee typing for basedpyright warning

* fix: honor init install-deps and tighten ado typing

* test: satisfy bundle converter constructor typing

* test: isolate module registry state in migration compatibility test

* Update change

* disable claude review due to high costs

---------

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

* archived change for module improvements

* fix: address review feedback in init and boundary tests

* Fix test setup for tmpfiles

* docs: add openspec change arch-05 bridge registry (#210)

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* docs: add openspec change arch-06 manifest security (#211)

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* feat: Core Contracts and Module Interface Formalization (#209)

* feat: add ModuleIOContract protocol and core-module isolation

- Create ModuleIOContract protocol with four core operations

- Add static analysis enforcement preventing core->module imports

- Add ProjectBundle schema versioning (schema_version field)

- Update 5 modules to implement ModuleIOContract

- Add protocol compliance tracking in module discovery

- Create docs for ProjectBundle schema and module contracts

- Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* chore: update arch-04 task tracking after implementation and PR

* test: fix flaky help assertions and typing warnings

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* Update specs and archive arch-04 change

* Fix changelog format

* docs: align arch-05 scope with protocol migration cleanup (#212)

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* docs: add OpenSpec changes for module marketplace phases

Add three OpenSpec changes from Module Marketplace Decoupling Plan:
- arch-07-schema-extension-system: Schema extension mechanism for ProjectBundle
- marketplace-01-central-module-registry: Central registry MVP with module discovery
- marketplace-02-advanced-marketplace-features: Dependency resolution and custom registries

All changes include:
- Proposal, design, specs, tasks, and validation artifacts
- Source tracking linked to GitHub issues #213, #214, #215
- TDD/SDD ordering with contract-first development
- Backward compatibility guarantees

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* feat: apply arch-05 bridge registry implementation (#216)

* docs: add openspec change arch-05 bridge registry

* feat: apply arch-05 bridge registry workflow

* docs: update arch-05 apply task execution state

* fix: resolve arch-05 protocol reporting and duplicate lifecycle logs

* fix: close arch-05 review gaps for protocol reporting

* docs: mark arch-05 PR task complete

* fix: complete arch-05 module io contract migration

* fix: make module protocol startup reporting user-friendly

* fix: make debug logging work for eager cli flags

* fix: print active debug log path on debug startup

* fix: harden repro output and telemetry fallback behavior

* test: fix service bridge metadata typing in unit tests

* fix: add strict crosshair mode and clearer repro diagnostics

* fix: remove contracts import side-effects for crosshair

* fix: make crosshair exploration output specific and deduplicated

* fix: make crosshair exploration skip noisy signature-limited files

* ci: reduce specfact workflow env setup overhead

* ci: avoid hatch env sync in specfact validation workflow

* fix: stabilize crosshair exploration for side-effectful modules

* fix: improve crosshair compatibility for backlog converters

* ci: require crosshair in specfact repro workflows

* Apply fixes on crosshair tests

* ci: speed up workflow setup with cache and lean hatch installs

* ci: pin contract scenario test env to py3.12

* ci: improve contract test progress logging

* ci: increase and expose smart test timeout for scenario runs

* Fix test failure logic

* Fix test failure logic

* Reformat files

* Fix contract test findings

* Update docs integrity

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* Archive arch-05 change after implementation

* fix: address post-merge review findings and restore lazy registration

* fix: refresh project console per invocation in tests

* fix: detect runtime interface protocol ops in source scan

* fix: harden project console refresh and protocol source scan

* fix: refresh import command console for each invocation

* fix: resolve type-check errors and harden protocol scanning

* fix: stabilize module protocol scan and project console lifecycle

* Refine pending changes for new modular ecosystem and marketplace integration

* fix: update stale spec-delta paths in tasks.md after change renames

Corrects three broken spec-delta references flagged in PR #221 review:
- backlog-core-02: add-backlog-add-interactive-issue-creation → backlog-core-02-interactive-issue-creation
- backlog-scrum-02: sprint-planning-capacity-commitment-support → backlog-scrum-02-sprint-planning
- backlog-scrum-03: story-complexity-splitting-hints-support → backlog-scrum-03-story-complexity

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* docs: rewrite CHANGE_ORDER.md for module-scoped changes and full dependency graph

- Replace old flat backlog-01..09 naming with module-scoped groups:
  backlog-core, backlog-scrum, backlog-kanban, backlog-safe,
  policy-engine, patch-mode, bundle-mapper, ceremony-cockpit
- Add arch-06/07 and marketplace-01/02 as pending changes
- Mark arch-01 through arch-05 as implemented (archived 2026-02-04..10)
- Update all GitHub issue numbers to current (incl. new #208, #213, #214,
  #215, #220 from recent changes)
- Clarify hard vs optional dependencies; optional deps are graceful no-ops
  and not set as GitHub blockers
- Update implementation waves to reflect current unblocked state (Wave 0 done)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* feat(backlog): daily/refine comment context, interactive standup posting, and filter parity (#222)

* feat(backlog): finalize daily/refine comment context, interactive posting, and docs parity

* docs(openspec): mark backlog-scrum-01 standup change checklist complete

* fix(openspec): mark backlog-refinement delta as ADDED for archive apply

* Archived completed change backlog-scrum-01

* fix(backlog): make map-fields exit cleanly under CliRunner

* Fix format

* fix(backlog): stabilize map-fields tests in non-interactive env

* docs(agents): enforce signed-commit handoff flow

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* fix(backlog): satisfy interactive daily adapter typing

* fix(backlog): bypass default daily limit for issue-window flags

* fix: parse backlog refine writeback fields and refactor refine command (#224)

* fix: parse backlog refine writeback fields and refactor refine command

* fix: preserve heading-style narrative sections in refine parser

* chore: sync OpenSpec change to GitHub issue tracking

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* fix: avoid raw label fallback when description block is missing

* fix: harden backlog refine prompt scaffold and mixed-format parsing (#228)

* fix: harden backlog refine prompt scaffold and parsing

* fix: normalize mixed notes parsing and boundary flushing

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* Finish change

* chore: bump version to 0.30.4 and update changelog

* Add MEMORY.md for claude code

* Archive backlog writeback field split change

* Archived flask support sidecar change

* feat: add backlog-core module — dependency analysis and command suites (#231)

* fix(backlog-core): remove unused module io contract global

* fix: rename LICENSE.md to LICENSE for GitHub license detection (#233)

GitHub's licensee gem only recognizes standard filenames (LICENSE,
LICENSE.txt) — LICENSE.md caused the repo to show "Other" instead
of "Apache License 2.0". Updated all references across pyproject.toml,
README, docs, workflows, and FAQ.

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

* fix: restore standard Apache 2.0 license text for GitHub detection (#235)

The LICENSE body had two non-standard edits that pushed it below
GitHub licensee's ~95% similarity threshold, causing "Other" instead
of "Apache License 2.0". Restored the canonical text; only the
copyright line in the appendix is customized (as intended by the
Apache template).

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

* Add openspec changes for architecture level enhancement

* feat(ci): attach test and repro log artifacts to PR orchestrator runs (#262)

* feat(ci): attach test and repro log artifacts to PR orchestrator runs

- Tests job: run smart-test-full, upload logs/tests/ as test-logs artifact
- Contract-first-ci: capture repro to logs/repro/, upload repro-logs and repro-reports
- Docs: CI and GitHub Actions section in troubleshooting (artifact names, usage)
- Version 0.31.1, CHANGELOG entry

Implements OpenSpec change ci-01-pr-orchestrator-log-artifacts. Fixes #260.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix workflow and test

* ci(pr-orchestrator): add log artifacts for all pipeline jobs

- type-check: capture output to logs/type-check/, upload type-check-logs
- lint: capture to logs/lint/, upload lint-logs
- compat-py311: capture to logs/compat-py311/, upload compat-py311-logs
- quality-gates: capture to logs/quality-gates/, upload quality-gates-logs
- compat-py311: use hatch -e ENV run run (not hatch test) for pytest
- docs: list all CI artifact names and jobs in troubleshooting

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: enhanced module manifest security and integrity (arch-06) (#263)

* feat: enhanced module manifest security and integrity (arch-06)

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: remove duplicate ModulePackageMetadata import (ruff F811)

* Fix failed tests

* Fix type-check errors

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: Schema Extension System for Modular ProjectBundle Extensions (arch-07) (#265)

* feat: add schema extension system for modular ProjectBundle extensions
  Enables modules to extend Feature and ProjectBundle with namespaced custom
  fields without modifying core models, supporting marketplace-ready
  interoperability.
  - Add extensions dict field to Feature and ProjectBundle models
  - Implement type-safe get/set extension accessors with namespace enforcement
  - Extend module manifest schema with schema_extensions declaration
  - Add ExtensionRegistry for collision detection and introspection
  - Extend module lifecycle registration to load and validate extensions
  OpenSpec Change: arch-07-schema-extension-system
  Resolves #213

* feat: schema extension system (arch-07) and quality gate fixes

- Add extensions field and get_extension/set_extension to Feature and ProjectBundle
- Add SchemaExtension model and schema_extensions to ModulePackageMetadata
- Add ExtensionRegistry with collision detection; integrate in module registration
- Parse schema_extensions in discover_package_metadata
- Docs: extending-projectbundle guide, architecture section, sidebar
- Version 0.32.0, CHANGELOG entry, TDD_EVIDENCE
- Format: E402 (imports at top in project.py), UP042 (StrEnum in backlog-core),
  RUF043/B017 in schema extension tests
- Type-check: pass schema_metadata/project_metadata in BundleManifest test calls

OpenSpec Change: arch-07-schema-extension-system
Resolves #213

Co-authored-by: Cursor <cursoragent@cursor.com>

* Update change progress

* Add docs guides and update changes

* Use v0.32.0 as version and combine arch-06/arch-07

* Update change order plan

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix codeql findings

* feat(workflow): standardize worktree-first development flow (#268)

* feat(workflow): standardize worktree-first development flow

* docs(openspec): mark workflow-01 delivery tasks complete

* Apply review finding

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* Fix review finding

* feat: implement policy-engine-01 unified policy framework (#270)

* feat(policy-engine): implement unified policy framework

* docs(openspec): mark policy-engine-01 implemented in change order

* fix(policy-engine): make module io contract compliant

* feat(policy-engine): add policy init templates and docs coverage

* fix: refine grouped policy limit semantics and outputs

* docs: clarify policy engine value for new users

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* fix: harden policy module imports and snapshot path resolution

* Update backlog core change to cover workspace level modules

* feat(init): align init module discovery with registry (backlog-core-01) (#275)

- Use discover_all_package_metadata() in init so list-modules/enable/disable
  use same roots as registry (built-in + workspace modules + SPECFACT_MODULES_ROOTS)
- Extend backlog-core-01 OpenSpec: init-module-discovery-alignment spec,
  tasks 0.5.x, TDD evidence
- Bump version to 0.34.0; CHANGELOG

Fixes #116

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: add thorough codebase validation (validation-01, #163) (#272)

* feat: add thorough codebase validation (validation-01)
  - Add --crosshair-per-path-timeout to specfact repro and ReproChecker
  - Add docs/reference/thorough-codebase-validation.md (quick check, contract-full, sidecar, dogfooding)
  - Unit test and TDD evidence for CrossHair per-path timeout
  - OpenSpec validation-01-deep-validation tasks and TDD_EVIDENCE updated

* fix: reject non-positive CrossHair per-path timeout (review)

* docs: CHANGELOG v0.34.0 and doc updates for thorough codebase validation

---------

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* feat: add patch apply (local + --write with confirmation) [#177] (#273)

* feat(patch-mode): add patch apply (local + --write with confirmation) [#177]

- Add patch_mode module: pipeline (generator, applier, idempotency), patch apply command
- specfact patch apply <file> (local + preflight), patch apply --write --yes (upstream, idempotent)
- OpenSpec patch-mode-01-preview-apply: proposal Source Tracking, tasks, TDD_EVIDENCE
- CHANGELOG [Unreleased] entry for v0.34.0 merge

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(patch-mode): sanitize idempotency keys, derive key from patch content [PR review]

* Fix errors and ensure module compatibility

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: add bundle-mapper module (bundle-mapper-01, #121) (#274)

* feat: add bundle-mapper module with confidence-based spec-to-bundle mapping

- BundleMapping model and BundleMapper engine (explicit label, historical, content similarity)
- Mapping history persistence and MappingRule (save_user_confirmed_mapping, load_bundle_mapping_config)
- Interactive UI (ask_bundle_mapping) with Rich confidence visualization
- Unit tests and TDD_EVIDENCE for bundle-mapper-01 (OpenSpec #121)

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(bundle-mapper): address PR review findings (P1/P2)

- P1 interactive: no default accept for low-confidence; use default only when conf >= 0.5
- P1 history: ignore empty key fields in item_keys_similar (only count non-empty matches)
- P2 engine: add historical weight only when hist_bundle == primary_bundle_id
- Add test_item_keys_similar_empty_fields_not_counted to lock empty-key behavior

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* Archive finished changes

* fix: implement verification-01 wave1 delta closure (#277)

* fix: implement verification-01 delta for bundle mapping, patch apply, and docs parity

* test: fix patch write yes scenario for real diff apply

* fix: keep bundle mapping history out of bundle manifest

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* Archive delta validation change and update specs

* Update patch version

* Potential fix for pull request finding 'Empty except'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>

* apply review fixes

* Add cli validation changes

* feat: launch central module marketplace lifecycle (#287)

* feat: launch module marketplace lifecycle and trust-first UX

Deliver the central module marketplace workflow with source-aware discovery, lifecycle management, and trust/publisher visibility so users can safely manage official vs local modules. This also aligns docs and OpenSpec artifacts with the shipped behavior, including command introspection and clearer install/uninstall guidance.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: respect explicit discovery roots in module tests

Disable implicit legacy/workspace roots when explicit roots are passed to module discovery so isolated test roots are honored and deterministic.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: enforce safe module extraction and upgrade reinstall

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: resolve bundle-mapper review defects with TDD evidence (#290)

* feat: add bundle-mapper module with confidence-based spec-to-bundle mapping

- BundleMapping model and BundleMapper engine (explicit label, historical, content similarity)
- Mapping history persistence and MappingRule (save_user_confirmed_mapping, load_bundle_mapping_config)
- Interactive UI (ask_bundle_mapping) with Rich confidence visualization
- Unit tests and TDD_EVIDENCE for bundle-mapper-01 (OpenSpec #121)

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(bundle-mapper): address PR review findings (P1/P2)

- P1 interactive: no default accept for low-confidence; use default only when conf >= 0.5
- P1 history: ignore empty key fields in item_keys_similar (only count non-empty matches)
- P2 engine: add historical weight only when hist_bundle == primary_bundle_id
- Add test_item_keys_similar_empty_fields_not_counted to lock empty-key behavior

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: address bundle-mapper review defects with tdd evidence

* test: make specmatic integration tests plugin-agnostic

---------

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* feat:Add architecture review docs and findings to mitigate

* feat(backlog): add backlog add for interactive issue creation (#289)

* feat: add interactive backlog issue creation flow

* feat(backlog): add interactive issue creation and mapping setup

* fix: align backlog protocol test fakes and module manifest versions

* Fix type error

* fix(backlog): persist ado sprint and normalize github create id

* fix(backlog-core): address review findings for add/config/github

---------

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* chore(openspec): archive completed changes and align architecture docs (#292)

* chore(openspec): archive completed changes and align architecture docs

* docs(architecture): refresh discrepancies report after arch-08 remediation

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* docs(change): Archive architecture discrepancy remediation change

* fix(codeql): preserve module contract marker and document fallback excepts

* fix(backlog): restore installed-runtime discovery parity and add backlog prompt (#294)

* fix(backlog): restore installed runtime discovery and add backlog prompt

* Archive bugfix change

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* fix(version): sync manifests to 0.36.1 and archive backlog-core-04 (#297)

* fix(backlog): restore installed runtime discovery and add backlog prompt

* Archive bugfix change

* fix(version): sync built-in module manifests to 0.36.1

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

---------

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 4 people

.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).