fix: GitHub Pages configuration and linting improvements (#9)

* chore: remove mcp.json from version control

* fix: correct test paths for new .specfact structure

- Fix test_compare_with_smart_defaults: remove duplicate mkdir for plans directory
- Fix test_compare_output_to_specfact_reports: move auto-derived plan to .specfact/plans/ instead of .specfact/reports/brownfield/
- Fix test_team_collaboration_workflow: use correct pattern 'report-*.md' for comparison reports and check auto-derived plans in .specfact/plans/

* fix: update .gitignore

* fix: correct pre-merge check to only flag root-level temporary files

- Fix regex to only match temporary files at project root (not in tests/)
- Patterns match .gitignore: /test_*.py, /debug_*.py, /trigger_*.py, /temp_*.py
- Use grep -v '/' to ensure files are at root level (no subdirectories)
- Also check for analysis artifacts at root
- Exclude legitimate test files in tests/ directory

* fix: add conftest.py to fix tools imports in tests

- Create tests/conftest.py to add project root to sys.path
- Fixes ModuleNotFoundError for 'tools' module in Python 3.11 tests
- Update test_smart_test_coverage.py to use consistent sys.path approach
- Required because pytest --import-mode=importlib doesn't respect pythonpath
  during test collection

* fix: install specfact-cli from local source in specfact-gate workflow

- Change from 'pip install specfact-cli' (PyPI) to 'pip install -e .' (local source)
- Required because package is not yet published to PyPI
- Matches approach used in pr-orchestrator.yml workflow
- Install hatch first to ensure proper environment setup

* refactor: combine hatch installation and CLI setup steps

- Combine 'Install dependencies' and 'Install SpecFact CLI from source' steps
- Ensures hatch is available before use
- Matches pattern used in pr-orchestrator.yml cli-validation job
- More efficient and clearer workflow structure

* fix: make repro main command the default callback

- Replace @app.command() with @app.callback(invoke_without_command=True)
- Allows 'specfact repro --verbose --budget 90' without requiring a subcommand
- Fixes workflow error: 'No such option: --verbose'
- main() now runs when repro is called without a subcommand

* fix: remove invalid -k filter from Python 3.11 compatibility tests

- Remove -k 'contract' filter that was deselecting all tests (exit code 5)
- Run unit and integration tests instead for Python 3.11 compatibility check
- Skip E2E tests to keep compatibility check fast
- Tests are advisory (don't fail build) to allow gradual compatibility work

* fix: sync __version__ with pyproject.toml (0.4.0)

- Update __version__ in __init__.py to match pyproject.toml version
- Ensures version consistency across package metadata

* fix: exclude tests, docs, tools from PyPI package

- Add [tool.hatch.build.targets.sdist] configuration
- Include only essential files: src/, README.md, LICENSE.md, pyproject.toml
- Exclude development files: tests/, tools/, docs/, .github/, .cursor/, contracts/, reports/, etc.
- Ensure clean PyPI package with only production code

* docs: fix uvx command syntax in all documentation

- Update all occurrences of 'uvx specfact' to 'uvx --from specfact-cli specfact'
- Fixes issue where uvx couldn't find package by command name alone
- Package name is 'specfact-cli', command name is 'specfact'
- Updated in: README.md, docs/README.md, docs/getting-started/installation.md,
  docs/guides/competitive-analysis.md, AGENTS.md

* fix: Contract test directory handling and GitHub Pages legal files (#3)

* fix: handle directories in contract test file scanning

- Add is_file() check in _get_modified_files() to skip directories
- Add IsADirectoryError handling in _get_file_hash() and _compute_file_hash()
- Fix contract test error when scanning resources directory
- Ensure only Python files are processed for contract validation

* fix: include LICENSE.md and TRADEMARKS.md in GitHub Pages

- Copy LICENSE.md and TRADEMARKS.md to docs/ before building
- Add root files to workflow paths trigger
- Update docs/index.md to use relative links for LICENSE and TRADEMARKS
- Ensure legal information is included in published documentation

* feat: enable PR orchestrator workflow for dev branch

- Add dev branch to pull_request and push triggers
- Ensure CI/CD runs on PRs to both main and dev branches
- Maintains same path ignore rules for both branches

* feat: enable specfact-gate workflow for dev branch

- Add dev branch to pull_request and push triggers
- Ensure contract validation runs on PRs to both main and dev branches

* fix: replace percent format with f-string in plan.py

- Fix UP031 ruff error by using f-string instead of percent format
- Update prompt text to use modern Python string formatting

* fix: resolve import sorting conflict between isort and ruff

- Remove isort from format and lint scripts to avoid conflicts
- Configure ruff's isort to match black profile (multi_line_output=3, combine_as_imports)
- Use ruff for both import sorting and formatting (more reliable and modern)
- Fix I001 import sorting errors in plan.py

This resolves the conflict where format and lint were producing different results
due to isort and ruff having different import sorting configurations.

* fix: use hatch run in GitHub workflow to ensure tools are available

- Change specfact repro to hatch run specfact repro in specfact-gate.yml
- Ensures all tools (semgrep, basedpyright, ruff, crosshair) are available in PATH
- Fix I001 import sorting in plan.py

* fix: replace try-except-pass with contextlib.suppress in logger_setup

- Fix SIM105 ruff error by using contextlib.suppress(Exception)
- Replace nested try-except-pass blocks with contextlib.suppress
- Improves code quality and follows ruff best practices

* fix: exclude logger_setup.py from CrossHair analysis

- Exclude logger_setup.py from CrossHair due to known signature analysis bug
- CrossHair has issues analyzing functions with *args/**kwargs patterns with decorators
- Contract exploration remains advisory, this prevents false failures

* fix: resolve ruff errors and CrossHair syntax issue

- Fix C414: Remove unnecessary list() call in sorted()
- Fix B007: Rename unused loop variable story_idx to _story_idx
- Fix CrossHair: Exclude common directory instead of using non-existent --exclude flag
- CrossHair doesn't support --exclude, so we exclude common/ by only including other directories

* fix: use unpacking instead of list concatenation for CrossHair targets

- Fix RUF005: Use unpacking (*crosshair_targets) instead of list concatenation
- Improves code quality and follows ruff best practices

* fix: resolve RET504 and SIM102 ruff errors

- Fix RET504: Remove unnecessary assignment before return in feature_keys.py
- Fix SIM102: Combine nested if statements into single if in fsm.py
- Improves code quality and follows ruff best practices

* fix: make CrossHair failures non-blocking

- Treat CrossHair failures as warnings (advisory only)
- Contract exploration is advisory, not blocking
- CrossHair has known issues analyzing certain function signatures with decorators
- Only count non-CrossHair failures for exit code determination

* fix: ruff check

* fix: ruff check

* fix: ruff check

---------

Co-authored-by: Dominikus Nold <[email protected]>

* feat: dynamic CrossHair detection, GitHub Action integration, and enforcement report enhancements (v0.4.2) (#5)

* feat: dynamic CrossHair detection, GitHub Action integration, and enforcement report enhancements

- Replace hard-coded skip list with dynamic signature issue detection
- Add comprehensive metadata to enforcement reports (plan, budget, config)
- Add structured findings extraction from tool output
- Add auto-fix support for Semgrep via --fix flag
- Add GitHub Action workflow with PR annotations and comments
- Add GitHub annotations utility with contract-first validation
- Add comprehensive test suite for new features
- Sync versions to 0.4.2 across all files

Fixes: CrossHair signature analysis limitations blocking CI/CD
New Features: GitHub Action integration, auto-fix support, enhanced reports

* fix: handle CrossHair signature analysis limitations in GitHub annotations

- Detect signature analysis limitations in create_annotations_from_report
- Treat signature issues as non-blocking (notice level, not error)
- Filter signature issues from failed checks in PR comments
- Add dedicated section for signature analysis limitations in PR comments
- Prevents workflow failures for non-blocking CrossHair signature issues

Fixes: GitHub Action workflow failing on CrossHair signature analysis limitations

* fix: escape GitHub Actions syntax in Jinja2 template

- Use {% raw %} blocks to escape GitHub Actions expressions
- Fixes Jinja2 UndefinedError for 'steps' variable
- All 5 failing tests now pass

Fixes:
- test_import_speckit_via_cli_command
- test_import_speckit_generates_github_action
- test_import_speckit_with_full_workflow
- test_generate_from_template
- test_generate_github_action

* fix: handle CrossHair signature issues in ReproChecker and fix ruff whitespace

- Detect CrossHair signature analysis limitations in ReproChecker.run_check()
- Mark signature issues as skipped instead of failed
- Fix whitespace issues in test_directory_structure_workflow.py (W293)
- Prevents local repro failures on CrossHair signature limitations

Fixes: specfact repro failing on CrossHair signature analysis limitations

* chore: remove duplicate specfact-gate.yml workflow

- specfact.yml is the new comprehensive workflow with PR annotations
- specfact-gate.yml was the old workflow with same triggers
- Removing to prevent duplicate workflow executions

Fixes: workflow running twice on each push

* fix: show all ruff errors by using --output-format=full

- Add --output-format=full flag to ruff check command
- Ensures all linting errors are reported, not just a few
- Fixes issue where pipeline only shows limited number of errors

Fixes: ruff report showing only a few issues instead of all

* fix: remove whitespace from blank lines in test_analyze_command.py

- Fix 20 W293 whitespace errors in dedent() strings
- Ruff now passes all checks for this file

Fixes: ruff linting errors in test file

* fix: remove whitespace from blank lines in test files

- Fix W293 whitespace errors in:
  - tests/integration/analyzers/test_code_analyzer_integration.py
  - tests/unit/analyzers/test_code_analyzer.py
  - tests/unit/tools/test_smart_test_coverage.py
  - tests/unit/utils/test_ide_setup.py
- All whitespace errors now fixed (68 fixed)
- Remaining 2 SIM105 suggestions are style recommendations, not errors

Fixes: ruff linting errors in test files

* fix: replace try-except-pass with contextlib.suppress for SIM105

- Replace try-except-pass pattern with contextlib.suppress(SystemExit)
- Fixes 2 SIM105 errors in test_smart_test_coverage.py
- All ruff linting errors now fixed

Fixes: SIM105 linting errors in test files

---------

Co-authored-by: Dominikus Nold <[email protected]>

* feat: Watch mode and documentation reorganization (v0.5.0) (#6)

* feat: add watch mode and complete documentation reorganization (v0.5.0)

- Add watch mode for continuous synchronization (sync spec-kit and sync repository)
- Implement real-time file system monitoring with configurable interval
- Add comprehensive E2E test suite for watch mode (20+ tests)
- Complete documentation reorganization (all 3 phases):
  - Phase 1: Core reorganization (streamlined README, persona-based docs/README)
  - Phase 2: Content creation (first-steps.md, workflows.md, troubleshooting.md, quick-examples.md)
  - Phase 3: Content enhancement (architecture.md, commands.md, polish all docs)
- Add plan sync --shared and plan compare --code-vs-plan convenience aliases
- Fix watch mode path validation and error handling
- Update all version artifacts to 0.5.0
- Add comprehensive CHANGELOG entry for 0.5.0

Closes: Watch mode implementation (Phase 6 & 7)
Closes: Documentation reorganization (all phases)

* chore: add reports/ to .gitignore and remove tracked reports

- Add reports/ directory to .gitignore (ephemeral artifacts should not be versioned)
- Remove tracked reports files from git (they are generated artifacts)
- Aligns with directory structure documentation where reports/ is gitignored

---------

Co-authored-by: Dominikus Nold <[email protected]>

* Update to repositioning for brownfield first strategy

* Switch to Apache 2 license

* Fix test failurs

* Fix tests and linter conflicts

* Fix github pages setup

* Fix pages setup

* Fix pages setup

* fix: remove container build job (no Dockerfile)

---------

Co-authored-by: Dominikus Nold <[email protected]>

Author: djm81

.github/workflows/pr-orchestrator.yml

@@ -344,64 +344,3 @@ jobs:
             fi
           } >> "$GITHUB_STEP_SUMMARY"
 
-  build-and-push-container:
-    name: Build and Push Container
-    runs-on: ubuntu-latest
-    needs: [package-validation]
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    permissions:
-      contents: read
-      packages: write
-      id-token: write
-    env:
-      REGISTRY: ghcr.io
-      IMAGE_NAME: ${{ github.repository }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Compute tags
-        id: vars
-        run: |
-          COMMIT_SHA="${{ github.sha }}"
-          SHORT_SHA="${COMMIT_SHA:0:8}"
-          TIMESTAMP=$(date -u +%Y%m%d-%H%M%S)
-          VERSION_TAG="$SHORT_SHA-$TIMESTAMP"
-
-          {
-            printf 'SHORT_SHA=%s\n' "$SHORT_SHA"
-            printf 'VERSION_TAG=%s\n' "$VERSION_TAG"
-          } >> "$GITHUB_ENV"
-
-      - name: Log in to ghcr.io
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build & Push specfact-cli
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: ./dockerfile
-          push: true
-          tags: |
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.VERSION_TAG }}
-
-      - name: Summary
-        if: always()
-        run: |
-          {
-            echo "## Container Build Summary"
-            echo "| Parameter | Value |"
-            echo "|-----------|--------|"
-            echo "| Branch | main |"
-            echo "| Version Tag | $VERSION_TAG |"
-            echo "| Image | \`${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest\` |"
-            echo "| Tagged | \`${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$VERSION_TAG\` |"
-          } >> "$GITHUB_STEP_SUMMARY"

_config.yml

@@ -3,9 +3,9 @@
 
 title: SpecFact CLI Documentation
 description: >-
-  Complete documentation for SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
-baseurl: "" # Set to "/specfact-cli" if using project pages, "" for user/organization pages
-url: "https://nold-ai.github.io" # Set to your GitHub Pages domain
+  Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.
+baseurl: "/specfact-cli" # Project pages require baseurl
+url: "https://nold-ai.github.io" # GitHub Pages domain
 
 # Build settings
 markdown: kramdown
@@ -51,26 +51,35 @@ defaults:
     values:
       layout: default
       permalink: /:basename/
+  - scope:
+      path: "getting-started"
+    values:
+      layout: default
+  - scope:
+      path: "guides"
+    values:
+      layout: default
+  - scope:
+      path: "reference"
+    values:
+      layout: default
+  - scope:
+      path: "examples"
+    values:
+      layout: default
 
 # Theme settings (using minimal theme for clean look)
 theme: minima
 minima:
   social:
-    github: nold-ai/specfact-cli
+    github:
+      username: nold-ai
+      repository: specfact-cli
   author:
     name: NOLD AI
     email: [email protected]
-
-# Navigation
-navigation:
-  - title: Getting Started
-    url: /getting-started/
-  - title: Guides
-    url: /guides/
-  - title: Reference
-    url: /reference/
-  - title: Examples
-    url: /examples/
+  skin: dark # or light, auto
+  show_excerpts: true
 
 # Footer
 footer:

docs/index.md

@@ -1,61 +1,56 @@
 ---
 layout: default
 title: SpecFact CLI Documentation
-description: Everything you need to know about using SpecFact CLI
+description: Brownfield-first CLI for reverse engineering legacy Python code into specs with runtime contract enforcement
 ---
 
-> **Everything you need to know about using SpecFact CLI**
+# SpecFact CLI Documentation
+
+**Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts**
+
+SpecFact CLI helps you modernize legacy codebases by automatically extracting specifications from existing code and enforcing them at runtime to prevent regressions.
 
 ---
 
-## 📚 Documentation
+## 🚀 Quick Start
 
 ### New to SpecFact CLI?
 
 **Primary Use Case**: Modernizing legacy Python codebases
 
-Start here:
-
-1. **[Getting Started](getting-started/README.md)** - Install and run your first command
-2. **[Modernizing Legacy Code?](guides/brownfield-engineer.md)** ⭐ **PRIMARY** - Brownfield-first guide
-3. **[The Brownfield Journey](guides/brownfield-journey.md)** ⭐ - Complete modernization workflow
-4. **[Use Cases](guides/use-cases.md)** - See real-world examples
-5. **[Command Reference](reference/commands.md)** - Learn all available commands
+1. **[Installation](getting-started/installation.md)** - Get started in 60 seconds
+2. **[First Steps](getting-started/first-steps.md)** - Run your first command
+3. **[Modernizing Legacy Code](guides/brownfield-engineer.md)** ⭐ **PRIMARY** - Brownfield-first guide
+4. **[The Brownfield Journey](guides/brownfield-journey.md)** ⭐ - Complete modernization workflow
 
 ### Using GitHub Spec-Kit?
 
-**Secondary Use Case**: SpecFact CLI complements Spec-Kit by adding automated enforcement to Spec-Kit's interactive authoring:
+**Secondary Use Case**: Add automated enforcement to your Spec-Kit projects
 
-- **[The Journey: From Spec-Kit to SpecFact](guides/speckit-journey.md)** - Add automated enforcement to your Spec-Kit projects
+- **[From Spec-Kit to SpecFact](guides/speckit-journey.md)** - Add enforcement to Spec-Kit projects
 - **[Spec-Kit Comparison](guides/speckit-comparison.md)** - Understand when to use each tool
 
+## 📚 Documentation
+
 ### Guides
 
+- **[Use Cases](guides/use-cases.md)** - Real-world scenarios and workflows
 - **[IDE Integration](guides/ide-integration.md)** - Set up slash commands in your IDE
 - **[CoPilot Mode](guides/copilot-mode.md)** - Using `--mode copilot` on CLI
-- **[Use Cases](guides/use-cases.md)** - Real-world scenarios
+- **[Troubleshooting](guides/troubleshooting.md)** - Common issues and solutions
 - **[Competitive Analysis](guides/competitive-analysis.md)** - How SpecFact compares
 
-### Reference Documentation
+### Reference
 
 - **[Command Reference](reference/commands.md)** - Complete command documentation
 - **[Architecture](reference/architecture.md)** - Technical design and principles
 - **[Operational Modes](reference/modes.md)** - CI/CD vs CoPilot modes
 - **[Directory Structure](reference/directory-structure.md)** - Project structure
 
----
-
-## 🚀 Quick Links
-
-### Common Tasks
+### Examples
 
-- **[Install SpecFact CLI](getting-started/installation.md)**
-- **[Modernize Legacy Code](guides/brownfield-engineer.md)** ⭐ **PRIMARY** - Reverse engineer existing code into specs
-- **[The Brownfield Journey](guides/brownfield-journey.md)** ⭐ - Complete modernization workflow
-- **[Set Up IDE Integration](guides/ide-integration.md)** - Initialize slash commands in your IDE
-- **[Analyze existing code](guides/use-cases.md#use-case-1-brownfield-code-modernization)** ⭐ **PRIMARY**
-- **[Add enforcement to Spec-Kit projects](guides/use-cases.md#use-case-2-github-spec-kit-migration)** - Secondary use case
-- **[Start a new project](guides/use-cases.md#use-case-3-greenfield-spec-first-development)** - Alternative workflow
+- **[Brownfield Examples](examples/)** - Real-world modernization examples
+- **[Quick Examples](examples/quick-examples.md)** - Code snippets and patterns
 
 ---