fix(security): confine IDE prompt exports

CHANGELOG.md

@@ -10,6 +10,16 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.55.5] - 2026-09-06
+
+### Security
+
+- **Repository-confined IDE exports:** reject symlinked or out-of-repository
+  prompt export roots before cleanup or writes, preventing attacker-controlled
+  repositories from deleting or overwriting external files.
+
+---
+
 ## [0.55.4] - 2026-09-02
 
 ### Security

openspec/changes/security-01-confine-ide-prompt-exports/TDD_EVIDENCE.md

@@ -0,0 +1,40 @@
+# TDD Evidence
+
+## Failing before implementation
+
+- Timestamp: 2026-09-06T23:20Z
+- Command: `hatch run pytest -q tests/unit/utils/test_ide_setup.py -k 'symlinked_export_root or preserves_unrelated_directory'`
+- Result: **failed as expected** (`1 failed, 1 passed`). The production path
+  removed the external `core` directory and wrote `specfact.test.md` through
+  the repository-controlled `.cursor/commands` symlink instead of raising.
+
+## Passing after implementation
+
+- Timestamp: 2026-09-06T23:22Z
+- Command: `hatch run pytest -q tests/unit/utils/test_ide_setup.py -k 'symlinked_export_root or preserves_unrelated_directory'`
+- Result: **passed** (`2 passed, 28 deselected`).
+- Command: `hatch run pytest -q tests/unit/utils/test_ide_setup.py`
+- Result: **passed** (`30 passed`).
+- Command: `hatch run pytest -q tests/unit/utils/test_ide_setup.py tests/unit/security/test_release_promotion_security_gates.py::test_patch_release_uses_next_version_in_all_sources tests/unit/scripts/test_reproducible_delivery.py::test_reproducible_delivery_checker_verifies_hashed_export`
+- Result: **passed** (`32 passed`).
+
+## Quality gates
+
+- `hatch run format`: passed; 987 files unchanged.
+- `hatch run type-check`: passed with 0 errors (repository baseline warnings were reported).
+- `hatch run lint`: passed with 0 errors and 0 warnings.
+- `hatch run yaml-lint`: command completed but reported pre-existing errors in archived and unrelated active evidence YAML.
+- `openspec validate security-01-confine-ide-prompt-exports --strict`: passed.
+- `hatch run python scripts/check_reproducible_delivery.py`: passed.
+- `uv lock --check`: passed.
+- `hatch run check-pypi-ahead`: passed; 0.55.5 is ahead of PyPI 0.55.4.
+- `hatch run semgrep-sast --json --output /tmp/specfact-semgrep.json` and gate: passed with 0 findings.
+- `hatch run bandit-scan`: passed with no medium/high findings.
+- `hatch run verify-modules-signature`: passed for all four manifests.
+- `hatch run smart-test`: 3043 passed and 34 skipped; four unrelated failures came from missing external bundle packages plus release/lock assertions that were subsequently corrected. The two corrected release/delivery tests pass in the focused 32-test run above.
+- `hatch run specfact code review run --json --out .specfact/code-review.json`: produced no findings, but failed closed because the installed review module lacked verified OCI analyzer cache entries; all required analyzer evidence was `UNKNOWN`.
+
+## Documentation and internal wiki review
+
+- Reviewed `README.md`, `docs/`, `docs/index.md`, and navigation impact. No documentation change is needed for this repository-bound security correction.
+- The sibling `specfact-cli-internal` checkout is unavailable. Follow-up: add/update `wiki/sources/security-01-confine-ide-prompt-exports.md` and run `python3 scripts/wiki_rebuild_graph.py` from that repository root.

openspec/changes/security-01-confine-ide-prompt-exports/design.md

@@ -0,0 +1,33 @@
+## Context
+
+IDE export paths are repository-relative configuration values, but resolving an
+attacker-controlled symlink turns the effective cleanup and write target into
+an external directory. Child-relative checks cannot establish repository
+containment after the root has already escaped.
+
+## Decision
+
+Validate the unresolved export root before any filesystem mutation. The root
+must not be a symlink and its resolved path must be strictly beneath the
+resolved repository path. Cleanup helpers return without side effects when the
+root is unsafe, while export entry points raise a clear error before creating
+or writing files.
+
+Cleanup remains narrowly limited to existing SpecFact legacy naming and flat
+`specfact*` output patterns; unrelated directories are not ownership evidence
+and remain untouched.
+
+## Alternatives Considered
+
+- Persist ownership markers for every exported path. This would support more
+  exact cleanup but adds migration state beyond the minimal security fix.
+- Resolve the root and check only its children. Rejected because it validates
+  containment relative to an already escaped root rather than the repository.
+
+## Risks and Rollback
+
+Repositories that intentionally symlink IDE export roots outside themselves
+will now fail closed. That compatibility break is required to preserve the
+repository boundary. A rollback must not occur without an alternative
+ownership- and containment-safe export design.
+

openspec/changes/security-01-confine-ide-prompt-exports/proposal.md

@@ -0,0 +1,48 @@
+## Why
+
+An attacker-controlled repository can make an IDE prompt export root, such as
+`.github/prompts`, a symlink to a writable location outside the repository.
+Prompt cleanup and export currently follow that root, which can delete legacy
+directories or write generated prompts outside the requested repository.
+
+## What Changes
+
+- Require every IDE prompt export root to be a real directory path contained
+  beneath the resolved target repository before cleanup or export.
+- Refuse symlinked or out-of-repository export roots without deleting or
+  writing through them.
+- Preserve unrelated team-owned directories while retaining normal cleanup of
+  legacy SpecFact export directories inside a repository.
+- Add focused security regression tests for cleanup and export behavior.
+
+## Capabilities
+
+### Modified Capabilities
+
+- `init-ide-prompt-source-selection`: IDE prompt exports remain confined to the
+  selected repository and do not traverse repository-controlled export-root
+  symlinks.
+
+## Impact
+
+- Affected code: `src/specfact_cli/utils/ide_setup.py`.
+- Affected tests: `tests/unit/utils/test_ide_setup.py`.
+- Compatibility: normal in-repository IDE exports and cleanup remain unchanged;
+  unsafe symlinked export roots are rejected.
+- Documentation: review `README.md`, `docs/`, `docs/index.md`, and navigation;
+  no user-facing documentation change is expected because this restores the
+  existing repository-bound safety contract.
+- Rollback: revert the helper and call-site guard together; doing so would
+  reopen the external filesystem deletion/write vulnerability.
+
+## Source Tracking
+
+<!-- source_repo: nold-ai/specfact-cli -->
+- **Parent Feature**: [#375](https://github.com/nold-ai/specfact-cli/issues/375)
+- **Parent Epic**: [#285](https://github.com/nold-ai/specfact-cli/issues/285)
+- **GitHub Issue**: [#720](https://github.com/nold-ai/specfact-cli/issues/720)
+- **Issue URL**: https://github.com/nold-ai/specfact-cli/issues/720
+- **Repository**: nold-ai/specfact-cli
+- **Blocked By**: none
+- **Last Synced Status**: issue open, Todo, assigned, labels and parent verified on 2026-09-06
+

openspec/changes/security-01-confine-ide-prompt-exports/specs/init-ide-prompt-source-selection/spec.md

@@ -0,0 +1,20 @@
+## ADDED Requirements
+
+### Requirement: IDE prompt exports are repository confined
+
+The CLI SHALL perform IDE prompt cleanup and export only through a non-symlink
+export root whose resolved path is contained beneath the resolved target
+repository. It SHALL NOT delete or write through an unsafe export root and
+SHALL preserve unrelated team-owned directories.
+
+#### Scenario: Repository-controlled export root targets an external directory
+
+- **GIVEN** an IDE prompt export root in the target repository is a symlink to a writable external directory
+- **WHEN** IDE prompt initialization attempts cleanup and export
+- **THEN** the CLI rejects the unsafe export root before deleting or writing any external content
+
+#### Scenario: Normal repository-contained export
+
+- **GIVEN** an IDE prompt export root is a real directory beneath the target repository
+- **WHEN** IDE prompt initialization cleans legacy SpecFact exports and writes selected prompts
+- **THEN** the CLI completes the export while leaving unrelated team-owned directories intact

openspec/changes/security-01-confine-ide-prompt-exports/tasks.md

@@ -0,0 +1,29 @@
+## 1. Worktree and specification
+
+- [x] 1.1 Confirm implementation runs on the dedicated non-protected `work` branch/worktree.
+- [x] 1.2 Add the repository-confined IDE prompt export specification and design.
+- [x] 1.3 Create and link public issue #720 with parent, labels, assignment, project status, and blocker metadata.
+
+## 2. Tests and failing evidence
+
+- [x] 2.1 Add tests derived from both specification scenarios: external export-root symlinks fail without mutation, and normal exports preserve unrelated directories.
+- [x] 2.2 Run the focused tests before production changes and record failing output in `TDD_EVIDENCE.md`.
+
+## 3. Implementation
+
+- [x] 3.1 Add a small internal containment guard for IDE export roots.
+- [x] 3.2 Apply the guard before cleanup and prompt export filesystem mutations.
+
+## 4. Verification and delivery
+
+- [x] 4.1 Re-run focused tests and record passing output in `TDD_EVIDENCE.md`.
+- [x] 4.2 Run formatting, type-checking, lint, YAML lint, contract tests, smart tests, independent static analysis, and SpecFact code review gates; record unrelated/environment limitations in `TDD_EVIDENCE.md`.
+- [x] 4.3 Review `README.md`, `docs/`, `docs/index.md`, and navigation for documentation impact; no update is required.
+- [x] 4.4 Bump the patch version in all canonical files and add the security fix to `CHANGELOG.md`.
+- [x] 4.5 Verify signed module manifests remain valid; no signed module asset changed.
+- [x] 4.6 Record the internal wiki mirror/rebuild follow-up because the sibling checkout is unavailable.
+- [ ] 4.7 Commit the completed change and create a pull request to `dev`.
+
+## 5. Post-merge cleanup
+
+- [ ] 5.1 After merge, run `openspec archive security-01-confine-ide-prompt-exports` and perform worktree cleanup.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.55.4"
+version = "0.55.5"
 description = "AI-bloat defense CLI for Python teams. Run deterministic code review, cleanup forecasts, and spec/contract evidence for AI-assisted and brownfield delivery."
 readme = "README.md"
 requires-python = ">=3.11"

setup.py

@@ -7,7 +7,7 @@
 if __name__ == "__main__":
     _setup = setup(
         name="specfact-cli",
-        version="0.55.4",
+        version="0.55.5",
         description=(
             "AI-bloat defense CLI for Python teams. Run deterministic code review, cleanup forecasts, "
             "and spec/contract evidence for AI-assisted and brownfield delivery."

src/__init__.py

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

src/specfact_cli/__init__.py

@@ -76,6 +76,6 @@ def _install_progressive_disclosure() -> None:
 # keeps missing-command and missing-parameter UX consistent outside the root CLI too.
 _install_progressive_disclosure()
 
-__version__ = "0.55.4"
+__version__ = "0.55.5"
 
 __all__ = ["__version__"]

src/specfact_cli/utils/ide_setup.py

@@ -457,10 +457,23 @@ def _merge_prompt_export_outputs_by_basename(
     return out
 
 
+def _safe_ide_export_dir(repo_path: Path, ide: str) -> Path:
+    """Return the IDE export directory only when it cannot escape the repository."""
+    export_dir = repo_path / str(IDE_CONFIG[ide]["folder"])
+    resolved_repo = repo_path.resolve()
+    resolved_export = export_dir.resolve()
+    try:
+        resolved_export.relative_to(resolved_repo)
+    except ValueError as exc:
+        raise ValueError(f"IDE export directory must remain inside the repository: {export_dir}") from exc
+    if export_dir.is_symlink():
+        raise ValueError(f"IDE export directory must not be a symlink: {export_dir}")
+    return resolved_export
+
+
 def _cleanup_legacy_multisource_segment_dirs(repo_path: Path, ide: str) -> None:
     """Remove per-source subfolders from older multi-source exports (layout is now flat under the IDE root)."""
-    config = IDE_CONFIG[ide]
-    base = (repo_path / str(config["folder"])).resolve()
+    base = _safe_ide_export_dir(repo_path, ide)
     if not base.is_dir():
         return
     for child in list(base.iterdir()):
@@ -498,7 +511,7 @@ def _prune_flat_specfact_exports_not_in_expected(
     """Remove prior flat ``specfact*`` exports that are not part of this merged export."""
     config = IDE_CONFIG[ide]
     format_type = str(config["format"])
-    base = (repo_path / str(config["folder"])).resolve()
+    base = _safe_ide_export_dir(repo_path, ide)
     if not base.is_dir():
         return
     pattern = _flat_export_glob_pattern_for_prune(format_type)
@@ -539,13 +552,12 @@ def _copy_template_files_to_ide(
 ) -> tuple[list[Path], Path | None]:
     """Copy a concrete list of prompt template files to the IDE target location."""
     config = IDE_CONFIG[ide]
-    ide_folder = str(config["folder"])
     format_type = str(config["format"])
     settings_file = config.get("settings_file")
     if settings_file is not None and not isinstance(settings_file, str):
         settings_file = None
 
-    ide_dir = repo_path / ide_folder
+    ide_dir = _safe_ide_export_dir(repo_path, ide)
     if source_segment is not None:
         ide_dir = ide_dir / source_segment
     ide_dir.mkdir(parents=True, exist_ok=True)
@@ -646,8 +658,7 @@ def _copy_skill_bundles_to_ide(
     force: bool = False,
 ) -> tuple[list[Path], None]:
     """Copy source/module prompt groups to skill-based IDE targets."""
-    config = IDE_CONFIG[ide]
-    ide_dir = repo_path / str(config["folder"])
+    ide_dir = _safe_ide_export_dir(repo_path, ide)
     ide_dir.mkdir(parents=True, exist_ok=True)
 
     expected = {_skill_output_name_for_source(source_id) for source_id in prompts_by_source}

tests/unit/security/test_release_promotion_security_gates.py

@@ -564,7 +564,7 @@ def run_rg(arguments: list[str], **_kwargs: object) -> subprocess.CompletedProce
 
 def test_patch_release_uses_next_version_in_all_sources() -> None:
     """The security baseline consumes only the next semver patch."""
-    expected = "0.55.4"
+    expected = "0.55.5"
     project = tomllib.loads((REPO_ROOT / "pyproject.toml").read_text(encoding="utf-8"))
     assert project["project"]["version"] == expected
     for path in ("setup.py", "src/__init__.py", "src/specfact_cli/__init__.py"):

tests/unit/utils/test_ide_setup.py

@@ -11,6 +11,7 @@
     PROMPT_SOURCE_CORE,
     SPECFACT_COMMANDS,
     _flat_export_glob_pattern_for_prune,
+    copy_prompts_by_source_to_ide,
     copy_templates_to_ide,
     create_vscode_settings,
     detect_ide,
@@ -262,6 +263,40 @@ def test_copy_templates_copies_non_core_prompt_ids_when_discovered(self, tmp_pat
         assert any(path.name == "specfact.backlog-add.md" for path in copied_files)
         assert (tmp_path / ".cursor" / "commands" / "specfact.backlog-add.md").exists()
 
+    def test_copy_prompts_rejects_symlinked_export_root_without_external_mutation(self, tmp_path: Path) -> None:
+        """Repository-controlled export-root symlinks must not delete or write external content."""
+        repo_path = tmp_path / "repo"
+        repo_path.mkdir()
+        external = tmp_path / "external"
+        (external / "core").mkdir(parents=True)
+        sentinel = external / "core" / "sentinel.txt"
+        sentinel.write_text("keep", encoding="utf-8")
+        (repo_path / ".cursor").mkdir()
+        (repo_path / ".cursor" / "commands").symlink_to(external, target_is_directory=True)
+        template = tmp_path / "specfact.test.md"
+        template.write_text("---\ndescription: Test\n---\n# Test\n", encoding="utf-8")
+
+        with pytest.raises(ValueError, match="IDE export directory"):
+            copy_prompts_by_source_to_ide(repo_path, "cursor", {PROMPT_SOURCE_CORE: [template]}, force=True)
+
+        assert sentinel.read_text(encoding="utf-8") == "keep"
+        assert not (external / "specfact.test.md").exists()
+
+    def test_copy_prompts_preserves_unrelated_directory_in_safe_export_root(self, tmp_path: Path) -> None:
+        """Normal repository-contained exports leave team-owned directories intact."""
+        custom_file = tmp_path / ".cursor" / "commands" / "custom" / "team.md"
+        custom_file.parent.mkdir(parents=True)
+        custom_file.write_text("keep", encoding="utf-8")
+        template = tmp_path / "specfact.test.md"
+        template.write_text("---\ndescription: Test\n---\n# Test\n", encoding="utf-8")
+
+        copied, _settings = copy_prompts_by_source_to_ide(
+            tmp_path, "cursor", {PROMPT_SOURCE_CORE: [template]}, force=True
+        )
+
+        assert copied == [tmp_path / ".cursor" / "commands" / "specfact.test.md"]
+        assert custom_file.read_text(encoding="utf-8") == "keep"
+
 
 def test_discover_prompt_template_files_falls_back_to_repo_resources(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch