feat: Batch update support for plan review and updates (v0.7.0) (#28)

* Build: Include resources in sdist and wheel builds

Co-authored-by: dominikus.nold <[email protected]>

* feat: Code2Spec Strategic Plan Phase 0 implementation (v0.6.9) (#26)

* feat: Add JSON/YAML support for plan bundles (#27)

* feat: add batch update support for plan review and updates (v0.7.0)

- Add --batch-updates option to plan update-feature command
- Add --batch-updates option to plan update-story command
- Add --list-findings option to plan review command with structured output
- Refactor review function to reduce complexity
- Add comprehensive e2e tests for batch updates
- Update documentation and prompts to prefer batch updates
- Update version to 0.7.0

* fix: remove whitespace from blank lines and apply formatting

* docs: align all documentation with CLI-first, integration-focused positioning

- Updated all examples and guides with CLI-first messaging
- Added Integration Showcases references throughout documentation
- Emphasized integration diversity (VS Code, Cursor, GitHub Actions, pre-commit)
- Updated brownfield showcase examples with integration workflow sections
- Updated platform-frontend CMS to link to Integration Showcases README
- Reviewed and aligned all brownfield documentation for CLI-first approach
- Updated version to 0.7.1

Files updated:
- All docs/examples/ files (6 files)
- All docs/guides/ files (6 files)
- docs/reference/directory-structure.md
- platform-frontend/iac/scripts/payload-content-helper.js
- Version files: pyproject.toml, setup.py, src/__init__.py, src/specfact_cli/__init__.py
- CHANGELOG.md with comprehensive 0.7.1 entry

* fix: resolve type checking errors in constitution_evidence_extractor

- Fixed basedpyright warnings for repo_path.exists() in contract decorators
- Added isinstance() type guard to properly narrow Path | None types
- Updated Example 3 validation status to FULLY VALIDATED (CI/CD workflow verified in production)
- Updated documentation to reflect Example 3 is validated in specfact-cli repository CI/CD

Fixes type checking errors reported in GitHub Actions workflow:
- constitution_evidence_extractor.py:65:53 - Type of "exists" is unknown
- Fixed in all three methods: extract_article_vii_evidence, extract_article_viii_evidence, extract_article_ix_evidence

Example 3 Status Update:
- Changed from "COMMANDS VERIFIED" to "FULLY VALIDATED"
- Validated in production CI/CD (specfact-cli PR #28)
- Workflow successfully runs specfact repro and blocks PRs when validation fails

* Fix typecheck error

* Fix all type check errors

* Fix type annotations

---------

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

Author: 3 people

.cursor/rules/session_startup_instructions.mdc

@@ -21,3 +21,25 @@ alwaysApply: true
 1.2. `CLAUDE.md`: Check for any session-specific goals or instructions (applies to Claude CLI only).
 2. `docs/README.md` to get the latest project status and priorities and see which plan is referenced as being worked on: Understand the current development phase and tasks based on the mentioned plan in the README.md file.
 3. Outline your understanding of the current development phase and tasks based on the mentioned plan in the README.md file, before proceeding with any work. Ask the user for confirmation before proceeding.
+
+## Documentation and Planning Guidelines
+
+**CRITICAL**: When working with planning and documentation:
+
+- **Work directly with major artifacts**: Update strategic plans, implementation plans, and analysis documents directly. Do NOT create plans for plans, tracking documents for tracking documents, or status artifacts for status artifacts.
+- **Update existing artifacts**: Add status annotations (✅ Complete, ⏳ In Progress, 🟡 Pending) directly to existing plan documents rather than creating separate status files.
+- **Consolidate, don't multiply**: Only create new documentation artifacts when they add clear, unique value that cannot be captured in existing artifacts.
+- **Performance metrics**: Record timing and performance data directly in implementation status documents, not in separate performance tracking files.
+- **Test results**: Include test results and validation outcomes in the relevant implementation status or quality analysis documents.
+
+**Examples of what NOT to do**:
+
+- ❌ Creating `PHASE0_TRACKING.md` when `CODE2SPEC_STRATEGIC_PLAN.md` already exists
+- ❌ Creating `STEP1_1_TEST_RESULTS.md` when `PHASE1_IMPLEMENTATION_STATUS.md` can be updated
+- ❌ Creating `PERFORMANCE_METRICS.md` when performance data can go in implementation status
+
+**Examples of what TO do**:
+
+- ✅ Update `CODE2SPEC_STRATEGIC_PLAN.md` with status annotations (✅ Complete, ⏳ Next)
+- ✅ Add test results and performance metrics to `PHASE1_IMPLEMENTATION_STATUS.md`
+- ✅ Update `QUALITY_GAP_ANALYSIS.md` with measurement results and progress

.cursor/rules/spec-fact-cli-rules.mdc

@@ -111,8 +111,9 @@ hatch test --cover -v tests/unit/common/test_logger_setup.py
 
 1. **Analyze Impact**: Understand system-wide effects before changes
 2. **Run Tests**: `hatch run smart-test` (≥80% coverage required)
-3. **Update Documentation**: Keep docs/ current with changes
-4. **Version Control**: Update CHANGELOG.md, sync versions in pyproject.toml/setup.py
+3. **Update Documentation**: Keep docs/ current with changes. **IMPORTANT** DO NOT create internal docs that should not be visible to end users in the specfact-cli repo folder. Instead use the respective internal repository for such documentation.
+4. **Version Control**: Update CHANGELOG.md
+5. Sync versions in across `pyproject.toml`, `setup.py`, `src/__init__.py`, `src/specfact_cli/__init__py`
 
 ### **Strict Testing Requirements (NO EXCEPTIONS)**
 

.cursorrules

@@ -22,6 +22,7 @@
 - **Contract-first**: All public APIs must have `@icontract` decorators and `@beartype` type checking
 - **CLI focus**: Commands should follow typer patterns with rich console output
 - **Data validation**: Use Pydantic models for all data structures
+- **Documentation and Planning**: Work directly with major artifacts (strategic plans, implementation plans, etc.). Do NOT create plans for plans, tracking documents for tracking documents, or status artifacts for status artifacts. Only create new documentation artifacts when they add clear value and are not redundant with existing artifacts. Update existing artifacts with status annotations rather than creating separate status files.
 - Always finish each output listing which rulesets have been applied in your implementation and which AI (LLM) provider and model (including the version) you are using in your actual request for clarity. Ensure the model version is accurate and reflects what is currently running.
 
 <available_instructions>

.github/workflows/cleanup-branches.yml

@@ -4,8 +4,8 @@ name: Cleanup Merged Branches
 
 on:
   schedule:
-    - cron: '0 0 * * 0'  # Weekly on Sunday at midnight UTC
-  workflow_dispatch:  # Allow manual trigger
+    - cron: "0 0 * * 0" # Weekly on Sunday at midnight UTC
+  workflow_dispatch: # Allow manual trigger
 
 jobs:
   cleanup:
@@ -27,7 +27,7 @@ jobs:
         run: |
           # Get list of merged feature branches (excluding main)
           MERGED_BRANCHES=$(git branch -r --merged origin/main | grep 'origin/feature/' | sed 's|origin/||' | tr -d ' ')
-          
+
           if [ -z "$MERGED_BRANCHES" ]; then
             echo "No merged feature branches to delete."
           else
@@ -44,4 +44,3 @@ jobs:
         run: |
           echo "✅ Cleanup complete"
           echo "Merged feature branches have been deleted from remote."
-

.github/workflows/github-pages.yml

@@ -5,20 +5,20 @@ on:
     branches:
       - main
     paths:
-      - 'docs/**'
-      - '.github/workflows/github-pages.yml'
-      - '_config.yml'
-      - 'docs/Gemfile'
-      - 'docs/index.md'
-      - 'docs/assets/**'
-      - 'LICENSE.md'
-      - 'TRADEMARKS.md'
+      - "docs/**"
+      - ".github/workflows/github-pages.yml"
+      - "_config.yml"
+      - "docs/Gemfile"
+      - "docs/index.md"
+      - "docs/assets/**"
+      - "LICENSE.md"
+      - "TRADEMARKS.md"
   workflow_dispatch:
     inputs:
       branch:
-        description: 'Branch to deploy (defaults to main)'
+        description: "Branch to deploy (defaults to main)"
         required: false
-        default: 'main'
+        default: "main"
 
 permissions:
   contents: read
@@ -43,7 +43,7 @@ jobs:
       - name: Setup Ruby (for Jekyll)
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.2'
+          ruby-version: "3.2"
           bundler-cache: false
           working-directory: ./docs
 
@@ -88,4 +88,3 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
-

.github/workflows/pr-orchestrator.yml

@@ -219,7 +219,8 @@ jobs:
       - name: Run type checking
         run: |
           echo "🔍 Running basedpyright type checking..."
-          hatch run type-check || echo "⚠️ Type checking incomplete"
+          # Fail on type errors (severity 8) to enforce type safety in CI/CD
+          hatch run type-check
 
   linting:
     name: Linting (ruff, pylint)
@@ -329,7 +330,7 @@ jobs:
         run: |
           PUBLISHED="${{ steps.publish.outputs.published }}"
           VERSION="${{ steps.publish.outputs.version }}"
-          
+
           {
             echo "## PyPI Publication Summary"
             echo "| Parameter | Value |"
@@ -343,4 +344,3 @@ jobs:
               echo "| Status | ⏭️ Skipped (version not newer) |"
             fi
           } >> "$GITHUB_STEP_SUMMARY"
-

.github/workflows/pre-merge-check.yml

@@ -27,13 +27,13 @@ jobs:
           # Patterns match .gitignore: /test_*.py, /debug_*.py, /trigger_*.py, /temp_*.py
           # These are files at the root level, not in subdirectories
           CHANGED_FILES=$(git diff origin/main...HEAD --name-only)
-          
+
           # Check for temporary Python files at root (not in tests/ or any subdirectory)
           TEMP_FILES=$(echo "$CHANGED_FILES" | grep -E "^(temp_|debug_|trigger_|test_).*\.py$" | grep -v "^tests/" | grep -v "/" || true)
-          
+
           # Also check for analysis artifacts at root
           ARTIFACT_FILES=$(echo "$CHANGED_FILES" | grep -E "^(functional_coverage|migration_analysis|messaging_migration_plan)\.json$" | grep -v "/" || true)
-          
+
           if [ -n "$TEMP_FILES" ] || [ -n "$ARTIFACT_FILES" ]; then
             echo "❌ Temporary files detected in PR:"
             [ -n "$TEMP_FILES" ] && echo "$TEMP_FILES"
@@ -50,7 +50,7 @@ jobs:
         run: |
           # Check for WIP commits in PR
           WIP_COMMITS=$(git log origin/main..HEAD --oneline | grep -i "wip\|todo\|fixme\|xxx" || true)
-          
+
           if [ -n "$WIP_COMMITS" ]; then
             echo "⚠️ WIP commits detected (may be intentional):"
             echo "$WIP_COMMITS"
@@ -64,12 +64,11 @@ jobs:
         run: |
           # Check for files larger than 1MB
           LARGE_FILES=$(git diff origin/main...HEAD --name-only | xargs -I {} find {} -size +1M 2>/dev/null || true)
-          
+
           if [ -n "$LARGE_FILES" ]; then
             echo "⚠️ Large files detected:"
             echo "$LARGE_FILES"
             echo "::warning::Large files detected. Consider using Git LFS."
           else
             echo "✅ No large files detected"
           fi
-

.github/workflows/specfact.yml

@@ -138,4 +138,3 @@ jobs:
         run: |
           echo "❌ Validation failed. Exiting with error code."
           exit 1
-

.gitignore

@@ -116,4 +116,5 @@ reports/
 .cursor/mcp.json
 
 # Jekyll bundle
-vendor/
+vendor/
+_site/

AGENTS.md

@@ -80,7 +80,7 @@
 - **Contract-first workflow**: Before pushing, run `hatch run format`, `hatch run lint`, and `hatch run contract-test`
 - PRs should link to CLI-First Strategy docs, describe contract impacts, and include tests
 - Attach contract validation notes and screenshots/logs when behavior changes
-- **Version Updates**: When updating the version in `pyproject.toml`, ensure it's newer than the latest PyPI version. The CI/CD pipeline will automatically publish to PyPI after successful merge to `main` only if the version is newer.
+- **Version Updates**: When updating the version in `pyproject.toml`, ensure it's newer than the latest PyPI version. The CI/CD pipeline will automatically publish to PyPI after successful merge to `main` only if the version is newer. Sync versions across `pyproject.toml`, `setup.py`, `src/__init__.py`, `src/specfact_cli/__init__py`
 
 ## CLI Command Development Notes
 
@@ -206,7 +206,7 @@ console.print("[bold red]✗[/bold red] Validation failed")
 - Package name: `specfact-cli`
 - CLI command: `specfact`
 - PyPI distribution: `pip install specfact-cli`
-- uvx usage: `uvx --from specfact-cli specfact <command>`
+- uvx usage: `uvx specfact-cli@latest <command>` (recommended) or `uvx --from specfact-cli specfact <command>`
 - Container: `docker run ghcr.io/nold-ai/specfact-cli:latest`
 
 ## Success Criteria