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

.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

@@ -329,7 +329,7 @@ jobs:
         run: |
           PUBLISHED="${{ steps.publish.outputs.published }}"
           VERSION="${{ steps.publish.outputs.version }}"
-          
+
           {
             echo "## PyPI Publication Summary"
             echo "| Parameter | Value |"
@@ -343,4 +343,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