Merge dev into main

[djm81]

Description

This pull request merges dev into main to ship the current integration branch. Highlights since the last promotion include:

• specfact init ide: Prompt source catalog, --prompts selection, flat export under .github/prompts/ (and other IDE roots) for editor/agent discoverability, core-vs-module deduplication by template basename, legacy segment cleanup, and VS Code chat.promptFilesRecommendations alignment.
• Runtime / resources: Cross-platform runtime and IDE resource discovery hardening.
• Docs: Core site IA and related documentation updates.
• Quality: Code-review and backlog-related fixes, contract/test follow-ups.

Fixes #(n/a — batch merge from dev)

New Features #(see commits on dev since last main promotion)

Contract References: Existing @icontract / @beartype on touched public APIs (e.g. ide_setup, init commands); no new public contract surface required for this merge description.

Type of Change

Please check all that apply:

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔒 Contract enforcement (adding/updating @icontract decorators)
• 🧪 Test enhancement (scenario tests, property-based tests)
• 🔧 Refactoring (code improvement without functionality change)

Contract-First Testing Evidence

Required for all changes affecting CLI commands or public APIs:

Contract Validation

• Runtime contracts added/updated (@icontract decorators on public APIs) — where applicable in merged changes
• Type checking enforced (@beartype decorators applied)
• CrossHair exploration completed: hatch run contract-test-exploration
• Contract violations reviewed and addressed — per CI / local gates on dev

Test Execution

• Contract validation: hatch run contract-test-contracts ✅
• Contract exploration: hatch run contract-test-exploration ✅
• Scenario tests: hatch run contract-test-scenarios ✅
• Full test suite: hatch run contract-test-full ✅

Test Quality

• CLI commands tested with typer test client
• Edge cases covered with Hypothesis property tests — where tests exist on dev
• Error handling tested with invalid inputs
• Rich console output verified manually or with snapshots

How Has This Been Tested?

Contract-First Approach: dev is validated by CI (contract layers, pytest, pre-commit). Init IDE changes are covered by unit tests in tests/unit/utils/test_ide_setup.py and tests/unit/modules/init/test_init_ide_prompt_selection.py.

Manual Testing

• Tested CLI commands manually
• Verified rich console output
• Tested with different input scenarios
• Checked error messages for clarity

Automated Testing

• Contract validation passes
• Property-based tests cover edge cases — where applicable
• Scenario tests cover user workflows
• All existing tests still pass — on dev / CI

Test Environment

• Python version: 3.11+ (per pyproject.toml)
• OS: Linux / macOS / Windows (CI matrix)

Checklist

• My code follows the style guidelines (PEP 8, ruff format, isort)
• I have performed a self-review of my code
• I have added/updated contracts (@icontract, @beartype) — only where changed in this batch
• I have added/updated docstrings (Google style)
• I have made corresponding changes to documentation — where included on dev
• My changes generate no new warnings (basedpyright, ruff, pylint) — target state on dev
• All tests pass locally / in CI
• I have added tests that prove my fix/feature works — for new behavior on dev
• Any dependent changes have been merged — dev includes merges from main as needed

Quality Gates Status

• Type checking ✅ (hatch run type-check)
• Linting ✅ (hatch run lint)
• Contract validation ✅ (hatch run contract-test-contracts)
• Contract exploration ✅ (hatch run contract-test-exploration)
• Scenario tests ✅ (hatch run contract-test-scenarios)

Screenshots/Recordings (if applicable)

N/A for this merge PR (CLI/infra batch).

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Summary by CodeRabbit

Release Notes v0.42.6

• Bug Fixes
  • Fixed IDE multi-source prompt export to use a flat directory layout instead of per-source subfolders for improved discoverability
  • Eliminated duplicate prompt exports when core and module sources share the same template filename
  • Added automatic cleanup of legacy prompt directories and stale exports when selected sources change

Walkthrough

Release version 0.42.6 patches IDE prompt export behavior: exports now use flat directory layout instead of per-source subfolders, core prompts omit basenames already provided by modules, and legacy per-source segment directories are removed during re-export when source selection changes.

Changes

Cohort / File(s)	Summary
Version Bumps pyproject.toml, setup.py, src/__init__.py, src/specfact_cli/__init__.py	Incremented package version from 0.42.5 to 0.42.6 across all version declaration files.
Module Metadata src/specfact_cli/modules/init/module-package.yaml	Updated init module package version from 0.1.17 to 0.1.18; regenerated integrity checksum and signature fields.
Documentation & Specifications CHANGELOG.md, openspec/changes/init-ide-prompt-source-selection/spec.md, openspec/changes/init-ide-prompt-source-selection/TDD_EVIDENCE.md	Added changelog entry documenting multi-source flat export, basename deduplication, and legacy cleanup behavior; updated specification to define flat directory layout and deterministic basename collision rules; recorded test execution evidence.
Core IDE Export Logic src/specfact_cli/utils/ide_setup.py	Significant refactor: replaced per-source segment export with basename-based merging; added _core_prompts_excluding_module_basenames() and _merge_prompt_export_outputs_by_basename(); removed segment-based functions; updated expected_ide_prompt_export_paths() to return flat paths; added _cleanup_legacy_multisource_segment_dirs() and _prune_flat_specfact_exports_not_in_expected(); updated VS Code/Copilot path generation for flat layout.
Command Documentation src/specfact_cli/modules/init/src/commands.py	Updated copy_templates_to_ide docstring to reflect "multi-source flat export" behavior instead of "namespaced multi-source export."
Unit Tests tests/unit/utils/test_ide_setup.py, tests/unit/modules/init/test_init_ide_prompt_selection.py, tests/unit/specfact_cli/registry/test_init_module_lifecycle_ux.py	Added monkeypatching of _module_prompt_sources_catalog to isolate catalog discovery; added test for flat export glob patterns; updated assertions for flat export paths; added module basename collision tests.
End-to-End Tests tests/e2e/test_init_command.py	Added autouse fixture to stub module prompt sources; updated path assertions and test setup from namespaced layout (.../commands/core) to flat layout (.../commands); adjusted skip/overwrite and auto-detection scenarios to reflect flat structure.

Sequence Diagram(s)

(Skipped: Changes are primarily internal refactoring of IDE export logic within a single module. While complex, the flow is straightforward internal data transformation without multi-component interactions that benefit from visualization.)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

The PR requires careful review of the new basename-merging logic and flat export layout in ide_setup.py, validation that the core-exclusion deduplication works correctly across module sources, verification of test coverage across multiple test files with heterogeneous assertion updates, and confirmation that legacy per-source directory cleanup does not inadvertently remove user files.

Possibly related issues

• IDE Prompt Source Selection #382: Directly addressed by this PR's IDE prompt source-selection orchestration in ide_setup.py, including catalog discovery, core-exclusion by basename, and flat export/merge functions.

Possibly related PRs

• release: promote dev to main for v0.42.5 (patch) #446: Modified the same src/specfact_cli/utils/ide_setup.py to add per-source export logic; this PR replaces that with flat basename-merged export and removes per-source segment infrastructure.

Suggested labels

enhancement, bug

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is vague and does not clearly convey the main changes; it only indicates a branch merge without specifying what features or fixes are being shipped.	Consider updating the title to reflect key changes, e.g., 'Merge dev: add specfact init ide features, flat export layout, and cross-platform hardening'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description is well-structured, comprehensive, and covers highlights, testing evidence, and quality gates, meeting the template requirements for a batch/integration merge.
Docstring Coverage	✅ Passed	Docstring coverage is 83.72% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 41dc0dba14

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".