diff --git a/CHANGELOG.md b/CHANGELOG.md index 09e5ddf..8198350 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,69 @@ All notable changes to this project will be documented in this file. --- +## [0.23.0] - 2026-01-07 + +### Added (0.23.0) + +- **Import Command Performance Optimizations**: Major performance improvements for large codebases + - **Pre-computed Caches**: AST parsing and file hashes are pre-computed once before parallel processing (5-15x faster) + - **Function Mapping Cache**: Function names are extracted once per file and cached for reuse + - **Optimized for Large Codebases**: Handles 3000+ features efficiently (6-15 minutes vs 90+ minutes previously) + - **Progress Reporting**: Real-time progress bars for feature analysis, source linking, and contract extraction + - **Early Save Checkpoint**: Features are saved immediately after initial analysis to prevent data loss on interruption + - **Feature Validation**: Automatic validation of existing features when resuming imports + - Detects orphaned features (all source files missing) + - Identifies invalid features (some files missing or structure issues) + - Reports validation results with actionable tips + - **Re-validation Flag**: `--revalidate-features` flag to force re-analysis even if files haven't changed + - Useful when analysis logic improves or confidence threshold changes + - Forces full codebase analysis regardless of incremental change detection + +### Changed (0.23.0) + +- **Import Command Performance**: Source file linking is now 5-15x faster for large codebases + - Pre-computes all AST parsing before parallel processing + - Caches file hashes to avoid repeated computation + - Optimized matching logic with pre-computed feature title words +- **Import Command Progress**: Enhanced progress reporting with detailed status messages + - Shows feature count, themes, and stories during analysis + - Real-time progress bars for source file linking + - Clear checkpoint messages when features are saved + - **Enhanced Analysis Setup**: Added spinner progress for file discovery (`repo.rglob("*.py")`), filtering, and hash collection phases + - Eliminates 30-60 second silent wait periods during file discovery + - Shows real-time status: "Preparing enhanced analysis..." → "Discovering Python files..." → "Filtering X files..." → "Ready to analyze X files" + - **Contract Loading**: Added progress bar for parallel YAML contract loading + - Shows "Loading X existing contract(s)..." with completion count + - Provides visibility during potentially slow contract file I/O operations + - **Enrichment Context Operations**: Added spinner progress for hash comparison, context building, and file writing + - Shows progress during hash comparison (reading existing file, building temp context) + - Shows progress during context building (iterating through features and contracts) + - Shows progress during markdown conversion and file writing + - **Incremental Change Detection**: Improved progress feedback with completion status message + - **Changed File Collection**: Added status message during file path collection + +### Documentation (0.23.0) + +- **Import Features Guide**: New comprehensive guide `docs/guides/import-features.md` + - Progress reporting details + - Feature validation explanation + - Early save checkpoint benefits + - Performance optimization details + - Re-validation flag usage + - Best practices for large codebases + - Troubleshooting tips +- **Command Reference**: Updated `docs/reference/commands.md` with new `--revalidate-features` flag +- **Quick Examples**: Updated `docs/examples/quick-examples.md` with new import features +- **README**: Updated timing information and checkpoint details + +### Fixed (0.23.0) + +- **Linting Errors**: Fixed unused `progress_columns` variable warnings in enrichment context functions + - Prefixed unused variables with underscore (`_progress_columns`) to indicate intentional non-usage + - All linting checks now pass without errors + +--- + ## [0.22.1] - 2026-01-03 ### Added (0.22.1) @@ -1993,25 +2056,6 @@ This patch release fixes the critical design issue identified during OSS validat --- -## [Unreleased] - -### Added - -- **Structured JSON/YAML Controls** - - New global `specfact --input-format/--output-format` options propagate preferred serialization across commands - - `specfact plan init` and `specfact import from-code` now expose `--output-format` overrides for per-command control - - `PlanGenerator` and `ReportGenerator` can emit JSON or YAML, and `validate_plan_bundle` / `FSMValidator` load either automatically - - Added regression tests covering JSON plan generation and validation to protect CI workflows - -### Changed - -- **CLI + Docs** - - Default plan-path helpers/search now detect both `.bundle.yaml` and `.bundle.json` - - Repository/prompt docs updated to describe the new format flags and reference `.bundle.` placeholders for slash-commands - - `SpecFactStructure` utilities now emit enriched/brownfield filenames preserving the original format so Copilot/CI stay in sync - ---- - ## [0.6.9] ### Added (0.6.9) @@ -2023,6 +2067,12 @@ This patch release fixes the critical design issue identified during OSS validat - Automatic detection of schema version mismatches and missing summary metadata - Migration path: 1.0 → 1.1 (adds summary metadata) +- **Structured JSON/YAML Controls** + - New global `specfact --input-format/--output-format` options propagate preferred serialization across commands + - `specfact plan init` and `specfact import from-code` now expose `--output-format` overrides for per-command control + - `PlanGenerator` and `ReportGenerator` can emit JSON or YAML, and `validate_plan_bundle` / `FSMValidator` load either automatically + - Added regression tests covering JSON plan generation and validation to protect CI workflows + - **Summary Metadata for Performance** - Plan bundles now include summary metadata (`metadata.summary`) for fast access - Summary includes: `features_count`, `stories_count`, `themes_count`, `releases_count`, `content_hash`, `computed_at` @@ -2051,6 +2101,11 @@ This patch release fixes the critical design issue identified during OSS validat - Early filtering: when `--last N` is used, only processes N+10 most recent files - Performance improved from 6.5s to 3.6s (44% faster) for typical workloads +- **CLI + Docs** + - Default plan-path helpers/search now detect both `.bundle.yaml` and `.bundle.json` + - Repository/prompt docs updated to describe the new format flags and reference `.bundle.` placeholders for slash-commands + - `SpecFactStructure` utilities now emit enriched/brownfield filenames preserving the original format so Copilot/CI stay in sync + --- ## [0.6.8] - 2025-11-20 diff --git a/README.md b/README.md index 45d6854..031152b 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,11 @@ specfact init --ide cursor --install-deps specfact import from-code my-project --repo . ``` -**⏱️ Timing:** Analysis typically takes **10-15 minutes** for typical repositories (e.g., `specfact-cli` itself with several hundred features & contracts). Smaller codebases may complete in 2-5 minutes. The analysis performs AST parsing, Semgrep pattern detection, and Specmatic integration. +**⏱️ Timing:** Analysis typically takes **10-15 minutes** for typical repositories (e.g., `specfact-cli` itself with several hundred features & contracts). Smaller codebases may complete in 2-5 minutes. Large codebases (3000+ features) may take 15-30 minutes, but progress reporting shows real-time status. The analysis performs AST parsing, Semgrep pattern detection, and Specmatic integration. + +**💾 Checkpointing:** Features are saved immediately after initial analysis, so you can safely interrupt and resume the import process without losing progress. + +**⚡ Performance:** Optimized for large codebases with pre-computed AST parsing and file hashes (5-15x faster than previous versions). **That's it!** SpecFact will extract features and stories from your code, find missing tests and contracts, and generate a plan bundle you can enforce. diff --git a/_site_local/LICENSE.md b/_site_local/LICENSE.md new file mode 100644 index 0000000..dd8dba5 --- /dev/null +++ b/_site_local/LICENSE.md @@ -0,0 +1,202 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (which shall not include Communications that are clearly marked or + otherwise designated in writing by the copyright owner as "Not a Work"). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is clearly marked or otherwise designated + in writing by the copyright owner as "Not a Contribution". + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2025 Nold AI (Owner: Dominikus Nold) + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/_site_local/README.md b/_site_local/README.md new file mode 100644 index 0000000..ba58b30 --- /dev/null +++ b/_site_local/README.md @@ -0,0 +1,236 @@ +# SpecFact CLI Documentation + +> **Everything you need to know about using SpecFact CLI** + +--- + +## Why SpecFact? + +### **Built for Real-World Agile Teams** + +SpecFact isn't just a technical tool—it's designed for **real-world agile/scrum teams** with role-based workflows: + +- 👤 **Product Owners** → Work with backlog, DoR checklists, prioritization, dependencies, and sprint planning +- 🏗️ **Architects** → Work with technical constraints, protocols, contracts, architectural decisions, and risk assessments +- 💻 **Developers** → Work with implementation tasks, code mappings, test scenarios, and Definition of Done criteria + +**Each role works in their own Markdown files** (no YAML editing), and SpecFact syncs everything together automatically. Perfect for teams using agile/scrum practices with clear role separation. + +👉 **[Agile/Scrum Workflows Guide](guides/agile-scrum-workflows.md)** ⭐ **START HERE** - Complete guide to persona-based team collaboration + +--- + +### **Love GitHub Spec-Kit or OpenSpec? SpecFact Adds What's Missing** + +**Use together:** Keep using Spec-Kit for new features, OpenSpec for change tracking, add SpecFact for legacy code modernization. + +**If you've tried GitHub Spec-Kit or OpenSpec**, you know they're great for documenting new features and tracking changes. SpecFact adds what's missing for legacy code modernization: + +👉 **[OpenSpec Journey Guide](guides/openspec-journey.md)** 🆕 ⭐ - Complete integration guide with DevOps export, visual workflows, and brownfield modernization examples + +- ✅ **Runtime contract enforcement** → Spec-Kit/OpenSpec generate docs; SpecFact prevents regressions with executable contracts +- ✅ **Brownfield-first** → Spec-Kit/OpenSpec excel at new features; SpecFact understands existing code +- ✅ **Formal verification** → Spec-Kit/OpenSpec use LLM suggestions; SpecFact uses mathematical proof (CrossHair) +- ✅ **Team collaboration** → Spec-Kit is single-user focused; SpecFact supports persona-based workflows for agile teams +- ✅ **DevOps integration** → Bridge adapters sync change proposals to GitHub Issues, ADO, Linear, Jira +- ✅ **GitHub Actions integration** → Works seamlessly with your existing GitHub workflows + +**Perfect together:** + +- ✅ **Spec-Kit** for new features → Fast spec generation with Copilot +- ✅ **OpenSpec** for change tracking → Specification anchoring and delta tracking +- ✅ **SpecFact** for legacy code → Runtime enforcement prevents regressions +- ✅ **Bridge adapters** → Sync between all tools automatically +- ✅ **Team workflows** → SpecFact adds persona-based collaboration for agile/scrum teams + +**Bottom line:** Use Spec-Kit for documenting new features. Use OpenSpec for change tracking. Use SpecFact for modernizing legacy code safely and enabling team collaboration. Use all three together for the best of all worlds. + +👉 **[See detailed comparison](guides/speckit-comparison.md)** | **[Journey from Spec-Kit](guides/speckit-journey.md)** | **[OpenSpec Journey](guides/openspec-journey.md)** 🆕 | **[Integrations Overview](guides/integrations-overview.md)** 🆕 | **[Bridge Adapters](reference/commands.md#sync-bridge)** + +--- + +## 🎯 Find Your Path + +### New to SpecFact? + +**Primary Goal**: Analyze legacy Python → find gaps → enforce contracts + +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. **[See It In Action](examples/dogfooding-specfact-cli.md)** - Real example (< 10 seconds) +5. **[Use Cases](guides/use-cases.md)** - Common scenarios + +**Time**: < 10 minutes | **Result**: Running your first brownfield analysis + +--- + +### Using AI IDEs? (Cursor, Copilot, Claude) 🆕 + +**Primary Goal**: Let SpecFact find gaps, use your AI IDE to fix them + +```bash +# 1. Run brownfield analysis and validation +specfact import from-code my-project --repo . +specfact repro --verbose + +# 2. Generate AI-ready prompt for a specific gap +specfact generate fix-prompt GAP-001 --bundle my-project + +# 3. Copy to AI IDE → AI generates fix → Validate with SpecFact +specfact enforce sdd --bundle my-project +``` + +**Why this approach?** + +- ✅ **You control the AI** - Use your preferred AI model +- ✅ **SpecFact validates** - Ensure AI-generated code meets contracts +- ✅ **No lock-in** - Works with any AI IDE + +👉 **[Command Reference - Generate Commands](reference/commands.md#generate---generate-artifacts)** - `fix-prompt` and `test-prompt` commands + +--- + +### Working with an Agile/Scrum Team? + +**Primary Goal**: Enable team collaboration with role-based workflows + +1. **[Agile/Scrum Workflows](guides/agile-scrum-workflows.md)** ⭐ **START HERE** - Persona-based team collaboration +2. **[Command Reference - Project Commands](reference/commands.md#project---project-bundle-management)** - `project export` and `project import` commands +3. **[Persona Workflows](guides/agile-scrum-workflows.md#persona-based-workflows)** - How Product Owners, Architects, and Developers work together +4. **[Definition of Ready](guides/agile-scrum-workflows.md#definition-of-ready-dor)** - DoR validation and sprint planning + +**Time**: 15-30 minutes | **Result**: Understanding how your team can collaborate with SpecFact + +--- + +### Love GitHub Spec-Kit or OpenSpec? + +**Why SpecFact?** Keep using Spec-Kit for new features, OpenSpec for change tracking, add SpecFact for legacy code modernization. + +**Use together:** + +- ✅ **Spec-Kit** for new features → Fast spec generation with Copilot +- ✅ **OpenSpec** for change tracking → Specification anchoring and delta tracking +- ✅ **SpecFact** for legacy code → Runtime enforcement prevents regressions +- ✅ **Bridge adapters** → Sync between all tools automatically +- ✅ **GitHub Actions** → SpecFact integrates with your existing GitHub workflows + +1. **[Tutorial: Using SpecFact with OpenSpec or Spec-Kit](getting-started/tutorial-openspec-speckit.md)** ⭐ **START HERE** - Complete beginner-friendly step-by-step tutorial +2. **[How SpecFact Compares to Spec-Kit](guides/speckit-comparison.md)** - See what SpecFact adds +3. **[The Journey: From Spec-Kit to SpecFact](guides/speckit-journey.md)** - Add enforcement to Spec-Kit projects +4. **[The Journey: OpenSpec + SpecFact Integration](guides/openspec-journey.md)** 🆕 - Complete OpenSpec integration guide with DevOps export (✅) and bridge adapter (✅) +5. **[DevOps Adapter Integration](guides/devops-adapter-integration.md)** - GitHub Issues and backlog tracking +6. **[Bridge Adapters](reference/commands.md#sync-bridge)** - OpenSpec and DevOps integration +7. **[Migration Use Case](guides/use-cases.md#use-case-2-github-spec-kit-migration)** - Step-by-step +8. **[Bidirectional Sync](guides/use-cases.md#use-case-2-github-spec-kit-migration)** - Keep both tools in sync + +**Time**: 15-30 minutes | **Result**: Understand how SpecFact complements Spec-Kit and OpenSpec for legacy code modernization + +--- + +### Using SpecFact Daily? + +**Goal**: Use SpecFact effectively in your workflow + +1. **[Command Chains Reference](guides/command-chains.md)** ⭐ **NEW** - Complete workflows and command sequences +2. **[Common Tasks Index](guides/common-tasks.md)** ⭐ **NEW** - Quick "How do I X?" reference +3. **[Command Reference](reference/commands.md)** - All commands with examples +4. **[Use Cases](guides/use-cases.md)** - Real-world scenarios +5. **[IDE Integration](guides/ide-integration.md)** - Set up slash commands +6. **[CoPilot Mode](guides/copilot-mode.md)** - Enhanced prompts + +**Time**: 30-60 minutes | **Result**: Master daily workflows + +--- + +### Contributing to SpecFact? + +**Goal**: Understand internals and contribute + +1. **[Architecture](reference/architecture.md)** - Technical design +2. **[Development Setup](getting-started/installation.md#development-setup)** - Local setup +3. **[Testing Procedures](technical/testing.md)** - How we test +4. **[Technical Deep Dives](technical/README.md)** - Implementation details + +**Time**: 2-4 hours | **Result**: Ready to contribute + +--- + +## 📚 Documentation Sections + +### Getting Started + +- [Installation](getting-started/installation.md) - All installation options +- [Enhanced Analysis Dependencies](installation/enhanced-analysis-dependencies.md) - Optional dependencies for graph-based analysis +- [First Steps](getting-started/first-steps.md) - Step-by-step first commands + +### User Guides + +#### Primary Use Case: Brownfield Modernization ⭐ + +- [Brownfield Engineer Guide](guides/brownfield-engineer.md) ⭐ **PRIMARY** - Complete modernization guide +- [The Brownfield Journey](guides/brownfield-journey.md) ⭐ **PRIMARY** - Step-by-step workflow +- [Brownfield ROI](guides/brownfield-roi.md) ⭐ - Calculate savings +- [Use Cases](guides/use-cases.md) ⭐ - Real-world scenarios (brownfield primary) + +#### Secondary Use Case: Spec-Kit & OpenSpec Integration + +- [Spec-Kit Journey](guides/speckit-journey.md) - Add enforcement to Spec-Kit projects +- [Spec-Kit Comparison](guides/speckit-comparison.md) - Understand when to use each tool +- [OpenSpec Journey](guides/openspec-journey.md) 🆕 - OpenSpec integration with SpecFact (DevOps export ✅, bridge adapter ⏳) +- [DevOps Adapter Integration](guides/devops-adapter-integration.md) - GitHub Issues, backlog tracking, and progress comments +- [Bridge Adapters](reference/commands.md#sync-bridge) - OpenSpec and DevOps integration + +#### Team Collaboration & Agile/Scrum + +- [Agile/Scrum Workflows](guides/agile-scrum-workflows.md) ⭐ **NEW** - Persona-based team collaboration with Product Owners, Architects, and Developers +- [Persona Workflows](guides/agile-scrum-workflows.md#persona-based-workflows) - Role-based workflows for agile teams +- [Definition of Ready](guides/agile-scrum-workflows.md#definition-of-ready-dor) - DoR validation and sprint planning +- [Dependency Management](guides/agile-scrum-workflows.md#dependency-management) - Track story and feature dependencies +- [Conflict Resolution](guides/agile-scrum-workflows.md#conflict-resolution) - Persona-aware merge conflict resolution + +#### General Guides + +- [UX Features](guides/ux-features.md) - Progressive disclosure, context detection, intelligent suggestions, templates +- [Workflows](guides/workflows.md) - Common daily workflows +- [IDE Integration](guides/ide-integration.md) - Slash commands +- [CoPilot Mode](guides/copilot-mode.md) - Enhanced prompts +- [Troubleshooting](guides/troubleshooting.md) - Common issues and solutions + +### Reference + +- [Commands](reference/commands.md) - Complete command reference +- [Architecture](reference/architecture.md) - Technical design +- [Operational Modes](reference/modes.md) - CI/CD vs CoPilot modes +- [Telemetry](reference/telemetry.md) - Privacy-first, opt-in analytics +- [Feature Keys](reference/feature-keys.md) - Key normalization +- [Directory Structure](reference/directory-structure.md) - Project layout + +### Examples + +- [Dogfooding Example](examples/dogfooding-specfact-cli.md) - Main example +- [Quick Examples](examples/quick-examples.md) - Code snippets + +### Technical + +- [Code2Spec Analysis](technical/code2spec-analysis-logic.md) - AI-first approach +- [Testing Procedures](technical/testing.md) - Testing guidelines + +--- + +## 🆘 Getting Help + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) + +--- + +**Happy building!** 🚀 + +--- + +Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold) + +**Trademarks**: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](../TRADEMARKS.md) for more information. diff --git a/_site_local/TRADEMARKS.md b/_site_local/TRADEMARKS.md new file mode 100644 index 0000000..03d6262 --- /dev/null +++ b/_site_local/TRADEMARKS.md @@ -0,0 +1,58 @@ +# Trademarks + +## NOLD AI Trademark + +**NOLD AI** (also referred to as **NOLDAI**) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). + +All rights to the NOLD AI trademark are reserved. + +## Third-Party Trademarks + +This project may reference or use trademarks, service marks, and trade names of other companies and organizations. These trademarks are the property of their respective owners. + +### AI and IDE Tools + +- **Claude** and **Claude Code** are trademarks of Anthropic PBC +- **Gemini** is a trademark of Google LLC +- **Cursor** is a trademark of Anysphere, Inc. +- **GitHub Copilot** is a trademark of GitHub, Inc. (Microsoft Corporation) +- **VS Code** (Visual Studio Code) is a trademark of Microsoft Corporation +- **Windsurf** is a trademark of Codeium, Inc. +- **Qwen Code** is a trademark of Alibaba Group +- **opencode** is a trademark of its respective owner +- **Codex CLI** is a trademark of OpenAI, L.P. +- **Amazon Q Developer** is a trademark of Amazon.com, Inc. +- **Amp** is a trademark of its respective owner +- **CodeBuddy CLI** is a trademark of its respective owner +- **Kilo Code** is a trademark of its respective owner +- **Auggie CLI** is a trademark of its respective owner +- **Roo Code** is a trademark of its respective owner + +### Development Tools and Platforms + +- **GitHub** is a trademark of GitHub, Inc. (Microsoft Corporation) +- **Spec-Kit** is a trademark of its respective owner +- **Python** is a trademark of the Python Software Foundation +- **Semgrep** is a trademark of Semgrep, Inc. +- **PyPI** (Python Package Index) is a trademark of the Python Software Foundation + +### Standards and Protocols + +- **OpenAPI** is a trademark of The Linux Foundation +- **JSON Schema** is a trademark of its respective owner + +## Trademark Usage + +When referencing trademarks in this project: + +1. **Always use proper capitalization** as shown above +2. **Include trademark notices** where trademarks are prominently displayed +3. **Respect trademark rights** - do not use trademarks in a way that suggests endorsement or affiliation without permission + +## Disclaimer + +The mention of third-party trademarks in this project does not imply endorsement, sponsorship, or affiliation with the trademark owners. All product names, logos, and brands are property of their respective owners. + +--- + +**Last Updated**: 2025-11-05 diff --git a/_site_local/ai-ide-workflow/index.html b/_site_local/ai-ide-workflow/index.html new file mode 100644 index 0000000..60ce867 --- /dev/null +++ b/_site_local/ai-ide-workflow/index.html @@ -0,0 +1,532 @@ + + + + + + + +AI IDE Workflow Guide | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

AI IDE Workflow Guide

+ +
+

Complete guide to using SpecFact CLI with AI IDEs (Cursor, VS Code + Copilot, Claude Code, etc.)

+
+ +
+ +

Overview

+ +

SpecFact CLI integrates with AI-assisted IDEs through slash commands that enable a seamless workflow: SpecFact finds gaps → AI IDE fixes them → SpecFact validates. This guide explains the complete workflow from setup to validation.

+ +

Key Benefits:

+ +
    +
  • ✅ You control the AI - Use your preferred AI model
    • +
  • ✅ SpecFact validates - Ensure AI-generated code meets contracts
    • +
  • ✅ No lock-in - Works with any AI IDE
    • +
  • ✅ CLI-first - Works offline, no account required
    • +
+ +
+ +

Setup Process

+ +

Step 1: Initialize IDE Integration

+ +

Run the init --ide command in your repository:

+ +
# Auto-detect IDE
+specfact init
+
+# Or specify IDE explicitly
+specfact init --ide cursor
+specfact init --ide vscode
+specfact init --ide copilot
+
+# Install required packages for contract enhancement
+specfact init --ide cursor --install-deps
+
+ +

What it does:

+ +
    +
  1. Detects your IDE (or uses --ide flag)
    2. +
  2. Copies prompt templates from resources/prompts/ to IDE-specific location
    3. +
  3. Creates/updates IDE settings if needed
    4. +
  4. Makes slash commands available in your IDE
    5. +
  5. Optionally installs required packages (beartype, icontract, crosshair-tool, pytest)
    6. +
+ +

Related: IDE Integration Guide - Complete setup instructions

+ +
+ +

Available Slash Commands

+ +

Once initialized, the following slash commands are available in your IDE:

+ +

Core Workflow Commands

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Slash CommandPurposeEquivalent CLI Command
/specfact.01-importImport from codebasespecfact import from-code
/specfact.02-planPlan managementspecfact plan init/add-feature/add-story
/specfact.03-reviewReview planspecfact plan review
/specfact.04-sddCreate SDD manifestspecfact enforce sdd
/specfact.05-enforceSDD enforcementspecfact enforce sdd
/specfact.06-syncSync operationsspecfact sync bridge
/specfact.07-contractsContract managementspecfact generate contracts-prompt
+ +

Advanced Commands

+ + + + + + + + + + + + + + + + + + + + + +
Slash CommandPurposeEquivalent CLI Command
/specfact.compareCompare plansspecfact plan compare
/specfact.validateValidation suitespecfact repro
+ +

Related: IDE Integration - Available Slash Commands

+ +
+ +

Complete Workflow: Prompt Generation → AI IDE → Validation Loop

+ +

Workflow Overview

+ +
graph TD
+    A[SpecFact Analysis] -->|Find Gaps| B[Generate Prompt]
+    B -->|Copy to IDE| C[AI IDE]
+    C -->|Generate Fix| D[Apply Changes]
+    D -->|SpecFact Validate| E[Validation]
+    E -->|Pass| F[Complete]
+    E -->|Fail| B
+
+ +

Step-by-Step Workflow

+ +

1. Run SpecFact Analysis

+ +
# Import from codebase
+specfact import from-code --bundle my-project --repo .
+
+# Run validation to find gaps
+specfact repro --verbose
+
+ +

2. Generate AI-Ready Prompt

+ +
# Generate fix prompt for a specific gap
+specfact generate fix-prompt GAP-001 --bundle my-project
+
+# Or generate contract prompt
+specfact generate contracts-prompt --bundle my-project --feature FEATURE-001
+
+# Or generate test prompt
+specfact generate test-prompt src/auth/login.py --bundle my-project
+
+ +

3. Use AI IDE to Apply Fixes

+ +

In Cursor / VS Code / Copilot:

+ +
    +
  1. Open the generated prompt file
    2. +
  2. Copy the prompt content
    3. +
  3. Paste into AI IDE chat
    4. +
  4. AI generates the fix
    5. +
  5. Review and apply the changes
    6. +
+ +

Example:

+ +
# After generating prompt
+cat .specfact/prompts/fix-prompt-GAP-001.md
+
+# Copy content to AI IDE chat
+# AI generates fix
+# Apply changes to code
+
+ +

4. Validate with SpecFact

+ +
# Check contract coverage
+specfact contract coverage --bundle my-project
+
+# Run validation
+specfact repro --verbose
+
+# Enforce SDD compliance
+specfact enforce sdd --bundle my-project
+
+ +

5. Iterate if Needed

+ +

If validation fails, return to step 2 and generate a new prompt for the remaining issues.

+ +
+ +

Integration with Command Chains

+ +

The AI IDE workflow integrates with several command chains:

+ +

AI-Assisted Code Enhancement Chain

+ +

Workflow: generate contracts-prompt → [AI IDE] → contracts-apply → contract coverage → repro

+ +

Related: AI-Assisted Code Enhancement Chain

+ +

Test Generation from Specifications Chain

+ +

Workflow: generate test-prompt → [AI IDE] → spec generate-tests → pytest

+ +

Related: Test Generation from Specifications Chain

+ +

Gap Discovery & Fixing Chain

+ +

Workflow: repro --verbose → generate fix-prompt → [AI IDE] → enforce sdd

+ +

Related: Gap Discovery & Fixing Chain

+ +
+ +

Example: Complete AI IDE Workflow

+ +

Scenario: Add Contracts to Existing Code

+ +
# 1. Analyze codebase
+specfact import from-code --bundle legacy-api --repo .
+
+# 2. Find gaps
+specfact repro --verbose
+
+# 3. Generate contract prompt
+specfact generate contracts-prompt --bundle legacy-api --feature FEATURE-001
+
+# 4. [In AI IDE] Use slash command or paste prompt
+# /specfact.generate-contracts-prompt legacy-api FEATURE-001
+# AI generates contracts
+# Apply contracts to code
+
+# 5. Validate
+specfact contract coverage --bundle legacy-api
+specfact repro --verbose
+specfact enforce sdd --bundle legacy-api
+
+ +
+ +

Supported IDEs

+ +

SpecFact CLI supports the following AI IDEs:

+ +
    +
  • ✅ Cursor - .cursor/commands/
    • +
  • ✅ VS Code / GitHub Copilot - .github/prompts/ + .vscode/settings.json
    • +
  • ✅ Claude Code - .claude/commands/
    • +
  • ✅ Gemini CLI - .gemini/commands/
    • +
  • ✅ Qwen Code - .qwen/commands/
    • +
  • ✅ opencode - .opencode/command/
    • +
  • ✅ Windsurf - .windsurf/workflows/
    • +
  • ✅ Kilo Code - .kilocode/workflows/
    • +
  • ✅ Auggie - .augment/commands/
    • +
  • ✅ Roo Code - .roo/commands/
    • +
  • ✅ CodeBuddy - .codebuddy/commands/
    • +
  • ✅ Amp - .agents/commands/
    • +
  • ✅ Amazon Q Developer - .amazonq/prompts/
    • +
+ +

Related: IDE Integration - Supported IDEs

+ +
+ +

Troubleshooting

+ +

Slash Commands Not Showing

+ +

Issue: Slash commands don’t appear in IDE

+ +

Solution:

+ +
# Re-initialize with force
+specfact init --ide cursor --force
+
+ +

Related: IDE Integration - Troubleshooting

+ +
+ +

AI-Generated Code Fails Validation

+ +

Issue: AI-generated code doesn’t pass SpecFact validation

+ +

Solution:

+ +
    +
  1. Review validation errors
    2. +
  2. Generate a new prompt with more specific requirements
    3. +
  3. Re-run AI generation
    4. +
  4. Validate again
    5. +
+ +
+ +

See Also

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/architecture/index.html b/_site_local/architecture/index.html new file mode 100644 index 0000000..9e1b6a9 --- /dev/null +++ b/_site_local/architecture/index.html @@ -0,0 +1,1210 @@ + + + + + + + +Architecture | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Architecture

+ +

Technical architecture and design principles of SpecFact CLI.

+ +

Quick Overview

+ +

For Users: SpecFact CLI is a brownfield-first tool that reverse engineers legacy Python code into documented specs, then enforces them as runtime contracts. It works in two modes: CI/CD mode (fast, automated) and CoPilot mode (interactive, AI-enhanced). Primary use case: Analyze existing codebases. Secondary use case: Add enforcement to Spec-Kit projects.

+ +

For Contributors: SpecFact CLI implements a contract-driven development framework through three layers: Specification (plans and protocols), Contract (runtime validation), and Enforcement (quality gates). The architecture supports dual-mode operation (CI/CD and CoPilot) with agent-based routing for complex operations.

+ +
+ +

Overview

+ +

SpecFact CLI implements a contract-driven development framework through three core layers:

+ +
    +
  1. Specification Layer - Plan bundles and protocol definitions
    2. +
  2. Contract Layer - Runtime contracts, static checks, and property tests
    3. +
  3. Enforcement Layer - No-escape gates with budgets and staged enforcement
    4. +
+ + + + + +

Operational Modes

+ +

SpecFact CLI supports two operational modes for different use cases:

+ +

Mode 1: CI/CD Automation (Default)

+ +

Best for:

+ +
    +
  • Clean-code repositories
    • +
  • Self-explaining codebases
    • +
  • Lower complexity projects
    • +
  • Automated CI/CD pipelines
    • +
+ +

Characteristics:

+ +
    +
  • Fast, deterministic execution (< 10s typical)
    • +
  • No AI copilot dependency
    • +
  • Direct command execution
    • +
  • Structured JSON/Markdown output
    • +
  • Enhanced Analysis: AST + Semgrep hybrid pattern detection (API endpoints, models, CRUD, code quality)
    • +
  • Optimized Bundle Size: 81% reduction (18MB → 3.4MB, 5.3x smaller) via test pattern extraction to OpenAPI contracts
    • +
  • Interruptible: All parallel operations support Ctrl+C for immediate cancellation
    • +
+ +

Usage:

+ +
# Auto-detected (default)
+specfact import from-code my-project --repo .
+
+# Explicit CI/CD mode
+specfact --mode cicd import from-code my-project --repo .
+
+ +

Mode 2: CoPilot-Enabled

+ +

Best for:

+ +
    +
  • Brownfield repositories
    • +
  • High complexity codebases
    • +
  • Mixed code quality
    • +
  • Interactive development with AI assistants
    • +
+ +

Characteristics:

+ +
    +
  • Enhanced prompts for better analysis
    • +
  • IDE integration via prompt templates (slash commands)
    • +
  • Agent mode routing for complex operations
    • +
  • Interactive assistance
    • +
+ +

Usage:

+ +
# Auto-detected (if CoPilot available)
+specfact import from-code my-project --repo .
+
+# Explicit CoPilot mode
+specfact --mode copilot import from-code my-project --repo .
+
+# IDE integration (slash commands)
+# First, initialize: specfact init --ide cursor
+# Then use in IDE chat:
+/specfact.01-import legacy-api --repo . --confidence 0.7
+/specfact.02-plan init legacy-api
+/specfact.06-sync --adapter speckit --repo . --bidirectional
+
+ +

Mode Detection

+ +

Mode is automatically detected based on:

+ +
    +
  1. Explicit --mode flag (highest priority)
    2. +
  2. CoPilot API availability (environment/IDE detection)
    3. +
  3. IDE integration (VS Code/Cursor with CoPilot enabled)
    4. +
  4. Default to CI/CD mode (fallback)
    5. +
+ +
+ +

Agent Modes

+ +

Agent modes provide enhanced prompts and routing for CoPilot-enabled operations:

+ +

Available Agent Modes

+ +
    +
  • analyze agent mode: Brownfield analysis with code understanding
    • +
  • plan agent mode: Plan management with business logic understanding
    • +
  • sync agent mode: Bidirectional sync with conflict resolution
    • +
+ +

Agent Mode Routing

+ +

Each command uses specialized agent mode routing:

+ +
# Analyze agent mode
+/specfact.01-import legacy-api --repo . --confidence 0.7
+# → Enhanced prompts for code understanding
+# → Context injection (current file, selection, workspace)
+# → Interactive assistance for complex codebases
+
+# Plan agent mode
+/specfact.02-plan init legacy-api
+# → Guided wizard mode
+# → Natural language prompts
+# → Context-aware feature extraction
+
+# Sync agent mode
+/specfact.06-sync --adapter speckit --repo . --bidirectional
+# → Automatic source detection via bridge adapter
+# → Conflict resolution assistance
+# → Change explanation and preview
+
+ +
+ +

Sync Operation

+ +

SpecFact CLI supports bidirectional synchronization for consistent change management:

+ +

Bridge-Based Sync (Adapter-Agnostic)

+ +

Bidirectional synchronization between external tools (e.g., Spec-Kit, OpenSpec) and SpecFact via configurable bridge:

+ +
# Spec-Kit bidirectional sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# OpenSpec read-only sync (Phase 1)
+specfact sync bridge --adapter openspec --mode read-only --bundle <bundle-name> --repo .
+
+# OpenSpec cross-repository sync
+specfact sync bridge --adapter openspec --mode read-only --bundle <bundle-name> --repo . --external-base-path ../specfact-cli-internal
+
+# Continuous watch mode
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+ +

What it syncs:

+ +
    +
  • specs/[###-feature-name]/spec.md, plan.md, tasks.md ↔ .specfact/projects/<bundle-name>/ aspect files
    • +
  • .specify/memory/constitution.md ↔ SpecFact business context
    • +
  • specs/[###-feature-name]/research.md, data-model.md, quickstart.md ↔ SpecFact supporting artifacts
    • +
  • specs/[###-feature-name]/contracts/*.yaml ↔ SpecFact protocol definitions
    • +
  • Automatic conflict resolution with priority rules
    • +
+ +

Bridge Architecture: The sync layer uses a configurable bridge (.specfact/config/bridge.yaml) that maps SpecFact logical concepts to physical tool artifacts, making it adapter-agnostic and extensible for future tool integrations (OpenSpec, Linear, Jira, Notion, etc.). The architecture uses a plugin-based adapter registry pattern - all adapters are registered in AdapterRegistry and accessed via AdapterRegistry.get_adapter(), eliminating hard-coded adapter checks in core components like BridgeProbe and BridgeSync.

+ +

Repository Sync

+ +

Sync code changes to SpecFact artifacts:

+ +
# One-time sync
+specfact sync repository --repo . --target .specfact
+
+# Continuous watch mode
+specfact sync repository --repo . --watch --interval 5
+
+ +

What it tracks:

+ +
    +
  • Code changes → Plan artifact updates
    • +
  • Deviations from manual plans
    • +
  • Feature/story extraction from code
    • +
+ +

Contract Layers

+ +
graph TD
+    A[Specification] --> B[Runtime Contracts]
+    B --> C[Static Checks]
+    B --> D[Property Tests]
+    B --> E[Runtime Sentinels]
+    C --> F[No-Escape Gate]
+    D --> F
+    E --> F
+    F --> G[PR Approved/Blocked]
+
+ +

1. Specification Layer

+ +

Project Bundle (.specfact/projects/<bundle-name>/ - modular structure with multiple aspect files):

+ +
version: "1.0"
+idea:
+  title: "SpecFact CLI Tool"
+  narrative: "Enable contract-driven development"
+product:
+  themes:
+    - "Developer Experience"
+  releases:
+    - name: "v0.1"
+      objectives: ["Import", "Analyze", "Enforce"]
+features:
+  - key: FEATURE-001
+    title: "Spec-Kit Import"
+    outcomes:
+      - "Zero manual conversion"
+    stories:
+      - key: STORY-001
+        title: "Parse Spec-Kit artifacts"
+        acceptance:
+          - "Schema validation passes"
+
+ +

Protocol (.specfact/protocols/workflow.protocol.yaml):

+ +
states:
+  - INIT
+  - PLAN
+  - REQUIREMENTS
+  - ARCHITECTURE
+  - CODE
+  - REVIEW
+  - DEPLOY
+start: INIT
+transitions:
+  - from_state: INIT
+    on_event: start_planning
+    to_state: PLAN
+  - from_state: PLAN
+    on_event: approve_plan
+    to_state: REQUIREMENTS
+    guard: plan_quality_gate_passes
+
+ +

2. Contract Layer

+ +

Runtime Contracts (icontract)

+ +
from icontract import require, ensure
+from beartype import beartype
+
+@require(lambda plan: plan.version == "1.0")
+@ensure(lambda result: len(result.features) > 0)
+@beartype
+def validate_plan(plan: PlanBundle) -> ValidationResult:
+    """Validate plan bundle against contracts."""
+    return ValidationResult(valid=True)
+
+ +

Static Checks (Semgrep)

+ +
# .semgrep/async-anti-patterns.yaml
+rules:
+  - id: async-without-await
+    pattern: |
+      async def $FUNC(...):
+        ...
+    pattern-not: |
+      async def $FUNC(...):
+        ...
+        await ...
+    message: "Async function without await"
+    severity: ERROR
+
+ +

Property Tests (Hypothesis)

+ +
from hypothesis import given
+from hypothesis.strategies import text
+
+@given(text())
+def test_plan_key_format(feature_key: str):
+    """All feature keys must match FEATURE-\d+ format."""
+    if feature_key.startswith("FEATURE-"):
+        assert feature_key[8:].isdigit()
+
+ +

Runtime Sentinels

+ +
import asyncio
+from typing import Optional
+
+class EventLoopMonitor:
+    """Monitor event loop health."""
+    
+    def __init__(self, lag_threshold_ms: float = 100.0):
+        self.lag_threshold_ms = lag_threshold_ms
+    
+    async def check_lag(self) -> Optional[float]:
+        """Return lag in ms if above threshold."""
+        start = asyncio.get_event_loop().time()
+        await asyncio.sleep(0)
+        lag_ms = (asyncio.get_event_loop().time() - start) * 1000
+        return lag_ms if lag_ms > self.lag_threshold_ms else None
+
+ +

3. Enforcement Layer

+ +

No-Escape Gate

+ +
# .github/workflows/specfact-gate.yml
+name: No-Escape Gate
+on: [pull_request]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: SpecFact Validation
+        run: |
+          specfact repro --budget 120 --verbose
+          if [ $? -ne 0 ]; then
+            echo "::error::Contract violations detected"
+            exit 1
+          fi
+
+ +

Staged Enforcement

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
StageDescriptionViolations
ShadowLog only, never blockAll logged, none block
WarnWarn on medium+, block highHIGH blocks, MEDIUM warns
BlockBlock all medium+MEDIUM+ blocks
+ +

Budget-Based Execution

+ +
from typing import Optional
+import time
+
+class BudgetedValidator:
+    """Validator with time budget."""
+    
+    def __init__(self, budget_seconds: int = 120):
+        self.budget_seconds = budget_seconds
+        self.start_time: Optional[float] = None
+    
+    def start(self):
+        """Start budget timer."""
+        self.start_time = time.time()
+    
+    def check_budget(self) -> bool:
+        """Return True if budget exceeded."""
+        if self.start_time is None:
+            return False
+        elapsed = time.time() - self.start_time
+        return elapsed > self.budget_seconds
+
+ +

Data Models

+ +

PlanBundle

+ +
from pydantic import BaseModel, Field
+from typing import List
+
+class Idea(BaseModel):
+    """High-level idea."""
+    title: str
+    narrative: str
+
+class Story(BaseModel):
+    """User story."""
+    key: str = Field(pattern=r"^STORY-\d+$")
+    title: str
+    acceptance: List[str]
+
+class Feature(BaseModel):
+    """Feature with stories."""
+    key: str = Field(pattern=r"^FEATURE-\d+$")
+    title: str
+    outcomes: List[str]
+    stories: List[Story]
+
+class PlanBundle(BaseModel):
+    """Complete plan bundle."""
+    version: str = "1.0"
+    idea: Idea
+    features: List[Feature]
+
+ +

ProtocolSpec

+ +
from pydantic import BaseModel
+from typing import List, Optional
+
+class Transition(BaseModel):
+    """State machine transition."""
+    from_state: str
+    on_event: str
+    to_state: str
+    guard: Optional[str] = None
+
+class ProtocolSpec(BaseModel):
+    """FSM protocol specification."""
+    states: List[str]
+    start: str
+    transitions: List[Transition]
+
+ +

Deviation

+ +
from enum import Enum
+from pydantic import BaseModel
+
+class DeviationSeverity(str, Enum):
+    """Severity levels."""
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+    CRITICAL = "CRITICAL"
+
+class Deviation(BaseModel):
+    """Detected deviation."""
+    type: str
+    severity: DeviationSeverity
+    description: str
+    location: str
+    suggestion: Optional[str] = None
+
+ +

Change Tracking Models (v1.1 Schema)

+ +

Introduced in v0.21.1: Tool-agnostic change tracking models for delta spec tracking and change proposals. These models support OpenSpec and other tools (Linear, Jira, etc.) that track changes to specifications.

+ +
from enum import Enum
+from pydantic import BaseModel
+from typing import Optional, Dict, List, Any
+
+class ChangeType(str, Enum):
+    """Change type for delta specs (tool-agnostic)."""
+    ADDED = "added"
+    MODIFIED = "modified"
+    REMOVED = "removed"
+
+class FeatureDelta(BaseModel):
+    """Delta tracking for a feature change (tool-agnostic)."""
+    feature_key: str
+    change_type: ChangeType
+    original_feature: Optional[Feature] = None  # For MODIFIED/REMOVED
+    proposed_feature: Optional[Feature] = None  # For ADDED/MODIFIED
+    change_rationale: Optional[str] = None
+    change_date: Optional[str] = None  # ISO timestamp
+    validation_status: Optional[str] = None  # pending, passed, failed
+    validation_results: Optional[Dict[str, Any]] = None
+    source_tracking: Optional[SourceTracking] = None  # Tool-specific metadata
+
+class ChangeProposal(BaseModel):
+    """Change proposal (tool-agnostic, used by OpenSpec and other tools)."""
+    name: str  # Change identifier (e.g., 'add-user-feedback')
+    title: str
+    description: str  # What: Description of the change
+    rationale: str  # Why: Rationale and business value
+    timeline: Optional[str] = None  # When: Timeline and dependencies
+    owner: Optional[str] = None  # Who: Owner and stakeholders
+    stakeholders: List[str] = []
+    dependencies: List[str] = []
+    status: str = "proposed"  # proposed, in-progress, applied, archived
+    created_at: str  # ISO timestamp
+    applied_at: Optional[str] = None
+    archived_at: Optional[str] = None
+    source_tracking: Optional[SourceTracking] = None  # Tool-specific metadata
+
+class ChangeTracking(BaseModel):
+    """Change tracking for a bundle (tool-agnostic capability)."""
+    proposals: Dict[str, ChangeProposal] = {}  # change_name -> ChangeProposal
+    feature_deltas: Dict[str, List[FeatureDelta]] = {}  # change_name -> [FeatureDelta]
+
+class ChangeArchive(BaseModel):
+    """Archive entry for completed changes (tool-agnostic)."""
+    change_name: str
+    applied_at: str  # ISO timestamp
+    applied_by: Optional[str] = None
+    pr_number: Optional[str] = None
+    commit_hash: Optional[str] = None
+    feature_deltas: List[FeatureDelta] = []
+    validation_results: Optional[Dict[str, Any]] = None
+    source_tracking: Optional[SourceTracking] = None  # Tool-specific metadata
+
+ +

Key Design Principles:

+ +
    +
  • Tool-Agnostic: All tool-specific metadata stored in source_tracking, not in core models
    • +
  • Cross-Repository Support: Adapters can load change tracking from external repositories
    • +
  • Backward Compatible: All fields optional - v1.0 bundles work without modification
    • +
  • Validation Integration: Change proposals can include SpecFact validation results
    • +
+ +

Schema Versioning:

+ +
    +
  • v1.0: Original bundle format (no change tracking)
    • +
  • v1.1: Extended with optional change_tracking and change_archive fields
    • +
  • Automatic Detection: Bundle loader checks schema version and conditionally loads change tracking via adapters
    • +
+ +

Module Structure

+ +
src/specfact_cli/
+├── cli.py                 # Main CLI entry point
+├── commands/              # CLI command implementations
+│   ├── import_cmd.py     # Import from external formats
+│   ├── analyze.py        # Code analysis
+│   ├── plan.py           # Plan management
+│   ├── enforce.py        # Enforcement configuration
+│   ├── repro.py          # Reproducibility validation
+│   └── sync.py           # Sync operations (Spec-Kit, repository)
+├── modes/                 # Operational mode management
+│   ├── detector.py       # Mode detection logic
+│   └── router.py         # Command routing
+├── utils/                 # Utilities
+│   └── ide_setup.py      # IDE integration (template copying)
+├── agents/                # Agent mode implementations
+│   ├── base.py           # Agent mode base class
+│   ├── analyze_agent.py # Analyze agent mode
+│   ├── plan_agent.py    # Plan agent mode
+│   └── sync_agent.py    # Sync agent mode
+├── adapters/              # Bridge adapter implementations
+│   ├── base.py           # BridgeAdapter base interface
+│   ├── registry.py       # AdapterRegistry for plugin-based architecture
+│   ├── openspec.py       # OpenSpec adapter (read-only sync)
+│   └── speckit.py        # Spec-Kit adapter (bidirectional sync)
+├── sync/                  # Sync operation modules
+│   ├── bridge_sync.py    # Bridge-based bidirectional sync (adapter-agnostic)
+│   ├── bridge_probe.py   # Bridge detection and auto-generation
+│   ├── bridge_watch.py   # Bridge-based watch mode
+│   ├── repository_sync.py # Repository sync
+│   └── watcher.py        # Watch mode for continuous sync
+├── models/               # Pydantic data models
+│   ├── plan.py          # Plan bundle models (legacy compatibility)
+│   ├── project.py       # Project bundle models (modular structure)
+│   ├── change.py         # Change tracking models (v1.1 schema)
+│   ├── bridge.py        # Bridge configuration models
+│   ├── protocol.py      # Protocol FSM models
+│   └── deviation.py     # Deviation models
+├── validators/          # Schema validators
+│   ├── schema.py        # Schema validation
+│   ├── contract.py      # Contract validation
+│   └── fsm.py           # FSM validation
+├── generators/          # Code generators
+│   ├── protocol.py      # Protocol generator
+│   ├── plan.py          # Plan generator
+│   └── report.py        # Report generator
+├── utils/               # CLI utilities
+│   ├── console.py       # Rich console output
+│   ├── git.py           # Git operations
+│   └── yaml_utils.py    # YAML helpers
+├── analyzers/          # Code analysis engines
+│   ├── code_analyzer.py # AST+Semgrep hybrid analysis
+│   ├── graph_analyzer.py # Dependency graph analysis
+│   └── relationship_mapper.py # Relationship extraction
+└── common/              # Shared utilities
+    ├── logger_setup.py  # Logging infrastructure
+    ├── logging_utils.py # Logging helpers
+    ├── text_utils.py    # Text utilities
+    └── utils.py         # File/JSON utilities
+
+ +

Analysis Components

+ +

AST+Semgrep Hybrid Analysis

+ +

The CodeAnalyzer uses a hybrid approach combining AST parsing with Semgrep pattern detection:

+ +

AST Analysis (Core):

+ +
    +
  • Structural code analysis (classes, methods, imports)
    • +
  • Type hint extraction
    • +
  • Parallelized processing (2-4x speedup)
    • +
  • Interruptible with Ctrl+C (graceful cancellation)
    • +
+ +

Recent Improvements (2025-11-30):

+ +
    +
  • ✅ Bundle Size Optimization: 81% reduction (18MB → 3.4MB, 5.3x smaller) via test pattern extraction to OpenAPI contracts
    • +
  • ✅ Acceptance Criteria Limiting: 1-3 high-level items per story (detailed examples in contract files)
    • +
  • ✅ KeyboardInterrupt Handling: All parallel operations support immediate cancellation
    • +
  • ✅ Semgrep Detection Fix: Increased timeout from 1s to 5s for reliable detection
    • +
  • Async pattern detection
    • +
  • Theme detection from imports
    • +
+ +

Semgrep Pattern Detection (Enhancement):

+ +
    +
  • API Endpoint Detection: FastAPI, Flask, Express, Gin routes
    • +
  • Database Model Detection: SQLAlchemy, Django, Pydantic, TortoiseORM, Peewee
    • +
  • CRUD Operation Detection: Function naming patterns (create_, get_, update_, delete_)
    • +
  • Authentication Patterns: Auth decorators, permission checks
    • +
  • Code Quality Assessment: Anti-patterns, code smells, security vulnerabilities
    • +
  • Framework Patterns: Async/await, context managers, type hints, configuration
    • +
+ +

Plugin Status: The import command displays plugin status (AST Analysis, Semgrep Pattern Detection, Dependency Graph Analysis) showing which tools are enabled and used.

+ +

Benefits:

+ +
    +
  • Framework-aware feature detection
    • +
  • Enhanced confidence scores (AST + Semgrep evidence)
    • +
  • Code quality maturity assessment
    • +
  • Multi-language ready (TypeScript, JavaScript, Go patterns available)
    • +
+ +

Testing Strategy

+ +

Contract-First Testing

+ +

SpecFact CLI uses contracts as specifications:

+ +
    +
  1. Runtime Contracts - @icontract decorators on public APIs
    2. +
  2. Type Validation - @beartype for runtime type checking
    3. +
  3. Contract Exploration - CrossHair to discover counterexamples
    4. +
  4. Scenario Tests - Focus on business workflows
    5. +
+ +

Test Pyramid

+ +
         /\
+        /  \  E2E Tests (Scenario)
+       /____\
+      /      \  Integration Tests (Contract)
+     /________\
+    /          \  Unit Tests (Property)
+   /____________\
+
+ +

Running Tests

+ +
# Contract validation
+hatch run contract-test-contracts
+
+# Contract exploration (CrossHair)
+hatch run contract-test-exploration
+
+# Scenario tests
+hatch run contract-test-scenarios
+
+# E2E tests
+hatch run contract-test-e2e
+
+# Full test suite
+hatch run contract-test-full
+
+ +

Bridge Adapter Interface

+ +

Introduced in v0.21.1: The BridgeAdapter interface has been extended with change tracking methods to support OpenSpec and other tools that track specification changes.

+ +

Core Interface Methods

+ +

All adapters must implement these base methods:

+ +
from abc import ABC, abstractmethod
+from pathlib import Path
+from specfact_cli.models.bridge import BridgeConfig
+from specfact_cli.models.change import ChangeProposal, ChangeTracking
+
+class BridgeAdapter(ABC):
+    @abstractmethod
+    def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool:
+        """Detect if adapter applies to repository."""
+
+    @abstractmethod
+    def import_artifact(self, artifact_key: str, artifact_path: Path | dict, project_bundle: Any, bridge_config: BridgeConfig | None = None) -> None:
+        """Import artifact from tool format to SpecFact."""
+
+    @abstractmethod
+    def export_artifact(self, artifact_key: str, artifact_data: Any, bridge_config: BridgeConfig | None = None) -> Path | dict:
+        """Export artifact from SpecFact to tool format."""
+
+    @abstractmethod
+    def generate_bridge_config(self, repo_path: Path) -> BridgeConfig:
+        """Generate bridge configuration for adapter."""
+    
+    @abstractmethod
+    def get_capabilities(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> ToolCapabilities:
+        """Get adapter capabilities (sync modes, layout, etc.)."""
+
+ +

Change Tracking Methods (v0.21.1+)

+ +

Introduced in v0.21.1: Adapters that support change tracking must implement these additional methods:

+ +
@abstractmethod
+def load_change_tracking(
+    self, bundle_dir: Path, bridge_config: BridgeConfig | None = None
+) -> ChangeTracking | None:
+    """
+    Load change tracking from adapter-specific storage location.
+    
+    Args:
+        bundle_dir: Path to bundle directory (.specfact/projects/<bundle-name>/)
+        bridge_config: Bridge configuration (may contain external_base_path for cross-repo)
+    
+    Returns:
+        ChangeTracking instance or None if not available
+    """
+
+@abstractmethod
+def save_change_tracking(
+    self, bundle_dir: Path, change_tracking: ChangeTracking, bridge_config: BridgeConfig | None = None
+) -> None:
+    """
+    Save change tracking to adapter-specific storage location.
+    
+    Args:
+        bundle_dir: Path to bundle directory
+        change_tracking: ChangeTracking instance to save
+        bridge_config: Bridge configuration (may contain external_base_path for cross-repo)
+    """
+
+@abstractmethod
+def load_change_proposal(
+    self, bundle_dir: Path, change_name: str, bridge_config: BridgeConfig | None = None
+) -> ChangeProposal | None:
+    """
+    Load change proposal from adapter-specific storage location.
+    
+    Args:
+        bundle_dir: Path to bundle directory
+        change_name: Change identifier (e.g., 'add-user-feedback')
+        bridge_config: Bridge configuration (may contain external_base_path for cross-repo)
+    
+    Returns:
+        ChangeProposal instance or None if not found
+    """
+
+@abstractmethod
+def save_change_proposal(
+    self, bundle_dir: Path, proposal: ChangeProposal, bridge_config: BridgeConfig | None = None
+) -> None:
+    """
+    Save change proposal to adapter-specific storage location.
+    
+    Args:
+        bundle_dir: Path to bundle directory
+        proposal: ChangeProposal instance to save
+        bridge_config: Bridge configuration (may contain external_base_path for cross-repo)
+    """
+
+ +

Cross-Repository Support

+ +

Adapters must support loading change tracking from external repositories:

+ +
    +
  • external_base_path: If bridge_config.external_base_path is set, adapters should load change tracking from that location instead of bundle_dir
    • +
  • Tool-Specific Storage: Each adapter determines where change tracking is stored (e.g., OpenSpec uses openspec/changes/, Linear uses API)
    • +
  • Source Tracking: Tool-specific metadata (issue IDs, file paths, etc.) stored in source_tracking field
    • +
+ +

Implementation Examples

+ +

OpenSpec Adapter (v0.21.1+):

+ +

The OpenSpec adapter provides read-only sync (Phase 1) for importing OpenSpec specifications and change tracking:

+ +
class OpenSpecAdapter(BridgeAdapter):
+    def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool:
+        # Detects openspec/project.md or openspec/specs/ directory
+        base_path = bridge_config.external_base_path if bridge_config and bridge_config.external_base_path else repo_path
+        return (base_path / "openspec" / "project.md").exists() or (base_path / "openspec" / "specs").exists()
+    
+    def get_capabilities(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> ToolCapabilities:
+        # Returns OpenSpec-specific capabilities
+        return ToolCapabilities(tool="openspec", layout="openspec", specs_dir="openspec/specs")
+    
+    def load_change_tracking(self, bundle_dir: Path, bridge_config: BridgeConfig | None = None) -> ChangeTracking | None:
+        # Load from openspec/changes/ directory
+        base_path = bridge_config.external_base_path if bridge_config and bridge_config.external_base_path else bundle_dir.parent.parent.parent
+        changes_dir = base_path / "openspec" / "changes"
+        # Parse change proposals and feature deltas
+        return ChangeTracking(...)
+    
+    def import_artifact(self, artifact_key: str, artifact_path: Path, project_bundle: Any, bridge_config: BridgeConfig | None = None) -> None:
+        # Supports: specification, project_context, change_proposal, change_spec_delta
+        # Parses OpenSpec markdown and updates project bundle
+        pass
+
+ +

Key Features:

+
    +
  • Read-only sync (Phase 1): Import only, export methods raise NotImplementedError
    • +
  • Cross-repository support: Uses external_base_path for OpenSpec in different repositories
    • +
  • Change tracking: Loads change proposals and feature deltas from openspec/changes/
    • +
  • Source tracking: Stores OpenSpec paths in source_tracking.source_metadata
    • +
+ +

SpecKit Adapter (v0.22.0+):

+ +

The SpecKit adapter provides full bidirectional sync for Spec-Kit markdown artifacts:

+ +
class SpecKitAdapter(BridgeAdapter):
+    def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool:
+        # Detects .specify/ directory or specs/ directory (classic/modern layouts)
+        base_path = bridge_config.external_base_path if bridge_config and bridge_config.external_base_path else repo_path
+        return (base_path / ".specify").exists() or (base_path / "specs").exists() or (base_path / "docs" / "specs").exists()
+    
+    def get_capabilities(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> ToolCapabilities:
+        # Returns Spec-Kit-specific capabilities (bidirectional sync supported)
+        return ToolCapabilities(
+            tool="speckit",
+            layout="classic" or "modern",
+            specs_dir="specs" or "docs/specs",
+            supported_sync_modes=["bidirectional", "unidirectional"]
+        )
+    
+    def import_artifact(self, artifact_key: str, artifact_path: Path, project_bundle: Any, bridge_config: BridgeConfig | None = None) -> None:
+        # Supports: specification, plan, tasks, constitution
+        # Parses Spec-Kit markdown and updates project bundle
+        pass
+    
+    def export_artifact(self, artifact_key: str, artifact_data: Any, bridge_config: BridgeConfig | None = None) -> Path:
+        # Supports: specification, plan, tasks, constitution
+        # Exports SpecFact models to Spec-Kit markdown format
+        pass
+
+ +

Key Features:

+
    +
  • Bidirectional sync: Full import and export support for Spec-Kit artifacts
    • +
  • Classic and modern layouts: Supports both specs/ (classic) and docs/specs/ (modern) directory structures
    • +
  • Public helper methods: discover_features(), detect_changes(), detect_conflicts(), export_bundle() for advanced operations
    • +
  • Contract-first: All methods have @beartype, @require, and @ensure decorators for runtime validation
    • +
  • Adapter registry: Registered in AdapterRegistry for plugin-based architecture
    • +
+ +

GitHub Adapter (export-only):

+ +
class GitHubAdapter(BridgeAdapter):
+    def load_change_tracking(self, bundle_dir: Path, bridge_config: BridgeConfig | None = None) -> ChangeTracking | None:
+        # GitHub adapter is export-only (OpenSpec → GitHub Issues)
+        return None
+    
+    def save_change_tracking(self, bundle_dir: Path, change_tracking: ChangeTracking, bridge_config: BridgeConfig | None = None) -> None:
+        # Export change proposals to GitHub Issues
+        pass
+    
+    def export_artifact(self, artifact_key: str, artifact_data: Any, bridge_config: BridgeConfig | None = None) -> dict:
+        # Supports artifact keys: change_proposal, change_status, change_proposal_update, code_change_progress
+        if artifact_key == "code_change_progress":
+            # Add progress comment to existing GitHub issue based on code changes
+            return self._add_progress_comment(artifact_data, ...)
+
+ +

Schema Version Handling

+ +
    +
  • v1.0 Bundles: load_change_tracking() returns None (backward compatible)
    • +
  • v1.1 Bundles: Bundle loader calls load_change_tracking() via adapter if schema version is 1.1+
    • +
  • Automatic Detection: ProjectBundle.load_from_directory() checks schema version before loading change tracking
    • +
+ +

Dependencies

+ +

Core

+ +
    +
  • typer - CLI framework
    • +
  • pydantic - Data validation
    • +
  • rich - Terminal output
    • +
  • networkx - Graph analysis
    • +
  • ruamel.yaml - YAML processing
    • +
+ +

Validation

+ +
    +
  • icontract - Runtime contracts
    • +
  • beartype - Type checking
    • +
  • crosshair-tool - Contract exploration
    • +
  • hypothesis - Property-based testing
    • +
+ +

Development

+ +
    +
  • hatch - Build and environment management
    • +
  • basedpyright - Type checking
    • +
  • ruff - Linting
    • +
  • pytest - Test runner
    • +
+ +

See pyproject.toml for complete dependency list.

+ +

Design Principles

+ +
    +
  1. Contract-Driven - Contracts are specifications
    2. +
  2. Evidence-Based - Claims require reproducible evidence
    3. +
  3. Offline-First - No SaaS required for core functionality
    4. +
  4. Progressive Enhancement - Shadow → Warn → Block
    5. +
  5. Fast Feedback - < 90s CI overhead
    6. +
  6. Escape Hatches - Override mechanisms for emergencies
    7. +
  7. Quality-First - TDD with quality gates from day 1
    8. +
  8. Dual-Mode Operation - CI/CD automation or CoPilot-enabled assistance
    9. +
  9. Bidirectional Sync - Consistent change management across tools
    10. +
+ +

Performance Characteristics

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationTypical TimeBudget
Plan validation< 1s5s
Contract exploration10-30s60s
Full repro suite60-90s120s
Brownfield analysis2-5 min300s
+ +

Security Considerations

+ +
    +
  1. No external dependencies for core validation
    2. +
  2. Secure defaults - Shadow mode by default
    3. +
  3. No data exfiltration - Works offline
    4. +
  4. Contract provenance - SHA256 hashes in reports
    5. +
  5. Reproducible builds - Deterministic outputs
    6. +
+ +
+ +

See Commands for command reference and Technical Deep Dives for testing procedures.

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/assets/main.css b/_site_local/assets/main.css new file mode 100644 index 0000000..1c1ae15 --- /dev/null +++ b/_site_local/assets/main.css @@ -0,0 +1 @@ +body,h1,h2,h3,h4,h5,h6,p,blockquote,pre,hr,dl,dd,ol,ul,figure{margin:0;padding:0}body{font:400 16px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";color:#111;background-color:#fdfdfd;-webkit-text-size-adjust:100%;-webkit-font-feature-settings:"kern" 1;-moz-font-feature-settings:"kern" 1;-o-font-feature-settings:"kern" 1;font-feature-settings:"kern" 1;font-kerning:normal;display:flex;min-height:100vh;flex-direction:column}h1,h2,h3,h4,h5,h6,p,blockquote,pre,ul,ol,dl,figure,.highlight{margin-bottom:15px}main{display:block}img{max-width:100%;vertical-align:middle}figure>img{display:block}figcaption{font-size:14px}ul,ol{margin-left:30px}li>ul,li>ol{margin-bottom:0}h1,h2,h3,h4,h5,h6{font-weight:400}a{color:#2a7ae2;text-decoration:none}a:visited{color:#1756a9}a:hover{color:#111;text-decoration:underline}.social-media-list a:hover{text-decoration:none}.social-media-list a:hover .username{text-decoration:underline}blockquote{color:#828282;border-left:4px solid #e8e8e8;padding-left:15px;font-size:18px;letter-spacing:-1px;font-style:italic}blockquote>:last-child{margin-bottom:0}pre,code{font-size:15px;border:1px solid #e8e8e8;border-radius:3px;background-color:#eef}code{padding:1px 5px}pre{padding:8px 12px;overflow-x:auto}pre>code{border:0;padding-right:0;padding-left:0}.wrapper{max-width:-webkit-calc(800px - (30px * 2));max-width:calc(800px - 30px*2);margin-right:auto;margin-left:auto;padding-right:30px;padding-left:30px}@media screen and (max-width: 800px){.wrapper{max-width:-webkit-calc(800px - (30px));max-width:calc(800px - (30px));padding-right:15px;padding-left:15px}}.footer-col-wrapper:after,.wrapper:after{content:"";display:table;clear:both}.svg-icon{width:16px;height:16px;display:inline-block;fill:#828282;padding-right:5px;vertical-align:text-top}.social-media-list li+li{padding-top:5px}table{margin-bottom:30px;width:100%;text-align:left;color:#3f3f3f;border-collapse:collapse;border:1px solid #e8e8e8}table tr:nth-child(even){background-color:#f7f7f7}table th,table td{padding:9.999999999px 15px}table th{background-color:#f0f0f0;border:1px solid #dedede;border-bottom-color:#c9c9c9}table td{border:1px solid #e8e8e8}.site-header{border-top:5px solid #424242;border-bottom:1px solid #e8e8e8;min-height:55.95px;position:relative}.site-title{font-size:26px;font-weight:300;line-height:54px;letter-spacing:-1px;margin-bottom:0;float:left}.site-title,.site-title:visited{color:#424242}.site-nav{float:right;line-height:54px}.site-nav .nav-trigger{display:none}.site-nav .menu-icon{display:none}.site-nav .page-link{color:#111;line-height:1.5}.site-nav .page-link:not(:last-child){margin-right:20px}@media screen and (max-width: 600px){.site-nav{position:absolute;top:9px;right:15px;background-color:#fdfdfd;border:1px solid #e8e8e8;border-radius:5px;text-align:right}.site-nav label[for=nav-trigger]{display:block;float:right;width:36px;height:36px;z-index:2;cursor:pointer}.site-nav .menu-icon{display:block;float:right;width:36px;height:26px;line-height:0;padding-top:10px;text-align:center}.site-nav .menu-icon>svg{fill:#424242}.site-nav input~.trigger{clear:both;display:none}.site-nav input:checked~.trigger{display:block;padding-bottom:5px}.site-nav .page-link{display:block;margin-left:20px;padding:5px 10px}.site-nav .page-link:not(:last-child){margin-right:0}}.site-footer{border-top:1px solid #e8e8e8;padding:30px 0}.footer-heading{font-size:18px;margin-bottom:15px}.contact-list,.social-media-list{list-style:none;margin-left:0}.footer-col-wrapper{font-size:15px;color:#828282;margin-left:-15px}.footer-col{float:left;margin-bottom:15px;padding-left:15px}.footer-col-1{width:-webkit-calc(35% - (30px / 2));width:calc(35% - 30px/2)}.footer-col-2{width:-webkit-calc(20% - (30px / 2));width:calc(20% - 30px/2)}.footer-col-3{width:-webkit-calc(45% - (30px / 2));width:calc(45% - 30px/2)}@media screen and (max-width: 800px){.footer-col-1,.footer-col-2{width:-webkit-calc(50% - (30px / 2));width:calc(50% - 30px/2)}.footer-col-3{width:-webkit-calc(100% - (30px / 2));width:calc(100% - 30px/2)}}@media screen and (max-width: 600px){.footer-col{float:none;width:-webkit-calc(100% - (30px / 2));width:calc(100% - 30px/2)}}.page-content{padding:30px 0;flex:1}.page-heading{font-size:32px}.post-list-heading{font-size:28px}.post-list{margin-left:0;list-style:none}.post-list>li{margin-bottom:30px}.post-meta{font-size:14px;color:#828282}.post-link{display:block;font-size:24px}.post-header{margin-bottom:30px}.post-title{font-size:42px;letter-spacing:-1px;line-height:1}@media screen and (max-width: 800px){.post-title{font-size:36px}}.post-content{margin-bottom:30px}.post-content h2{font-size:32px}@media screen and (max-width: 800px){.post-content h2{font-size:28px}}.post-content h3{font-size:26px}@media screen and (max-width: 800px){.post-content h3{font-size:22px}}.post-content h4{font-size:20px}@media screen and (max-width: 800px){.post-content h4{font-size:18px}}.highlight{background:#fff}.highlighter-rouge .highlight{background:#eef}.highlight .c{color:#998;font-style:italic}.highlight .err{color:#a61717;background-color:#e3d2d2}.highlight .k{font-weight:bold}.highlight .o{font-weight:bold}.highlight .cm{color:#998;font-style:italic}.highlight .cp{color:#999;font-weight:bold}.highlight .c1{color:#998;font-style:italic}.highlight .cs{color:#999;font-weight:bold;font-style:italic}.highlight .gd{color:#000;background-color:#fdd}.highlight .gd .x{color:#000;background-color:#faa}.highlight .ge{font-style:italic}.highlight .gr{color:#a00}.highlight .gh{color:#999}.highlight .gi{color:#000;background-color:#dfd}.highlight .gi .x{color:#000;background-color:#afa}.highlight .go{color:#888}.highlight .gp{color:#555}.highlight .gs{font-weight:bold}.highlight .gu{color:#aaa}.highlight .gt{color:#a00}.highlight .kc{font-weight:bold}.highlight .kd{font-weight:bold}.highlight .kp{font-weight:bold}.highlight .kr{font-weight:bold}.highlight .kt{color:#458;font-weight:bold}.highlight .m{color:#099}.highlight .s{color:#d14}.highlight .na{color:teal}.highlight .nb{color:#0086b3}.highlight .nc{color:#458;font-weight:bold}.highlight .no{color:teal}.highlight .ni{color:purple}.highlight .ne{color:#900;font-weight:bold}.highlight .nf{color:#900;font-weight:bold}.highlight .nn{color:#555}.highlight .nt{color:navy}.highlight .nv{color:teal}.highlight .ow{font-weight:bold}.highlight .w{color:#bbb}.highlight .mf{color:#099}.highlight .mh{color:#099}.highlight .mi{color:#099}.highlight .mo{color:#099}.highlight .sb{color:#d14}.highlight .sc{color:#d14}.highlight .sd{color:#d14}.highlight .s2{color:#d14}.highlight .se{color:#d14}.highlight .sh{color:#d14}.highlight .si{color:#d14}.highlight .sx{color:#d14}.highlight .sr{color:#009926}.highlight .s1{color:#d14}.highlight .ss{color:#990073}.highlight .bp{color:#999}.highlight .vc{color:teal}.highlight .vg{color:teal}.highlight .vi{color:teal}.highlight .il{color:#099}:root{--primary-color: #64ffda;--primary-hover: #7affeb;--text-color: #ccd6f6;--text-light: #8892b0;--text-muted: #495670;--bg-color: #0a192f;--bg-light: #112240;--bg-alt: #1d2d50;--border-color: rgba(100, 255, 218, 0.1);--border-hover: rgba(100, 255, 218, 0.3);--code-bg: #1d2d50;--link-color: #64ffda;--link-hover: #7affeb}body{font-family:"Inter",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif !important;line-height:1.7 !important;color:var(--text-color) !important;background-color:var(--bg-color) !important;-webkit-font-smoothing:antialiased}.site-header{border-bottom:2px solid var(--border-color);background-color:var(--bg-light);padding:1rem 0}.site-header .site-title{font-size:1.5rem;font-weight:700;color:var(--primary-color);text-decoration:none}.site-header .site-title:hover{color:var(--primary-hover)}.site-header .site-nav .page-link{color:var(--text-color);font-weight:500;margin:0 .5rem;text-decoration:none;transition:color .2s}.site-header .site-nav .page-link:hover{color:var(--primary-color)}.page-content{padding:2rem 0;color:var(--text-color) !important;background-color:var(--bg-color) !important}.page-content,.page-content *{color:inherit}.docs-content{padding:2rem 0;color:var(--text-color) !important;background-color:var(--bg-color) !important}.docs-content h1{font-size:2.5rem;font-weight:800;margin-bottom:1rem;color:var(--text-color) !important;border-bottom:3px solid var(--primary-color);padding-bottom:.5rem}.docs-content h2{font-size:2rem;font-weight:700;margin-top:2rem;margin-bottom:1rem;color:var(--text-color) !important}.docs-content h3{font-size:1.5rem;font-weight:600;margin-top:1.5rem;margin-bottom:.75rem;color:var(--text-color) !important}.docs-content h4{font-size:1.25rem;font-weight:600;margin-top:1rem;margin-bottom:.5rem;color:var(--text-color) !important}.docs-content p{margin-bottom:1rem;color:var(--text-color) !important}.docs-content *{color:inherit}.docs-content a{color:var(--link-color);text-decoration:none;font-weight:500;transition:color .2s}.docs-content a:hover{color:var(--link-hover);text-decoration:underline}.docs-content ul,.docs-content ol{margin-bottom:1rem;padding-left:2rem;color:var(--text-color) !important}.docs-content ul li,.docs-content ol li{margin-bottom:.5rem;color:var(--text-color) !important}.docs-content ul li a,.docs-content ol li a{color:var(--link-color) !important}.docs-content ul li a:hover,.docs-content ol li a:hover{color:var(--link-hover) !important}.docs-content table{width:100%;border-collapse:collapse;margin:1.5rem 0;background-color:var(--bg-color) !important}.docs-content table th,.docs-content table td{padding:.75rem;border:1px solid var(--border-color);color:var(--text-color) !important}.docs-content table th{background-color:var(--bg-light) !important;font-weight:600;color:var(--text-color) !important}.docs-content table tr{background-color:var(--bg-color) !important}.docs-content table tr:nth-child(even){background-color:var(--bg-light) !important}.docs-content .highlighter-rouge{background-color:var(--code-bg) !important;border:1px solid var(--border-color);border-radius:.5rem;margin-bottom:1rem;font-family:"JetBrains Mono","Fira Code",monospace !important}.docs-content .highlighter-rouge .highlight{background-color:var(--code-bg) !important}.docs-content .highlighter-rouge .highlight pre{background-color:var(--code-bg) !important;border:none;border-radius:.5rem;padding:1rem;overflow-x:auto;margin:0;color:var(--text-color) !important}.docs-content .highlighter-rouge .highlight pre code{background-color:rgba(0,0,0,0) !important;padding:0;border:none;color:var(--text-color) !important;font-family:"JetBrains Mono","Fira Code",monospace !important}.docs-content pre{background-color:var(--code-bg) !important;border:1px solid var(--border-color);border-radius:.5rem;padding:1rem;overflow-x:auto;margin-bottom:1rem;color:var(--text-color) !important;font-family:"JetBrains Mono","Fira Code",monospace !important}.docs-content pre code{background-color:rgba(0,0,0,0) !important;padding:0;border:none;color:var(--text-color) !important;font-family:"JetBrains Mono","Fira Code",monospace !important}.docs-content code{background-color:var(--code-bg) !important;padding:.2rem .4rem;border-radius:.25rem;font-size:.9em;border:1px solid var(--border-color);color:var(--text-color) !important;font-family:"JetBrains Mono","Fira Code",monospace !important}.docs-content .highlight span{background-color:rgba(0,0,0,0) !important;color:var(--text-color) !important}.docs-content .highlight .c{color:#8892b0 !important}.docs-content .highlight .k{color:#ff6b9d !important}.docs-content .highlight .l{color:#64ffda !important}.docs-content .highlight .n{color:var(--text-color) !important}.docs-content .highlight .o{color:#ff6b9d !important}.docs-content .highlight .p{color:#ccd6f6 !important}.docs-content .highlight .cm{color:#8892b0 !important}.docs-content .highlight .cp{color:#8892b0 !important}.docs-content .highlight .c1{color:#8892b0 !important}.docs-content .highlight .cs{color:#8892b0 !important}.docs-content .highlight .gd{color:#ff6b9d !important}.docs-content .highlight .ge{font-style:italic !important}.docs-content .highlight .gr{color:#ff6b9d !important}.docs-content .highlight .gh{color:var(--text-color) !important;font-weight:bold !important}.docs-content .highlight .gi{color:#64ffda !important}.docs-content .highlight .go{color:#8892b0 !important}.docs-content .highlight .gp{color:#8892b0 !important}.docs-content .highlight .gs{font-weight:bold !important}.docs-content .highlight .gu{color:var(--text-color) !important;font-weight:bold !important}.docs-content .highlight .gt{color:#ff6b9d !important}.docs-content .highlight .kc{color:#64ffda !important}.docs-content .highlight .kd{color:#ff6b9d !important}.docs-content .highlight .kn{color:#ff6b9d !important}.docs-content .highlight .kp{color:#ff6b9d !important}.docs-content .highlight .kr{color:#ff6b9d !important}.docs-content .highlight .kt{color:#ff6b9d !important}.docs-content .highlight .ld{color:#64ffda !important}.docs-content .highlight .m{color:#64ffda !important}.docs-content .highlight .s{color:#a8e6cf !important}.docs-content .highlight .na{color:#64ffda !important}.docs-content .highlight .nb{color:#64ffda !important}.docs-content .highlight .nc{color:#c792ea !important}.docs-content .highlight .no{color:#64ffda !important}.docs-content .highlight .nd{color:#c792ea !important}.docs-content .highlight .ni{color:#c792ea !important}.docs-content .highlight .ne{color:#ff6b9d !important;font-weight:bold !important}.docs-content .highlight .nf{color:#c792ea !important}.docs-content .highlight .nl{color:#64ffda !important}.docs-content .highlight .nn{color:var(--text-color) !important}.docs-content .highlight .nx{color:var(--text-color) !important}.docs-content .highlight .py{color:var(--text-color) !important}.docs-content .highlight .nt{color:#64ffda !important}.docs-content .highlight .nv{color:#ffd93d !important}.docs-content .highlight .ow{color:#ff6b9d !important}.docs-content .highlight .w{color:#8892b0 !important}.docs-content .highlight .mf{color:#64ffda !important}.docs-content .highlight .mh{color:#64ffda !important}.docs-content .highlight .mi{color:#64ffda !important}.docs-content .highlight .mo{color:#64ffda !important}.docs-content .highlight .sb{color:#a8e6cf !important}.docs-content .highlight .sc{color:#a8e6cf !important}.docs-content .highlight .sd{color:#8892b0 !important}.docs-content .highlight .s2{color:#a8e6cf !important}.docs-content .highlight .se{color:#a8e6cf !important}.docs-content .highlight .sh{color:#a8e6cf !important}.docs-content .highlight .si{color:#a8e6cf !important}.docs-content .highlight .sx{color:#a8e6cf !important}.docs-content .highlight .sr{color:#a8e6cf !important}.docs-content .highlight .s1{color:#a8e6cf !important}.docs-content .highlight .ss{color:#a8e6cf !important}.docs-content .highlight .bp{color:var(--text-color) !important}.docs-content .highlight .vc{color:#ffd93d !important}.docs-content .highlight .vg{color:#ffd93d !important}.docs-content .highlight .vi{color:#ffd93d !important}.docs-content .highlight .il{color:#64ffda !important}.docs-content blockquote{border-left:4px solid var(--primary-color);padding-left:1rem;margin:1rem 0;color:var(--text-light);font-style:italic}.docs-content hr{border:none;border-top:2px solid var(--border-color);margin:2rem 0}.docs-content .emoji{font-size:1.2em}.docs-content .primary{background-color:var(--bg-light);border-left:4px solid var(--primary-color);padding:1rem;margin:1.5rem 0;border-radius:.25rem}.wrapper.docs-layout{max-width:1200px;margin:0 auto;padding:2rem 1rem;display:flex;gap:2rem;align-items:flex-start}.docs-sidebar{flex:0 0 260px;border-right:1px solid var(--border-color);background-color:var(--bg-light);padding:1.5rem 1rem;position:sticky;top:4rem;max-height:calc(100vh - 4rem);overflow-y:auto}.docs-sidebar-title{font-size:1.25rem;font-weight:700;margin:0 0 1rem 0}.docs-sidebar-title a{color:var(--primary-color);text-decoration:none}.docs-sidebar-title a:hover{color:var(--primary-hover);text-decoration:underline}.docs-nav{font-size:.95rem}.docs-nav-section{font-weight:600;margin:1rem 0 .5rem 0;color:var(--text-light);text-transform:uppercase;letter-spacing:.05em;font-size:.8rem}.docs-nav ul{list-style:none;margin:0 0 .5rem 0;padding-left:0}.docs-nav li{margin-bottom:.35rem}.docs-nav a{color:var(--text-color);text-decoration:none}.docs-nav a:hover{color:var(--primary-color);text-decoration:underline}.docs-content{flex:1 1 auto;min-width:0}.site-footer{border-top:2px solid var(--border-color);background-color:var(--bg-light);padding:2rem 0;margin-top:3rem;text-align:center;color:var(--text-light);font-size:.9rem}.site-footer .footer-heading{font-weight:600;margin-bottom:.5rem;color:var(--text-color)}.site-footer .footer-col-wrapper{display:flex;justify-content:center;flex-wrap:wrap;gap:2rem}.site-footer a{color:var(--link-color)}.site-footer a:hover{color:var(--link-hover)}@media screen and (max-width: 768px){.docs-layout{padding:1.5rem 1rem;flex-direction:column}.docs-sidebar{position:static;max-height:none;border-right:none;border-bottom:1px solid var(--border-color);margin-bottom:1rem}.site-header .site-title{font-size:1.25rem}.site-header .site-nav .page-link{margin:0 .25rem;font-size:.9rem}.page-content h1{font-size:2rem}.page-content h2{font-size:1.75rem}.page-content h3{font-size:1.25rem}.site-footer .footer-col-wrapper{flex-direction:column;gap:1rem}}.mermaid{background-color:var(--bg-light) !important;padding:1.5rem;border-radius:.5rem;border:1px solid var(--border-color);margin:1.5rem 0;overflow-x:auto}.mermaid svg{background-color:rgba(0,0,0,0) !important}.mermaid text{fill:var(--text-color) !important}.mermaid .node rect,.mermaid .node circle,.mermaid .node ellipse,.mermaid .node polygon{fill:var(--bg-alt) !important;stroke:var(--primary-color) !important}.mermaid .edgePath path,.mermaid .flowchart-link{stroke:var(--primary-color) !important}.mermaid .arrowheadPath{fill:var(--primary-color) !important}.mermaid .edgeLabel{background-color:var(--bg-light) !important;color:var(--text-color) !important}.mermaid .edgeLabel text{fill:var(--text-color) !important}@media print{.site-header,.site-footer{display:none}.page-content{max-width:100%;padding:0}} \ No newline at end of file diff --git a/_site_local/assets/minima-social-icons.svg b/_site_local/assets/minima-social-icons.svg new file mode 100644 index 0000000..fa7399f --- /dev/null +++ b/_site_local/assets/minima-social-icons.svg @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/_site_local/brownfield-engineer/index.html b/_site_local/brownfield-engineer/index.html new file mode 100644 index 0000000..e97995d --- /dev/null +++ b/_site_local/brownfield-engineer/index.html @@ -0,0 +1,648 @@ + + + + + + + +Modernizing Legacy Code (Brownfield Engineer Guide) | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Guide for Legacy Modernization Engineers

+ +
+

Complete walkthrough for modernizing legacy Python code with SpecFact CLI

+
+ +
+ +

Your Challenge

+ +

You’re responsible for modernizing a legacy Python system that:

+ +
    +
  • Has minimal or no documentation
    • +
  • Was built by developers who have left
    • +
  • Contains critical business logic you can’t risk breaking
    • +
  • Needs migration to modern Python, cloud infrastructure, or microservices
    • +
+ +

Sound familiar? You’re not alone. 70% of IT budgets are consumed by legacy maintenance, and the legacy modernization market is $25B+ and growing.

+ +
+ +

SpecFact for Brownfield: Your Safety Net

+ +

SpecFact CLI is designed specifically for your situation. It provides:

+ +
    +
  1. Automated spec extraction (code2spec) - Understand what your code does in < 10 seconds
    2. +
  2. Runtime contract enforcement - Prevent regressions during modernization
    3. +
  3. Symbolic execution - Discover hidden edge cases with CrossHair
    4. +
  4. Formal guarantees - Mathematical verification, not probabilistic LLM suggestions
    5. +
  5. CLI-first integration - Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. Works offline, no account required, no vendor lock-in.
    6. +
+ +
+ +

Step 1: Understand What You Have

+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

+ +

Extract Specs from Legacy Code

+ +
# Analyze your legacy codebase
+specfact import from-code --bundle legacy-api --repo ./legacy-app
+
+# For large codebases or multi-project repos, analyze specific modules:
+specfact import from-code --bundle core-module --repo ./legacy-app --entry-point src/core
+specfact import from-code --bundle api-module --repo ./legacy-app --entry-point src/api
+
+ +

What you get:

+ +
    +
  • ✅ Auto-generated feature map of existing functionality
    • +
  • ✅ Extracted user stories from code patterns
    • +
  • ✅ Dependency graph showing module relationships
    • +
  • ✅ Business logic documentation from function signatures
    • +
  • ✅ Edge cases discovered via symbolic execution
    • +
+ +

Example output:

+ +
✅ Analyzed 47 Python files
+✅ Extracted 23 features:
+
+   - FEATURE-001: User Authentication (95% confidence)
+   - FEATURE-002: Payment Processing (92% confidence)
+   - FEATURE-003: Order Management (88% confidence)
+   ...
+✅ Generated 112 user stories from existing code patterns
+✅ Detected 6 edge cases with CrossHair symbolic execution
+⏱️  Completed in 8.2 seconds
+
+ +

Time saved: 60-120 hours of manual documentation work → 8 seconds

+ +

💡 Partial Repository Coverage:

+ +

For large codebases or monorepos with multiple projects, you can analyze specific subdirectories using --entry-point:

+ +
# Analyze only the core module
+specfact import from-code --bundle core-module --repo . --entry-point src/core
+
+# Analyze only the API service
+specfact import from-code --bundle api-service --repo . --entry-point projects/api-service
+
+ +

This enables:

+ +
    +
  • Faster analysis - Focus on specific modules for quicker feedback
    • +
  • Incremental modernization - Modernize one module at a time
    • +
  • Multi-plan support - Create separate plan bundles for different projects/modules
    • +
  • Better organization - Keep plans organized by project boundaries
    • +
+ +

💡 Tip: After importing, the CLI may suggest generating a bootstrap constitution for Spec-Kit integration. This auto-generates a constitution from your repository analysis:

+ +
# If suggested, accept to auto-generate
+# Or run manually:
+specfact sdd constitution bootstrap --repo .
+
+ +

This is especially useful if you plan to sync with Spec-Kit later.

+ +
+ +

Step 2: Add Contracts to Critical Paths

+ +

Identify Critical Functions

+ +

SpecFact helps you identify which functions are critical (high risk, high business value):

+ +
# Review extracted plan to identify critical paths
+cat .specfact/projects/<bundle-name>/bundle.manifest.yaml
+
+ +

Add Runtime Contracts

+ +

Add contract decorators to critical functions:

+ +
# Before: Undocumented legacy function
+def process_payment(user_id, amount, currency):
+    # 80 lines of legacy code with hidden business rules
+    ...
+
+# After: Contract-enforced function
+import icontract
+
+@icontract.require(lambda amount: amount > 0, "Payment amount must be positive")
+@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP'])
+@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED'])
+def process_payment(user_id, amount, currency):
+    # Same 80 lines of legacy code
+    # Now with runtime enforcement
+    ...
+
+ +

What this gives you:

+ +
    +
  • ✅ Runtime validation catches invalid inputs immediately
    • +
  • ✅ Prevents regressions during refactoring
    • +
  • ✅ Documents expected behavior (executable documentation)
    • +
  • ✅ CrossHair discovers edge cases automatically
    • +
+ +
+ +

Step 3: Modernize with Confidence

+ +

Refactor Safely

+ +

With contracts in place, you can refactor knowing that violations will be caught:

+ +
# Refactored version (same contracts)
+@icontract.require(lambda amount: amount > 0, "Payment amount must be positive")
+@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP'])
+@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED'])
+def process_payment(user_id, amount, currency):
+    # Modernized implementation
+    # If contract violated → exception raised immediately
+    ...
+
+
+ +

Catch Regressions Automatically

+ +
# During modernization, accidentally break contract:
+process_payment(user_id=-1, amount=-50, currency="XYZ")
+
+# Runtime enforcement catches it:
+# ❌ ContractViolation: Payment amount must be positive (got -50)
+#    at process_payment() call from refactored checkout.py:142
+#    → Prevented production bug during modernization!
+
+ +
+ +

Step 4: Discover Hidden Edge Cases

+ +

CrossHair Symbolic Execution

+ +

SpecFact uses CrossHair to discover edge cases that manual testing misses:

+ +
# Legacy function with hidden edge case
+@icontract.require(lambda numbers: len(numbers) > 0)
+@icontract.ensure(lambda numbers, result: len(numbers) == 0 or min(numbers) > result)
+def remove_smallest(numbers: List[int]) -> int:
+    """Remove and return smallest number from list"""
+    smallest = min(numbers)
+    numbers.remove(smallest)
+    return smallest
+
+# CrossHair finds counterexample:
+# Input: [3, 3, 5] → After removal: [3, 5], min=3, returned=3
+# ❌ Postcondition violated: min(numbers) > result fails when duplicates exist!
+# CrossHair generates concrete failing input: [3, 3, 5]
+
+ +

Why this matters:

+ +
    +
  • ✅ Discovers edge cases LLMs miss
    • +
  • ✅ Mathematical proof of violations (not probabilistic)
    • +
  • ✅ Generates concrete test inputs automatically
    • +
  • ✅ Prevents production bugs before they happen
    • +
+ +
+ +

Real-World Example: Django Legacy App

+ +

The Problem

+ +

You inherited a 3-year-old Django app with:

+ +
    +
  • No documentation
    • +
  • No type hints
    • +
  • No tests
    • +
  • 15 undocumented API endpoints
    • +
  • Business logic buried in views
    • +
+ +

The Solution

+ +
# Step 1: Extract specs
+specfact import from-code --bundle customer-portal --repo ./legacy-django-app
+
+# Output:
+✅ Analyzed 47 Python files
+✅ Extracted 23 features (API endpoints, background jobs, integrations)
+✅ Generated 112 user stories from existing code patterns
+✅ Time: 8 seconds
+
+ +

The Results

+ +
    +
  • ✅ Legacy app fully documented in < 10 minutes
    • +
  • ✅ Prevented 4 production bugs during refactoring
    • +
  • ✅ New developers onboard 60% faster
    • +
  • ✅ CrossHair discovered 6 hidden edge cases
    • +
+ +
+ +

ROI: Time and Cost Savings

+ +

Manual Approach

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TaskTime InvestmentCost (@$150/hr)
Manually document 50-file legacy app80-120 hours$12,000-$18,000
Write tests for undocumented code100-150 hours$15,000-$22,500
Debug regression during refactor40-80 hours$6,000-$12,000
TOTAL220-350 hours$33,000-$52,500
+ +

SpecFact Automated Approach

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TaskTime InvestmentCost (@$150/hr)
Run code2spec extraction10 minutes$25
Review and refine extracted specs8-16 hours$1,200-$2,400
Add contracts to critical paths16-24 hours$2,400-$3,600
CrossHair edge case discovery2-4 hours$300-$600
TOTAL26-44 hours$3,925-$6,625
+ +

ROI: 87% time saved, $26,000-$45,000 cost avoided

+ +
+ +

Integration with Your Workflow

+ +

SpecFact CLI integrates seamlessly with your existing tools:

+ +
    +
  • VS Code: Use pre-commit hooks to catch breaking changes before commit
    • +
  • Cursor: AI assistant workflows catch regressions during refactoring
    • +
  • GitHub Actions: CI/CD integration blocks bad code from merging
    • +
  • Pre-commit hooks: Local validation prevents breaking changes
    • +
  • Any IDE: Pure CLI-first approach—works with any editor
    • +
+ +

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via integrations

+ +

Best Practices

+ +

1. Start with Shadow Mode

+ +

Begin in shadow mode to observe without blocking:

+ +
specfact import from-code --bundle legacy-api --repo . --shadow-only
+
+ +

2. Add Contracts Incrementally

+ +

Don’t try to contract everything at once:

+ +
    +
  1. Week 1: Add contracts to 3-5 critical functions
    2. +
  2. Week 2: Expand to 10-15 functions
    3. +
  3. Week 3: Add contracts to all public APIs
    4. +
  4. Week 4+: Add contracts to internal functions as needed
    5. +
+ +

3. Use CrossHair for Edge Case Discovery

+ +

Run CrossHair on critical functions before refactoring:

+ +
hatch run contract-explore src/payment.py
+
+ +

4. Document Your Findings

+ +

Keep notes on:

+ +
    +
  • Edge cases discovered
    • +
  • Contract violations caught
    • +
  • Time saved on documentation
    • +
  • Bugs prevented during modernization
    • +
+ +
+ +

Common Questions

+ +

Can SpecFact analyze code with no docstrings?

+ +

Yes. code2spec analyzes:

+ +
    +
  • Function signatures and type hints
    • +
  • Code patterns and control flow
    • +
  • Existing validation logic
    • +
  • Module dependencies
    • +
+ +

No docstrings needed.

+ +

What if the legacy code has no type hints?

+ +

SpecFact infers types from usage patterns and generates specs. You can add type hints incrementally as part of modernization.

+ +

Can SpecFact handle obfuscated or minified code?

+ +

Limited. SpecFact works best with:

+ +
    +
  • Source code (not compiled bytecode)
    • +
  • Readable variable names
    • +
+ +

For heavily obfuscated code, consider deobfuscation first.

+ +

Will contracts slow down my code?

+ +

Minimal impact. Contract checks are fast (microseconds per call). For high-performance code, you can disable contracts in production while keeping them in tests.

+ +
+ +

Next Steps

+ +
    +
  1. Integration Showcases - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations
    2. +
  2. ROI Calculator - Calculate your time and cost savings
    3. +
  3. Brownfield Journey - Complete modernization workflow
    4. +
  4. Examples - Real-world brownfield examples
    5. +
  5. FAQ - More brownfield-specific questions
    6. +
+ +
+ +

Support

+ + + +
+ +

Happy modernizing! 🚀

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/brownfield-journey/index.html b/_site_local/brownfield-journey/index.html new file mode 100644 index 0000000..7a3401a --- /dev/null +++ b/_site_local/brownfield-journey/index.html @@ -0,0 +1,701 @@ + + + + + + + +Brownfield Modernization Journey | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Brownfield Modernization Journey

+ +
+

Complete step-by-step workflow for modernizing legacy Python code with SpecFact CLI

+
+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

+ +
+ +

Overview

+ +

This guide walks you through the complete brownfield modernization journey:

+ +
    +
  1. Understand - Extract specs from legacy code
    2. +
  2. Protect - Add contracts to critical paths
    3. +
  3. Discover - Find hidden edge cases
    4. +
  4. Modernize - Refactor safely with contract safety net
    5. +
  5. Validate - Verify modernization success
    6. +
+ +

Time investment: 26-44 hours (vs. 220-350 hours manual)
+ROI: 87% time saved, $26,000-$45,000 cost avoided

+ +
+ +

Phase 1: Understand Your Legacy Code

+ +

Step 1.1: Extract Specs Automatically

+ +

CLI-First Integration: Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. See Integration Showcases for real examples.

+ +
# Analyze your legacy codebase
+specfact import from-code --bundle legacy-api --repo ./legacy-app
+
+ +

What happens:

+ +
    +
  • SpecFact analyzes all Python files
    • +
  • Extracts features, user stories, and business logic
    • +
  • Generates dependency graphs
    • +
  • Creates plan bundle with extracted specs
    • +
+ +

Output:

+ +
✅ Analyzed 47 Python files
+✅ Extracted 23 features
+✅ Generated 112 user stories
+⏱️  Completed in 8.2 seconds
+
+ +

Time saved: 60-120 hours of manual documentation → 8 seconds

+ +

💡 Tip: After importing, the CLI may suggest generating a bootstrap constitution for Spec-Kit integration. This auto-generates a constitution from your repository analysis:

+ +
# If suggested, accept to auto-generate
+# Or run manually:
+specfact sdd constitution bootstrap --repo .
+
+ +

This is especially useful if you plan to sync with Spec-Kit later.

+ +

Step 1.2: Review Extracted Specs

+ +
# Review the extracted plan using CLI commands
+specfact plan review --bundle legacy-api
+
+ +

What to look for:

+ +
    +
  • High-confidence features (95%+) - These are well-understood
    • +
  • Low-confidence features (<70%) - These need manual review
    • +
  • Missing features - May indicate incomplete extraction
    • +
  • Edge cases - Already discovered by CrossHair
    • +
+ +

Step 1.3: Validate Extraction Quality

+ +
# Compare extracted plan to your understanding (bundle directory paths)
+specfact plan compare \
+  --manual .specfact/projects/manual-plan \
+  --auto .specfact/projects/your-project
+
+ +

What you get:

+ +
    +
  • Deviations between manual and auto-derived plans
    • +
  • Missing features in extraction
    • +
  • Extra features in extraction (may be undocumented functionality)
    • +
+ +
+ +

Phase 2: Protect Critical Paths

+ +

Step 2.1: Identify Critical Functions

+ +

Criteria for “critical”:

+ +
    +
  • High business value (payment, authentication, data processing)
    • +
  • High risk (production bugs would be costly)
    • +
  • Complex logic (hard to understand, easy to break)
    • +
  • Frequently called (high impact if broken)
    • +
+ +

Review extracted plan:

+ +
# Review plan using CLI commands
+specfact plan review --bundle legacy-api
+
+ +

Step 2.2: Add Contracts Incrementally

+ +

Week 1: Start with 3-5 critical functions

+ +
# Example: Add contracts to payment processing
+import icontract
+
+@icontract.require(lambda amount: amount > 0, "Amount must be positive")
+@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP'])
+@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED'])
+def process_payment(user_id, amount, currency):
+    # Legacy code with contracts
+    ...
+
+ +

Week 2: Expand to 10-15 functions

+ +

Week 3: Add contracts to all public APIs

+ +

Week 4+: Add contracts to internal functions as needed

+ +

Step 2.3: Start in Shadow Mode

+ +

Shadow mode observes violations without blocking:

+ +
# Run in shadow mode (observe only)
+specfact enforce --mode shadow
+
+ +

Benefits:

+ +
    +
  • See violations without breaking workflow
    • +
  • Understand contract behavior before enforcing
    • +
  • Build confidence gradually
    • +
+ +

Graduation path:

+ +
    +
  1. Shadow mode (Week 1) - Observe only
    2. +
  2. Warn mode (Week 2) - Log violations, don’t block
    3. +
  3. Block mode (Week 3+) - Raise exceptions on violations
    4. +
+ +
+ +

Phase 3: Discover Hidden Edge Cases

+ +

Step 3.1: Run CrossHair on Critical Functions

+ +
# Discover edge cases in payment processing
+hatch run contract-explore src/payment.py
+
+ +

What CrossHair does:

+ +
    +
  • Explores all possible code paths symbolically
    • +
  • Finds inputs that violate contracts
    • +
  • Generates concrete test cases for violations
    • +
+ +

Example output:

+ +
❌ Postcondition violation found:
+   Function: process_payment
+   Input: amount=0.0, currency='USD'
+   Issue: Amount must be positive (got 0.0)
+
+
+ +

Step 3.2: Fix Discovered Edge Cases

+ +
# Add validation for edge cases
+@icontract.require(
+    lambda amount: amount > 0 and amount <= 1000000,
+    "Amount must be between 0 and 1,000,000"
+)
+def process_payment(...):
+    # Now handles edge cases discovered by CrossHair
+    ...
+
+ +

Step 3.3: Document Edge Cases

+ +

Keep notes on:

+ +
    +
  • Edge cases discovered
    • +
  • Contract violations found
    • +
  • Fixes applied
    • +
  • Test cases generated
    • +
+ +

Why this matters:

+ +
    +
  • Prevents regressions in future refactoring
    • +
  • Documents hidden business rules
    • +
  • Helps new team members understand code
    • +
+ +
+ +

Phase 4: Modernize Safely

+ +

Step 4.1: Refactor Incrementally

+ +

One function at a time:

+ +
    +
  1. Add contracts to function (if not already done)
    2. +
  2. Run CrossHair to discover edge cases
    3. +
  3. Refactor function implementation
    4. +
  4. Verify contracts still pass
    5. +
  5. Move to next function
    6. +
+ +

Example:

+ +
# Before: Legacy implementation
+@icontract.require(lambda amount: amount > 0)
+def process_payment(user_id, amount, currency):
+    # 80 lines of legacy code
+    ...
+
+# After: Modernized implementation (same contracts)
+@icontract.require(lambda amount: amount > 0)
+def process_payment(user_id, amount, currency):
+    # Modernized code (same contracts protect behavior)
+    payment_service = PaymentService()
+    return payment_service.process(user_id, amount, currency)
+
+ +

Step 4.2: Catch Regressions Automatically

+ +

Contracts catch violations during refactoring:

+ +
# During modernization, accidentally break contract:
+process_payment(user_id=-1, amount=-50, currency="XYZ")
+
+# Runtime enforcement catches it:
+# ❌ ContractViolation: Amount must be positive (got -50)
+#    → Fix the bug before it reaches production!
+
+
+ +

Step 4.3: Verify Modernization Success

+ +
# Run contract validation
+hatch run contract-test-full
+
+# Check for violations
+specfact enforce --mode block
+
+ +

Success criteria:

+ +
    +
  • ✅ All contracts pass
    • +
  • ✅ No new violations introduced
    • +
  • ✅ Edge cases still handled
    • +
  • ✅ Performance acceptable
    • +
+ +
+ +

Phase 5: Validate and Measure

+ +

Step 5.1: Measure ROI

+ +

Track metrics:

+ +
    +
  • Time saved on documentation
    • +
  • Bugs prevented during modernization
    • +
  • Edge cases discovered
    • +
  • Developer onboarding time reduction
    • +
+ +

Example metrics:

+ +
    +
  • Documentation: 87% time saved (8 hours vs. 60 hours)
    • +
  • Bugs prevented: 4 production bugs
    • +
  • Edge cases: 6 discovered automatically
    • +
  • Onboarding: 60% faster (3-5 days vs. 2-3 weeks)
    • +
+ +

Step 5.2: Document Success

+ +

Create case study:

+ +
    +
  • Problem statement
    • +
  • Solution approach
    • +
  • Quantified results
    • +
  • Lessons learned
    • +
+ +

Why this matters:

+ +
    +
  • Validates approach for future projects
    • +
  • Helps other teams learn from your experience
    • +
  • Builds confidence in brownfield modernization
    • +
+ +
+ +

Real-World Example: Complete Journey

+ +

The Problem

+ +

Legacy Django app:

+ +
    +
  • 47 Python files
    • +
  • No documentation
    • +
  • No type hints
    • +
  • No tests
    • +
  • 15 undocumented API endpoints
    • +
+ +

The Journey

+ +

Week 1: Understand

+ +
    +
  • Ran specfact import from-code --bundle legacy-api --repo . → 23 features extracted in 8 seconds
    • +
  • Reviewed extracted plan → Identified 5 critical features
    • +
  • Time: 2 hours (vs. 60 hours manual)
    • +
+ +

Week 2: Protect

+ +
    +
  • Added contracts to 5 critical functions
    • +
  • Started in shadow mode → Observed 3 violations
    • +
  • Time: 16 hours
    • +
+ +

Week 3: Discover

+ +
    +
  • Ran CrossHair on critical functions → Discovered 6 edge cases
    • +
  • Fixed edge cases → Added validation
    • +
  • Time: 4 hours
    • +
+ +

Week 4: Modernize

+ +
    +
  • Refactored 5 critical functions with contract safety net
    • +
  • Caught 4 regressions automatically (contracts prevented bugs)
    • +
  • Time: 24 hours
    • +
+ +

Week 5: Validate

+ +
    +
  • All contracts passing
    • +
  • No production bugs from modernization
    • +
  • New developers productive in 3 days (vs. 2-3 weeks)
    • +
+ +

The Results

+ +
    +
  • ✅ 87% time saved on documentation (8 hours vs. 60 hours)
    • +
  • ✅ 4 production bugs prevented during modernization
    • +
  • ✅ 6 edge cases discovered automatically
    • +
  • ✅ 60% faster onboarding (3-5 days vs. 2-3 weeks)
    • +
  • ✅ Zero downtime modernization
    • +
+ +

ROI: $42,000 saved, 5-week acceleration

+ +
+ +

Best Practices

+ +

1. Start Small

+ +
    +
  • Don’t try to contract everything at once
    • +
  • Start with 3-5 critical functions
    • +
  • Expand incrementally
    • +
+ +

2. Use Shadow Mode First

+ +
    +
  • Observe violations before enforcing
    • +
  • Build confidence gradually
    • +
  • Graduate to warn → block mode
    • +
+ +

3. Run CrossHair Early

+ +
    +
  • Discover edge cases before refactoring
    • +
  • Fix issues proactively
    • +
  • Document findings
    • +
+ +

4. Refactor Incrementally

+ +
    +
  • One function at a time
    • +
  • Verify contracts after each refactor
    • +
  • Don’t rush
    • +
+ +

5. Document Everything

+ +
    +
  • Edge cases discovered
    • +
  • Contract violations found
    • +
  • Fixes applied
    • +
  • Lessons learned
    • +
+ +
+ +

Common Pitfalls

+ +

❌ Trying to Contract Everything at Once

+ +

Problem: Overwhelming, slows down development

+ +

Solution: Start with 3-5 critical functions, expand incrementally

+ +

❌ Skipping Shadow Mode

+ +

Problem: Too many violations, breaks workflow

+ +

Solution: Always start in shadow mode, graduate gradually

+ +

❌ Ignoring CrossHair Findings

+ +

Problem: Edge cases discovered but not fixed

+ +

Solution: Fix edge cases before refactoring

+ +

❌ Refactoring Too Aggressively

+ +

Problem: Breaking changes, contract violations

+ +

Solution: Refactor incrementally, verify contracts after each change

+ +
+ +

Next Steps

+ +
    +
  1. Integration Showcases - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations
    2. +
  2. Brownfield Engineer Guide - Complete persona guide
    3. +
  3. ROI Calculator - Calculate your savings
    4. +
  4. Examples - Real-world brownfield examples
    5. +
  5. FAQ - More brownfield questions
    6. +
+ +
+ +

Support

+ + + +
+ +

Happy modernizing! 🚀

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/common-tasks/index.html b/_site_local/common-tasks/index.html new file mode 100644 index 0000000..15fd2cd --- /dev/null +++ b/_site_local/common-tasks/index.html @@ -0,0 +1,632 @@ + + + + + + + +Common Tasks Quick Reference | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Common Tasks Quick Reference

+ +
+

Quick answers to “How do I X?” questions

+
+ +
+ +

Overview

+ +

This guide maps common user goals to recommended SpecFact CLI commands or command chains. Each entry includes a task description, recommended approach, link to detailed guide, and a quick example.

+ +

Not sure which task matches your goal? Use the Command Chains Decision Tree to find the right workflow.

+ +
+ +

Getting Started

+ +

I want to analyze my legacy code

+ +

Recommended: Brownfield Modernization Chain

+ +

Command: import from-code

+ +

Quick Example:

+ +
specfact import from-code --bundle legacy-api --repo .
+
+ +

Detailed Guide: Brownfield Engineer Guide

+ +
+ +

I want to plan a new feature from scratch

+ +

Recommended: Greenfield Planning Chain

+ +

Command: plan init → plan add-feature → plan add-story

+ +

Quick Example:

+ +
specfact plan init --bundle new-feature --interactive
+specfact plan add-feature --bundle new-feature --name "User Authentication"
+specfact plan add-story --bundle new-feature --feature <feature-id> --story "As a user, I want to log in"
+
+ +

Detailed Guide: Agile/Scrum Workflows

+ +
+ +

I want to sync with Spec-Kit or OpenSpec

+ +

Recommended: External Tool Integration Chain

+ +

Command: import from-bridge → sync bridge

+ +

Quick Example:

+ +
specfact import from-bridge --repo . --adapter speckit --write
+specfact sync bridge --adapter speckit --bundle <bundle-name> --bidirectional --watch
+
+ + + + + + + + +
Detailed Guide: Spec-Kit JourneyOpenSpec Journey
+ +
+ +

Brownfield Modernization

+ +

I want to extract specifications from existing code

+ +

Recommended: import from-code

+ +

Quick Example:

+ +
specfact import from-code --bundle legacy-api --repo ./legacy-app
+
+ +

Detailed Guide: Brownfield Engineer Guide

+ +
+ +

I want to review and update extracted features

+ +

Recommended: plan review → plan update-feature

+ +

Quick Example:

+ +
specfact plan review --bundle legacy-api
+specfact plan update-feature --bundle legacy-api --feature <feature-id>
+
+ +

Detailed Guide: Brownfield Engineer Guide

+ +
+ +

I want to detect code-spec drift

+ +

Recommended: Code-to-Plan Comparison Chain

+ +

Command: plan compare → drift detect

+ +

Quick Example:

+ +
specfact import from-code --bundle current-state --repo .
+specfact plan compare --bundle <plan-bundle> --code-vs-plan
+specfact drift detect --bundle <bundle-name>
+
+ +

Detailed Guide: Drift Detection

+ +
+ +

I want to add contracts to existing code

+ +

Recommended: AI-Assisted Code Enhancement Chain

+ +

Command: generate contracts-prompt → [AI IDE] → contracts-apply

+ +

Quick Example:

+ +
specfact generate contracts-prompt --bundle <bundle-name> --feature <feature-id>
+# Then use AI IDE slash command: /specfact-cli/contracts-apply <prompt-file>
+specfact contract coverage --bundle <bundle-name>
+
+ +

Detailed Guide: AI IDE Workflow

+ +
+ +

API Development

+ +

I want to validate API contracts

+ +

Recommended: API Contract Development Chain

+ +

Command: spec validate → spec backward-compat

+ +

Quick Example:

+ +
specfact spec validate --spec openapi.yaml
+specfact spec backward-compat --spec openapi.yaml --previous-spec openapi-v1.yaml
+
+ +

Detailed Guide: Specmatic Integration

+ +
+ +

I want to generate tests from API specifications

+ +

Recommended: spec generate-tests

+ +

Quick Example:

+ +
specfact spec generate-tests --spec openapi.yaml --output tests/
+pytest tests/
+
+ +

Detailed Guide: Contract Testing Workflow

+ +
+ +

I want to create a mock server for API development

+ +

Recommended: spec mock

+ +

Quick Example:

+ +
specfact spec mock --spec openapi.yaml --port 8080
+
+ +

Detailed Guide: Specmatic Integration

+ +
+ +

Team Collaboration

+ +

I want to set up team collaboration

+ +

Recommended: Team Collaboration Workflow

+ +

Command: project export → project import → project lock/unlock

+ +

Quick Example:

+ +
specfact project init-personas --bundle <bundle-name>
+specfact project export --bundle <bundle-name> --persona product-owner
+# Edit exported Markdown files
+specfact project import --bundle <bundle-name> --persona product-owner --source exported-plan.md
+
+ +

Detailed Guide: Agile/Scrum Workflows

+ +
+ +

I want to export persona-specific views

+ +

Recommended: project export

+ +

Quick Example:

+ +
specfact project export --bundle <bundle-name> --persona product-owner
+specfact project export --bundle <bundle-name> --persona architect
+specfact project export --bundle <bundle-name> --persona developer
+
+ +

Detailed Guide: Agile/Scrum Workflows

+ +
+ +

I want to manage project versions

+ +

Recommended: project version check → project version bump

+ +

Quick Example:

+ +
specfact project version check --bundle <bundle-name>
+specfact project version bump --bundle <bundle-name> --type minor
+
+ +

Detailed Guide: Project Version Management

+ +
+ +

Plan Management

+ +

I want to promote a plan through stages

+ +

Recommended: Plan Promotion & Release Chain

+ +

Command: plan review → enforce sdd → plan promote

+ +

Quick Example:

+ +
specfact plan review --bundle <bundle-name>
+specfact enforce sdd --bundle <bundle-name>
+specfact plan promote --bundle <bundle-name> --stage approved
+
+ +

Detailed Guide: Agile/Scrum Workflows

+ +
+ +

I want to compare two plans

+ +

Recommended: plan compare

+ +

Quick Example:

+ +
specfact plan compare --bundle plan-v1 plan-v2
+
+ +

Detailed Guide: Plan Comparison

+ +
+ +

Validation & Enforcement

+ +

I want to validate everything

+ +

Recommended: repro

+ +

Quick Example:

+ +
specfact repro --verbose
+
+ +

Detailed Guide: Validation Workflow

+ +
+ +

I want to enforce SDD compliance

+ +

Recommended: enforce sdd

+ +

Quick Example:

+ +
specfact enforce sdd --bundle <bundle-name>
+
+ +

Detailed Guide: SDD Enforcement

+ +
+ +

I want to find gaps in my code

+ +

Recommended: Gap Discovery & Fixing Chain

+ +

Command: repro --verbose → generate fix-prompt

+ +

Quick Example:

+ +
specfact repro --verbose
+specfact generate fix-prompt --bundle <bundle-name> --gap <gap-id>
+# Then use AI IDE to apply fixes
+
+ +

Detailed Guide: AI IDE Workflow

+ +
+ +

AI IDE Integration

+ +

I want to set up AI IDE slash commands

+ +

Recommended: init --ide cursor

+ +

Quick Example:

+ +
specfact init --ide cursor
+
+ + + + + + + + +
Detailed Guide: AI IDE WorkflowIDE Integration
+ +
+ +

I want to generate tests using AI

+ +

Recommended: Test Generation from Specifications Chain

+ +

Command: generate test-prompt → [AI IDE] → spec generate-tests

+ +

Quick Example:

+ +
specfact generate test-prompt --bundle <bundle-name> --feature <feature-id>
+# Then use AI IDE slash command: /specfact-cli/test-generate <prompt-file>
+specfact spec generate-tests --spec <spec-file> --output tests/
+
+ +

Detailed Guide: AI IDE Workflow

+ +
+ +

DevOps Integration

+ +

I want to sync change proposals to GitHub Issues

+ +

Recommended: sync bridge --mode export-only

+ +

Quick Example:

+ +
specfact sync bridge --adapter github --mode export-only --repo-owner owner --repo-name repo
+
+ +

Detailed Guide: DevOps Adapter Integration

+ +
+ +

I want to track changes in GitHub Projects

+ +

Recommended: DevOps bridge adapter with project linking

+ +

Quick Example:

+ +
specfact sync bridge --adapter github --mode export-only --project "SpecFact CLI Development Board"
+
+ +

Detailed Guide: DevOps Adapter Integration

+ +
+ +

Migration & Troubleshooting

+ +

I want to migrate from an older version

+ +

Recommended: Check migration guides

+ +

Quick Example:

+ +
# Check current version
+specfact --version
+
+# Review migration guide for your version
+# See: guides/migration-*.md
+
+ + + + + + + + +
Detailed Guide: Migration GuideTroubleshooting
+ +
+ +

I want to troubleshoot an issue

+ +

Recommended: Troubleshooting Guide

+ +

Quick Example:

+ +
# Run validation with verbose output
+specfact repro --verbose
+
+# Check plan for issues
+specfact plan review --bundle <bundle-name>
+
+ +

Detailed Guide: Troubleshooting

+ +
+ +

See Also

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/competitive-analysis/index.html b/_site_local/competitive-analysis/index.html new file mode 100644 index 0000000..f18695e --- /dev/null +++ b/_site_local/competitive-analysis/index.html @@ -0,0 +1,634 @@ + + + + + + + +Competitive Analysis | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

What You Gain with SpecFact CLI

+ +

How SpecFact CLI complements and extends other development tools.

+ +

Overview

+ +

SpecFact CLI is a brownfield-first legacy code modernization tool that reverse engineers existing Python code into documented specs, then enforces them as runtime contracts. It builds on the strengths of specification tools like GitHub Spec-Kit and works alongside AI coding platforms to provide production-ready quality gates for legacy codebases.

+ +
+ +

Building on Specification Tools

+ +

SpecFact CLI integrates with multiple specification and planning tools through a plugin-based adapter architecture:

+ +
    +
  • GitHub Spec-Kit - Interactive specification authoring
    • +
  • OpenSpec - Specification anchoring and change tracking (v0.22.0+)
    • +
  • GitHub Issues - DevOps backlog integration
    • +
  • Future: Linear, Jira, Azure DevOps, and more
    • +
+ +

Building on GitHub Spec-Kit

+ +

What Spec-Kit Does Great

+ +

GitHub Spec-Kit pioneered the concept of living specifications with interactive slash commands. It’s excellent for:

+ +
    +
  • ✅ Interactive Specification - Slash commands (/speckit.specify, /speckit.plan) with AI assistance
    • +
  • ✅ Rapid Prototyping - Quick spec → plan → tasks → code workflow for new features
    • +
  • ✅ Learning & Exploration - Great for understanding state machines, contracts, requirements
    • +
  • ✅ IDE Integration - CoPilot chat makes it accessible to less technical developers
    • +
  • ✅ Constitution & Planning - Add constitution, plans, and feature breakdowns for new features
    • +
  • ✅ Single-Developer Projects - Perfect for personal projects and learning
    • +
+ +

Note: Spec-Kit excels at working with new features - you can add constitution, create plans, and break down features for things you’re building from scratch.

+ +

What SpecFact CLI Adds To GitHub Spec-Kit

+ +

SpecFact CLI complements Spec-Kit by adding automation and enforcement:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EnhancementWhat You Get
Automated enforcementRuntime + static contract validation, CI/CD gates
Shared plansShared structured plans enable team collaboration with automated bidirectional sync (not just manual markdown sharing like Spec-Kit)
Code vs plan drift detectionAutomated comparison of intended design (manual plan) vs actual implementation (code-derived plan from import from-code)
CI/CD integrationAutomated quality gates in your pipeline
Brownfield supportAnalyze existing code to complement Spec-Kit’s greenfield focus
Property testingFSM fuzzing, Hypothesis-based validation
No-escape gatesBudget-based enforcement prevents violations
Bidirectional syncKeep using Spec-Kit interactively, sync automatically with SpecFact
+ +

The Journey: From Spec-Kit to SpecFact

+ +

Spec-Kit and SpecFact are complementary, not competitive:

+ +
    +
  • Stage 1: Spec-Kit - Interactive authoring with slash commands (/speckit.specify, /speckit.plan)
    • +
  • Stage 2: SpecFact - Automated enforcement (CI/CD gates, contract validation)
    • +
  • Stage 3: Bidirectional Sync - Use both tools together (Spec-Kit authoring + SpecFact enforcement)
    • +
+ +

Learn the full journey →

+ +

Working With OpenSpec

+ +

OpenSpec is another complementary tool that focuses on specification anchoring and change tracking. SpecFact CLI integrates with OpenSpec via the OpenSpec adapter (available in v0.22.0+):

+ +
    +
  • OpenSpec manages specifications and change proposals (the “what” and “why”)
    • +
  • SpecFact analyzes existing code and enforces contracts (the “how” and “safety”)
    • +
  • Bridge Adapters sync change proposals to DevOps tools (the “tracking”)
    • +
+ +

Integration:

+ +
# Read-only sync from OpenSpec to SpecFact (v0.22.0+)
+specfact sync bridge --adapter openspec --mode read-only \
+  --bundle my-project \
+  --repo /path/to/openspec-repo
+
+# Export OpenSpec change proposals to GitHub Issues
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner your-org \
+  --repo-name your-repo \
+  --repo /path/to/openspec-repo
+
+ +

Learn the full OpenSpec integration journey →

+ +

Seamless Migration

+ +

Already using Spec-Kit? SpecFact CLI imports your work in one command:

+ +
specfact import from-bridge --adapter speckit --repo ./my-speckit-project --write
+
+ +

Result: Your Spec-Kit artifacts (spec.md, plan.md, tasks.md) become production-ready contracts with zero manual work.

+ +

Ongoing: Keep using Spec-Kit interactively, sync automatically with SpecFact:

+ +
# Enable bidirectional sync (bridge-based, adapter-agnostic)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Best of both worlds: Interactive authoring (Spec-Kit) + Automated enforcement (SpecFact)

+ +

Note: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in AdapterRegistry and accessed via specfact sync bridge --adapter <adapter-name>, making the architecture extensible for future tool integrations.

+ +

Team collaboration: Shared structured plans enable multiple developers to work on the same plan with automated deviation detection. Unlike Spec-Kit’s manual markdown sharing, SpecFact provides automated bidirectional sync that keeps plans synchronized across team members:

+ +
# Enable bidirectional sync for team collaboration
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+# → Automatically syncs Spec-Kit artifacts ↔ SpecFact project bundles
+# → Multiple developers can work on the same plan with automated synchronization
+# → No manual markdown sharing required
+
+# Detect code vs plan drift automatically
+specfact plan compare --bundle legacy-api --code-vs-plan
+# → Compares intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code)
+# → Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift"
+# → Identifies deviations automatically (not just artifact consistency like Spec-Kit's /speckit.analyze)
+
+ +
+ +

Working With AI Coding Tools

+ +

What AI Tools Do Great

+ +

Tools like Replit Agent 3, Lovable, Cursor, and Copilot excel at:

+ +
    +
  • ✅ Rapid code generation
    • +
  • ✅ Quick prototyping
    • +
  • ✅ Learning and exploration
    • +
  • ✅ Boilerplate reduction
    • +
+ +

What SpecFact CLI Adds To AI Coding Tools

+ +

SpecFact CLI validates AI-generated code with:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EnhancementWhat You Get
Contract validationEnsure AI code meets your specs
Runtime sentinelsCatch async anti-patterns automatically
No-escape gatesBlock broken code from merging
Offline validationWorks in air-gapped environments
Evidence trailsReproducible proof of quality
Team standardsEnforce consistent patterns across AI-generated code
CoPilot integrationSlash commands for seamless IDE workflow
Agent mode routingEnhanced prompts for better AI assistance
+ +

Perfect Combination

+ +

AI tools generate code fast → SpecFact CLI ensures it’s correct

+ +

Use AI for speed, use SpecFact for quality.

+ +

CoPilot-Enabled Mode

+ +

When using Cursor, Copilot, or other AI assistants, SpecFact CLI integrates seamlessly:

+ +
# Slash commands in IDE (after specfact init)
+specfact init --ide cursor
+/specfact.01-import legacy-api --repo . --confidence 0.7
+/specfact.02-plan init legacy-api
+/specfact.06-sync --repo . --bidirectional
+
+ +

Benefits:

+ +
    +
  • Automatic mode detection - Switches to CoPilot mode when available
    • +
  • Context injection - Uses current file, selection, and workspace context
    • +
  • Enhanced prompts - Optimized for AI understanding
    • +
  • Agent mode routing - Specialized prompts for different operations
    • +
+ +
+ +

Key Capabilities

+ +

1. Temporal Contracts

+ +

What it means: State machines with runtime validation

+ +

Why developers love it: Catches state transition bugs automatically

+ +

Example:

+ +
# Protocol enforces valid state transitions
+transitions:
+  - from_state: CONNECTED
+    on_event: disconnect
+    to_state: DISCONNECTING
+    guard: no_pending_messages  # ✅ Checked at runtime
+
+ +

2. Proof-Carrying Promotion

+ +

What it means: Evidence required before code merges

+ +

Why developers love it: “Works on my machine” becomes provable

+ +

Example:

+ +
# PR includes reproducible evidence
+specfact repro --budget 120 --report evidence.md
+
+ +

3. Brownfield-First ⭐ PRIMARY

+ +

What it means: Primary use case - Reverse engineer existing legacy code into documented specs, then enforce contracts to prevent regressions during modernization.

+ +

Why developers love it: Understand undocumented legacy code in minutes, not weeks. Modernize with confidence knowing contracts catch regressions automatically.

+ +

Example:

+ +
# Primary use case: Analyze legacy code
+specfact import from-code --bundle legacy-api --repo ./legacy-app
+
+# Extract specs from existing code in < 10 seconds
+# Then enforce contracts to prevent regressions
+specfact enforce stage --preset balanced
+
+ +

How it complements Spec-Kit: Spec-Kit focuses on new feature authoring (greenfield); SpecFact CLI’s primary focus is brownfield code modernization with runtime enforcement.

+ +

4. Code vs Plan Drift Detection

+ +

What it means: Automated comparison of intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what’s in your code). Auto-derived plans come from import from-code (code analysis), so comparison IS “code vs plan drift”.

+ +

Why developers love it: Detects code vs plan drift automatically (not just artifact consistency like Spec-Kit’s /speckit.analyze). Spec-Kit’s /speckit.analyze only checks artifact consistency between markdown files; SpecFact CLI detects actual code vs plan drift by comparing manual plans (intended design) with code-derived plans (actual implementation from code analysis).

+ +

Example:

+ +
# Detect code vs plan drift automatically
+specfact plan compare --bundle legacy-api --code-vs-plan
+# → Compares intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code)
+# → Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift"
+# → Identifies deviations automatically (not just artifact consistency like Spec-Kit's /speckit.analyze)
+
+ +

How it complements Spec-Kit: Spec-Kit’s /speckit.analyze only checks artifact consistency between markdown files; SpecFact CLI detects code vs plan drift by comparing manual plans (intended design) with code-derived plans (actual implementation from import from-code).

+ +

5. Evidence-Based

+ +

What it means: Reproducible validation and reports

+ +

Why developers love it: Debug failures with concrete data

+ +

Example:

+ +
# Generate reproducible evidence
+specfact repro --report evidence.md
+
+ +

6. Offline-First

+ +

What it means: Works without internet connection

+ +

Why developers love it: Air-gapped environments, no data exfiltration, fast

+ +

Example:

+ +
# Works completely offline
+uvx specfact-cli@latest plan init --interactive
+
+ +
+ +

When to Use SpecFact CLI

+ +

SpecFact CLI is Perfect For ⭐ PRIMARY

+ +
    +
  • ✅ Legacy code modernization ⭐ - Reverse engineer undocumented code into specs
    • +
  • ✅ Brownfield projects ⭐ - Understand and modernize existing Python codebases
    • +
  • ✅ High-risk refactoring ⭐ - Prevent regressions with runtime contract enforcement
    • +
  • ✅ Production systems - Need quality gates and validation
    • +
  • ✅ Team projects - Multiple developers need consistent standards
    • +
  • ✅ Compliance environments - Evidence-based validation required
    • +
  • ✅ Air-gapped deployments - Offline-first architecture
    • +
  • ✅ Open source projects - Transparent, inspectable tooling
    • +
+ +

SpecFact CLI Works Alongside

+ +
    +
  • ✅ AI coding assistants - Validate AI-generated code
    • +
  • ✅ Spec-Kit projects - One-command import
    • +
  • ✅ Existing CI/CD - Drop-in quality gates
    • +
  • ✅ Your IDE - Command-line or extension (v0.2)
    • +
+ +
+ +

Getting Started With SpecFact CLI

+ +

Modernizing Legacy Code? ⭐ PRIMARY

+ +

Reverse engineer existing code:

+ +
# Primary use case: Analyze legacy codebase
+specfact import from-code --bundle legacy-api --repo ./legacy-app
+
+ +

See Use Cases: Brownfield Modernization ⭐

+ +

Already Using Spec-Kit? (Secondary)

+ +

One-command import:

+ +
specfact import from-bridge --adapter speckit --repo . --write
+
+ +

See Use Cases: Spec-Kit Migration

+ +

Using AI Coding Tools?

+ +

Add validation layer:

+ +
    +
  1. Let AI generate code as usual
    2. +
  2. Run specfact import from-code --repo . (auto-detects CoPilot mode)
    3. +
  3. Review auto-generated plan
    4. +
  4. Enable specfact enforce stage --preset balanced
    5. +
+ +

With CoPilot Integration:

+ +

Use slash commands directly in your IDE:

+ +
# First, initialize IDE integration
+specfact init --ide cursor
+
+# Then use slash commands in IDE chat
+/specfact.01-import legacy-api --repo . --confidence 0.7
+/specfact.compare --bundle legacy-api
+/specfact.06-sync --repo . --bidirectional
+
+ +

SpecFact CLI automatically detects CoPilot and switches to enhanced mode.

+ +

Starting From Scratch?

+ +

Greenfield approach:

+ +
    +
  1. specfact plan init --bundle legacy-api --interactive
    2. +
  2. Add features and stories
    3. +
  3. Enable strict enforcement
    4. +
  4. Let SpecFact guide development
    5. +
+ +

See Getting Started for detailed setup.

+ +
+ +

See Getting Started for quick setup and Use Cases for detailed scenarios.

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/copilot-mode/index.html b/_site_local/copilot-mode/index.html new file mode 100644 index 0000000..5747f5d --- /dev/null +++ b/_site_local/copilot-mode/index.html @@ -0,0 +1,478 @@ + + + + + + + +Using CoPilot Mode | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Using CoPilot Mode

+ +

Status: ✅ AVAILABLE (v0.4.2+)
+Last Updated: 2025-11-02

+ +
+ +

Overview

+ +

SpecFact CLI supports two operational modes:

+ +
    +
  • CI/CD Mode (Default): Fast, deterministic execution for automation
    • +
  • CoPilot Mode: Interactive assistance with enhanced prompts for IDEs
    • +
+ +

Mode is auto-detected based on environment, or you can explicitly set it with --mode cicd or --mode copilot.

+ +
+ +

Quick Start

+ +

Quick Start Using CoPilot Mode

+ +
# Explicitly enable CoPilot mode
+specfact --mode copilot import from-code --bundle legacy-api --repo . --confidence 0.7
+
+# Mode is auto-detected based on environment (IDE integration, CoPilot API availability)
+specfact import from-code --bundle legacy-api --repo . --confidence 0.7  # Auto-detects CoPilot if available
+
+ +

What You Get with CoPilot Mode

+ +
    +
  • ✅ Enhanced prompts with context injection (current file, selection, workspace)
    • +
  • ✅ Agent routing for better analysis and planning
    • +
  • ✅ Context-aware execution optimized for interactive use
    • +
  • ✅ Better AI steering with detailed instructions
    • +
+ +
+ +

How It Works

+ +

Mode Detection

+ +

SpecFact CLI automatically detects the operational mode:

+ +
    +
  1. Explicit flag - --mode cicd or --mode copilot (highest priority)
    2. +
  2. Environment detection - Checks for CoPilot API availability, IDE integration
    3. +
  3. Default - Falls back to CI/CD mode if no CoPilot environment detected
    4. +
+ +

Agent Routing

+ +

In CoPilot mode, commands are routed through specialized agents:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandAgentPurpose
import from-codeAnalyzeAgentAI-first brownfield analysis with semantic understanding (multi-language support)
plan initPlanAgentPlan management with business logic understanding
plan comparePlanAgentPlan comparison with deviation analysis
sync bridge --adapter speckitSyncAgentBidirectional sync with conflict resolution
+ +

Context Injection

+ +

CoPilot mode automatically injects relevant context:

+ +
    +
  • Current file: Active file in IDE
    • +
  • Selection: Selected text/code
    • +
  • Workspace: Repository root path
    • +
  • Git context: Current branch, recent commits
    • +
  • Codebase context: Directory structure, files, dependencies
    • +
+ +

This context is used to generate enhanced prompts that instruct the AI IDE to:

+ +
    +
  • Understand the codebase semantically
    • +
  • Call the SpecFact CLI with appropriate arguments
    • +
  • Enhance CLI results with semantic understanding
    • +
+ +

Pragmatic Integration Benefits

+ +
    +
  • ✅ No separate LLM setup - Uses AI IDE’s existing LLM (Cursor, CoPilot, etc.)
    • +
  • ✅ No additional API costs - Leverages existing IDE infrastructure
    • +
  • ✅ Simpler architecture - No langchain, API keys, or complex integration
    • +
  • ✅ Better developer experience - Native IDE integration via slash commands
    • +
  • ✅ Streamlined workflow - AI understands codebase, CLI handles structured work
    • +
+ +
+ +

Examples

+ +

Example 1: Brownfield Analysis ⭐ PRIMARY

+ +
# CI/CD mode (fast, deterministic, Python-only)
+specfact --mode cicd import from-code --repo . --confidence 0.7
+
+# CoPilot mode (AI-first, semantic understanding, multi-language)
+specfact --mode copilot import from-code --repo . --confidence 0.7
+
+# Output (CoPilot mode):
+# Mode: CoPilot (AI-first analysis)
+# 🤖 AI-powered analysis (semantic understanding)...
+# ✓ AI analysis complete
+# ✓ Found X features
+# ✓ Detected themes: ...
+
+ +

Key Differences:

+ +
    +
  • CoPilot Mode: Uses LLM for semantic understanding, supports all languages, generates high-quality Spec-Kit artifacts
    • +
  • CI/CD Mode: Uses Python AST for fast analysis, Python-only, generates generic content (hardcoded fallbacks)
    • +
+ +

Example 2: Plan Initialization

+ +
# CI/CD mode (minimal prompts)
+specfact --mode cicd plan init --no-interactive
+
+# CoPilot mode (enhanced interactive prompts)
+specfact --mode copilot plan init --interactive
+
+# Output:
+# Mode: CoPilot (agent routing)
+# Agent prompt generated (XXX chars)
+# [enhanced interactive prompts]
+
+ +

Example 3: Plan Comparison

+ +
# CoPilot mode with enhanced deviation analysis (bundle directory paths)
+specfact --mode copilot plan compare \
+  --manual .specfact/projects/main \
+  --auto .specfact/projects/my-project-auto
+
+# Output:
+# Mode: CoPilot (agent routing)
+# Agent prompt generated (XXX chars)
+# [enhanced deviation analysis with context]
+
+ +
+ +

Mode Differences

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureCI/CD ModeCoPilot Mode
SpeedFast, deterministicSlightly slower, context-aware
OutputStructured, minimalEnhanced, detailed
PromptsStandardEnhanced with context
ContextMinimalFull context injection
Agent RoutingDirect executionAgent-based routing
Use CaseAutomation, CI/CDInteractive development, IDE
+ +
+ +

When to Use Each Mode

+ +

Use CI/CD Mode When

+ +
    +
  • ✅ Running in CI/CD pipelines
    • +
  • ✅ Automating workflows
    • +
  • ✅ Need fast, deterministic execution
    • +
  • ✅ Don’t need enhanced prompts
    • +
+ +

Use CoPilot Mode When

+ +
    +
  • ✅ Working in IDE with AI assistance
    • +
  • ✅ Need enhanced prompts for better AI steering
    • +
  • ✅ Want context-aware execution
    • +
  • ✅ Interactive development workflows
    • +
+ +
+ +

IDE Integration

+ +

For IDE integration with slash commands, see:

+ + + +
+ + + + + +
+ +

Next Steps

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/directory-structure/index.html b/_site_local/directory-structure/index.html new file mode 100644 index 0000000..b7aeafb --- /dev/null +++ b/_site_local/directory-structure/index.html @@ -0,0 +1,1064 @@ + + + + + + + +SpecFact CLI Directory Structure | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

SpecFact CLI Directory Structure

+ +

This document defines the canonical directory structure for SpecFact CLI artifacts.

+ +
+

Primary Use Case: SpecFact CLI is designed for brownfield code modernization - reverse-engineering existing codebases into documented specs with runtime contract enforcement. The directory structure reflects this brownfield-first approach.

+
+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

+ +

Overview

+ +

All SpecFact artifacts are stored under .specfact/ in the repository root. This ensures:

+ +
    +
  • Consistency: All artifacts in one predictable location
    • +
  • Multiple plans: Support for multiple plan bundles in a single repository
    • +
  • Gitignore-friendly: Easy to exclude reports from version control
    • +
  • Clear separation: Plans (versioned) vs reports (ephemeral)
    • +
  • CLI-first: All artifacts are local, no cloud storage required
    • +
+ +

Canonical Structure

+ +
.specfact/
+├── config.yaml              # SpecFact configuration (optional)
+├── config/                  # Global configuration (optional)
+│   ├── bridge.yaml          # Bridge configuration for external tools
+│   └── ...
+├── cache/                   # Shared cache (gitignored, global for performance)
+│   ├── dependency-graph.json
+│   └── commit-history.json
+├── projects/                # Modular project bundles (versioned in git)
+│   ├── <bundle-name>/       # Project bundle directory
+│   │   ├── bundle.manifest.yaml  # Bundle metadata, versioning, and checksums
+│   │   ├── idea.yaml             # Product vision (optional)
+│   │   ├── business.yaml         # Business context (optional)
+│   │   ├── product.yaml          # Releases, themes (required)
+│   │   ├── clarifications.yaml   # Clarification sessions (optional)
+│   │   ├── sdd.yaml              # SDD manifest (bundle-specific, Phase 8.5)
+│   │   ├── tasks.yaml            # Task breakdown (bundle-specific, Phase 8.5)
+│   │   ├── features/             # Individual feature files
+│   │   │   ├── FEATURE-001.yaml
+│   │   │   ├── FEATURE-002.yaml
+│   │   │   └── ...
+│   │   ├── contracts/            # OpenAPI contracts (bundle-specific)
+│   │   │   └── ...
+│   │   ├── protocols/            # FSM protocols (bundle-specific)
+│   │   │   └── ...
+│   │   ├── reports/              # Bundle-specific reports (gitignored, Phase 8.5)
+│   │   │   ├── brownfield/
+│   │   │   │   └── analysis-2025-10-31T14-30-00.md
+│   │   │   ├── comparison/
+│   │   │   │   └── report-2025-10-31T14-30-00.md
+│   │   │   ├── enrichment/
+│   │   │   │   └── <bundle-name>-2025-10-31T14-30-00.enrichment.md
+│   │   │   └── enforcement/
+│   │   │       └── report-2025-10-31T14-30-00.yaml
+│   │   ├── logs/                 # Bundle-specific logs (gitignored, Phase 8.5)
+│   │   │   └── 2025-10-31T14-30-00.log
+│   │   └── prompts/              # AI IDE contract enhancement prompts (optional)
+│   │       └── enhance-<filename>-<contracts>.md
+│   ├── legacy-api/         # Example: Brownfield-derived bundle
+│   │   ├── bundle.manifest.yaml
+│   │   ├── product.yaml
+│   │   ├── sdd.yaml
+│   │   ├── tasks.yaml
+│   │   ├── features/
+│   │   ├── reports/
+│   │   └── logs/
+│   └── my-project/          # Example: Main project bundle
+│       ├── bundle.manifest.yaml
+│       ├── idea.yaml
+│       ├── business.yaml
+│       ├── product.yaml
+│       ├── sdd.yaml
+│       ├── tasks.yaml
+│       ├── features/
+│       ├── reports/
+│       └── logs/
+└── gates/                   # Enforcement configuration (global)
+    └── config.yaml          # Enforcement settings (versioned)
+
+ +

Directory Purposes

+ +

.specfact/projects/ (Versioned)

+ +

Purpose: Store modular project bundles that define the contract for the project.

+ +

Guidelines:

+ +
    +
  • Each project bundle is stored in its own directory: .specfact/projects/<bundle-name>/
    • +
  • Each bundle directory contains multiple aspect files: +
      +
    • bundle.manifest.yaml - Bundle metadata, versioning, checksums, and feature index (required) +
        +
      • Schema Versioning: Set schema_metadata.schema_version to "1.1" to enable change tracking (v0.21.1+)
        • +
      • Change Tracking (v1.1+): Optional change_tracking and change_archive fields are loaded via bridge adapters (not stored in bundle directory) +
          +
        • change_tracking: Active change proposals and feature deltas (loaded from external tools like OpenSpec)
          • +
        • change_archive: Completed changes with audit trail (loaded from external tools)
          • +
        • Both fields are optional and backward compatible - v1.0 bundles work without them
          • +
        +
        • +
      • See Schema Versioning for details
        • +
      +
      • +
    • product.yaml - Product definition with themes and releases (required)
      • +
    • idea.yaml - Product vision and intent (optional)
      • +
    • business.yaml - Business context and market segments (optional)
      • +
    • clarifications.yaml - Clarification sessions and Q&A (optional)
      • +
    • sdd.yaml - SDD manifest (bundle-specific, Phase 8.5, versioned)
      • +
    • tasks.yaml - Task breakdown (bundle-specific, Phase 8.5, versioned)
      • +
    • features/ - Directory containing individual feature files: +
        +
      • FEATURE-001.yaml - Individual feature with stories
        • +
      • FEATURE-002.yaml - Individual feature with stories
        • +
      • Each feature file is self-contained with its stories, acceptance criteria, etc.
        • +
      +
      • +
    • contracts/ - OpenAPI contract files (bundle-specific, versioned)
      • +
    • protocols/ - FSM protocol definitions (bundle-specific, versioned)
      • +
    • reports/ - Bundle-specific analysis reports (gitignored, Phase 8.5)
      • +
    • logs/ - Bundle-specific execution logs (gitignored, Phase 8.5)
      • +
    +
    • +
  • Always committed to git - these are the source of truth (except reports/ and logs/)
    • +
  • Phase 8.5: All bundle-specific artifacts are stored within bundle folders for better isolation
    • +
  • Use descriptive bundle names: legacy-api, my-project, feature-auth
    • +
  • Supports multiple bundles per repository for brownfield modernization, monorepos, or feature branches
    • +
  • Aspect files are YAML format (JSON support may be added in future)
    • +
+ +

Plan Bundle Structure:

+ +

Plan bundles are YAML (or JSON) files with the following structure:

+ +
version: "1.1"  # Schema version (current: 1.1)
+
+metadata:
+  stage: "draft"  # draft, review, approved, released
+  summary:  # Summary metadata for fast access (added in v1.1)
+    features_count: 5
+    stories_count: 12
+    themes_count: 2
+    releases_count: 1
+    content_hash: "abc123def456..."  # SHA256 hash for integrity
+    computed_at: "2025-01-15T10:30:00"
+
+idea:
+  title: "Project Title"
+  narrative: "Project description"
+  # ... other idea fields
+
+product:
+  themes: ["Theme1", "Theme2"]
+  releases: [...]
+
+features:
+  - key: "FEATURE-001"
+    title: "Feature Title"
+    stories: [...]
+    # ... other feature fields
+
+ +

Bundle Manifest Structure (bundle.manifest.yaml):

+ +

The bundle.manifest.yaml file contains bundle metadata and (in v1.1+) optional change tracking fields:

+ +
schema_metadata:
+  schema_version: "1.1"  # Set to "1.1" to enable change tracking (v0.21.1+)
+  project_version: "0.1.0"
+
+# ... other manifest fields (checksums, feature index, etc.)
+
+# Optional change tracking fields (v1.1+, loaded via bridge adapters)
+change_tracking: null  # Optional - loaded via bridge adapters (not stored in bundle directory)
+change_archive: []     # Optional - list of archived changes (not stored in bundle directory)
+
+ +

Note: The change_tracking and change_archive fields are optional and loaded dynamically via bridge adapters (e.g., OpenSpec adapter) rather than being stored directly in the bundle directory. This allows change tracking to be managed by external tools while keeping bundles tool-agnostic. See Schema Versioning for details.

+ +

Summary Metadata (v1.1+):

+ +

Plan bundles version 1.1 and later include summary metadata in the metadata.summary section. This provides:

+ +
    +
  • Fast access: Read plan counts without parsing entire file (44% faster performance)
    • +
  • Integrity verification: Content hash detects plan modifications
    • +
  • Performance optimization: Only reads first 50KB for large files (>10MB)
    • +
+ +

Upgrading Plan Bundles:

+ +

Use specfact plan upgrade to migrate older plan bundles to the latest schema:

+ +
# Upgrade active plan
+specfact plan upgrade
+
+# Upgrade all plans
+specfact plan upgrade --all
+
+# Preview upgrades
+specfact plan upgrade --dry-run
+
+ +

See plan upgrade for details.

+ +

Example:

+ +
.specfact/projects/
+├── my-project/                    # Primary project bundle
+│   ├── bundle.manifest.yaml       # Metadata, checksums, feature index
+│   ├── idea.yaml                  # Product vision
+│   ├── business.yaml              # Business context
+│   ├── product.yaml               # Themes and releases
+│   ├── features/                  # Individual feature files
+│   │   ├── FEATURE-001.yaml
+│   │   ├── FEATURE-002.yaml
+│   │   └── FEATURE-003.yaml
+│   └── prompts/                   # AI IDE contract enhancement prompts (optional)
+│       └── enhance-<filename>-<contracts>.md
+├── legacy-api/                    # ⭐ Reverse-engineered from existing API (brownfield)
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   ├── features/
+│   │   ├── FEATURE-AUTH.yaml
+│   │   └── FEATURE-PAYMENT.yaml
+│   └── prompts/                   # Bundle-specific prompts (avoids conflicts)
+│       └── enhance-<filename>-<contracts>.md
+├── legacy-payment/                 # ⭐ Reverse-engineered from existing payment system (brownfield)
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   └── features/
+│       └── FEATURE-PAYMENT.yaml
+└── feature-auth/                   # Auth feature bundle
+    ├── bundle.manifest.yaml
+    ├── product.yaml
+    └── features/
+        └── FEATURE-AUTH.yaml
+
+ +

.specfact/protocols/ (Versioned)

+ +

Purpose: Store FSM (Finite State Machine) protocol definitions.

+ +

Guidelines:

+ +
    +
  • Define valid states and transitions
    • +
  • Always committed to git
    • +
  • Used for workflow validation
    • +
+ +

Example:

+ +
.specfact/protocols/
+├── development-workflow.protocol.yaml
+└── deployment-pipeline.protocol.yaml
+
+ +

Bundle-Specific Artifacts (Phase 8.5)

+ +

Phase 8.5 Update: All bundle-specific artifacts are now stored within .specfact/projects/<bundle-name>/ folders for better isolation and organization.

+ +

Bundle-Specific Artifacts:

+ +
    +
  • Reports: .specfact/projects/<bundle-name>/reports/ (gitignored) +
      +
    • brownfield/ - Brownfield analysis reports
      • +
    • comparison/ - Plan comparison reports
      • +
    • enrichment/ - LLM enrichment reports
      • +
    • enforcement/ - SDD enforcement validation reports
      • +
    +
    • +
  • SDD Manifests: .specfact/projects/<bundle-name>/sdd.yaml (versioned)
    • +
  • Tasks: .specfact/projects/<bundle-name>/tasks.yaml (versioned)
    • +
  • Logs: .specfact/projects/<bundle-name>/logs/ (gitignored)
    • +
+ +

Migration: Use specfact migrate artifacts to move existing artifacts from global locations to bundle-specific folders.

+ +

Example:

+ +
.specfact/projects/legacy-api/
+├── bundle.manifest.yaml
+├── product.yaml
+├── sdd.yaml                    # Bundle-specific SDD manifest
+├── tasks.yaml                  # Bundle-specific task breakdown
+├── reports/                    # Bundle-specific reports (gitignored)
+│   ├── brownfield/
+│   │   └── analysis-2025-10-31T14-30-00.md
+│   ├── comparison/
+│   │   └── report-2025-10-31T14-30-00.md
+│   ├── enrichment/
+│   │   └── legacy-api-2025-10-31T14-30-00.enrichment.md
+│   └── enforcement/
+│       └── report-2025-10-31T14-30-00.yaml
+└── logs/                       # Bundle-specific logs (gitignored)
+    └── 2025-10-31T14-30-00.log
+
+ +

Legacy Global Locations (Removed)

+ +

Note: The following global locations have been removed (Phase 8.5):

+ +
    +
  • ❌ .specfact/plans/ - Removed (active bundle config migrated to .specfact/config.yaml)
    • +
  • ❌ .specfact/gates/results/ - Removed (enforcement reports are bundle-specific)
    • +
  • ❌ .specfact/reports/ - Removed (reports are bundle-specific)
    • +
  • ❌ .specfact/sdd/ - Removed (SDD manifests are bundle-specific)
    • +
  • ❌ .specfact/tasks/ - Removed (task files are bundle-specific)
    • +
+ +

Migration: Use specfact migrate cleanup-legacy to remove empty legacy directories, and specfact migrate artifacts to migrate existing artifacts to bundle-specific locations.

+ +

.specfact/gates/ (Versioned)

+ +

Purpose: Global enforcement configuration.

+ +

Guidelines:

+ +
    +
  • config.yaml is versioned (defines enforcement policy)
    • +
  • Enforcement reports are bundle-specific (stored in .specfact/projects/<bundle-name>/reports/enforcement/)
    • +
+ +

Example:

+ +
.specfact/gates/
+└── config.yaml              # Versioned: enforcement policy
+
+ +

Note: Enforcement execution reports are stored in bundle-specific locations (Phase 8.5):

+ +
    +
  • .specfact/projects/<bundle-name>/reports/enforcement/report-<timestamp>.yaml
    • +
+ +

.specfact/cache/ (Gitignored)

+ +

Purpose: Tool caches for faster execution.

+ +

Guidelines:

+ +
    +
  • Gitignored - optimization only
    • +
  • Safe to delete anytime
    • +
  • Automatically regenerated
    • +
+ +

Default Command Paths

+ +

specfact import from-code ⭐ PRIMARY

+ +

Primary use case: Reverse-engineer existing codebases into project bundles.

+ +
# Command syntax
+specfact import from-code <bundle-name> --repo . [OPTIONS]
+
+# Creates modular bundle at:
+.specfact/projects/<bundle-name>/
+├── bundle.manifest.yaml  # Bundle metadata, versioning, checksums, feature index
+├── product.yaml          # Product definition (required)
+├── idea.yaml            # Product vision (if provided)
+├── business.yaml        # Business context (if provided)
+└── features/            # Individual feature files
+    ├── FEATURE-001.yaml
+    ├── FEATURE-002.yaml
+    └── ...
+
+# Analysis report (bundle-specific, gitignored, Phase 8.5)
+.specfact/projects/<bundle-name>/reports/brownfield/analysis-<timestamp>.md
+
+ +

Example (brownfield modernization):

+ +
# Analyze legacy codebase
+specfact import from-code legacy-api --repo . --confidence 0.7
+
+# Creates:
+# - .specfact/projects/legacy-api/bundle.manifest.yaml (versioned)
+# - .specfact/projects/legacy-api/product.yaml (versioned)
+# - .specfact/projects/legacy-api/features/FEATURE-*.yaml (versioned, one per feature)
+# - .specfact/reports/brownfield/analysis-2025-10-31T14-30-00.md (gitignored)
+
+ +

specfact plan init (Alternative)

+ +

Alternative use case: Create new project bundles for greenfield projects.

+ +
# Command syntax
+specfact plan init <bundle-name> [OPTIONS]
+
+# Creates modular bundle at:
+.specfact/projects/<bundle-name>/
+├── bundle.manifest.yaml  # Bundle metadata and versioning
+├── product.yaml         # Product definition (required)
+├── idea.yaml           # Product vision (if provided via prompts)
+└── features/           # Empty features directory (created when first feature added)
+
+# Also creates (if --interactive):
+.specfact/config.yaml
+
+ +

specfact plan compare

+ +
# Compare two bundles (explicit paths to bundle directories)
+specfact plan compare \
+  --manual .specfact/projects/manual-plan \
+  --auto .specfact/projects/auto-derived \
+  --out .specfact/reports/comparison/report-*.md
+
+# Note: Commands accept bundle directory paths, not individual files
+
+ +

specfact sync bridge

+ +
# Sync with external tools (Spec-Kit, Linear, Jira, etc.)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Watch mode
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+# Sync files are tracked in .specfact/reports/sync/
+
+ +

specfact sync repository

+ +
# Sync code changes
+specfact sync repository --repo . --target .specfact
+
+# Watch mode
+specfact sync repository --repo . --watch --interval 5
+
+# Sync reports in .specfact/reports/sync/
+
+ +

specfact enforce stage

+ +
# Reads/writes
+.specfact/gates/config.yaml
+
+ +

specfact init

+ +

Initializes IDE integration by copying prompt templates to IDE-specific locations:

+ +
# Auto-detect IDE
+specfact init
+
+# Specify IDE explicitly
+specfact init --ide cursor
+specfact init --ide vscode
+specfact init --ide copilot
+
+ +

Creates IDE-specific directories:

+ +
    +
  • Cursor: .cursor/commands/ (markdown files)
    • +
  • VS Code / Copilot: .github/prompts/ (.prompt.md files) + .vscode/settings.json
    • +
  • Claude Code: .claude/commands/ (markdown files)
    • +
  • Gemini: .gemini/commands/ (TOML files)
    • +
  • Qwen: .qwen/commands/ (TOML files)
    • +
  • Other IDEs: See IDE Integration Guide
    • +
+ +

See IDE Integration Guide for complete setup instructions.

+ +

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via IDE integrations

+ +

Configuration File

+ +

.specfact/config.yaml (optional):

+ +
version: "1.0"
+
+# Default bundle to use (optional)
+default_bundle: my-project
+
+# Analysis settings
+analysis:
+  confidence_threshold: 0.7
+  exclude_patterns:
+    - "**/__pycache__/**"
+    - "**/node_modules/**"
+    - "**/venv/**"
+
+# Enforcement settings
+enforcement:
+  preset: balanced  # strict, balanced, minimal, shadow
+  budget_seconds: 120
+  fail_fast: false
+
+# Repro settings
+repro:
+  parallel: true
+  timeout: 300
+
+ +

IDE Integration Directories

+ +

When you run specfact init, prompt templates are copied to IDE-specific locations for slash command integration.

+ +

IDE-Specific Locations

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDEDirectoryFormatSettings File
Cursor.cursor/commands/MarkdownNone
VS Code / Copilot.github/prompts/.prompt.md.vscode/settings.json
Claude Code.claude/commands/MarkdownNone
Gemini.gemini/commands/TOMLNone
Qwen.qwen/commands/TOMLNone
opencode.opencode/command/MarkdownNone
Windsurf.windsurf/workflows/MarkdownNone
Kilo Code.kilocode/workflows/MarkdownNone
Auggie.augment/commands/MarkdownNone
Roo Code.roo/commands/MarkdownNone
CodeBuddy.codebuddy/commands/MarkdownNone
Amp.agents/commands/MarkdownNone
Amazon Q.amazonq/prompts/MarkdownNone
+ +

Example Structure (Cursor)

+ +
.cursor/
+└── commands/
+    ├── specfact.01-import.md
+    ├── specfact.02-plan.md
+    ├── specfact.03-review.md
+    ├── specfact.04-sdd.md
+    ├── specfact.05-enforce.md
+    ├── specfact.06-sync.md
+    ├── specfact.compare.md
+    └── specfact.validate.md
+
+ +

Example Structure (VS Code / Copilot)

+ +
.github/
+└── prompts/
+    ├── specfact.01-import.prompt.md
+    ├── specfact.02-plan.prompt.md
+    ├── specfact.03-review.prompt.md
+    ├── specfact.04-sdd.prompt.md
+    ├── specfact.05-enforce.prompt.md
+    ├── specfact.06-sync.prompt.md
+    ├── specfact.compare.prompt.md
+    └── specfact.validate.prompt.md
+.vscode/
+└── settings.json  # Updated with promptFilesRecommendations
+
+ +

Guidelines:

+ +
    +
  • Versioned - IDE directories are typically committed to git (team-shared configuration)
    • +
  • Templates - Prompt templates are read-only for the IDE, not modified by users
    • +
  • Settings - VS Code settings.json is merged (not overwritten) to preserve existing settings
    • +
  • Auto-discovery - IDEs automatically discover and register templates as slash commands
    • +
  • CLI-first - Works offline, no account required, no vendor lock-in
    • +
+ +

See IDE Integration Guide for detailed setup and usage.

+ +

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via IDE integrations

+ +
+ +

SpecFact CLI Package Structure

+ +

The SpecFact CLI package includes prompt templates that are copied to IDE locations:

+ +
specfact-cli/
+└── resources/
+    └── prompts/              # Prompt templates (in package)
+        ├── specfact.01-import.md
+        ├── specfact.02-plan.md
+        ├── specfact.03-review.md
+        ├── specfact.04-sdd.md
+        ├── specfact.05-enforce.md
+        ├── specfact.06-sync.md
+        ├── specfact.compare.md
+        ├── specfact.validate.md
+        └── shared/
+            └── cli-enforcement.md
+
+ +

These templates are:

+ +
    +
  • Packaged with SpecFact CLI
    • +
  • Copied to IDE locations by specfact init
    • +
  • Not modified by users (read-only templates)
    • +
+ +
+ +

.gitignore Recommendations

+ +

Add to .gitignore:

+ +
# SpecFact ephemeral artifacts
+.specfact/projects/*/reports/
+.specfact/projects/*/logs/
+.specfact/cache/
+
+# Keep these versioned
+!.specfact/projects/
+!.specfact/config.yaml
+!.specfact/gates/config.yaml
+
+# IDE integration directories (optional - typically versioned)
+# Uncomment if you don't want to commit IDE integration files
+# .cursor/commands/
+# .github/prompts/
+# .vscode/settings.json
+# .claude/commands/
+# .gemini/commands/
+# .qwen/commands/
+
+ +

Note: IDE integration directories are typically versioned (committed to git) so team members share the same slash commands. However, you can gitignore them if preferred.

+ +

Migration from Old Structure

+ +

If you have existing artifacts in other locations:

+ +
# Old structure (monolithic bundles, deprecated)
+.specfact/plans/<name>.bundle.<format>
+.specfact/reports/analysis.md
+
+# New structure (modular bundles)
+.specfact/projects/my-project/
+├── bundle.manifest.yaml
+└── bundle.yaml
+.specfact/reports/brownfield/analysis.md
+
+# Migration
+mkdir -p .specfact/projects/my-project .specfact/reports/brownfield
+# Convert monolithic bundle to modular bundle structure
+# (Use 'specfact plan upgrade' or manual conversion)
+mv reports/analysis.md .specfact/reports/brownfield/
+
+ +

Multiple Plans in One Repository

+ +

SpecFact supports multiple plan bundles for:

+ +
    +
  • Brownfield modernization ⭐ PRIMARY: Separate plans for legacy components vs modernized code
    • +
  • Monorepos: One plan per service
    • +
  • Feature branches: Feature-specific plans
    • +
+ +

Example (Brownfield Modernization):

+ +
.specfact/projects/
+├── my-project/                      # Overall project bundle
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   └── features/
+│       └── ...
+├── legacy-api/                      # ⭐ Reverse-engineered from existing API (brownfield)
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   └── features/
+│       ├── FEATURE-AUTH.yaml
+│       └── FEATURE-API.yaml
+├── legacy-payment/                  # ⭐ Reverse-engineered from existing payment system (brownfield)
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   └── features/
+│       └── FEATURE-PAYMENT.yaml
+├── modernized-api/                  # New API bundle (after modernization)
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   └── features/
+│       └── ...
+└── feature-new-auth/                # Experimental feature bundle
+    ├── bundle.manifest.yaml
+    ├── product.yaml
+    └── features/
+        └── FEATURE-AUTH.yaml
+
+ +

Usage (Brownfield Workflow):

+ +
# Step 1: Reverse-engineer legacy codebase
+specfact import from-code legacy-api \
+  --repo src/legacy-api \
+  --confidence 0.7
+
+# Step 2: Compare legacy vs modernized (use bundle directories, not files)
+specfact plan compare \
+  --manual .specfact/projects/legacy-api \
+  --auto .specfact/projects/modernized-api
+
+# Step 3: Analyze specific legacy component
+specfact import from-code legacy-payment \
+  --repo src/legacy-payment \
+  --confidence 0.7
+
+ +

Summary

+ +

SpecFact Artifacts

+ +
    +
  • .specfact/ - All SpecFact artifacts live here
    • +
  • projects/ and protocols/ - Versioned (git)
    • +
  • reports/, gates/results/, cache/ - Gitignored (ephemeral)
    • +
  • Modular bundles - Each bundle in its own directory with manifest and content files
    • +
  • Use descriptive bundle names - Supports multiple bundles per repo
    • +
  • Default paths always start with .specfact/ - Consistent and predictable
    • +
  • Timestamped reports - Auto-generated reports include timestamps for tracking
    • +
  • Bridge architecture - Bidirectional sync with external tools (Spec-Kit, Linear, Jira, etc.) via bridge adapters
    • +
+ +

IDE Integration

+ +
    +
  • IDE directories - Created by specfact init (e.g., .cursor/commands/, .github/prompts/)
    • +
  • Prompt templates - Copied from resources/prompts/ in SpecFact CLI package
    • +
  • Typically versioned - IDE directories are usually committed to git for team sharing
    • +
  • Auto-discovery - IDEs automatically discover and register templates as slash commands
    • +
  • Settings files - VS Code settings.json is merged (not overwritten)
    • +
+ +

Quick Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeLocationGit StatusPurpose
Project Bundles.specfact/projects/<bundle-name>/VersionedModular contract definitions
Bundle Prompts.specfact/projects/<bundle-name>/prompts/Versioned (optional)AI IDE contract enhancement prompts
Protocols.specfact/protocols/VersionedFSM definitions
Reports.specfact/reports/GitignoredAnalysis reports
Cache.specfact/cache/GitignoredTool caches
IDE Templates.cursor/commands/, .github/prompts/, etc.Versioned (recommended)Slash command templates
+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/examples/brownfield-data-pipeline.md b/_site_local/examples/brownfield-data-pipeline.md new file mode 100644 index 0000000..e3b1888 --- /dev/null +++ b/_site_local/examples/brownfield-data-pipeline.md @@ -0,0 +1,400 @@ +# Brownfield Example: Modernizing Legacy Data Pipeline + +> **Complete walkthrough: From undocumented ETL pipeline to contract-enforced data processing** + +--- + +## The Problem + +You inherited a 5-year-old Python data pipeline with: + +- ❌ No documentation +- ❌ No type hints +- ❌ No data validation +- ❌ Critical ETL jobs (can't risk breaking) +- ❌ Business logic embedded in transformations +- ❌ Original developers have left + +**Challenge:** Modernize from Python 2.7 → 3.12 without breaking production ETL jobs. + +--- + +## Step 1: Reverse Engineer Data Pipeline + +> **Note**: This example demonstrates the complete hard-SDD workflow, including SDD manifest creation, validation, and plan promotion gates. The SDD manifest serves as your "hard spec" - a canonical reference that prevents drift during modernization. + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. + +### Extract Specs from Legacy Pipeline + +```bash +# Analyze the legacy data pipeline +specfact import from-code customer-etl \ + --repo ./legacy-etl-pipeline \ + --language python + +``` + +### Output + +```text +✅ Analyzed 34 Python files +✅ Extracted 18 ETL jobs: + + - JOB-001: Customer Data Import (95% confidence) + - JOB-002: Order Data Transformation (92% confidence) + - JOB-003: Payment Data Aggregation (88% confidence) + ... +✅ Generated 67 user stories from pipeline code +✅ Detected 6 edge cases with CrossHair symbolic execution +⏱️ Completed in 7.5 seconds +``` + +### What You Get + +**Auto-generated pipeline documentation:** + +```yaml +features: + + - key: JOB-002 + name: Order Data Transformation + description: Transform raw order data into normalized format + stories: + + - key: STORY-002-001 + title: Transform order records + description: Transform order data with validation + acceptance_criteria: + + - Input: Raw order records (CSV/JSON) + - Validation: Order ID must be positive integer + - Validation: Amount must be positive decimal + - Output: Normalized order records +``` + +--- + +## Step 2: Create Hard SDD Manifest + +After extracting the plan, create a hard SDD manifest: + +```bash +# Create SDD manifest from the extracted plan +specfact plan harden customer-etl +``` + +### Output + +```text +✅ SDD manifest created: .specfact/projects//sdd.yaml + +📋 SDD Summary: + WHY: Modernize legacy ETL pipeline with zero data corruption + WHAT: 18 ETL jobs, 67 stories extracted from legacy code + HOW: Runtime contracts, data validation, incremental enforcement + +🔗 Linked to plan: customer-etl (hash: ghi789jkl012...) +📊 Coverage thresholds: + - Contracts per story: 1.0 (minimum) + - Invariants per feature: 2.0 (minimum) + - Architecture facets: 3 (minimum) +``` + +--- + +## Step 3: Validate SDD Before Modernization + +Validate that your SDD manifest matches your plan: + +```bash +# Validate SDD manifest against plan +specfact enforce sdd customer-etl +``` + +### Output + +```text +✅ Hash match verified +✅ Contracts/story: 1.1 (threshold: 1.0) ✓ +✅ Invariants/feature: 2.3 (threshold: 2.0) ✓ +✅ Architecture facets: 4 (threshold: 3) ✓ + +✅ SDD validation passed +``` + +--- + +## Step 4: Promote Plan with SDD Validation + +Promote your plan to "review" stage (requires valid SDD): + +```bash +# Promote plan to review stage +specfact plan promote customer-etl --stage review +``` + +**Why this matters**: Plan promotion enforces SDD presence, ensuring you have a hard spec before starting modernization work. + +--- + +## Step 5: Add Contracts to Data Transformations + +### Before: Undocumented Legacy Transformation + +```python +# transformations/orders.py (legacy code) +def transform_order(raw_order): + """Transform raw order data""" + order_id = raw_order.get('id') + amount = float(raw_order.get('amount', 0)) + customer_id = raw_order.get('customer_id') + + # 50 lines of legacy transformation logic + # Hidden business rules: + # - Order ID must be positive integer + # - Amount must be positive decimal + # - Customer ID must be valid + ... + + return { + 'order_id': order_id, + 'amount': amount, + 'customer_id': customer_id, + 'status': 'processed' + } + +``` + +### After: Contract-Enforced Transformation + +```python +# transformations/orders.py (modernized with contracts) +import icontract +from typing import Dict, Any + +@icontract.require( + lambda raw_order: isinstance(raw_order.get('id'), int) and raw_order['id'] > 0, + "Order ID must be positive integer" +) +@icontract.require( + lambda raw_order: float(raw_order.get('amount', 0)) > 0, + "Order amount must be positive decimal" +) +@icontract.require( + lambda raw_order: raw_order.get('customer_id') is not None, + "Customer ID must be present" +) +@icontract.ensure( + lambda result: 'order_id' in result and 'amount' in result, + "Result must contain order_id and amount" +) +def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]: + """Transform raw order data with runtime contract enforcement""" + order_id = raw_order['id'] + amount = float(raw_order['amount']) + customer_id = raw_order['customer_id'] + + # Same 50 lines of legacy transformation logic + # Now with runtime enforcement + + return { + 'order_id': order_id, + 'amount': amount, + 'customer_id': customer_id, + 'status': 'processed' + } +``` + +### Re-validate SDD After Adding Contracts + +After adding contracts, re-validate your SDD: + +```bash +specfact enforce sdd customer-etl +``` + +--- + +## Step 6: Discover Data Edge Cases + +### Run CrossHair on Data Transformations + +```bash +# Discover edge cases in order transformation +hatch run contract-explore transformations/orders.py + +``` + +### CrossHair Output + +```text +🔍 Exploring contracts in transformations/orders.py... + +❌ Precondition violation found: + Function: transform_order + Input: raw_order={'id': 0, 'amount': '100.50', 'customer_id': 123} + Issue: Order ID must be positive integer (got 0) + +❌ Precondition violation found: + Function: transform_order + Input: raw_order={'id': 456, 'amount': '-50.00', 'customer_id': 123} + Issue: Order amount must be positive decimal (got -50.0) + +✅ Contract exploration complete + - 2 violations found + - 0 false positives + - Time: 10.2 seconds + +``` + +### Add Data Validation + +```python +# Add data validation based on CrossHair findings +@icontract.require( + lambda raw_order: isinstance(raw_order.get('id'), int) and raw_order['id'] > 0, + "Order ID must be positive integer" +) +@icontract.require( + lambda raw_order: isinstance(raw_order.get('amount'), (int, float, str)) and + float(raw_order.get('amount', 0)) > 0, + "Order amount must be positive decimal" +) +def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]: + """Transform with enhanced validation""" + # Handle string amounts (common in CSV imports) + amount = float(raw_order['amount']) if isinstance(raw_order['amount'], str) else raw_order['amount'] + ... +``` + +--- + +## Step 7: Modernize Pipeline Safely + +### Refactor with Contract Safety Net + +```python +# Modernized version (same contracts) +@icontract.require(...) # Same contracts as before +def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]: + """Modernized order transformation with contract safety net""" + + # Modernized implementation (Python 3.12) + order_id: int = raw_order['id'] + amount: float = float(raw_order['amount']) if isinstance(raw_order['amount'], str) else raw_order['amount'] + customer_id: int = raw_order['customer_id'] + + # Modernized transformation logic + transformed = OrderTransformer().transform( + order_id=order_id, + amount=amount, + customer_id=customer_id + ) + + return { + 'order_id': transformed.order_id, + 'amount': transformed.amount, + 'customer_id': transformed.customer_id, + 'status': 'processed' + } + +``` + +### Catch Data Pipeline Regressions + +```python +# During modernization, accidentally break contract: +# Missing amount validation in refactored code + +# Runtime enforcement catches it: +# ❌ ContractViolation: Order amount must be positive decimal (got -50.0) +# at transform_order() call from etl_job.py:142 +# → Prevented data corruption in production ETL! +``` + +--- + +## Results + +### Quantified Outcomes + +| Metric | Before SpecFact | After SpecFact | Improvement | +|--------|----------------|----------------|-------------| +| **Pipeline documentation** | 0% (none) | 100% (auto-generated) | **∞ improvement** | +| **Data validation** | Manual (error-prone) | Automated (contracts) | **100% coverage** | +| **Edge cases discovered** | 0-2 (manual) | 6 (CrossHair) | **3x more** | +| **Data corruption prevented** | 0 (no safety net) | 11 incidents | **∞ improvement** | +| **Migration time** | 8 weeks (cautious) | 3 weeks (confident) | **62% faster** | + +### Case Study: Customer ETL Pipeline + +**Challenge:** + +- 5-year-old Python data pipeline (12K LOC) +- No documentation, original developers left +- Needed modernization from Python 2.7 → 3.12 +- Fear of breaking critical ETL jobs + +**Solution:** + +1. Ran `specfact import from-code` → 47 features extracted in 12 seconds +2. Added contracts to 23 critical data transformation functions +3. CrossHair discovered 6 edge cases in legacy validation logic +4. Enforced contracts during migration, blocked 11 regressions + +**Results:** + +- ✅ 87% faster documentation (8 hours vs. 60 hours manual) +- ✅ 11 production bugs prevented during migration +- ✅ Zero downtime migration completed in 3 weeks vs. estimated 8 weeks +- ✅ New team members productive in days vs. weeks + +**ROI:** $42,000 saved, 5-week acceleration + +--- + +## Integration with Your Workflow + +SpecFact CLI integrates seamlessly with your existing tools: + +- **VS Code**: Use pre-commit hooks to catch breaking changes before commit +- **Cursor**: AI assistant workflows catch regressions during refactoring +- **GitHub Actions**: CI/CD integration blocks bad code from merging +- **Pre-commit hooks**: Local validation prevents breaking changes +- **Any IDE**: Pure CLI-first approach—works with any editor + +**See real examples**: [Integration Showcases](integration-showcases/) - 5 complete examples showing bugs fixed via integrations + +## Key Takeaways + +### What Worked Well + +1. ✅ **code2spec** extracted pipeline structure automatically +2. ✅ **SDD manifest** created hard spec reference, preventing drift +3. ✅ **SDD validation** ensured coverage thresholds before modernization +4. ✅ **Plan promotion gates** required SDD presence, enforcing discipline +5. ✅ **Contracts** enforced data validation at runtime +6. ✅ **CrossHair** discovered edge cases in data transformations +7. ✅ **Incremental modernization** reduced risk +8. ✅ **CLI-first integration** - Works offline, no account required, no vendor lock-in + +### Lessons Learned + +1. **Start with critical jobs** - Maximum impact, minimum risk +2. **Validate data early** - Contracts catch bad data before processing +3. **Test edge cases** - Run CrossHair on data transformations +4. **Monitor in production** - Keep contracts enabled to catch regressions + +--- + +## Next Steps + +1. **[Integration Showcases](integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations +2. **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** - Complete modernization workflow +3. **[Django Example](brownfield-django-modernization.md)** - Web app modernization +4. **[Flask API Example](brownfield-flask-api.md)** - API modernization + +--- + +**Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) | [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_local/examples/brownfield-django-modernization.md b/_site_local/examples/brownfield-django-modernization.md new file mode 100644 index 0000000..d204565 --- /dev/null +++ b/_site_local/examples/brownfield-django-modernization.md @@ -0,0 +1,496 @@ +# Brownfield Example: Modernizing Legacy Django Code + +> **Complete walkthrough: From undocumented legacy Django app to contract-enforced modern codebase** + +--- + +## The Problem + +You inherited a 3-year-old Django app with: + +- ❌ No documentation +- ❌ No type hints +- ❌ No tests +- ❌ 15 undocumented API endpoints +- ❌ Business logic buried in views +- ❌ Original developers have left + +**Sound familiar?** This is a common brownfield scenario. + +--- + +## Step 1: Reverse Engineer with SpecFact + +> **Note**: This example demonstrates the complete hard-SDD workflow, including SDD manifest creation, validation, and plan promotion gates. The SDD manifest serves as your "hard spec" - a canonical reference that prevents drift during modernization. + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. + +### Extract Specs from Legacy Code + +```bash +# Analyze the legacy Django app +specfact import from-code customer-portal \ + --repo ./legacy-django-app \ + --language python + +``` + +### Output + +```text +✅ Analyzed 47 Python files +✅ Extracted 23 features: + + - FEATURE-001: User Authentication (95% confidence) + - Stories: Login, Logout, Password Reset, Session Management + - FEATURE-002: Payment Processing (92% confidence) + - Stories: Process Payment, Refund, Payment History + - FEATURE-003: Order Management (88% confidence) + - Stories: Create Order, Update Order, Cancel Order + ... +✅ Generated 112 user stories from existing code patterns +✅ Dependency graph: 8 modules, 23 dependencies +⏱️ Completed in 8.2 seconds +``` + +### What You Get + +**Auto-generated project bundle** (`.specfact/projects/customer-portal/` - modular structure): + +```yaml +features: + + - key: FEATURE-002 + name: Payment Processing + description: Process payments for customer orders + stories: + + - key: STORY-002-001 + title: Process payment for order + description: Process payment with amount and currency + acceptance_criteria: + + - Amount must be positive decimal + - Supported currencies: USD, EUR, GBP + - Returns SUCCESS or FAILED status +``` + +**Time saved:** 60-120 hours of manual documentation → **8 seconds** + +--- + +## Step 2: Create Hard SDD Manifest + +After extracting the plan, create a hard SDD (Spec-Driven Development) manifest that captures WHY, WHAT, and HOW: + +```bash +# Create SDD manifest from the extracted plan +specfact plan harden customer-portal +``` + +### Output + +```text +✅ SDD manifest created: .specfact/projects//sdd.yaml + +📋 SDD Summary: + WHY: Modernize legacy Django customer portal with zero downtime + WHAT: 23 features, 112 stories extracted from legacy code + HOW: Runtime contracts, symbolic execution, incremental enforcement + +🔗 Linked to plan: customer-portal (hash: abc123def456...) +📊 Coverage thresholds: + - Contracts per story: 1.0 (minimum) + - Invariants per feature: 2.0 (minimum) + - Architecture facets: 3 (minimum) + +✅ SDD manifest saved to .specfact/projects//sdd.yaml +``` + +### What You Get + +**SDD manifest** (`.specfact/projects//sdd.yaml`, Phase 8.5) captures: + +- **WHY**: Intent, constraints, target users, value hypothesis +- **WHAT**: Capabilities, acceptance criteria, out-of-scope items +- **HOW**: Architecture, invariants, contracts, module boundaries +- **Coverage thresholds**: Minimum contracts/story, invariants/feature, architecture facets +- **Plan linkage**: Hash-linked to plan bundle for drift detection + +**Why this matters**: The SDD manifest serves as your "hard spec" - a canonical reference that prevents drift between your plan and implementation during modernization. + +--- + +## Step 3: Validate SDD Before Modernization + +Before starting modernization, validate that your SDD manifest matches your plan: + +```bash +# Validate SDD manifest against plan +specfact enforce sdd customer-portal +``` + +### Output + +```text +✅ Loading SDD manifest: .specfact/projects/customer-portal/sdd.yaml +✅ Loading project bundle: .specfact/projects/customer-portal/ + +🔍 Validating hash match... +✅ Hash match verified + +🔍 Validating coverage thresholds... +✅ Contracts/story: 1.2 (threshold: 1.0) ✓ +✅ Invariants/feature: 2.5 (threshold: 2.0) ✓ +✅ Architecture facets: 4 (threshold: 3) ✓ + +✅ SDD validation passed +📄 Report saved to: .specfact/projects//reports/enforcement/report-2025-01-23T10-30-45.yaml +``` + +**If validation fails**, you'll see specific deviations: + +```text +❌ SDD validation failed + +🔍 Validating coverage thresholds... +⚠️ Contracts/story: 0.8 (threshold: 1.0) - Below threshold +⚠️ Invariants/feature: 1.5 (threshold: 2.0) - Below threshold + +📊 Validation report: + - 2 medium severity deviations + - Fix: Add contracts to stories or adjust thresholds + +💡 Run 'specfact plan harden' to update SDD manifest +``` + +--- + +## Step 4: Review Plan with SDD Validation + +Review your plan to identify ambiguities and ensure SDD compliance: + +```bash +# Review plan (automatically checks SDD, bundle name as positional argument) +specfact plan review customer-portal --max-questions 5 +``` + +### Output + +```text +📋 SpecFact CLI - Plan Review + +✅ Loading project bundle: .specfact/projects/customer-portal/ +✅ Current stage: draft + +🔍 Checking SDD manifest... +✅ SDD manifest validated successfully +ℹ️ Found 2 coverage threshold warning(s) + +❓ Questions to resolve ambiguities: + 1. Q001: What is the expected response time for payment processing? + 2. Q002: Should password reset emails expire after 24 or 48 hours? + ... + +✅ Review complete: 5 questions identified +💡 Run 'specfact plan review --answers answers.json' to resolve in bulk +``` + +**SDD integration**: The review command automatically checks for SDD presence and validates coverage thresholds, warning you if thresholds aren't met. + +--- + +## Step 5: Promote Plan with SDD Validation + +Before starting modernization, promote your plan to "review" stage. This requires a valid SDD manifest: + +```bash +# Promote plan to review stage (requires SDD, bundle name as positional argument) +specfact plan promote customer-portal --stage review +``` + +### Output (Success) + +```text +📋 SpecFact CLI - Plan Promotion + +✅ Loading project bundle: .specfact/projects/customer-portal/ +✅ Current stage: draft +✅ Target stage: review + +🔍 Checking promotion rules... +🔍 Checking SDD manifest... +✅ SDD manifest validated successfully +ℹ️ Found 2 coverage threshold warning(s) + +✅ Promoted plan to stage: review +💡 Plan is now ready for modernization work +``` + +### Output (SDD Missing) + +```text +❌ SDD manifest is required for promotion to 'review' or higher stages +💡 Run 'specfact plan harden' to create SDD manifest +``` + +**Why this matters**: Plan promotion now enforces SDD presence, ensuring you have a hard spec before starting modernization work. This prevents drift and ensures coverage thresholds are met. + +--- + +## Step 6: Add Contracts to Critical Paths + +### Identify Critical Functions + +Review the extracted plan to identify high-risk functions: + +```bash +# Review extracted plan using CLI commands +specfact plan review customer-portal + +``` + +### Before: Undocumented Legacy Function + +```python +# views/payment.py (legacy code) +def process_payment(request, order_id): + """Process payment for order""" + order = Order.objects.get(id=order_id) + amount = float(request.POST.get('amount')) + currency = request.POST.get('currency') + + # 80 lines of legacy payment logic + # Hidden business rules: + # - Amount must be positive + # - Currency must be USD, EUR, or GBP + # - Returns PaymentResult with status + ... + + return PaymentResult(status='SUCCESS') + +``` + +### After: Contract-Enforced Function + +```python +# views/payment.py (modernized with contracts) +import icontract +from typing import Literal + +@icontract.require( + lambda amount: amount > 0, + "Payment amount must be positive" +) +@icontract.require( + lambda currency: currency in ['USD', 'EUR', 'GBP'], + "Currency must be USD, EUR, or GBP" +) +@icontract.ensure( + lambda result: result.status in ['SUCCESS', 'FAILED'], + "Payment result must have valid status" +) +def process_payment( + request, + order_id: int, + amount: float, + currency: Literal['USD', 'EUR', 'GBP'] +) -> PaymentResult: + """Process payment for order with runtime contract enforcement""" + order = Order.objects.get(id=order_id) + + # Same 80 lines of legacy payment logic + # Now with runtime enforcement + + return PaymentResult(status='SUCCESS') +``` + +**What this gives you:** + +- ✅ Runtime validation catches invalid inputs immediately +- ✅ Prevents regressions during refactoring +- ✅ Documents expected behavior (executable documentation) +- ✅ CrossHair discovers edge cases automatically + +### Re-validate SDD After Adding Contracts + +After adding contracts, re-validate your SDD to ensure coverage thresholds are met: + +```bash +# Re-validate SDD after adding contracts +specfact enforce sdd customer-portal +``` + +This ensures your SDD manifest reflects the current state of your codebase and that coverage thresholds are maintained. + +--- + +## Step 7: Discover Hidden Edge Cases + +### Run CrossHair Symbolic Execution + +```bash +# Discover edge cases in payment processing +hatch run contract-explore views/payment.py + +``` + +### CrossHair Output + +```text +🔍 Exploring contracts in views/payment.py... + +❌ Postcondition violation found: + Function: process_payment + Input: amount=0.0, currency='USD' + Issue: Amount must be positive (got 0.0) + +❌ Postcondition violation found: + Function: process_payment + Input: amount=-50.0, currency='USD' + Issue: Amount must be positive (got -50.0) + +✅ Contract exploration complete + - 2 violations found + - 0 false positives + - Time: 12.3 seconds + +``` + +### Fix Edge Cases + +```python +# Add validation for edge cases discovered by CrossHair +@icontract.require( + lambda amount: amount > 0 and amount <= 1000000, + "Payment amount must be between 0 and 1,000,000" +) +def process_payment(...): + # Now handles edge cases discovered by CrossHair + ... +``` + +--- + +## Step 8: Prevent Regressions During Modernization + +### Refactor Safely + +With contracts in place, refactor knowing violations will be caught: + +```python +# Refactored version (same contracts) +@icontract.require(lambda amount: amount > 0, "Payment amount must be positive") +@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP']) +@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED']) +def process_payment(request, order_id: int, amount: float, currency: str) -> PaymentResult: + """Modernized payment processing with contract safety net""" + + # Modernized implementation + order = get_order_or_404(order_id) + payment_service = PaymentService() + + try: + result = payment_service.process( + order=order, + amount=amount, + currency=currency + ) + return PaymentResult(status='SUCCESS', transaction_id=result.id) + except PaymentError as e: + return PaymentResult(status='FAILED', error=str(e)) + +``` + +### Catch Regressions Automatically + +```python +# During modernization, accidentally break contract: +process_payment(request, order_id=-1, amount=-50, currency="XYZ") + +# Runtime enforcement catches it: +# ❌ ContractViolation: Payment amount must be positive (got -50) +# at process_payment() call from refactored checkout.py:142 +# → Prevented production bug during modernization! +``` + +--- + +## Results + +### Quantified Outcomes + +| Metric | Before SpecFact | After SpecFact | Improvement | +|--------|----------------|----------------|-------------| +| **Documentation time** | 60-120 hours | 8 seconds | **99.9% faster** | +| **Production bugs prevented** | 0 (no safety net) | 4 bugs | **∞ improvement** | +| **Developer onboarding** | 2-3 weeks | 3-5 days | **60% faster** | +| **Edge cases discovered** | 0-2 (manual) | 6 (CrossHair) | **3x more** | +| **Refactoring confidence** | Low (fear of breaking) | High (contracts catch violations) | **Qualitative improvement** | + +### Time and Cost Savings + +**Manual approach:** + +- Documentation: 80-120 hours ($12,000-$18,000) +- Testing: 100-150 hours ($15,000-$22,500) +- Debugging regressions: 40-80 hours ($6,000-$12,000) +- **Total: 220-350 hours ($33,000-$52,500)** + +**SpecFact approach:** + +- code2spec extraction: 10 minutes ($25) +- Review and refine specs: 8-16 hours ($1,200-$2,400) +- Add contracts: 16-24 hours ($2,400-$3,600) +- CrossHair edge case discovery: 2-4 hours ($300-$600) +- **Total: 26-44 hours ($3,925-$6,625)** + +**ROI: 87% time saved, $26,000-$45,000 cost avoided** + +--- + +## Integration with Your Workflow + +SpecFact CLI integrates seamlessly with your existing tools: + +- **VS Code**: Use pre-commit hooks to catch breaking changes before commit +- **Cursor**: AI assistant workflows catch regressions during refactoring +- **GitHub Actions**: CI/CD integration blocks bad code from merging +- **Pre-commit hooks**: Local validation prevents breaking changes +- **Any IDE**: Pure CLI-first approach—works with any editor + +**See real examples**: [Integration Showcases](integration-showcases/) - 5 complete examples showing bugs fixed via integrations + +## Key Takeaways + +### What Worked Well + +1. ✅ **code2spec extraction** provided immediate value (< 10 seconds) +2. ✅ **SDD manifest** created hard spec reference, preventing drift during modernization +3. ✅ **SDD validation** ensured coverage thresholds before starting work +4. ✅ **Plan promotion gates** required SDD presence, enforcing discipline +5. ✅ **Runtime contracts** prevented 4 production bugs during refactoring +6. ✅ **CrossHair** discovered 6 edge cases manual testing missed +7. ✅ **Incremental approach** (shadow → warn → block) reduced risk +8. ✅ **CLI-first integration** - Works offline, no account required, no vendor lock-in + +### Lessons Learned + +1. **Start with critical paths** - Don't try to contract everything at once +2. **Use shadow mode first** - Observe violations before enforcing +3. **Run CrossHair early** - Discover edge cases before refactoring +4. **Document findings** - Keep notes on violations and edge cases + +--- + +## Next Steps + +1. **[Integration Showcases](integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations +2. **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** - Complete modernization workflow +3. **[ROI Calculator](../guides/brownfield-roi.md)** - Calculate your savings +4. **[Flask API Example](brownfield-flask-api.md)** - Another brownfield scenario +5. **[Data Pipeline Example](brownfield-data-pipeline.md)** - ETL modernization + +--- + +**Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) | [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_local/examples/brownfield-flask-api.md b/_site_local/examples/brownfield-flask-api.md new file mode 100644 index 0000000..30797c0 --- /dev/null +++ b/_site_local/examples/brownfield-flask-api.md @@ -0,0 +1,381 @@ +# Brownfield Example: Modernizing Legacy Flask API + +> **Complete walkthrough: From undocumented Flask API to contract-enforced modern service** + +--- + +## The Problem + +You inherited a 2-year-old Flask REST API with: + +- ❌ No OpenAPI/Swagger documentation +- ❌ No type hints +- ❌ No request validation +- ❌ 12 undocumented API endpoints +- ❌ Business logic mixed with route handlers +- ❌ No error handling standards + +--- + +## Step 1: Reverse Engineer API Endpoints + +> **Note**: This example demonstrates the complete hard-SDD workflow, including SDD manifest creation, validation, and plan promotion gates. The SDD manifest serves as your "hard spec" - a canonical reference that prevents drift during modernization. + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. + +### Extract Specs from Legacy Flask Code + +```bash +# Analyze the legacy Flask API +specfact import from-code customer-api \ + --repo ./legacy-flask-api \ + --language python + +``` + +### Output + +```text +✅ Analyzed 28 Python files +✅ Extracted 12 API endpoints: + + - POST /api/v1/users (User Registration) + - GET /api/v1/users/{id} (Get User) + - POST /api/v1/orders (Create Order) + - PUT /api/v1/orders/{id} (Update Order) + ... +✅ Generated 45 user stories from route handlers +✅ Detected 4 edge cases with CrossHair symbolic execution +⏱️ Completed in 6.8 seconds +``` + +### What You Get + +**Auto-generated API documentation** from route handlers: + +```yaml +features: + + - key: FEATURE-003 + name: Order Management API + description: REST API for order management + stories: + + - key: STORY-003-001 + title: Create order via POST /api/v1/orders + description: Create new order with items and customer ID + acceptance_criteria: + + - Request body must contain items array + - Each item must have product_id and quantity + - Customer ID must be valid integer + - Returns order object with status +``` + +--- + +## Step 2: Create Hard SDD Manifest + +After extracting the plan, create a hard SDD manifest: + +```bash +# Create SDD manifest from the extracted plan +specfact plan harden customer-api +``` + +### Output + +```text +✅ SDD manifest created: .specfact/projects//sdd.yaml + +📋 SDD Summary: + WHY: Modernize legacy Flask API with zero downtime + WHAT: 12 API endpoints, 45 stories extracted from legacy code + HOW: Runtime contracts, request validation, incremental enforcement + +🔗 Linked to plan: customer-api (hash: def456ghi789...) +📊 Coverage thresholds: + - Contracts per story: 1.0 (minimum) + - Invariants per feature: 2.0 (minimum) + - Architecture facets: 3 (minimum) +``` + +--- + +## Step 3: Validate SDD Before Modernization + +Validate that your SDD manifest matches your plan: + +```bash +# Validate SDD manifest against plan +specfact enforce sdd customer-api +``` + +### Output + +```text +✅ Hash match verified +✅ Contracts/story: 1.3 (threshold: 1.0) ✓ +✅ Invariants/feature: 2.8 (threshold: 2.0) ✓ +✅ Architecture facets: 4 (threshold: 3) ✓ + +✅ SDD validation passed +``` + +--- + +## Step 4: Promote Plan with SDD Validation + +Promote your plan to "review" stage (requires valid SDD): + +```bash +# Promote plan to review stage +specfact plan promote customer-api --stage review +``` + +**Why this matters**: Plan promotion enforces SDD presence, ensuring you have a hard spec before starting modernization work. + +--- + +## Step 5: Add Contracts to API Endpoints + +### Before: Undocumented Legacy Route + +```python +# routes/orders.py (legacy code) +@app.route('/api/v1/orders', methods=['POST']) +def create_order(): + """Create new order""" + data = request.get_json() + customer_id = data.get('customer_id') + items = data.get('items', []) + + # 60 lines of legacy order creation logic + # Hidden business rules: + # - Customer ID must be positive integer + # - Items must be non-empty array + # - Each item must have product_id and quantity > 0 + ... + + return jsonify({'order_id': order.id, 'status': 'created'}), 201 + +``` + +### After: Contract-Enforced Route + +```python +# routes/orders.py (modernized with contracts) +import icontract +from typing import List, Dict +from flask import request, jsonify + +@icontract.require( + lambda data: isinstance(data.get('customer_id'), int) and data['customer_id'] > 0, + "Customer ID must be positive integer" +) +@icontract.require( + lambda data: isinstance(data.get('items'), list) and len(data['items']) > 0, + "Items must be non-empty array" +) +@icontract.require( + lambda data: all( + isinstance(item, dict) and + 'product_id' in item and + 'quantity' in item and + item['quantity'] > 0 + for item in data.get('items', []) + ), + "Each item must have product_id and quantity > 0" +) +@icontract.ensure( + lambda result: result[1] == 201, + "Must return 201 status code" +) +@icontract.ensure( + lambda result: 'order_id' in result[0].json, + "Response must contain order_id" +) +def create_order(): + """Create new order with runtime contract enforcement""" + data = request.get_json() + customer_id = data['customer_id'] + items = data['items'] + + # Same 60 lines of legacy order creation logic + # Now with runtime enforcement + + return jsonify({'order_id': order.id, 'status': 'created'}), 201 +``` + +### Re-validate SDD After Adding Contracts + +After adding contracts, re-validate your SDD: + +```bash +specfact enforce sdd customer-api +``` + +--- + +## Step 6: Discover API Edge Cases + +### Run CrossHair on API Endpoints + +```bash +# Discover edge cases in order creation +hatch run contract-explore routes/orders.py + +``` + +### CrossHair Output + +```text +🔍 Exploring contracts in routes/orders.py... + +❌ Precondition violation found: + Function: create_order + Input: data={'customer_id': 0, 'items': [...]} + Issue: Customer ID must be positive integer (got 0) + +❌ Precondition violation found: + Function: create_order + Input: data={'customer_id': 123, 'items': []} + Issue: Items must be non-empty array (got []) + +✅ Contract exploration complete + - 2 violations found + - 0 false positives + - Time: 8.5 seconds + +``` + +### Add Request Validation + +```python +# Add Flask request validation based on CrossHair findings +from flask import request +from marshmallow import Schema, fields, ValidationError + +class CreateOrderSchema(Schema): + customer_id = fields.Int(required=True, validate=lambda x: x > 0) + items = fields.List( + fields.Dict(keys=fields.Str(), values=fields.Raw()), + required=True, + validate=lambda x: len(x) > 0 + ) + +@app.route('/api/v1/orders', methods=['POST']) +@icontract.require(...) # Keep contracts for runtime enforcement +def create_order(): + """Create new order with request validation + contract enforcement""" + try: + data = CreateOrderSchema().load(request.get_json()) + except ValidationError as e: + return jsonify({'error': e.messages}), 400 + + # Process order with validated data + ... +``` + +--- + +## Step 7: Modernize API Safely + +### Refactor with Contract Safety Net + +```python +# Modernized version (same contracts) +@icontract.require(...) # Same contracts as before +def create_order(): + """Modernized order creation with contract safety net""" + + # Modernized implementation + data = CreateOrderSchema().load(request.get_json()) + order_service = OrderService() + + try: + order = order_service.create_order( + customer_id=data['customer_id'], + items=data['items'] + ) + return jsonify({ + 'order_id': order.id, + 'status': order.status + }), 201 + except OrderCreationError as e: + return jsonify({'error': str(e)}), 400 + +``` + +### Catch API Regressions + +```python +# During modernization, accidentally break contract: +# Missing customer_id validation in refactored code + +# Runtime enforcement catches it: +# ❌ ContractViolation: Customer ID must be positive integer (got 0) +# at create_order() call from test_api.py:42 +# → Prevented API bug from reaching production! +``` + +--- + +## Results + +### Quantified Outcomes + +| Metric | Before SpecFact | After SpecFact | Improvement | +|--------|----------------|----------------|-------------| +| **API documentation** | 0% (none) | 100% (auto-generated) | **∞ improvement** | +| **Request validation** | Manual (error-prone) | Automated (contracts) | **100% coverage** | +| **Edge cases discovered** | 0-1 (manual) | 4 (CrossHair) | **4x more** | +| **API bugs prevented** | 0 (no safety net) | 3 bugs | **∞ improvement** | +| **Refactoring time** | 4-6 weeks (cautious) | 2-3 weeks (confident) | **50% faster** | + +--- + +## Integration with Your Workflow + +SpecFact CLI integrates seamlessly with your existing tools: + +- **VS Code**: Use pre-commit hooks to catch breaking changes before commit +- **Cursor**: AI assistant workflows catch regressions during refactoring +- **GitHub Actions**: CI/CD integration blocks bad code from merging +- **Pre-commit hooks**: Local validation prevents breaking changes +- **Any IDE**: Pure CLI-first approach—works with any editor + +**See real examples**: [Integration Showcases](integration-showcases/) - 5 complete examples showing bugs fixed via integrations + +## Key Takeaways + +### What Worked Well + +1. ✅ **code2spec** extracted API endpoints automatically +2. ✅ **SDD manifest** created hard spec reference, preventing drift +3. ✅ **SDD validation** ensured coverage thresholds before modernization +4. ✅ **Plan promotion gates** required SDD presence, enforcing discipline +5. ✅ **Contracts** enforced request validation at runtime +6. ✅ **CrossHair** discovered edge cases in API inputs +7. ✅ **Incremental modernization** reduced risk +8. ✅ **CLI-first integration** - Works offline, no account required, no vendor lock-in + +### Lessons Learned + +1. **Start with high-traffic endpoints** - Maximum impact +2. **Combine validation + contracts** - Request validation + runtime enforcement +3. **Test edge cases early** - Run CrossHair before refactoring +4. **Document API changes** - Keep changelog of modernized endpoints + +--- + +## Next Steps + +1. **[Integration Showcases](integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations +2. **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** - Complete modernization workflow +3. **[Django Example](brownfield-django-modernization.md)** - Web app modernization +4. **[Data Pipeline Example](brownfield-data-pipeline.md)** - ETL modernization + +--- + +**Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) | [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_local/examples/dogfooding-specfact-cli.md b/_site_local/examples/dogfooding-specfact-cli.md new file mode 100644 index 0000000..83d638d --- /dev/null +++ b/_site_local/examples/dogfooding-specfact-cli.md @@ -0,0 +1,683 @@ +# Real-World Example: SpecFact CLI Analyzing Itself + +> **TL;DR**: We ran SpecFact CLI on its own codebase in two ways: (1) **Brownfield analysis** discovered **19 features** and **49 stories** in **under 3 seconds**, found **24 deviations**, and blocked the merge (as configured). (2) **Contract enhancement** added beartype, icontract, and CrossHair contracts to our core telemetry module with **7-step validation** (all tests passed, code quality maintained). Total time: **< 10 seconds** for analysis, **~3 minutes** for contract enhancement. 🚀 +> **Note**: "Dogfooding" is a well-known tech term meaning "eating your own dog food" - using your own product. It's a common practice in software development to validate that tools work in real-world scenarios. + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in. + +--- + +## The Challenge + +We built SpecFact CLI and wanted to validate that it actually works in the real world. So we did what every good developer does: **we dogfooded it**. + +**Goal**: Analyze the SpecFact CLI codebase itself and demonstrate: + +1. How fast brownfield analysis is +2. How enforcement actually blocks bad code +3. How the complete workflow works end-to-end +4. How contract enhancement works on real production code + +--- + +## Step 1: Brownfield Analysis (3 seconds ⚡) + +First, we analyzed the existing codebase to see what features it discovered: + +```bash +specfact import from-code specfact-cli --repo . --confidence 0.5 +``` + +**Output**: + +```bash +🔍 Analyzing Python files... +✓ Found 19 features +✓ Detected themes: CLI, Validation +✓ Total stories: 49 + +✓ Analysis complete! +Project bundle written to: .specfact/projects/specfact-cli/ +``` + +### What It Discovered + +The brownfield analysis extracted **19 features** from our codebase: + +| Feature | Stories | Confidence | What It Does | +|---------|---------|------------|--------------| +| Enforcement Config | 3 | 0.9 | Configuration for contract enforcement and quality gates | +| Code Analyzer | 2 | 0.7 | Analyzes Python code to auto-derive plan bundles | +| Plan Comparator | 1 | 0.7 | Compares two plan bundles to detect deviations | +| Report Generator | 3 | 0.9 | Generator for validation and deviation reports | +| Protocol Generator | 3 | 0.9 | Generator for protocol YAML files | +| Plan Generator | 3 | 0.9 | Generator for plan bundle YAML files | +| FSM Validator | 3 | 1.0 | FSM validator for protocol validation | +| Schema Validator | 2 | 0.7 | Schema validator for plan bundles and protocols | +| Git Operations | 5 | 1.0 | Helper class for Git operations | +| Logger Setup | 3 | 1.0 | Utility class for standardized logging setup | +| ... and 9 more | 21 | - | Supporting utilities and infrastructure | + +**Total**: **49 user stories** auto-generated with Fibonacci story points (1, 2, 3, 5, 8, 13...) + +### Sample Auto-Generated Story + +Here's what the analyzer extracted from our `EnforcementConfig` class: + +```yaml +- key: STORY-ENFORCEMENTCONFIG-001 + title: As a developer, I can configure Enforcement Config + acceptance: + - Configuration functionality works as expected + tags: [] + story_points: 2 + value_points: 3 + tasks: + - __init__() + confidence: 0.6 + draft: false +``` + +**Time taken**: ~3 seconds for 19 Python files + +> **💡 How does it work?** SpecFact CLI uses **AI-first approach** (LLM) in CoPilot mode for semantic understanding and multi-language support, with **AST-based fallback** in CI/CD mode for fast, deterministic Python-only analysis. [Read the technical deep dive →](../technical/code2spec-analysis-logic.md) + +--- + +## Step 2: Set Enforcement Rules (1 second 🎯) + +Next, we configured quality gates to block HIGH severity violations: + +```bash +specfact enforce stage --preset balanced +``` + +**Output**: + +```bash +Setting enforcement mode: balanced + Enforcement Mode: + BALANCED +┏━━━━━━━━━━┳━━━━━━━━┓ +┃ Severity ┃ Action ┃ +┡━━━━━━━━━━╇━━━━━━━━┩ +│ HIGH │ BLOCK │ +│ MEDIUM │ WARN │ +│ LOW │ LOG │ +└──────────┴────────┘ + +✓ Enforcement mode set to balanced +Configuration saved to: .specfact/gates/config/enforcement.yaml +``` + +**What this means**: + +- 🚫 **HIGH** severity deviations → **BLOCK** the merge (exit code 1) +- ⚠️ **MEDIUM** severity deviations → **WARN** but allow (exit code 0) +- 📝 **LOW** severity deviations → **LOG** silently (exit code 0) + +--- + +## Step 3: Create Manual Plan (30 seconds ✍️) + +We created a minimal manual plan with just 2 features we care about: + +```yaml +features: + - key: FEATURE-ENFORCEMENT + title: Contract Enforcement System + outcomes: + - Developers can set and enforce quality gates + - Automated blocking of contract violations + stories: + - key: STORY-ENFORCEMENT-001 + title: As a developer, I want to set enforcement presets + story_points: 5 + value_points: 13 + + - key: FEATURE-BROWNFIELD + title: Brownfield Code Analysis + outcomes: + - Automatically derive plans from existing codebases + - Identify features and stories from Python code + stories: + - key: STORY-BROWNFIELD-001 + title: As a developer, I want to analyze existing code + story_points: 8 + value_points: 21 +``` + +**Saved to**: `.specfact/projects/main/` (modular project bundle structure) + +--- + +## Step 4: Compare Plans with Enforcement (5 seconds 🔍) + +Now comes the magic - compare the manual plan against what's actually implemented: + +```bash +specfact plan compare +``` + +### Results + +**Deviations Found**: 24 total + +- 🔴 **HIGH**: 2 (Missing features from manual plan) +- 🟡 **MEDIUM**: 19 (Extra implementations found in code) +- 🔵 **LOW**: 3 (Metadata mismatches) + +### Detailed Breakdown + +#### 🔴 HIGH Severity (BLOCKED) + +```table +┃ 🔴 HIGH │ Missing Feature │ Feature 'FEATURE-ENFORCEMENT' │ features[FEATURE-E… │ +┃ │ │ (Contract Enforcement System) │ │ +┃ │ │ in manual plan but not implemented │ │ +``` + +**Wait, what?** We literally just built the enforcement feature! 🤔 + +**Explanation**: The brownfield analyzer found `FEATURE-ENFORCEMENTCONFIG` (the model class), but our manual plan calls it `FEATURE-ENFORCEMENT` (the complete system). This is a **real deviation** - our naming doesn't match! + +#### ⚠️ MEDIUM Severity (WARNED) + +```table +┃ 🟡 MEDIUM │ Extra Implementation │ Feature 'FEATURE-YAMLUTILS' │ features[FEATURE-Y… │ +┃ │ │ (Y A M L Utils) found in code │ │ +┃ │ │ but not in manual plan │ │ +``` + +**Explanation**: We have 19 utility features (YAML utils, Git operations, validators, etc.) that exist in code but aren't documented in our minimal manual plan. + +**Value**: This is exactly what we want! It shows us **undocumented features** that should either be: + +1. Added to the manual plan, or +2. Removed if they're not needed + +#### 📝 LOW Severity (LOGGED) + +```table +┃ 🔵 LOW │ Mismatch │ Idea title differs: │ idea.title │ +┃ │ │ manual='SpecFact CLI', │ │ +┃ │ │ auto='Unknown Project' │ │ +``` + +**Explanation**: Brownfield analysis couldn't detect our project name, so it used "Unknown Project". Minor metadata issue. + +--- + +## Step 5: Enforcement In Action 🚫 + +Here's where it gets interesting. With **balanced enforcement** enabled: + +### Enforcement Report + +```bash +============================================================ +Enforcement Rules +============================================================ + +Using enforcement config: .specfact/gates/config/enforcement.yaml + +📝 [LOW] mismatch: LOG +📝 [LOW] mismatch: LOG +📝 [LOW] mismatch: LOG +🚫 [HIGH] missing_feature: BLOCK +🚫 [HIGH] missing_feature: BLOCK +⚠️ [MEDIUM] extra_implementation: WARN +⚠️ [MEDIUM] extra_implementation: WARN +⚠️ [MEDIUM] extra_implementation: WARN +... (16 more MEDIUM warnings) + +❌ Enforcement BLOCKED: 2 deviation(s) violate quality gates +Fix the blocking deviations or adjust enforcement config +``` + +**Exit Code**: 1 (BLOCKED) ❌ + +**What happened**: The 2 HIGH severity deviations violated our quality gate, so the command **blocked** execution. + +**In CI/CD**: This would **fail the PR** and prevent the merge until we fix the deviations or update the enforcement config. + +--- + +## Step 6: Switch to Minimal Enforcement (1 second 🔄) + +Let's try again with **minimal enforcement** (never blocks): + +```bash +specfact enforce stage --preset minimal +specfact plan compare +``` + +### New Enforcement Report + +```bash +============================================================ +Enforcement Rules +============================================================ + +Using enforcement config: .specfact/gates/config/enforcement.yaml + +📝 [LOW] mismatch: LOG +📝 [LOW] mismatch: LOG +📝 [LOW] mismatch: LOG +⚠️ [HIGH] missing_feature: WARN ← Changed from BLOCK +⚠️ [HIGH] missing_feature: WARN ← Changed from BLOCK +⚠️ [MEDIUM] extra_implementation: WARN +... (all 24 deviations) + +✅ Enforcement PASSED: No blocking deviations +``` + +**Exit Code**: 0 (PASSED) ✅ + +**Same deviations, different outcome**: With minimal enforcement, even HIGH severity issues are downgraded to warnings. Perfect for exploration phase! + +--- + +## Part 2: Contract Enhancement Workflow (Production Use Case) 🎯 + +After validating the brownfield analysis workflow, we took it a step further: **we used SpecFact CLI to enhance one of our own core modules with contracts**. This demonstrates the complete contract enhancement workflow in a real production scenario. + +**Goal**: Add beartype, icontract, and CrossHair contracts to `src/specfact_cli/telemetry.py` - a core module that handles privacy-first telemetry. + +--- + +## Step 7: Generate Contract Enhancement Prompt (1 second 📝) + +First, we generated a structured prompt for our AI IDE (Cursor) to enhance the telemetry module: + +```bash +specfact generate contracts-prompt src/specfact_cli/telemetry.py --bundle specfact-cli-test --apply all-contracts --no-interactive +``` + +**Output**: + +```bash +✓ Analyzing file: src/specfact_cli/telemetry.py +✓ Generating prompt for: beartype, icontract, crosshair +✓ Prompt saved to: .specfact/projects/specfact-cli-test/prompts/enhance-telemetry-beartype-icontract-crosshair.md +``` + +**What happened**: + +- CLI analyzed the telemetry module (543 lines) +- Generated a structured prompt with: + - **CRITICAL REQUIREMENT**: Add contracts to ALL eligible functions (no asking the user) + - Detailed instructions for each contract type (beartype, icontract, crosshair) + - Code quality guidance (follow project formatting rules) + - Step-by-step validation workflow +- Saved prompt to bundle-specific directory (prevents conflicts with multiple bundles) + +--- + +## Step 8: AI IDE Enhancement (2-3 minutes 🤖) + +We copied the prompt to Cursor (our AI IDE), which: + +1. **Read the file** from the provided path +2. **Added contracts to ALL eligible functions**: + - `@beartype` decorators on all functions/methods + - `@require` and `@ensure` decorators where appropriate + - CrossHair property-based test functions +3. **Wrote enhanced code** to `enhanced_telemetry.py` (temporary file) +4. **Ran validation** using SpecFact CLI (see Step 9) + +**Key Point**: The AI IDE followed the prompt's **CRITICAL REQUIREMENT** and added contracts to all eligible functions automatically, without asking for confirmation. + +--- + +## Step 9: Comprehensive Validation (7-step process ✅) + +The AI IDE ran SpecFact CLI validation on the enhanced code: + +```bash +specfact generate contracts-apply enhanced_telemetry.py --original src/specfact_cli/telemetry.py +``` + +### Validation Results + +**Step 1/7: File Size Check** ✅ + +- Enhanced file: 678 lines (was 543 lines) +- Validation: Passed (enhanced file is larger, indicating contracts were added) + +**Step 2/7: Syntax Validation** ✅ + +- Python syntax check: Passed +- File compiles successfully + +**Step 3/7: AST Structure Comparison** ✅ + +- Original: 23 definitions (functions, classes, methods) +- Enhanced: 23 definitions preserved +- Validation: All definitions maintained (no functions removed) + +**Step 4/7: Contract Imports Verification** ✅ + +- Required imports present: + - `from beartype import beartype` + - `from icontract import require, ensure` +- Validation: All imports verified + +**Step 5/7: Code Quality Checks** ✅ + +- **Ruff linting**: Passed (1 tool checked, 1 passed) +- **Pylint**: Not available (skipped) +- **BasedPyright**: Not available (skipped) +- **MyPy**: Not available (skipped) +- Note: Tools run automatically if installed (non-blocking) + +**Step 6/7: Test Execution** ✅ + +- **Scoped test run**: `pytest tests/unit/specfact_cli/test_telemetry.py` +- **Results**: 10/10 tests passed +- **Time**: Seconds (optimized scoped run, not full repository validation) +- Note: Tests always run for validation, even in `--dry-run` mode + +**Step 7/7: Diff Preview** ✅ + +- Previewed changes before applying +- All validations passed + +### Final Result + +```bash +✓ All validations passed! +✓ Enhanced code applied to: src/specfact_cli/telemetry.py +✓ Temporary file cleaned up: enhanced_telemetry.py +``` + +**Total validation time**: < 10 seconds (7-step comprehensive validation) + +--- + +## What We Achieved + +### Contracts Applied + +1. **beartype decorators**: Added `@beartype` to all eligible functions and methods + - Regular functions, class methods, static methods, async functions + - Runtime type checking for all public APIs + +2. **icontract decorators**: Added `@require` and `@ensure` where appropriate + - Preconditions for parameter validation and state checks + - Postconditions for return value validation and guarantees + +3. **CrossHair tests**: Added property-based test functions + - `test_coerce_bool_property()` - Validates boolean coercion + - `test_parse_headers_property()` - Validates header parsing + - `test_telemetry_settings_from_env_property()` - Validates settings creation + - `test_telemetry_manager_sanitize_property()` - Validates data sanitization + - `test_telemetry_manager_normalize_value_property()` - Validates value normalization + +### Validation Quality + +- ✅ **File size check**: Ensured no code was removed +- ✅ **Syntax validation**: Python compilation successful +- ✅ **AST structure**: All 23 definitions preserved +- ✅ **Contract imports**: All required imports verified +- ✅ **Code quality**: Ruff linting passed +- ✅ **Tests**: 10/10 tests passed +- ✅ **Diff preview**: Changes reviewed before applying + +### Production Value + +This demonstrates **real production use**: + +- Enhanced a **core module** (telemetry) used throughout the CLI +- Applied **all three contract types** (beartype, icontract, crosshair) +- **All tests passed** (10/10) - no regressions introduced +- **Code quality maintained** (ruff linting passed) +- **Fast validation** (< 10 seconds for comprehensive 7-step process) + +--- + +## Complete Contract Enhancement Workflow + +```bash +# 1. Generate prompt (1 second) +specfact generate contracts-prompt src/specfact_cli/telemetry.py \ + --bundle specfact-cli-test \ + --apply all-contracts \ + --no-interactive +# ✅ Prompt saved to: .specfact/projects/specfact-cli-test/prompts/ + +# 2. AI IDE enhancement (2-3 minutes) +# - Copy prompt to Cursor/CoPilot/etc. +# - AI IDE reads file and adds contracts +# - AI IDE writes to enhanced_telemetry.py + +# 3. Validate and apply (10 seconds) +specfact generate contracts-apply enhanced_telemetry.py \ + --original src/specfact_cli/telemetry.py +# ✅ 7-step validation passed +# ✅ All tests passed (10/10) +# ✅ Code quality checks passed +# ✅ Changes applied to original file + +# Total time: ~3 minutes (mostly AI IDE processing) +# Total value: Production-ready contract-enhanced code +``` + +--- + +## What We Learned (Part 2) + +### 1. **Comprehensive Validation** 🛡️ + +The 7-step validation process caught potential issues: + +- File size check prevents accidental code removal +- AST structure comparison ensures no functions are deleted +- Contract imports verification prevents missing dependencies +- Code quality checks (if tools available) catch linting issues +- Test execution validates functionality (10/10 passed) + +### 2. **Production-Ready Workflow** 🚀 + +- **Fast**: Validation completes in < 10 seconds +- **Thorough**: 7-step comprehensive validation +- **Safe**: Only applies changes if all validations pass +- **Flexible**: Works with any AI IDE (Cursor, CoPilot, etc.) +- **Non-blocking**: Code quality tools optional (run if available) + +### 3. **Real-World Validation** 💎 + +We enhanced a **real production module**: + +- Core telemetry module (used throughout CLI) +- 543 lines → 678 lines (contracts added) +- All tests passing (10/10) +- Code quality maintained (ruff passed) +- No regressions introduced + +### 4. **Self-Improvement** 🔄 + +This demonstrates **true dogfooding**: + +- We used SpecFact CLI to enhance SpecFact CLI +- Validated the workflow on real production code +- Proved the tool works for its intended purpose +- Enhanced our own codebase with contracts + +--- + +## What We Learned + +### 1. **Speed** ⚡ + +| Task | Time | +|------|------| +| Analyze 19 Python files | 3 seconds | +| Set enforcement | 1 second | +| Compare plans | 5 seconds | +| **Total** | **< 10 seconds** | + +### 2. **Accuracy** 🎯 + +- Discovered **19 features** we actually built +- Generated **49 user stories** with meaningful titles +- Calculated story points using Fibonacci (1, 2, 3, 5, 8...) +- Detected real naming inconsistencies (e.g., `FEATURE-ENFORCEMENT` vs `FEATURE-ENFORCEMENTCONFIG`) + +### 3. **Enforcement Works** 🚫 + +- **Balanced mode**: Blocked execution due to 2 HIGH deviations (exit 1) +- **Minimal mode**: Passed with warnings (exit 0) +- **CI/CD ready**: Exit codes work perfectly with GitHub Actions, GitLab CI, etc. + +### 4. **Real Value** 💎 + +The tool found **real issues**: + +1. **Naming inconsistency**: Manual plan uses `FEATURE-ENFORCEMENT`, but code has `FEATURE-ENFORCEMENTCONFIG` +2. **Undocumented features**: 19 utility features exist in code but aren't in the manual plan +3. **Documentation gap**: Should we document all utilities, or are they internal implementation details? + +These are **actual questions** that need answers, not false positives! + +--- + +## Complete Workflow (< 10 seconds) + +```bash +# 1. Analyze existing codebase (3 seconds) +specfact import from-code specfact-cli --repo . --confidence 0.5 +# ✅ Discovers 19 features, 49 stories + +# 2. Set quality gates (1 second) +specfact enforce stage --preset balanced +# ✅ BLOCK HIGH, WARN MEDIUM, LOG LOW + +# 3. Compare plans (5 seconds) - uses active plan or default bundle +specfact plan compare +# ✅ Finds 24 deviations +# ❌ BLOCKS execution (2 HIGH violations) + +# Total time: < 10 seconds +# Total value: Priceless 💎 +``` + +--- + +## Use Cases Demonstrated + +### ✅ Brownfield Analysis + +**Problem**: "We have 10,000 lines of code and no documentation" + +**Solution**: Run `import from-code` → get instant plan bundle with features and stories + +**Time**: Seconds, not days + +### ✅ Quality Gates + +**Problem**: "How do I prevent bad code from merging?" + +**Solution**: Set enforcement preset → configure CI to run `plan compare` + +**Result**: PRs blocked automatically if they violate contracts + +### ✅ CI/CD Integration + +**Problem**: "I need consistent exit codes for automation" + +**Solution**: SpecFact CLI uses standard exit codes: + +- 0 = success (no blocking deviations) +- 1 = failure (enforcement blocked) + +**Integration**: Works with any CI system (GitHub Actions, GitLab, Jenkins, etc.) + +--- + +## Next Steps + +### Try It Yourself + +```bash +# Clone SpecFact CLI +git clone https://github.com/nold-ai/specfact-cli.git +cd specfact-cli + +# Run the same analysis +hatch run python -c "import sys; sys.path.insert(0, 'src'); from specfact_cli.cli import app; app()" import from-code specfact-cli --repo . --confidence 0.5 + +# Set enforcement +hatch run python -c "import sys; sys.path.insert(0, 'src'); from specfact_cli.cli import app; app()" enforce stage --preset balanced + +# Compare plans +hatch run python -c "import sys; sys.path.insert(0, 'src'); from specfact_cli.cli import app; app()" plan compare +``` + +### Learn More + +- ⭐ **[Integration Showcases](integration-showcases/)** - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations +- 🔧 [How Code2Spec Works](../technical/code2spec-analysis-logic.md) - Deep dive into AST-based analysis +- 📖 [Getting Started Guide](../getting-started/README.md) +- 📋 [Command Reference](../reference/commands.md) +- 💡 [More Use Cases](../guides/use-cases.md) + +--- + +## Files Generated + +All artifacts are stored in `.specfact/`: + +```shell +.specfact/ +├── plans/ +│ └── main.bundle.yaml # Manual plan (versioned) +├── reports/ +│ ├── brownfield/ +│ │ ├── auto-derived.2025-10-30T16-57-51.bundle.yaml # Auto-derived plan +│ │ └── report-2025-10-30-16-57.md # Analysis report +│ └── comparison/ +│ └── report-2025-10-30-16-58.md # Deviation report +└── gates/ + └── config/ + └── enforcement.yaml # Enforcement config (versioned) +``` + +**Versioned** (commit to git): `plans/`, `gates/config/` + +**Gitignored** (ephemeral): `reports/` + +--- + +## Conclusion + +SpecFact CLI **works**. We proved it by running it on itself in two real-world scenarios: + +### Part 1: Brownfield Analysis + +- ⚡ **Fast**: Analyzed 19 files → 19 features, 49 stories in **3 seconds** +- 🎯 **Accurate**: Found **24 real deviations** (naming inconsistencies, undocumented features) +- 🚫 **Blocks bad code**: Enforcement prevented merge with 2 HIGH violations +- 🔄 **CI/CD ready**: Standard exit codes, works everywhere + +### Part 2: Contract Enhancement + +- 🛡️ **Comprehensive**: 7-step validation process (file size, syntax, AST, imports, quality, tests, diff) +- ✅ **Production-ready**: Enhanced core telemetry module (543 → 678 lines) +- 🧪 **All tests passed**: 10/10 tests passed, no regressions +- 🚀 **Fast validation**: < 10 seconds for complete validation workflow + +**Key Takeaways**: + +1. ⚡ **Fast**: Analyze thousands of lines in seconds, validate contracts in < 10 seconds +2. 🎯 **Accurate**: Finds real deviations, not false positives +3. 🚫 **Blocks bad code**: Enforcement actually prevents merges +4. 🛡️ **Comprehensive validation**: 7-step process ensures code quality +5. 🔄 **CI/CD ready**: Standard exit codes, works everywhere +6. 🐕 **True dogfooding**: We use it on our own production code + +**Try it yourself** and see how much time you save! + +--- + +> **Built by dogfooding** - This example is real, not fabricated. We ran SpecFact CLI on itself in two ways: (1) brownfield analysis workflow, and (2) contract enhancement workflow on our core telemetry module. All results are actual, documented outcomes from production use. diff --git a/_site_local/examples/index.html b/_site_local/examples/index.html new file mode 100644 index 0000000..ff1b5fd --- /dev/null +++ b/_site_local/examples/index.html @@ -0,0 +1,283 @@ + + + + + + + +Examples | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Examples

+ +

Real-world examples of using SpecFact CLI.

+ +

Available Examples

+ +
    +
  • Integration Showcases ⭐ START HERE - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations + +
    • +
  • Brownfield Examples ⭐ NEW - Complete hard-SDD workflow demonstrations +
      +
    • Django Modernization - Legacy Django app → contract-enforced modern codebase
      • +
    • Flask API - Legacy Flask API → contract-enforced modern service
      • +
    • Data Pipeline - Legacy ETL pipeline → contract-enforced data processing
      • +
    • All examples now include: plan harden, enforce sdd, plan review, and plan promote with SDD validation
      • +
    +
    • +
  • Quick Examples - Quick code snippets for common tasks, including SDD workflow
    • +
  • Dogfooding SpecFact CLI - We ran SpecFact CLI on itself (< 10 seconds!)
    • +
+ +

Quick Start

+ +

See It In Action

+ +

For Brownfield Modernization (Recommended):

+ +

Read the complete brownfield examples to see the hard-SDD workflow:

+ +

Django Modernization Example

+ +

This example shows the complete workflow:

+ +
    +
  1. ⚡ Extract specs from legacy code → 23 features, 112 stories in 8 seconds
    2. +
  2. 📋 Create SDD manifest → Hard spec with WHY/WHAT/HOW, coverage thresholds
    3. +
  3. ✅ Validate SDD → Hash match, coverage threshold validation
    4. +
  4. 📊 Review plan → SDD validation integrated, ambiguity resolution
    5. +
  5. 🚀 Promote plan → SDD required for “review” or higher stages
    6. +
  6. 🔒 Add contracts → Runtime enforcement prevents regressions
    7. +
  7. 🔍 Re-validate SDD → Ensure coverage thresholds maintained
    8. +
+ +

For Quick Testing:

+ +

Dogfooding SpecFact CLI

+ +

This example shows:

+ +
    +
  • ⚡ Analyzed 19 Python files → Discovered 19 features and 49 stories in 3 seconds
    • +
  • 🚫 Set enforcement to “balanced” → Blocked 2 HIGH violations (as configured)
    • +
  • 📊 Compared manual vs auto-derived plans → Found 24 deviations in 5 seconds
    • +
+ + + + + + + + +
Total time: < 10 secondsTotal value: Found real naming inconsistencies and undocumented features
+ + + + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/examples/integration-showcases/README.md b/_site_local/examples/integration-showcases/README.md new file mode 100644 index 0000000..80b035b --- /dev/null +++ b/_site_local/examples/integration-showcases/README.md @@ -0,0 +1,164 @@ +# Integration Showcases + +> **Core USP**: SpecFact CLI works seamlessly with VS Code, Cursor, GitHub Actions, and any agentic workflow. This folder contains real examples of bugs that were caught and fixed through different integration points. + +--- + +## 📚 What's in This Folder + +This folder contains everything you need to understand and test SpecFact CLI integrations: + +### Main Documents + +1. **[`integration-showcases.md`](integration-showcases.md)** ⭐ **START HERE** + + - **Purpose**: Real-world examples of bugs fixed via CLI integrations + - **Content**: 5 complete examples showing how SpecFact catches bugs in different workflows + - **Best for**: Understanding what SpecFact can do and seeing real bug fixes + - **Time**: 15-20 minutes to read + +2. **[`integration-showcases-testing-guide.md`](integration-showcases-testing-guide.md)** 🔧 **TESTING GUIDE** + + - **Purpose**: Step-by-step guide to test and validate all 5 examples + - **Content**: Detailed instructions, expected outputs, validation status + - **Best for**: Developers who want to verify the examples work as documented + - **Time**: 2-4 hours to complete all tests + +3. **[`integration-showcases-quick-reference.md`](integration-showcases-quick-reference.md)** ⚡ **QUICK REFERENCE** + + - **Purpose**: Quick command reference for all 5 examples + - **Content**: Essential commands, setup steps, common workflows + - **Best for**: Quick lookups when you know what you need + - **Time**: 5 minutes to scan + +### Setup Script + +1. **[`setup-integration-tests.sh`](setup-integration-tests.sh)** 🚀 **AUTOMATED SETUP** + + - **Purpose**: Automated script to create test cases for all examples + - **Content**: Creates test directories, sample code, and configuration files + - **Best for**: Setting up test environment quickly + - **Time**: < 1 minute to run + +--- + +## 🎯 Quick Start Guide + +### For First-Time Users + +**Step 1**: Read the main showcase document +→ **[`integration-showcases.md`](integration-showcases.md)** + +This gives you a complete overview of what SpecFact can do with real examples. + +**Step 2**: Choose your path: + +- **Want to test the examples?** → Use [`setup-integration-tests.sh`](setup-integration-tests.sh) then follow [`integration-showcases-testing-guide.md`](integration-showcases-testing-guide.md) + +- **Just need quick commands?** → Check [`integration-showcases-quick-reference.md`](integration-showcases-quick-reference.md) + +- **Ready to integrate?** → Pick an example from [`integration-showcases.md`](integration-showcases.md) and adapt it to your workflow + +### For Developers Testing Examples + +**Step 1**: Run the setup script + +```bash +./docs/examples/integration-showcases/setup-integration-tests.sh +``` + +**Step 2**: Follow the testing guide + +→ **[`integration-showcases-testing-guide.md`](integration-showcases-testing-guide.md)** + +**Step 3**: Verify validation status + +- Example 1: ✅ **FULLY VALIDATED** +- Example 2: ✅ **FULLY VALIDATED** +- Example 3: ⚠️ **COMMANDS VERIFIED** (end-to-end testing deferred) +- Example 4: ✅ **FULLY VALIDATED** +- Example 5: ⏳ **PENDING VALIDATION** + +--- + +## 📋 Examples Overview + +### Example 1: VS Code Integration - Async Bug Detection + +- **Integration**: VS Code + Pre-commit Hook +- **Bug**: Blocking I/O call in async context +- **Result**: Caught before commit, prevented production race condition +- **Status**: ✅ **FULLY VALIDATED** + +### Example 2: Cursor Integration - Regression Prevention + +- **Integration**: Cursor AI Assistant +- **Bug**: Missing None check in data processing +- **Result**: Prevented regression during refactoring +- **Status**: ✅ **FULLY VALIDATED** + +### Example 3: GitHub Actions - CI/CD Integration + +- **Integration**: GitHub Actions workflow +- **Bug**: Type mismatch in API endpoint +- **Result**: Blocked bad code from merging +- **Status**: ✅ **FULLY VALIDATED** (CI/CD workflow validated in production) + +### Example 4: Pre-commit Hook - Breaking Change Detection + +- **Integration**: Git pre-commit hook +- **Bug**: Function signature change (breaking change) +- **Result**: Blocked commit locally before pushing +- **Status**: ✅ **FULLY VALIDATED** + +### Example 5: Agentic Workflows - Edge Case Discovery + +- **Integration**: AI assistant workflows +- **Bug**: Edge cases in data validation +- **Result**: Discovered hidden bugs with symbolic execution +- **Status**: ⏳ **PENDING VALIDATION** + +--- + +## 🔗 Related Documentation + +- **[Examples README](../README.md)** - Overview of all SpecFact examples +- **[Brownfield FAQ](../../guides/brownfield-faq.md)** - Common questions about brownfield modernization +- **[Getting Started](../../getting-started/README.md)** - Installation and setup +- **[Command Reference](../../reference/commands.md)** - All available commands + +--- + +## ✅ Validation Status + +**Overall Progress**: 80% complete (4/5 fully validated, 1/5 pending) + +**Key Achievements**: + +- ✅ CLI-first approach validated (works offline, no account required) +- ✅ 3+ integration case studies showing bugs fixed +- ✅ Enforcement blocking validated across all tested examples +- ✅ Documentation updated with actual command outputs and test results + +**Remaining Work**: + +- ⏳ Example 5 validation (2-3 hours estimated) +- ✅ Example 3 validated in production CI/CD (GitHub Actions workflow verified) + +--- + +## 💡 Tips + +1. **Start with Example 1** - It's the simplest and fully validated + +2. **Use the setup script** - Saves time creating test cases + +3. **Check validation status** - Examples 1, 2, and 4 are fully tested and working + +4. **Read the testing guide** - It has actual command outputs and expected results + +5. **Adapt to your workflow** - These examples are templates you can customize + +--- + +**Questions?** Check the [Brownfield FAQ](../../guides/brownfield-faq.md) or open an issue on GitHub. diff --git a/_site_local/examples/integration-showcases/integration-showcases-quick-reference.md b/_site_local/examples/integration-showcases/integration-showcases-quick-reference.md new file mode 100644 index 0000000..33c8e9f --- /dev/null +++ b/_site_local/examples/integration-showcases/integration-showcases-quick-reference.md @@ -0,0 +1,225 @@ +# Integration Showcases - Quick Reference + +> **Quick command reference** for testing all 5 integration examples + +--- + +## Setup (One-Time) + +### Step 1: Verify Python Version + +```bash +# Check Python version (requires 3.11+) +python3 --version +# Should show Python 3.11.x or higher +``` + +### Step 2: Install SpecFact + +```bash +# Install via pip (required for interactive AI assistant) +pip install specfact-cli + +# Verify installation +specfact --version +``` + +### Step 3: Create Test Cases + +```bash +# Run setup script +./docs/examples/integration-showcases/setup-integration-tests.sh + +# Or manually +mkdir -p /tmp/specfact-integration-tests +cd /tmp/specfact-integration-tests +``` + +### Step 4: Initialize IDE Integration (For Interactive Mode) + +```bash +# Navigate to test directory +cd /tmp/specfact-integration-tests/example1_vscode + +# Initialize SpecFact for your IDE (one-time per project) +specfact init + +# Or specify IDE explicitly: +# specfact init --ide cursor +# specfact init --ide vscode +``` + +**⚠️ Important**: `specfact init` copies templates to the directory where you run it (e.g., `/tmp/specfact-integration-tests/example1_vscode/.cursor/commands/`). For slash commands to work correctly: + +- **Open the demo repo in your IDE** as the workspace root (e.g., `/tmp/specfact-integration-tests/example1_vscode`) +- Interactive mode automatically uses your IDE workspace - no `--repo .` parameter needed +- **OR** if you need to analyze a different repository: `/specfact.01-import legacy-api --repo /path/to/other/repo` + +--- + +## Example 1: VS Code - Async Bug + +**⚠️ Prerequisite**: Open `/tmp/specfact-integration-tests/example1_vscode` as your IDE workspace. + +```bash +cd /tmp/specfact-integration-tests/example1_vscode + +# Step 1: Import code to create plan +# Recommended: Use interactive AI assistant (slash command in IDE) +# /specfact.01-import legacy-api --repo . +# (Interactive mode automatically uses IDE workspace - --repo . optional) +# The AI will prompt for a plan name - suggest: "Payment Processing" + +# Alternative: CLI-only mode (bundle name as positional argument) +specfact --no-banner import from-code payment-processing --repo . --output-format yaml + +# Step 2: Run enforcement +specfact --no-banner enforce stage --preset balanced + +# Expected: Contract violation about blocking I/O +``` + +**Capture**: Full output, exit code (`echo $?`) + +--- + +## Example 2: Cursor - Regression Prevention + +```bash +cd /tmp/specfact-integration-tests/example2_cursor + +# Step 1: Import code (bundle name as positional argument) +specfact --no-banner import from-code data-pipeline --repo . --output-format yaml + +# Step 2: Test original (should pass) +specfact --no-banner enforce stage --preset balanced + +# Step 3: Create broken version (remove None check) +# Edit src/pipeline.py to remove None check, then: +specfact --no-banner plan compare src/pipeline.py src/pipeline_broken.py --fail-on HIGH + +# Expected: Contract violation for missing None check +``` + +**Capture**: Output from both commands + +--- + +## Example 3: GitHub Actions - Type Error + +```bash +cd /tmp/specfact-integration-tests/example3_github_actions + +# Step 1: Import code (bundle name as positional argument) +specfact --no-banner import from-code user-api --repo . --output-format yaml + +# Step 2: Run enforcement +specfact --no-banner enforce stage --preset balanced + +# Expected: Type mismatch violation (int vs dict) +``` + +**Capture**: Full output, exit code + +--- + +## Example 4: Pre-commit - Breaking Change + +```bash +cd /tmp/specfact-integration-tests/example4_precommit + +# Step 1: Initial commit (bundle name as positional argument) +specfact --no-banner import from-code order-processor --repo . --output-format yaml +git add . +git commit -m "Initial code" + +# Step 2: Modify function (add user_id parameter) +# Edit src/legacy.py to add user_id parameter, then: +git add src/legacy.py +git commit -m "Breaking change test" + +# Expected: Pre-commit hook blocks commit, shows breaking change +``` + +**Capture**: Pre-commit hook output, git commit result + +--- + +## Example 5: Agentic - CrossHair Edge Case + +```bash +cd /tmp/specfact-integration-tests/example5_agentic + +# Option 1: CrossHair exploration (if available) +specfact --no-banner contract-test-exploration src/validator.py + +# Option 2: Contract enforcement (fallback) +specfact --no-banner enforce stage --preset balanced + +# Expected: Division by zero edge case detected +``` + +**Capture**: Output from exploration or enforcement + +--- + +## Output Template + +For each example, provide: + +```markdown +# Example X: [Name] + +## Command Executed + +```bash +[exact command] +``` + +## Full Output + +```bash +[complete stdout and stderr] +``` + +## Exit Code + +```bash +[exit code from echo $?] +``` + +## Files Created + +- [list of files] + +## Issues Found + +- [any problems or unexpected behavior] + +## Expected vs Actual + +- [comparison] + +```text +[comparison details] +``` + +--- + +## Quick Test All + +```bash +# Run all examples in sequence (bundle name as positional argument) +for dir in example1_vscode example2_cursor example3_github_actions example4_precommit example5_agentic; do + echo "Testing $dir..." + cd /tmp/specfact-integration-tests/$dir + bundle_name=$(echo "$dir" | sed 's/example[0-9]_//') + specfact --no-banner import from-code "$bundle_name" --repo . --output-format yaml 2>&1 + specfact --no-banner enforce stage --preset balanced 2>&1 + echo "---" +done +``` + +--- + +**Ready?** Start with Example 1 and work through each one! diff --git a/_site_local/examples/integration-showcases/integration-showcases-testing-guide.md b/_site_local/examples/integration-showcases/integration-showcases-testing-guide.md new file mode 100644 index 0000000..bb076c7 --- /dev/null +++ b/_site_local/examples/integration-showcases/integration-showcases-testing-guide.md @@ -0,0 +1,1692 @@ +# Integration Showcases Testing Guide + +> **Purpose**: Step-by-step guide to test and validate all 5 integration examples from `integration-showcases.md` + +This guide walks you through testing each example to ensure they work as documented and produce the expected outputs. + +--- + +## Prerequisites + +Before starting, ensure you have: + +1. **Python 3.11+ installed**: + + ```bash + # Check your Python version + python3 --version + # Should show Python 3.11.x or higher + ``` + + **Note**: SpecFact CLI requires Python 3.11 or higher. If you have an older version, upgrade Python first. + +2. **Semgrep installed** (optional, for async pattern detection in Example 1): + + ```bash + # Install Semgrep via pip (recommended) + pip install semgrep + + # Verify installation + semgrep --version + ``` + + **Note**: + + - Semgrep is optional but recommended for async pattern detection in Example 1 + - The setup script (`setup-integration-tests.sh`) will create the Semgrep config file automatically + - If Semgrep is not installed, async detection will be skipped but other checks will still run + - Semgrep is available via `pip install semgrep` and works well with Python projects + - The setup script will check if Semgrep is installed and provide installation instructions if missing + +3. **SpecFact CLI installed via pip** (required for interactive AI assistant): + + ```bash + # Install via pip (not just uvx - needed for IDE integration) + pip install specfact-cli + + # Verify installation (first time - banner shows) + specfact --version + ``` + + **Note**: For interactive AI assistant usage (slash commands), SpecFact must be installed via pip so the `specfact` command is available in your environment. `uvx` alone won't work for IDE integration. + +4. **One-time IDE setup** (for interactive AI assistant): + + ```bash + # Navigate to your test directory + cd /tmp/specfact-integration-tests/example1_vscode + + # Initialize SpecFact for your IDE (auto-detects IDE type) + # First time - banner shows, subsequent uses add --no-banner + specfact init + + # Or specify IDE explicitly: + # specfact init --ide cursor + # specfact init --ide vscode + ``` + + **⚠️ Important**: `specfact init` copies templates to the directory where you run the command (e.g., `/tmp/specfact-integration-tests/example1_vscode/.cursor/commands/`). However, for slash commands to work correctly with `--repo .`, you must: + + - **Open the demo repo directory as your IDE workspace** (e.g., `/tmp/specfact-integration-tests/example1_vscode`) + - This ensures `--repo .` operates on the correct repository + - **Note**: Interactive mode automatically uses your IDE workspace. If you need to analyze a different repository, specify: `/specfact.01-import legacy-api --repo /path/to/other/repo` + +5. **Test directory created**: + + ```bash + mkdir -p /tmp/specfact-integration-tests + cd /tmp/specfact-integration-tests + ``` + + **Note**: The setup script (`setup-integration-tests.sh`) automatically initializes git repositories in each example directory, so you don't need to run `git init` manually. + +--- + +## Test Setup + +### Create Test Files + +We'll create test files for each example. Run these commands: + +```bash +# Create directory structure +mkdir -p example1_vscode example2_cursor example3_github_actions example4_precommit example5_agentic +``` + +--- + +## Example 1: VS Code Integration - Async Bug Detection + +### Example 1 - Step 1: Create Test Files + +```bash +cd /tmp/specfact-integration-tests/example1_vscode +``` + +**Note**: The setup script already initializes a git repository in this directory, so `git init` is not needed. + +Create `src/views.py`: + +```python +# src/views.py - Legacy Django view with async bug +def process_payment(request): + user = get_user(request.user_id) + payment = create_payment(user.id, request.amount) + send_notification(user.email, payment.id) # ⚠️ Blocking call + return {"status": "success"} +``` + +### Example 1 - Step 2: Create SpecFact Plan + +**Option A: Interactive AI Assistant (Recommended)** ✅ + +**Prerequisites** (one-time setup): + +1. Ensure Python 3.11+ is installed: + + ```bash + python3 --version # Should show 3.11.x or higher + ``` + +2. Install SpecFact via pip: + + ```bash + pip install specfact-cli + ``` + +3. Initialize IDE integration: + + ```bash + cd /tmp/specfact-integration-tests/example1_vscode + specfact init + ``` + +4. **Open the demo repo in your IDE** (Cursor, VS Code, etc.): + + - Open `/tmp/specfact-integration-tests/example1_vscode` as your workspace + - This ensures `--repo .` operates on the correct repository + +5. Open `views.py` in your IDE and use the slash command: + + ```text + /specfact.01-import legacy-api --repo . + ``` + + **Interactive Flow**: + + 1. **Plan Name Prompt**: The AI assistant will prompt: "What name would you like to use for this plan? (e.g., 'API Client v2', 'User Authentication', 'Payment Processing')" + 2. **Provide Plan Name**: Reply with a meaningful name (e.g., "Payment Processing" or "django-example") + - **Suggested plan name for Example 1**: `Payment Processing` or `Legacy Payment View` + 3. **CLI Execution**: The AI will: + - Sanitize the name (lowercase, remove spaces/special chars) + - Run `specfact import from-code --repo --confidence 0.5` + - Capture CLI output and create a project bundle + 4. **CLI Output Summary**: The AI will present a summary showing: + - Bundle name used + - Mode detected (CI/CD or Copilot) + - Features/stories found (may be 0 for minimal test cases) + - Project bundle location: `.specfact/projects//` (modular structure) + - Analysis report location: `.specfact/projects//reports/brownfield/analysis-.md` (bundle-specific, Phase 8.5) + 5. **Next Steps**: The AI will offer options: + - **LLM Enrichment** (optional in CI/CD mode, required in Copilot mode): Add semantic understanding to detect features/stories that AST analysis missed + - Reply: "Please enrich" or "apply enrichment" + - The AI will read the CLI artifacts and code, create an enrichment report, and apply it via CLI + - **Rerun with different confidence**: Try a lower confidence threshold (e.g., 0.3) to catch more features + - Reply: "rerun with confidence 0.3" + + **Note**: For minimal test cases, the CLI may report "0 features" and "0 stories" - this is expected. Use LLM enrichment to add semantic understanding and detect features that AST analysis missed. + + **Enrichment Workflow** (when you choose "Please enrich"): + + 1. **AI Reads Artifacts**: The AI will read: + - The CLI-generated project bundle (`.specfact/projects//` - modular structure) + - The analysis report (`.specfact/projects//reports/brownfield/analysis-.md`) + - Your source code files (e.g., `views.py`) + 2. **Enrichment Report Creation**: The AI will: + - Draft an enrichment markdown file: `-.enrichment.md` (saved to `.specfact/projects//reports/enrichment/`, Phase 8.5) + - Include missing features, stories, confidence adjustments, and business context + - **CRITICAL**: Follow the exact enrichment report format (see [Dual-Stack Enrichment Guide](../../guides/dual-stack-enrichment.md) for format requirements): + - Features must use numbered list: `1. **Feature Title** (Key: FEATURE-XXX)` + - Each feature must have a `Stories:` section with numbered stories + - Stories must have `- Acceptance:` criteria + - Stories must be indented under the feature + 3. **Apply Enrichment**: The AI will run: + + ```bash + specfact import from-code --repo --enrichment .specfact/projects//reports/enrichment/-.enrichment.md --confidence 0.5 + ``` + + 4. **Enriched Project Bundle**: The CLI will update: + - **Project bundle**: `.specfact/projects//` (updated with enrichment) + - **New analysis report**: `report-.md` + 5. **Enrichment Results**: The AI will present: + - Number of features added + - Number of confidence scores adjusted + - Stories included per feature + - Business context added + - Plan validation status + + **Example Enrichment Results**: + - ✅ 1 feature added: `FEATURE-PAYMENTVIEW` (Payment Processing) + - ✅ 4 stories included: Async Payment Processing, Payment Status API, Cancel Payment, Create Payment + - ✅ Business context: Prioritize payment reliability, migrate blocking notifications to async + - ✅ Confidence: 0.88 (adjusted from default) + + **Note**: In interactive mode, `--repo .` is not required - it automatically uses your IDE workspace. If you need to analyze a different repository than your workspace, you can specify: `/specfact.01-import legacy-api --repo /path/to/other/repo` + +### Option B: CLI-only (For Integration Testing) + +```bash +uvx specfact-cli@latest --no-banner import from-code --repo . --output-format yaml +``` + +**Note**: CLI-only mode uses AST-based analysis and may show "0 features" for minimal test cases. This is expected and the plan bundle is still created for manual contract addition. + +**Banner Usage**: + +- **First-time setup**: Omit `--no-banner` to see the banner (verification, `specfact init`, `specfact --version`) +- **Repeated runs**: Use `--no-banner` **before** the command to suppress banner output +- **Important**: `--no-banner` is a global parameter and must come **before** the subcommand, not after + - ✅ Correct: `specfact --no-banner enforce stage --preset balanced` + - ✅ Correct: `uvx specfact-cli@latest --no-banner import from-code --repo . --output-format yaml` + - ❌ Wrong: `specfact enforce stage --preset balanced --no-banner` + - ❌ Wrong: `uvx specfact-cli@latest import from-code --repo . --output-format yaml --no-banner` + +**Note**: The `import from-code` command analyzes the entire repository/directory, not individual files. It will automatically detect and analyze all Python files in the current directory. + +**Important**: These examples are designed for **interactive AI assistant usage** (slash commands in Cursor, VS Code, etc.), not CLI-only execution. + +**CLI vs Interactive Mode**: + +- **CLI-only** (`uvx specfact-cli@latest import from-code` or `specfact import from-code`): Uses AST-based analyzer (CI/CD mode) + - May show "0 features" for minimal test cases + - Limited to AST pattern matching + - Works but may not detect all features in simple examples + - ✅ Works with `uvx` or pip installation + +- **Interactive AI Assistant** (slash commands in IDE): Uses AI-first semantic understanding + - ✅ **Creates valid plan bundles with features and stories** + - Uses AI to understand code semantics + - Works best for these integration showcase examples + - ⚠️ **Requires**: `pip install specfact-cli` + `specfact init` (one-time setup) + +**How to Use These Examples**: + +1. **Recommended**: Use with AI assistant (Cursor, VS Code CoPilot, etc.) + - Install SpecFact: `pip install specfact-cli` + - Navigate to demo repo: `cd /tmp/specfact-integration-tests/example1_vscode` + - Initialize IDE: `specfact init` (copies templates to `.cursor/commands/` in this directory) + - **⚠️ Important**: Open the demo repo directory as your IDE workspace (e.g., `/tmp/specfact-integration-tests/example1_vscode`) + - Interactive mode automatically uses your IDE workspace - no `--repo .` needed + - Open the test file in your IDE + - Use slash command: `/specfact.01-import legacy-api --repo .` + - Or let the AI prompt you for bundle name - provide a meaningful name (e.g., "legacy-api", "payment-service") + - The command will automatically analyze your IDE workspace + - If initial import shows "0 features", reply "Please enrich" to add semantic understanding + - AI will create an enriched plan bundle with detected features and stories + +2. **Alternative**: CLI-only (for integration testing) + - Works with `uvx specfact-cli@latest` or `pip install specfact-cli` + - May show 0 features, but plan bundle is still created + - Can manually add contracts for enforcement testing + - Useful for testing pre-commit hooks, CI/CD workflows + +**Expected Output**: + +- **Interactive mode**: + - AI creates workflow TODOs to track steps + - CLI runs automatically after plan name is provided + - May show "0 features" and "0 stories" for minimal test cases (expected) + - AI presents CLI output summary with mode, features/stories found, and artifact locations + - AI offers next steps: LLM enrichment or rerun with different confidence + - **Project bundle**: `.specfact/projects//` (modular structure) + - **Analysis report**: `.specfact/projects//reports/brownfield/analysis-.md` (bundle-specific, Phase 8.5) + - **After enrichment** (if requested): + - Enrichment report: `.specfact/projects//reports/enrichment/-.enrichment.md` (bundle-specific, Phase 8.5) + - Project bundle updated: `.specfact/projects//` (enriched) + - New analysis report: `.specfact/projects//reports/brownfield/analysis-.md` (bundle-specific, Phase 8.5) + - Features and stories added (e.g., 1 feature with 4 stories) + - Business context and confidence adjustments included +- **CLI-only mode**: Plan bundle created (may show 0 features for minimal cases) + +### Example 1 - Step 3: Review Plan and Add Missing Stories/Contracts + +**Important**: After enrichment, the plan bundle may have features but missing stories or contracts. Use `plan review` to identify gaps and add them via CLI commands. + +**⚠️ Do NOT manually edit `.specfact` artifacts**. All plan management should be done via CLI commands. + +#### Step 3.1: Run Plan Review to Identify Missing Items + +Run plan review to identify missing stories, contracts, and other gaps: + +```bash +cd /tmp/specfact-integration-tests/example1_vscode + +# Run plan review with auto-enrichment to identify gaps (bundle name as positional argument) +specfact --no-banner plan review django-example \ + --auto-enrich \ + --no-interactive \ + --list-findings \ + --findings-format json +``` + +**What to Look For**: + +- ✅ Review findings show missing stories, contracts, or acceptance criteria +- ✅ Critical findings (status: "Missing") that need to be addressed +- ✅ Partial findings (status: "Partial") that can be refined later + +#### Step 3.2: Add Missing Stories via CLI + +If stories are missing, add them using `plan add-story`: + +```bash +# Add the async payment processing story (bundle name via --bundle option) +specfact --no-banner plan add-story \ + --bundle django-example \ + --feature FEATURE-PAYMENTVIEW \ + --key STORY-PAYMENT-ASYNC \ + --title "Async Payment Processing" \ + --acceptance "process_payment does not call blocking notification functions directly; notifications dispatched via async-safe mechanism (task queue or async I/O); end-to-end payment succeeds and returns status: success" \ + --story-points 8 \ + --value-points 10 + +# Add other stories as needed (Payment Status API, Cancel Payment, Create Payment) +specfact --no-banner plan add-story \ + --bundle django-example \ + --feature FEATURE-PAYMENTVIEW \ + --key STORY-PAYMENT-STATUS \ + --title "Payment Status API" \ + --acceptance "get_payment_status returns correct status for existing payment; returns 404-equivalent for missing payment IDs; status values are one of: pending, success, cancelled" \ + --story-points 3 \ + --value-points 5 +``` + +**Note**: In interactive AI assistant mode (slash commands), the AI will automatically add missing stories based on the review findings. You can also use the interactive mode to guide the process. + +#### Step 3.3: Verify Plan Bundle Completeness + +After adding stories, verify the plan bundle is complete: + +```bash +# Re-run plan review to verify all critical items are resolved +specfact --no-banner plan review django-example \ + --no-interactive \ + --list-findings \ + --findings-format json +``` + +**What to Look For**: + +- ✅ No critical "Missing" findings remaining +- ✅ Stories are present in the plan bundle +- ✅ Acceptance criteria are complete and testable + +**Note**: Contracts are **automatically extracted** during `import from-code` by the AST analyzer, but only if function signatures have type hints. For the async bug detection example, detecting "blocking I/O in async context" requires additional analysis (Semgrep async patterns, not just AST contracts). + +#### Step 3.4: Set Up Enforcement Configuration + +```bash +specfact --no-banner enforce stage --preset balanced +``` + +**What to Look For**: + +- ✅ Enforcement mode configured +- ✅ Configuration saved to `.specfact/gates/config/enforcement.yaml` + +#### Step 3.5: Run Code Analysis for Async Violations + +For detecting async violations (like blocking I/O), use the validation suite which includes Semgrep async pattern analysis: + +**Prerequisites**: The setup script (`setup-integration-tests.sh`) already creates the proper project structure and Semgrep config. If you're setting up manually: + +```bash +# Create proper project structure (if not already done) +cd /tmp/specfact-integration-tests/example1_vscode +mkdir -p src tests tools/semgrep + +# The setup script automatically creates tools/semgrep/async.yml +# If running manually, ensure Semgrep config exists at: tools/semgrep/async.yml +``` + +**Note**: The setup script automatically: + +- Creates `tools/semgrep/` directory +- Copies or creates Semgrep async config (`tools/semgrep/async.yml`) +- Checks if Semgrep is installed and provides installation instructions if missing + +**Run Validation**: + +```bash +specfact --no-banner repro --repo . --budget 60 +``` + +**What to Look For**: + +- ✅ Semgrep async pattern analysis runs (if `tools/semgrep/async.yml` exists and Semgrep is installed) +- ✅ Semgrep appears in the summary table with status (PASSED/FAILED/SKIPPED) +- ✅ Detects blocking calls in async context (if violations exist) +- ✅ Reports violations with severity levels +- ⚠️ If Semgrep is not installed or config doesn't exist, this check will be skipped +- 💡 Use `--verbose` flag to see detailed Semgrep output: `specfact --no-banner repro --repo . --budget 60 --verbose` + +**Expected Output Format** (summary table): + +```bash +Check Summary +┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━┓ +┃ Check ┃ Tool ┃ Status ┃ +┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━┩ +│ Linting (ruff) │ ruff │ ✗ FAILED │ +│ Async patterns (semgrep) │ semgrep │ ✓ PASSED │ +│ Type checking (basedpyright) │ basedpyright │ ⊘ SKIPPED │ +│ Contract exploration (CrossHair)│ crosshair │ ✓ PASSED │ +└─────────────────────────────────┴──────────────┴───────────┘ +``` + +**With `--verbose` flag**, you'll see detailed Semgrep output: + +```bash +Async patterns (semgrep) Error: +┌─────────────┐ +│ Scan Status │ +└─────────────┘ + Scanning 46 files tracked by git with 13 Code rules: + Scanning 1 file with 13 python rules. + +┌──────────────┐ +│ Scan Summary │ +└──────────────┘ +✅ Scan completed successfully. + • Findings: 0 (0 blocking) + • Rules run: 13 + • Targets scanned: 1 +``` + +**Note**: + +- Semgrep output is shown in the summary table by default +- Detailed Semgrep output (scan status, findings) is only shown with `--verbose` flag +- If Semgrep is not installed or config doesn't exist, the check will be skipped +- The enforcement workflow still works via `plan compare`, which validates acceptance criteria in the plan bundle +- Use `--fix` flag to apply Semgrep auto-fixes: `specfact --no-banner repro --repo . --budget 60 --fix` + +#### Alternative: Use Plan Compare for Contract Validation + +You can also use `plan compare` to detect deviations between code and plan contracts: + +```bash +specfact --no-banner plan compare --code-vs-plan +``` + +This compares the current code state against the plan bundle contracts and reports any violations. + +### Example 1 - Step 4: Test Enforcement + +Now let's test that enforcement actually works by comparing plans and detecting violations: + +```bash +# Test plan comparison with enforcement (bundle directory paths) +cd /tmp/specfact-integration-tests/example1_vscode +specfact --no-banner plan compare \ + --manual .specfact/projects/django-example \ + --auto .specfact/projects/django-example-auto +``` + +**Expected Output**: + +```bash +============================================================ +Comparison Results +============================================================ + +Total Deviations: 1 + +Deviation Summary: + 🔴 HIGH: 1 + 🟡 MEDIUM: 0 + 🔵 LOW: 0 + +🚫 [HIGH] missing_feature: BLOCK +❌ Enforcement BLOCKED: 1 deviation(s) violate quality gates +Fix the blocking deviations or adjust enforcement config +``` + +**What This Shows**: + +- ✅ Enforcement is working: HIGH severity deviations are blocked +- ✅ Plan comparison detects differences between enriched and original plans +- ✅ Enforcement rules are applied correctly (HIGH → BLOCK) + +**Note**: This test demonstrates that enforcement blocks violations. For the actual async blocking detection, you would use Semgrep async pattern analysis (requires a more complete project structure with `src/` and `tests/` directories). + +### Example 1 - Step 5: Verify Results + +**What We've Accomplished**: + +1. ✅ Created plan bundle from code (`import from-code`) +2. ✅ Enriched plan with semantic understanding (added feature and stories) +3. ✅ Reviewed plan and added missing stories via CLI +4. ✅ Configured enforcement (balanced preset) +5. ✅ Tested enforcement (plan compare detected and blocked violations) + +**Plan Bundle Status**: + +- Features: 1 (`FEATURE-PAYMENTVIEW`) +- Stories: 4 (including `STORY-PAYMENT-ASYNC` with acceptance criteria requiring non-blocking notifications) +- Enforcement: Configured and working + +**Validation Status**: + +- ✅ **Workflow Validated**: End-to-end workflow (import → enrich → review → enforce) works correctly +- ✅ **Enforcement Validated**: Enforcement blocks HIGH severity violations via `plan compare` +- ✅ **Async Detection**: Semgrep integration works (Semgrep available via `pip install semgrep`) + - Semgrep runs async pattern analysis when `tools/semgrep/async.yml` exists + - Semgrep appears in validation summary table with status (PASSED/FAILED/SKIPPED) + - Detailed Semgrep output shown with `--verbose` flag + - `--fix` flag works: adds `--autofix` to Semgrep command for automatic fixes + - Async detection check passes in validation suite + - Proper project structure (`src/` directory) required for Semgrep to scan files + +**Test Results**: + +- Plan bundle: ✅ 1 feature, 4 stories (including `STORY-PAYMENT-ASYNC`) +- Enforcement: ✅ Blocks HIGH severity violations +- Async detection: ✅ Semgrep runs successfully (installed via `pip install semgrep`) + +**Note**: The demo is fully validated. Semgrep is available via `pip install semgrep` and integrates seamlessly with SpecFact CLI. The acceptance criteria in `STORY-PAYMENT-ASYNC` explicitly requires non-blocking notifications, and enforcement will block violations when comparing code against the plan. + +--- + +## Example 2: Cursor Integration - Regression Prevention + +### Example 2 - Step 1: Create Test Files + +```bash +cd /tmp/specfact-integration-tests/example2_cursor +``` + +**Note**: The setup script already initializes a git repository in this directory, so `git init` is not needed. + +Create `src/pipeline.py`: + +```python +# src/pipeline.py - Legacy data processing +def process_data(data: list[dict]) -> dict: + if not data: + return {"status": "empty", "count": 0} + + # Critical: handles None values in data + filtered = [d for d in data if d is not None and d.get("value") is not None] + + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } +``` + +### Example 2 - Step 2: Create Plan with Contract + +**Recommended**: Use interactive AI assistant (slash command in IDE): + +```text +/specfact.01-import legacy-api --repo . +``` + +**Interactive Flow**: + +- The AI assistant will prompt for bundle name if not provided +- **Suggested plan name for Example 2**: `Data Processing` or `Legacy Data Pipeline` +- Reply with the plan name (e.g., "Data Processing or Legacy Data Pipeline") +- The AI will: + 1. Run CLI import (may show 0 features initially - expected for AST-only analysis) + 2. Review artifacts and detect `DataProcessor` class + 3. Generate enrichment report + 4. Apply enrichment via CLI + 5. Add stories via CLI commands if needed + +**Expected Output Format**: + +```text +## Import complete + +### Plan bundles +- Original plan: data-processing-or-legacy-data-pipeline..bundle.yaml +- Enriched plan: data-processing-or-legacy-data-pipeline..enriched..bundle.yaml + +### CLI analysis results +- Features identified: 0 (AST analysis missed the DataProcessor class) +- Stories extracted: 0 +- Confidence threshold: 0.5 + +### LLM enrichment insights +Missing feature discovered: +- FEATURE-DATAPROCESSOR: Data Processing with Legacy Data Support + - Confidence: 0.85 + - Outcomes: + - Process legacy data with None value handling + - Transform and validate data structures + - Filter data by key criteria + +Stories added (4 total): +1. STORY-001: Process Data with None Handling (Story Points: 5 | Value Points: 8) +2. STORY-002: Validate Data Structure (Story Points: 2 | Value Points: 5) +3. STORY-003: Transform Data Format (Story Points: 3 | Value Points: 6) +4. STORY-004: Filter Data by Key (Story Points: 2 | Value Points: 5) + +### Final plan summary +- Features: 1 +- Stories: 4 +- Themes: Core +- Stage: draft +``` + +**Note**: In interactive mode, the command automatically uses your IDE workspace - no `--repo .` parameter needed. + +**Alternative**: CLI-only mode: + +```bash +uvx specfact-cli@latest --no-banner import from-code --repo . --output-format yaml +``` + +**Note**: Interactive mode creates valid plan bundles with features. CLI-only may show 0 features for minimal test cases. Use `--no-banner` before the command to suppress banner output: `specfact --no-banner `. + +### Example 2 - Step 3: Review Plan and Improve Quality + +**Important**: After enrichment, review the plan to identify gaps and improve quality. The `plan review` command can auto-enrich the plan to fix common issues: + +#### Option A: Interactive AI Assistant (Recommended) + +Use the slash command in your IDE: + +```text +/specfact.03-review legacy-api +``` + +**Interactive Flow**: + +- The AI assistant will review the enriched plan bundle +- It will run with `--auto-enrich` to fix common quality issues +- The AI will: + 1. Analyze the plan for missing items (target users, acceptance criteria, etc.) + 2. Create batch update files to address findings + 3. Apply updates via CLI commands + 4. Re-run review to verify improvements + 5. Present a summary of improvements made + +**Expected Output Format**: + +```text +## Review complete + +### Summary +Project Bundle: .specfact/projects/data-processing-or-legacy-data-pipeline/ + +Updates Applied: +- Idea section: Added target users and value hypothesis +- Feature acceptance criteria: Added 3 testable criteria +- Story acceptance criteria: Enhanced all 4 stories with specific, testable Given/When/Then criteria + +### Coverage summary +| Category | Status | Notes | +|----------|--------|-------| +| Functional Scope & Behavior | Clear | Resolved (was Missing) - Added target users | +| Domain & Data Model | Partial | Minor gap (data model constraints) - not critical | +| Interaction & UX Flow | Clear | Resolved (was Partial) - Added error handling | +| Edge Cases & Failure Handling | Clear | Resolved (was Partial) - Added edge case criteria | +| Feature/Story Completeness | Clear | Resolved (was Missing) - Added feature acceptance criteria | + +### Improvements made +1. Target users: Added "Data engineers", "Developers working with legacy data", "Backend developers" +2. Value hypothesis: Added business value statement +3. Feature acceptance criteria: Added 3 testable criteria covering: + - Successful method execution + - None value handling + - Error handling for invalid inputs +4. Story acceptance criteria: Enhanced all 4 stories with: + - Specific method signatures (e.g., `process_data(data: list[dict])`) + - Expected return values (e.g., `dict with 'status' key`) + - Edge cases (empty lists, None values, invalid inputs) + - Error handling scenarios + +### Next steps +- Plan is ready for promotion to `review` stage +- All critical ambiguities resolved +- All acceptance criteria are testable and specific +``` + +#### Option B: CLI-only Mode + +```bash +cd /tmp/specfact-integration-tests/example2_cursor + +# Review plan with auto-enrichment (bundle name as positional argument) +specfact --no-banner plan review data-processing-or-legacy-data-pipeline \ + --auto-enrich \ + --no-interactive \ + --list-findings \ + --findings-format json +``` + +**What to Look For**: + +- ✅ All critical findings resolved (Status: Clear) +- ✅ Feature acceptance criteria added (3 testable criteria) +- ✅ Story acceptance criteria enhanced (specific, testable Given/When/Then format) +- ✅ Target users and value hypothesis added +- ⚠️ Minor partial findings (e.g., data model constraints) are acceptable and not blocking + +**Note**: The `plan review` command with `--auto-enrich` will automatically fix common quality issues via CLI commands, so you don't need to manually edit plan bundles. + +### Example 2 - Step 4: Configure Enforcement + +After plan review is complete and all critical issues are resolved, configure enforcement: + +```bash +cd /tmp/specfact-integration-tests/example2_cursor +specfact --no-banner enforce stage --preset balanced +``` + +**Expected Output**: + +```text +Setting enforcement mode: balanced + Enforcement Mode: + BALANCED +┏━━━━━━━━━━┳━━━━━━━━┓ +┃ Severity ┃ Action ┃ +┡━━━━━━━━━━╇━━━━━━━━┩ +│ HIGH │ BLOCK │ +│ MEDIUM │ WARN │ +│ LOW │ LOG │ +└──────────┴────────┘ + +✓ Enforcement mode set to balanced +Configuration saved to: .specfact/gates/config/enforcement.yaml +``` + +**What to Look For**: + +- ✅ Enforcement mode configured (BALANCED preset) +- ✅ Configuration saved to `.specfact/gates/config/enforcement.yaml` +- ✅ Severity-to-action mapping displayed (HIGH → BLOCK, MEDIUM → WARN, LOW → LOG) + +**Note**: The plan review in Step 3 should have resolved all critical ambiguities and enhanced acceptance criteria. The plan is now ready for enforcement testing. + +### Example 2 - Step 5: Test Plan Comparison + +Test that plan comparison works correctly by comparing the enriched plan against the original plan: + +```bash +cd /tmp/specfact-integration-tests/example2_cursor +specfact --no-banner plan compare \ + --manual .specfact/projects/data-processing-or-legacy-data-pipeline \ + --auto .specfact/projects/data-processing-or-legacy-data-pipeline-auto +``` + +**Expected Output**: + +```text +ℹ️ Writing comparison report to: +.specfact/projects//reports/comparison/report-.md + +============================================================ +SpecFact CLI - Plan Comparison +============================================================ + +ℹ️ Loading manual plan: +ℹ️ Loading auto plan: +ℹ️ Comparing plans... + +============================================================ +Comparison Results +============================================================ + +Manual Plan: +Auto Plan: +Total Deviations: 1 + +Deviation Summary: + 🔴 HIGH: 1 + 🟡 MEDIUM: 0 + 🔵 LOW: 0 + + Deviations by Type and Severity +┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ +┃ Severity ┃ Type ┃ Description ┃ Location ┃ +┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩ +│ 🔴 HIGH │ Missing Feature │ Feature │ features[FEATURE-DATA… │ +│ │ │ 'FEATURE-DATAPROCESSO… │ │ +│ │ │ (Data Processing with │ │ +│ │ │ Legacy Data Support) │ │ +│ │ │ in ma... │ │ +└──────────┴─────────────────┴────────────────────────┴────────────────────────┘ + +============================================================ +Enforcement Rules +============================================================ + +Using enforcement config: .specfact/gates/config/enforcement.yaml + +🚫 [HIGH] missing_feature: BLOCK +❌ Enforcement BLOCKED: 1 deviation(s) violate quality gates +Fix the blocking deviations or adjust enforcement config +❌ Comparison failed: 1 +``` + +**What to Look For**: + +- ✅ Plan comparison runs successfully +- ✅ Deviations detected (enriched plan has features that original plan doesn't) +- ✅ HIGH severity deviation triggers BLOCK action +- ✅ Enforcement blocks the comparison (exit code: 1) +- ✅ Comparison report generated at `.specfact/projects//reports/comparison/report-.md` + +**Note**: This demonstrates that plan comparison works and enforcement blocks HIGH severity violations. The deviation is expected because the enriched plan has additional features/stories that the original AST-derived plan doesn't have. + +### Example 2 - Step 6: Test Breaking Change (Regression Detection) + +**Concept**: This step demonstrates how SpecFact detects when code changes violate contracts. The enriched plan has acceptance criteria requiring None value handling. If code is modified to remove the None check, plan comparison should detect this as a violation. + +**Note**: The actual regression detection would require: + +1. Creating a new plan from the modified (broken) code +2. Comparing the new plan against the enriched plan +3. Detecting that the new plan violates the acceptance criteria + +For demonstration purposes, Step 5 already shows that plan comparison works and enforcement blocks HIGH severity violations. The workflow is: + +1. **Original code** → Import → Create plan → Enrich → Review (creates enriched plan with contracts) +2. **Code changes** (e.g., removing None check) → Import → Create new plan +3. **Compare plans** → Detects violations → Enforcement blocks if HIGH severity + +**To fully demonstrate regression detection**, you would: + +```bash +# 1. Create broken version (removes None check) +cat > src/pipeline_broken.py << 'EOF' +# src/pipeline_broken.py - Broken version without None check +class DataProcessor: + def process_data(self, data: list[dict]) -> dict: + if not data: + return {"status": "empty", "count": 0} + # ⚠️ None check removed + filtered = [d for d in data if d.get("value") is not None] + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } +EOF + +# 2. Temporarily replace original with broken version +mv src/pipeline.py src/pipeline_original.py +mv src/pipeline_broken.py src/pipeline.py + +# 3. Import broken code to create new plan +specfact --no-banner import from-code pipeline-broken --repo . --output-format yaml + +# 4. Compare new plan (from broken code) against enriched plan +specfact --no-banner plan compare \ + --manual .specfact/projects/data-processing-or-legacy-data-pipeline \ + --auto .specfact/projects/pipeline-broken + +# 5. Restore original code +mv src/pipeline.py src/pipeline_broken.py +mv src/pipeline_original.py src/pipeline.py +``` + +**Expected Result**: The comparison should detect that the broken code plan violates the acceptance criteria requiring None value handling, resulting in a HIGH severity deviation that gets blocked by enforcement. + +**What This Demonstrates**: + +- ✅ **Regression Prevention**: SpecFact detects when refactoring removes critical edge case handling +- ✅ **Contract Enforcement**: The None check requirement is enforced via acceptance criteria in the plan +- ✅ **Breaking Change Detection**: `plan compare` identifies when code changes violate plan contracts +- ✅ **Enforcement Blocking**: HIGH severity violations are automatically blocked + +### Example 2 - Step 7: Verify Results + +**What We've Accomplished**: + +1. ✅ Created plan bundle from code (`import from-code`) +2. ✅ Enriched plan with semantic understanding (added FEATURE-DATAPROCESSOR and 4 stories) +3. ✅ Reviewed plan and improved quality (added target users, value hypothesis, feature acceptance criteria, enhanced story acceptance criteria with Given/When/Then format) +4. ✅ Configured enforcement (balanced preset with HIGH → BLOCK, MEDIUM → WARN, LOW → LOG) +5. ✅ Tested plan comparison (detects deviations and blocks HIGH severity violations) +6. ✅ Demonstrated regression detection workflow (plan comparison works, enforcement blocks violations) + +**Plan Bundle Status**: + +- Features: 1 (`FEATURE-DATAPROCESSOR`) +- Stories: 4 (including STORY-001: Process Data with None Handling) +- Enforcement: Configured and working (BALANCED preset) + +**Actual Test Results**: + +- ✅ Enforcement configuration: Successfully configured with BALANCED preset +- ✅ Plan comparison: Successfully detects deviations (1 HIGH severity deviation found) +- ✅ Enforcement blocking: HIGH severity violations are blocked (exit code: 1) +- ✅ Comparison report: Generated at `.specfact/projects//reports/comparison/report-.md` + +**What This Demonstrates**: + +- ✅ **Regression Prevention**: SpecFact detects when refactoring removes critical edge case handling +- ✅ **Contract Enforcement**: The None check requirement is enforced via acceptance criteria in the plan +- ✅ **Breaking Change Detection**: `plan compare` identifies when code changes violate plan contracts +- ✅ **Enforcement Blocking**: HIGH severity violations are automatically blocked by enforcement rules + +**Validation Status**: Example 2 workflow is validated. Plan comparison works correctly and enforcement blocks HIGH severity violations as expected. + +--- + +## Example 3: GitHub Actions Integration - Type Error Detection + +### Example 3 - Step 1: Create Test Files + +```bash +cd /tmp/specfact-integration-tests/example3_github_actions +``` + +**Note**: The setup script already initializes a git repository in this directory, so `git init` is not needed. + +Create `src/api.py`: + +```python +# src/api.py - New endpoint with type mismatch +def get_user_stats(user_id: str) -> dict: + # Simulate: calculate_stats returns int, not dict + stats = 42 # Returns int, not dict + return stats # ⚠️ Type mismatch: int vs dict +``` + +### Example 3 - Step 2: Create Plan with Type Contract + +**Recommended**: Use interactive AI assistant (slash command in IDE): + +```text +/specfact.01-import legacy-api --repo . +``` + +**Interactive Flow**: + +- The AI assistant will prompt for bundle name if not provided +- **Suggested plan name for Example 3**: `User Stats API` or `API Endpoints` +- Reply with the plan name +- The AI will create and enrich the plan bundle with detected features and stories + +**Note**: In interactive mode, the command automatically uses your IDE workspace - no `--repo .` parameter needed. + +**Alternative**: CLI-only mode: + +```bash +specfact --no-banner import from-code --repo . --output-format yaml +``` + +**Note**: Interactive mode creates valid plan bundles with features. CLI-only may show 0 features for minimal test cases. Use `--no-banner` before the command to suppress banner output: `specfact --no-banner `. + +### Example 3 - Step 3: Add Type Contract + +**Note**: Use CLI commands to interact with bundles. Do not edit `.specfact` files directly. Use `plan update-feature` or `plan update-story` commands to add contracts. + +### Example 3 - Step 4: Configure Enforcement + +```bash +cd /tmp/specfact-integration-tests/example3_github_actions +specfact --no-banner enforce stage --preset balanced +``` + +**What to Look For**: + +- ✅ Enforcement mode configured +- ✅ Configuration saved to `.specfact/gates/config/enforcement.yaml` + +### Example 3 - Step 5: Run Validation Checks + +```bash +specfact --no-banner repro --repo . --budget 90 +``` + +**Expected Output Format**: + +```text +Running validation suite... +Repository: . +Time budget: 90s + +⠙ Running validation checks... + +Validation Results + + Check Summary +┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓ +┃ Check ┃ Tool ┃ Status ┃ Duration ┃ +┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩ +│ Linting (ruff) │ ruff │ ✗ FAILED │ 0.03s │ +│ Type checking (basedpyright) │ basedpyright │ ✗ FAILED │ 1.12s │ +│ Contract exploration (CrossHair) │ crosshair │ ✗ FAILED │ 0.58s │ +└──────────────────────────────────┴──────────────┴──────────┴──────────┘ + +Summary: + Total checks: 3 + Passed: 0 + Failed: 3 + Total duration: 1.73s + +Report written to: .specfact/projects//reports/enforcement/report-.yaml + +✗ Some validations failed +``` + +**What to Look For**: + +- ✅ Validation suite runs successfully +- ✅ Check summary table shows status of each check +- ✅ Type checking detects type mismatches (if basedpyright is available) +- ✅ Report generated at `.specfact/projects//reports/enforcement/report-.yaml` (bundle-specific, Phase 8.5) +- ✅ Exit code 1 if violations found (blocks PR merge in GitHub Actions) + +**Note**: The `repro` command runs validation checks conditionally: + +- **Always runs**: + - Linting (ruff) - code style and common Python issues + - Type checking (basedpyright) - type annotations and type safety + +- **Conditionally runs** (only if present): + - Contract exploration (CrossHair) - only if `[tool.crosshair]` config exists in `pyproject.toml` (use `specfact repro setup` to generate) and `src/` directory exists (symbolic execution to find counterexamples, not runtime contract validation) + - Semgrep async patterns - only if `tools/semgrep/async.yml` exists (requires semgrep installed) + - Property tests (pytest) - only if `tests/contracts/` directory exists + - Smoke tests (pytest) - only if `tests/smoke/` directory exists + +**CrossHair Setup**: Before running `repro` for the first time, set up CrossHair configuration: + +```bash +specfact repro setup +``` +This automatically generates `[tool.crosshair]` configuration in `pyproject.toml` to enable contract exploration. + +**Important**: `repro` does **not** perform runtime contract validation (checking `@icontract` decorators at runtime). It runs static analysis (linting, type checking) and symbolic execution (CrossHair) for contract exploration. Type mismatches will be detected by the type checking tool (basedpyright) if available. The enforcement configuration determines whether failures block the workflow. + +### Example 3 - Step 6: Verify Results + +**What We've Accomplished**: + +1. ✅ Created plan bundle from code (`import from-code`) +2. ✅ Enriched plan with semantic understanding (if using interactive mode) +3. ✅ Configured enforcement (balanced preset) +4. ✅ Ran validation suite (`specfact repro`) +5. ✅ Validation checks executed (linting, type checking, contract exploration) + +**Expected Test Results**: + +- Enforcement: ✅ Configured with BALANCED preset +- Validation: ✅ Runs comprehensive checks via `repro` command +- Type checking: ✅ Detects type mismatches (if basedpyright is available) +- Exit code: ✅ Returns 1 if violations found (blocks PR in GitHub Actions) + +**What This Demonstrates**: + +- ✅ **CI/CD Integration**: SpecFact works seamlessly in GitHub Actions +- ✅ **Automated Validation**: `repro` command runs all validation checks +- ✅ **Type Safety**: Type checking detects mismatches before merge +- ✅ **PR Blocking**: Workflow fails (exit code 1) when violations are found + +**Validation Status**: Example 3 is **fully validated** in production CI/CD. The GitHub Actions workflow runs `specfact repro` in the specfact-cli repository and successfully: + +- ✅ Runs linting (ruff) checks +- ✅ Runs async pattern detection (Semgrep) +- ✅ Runs type checking (basedpyright) - detects type errors +- ✅ Runs contract exploration (CrossHair) - conditionally +- ✅ Blocks PRs when validation fails (exit code 1) + +**Production Validation**: The workflow is actively running in [PR #28](https://github.com/nold-ai/specfact-cli/pull/28) and successfully validates code changes. Type checking errors are detected and reported, demonstrating that the CI/CD integration works as expected. + +--- + +## Example 4: Pre-commit Hook - Breaking Change Detection + +### Example 4 - Step 1: Create Test Files + +```bash +cd /tmp/specfact-integration-tests/example4_precommit +``` + +**Note**: The setup script already initializes a git repository in this directory, so `git init` is not needed. + +Create `src/legacy.py`: + +```python +# src/legacy.py - Original function +def process_order(order_id: str) -> dict: + return {"order_id": order_id, "status": "processed"} +``` + +Create `src/caller.py`: + +```python +# src/caller.py - Uses legacy function +from legacy import process_order + +result = process_order(order_id="123") +``` + +### Example 4 - Step 2: Create Initial Plan + +**Recommended**: Use interactive AI assistant (slash command in IDE): + +```text +/specfact.01-import legacy-api --repo . +``` + +**Interactive Flow**: + +- The AI assistant will prompt for bundle name if not provided +- **Suggested plan name for Example 4**: `Order Processing` or `Legacy Order System` +- Reply with the plan name +- The AI will create and enrich the plan bundle with detected features and stories + +**Note**: In interactive mode, the command automatically uses your IDE workspace - no `--repo .` parameter needed. + +**Alternative**: CLI-only mode: + +```bash +specfact --no-banner import from-code --repo . --output-format yaml +``` + +**Important**: After creating the initial plan, we need to make it the default plan so `plan compare --code-vs-plan` can find it. Use `plan select` to set it as the active plan: + +```bash +# Find the created plan bundle +# Use bundle name directly (no need to find file) +BUNDLE_NAME="example4_github_actions" +PLAN_NAME=$(basename "$PLAN_FILE") + +# Set it as the active plan (this makes it the default for plan compare) +specfact --no-banner plan select "$BUNDLE_NAME" --no-interactive + +# Verify it's set as active +specfact --no-banner plan select --current +``` + +**Note**: `plan compare --code-vs-plan` uses the active plan (set via `plan select`) or falls back to the default bundle if no active plan is set. Using `plan select` is the recommended approach as it's cleaner and doesn't require file copying. + +Then commit: + +```bash +git add . +git commit -m "Initial code" +``` + +**Note**: Interactive mode creates valid plan bundles with features. CLI-only may show 0 features for minimal test cases. + +### Example 4 - Step 3: Modify Function (Breaking Change) + +Edit `src/legacy.py` to add a required parameter (breaking change): + +```python +# src/legacy.py - Modified function signature +class OrderProcessor: + """Processes orders.""" + + def process_order(self, order_id: str, user_id: str) -> dict: # ⚠️ Added required user_id + """Process an order with user ID. + + Processes an order and returns its status. + Note: user_id is now required (breaking change). + """ + return {"order_id": order_id, "user_id": user_id, "status": "processed"} + + def get_order(self, order_id: str) -> dict: + """Get order details.""" + return {"id": order_id, "items": []} + + def update_order(self, order_id: str, data: dict) -> dict: + """Update an order.""" + return {"id": order_id, "updated": True, **data} +``` + +**Note**: The caller (`src/caller.py`) still uses the old signature without `user_id`, which will cause a breaking change. + +### Example 4 - Step 3.5: Configure Enforcement (Before Pre-commit Hook) + +Before setting up the pre-commit hook, configure enforcement: + +```bash +cd /tmp/specfact-integration-tests/example4_precommit +specfact --no-banner enforce stage --preset balanced +``` + +**What to Look For**: + +- ✅ Enforcement mode configured (BALANCED preset) +- ✅ Configuration saved to `.specfact/gates/config/enforcement.yaml` +- ✅ Severity-to-action mapping: HIGH → BLOCK, MEDIUM → WARN, LOW → LOG + +**Note**: The pre-commit hook uses this enforcement configuration to determine whether to block commits. + +### Example 4 - Step 4: Set Up Pre-commit Hook + +Create `.git/hooks/pre-commit`: + +```bash +#!/bin/sh +# First, import current code to create a new plan for comparison +# Use default name "auto-derived" so plan compare --code-vs-plan can find it +specfact --no-banner import from-code --repo . --output-format yaml > /dev/null 2>&1 + +# Then compare: uses active plan (set via plan select) as manual, latest code-derived plan as auto +specfact --no-banner plan compare --code-vs-plan +``` + +**What This Does**: + +- Imports current code to create a new plan (auto-derived from modified code) + - **Important**: Uses default name "auto-derived" (or omit `--name`) so `plan compare --code-vs-plan` can find it + - `plan compare --code-vs-plan` looks for plans named `auto-derived.*.bundle.*` +- Compares the new plan (auto) against the active plan (manual/baseline - set via `plan select` in Step 2) +- Uses enforcement configuration to determine if deviations should block the commit +- Blocks commit if HIGH severity deviations are found (based on enforcement preset) + +**Note**: The `--code-vs-plan` flag automatically uses: + +- **Manual plan**: The active plan (set via `plan select`) or `main.bundle.yaml` as fallback +- **Auto plan**: The latest `auto-derived` project bundle (from `import from-code auto-derived` or default bundle name) + +Make it executable: + +```bash +chmod +x .git/hooks/pre-commit +``` + +### Example 4 - Step 5: Test Pre-commit Hook + +```bash +git add src/legacy.py +git commit -m "Breaking change test" +``` + +**What to Look For**: + +- ✅ Pre-commit hook runs +- ✅ Breaking change detected +- ✅ Commit blocked +- ✅ Error message about signature change + +**Expected Output Format**: + +```bash +============================================================ +Code vs Plan Drift Detection +============================================================ + +Comparing intended design (manual plan) vs actual implementation (code-derived plan) + +ℹ️ Using default manual plan: .specfact/projects/django-example/ +ℹ️ Using latest code-derived plan: .specfact/projects/auto-derived/ + +============================================================ +Comparison Results +============================================================ + +Total Deviations: 3 + +Deviation Summary: + 🔴 HIGH: 1 + 🟡 MEDIUM: 0 + 🔵 LOW: 2 + + Deviations by Type and Severity +┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ +┃ Severity ┃ Type ┃ Description ┃ Location ┃ +┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩ +│ 🔴 HIGH │ Missing Feature │ Feature 'FEATURE-*' │ features[FEATURE-*] │ +│ │ │ in manual plan but not │ │ +│ │ │ implemented in code │ │ +└──────────┴─────────────────┴────────────────────────┴────────────────────────┘ + +============================================================ +Enforcement Rules +============================================================ + +🚫 [HIGH] missing_feature: BLOCK +❌ Enforcement BLOCKED: 1 deviation(s) violate quality gates +Fix the blocking deviations or adjust enforcement config +❌ Comparison failed: 1 +``` + +**What This Shows**: + +- ✅ Plan comparison successfully finds both plans (active plan as manual, latest auto-derived as auto) +- ✅ Detects deviations (missing features, mismatches) +- ✅ Enforcement blocks the commit (HIGH → BLOCK based on balanced preset) +- ✅ Pre-commit hook exits with code 1, blocking the commit + +**Note**: The comparison may show deviations like "Missing Feature" when comparing an enriched plan (with AI-added features) against an AST-only plan (which may have 0 features). This is expected behavior - the enriched plan represents the intended design, while the AST-only plan represents what's actually in the code. For breaking change detection, you would compare two code-derived plans (before and after code changes). + +### Example 4 - Step 6: Verify Results + +**What We've Accomplished**: + +1. ✅ Created initial plan bundle from original code (`import from-code`) +2. ✅ Committed the original plan (baseline) +3. ✅ Modified code to introduce breaking change (added required `user_id` parameter) +4. ✅ Configured enforcement (balanced preset with HIGH → BLOCK) +5. ✅ Set up pre-commit hook (`plan compare --code-vs-plan`) +6. ✅ Tested pre-commit hook (commit blocked due to HIGH severity deviation) + +**Plan Bundle Status**: + +- Original plan: Created from initial code (before breaking change) +- New plan: Auto-derived from modified code (with breaking change) +- Comparison: Detects signature change as HIGH severity deviation +- Enforcement: Blocks commit when HIGH severity deviations found + +**Validation Status**: + +- ✅ **Pre-commit Hook**: Successfully blocks commits with breaking changes +- ✅ **Enforcement**: HIGH severity deviations trigger BLOCK action +- ✅ **Plan Comparison**: Detects signature changes and other breaking changes +- ✅ **Workflow**: Complete end-to-end validation (plan → modify → compare → block) + +**What This Demonstrates**: + +- ✅ **Breaking Change Detection**: SpecFact detects when function signatures change +- ✅ **Backward Compatibility**: Pre-commit hook prevents breaking changes from being committed +- ✅ **Local Validation**: No CI delay - issues caught before commit +- ✅ **Enforcement Integration**: Uses enforcement configuration to determine blocking behavior + +--- + +## Example 5: Agentic Workflow - CrossHair Edge Case Discovery + +### Example 5 - Step 1: Create Test Files + +```bash +cd /tmp/specfact-integration-tests/example5_agentic +``` + +**Note**: The setup script already initializes a git repository in this directory, so `git init` is not needed. + +Create `src/validator.py`: + +```python +# src/validator.py - AI-generated validation with edge case +def validate_and_calculate(data: dict) -> float: + value = data.get("value", 0) + divisor = data.get("divisor", 1) + return value / divisor # ⚠️ Edge case: divisor could be 0 +``` + +### Example 5 - Step 2: Run CrossHair Exploration + +```bash +specfact --no-banner contract-test-exploration src/validator.py +``` + +**Note**: If using `uvx`, the command would be: + +```bash +uvx specfact-cli@latest --no-banner contract-test-exploration src/validator.py +``` + +**What to Look For**: + +- ✅ CrossHair runs (if available) +- ✅ Division by zero detected +- ✅ Counterexample found +- ✅ Edge case identified + +**Expected Output Format** (if CrossHair is configured): + +```bash +🔍 CrossHair Exploration: Found counterexample + File: src/validator.py:3 + Function: validate_and_calculate + Issue: Division by zero when divisor=0 + Counterexample: {"value": 10, "divisor": 0} + Severity: HIGH + Fix: Add divisor != 0 check +``` + +**Note**: CrossHair requires additional setup. If not available, we can test with contract enforcement instead. + +### Example 5 - Step 3: Alternative Test (Contract Enforcement) + +If CrossHair is not available, test with contract enforcement: + +```bash +specfact --no-banner enforce stage --preset balanced +``` + +### Example 5 - Step 4: Provide Output + +Please provide: + +1. Output from `contract-test-exploration` (or `enforce stage`) +2. Any CrossHair errors or warnings +3. Whether edge case was detected + +--- + +## Testing Checklist + +For each example, please provide: + +- [ ] **Command executed**: Exact command you ran +- [ ] **Full output**: Complete stdout and stderr +- [ ] **Exit code**: `echo $?` after command +- [ ] **Files created**: List of test files +- [ ] **Project bundle**: Location of `.specfact/projects//` if created +- [ ] **Issues found**: Any problems or unexpected behavior +- [ ] **Expected vs Actual**: Compare expected output with actual + +--- + +## Quick Test Script + +You can also run this script to set up all test cases at once: + +```bash +#!/bin/bash +# setup_all_tests.sh + +BASE_DIR="/tmp/specfact-integration-tests" +mkdir -p "$BASE_DIR" + +# Example 1 +mkdir -p "$BASE_DIR/example1_vscode" +cd "$BASE_DIR/example1_vscode" +cat > views.py << 'EOF' +def process_payment(request): + user = get_user(request.user_id) + payment = create_payment(user.id, request.amount) + send_notification(user.email, payment.id) + return {"status": "success"} +EOF + +# Example 2 +mkdir -p "$BASE_DIR/example2_cursor" +cd "$BASE_DIR/example2_cursor" +cat > src/pipeline.py << 'EOF' +def process_data(data: list[dict]) -> dict: + if not data: + return {"status": "empty", "count": 0} + filtered = [d for d in data if d is not None and d.get("value") is not None] + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } +EOF + +# Example 3 +mkdir -p "$BASE_DIR/example3_github_actions" +cd "$BASE_DIR/example3_github_actions" +cat > src/api.py << 'EOF' +def get_user_stats(user_id: str) -> dict: + stats = 42 + return stats +EOF + +# Example 4 +mkdir -p "$BASE_DIR/example4_precommit" +cd "$BASE_DIR/example4_precommit" +cat > src/legacy.py << 'EOF' +def process_order(order_id: str) -> dict: + return {"order_id": order_id, "status": "processed"} +EOF +cat > caller.py << 'EOF' +from legacy import process_order +result = process_order(order_id="123") +EOF + +# Example 5 +mkdir -p "$BASE_DIR/example5_agentic" +cd "$BASE_DIR/example5_agentic" +cat > src/validator.py << 'EOF' +def validate_and_calculate(data: dict) -> float: + value = data.get("value", 0) + divisor = data.get("divisor", 1) + return value / divisor +EOF + +echo "✅ All test cases created in $BASE_DIR" +``` + +--- + +## Next Steps + +1. **Run each example** following the steps above +2. **Capture output** for each test case +3. **Report results** so we can update the documentation with actual outputs +4. **Identify issues** if any commands don't work as expected + +--- + +## Questions to Answer + +For each example, please answer: + +1. Did the command execute successfully? +2. Was the expected violation/issue detected? +3. Did the output match the expected format? +4. Were there any errors or warnings? +5. What would you change in the documentation based on your testing? + +--- + +## Cleanup After Testing + +After completing all examples, you can clean up the test directories: + +### Option 1: Remove All Test Directories + +```bash +# Remove all test directories +rm -rf /tmp/specfact-integration-tests +``` + +### Option 2: Keep Test Directories for Reference + +If you want to keep the test directories for reference or future testing: + +```bash +# Just remove temporary files (keep structure) +find /tmp/specfact-integration-tests -name "*.pyc" -delete +find /tmp/specfact-integration-tests -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null +find /tmp/specfact-integration-tests -name ".ruff_cache" -type d -exec rm -rf {} + 2>/dev/null +``` + +### Option 3: Archive Test Results + +If you want to save the test results before cleanup: + +```bash +# Create archive of test results +cd /tmp +tar -czf specfact-integration-tests-$(date +%Y%m%d).tar.gz specfact-integration-tests/ + +# Then remove original +rm -rf specfact-integration-tests +``` + +**Note**: The `.specfact` directories contain plan bundles, enforcement configs, and reports that may be useful for reference. Consider archiving them if you want to keep the test results. + +--- + +## Validation Status Summary + +### Example 1: VS Code Integration - ✅ **FULLY VALIDATED** + +**Status**: Fully validated - workflow works, async detection works with Semgrep (available via `pip install semgrep`) + +**What's Validated**: + +- ✅ Plan bundle creation (`import from-code`) +- ✅ Plan enrichment (LLM adds features and stories) +- ✅ Plan review (identifies missing items) +- ✅ Story addition via CLI (`plan add-story`) +- ✅ Enforcement configuration (`enforce stage`) +- ✅ Enforcement blocking (`plan compare` blocks HIGH severity violations) + +**Async Detection Setup** (for full async pattern analysis): + +- ✅ Semgrep available via `pip install semgrep` +- ✅ Proper project structure (`src/` directory) - created by setup script +- ✅ Semgrep config at `tools/semgrep/async.yml` - copied by setup script + +**Test Results**: + +- Plan bundle: ✅ 1 feature, 4 stories (including `STORY-PAYMENT-ASYNC`) +- Enforcement: ✅ Blocks HIGH severity violations +- Async detection: ✅ Semgrep runs successfully (installed via `pip install semgrep`) + +**Conclusion**: Example 1 is **fully validated**. Semgrep is available via `pip install semgrep` and integrates seamlessly with SpecFact CLI. The enforcement workflow works end-to-end, and async blocking detection runs successfully when Semgrep is installed. The acceptance criteria in the plan bundle explicitly requires non-blocking notifications, and enforcement will block violations when comparing code against the plan. + +### Example 2: Cursor Integration - ✅ **FULLY VALIDATED** + +**Status**: Fully validated - workflow works, plan comparison detects deviations, enforcement blocks HIGH severity violations + +**What's Validated**: + +- ✅ Plan bundle creation (`import from-code`) +- ✅ Plan enrichment (LLM adds FEATURE-DATAPROCESSOR and 4 stories) +- ✅ Plan review (auto-enrichment adds target users, value hypothesis, feature acceptance criteria, enhanced story acceptance criteria) +- ✅ Enforcement configuration (`enforce stage` with BALANCED preset) +- ✅ Plan comparison (`plan compare` detects deviations) +- ✅ Enforcement blocking (`plan compare` blocks HIGH severity violations with exit code 1) + +**Test Results**: + +- Plan bundle: ✅ 1 feature (`FEATURE-DATAPROCESSOR`), 4 stories (including STORY-001: Process Data with None Handling) +- Enforcement: ✅ Configured with BALANCED preset (HIGH → BLOCK, MEDIUM → WARN, LOW → LOG) +- Plan comparison: ✅ Detects deviations and blocks HIGH severity violations +- Comparison reports: ✅ Generated at `.specfact/projects//reports/comparison/report-.md` + +**Conclusion**: Example 2 is **fully validated**. The regression prevention workflow works end-to-end. Plan comparison successfully detects deviations between enriched and original plans, and enforcement blocks HIGH severity violations as expected. The workflow demonstrates how SpecFact prevents regressions by detecting when code changes violate plan contracts. + +### Example 4: Pre-commit Hook Integration - ✅ **FULLY VALIDATED** + +**Status**: Fully validated - workflow works, pre-commit hook successfully blocks commits with breaking changes + +**What's Validated**: + +- ✅ Plan bundle creation (`import from-code`) +- ✅ Plan selection (`plan select` sets active plan) +- ✅ Enforcement configuration (`enforce stage` with BALANCED preset) +- ✅ Pre-commit hook setup (imports code, then compares) +- ✅ Plan comparison (`plan compare --code-vs-plan` finds both plans correctly) +- ✅ Enforcement blocking (blocks HIGH severity violations with exit code 1) + +**Test Results**: + +- Plan creation: ✅ `import from-code ` creates project bundle at `.specfact/projects//` (modular structure) +- Plan selection: ✅ `plan select` sets active plan correctly +- Plan comparison: ✅ `plan compare --code-vs-plan` finds: + - Manual plan: Active plan (set via `plan select`) + - Auto plan: Latest `auto-derived` project bundle (`.specfact/projects/auto-derived/`) +- Deviation detection: ✅ Detects deviations (1 HIGH, 2 LOW in test case) +- Enforcement: ✅ Blocks commit when HIGH severity deviations found +- Pre-commit hook: ✅ Exits with code 1, blocking the commit + +**Key Findings**: + +- ✅ `import from-code` should use bundle name "auto-derived" so `plan compare --code-vs-plan` can find it +- ✅ `plan select` is the recommended way to set the baseline plan (cleaner than copying to `main.bundle.yaml`) +- ✅ Pre-commit hook workflow: `import from-code` → `plan compare --code-vs-plan` works correctly +- ✅ Enforcement configuration is respected (HIGH → BLOCK based on preset) + +**Conclusion**: Example 4 is **fully validated**. The pre-commit hook integration works end-to-end. The hook successfully imports current code, compares it against the active plan, and blocks commits when HIGH severity deviations are detected. The workflow demonstrates how SpecFact prevents breaking changes from being committed locally, before they reach CI/CD. + +### Example 3: GitHub Actions Integration - ✅ **FULLY VALIDATED** + +**Status**: Fully validated in production CI/CD - workflow runs `specfact repro` in GitHub Actions and successfully blocks PRs when validation fails + +**What's Validated**: + +- ✅ GitHub Actions workflow configuration (uses `pip install specfact-cli`, includes `specfact repro`) +- ✅ `specfact repro` command execution in CI/CD environment +- ✅ Validation checks execution (linting, type checking, Semgrep, CrossHair) +- ✅ Type checking error detection (basedpyright detects type mismatches) +- ✅ PR blocking when validation fails (exit code 1 blocks merge) + +**Production Validation**: + +- ✅ Workflow actively running in [specfact-cli PR #28](https://github.com/nold-ai/specfact-cli/pull/28) +- ✅ Type checking errors detected and reported in CI/CD +- ✅ Validation suite completes successfully (linting, Semgrep pass, type checking detects issues) +- ✅ Workflow demonstrates CI/CD integration working as expected + +**Test Results** (from production CI/CD): + +- Linting (ruff): ✅ PASSED +- Async patterns (Semgrep): ✅ PASSED +- Type checking (basedpyright): ✗ FAILED (detects type errors correctly) +- Contract exploration (CrossHair): ⊘ SKIPPED (signature analysis limitation, non-blocking) + +**Conclusion**: Example 3 is **fully validated** in production CI/CD. The GitHub Actions workflow successfully runs `specfact repro` and blocks PRs when validation fails. The workflow demonstrates how SpecFact integrates into CI/CD pipelines to prevent bad code from merging. + +### Example 5: Agentic Workflows - ⏳ **PENDING VALIDATION** + +Example 5 follows a similar workflow and should be validated using the same approach: + +1. Create test files +2. Create plan bundle (`import from-code`) +3. Enrich plan (if needed) +4. Review plan and add missing items +5. Configure enforcement +6. Test enforcement + +--- + +**Ready to start?** Begin with Example 1 and work through each one systematically. Share the outputs as you complete each test! diff --git a/_site_local/examples/integration-showcases/integration-showcases.md b/_site_local/examples/integration-showcases/integration-showcases.md new file mode 100644 index 0000000..072289a --- /dev/null +++ b/_site_local/examples/integration-showcases/integration-showcases.md @@ -0,0 +1,564 @@ +# Integration Showcases: Bugs Fixed via CLI Integrations + +> **Core USP**: SpecFact CLI works seamlessly with VS Code, Cursor, GitHub Actions, and any agentic workflow. This document showcases real examples of bugs that were caught and fixed through different integration points. + +--- + +## Overview + +SpecFact CLI works with your existing tools—no new platform to learn. These examples show real bugs that were caught through different integrations. + +### What You Need + +- **Python 3.11+** installed +- **SpecFact CLI** installed (via `pip install specfact-cli` or `uvx specfact-cli@latest`) +- **Your favorite IDE** (VS Code, Cursor, etc.) or CI/CD system + +### Integration Points Covered + +- ✅ **VS Code** - Catch bugs before you commit +- ✅ **Cursor** - Validate AI suggestions automatically +- ✅ **GitHub Actions** - Block bad code from merging +- ✅ **Pre-commit Hooks** - Check code locally before pushing +- ✅ **AI Assistants** - Find edge cases AI might miss + +--- + +## Example 1: VS Code Integration - Caught Async Bug Before Commit + +### The Problem + +A developer was refactoring a legacy Django view to use async/await. The code looked correct but had a subtle async bug that would cause race conditions in production. + +**Original Code**: + +```python +# views.py - Legacy Django view being modernized +def process_payment(request): + user = get_user(request.user_id) + payment = create_payment(user.id, request.amount) + send_notification(user.email, payment.id) # ⚠️ Blocking call in async context + return JsonResponse({"status": "success"}) +``` + +### The Integration + +**Setup** (one-time, takes 2 minutes): + +1. Install SpecFact CLI: `pip install specfact-cli` or use `uvx specfact-cli@latest` +2. Add a pre-commit hook to check code before commits: + +```bash +# .git/hooks/pre-commit +#!/bin/sh +specfact --no-banner enforce stage --preset balanced +``` + +**What This Does**: Runs SpecFact validation automatically before every commit. If it finds issues, the commit is blocked. + +### What SpecFact Caught + +```bash +🚫 Contract Violation: Blocking I/O in async context + File: views.py:45 + Function: process_payment + Issue: send_notification() is a blocking call + Severity: HIGH + Fix: Use async version or move to background task +``` + +### The Fix + +```python +# Fixed code +async def process_payment(request): + user = await get_user_async(request.user_id) + payment = await create_payment_async(user.id, request.amount) + await send_notification_async(user.email, payment.id) # ✅ Async call + return JsonResponse({"status": "success"}) +``` + +### Result + +- ✅ **Bug caught**: Before commit (local validation) +- ✅ **Time saved**: Prevented production race condition +- ✅ **Integration**: VS Code + pre-commit hook +- ✅ **No platform required**: Pure CLI integration + +--- + +## Example 2: Cursor Integration - Prevented Regression During Refactoring + +### The Problem + +A developer was using Cursor AI to refactor a legacy data pipeline. The AI assistant suggested changes that looked correct but would have broken a critical edge case. + +**Original Code**: + +```python +# pipeline.py - Legacy data processing +def process_data(data: list[dict]) -> dict: + if not data: + return {"status": "empty", "count": 0} + + # Critical: handles None values in data + filtered = [d for d in data if d is not None and d.get("value") is not None] + + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } +``` + +### The Integration + +**Setup** (one-time): + +1. Install SpecFact CLI: `pip install specfact-cli` +2. Initialize SpecFact in your project: `specfact init` +3. Use the slash command in Cursor: `/specfact.03-review legacy-api` + +**What This Does**: When Cursor suggests code changes, SpecFact checks if they break existing contracts or introduce regressions. + +### What SpecFact Caught + +The AI suggested removing the `None` check, which would have broken the edge case: + +```bash +🚫 Contract Violation: Missing None check + File: pipeline.py:12 + Function: process_data + Issue: Suggested code removes None check, breaking edge case + Severity: HIGH + Contract: Must handle None values in input data + Fix: Keep None check or add explicit contract +``` + +### The Fix + +```python +# AI suggestion rejected, kept original with contract +@icontract.require(lambda data: isinstance(data, list)) +@icontract.ensure(lambda result: result["count"] >= 0) +def process_data(data: list[dict]) -> dict: + if not data: + return {"status": "empty", "count": 0} + + # Contract enforces None handling + filtered = [d for d in data if d is not None and d.get("value") is not None] + + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } +``` + +### Result + +- ✅ **Regression prevented**: Edge case preserved +- ✅ **AI validation**: Cursor suggestions validated before acceptance +- ✅ **Integration**: Cursor + SpecFact CLI +- ✅ **Contract enforcement**: Runtime guarantees maintained + +--- + +## Example 3: GitHub Actions Integration - Blocked Merge with Type Error + +### The Problem + +A developer submitted a PR that added a new feature but introduced a type mismatch that would cause runtime errors. + +**PR Code**: + +```python +# api.py - New endpoint added +def get_user_stats(user_id: str) -> dict: + user = User.objects.get(id=user_id) + stats = calculate_stats(user) # Returns int, not dict + return stats # ⚠️ Type mismatch: int vs dict +``` + +### The Integration + +**Setup** (add to your GitHub repository): + +Create `.github/workflows/specfact-enforce.yml`: + +```yaml +name: SpecFact Validation + +on: + pull_request: + branches: [main] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + cache: "pip" + - name: Install SpecFact CLI + run: pip install specfact-cli + - name: Configure Enforcement + run: specfact --no-banner enforce stage --preset balanced + - name: Run SpecFact Validation + run: specfact --no-banner repro --repo . --budget 90 +``` + +**What This Does**: + +1. **Configure Enforcement**: Sets enforcement mode to `balanced` (blocks HIGH severity violations, warns on MEDIUM) +2. **Run Validation**: Executes `specfact repro` which runs validation checks: + + **Always runs**: + - Linting (ruff) - checks code style and common Python issues + - Type checking (basedpyright) - validates type annotations and type safety + + **Conditionally runs** (only if present): + - Contract exploration (CrossHair) - if `src/` directory exists (symbolic execution to find counterexamples) + - Async patterns (semgrep) - if `tools/semgrep/async.yml` exists (requires semgrep installed) + - Property tests (pytest) - if `tests/contracts/` directory exists + - Smoke tests (pytest) - if `tests/smoke/` directory exists + + **Note**: `repro` does not perform runtime contract validation (checking `@icontract` decorators at runtime). It runs static analysis tools (linting, type checking) and symbolic execution (CrossHair) for contract exploration. + +**Expected Output**: + +```text +Running validation suite... +Repository: . +Time budget: 90s + +⠙ Running validation checks... + +Validation Results + + Check Summary +┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓ +┃ Check ┃ Tool ┃ Status ┃ Duration ┃ +┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩ +│ Linting (ruff) │ ruff │ ✗ FAILED │ 0.03s │ +│ Type checking (basedpyright) │ basedpyright │ ✗ FAILED │ 1.12s │ +│ Contract exploration (CrossHair) │ crosshair │ ✗ FAILED │ 0.58s │ +└──────────────────────────────────┴──────────────┴──────────┴──────────┘ + +Summary: + Total checks: 3 + Passed: 0 + Failed: 3 + Total duration: 1.73s + +Report written to: .specfact/projects//reports/enforcement/report-.yaml + +✗ Some validations failed +``` + +If SpecFact finds violations that trigger enforcement rules, the workflow fails (exit code 1) and the PR is blocked from merging. + +### What SpecFact Caught + +```bash +🚫 Contract Violation: Return type mismatch + File: api.py:45 + Function: get_user_stats + Issue: Function returns int, but contract requires dict + Severity: HIGH + Contract: @ensure(lambda result: isinstance(result, dict)) + Fix: Return dict with stats, not raw int +``` + +### The Fix + +```python +# Fixed code +@icontract.ensure(lambda result: isinstance(result, dict)) +def get_user_stats(user_id: str) -> dict: + user = User.objects.get(id=user_id) + stats_value = calculate_stats(user) + return {"stats": stats_value} # ✅ Returns dict +``` + +### Result + +- ✅ **Merge blocked**: PR failed CI check +- ✅ **Type safety**: Runtime type error prevented +- ✅ **Integration**: GitHub Actions + SpecFact CLI +- ✅ **Automated**: No manual review needed + +--- + +## Example 4: Pre-commit Hook - Caught Undocumented Breaking Change + +### The Problem + +A developer modified a legacy function's signature without updating callers, breaking backward compatibility. + +**Modified Code**: + +```python +# legacy.py - Function signature changed +def process_order(order_id: str, user_id: str) -> dict: # ⚠️ Added required user_id + # ... implementation +``` + +**Caller Code** (not updated): + +```python +# caller.py - Still using old signature +result = process_order(order_id="123") # ⚠️ Missing user_id +``` + +### The Integration + +**Setup** (one-time): + +1. Configure enforcement: `specfact --no-banner enforce stage --preset balanced` +2. Add pre-commit hook: + +```bash +# .git/hooks/pre-commit +#!/bin/sh +# Import current code to create a new plan for comparison +# Use bundle name "auto-derived" so plan compare --code-vs-plan can find it +specfact --no-banner import from-code auto-derived --repo . --output-format yaml > /dev/null 2>&1 + +# Compare: uses active plan (set via plan select) as manual, latest auto-derived plan as auto +specfact --no-banner plan compare --code-vs-plan +``` + +**What This Does**: Before you commit, SpecFact imports your current code to create a new plan, then compares it against the baseline plan. If it detects breaking changes with HIGH severity, the commit is blocked (based on enforcement configuration). + +### What SpecFact Caught + +```bash +🚫 Contract Violation: Breaking change detected + File: legacy.py:12 + Function: process_order + Issue: Signature changed from (order_id) to (order_id, user_id) + Severity: HIGH + Impact: 3 callers will break + Fix: Make user_id optional or update all callers +``` + +### The Fix + +```python +# Fixed: Made user_id optional to maintain backward compatibility +def process_order(order_id: str, user_id: str | None = None) -> dict: + if user_id is None: + # Legacy behavior + user_id = get_default_user_id() + # ... implementation +``` + +### Result + +- ✅ **Breaking change caught**: Before commit +- ✅ **Backward compatibility**: Maintained +- ✅ **Integration**: Pre-commit hook + SpecFact CLI +- ✅ **Local validation**: No CI delay + +--- + +## Example 5: Agentic Workflow - CrossHair Found Edge Case + +### The Problem + +A developer was using an AI coding assistant to add input validation. The code looked correct but had an edge case that would cause division by zero. + +**AI-Generated Code**: + +```python +# validator.py - AI-generated validation +def validate_and_calculate(data: dict) -> float: + value = data.get("value", 0) + divisor = data.get("divisor", 1) + return value / divisor # ⚠️ Edge case: divisor could be 0 +``` + +### The Integration + +**Setup** (when using AI assistants): + +1. Install SpecFact CLI: `pip install specfact-cli` +2. Use the slash command in your AI assistant: `/specfact-contract-test-exploration` + +**What This Does**: Uses mathematical proof (not guessing) to find edge cases that AI might miss, like division by zero or None handling issues. + +### What SpecFact Caught + +**CrossHair Symbolic Execution** discovered the edge case: + +```bash +🔍 CrossHair Exploration: Found counterexample + File: validator.py:5 + Function: validate_and_calculate + Issue: Division by zero when divisor=0 + Counterexample: {"value": 10, "divisor": 0} + Severity: HIGH + Fix: Add divisor != 0 check +``` + +### The Fix + +```python +# Fixed with contract +@icontract.require(lambda data: data.get("divisor", 1) != 0) +def validate_and_calculate(data: dict) -> float: + value = data.get("value", 0) + divisor = data.get("divisor", 1) + return value / divisor # ✅ Contract ensures divisor != 0 +``` + +### Result + +- ✅ **Edge case found**: Mathematical proof, not LLM guess +- ✅ **Symbolic execution**: CrossHair discovered counterexample +- ✅ **Integration**: Agentic workflow + SpecFact CLI +- ✅ **Formal verification**: Deterministic, not probabilistic + +--- + +## Integration Patterns + +### Pattern 1: Pre-commit Validation + +**Best For**: Catching issues before they enter the repository + +**Setup**: + +```bash +# .git/hooks/pre-commit +#!/bin/sh +specfact --no-banner enforce stage --preset balanced +``` + +**Benefits**: + +- ✅ Fast feedback (runs locally) +- ✅ Prevents bad commits +- ✅ Works with any IDE or editor + +### Pattern 2: CI/CD Integration + +**Best For**: Automated validation in pull requests + +**Setup** (GitHub Actions example): + +```yaml +- name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + cache: "pip" +- name: Install SpecFact CLI + run: pip install specfact-cli +- name: Configure Enforcement + run: specfact --no-banner enforce stage --preset balanced +- name: Run SpecFact Validation + run: specfact --no-banner repro --repo . --budget 90 +``` + +**Benefits**: + +- ✅ Blocks merges automatically +- ✅ Same checks for everyone on the team +- ✅ No manual code review needed for these issues + +### Pattern 3: IDE Integration + +**Best For**: Real-time validation while coding + +**Setup** (VS Code example): + +```json +// .vscode/tasks.json +{ + "label": "SpecFact Validate", + "type": "shell", + "command": "specfact --no-banner enforce stage --preset balanced" +} +``` + +**Benefits**: + +- ✅ Immediate feedback as you code +- ✅ Works with any editor (VS Code, Cursor, etc.) +- ✅ No special extension needed + +### Pattern 4: AI Assistant Integration + +**Best For**: Validating AI-generated code suggestions + +**Setup**: + +1. Install SpecFact: `pip install specfact-cli` +2. Initialize: `specfact init` (creates slash commands for your IDE) +3. Use slash commands like `/specfact.03-review legacy-api` in Cursor or GitHub Copilot + +**Benefits**: + +- ✅ Catches bugs in AI suggestions +- ✅ Prevents AI from making mistakes +- ✅ Uses formal proof, not guessing + +--- + +## Key Takeaways + +### ✅ What Makes These Integrations Work + +1. **CLI-First Design**: Works with any tool, no platform lock-in +2. **Standard Exit Codes**: Integrates with any CI/CD system +3. **Fast Execution**: < 10 seconds for most validations +4. **Formal Guarantees**: Runtime contracts + symbolic execution +5. **Zero Configuration**: Works out of the box + +### ✅ Bugs Caught That Other Tools Missed + +- **Async bugs**: Blocking calls in async context +- **Type mismatches**: Runtime type errors +- **Breaking changes**: Backward compatibility issues +- **Edge cases**: Division by zero, None handling +- **Contract violations**: Missing preconditions/postconditions + +### ✅ Integration Benefits + +- **VS Code**: Pre-commit validation, no extension needed +- **Cursor**: AI suggestion validation +- **GitHub Actions**: Automated merge blocking +- **Pre-commit**: Local validation before commits +- **Agentic Workflows**: Formal verification of AI code + +--- + +## Next Steps + +1. **Try an Integration**: Pick your IDE/CI and add SpecFact validation +2. **Share Your Example**: Document bugs you catch via integrations +3. **Contribute**: Add integration examples to this document + +--- + +## Related Documentation + +- **[Getting Started](../../getting-started/README.md)** - Installation and setup +- **[IDE Integration](../../guides/ide-integration.md)** - Set up integrations +- **[Use Cases](../../guides/use-cases.md)** - More real-world scenarios +- **[Dogfooding Example](../dogfooding-specfact-cli.md)** - SpecFact analyzing itself + +--- + +**Remember**: SpecFact CLI's core USP is **seamless integration** into your existing workflow. These examples show how different integrations caught real bugs that other tools missed. Start with one integration, then expand as you see value. diff --git a/_site_local/examples/integration-showcases/setup-integration-tests.sh b/_site_local/examples/integration-showcases/setup-integration-tests.sh new file mode 100755 index 0000000..02d5d57 --- /dev/null +++ b/_site_local/examples/integration-showcases/setup-integration-tests.sh @@ -0,0 +1,363 @@ +#!/bin/bash +# setup-integration-tests.sh +# Quick setup script for integration showcase testing +# +# Usage: +# From specfact-cli repo root: +# ./docs/examples/integration-showcases/setup-integration-tests.sh +# +# Or from this directory: +# ./setup-integration-tests.sh +# +# Prerequisites: +# - Python 3.11+ (required by specfact-cli) +# - pip install specfact-cli (for interactive AI assistant mode) +# - pip install semgrep (optional, for async pattern detection in Example 1) +# - specfact init (one-time IDE setup) +# +# This script creates test cases in /tmp/specfact-integration-tests/ for +# validating the integration showcase examples. +# +# Project Structure Created: +# - All examples use src/ directory for source code (required for specfact repro) +# - tests/ directory created for test files +# - tools/semgrep/ directory created for Example 1 (Semgrep async config copied if available) + +set -e + +BASE_DIR="/tmp/specfact-integration-tests" +echo "📁 Creating test directory: $BASE_DIR" +mkdir -p "$BASE_DIR" +cd "$BASE_DIR" + +# Example 1: VS Code Integration +echo "📝 Setting up Example 1: VS Code Integration" +mkdir -p example1_vscode/src example1_vscode/tests example1_vscode/tools/semgrep +cd example1_vscode +git init > /dev/null 2>&1 || true + +# Copy Semgrep config if available from specfact-cli repo +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)" +if [ -f "$REPO_ROOT/src/specfact_cli/resources/semgrep/async.yml" ]; then + cp "$REPO_ROOT/src/specfact_cli/resources/semgrep/async.yml" tools/semgrep/ 2>/dev/null || true + echo "✅ Copied Semgrep async config" +elif [ -f "$REPO_ROOT/tools/semgrep/async.yml" ]; then + cp "$REPO_ROOT/tools/semgrep/async.yml" tools/semgrep/ 2>/dev/null || true + echo "✅ Copied Semgrep async config" +else + echo "⚠️ Semgrep config not found - creating minimal config" + # Create minimal Semgrep config for async detection + cat > tools/semgrep/async.yml << 'SEMGREP_EOF' +rules: + - id: blocking-io-in-async + pattern: | + def $FUNC(...): + ... + $CALL(...) + message: Blocking I/O call in potentially async context + languages: [python] + severity: ERROR +SEMGREP_EOF + echo "✅ Created minimal Semgrep async config" +fi + +# Check if semgrep is installed, offer to install if not +if ! command -v semgrep &> /dev/null; then + echo "⚠️ Semgrep not found in PATH" + echo " To enable async pattern detection, install Semgrep:" + echo " pip install semgrep" + echo " (This is optional - async detection will be skipped if Semgrep is not installed)" +else + echo "✅ Semgrep found: $(semgrep --version | head -1)" +fi + +cat > src/views.py << 'EOF' +# views.py - Legacy Django view with async bug +"""Payment processing views for legacy Django application.""" + +from typing import Dict, Any + +class PaymentView: + """Legacy Django view being modernized to async. + + This view handles payment processing operations including + creating payments, checking status, and cancelling payments. + """ + + def process_payment(self, request): + """Process payment with blocking I/O call. + + This method processes a payment request and sends a notification. + The send_notification call is blocking and should be async. + """ + user = get_user(request.user_id) + payment = create_payment(user.id, request.amount) + send_notification(user.email, payment.id) # ⚠️ Blocking call in async context + return {"status": "success"} + + def get_payment_status(self, payment_id: str) -> dict: + """Get payment status by ID. + + Returns the current status of a payment. + """ + return {"id": payment_id, "status": "pending"} + + def cancel_payment(self, payment_id: str) -> dict: + """Cancel a payment. + + Cancels an existing payment and returns the updated status. + """ + return {"id": payment_id, "status": "cancelled"} + + def create_payment(self, user_id: str, amount: float) -> dict: + """Create a new payment. + + Creates a new payment record for the specified user and amount. + """ + return {"id": "123", "user_id": user_id, "amount": amount} +EOF +echo "✅ Example 1 setup complete (src/views.py created)" +cd .. + +# Example 2: Cursor Integration +echo "📝 Setting up Example 2: Cursor Integration" +mkdir -p example2_cursor/src example2_cursor/tests +cd example2_cursor +git init > /dev/null 2>&1 || true +cat > src/pipeline.py << 'EOF' +# pipeline.py - Legacy data processing +class DataProcessor: + """Processes data with None value handling. + + This processor handles data transformation and validation, + with special attention to None value handling for legacy data. + """ + + def process_data(self, data: list[dict]) -> dict: + """Process data with critical None handling. + + Processes a list of data dictionaries, filtering out None values + and calculating totals. Critical for handling legacy data formats. + """ + if not data: + return {"status": "empty", "count": 0} + + # Critical: handles None values in data + filtered = [d for d in data if d is not None and d.get("value") is not None] + + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } + + def validate_data(self, data: list[dict]) -> bool: + """Validate data structure. + + Checks if data is a non-empty list of dictionaries. + """ + return isinstance(data, list) and len(data) > 0 + + def transform_data(self, data: list[dict]) -> list[dict]: + """Transform data format. + + Transforms data by adding a processed flag to each item. + """ + return [{"processed": True, **item} for item in data if item] + + def filter_data(self, data: list[dict], key: str) -> list[dict]: + """Filter data by key. + + Returns only items that contain the specified key. + """ + return [item for item in data if key in item] +EOF +echo "✅ Example 2 setup complete (src/pipeline.py created)" +cd .. + +# Example 3: GitHub Actions Integration +echo "📝 Setting up Example 3: GitHub Actions Integration" +mkdir -p example3_github_actions/src example3_github_actions/tests +cd example3_github_actions +git init > /dev/null 2>&1 || true +cat > src/api.py << 'EOF' +# api.py - New endpoint with type mismatch +class UserAPI: + """User API endpoints. + + Provides REST API endpoints for user management operations + including profile retrieval, statistics, and updates. + """ + + def get_user_stats(self, user_id: str) -> dict: + """Get user statistics. + + Returns user statistics as a dictionary. Note: This method + has a type mismatch bug - returns int instead of dict. + """ + # Simulate: calculate_stats returns int, not dict + stats = 42 # Returns int, not dict + return stats # ⚠️ Type mismatch: int vs dict + + def get_user_profile(self, user_id: str) -> dict: + """Get user profile information. + + Retrieves the complete user profile for the given user ID. + """ + return {"id": user_id, "name": "John Doe"} + + def update_user(self, user_id: str, data: dict) -> dict: + """Update user information. + + Updates user information with the provided data. + """ + return {"id": user_id, "updated": True, **data} + + def create_user(self, user_data: dict) -> dict: + """Create a new user. + + Creates a new user with the provided data. + """ + return {"id": "new-123", **user_data} +EOF +echo "✅ Example 3 setup complete (src/api.py created)" +cd .. + +# Example 4: Pre-commit Hook +echo "📝 Setting up Example 4: Pre-commit Hook" +mkdir -p example4_precommit/src example4_precommit/tests +cd example4_precommit +git init > /dev/null 2>&1 || true +cat > src/legacy.py << 'EOF' +# legacy.py - Original function +class OrderProcessor: + """Processes orders. + + Handles order processing operations including order creation, + status retrieval, and order updates. + """ + + def process_order(self, order_id: str) -> dict: + """Process an order. + + Processes an order and returns its status. + """ + return {"order_id": order_id, "status": "processed"} + + def get_order(self, order_id: str) -> dict: + """Get order details. + + Retrieves order information by order ID. + """ + return {"id": order_id, "items": []} + + def update_order(self, order_id: str, data: dict) -> dict: + """Update an order. + + Updates order information with the provided data. + """ + return {"id": order_id, "updated": True, **data} +EOF +cat > src/caller.py << 'EOF' +# caller.py - Uses legacy function +from legacy import OrderProcessor + +processor = OrderProcessor() +result = processor.process_order(order_id="123") +EOF +# Create pre-commit hook (enforcement must be configured separately) +mkdir -p .git/hooks +cat > .git/hooks/pre-commit << 'EOF' +#!/bin/sh +specfact --no-banner plan compare --code-vs-plan +EOF +chmod +x .git/hooks/pre-commit +echo "⚠️ Pre-commit hook created. Remember to run 'specfact enforce stage --preset balanced' before testing." +echo "✅ Example 4 setup complete (src/legacy.py, src/caller.py, pre-commit hook created)" +cd .. + +# Example 5: Agentic Workflow +echo "📝 Setting up Example 5: Agentic Workflow" +mkdir -p example5_agentic/src example5_agentic/tests +cd example5_agentic +git init > /dev/null 2>&1 || true +cat > src/validator.py << 'EOF' +# validator.py - AI-generated validation with edge case +class DataValidator: + """Validates and calculates data. + + Provides validation and calculation utilities for data processing, + with support for various data types and formats. + """ + + def validate_and_calculate(self, data: dict) -> float: + """Validate data and perform calculation. + + Validates input data and performs division calculation. + Note: This method has an edge case bug - divisor could be 0. + """ + value = data.get("value", 0) + divisor = data.get("divisor", 1) + return value / divisor # ⚠️ Edge case: divisor could be 0 + + def validate_input(self, data: dict) -> bool: + """Validate input data structure. + + Checks if data is a valid dictionary with required fields. + """ + return isinstance(data, dict) and "value" in data + + def calculate_total(self, values: list[float]) -> float: + """Calculate total from list of values. + + Sums all values in the provided list. + """ + return sum(values) if values else 0.0 + + def check_data_quality(self, data: dict) -> bool: + """Check data quality. + + Performs quality checks on the provided data dictionary. + """ + return isinstance(data, dict) and len(data) > 0 +EOF +echo "✅ Example 5 setup complete (src/validator.py created)" +cd .. + +echo "" +echo "✅ All test cases created in $BASE_DIR" +echo "" +echo "📋 Test directories:" +echo " 1. example1_vscode - VS Code async bug detection" +echo " 2. example2_cursor - Cursor regression prevention" +echo " 3. example3_github_actions - GitHub Actions type error" +echo " 4. example4_precommit - Pre-commit breaking change" +echo " 5. example5_agentic - Agentic workflow edge case" +echo "" +echo "⚠️ IMPORTANT: For Interactive AI Assistant Usage" +echo "" +echo " Before using slash commands in your IDE, you need to:" +echo " 1. Install SpecFact via pip: pip install specfact-cli" +echo " 2. Initialize IDE integration (one-time per project):" +echo " cd $BASE_DIR/example1_vscode" +echo " specfact init" +echo "" +echo " This sets up prompt templates so slash commands work." +echo "" +echo "🚀 Next steps:" +echo " 1. Follow the testing guide: integration-showcases-testing-guide.md (in this directory)" +echo " 2. Install SpecFact: pip install specfact-cli" +echo " 3. Initialize IDE: cd $BASE_DIR/example1_vscode && specfact init" +echo " 4. Open test file in IDE and use slash command: /specfact.01-import legacy-api --repo ." +echo " (Interactive mode automatically uses IDE workspace - --repo . optional)" +echo "" +echo "📚 Documentation:" +echo " - Testing Guide: docs/examples/integration-showcases/integration-showcases-testing-guide.md" +echo " - Quick Reference: docs/examples/integration-showcases/integration-showcases-quick-reference.md" +echo " - Showcases: docs/examples/integration-showcases/integration-showcases.md" +echo "" + diff --git a/_site_local/feed/index.xml b/_site_local/feed/index.xml new file mode 100644 index 0000000..fea52a0 --- /dev/null +++ b/_site_local/feed/index.xml @@ -0,0 +1 @@ +Jekyll2026-01-05T02:10:01+01:00https://nold-ai.github.io/specfact-cli/feed/SpecFact CLI DocumentationComplete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. \ No newline at end of file diff --git a/_site_local/getting-started/README.md b/_site_local/getting-started/README.md new file mode 100644 index 0000000..7377db6 --- /dev/null +++ b/_site_local/getting-started/README.md @@ -0,0 +1,54 @@ +# Getting Started with SpecFact CLI + +Welcome to SpecFact CLI! This guide will help you get started in under 60 seconds. + +## Installation + +Choose your preferred installation method: + +- **[Installation Guide](installation.md)** - All installation options (uvx, pip, Docker, GitHub Actions) +- **[Enhanced Analysis Dependencies](../installation/enhanced-analysis-dependencies.md)** - Optional dependencies for graph-based analysis (pyan3, syft, bearer, graphviz) + +## Quick Start + +### Your First Command + +**For Legacy Code Modernization** (Recommended): + +```bash +# CLI-only mode (works with uvx, no installation needed) +uvx specfact-cli@latest import from-code my-project --repo . + +# Interactive AI Assistant mode (requires pip install + specfact init) +# See First Steps guide for IDE integration setup +``` + +**For New Projects**: + +```bash +# CLI-only mode (bundle name as positional argument) +uvx specfact-cli@latest plan init my-project --interactive + +# Interactive AI Assistant mode (recommended for better results) +# Requires: pip install specfact-cli && specfact init +``` + +**Note**: Interactive AI Assistant mode provides better feature detection and semantic understanding, but requires `pip install specfact-cli` and IDE setup. CLI-only mode works immediately with `uvx` but may show 0 features for simple test cases. + +### Modernizing Legacy Code? + +**New to brownfield modernization?** See our **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** for a complete walkthrough of modernizing legacy Python code with SpecFact CLI. + +## Next Steps + +- 📖 **[Installation Guide](installation.md)** - Install SpecFact CLI +- 📖 **[First Steps](first-steps.md)** - Step-by-step first commands +- 📖 **[Tutorial: Using SpecFact with OpenSpec or Spec-Kit](tutorial-openspec-speckit.md)** ⭐ **NEW** - Complete beginner-friendly tutorial +- 📖 **[Use Cases](../guides/use-cases.md)** - See real-world examples +- 📖 **[Command Reference](../reference/commands.md)** - Learn all available commands + +## Need Help? + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_local/getting-started/first-steps/index.html b/_site_local/getting-started/first-steps/index.html new file mode 100644 index 0000000..a1f32a1 --- /dev/null +++ b/_site_local/getting-started/first-steps/index.html @@ -0,0 +1,609 @@ + + + + + + + +Your First Steps with SpecFact CLI | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Your First Steps with SpecFact CLI

+ +

This guide walks you through your first commands with SpecFact CLI, with step-by-step explanations.

+ +

Before You Start

+ +
    +
  • Install SpecFact CLI (if not already installed)
    • +
  • Python 3.11+ required: Check with python3 --version
    • +
  • Choose your scenario below
    • +
+ +

Installation Options:

+ +
    +
  • Quick start (CLI-only): uvx specfact-cli@latest --help (no installation needed)
    • +
  • Better results (Interactive): pip install specfact-cli + specfact init (recommended for legacy code)
    • +
+ +
+ +

Scenario 1: Modernizing Legacy Code ⭐ PRIMARY

+ +

Goal: Reverse engineer existing code into documented specs

+ +

Time: < 5 minutes

+ +

Step 1: Analyze Your Legacy Codebase

+ +

Option A: CLI-only Mode (Quick start, works with uvx):

+ +
uvx specfact-cli@latest import from-code my-project --repo .
+
+ +

Option B: Interactive AI Assistant Mode (Recommended for better results):

+ +
# Step 1: Install SpecFact CLI
+pip install specfact-cli
+
+# Step 2: Navigate to your project
+cd /path/to/your/project
+
+# Step 3: Initialize IDE integration (one-time)
+specfact init
+
+# Step 4: Use slash command in IDE chat
+/specfact.01-import legacy-api --repo .
+# Or let the AI assistant prompt you for bundle name
+
+ +

What happens:

+ +
    +
  • Auto-detects project context: Language, framework, existing specs, and configuration
    • +
  • Analyzes all Python files in your repository
    • +
  • Extracts features, user stories, and business logic from code
    • +
  • Generates dependency graphs
    • +
  • Creates plan bundle with extracted specs
    • +
  • Suggests next steps: Provides actionable commands based on your project state
    • +
+ +

💡 Tip: Use --help or -h for standard help, or --help-advanced (alias: -ha) to see all options including advanced configuration.

+ +

Example output (Interactive mode - better results):

+ +
✅ Analyzed 47 Python files
+✅ Extracted 23 features
+✅ Generated 112 user stories
+⏱️  Completed in 8.2 seconds
+
+ +

Example output (CLI-only mode - may show 0 features for simple cases):

+ +
✅ Analyzed 3 Python files
+✅ Extracted 0 features  # ⚠️ AST-based analysis may miss features in simple code
+✅ Generated 0 user stories
+⏱️  Completed in 2.1 seconds
+
+ +

Note: CLI-only mode uses AST-based analysis which may show 0 features for simple test cases. Interactive AI Assistant mode provides better semantic understanding and feature detection.

+ +

Step 2: Review Extracted Specs

+ +
# Review the extracted bundle using CLI commands
+specfact plan review my-project
+
+# Or get structured findings for analysis
+specfact plan review my-project --list-findings --findings-format json
+
+ +

Review the auto-generated plan to understand what SpecFact discovered about your codebase.

+ +

Note: Use CLI commands to interact with bundles. The bundle structure is managed by SpecFact CLI - use commands like plan review, plan add-feature, plan update-feature to work with bundles, not direct file editing.

+ +

💡 Tip: If you plan to sync with Spec-Kit later, the import command will suggest generating a bootstrap constitution. You can also run it manually:

+ +
specfact sdd constitution bootstrap --repo .
+
+ +

Step 3: Find and Fix Gaps

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Analyze and validate your codebase
+specfact repro --verbose
+
+ +

What happens:

+ +
    +
  • repro setup configures CrossHair for contract exploration (one-time setup)
    • +
  • repro runs the full validation suite (linting, type checking, contracts, tests)
    • +
  • Identifies gaps and issues in your codebase
    • +
  • Generates enforcement reports that downstream tools (like generate fix-prompt) can use
    • +
+ +

Step 4: Use AI to Fix Gaps (New in 0.17+)

+ +
# Generate AI-ready prompt to fix a specific gap
+specfact generate fix-prompt GAP-001 --bundle my-project
+
+# Generate AI-ready prompt to add tests
+specfact generate test-prompt src/auth/login.py
+
+ +

What happens:

+ +
    +
  • Creates structured prompt file in .specfact/prompts/
    • +
  • Copy prompt to your AI IDE (Cursor, Copilot, Claude)
    • +
  • AI generates the fix
    • +
  • Validate with SpecFact enforcement
    • +
+ +

Step 5: Enforce Contracts

+ +
# Start in shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# Validate the codebase
+specfact enforce sdd --bundle my-project
+
+ +

See Brownfield Engineer Guide for complete workflow.

+ +
+ +

Scenario 2: Starting a New Project (Alternative)

+ +

Goal: Create a plan before writing code

+ +

Time: 5-10 minutes

+ +

Step 1: Initialize a Plan

+ +
specfact plan init my-project --interactive
+
+ +

What happens:

+ +
    +
  • Creates .specfact/ directory structure
    • +
  • Prompts you for project title and description
    • +
  • Creates modular project bundle at .specfact/projects/my-project/
    • +
+ +

Example output:

+ +
📋 Initializing new development plan...
+
+Enter project title: My Awesome Project
+Enter project description: A project to demonstrate SpecFact CLI
+
+✅ Plan initialized successfully!
+📁 Project bundle: .specfact/projects/my-project/
+
+ +

Step 2: Add Your First Feature

+ +
specfact plan add-feature \
+  --bundle my-project \
+  --key FEATURE-001 \
+  --title "User Authentication" \
+  --outcomes "Users can login securely"
+
+ +

What happens:

+ +
    +
  • Adds a new feature to your project bundle
    • +
  • Creates a feature with key FEATURE-001
    • +
  • Sets the title and outcomes
    • +
+ +

Step 3: Add Stories to the Feature

+ +
specfact plan add-story \
+  --bundle my-project \
+  --feature FEATURE-001 \
+  --title "As a user, I can login with email and password" \
+  --acceptance "Login form validates input" \
+  --acceptance "User is redirected after successful login"
+
+ +

What happens:

+ +
    +
  • Adds a user story to the feature
    • +
  • Defines acceptance criteria
    • +
  • Links the story to the feature
    • +
+ +

Step 4: Validate the Plan

+ +
specfact repro
+
+ +

What happens:

+ +
    +
  • Validates the plan bundle structure
    • +
  • Checks for required fields
    • +
  • Reports any issues
    • +
+ +

Expected output:

+ +
✅ Plan validation passed
+📊 Features: 1
+📊 Stories: 1
+
+ +

Next Steps

+ + + +
+ +

Scenario 3: Migrating from Spec-Kit (Secondary)

+ +

Goal: Add automated enforcement to Spec-Kit project

+ +

Time: 15-30 minutes

+ +

Step 1: Preview Migration

+ +
specfact import from-bridge \
+  --repo ./my-speckit-project \
+  --adapter speckit \
+  --dry-run
+
+ +

What happens:

+ +
    +
  • Analyzes your Spec-Kit project structure
    • +
  • Detects Spec-Kit artifacts (specs, plans, tasks, constitution)
    • +
  • Shows what will be imported
    • +
  • Does not modify anything (dry-run mode)
    • +
+ +

Example output:

+ +
🔍 Analyzing Spec-Kit project...
+✅ Found .specify/ directory (modern format)
+✅ Found specs/001-user-authentication/spec.md
+✅ Found specs/001-user-authentication/plan.md
+✅ Found specs/001-user-authentication/tasks.md
+✅ Found .specify/memory/constitution.md
+
+📊 Migration Preview:
+  - Will create: .specfact/projects/<bundle-name>/ (modular project bundle)
+  - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected)
+  - Will convert: Spec-Kit features → SpecFact Feature models
+  - Will convert: Spec-Kit user stories → SpecFact Story models
+  
+🚀 Ready to migrate (use --write to execute)
+
+ +

Step 2: Execute Migration

+ +
specfact import from-bridge \
+  --repo ./my-speckit-project \
+  --adapter speckit \
+  --write
+
+ +

What happens:

+ +
    +
  • Imports Spec-Kit artifacts into SpecFact format using bridge architecture
    • +
  • Creates .specfact/ directory structure
    • +
  • Converts Spec-Kit features and stories to SpecFact models
    • +
  • Creates modular project bundle at .specfact/projects/<bundle-name>/
    • +
  • Preserves all information
    • +
+ +

Step 3: Review Generated Bundle

+ +
# Review the imported bundle
+specfact plan review <bundle-name>
+
+# Check bundle status
+specfact plan select
+
+ +

What was created:

+ +
    +
  • Modular project bundle at .specfact/projects/<bundle-name>/ with multiple aspect files
    • +
  • .specfact/protocols/workflow.protocol.yaml - FSM definition (if protocol detected)
    • +
  • .specfact/gates/config.yaml - Quality gates configuration
    • +
+ +

Note: Use CLI commands (plan review, plan add-feature, etc.) to interact with bundles. Do not edit .specfact files directly.

+ +

Step 4: Set Up Bidirectional Sync (Optional)

+ +

Keep Spec-Kit and SpecFact synchronized:

+ +
# Generate constitution if missing (auto-suggested during sync)
+specfact sdd constitution bootstrap --repo .
+
+# One-time bidirectional sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Continuous watch mode
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+ +

What happens:

+ +
    +
  • Constitution bootstrap: Auto-generates constitution from repository analysis (if missing or minimal)
    • +
  • Syncs changes between Spec-Kit and SpecFact
    • +
  • Bidirectional: changes in either direction are synced
    • +
  • Watch mode: continuously monitors for changes
    • +
  • Auto-generates all Spec-Kit fields: When syncing from SpecFact to Spec-Kit, all required fields (frontmatter, INVSEST, Constitution Check, Phases, Technology Stack, Story mappings) are automatically generated - ready for /speckit.analyze without manual editing
    • +
+ +

Step 5: Enable Enforcement

+ +
# Start in shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# After stabilization, enable warnings
+specfact enforce stage --preset balanced
+
+# For production, enable strict mode
+specfact enforce stage --preset strict
+
+ +

What happens:

+ +
    +
  • Configures enforcement rules
    • +
  • Sets severity levels (HIGH, MEDIUM, LOW)
    • +
  • Defines actions (BLOCK, WARN, LOG)
    • +
+ +

Next Steps for Scenario 3 (Secondary)

+ + + +
+ +

Common Questions

+ +

What if I make a mistake?

+ +

All commands support --dry-run or --shadow-only flags to preview changes without modifying files.

+ +

Can I undo changes?

+ +

Yes! SpecFact CLI creates backups and you can use Git to revert changes:

+ +
git status
+git diff
+git restore .specfact/
+
+ +

How do I learn more?

+ + + +
+ +

Happy building! 🚀

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/getting-started/installation/index.html b/_site_local/getting-started/installation/index.html new file mode 100644 index 0000000..90d829b --- /dev/null +++ b/_site_local/getting-started/installation/index.html @@ -0,0 +1,710 @@ + + + + + + + +Getting Started with SpecFact CLI | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Getting Started with SpecFact CLI

+ +

This guide will help you get started with SpecFact CLI in under 60 seconds.

+ +
+

Primary Use Case: SpecFact CLI is designed for brownfield code modernization - reverse-engineering existing codebases into documented specs with runtime contract enforcement. See First Steps for brownfield workflows.

+
+ +

Installation

+ +

Option 1: uvx (CLI-only Mode)

+ +

No installation required - run directly:

+ +
uvx specfact-cli@latest --help
+
+ +

Best for: Quick testing, CI/CD, one-off commands

+ +

Limitations: CLI-only mode uses AST-based analysis which may show 0 features for simple test cases. For better results, use interactive AI Assistant mode (Option 2).

+ +

Option 2: pip (Interactive AI Assistant Mode)

+ +

Required for: IDE integration, slash commands, enhanced feature detection

+ +
# System-wide
+pip install specfact-cli
+
+# User install
+pip install --user specfact-cli
+
+# Virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
+pip install specfact-cli
+
+ +

Optional: For enhanced graph-based dependency analysis, see Enhanced Analysis Dependencies.

+ +

After installation: Set up IDE integration for interactive mode:

+ +
# Navigate to your project
+cd /path/to/your/project
+
+# Initialize IDE integration (one-time per project)
+specfact init
+
+# Or specify IDE explicitly
+specfact init --ide cursor
+specfact init --ide vscode
+
+# Install required packages for contract enhancement
+specfact init --install-deps
+
+# Initialize for specific IDE and install dependencies
+specfact init --ide cursor --install-deps
+
+ +

Note: Interactive mode requires Python 3.11+ and automatically uses your IDE workspace (no --repo . needed in slash commands).

+ +

Option 3: Container

+ +
# Docker
+docker run --rm -v $(pwd):/workspace ghcr.io/nold-ai/specfact-cli:latest --help
+
+# Podman
+podman run --rm -v $(pwd):/workspace ghcr.io/nold-ai/specfact-cli:latest --help
+
+ +

Option 4: GitHub Action

+ +

Create .github/workflows/specfact.yml:

+ +
name: SpecFact CLI Validation
+
+on:
+  pull_request:
+    branches: [main, dev]
+  push:
+    branches: [main, dev]
+  workflow_dispatch:
+    inputs:
+      budget:
+        description: "Time budget in seconds"
+        required: false
+        default: "90"
+        type: string
+      mode:
+        description: "Enforcement mode (block, warn, log)"
+        required: false
+        default: "block"
+        type: choice
+        options:
+          - block
+          - warn
+          - log
+
+jobs:
+  specfact-validation:
+    name: Contract Validation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      checks: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install SpecFact CLI
+        run: pip install specfact-cli
+
+      - name: Set up CrossHair Configuration
+        run: specfact repro setup
+
+      - name: Run Contract Validation
+        run: specfact repro --verbose --budget 90
+
+      - name: Generate PR Comment
+        if: github.event_name == 'pull_request'
+        run: python -m specfact_cli.utils.github_annotations
+        env:
+          SPECFACT_REPORT_PATH: .specfact/projects/<bundle-name>/reports/enforcement/report-*.yaml
+
+ +

First Steps

+ +

Operational Modes

+ +

SpecFact CLI supports two operational modes:

+ +
    +
  • CLI-only Mode (uvx): Fast, AST-based analysis for automation +
      +
    • Works immediately with uvx specfact-cli@latest
      • +
    • No installation required
      • +
    • May show 0 features for simple test cases (AST limitations)
      • +
    • Best for: CI/CD, quick testing, one-off commands
      • +
    +
    • +
  • Interactive AI Assistant Mode (pip + specfact init): Enhanced semantic understanding +
      +
    • Requires pip install specfact-cli and specfact init
      • +
    • Better feature detection and semantic understanding
      • +
    • IDE integration with slash commands
      • +
    • Automatically uses IDE workspace (no --repo . needed)
      • +
    • Best for: Development, legacy code analysis, complex projects
      • +
    +
    • +
+ +

Mode Selection:

+ +
# CLI-only mode (uvx - no installation)
+uvx specfact-cli@latest import from-code my-project --repo .
+
+# Interactive mode (pip + specfact init - recommended)
+# After: pip install specfact-cli && specfact init
+# Then use slash commands in IDE: /specfact.01-import legacy-api --repo .
+
+ +

Note: Mode is auto-detected based on whether specfact command is available and IDE integration is set up.

+ +

For Greenfield Projects

+ +

Start a new contract-driven project:

+ +
specfact plan init --interactive
+
+ +

This will guide you through creating:

+ +
    +
  • Initial project idea and narrative
    • +
  • Product themes and releases
    • +
  • First features and stories
    • +
  • Protocol state machine
    • +
+ +

With IDE Integration (Interactive AI Assistant Mode):

+ +
# Step 1: Install SpecFact CLI
+pip install specfact-cli
+
+# Step 2: Navigate to your project
+cd /path/to/your/project
+
+# Step 3: Initialize IDE integration (one-time per project)
+specfact init
+# Or specify IDE: specfact init --ide cursor
+
+# Step 4: Use slash command in IDE chat
+/specfact.02-plan init legacy-api
+# Or use other plan operations: /specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth"
+
+ +

Important:

+ +
    +
  • Interactive mode automatically uses your IDE workspace
    • +
  • Slash commands use numbered format: /specfact.01-import, /specfact.02-plan, etc.
    • +
  • Commands are numbered for natural workflow progression (01-import → 02-plan → 03-review → 04-sdd → 05-enforce → 06-sync)
    • +
  • No --repo . parameter needed in interactive mode (uses workspace automatically)
    • +
  • The AI assistant will prompt you for bundle names and other inputs if not provided
    • +
+ +

See IDE Integration Guide for detailed setup instructions.

+ +

For Spec-Kit Migration

+ +

Convert an existing GitHub Spec-Kit project:

+ +
# Preview what will be migrated
+specfact import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run
+
+# Execute migration (one-time import)
+specfact import from-bridge \
+  --adapter speckit \
+  --repo ./my-speckit-project \
+  --write
+
+# Ongoing bidirectional sync (after migration)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Bidirectional Sync:

+ +

Keep Spec-Kit and SpecFact artifacts synchronized:

+ +
# One-time sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Continuous watch mode
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Note: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in AdapterRegistry and accessed via specfact sync bridge --adapter <adapter-name>, making the architecture extensible for future tool integrations.

+ +

For Brownfield Projects

+ +

Analyze existing code to generate specifications.

+ +

With IDE Integration (Interactive AI Assistant Mode - Recommended):

+ +
# Step 1: Install SpecFact CLI
+pip install specfact-cli
+
+# Step 2: Navigate to your project
+cd /path/to/your/project
+
+# Step 3: Initialize IDE integration (one-time per project)
+specfact init
+# Or specify IDE: specfact init --ide cursor
+
+# Step 4: Use slash command in IDE chat
+/specfact.01-import legacy-api
+# Or let the AI assistant prompt you for bundle name and other options
+
+ +

Important for IDE Integration:

+ +
    +
  • Interactive mode automatically uses your IDE workspace (no --repo . needed in interactive mode)
    • +
  • Slash commands use numbered format: /specfact.01-import, /specfact.02-plan, etc. (numbered for workflow ordering)
    • +
  • Commands follow natural progression: 01-import → 02-plan → 03-review → 04-sdd → 05-enforce → 06-sync
    • +
  • The AI assistant will prompt you for bundle names and confidence thresholds if not provided
    • +
  • Better feature detection than CLI-only mode (semantic understanding vs AST-only)
    • +
  • Do NOT use --mode copilot with IDE slash commands - IDE integration automatically provides enhanced prompts
    • +
+ +

CLI-Only Mode (Alternative - for CI/CD or when IDE integration is not available):

+ +
# Analyze repository (CI/CD mode - fast)
+specfact import from-code my-project \
+  --repo ./my-project \
+  --shadow-only \
+  --report analysis.md
+
+# Analyze with CoPilot mode (enhanced prompts - CLI only, not for IDE)
+specfact --mode copilot import from-code my-project \
+  --repo ./my-project \
+  --confidence 0.7 \
+  --report analysis.md
+
+# Review generated plan
+cat analysis.md
+
+ +

Note: --mode copilot is for CLI usage only. When using IDE integration, use slash commands (e.g., /specfact.01-import) instead - IDE integration automatically provides enhanced prompts without needing the --mode copilot flag.

+ +

See IDE Integration Guide for detailed setup instructions.

+ +

Sync Changes:

+ +

Keep plan artifacts updated as code changes:

+ +
# One-time sync
+specfact sync repository --repo . --target .specfact
+
+# Continuous watch mode
+specfact sync repository --repo . --watch
+
+ +

Next Steps

+ +
    +
  1. Explore Commands: See Command Reference
    2. +
  2. Learn Use Cases: Read Use Cases
    3. +
  3. Understand Architecture: Check Architecture
    4. +
  4. Set Up IDE Integration: See IDE Integration Guide
    5. +
+ +

Quick Tips

+ +
    +
  • Python 3.11+ required: SpecFact CLI requires Python 3.11 or higher
    • +
  • Start in shadow mode: Use --shadow-only to observe without blocking
    • +
  • Use dry-run: Always preview with --dry-run before writing changes
    • +
  • Check reports: Generate reports with --report <filename> for review
    • +
  • Progressive enforcement: Start with minimal, move to balanced, then strict
    • +
  • CLI-only vs Interactive: Use uvx for quick testing, pip install + specfact init for better results
    • +
  • IDE integration: Use specfact init to set up slash commands in IDE (requires pip install)
    • +
  • Slash commands: Use numbered format /specfact.01-import, /specfact.02-plan, etc. (numbered for workflow ordering)
    • +
  • Global flags: Place --no-banner before the command: specfact --no-banner <command>
    • +
  • Bridge adapter sync: Use sync bridge --adapter <adapter-name> for external tool integration (Spec-Kit, OpenSpec, GitHub, etc.)
    • +
  • Repository sync: Use sync repository for code change tracking
    • +
  • Semgrep (optional): Install pip install semgrep for async pattern detection in specfact repro
    • +
+ +
+ +

Supported Project Management Tools

+ +

SpecFact CLI automatically detects and works with the following Python project management tools. No configuration needed - it detects your project’s environment manager automatically!

+ +

Automatic Detection

+ +

When you run SpecFact CLI commands on a repository, it automatically:

+ +
    +
  1. Detects the environment manager by checking for configuration files
    2. +
  2. Detects source directories (src/, lib/, or package name from pyproject.toml)
    3. +
  3. Builds appropriate commands using the detected environment manager
    4. +
  4. Checks tool availability and skips with clear messages if tools are missing
    5. +
+ +

Supported Tools

+ +

1. hatch - Modern Python project manager

+ +
    +
  • Detection: [tool.hatch] section in pyproject.toml
    • +
  • Command prefix: hatch run
    • +
  • Example: hatch run pytest tests/
    • +
  • Use case: Modern Python projects using hatch for build and dependency management
    • +
+ +

2. poetry - Dependency management and packaging

+ +
    +
  • Detection: [tool.poetry] section in pyproject.toml or poetry.lock file
    • +
  • Command prefix: poetry run
    • +
  • Example: poetry run pytest tests/
    • +
  • Use case: Projects using Poetry for dependency management
    • +
+ +

3. uv - Fast Python package installer and resolver

+ +
    +
  • Detection: [tool.uv] section in pyproject.toml, uv.lock, or uv.toml file
    • +
  • Command prefix: uv run
    • +
  • Example: uv run pytest tests/
    • +
  • Use case: Projects using uv for fast package management
    • +
+ +

4. pip - Standard Python package installer

+ +
    +
  • Detection: requirements.txt or setup.py file
    • +
  • Command prefix: Direct tool invocation (no prefix)
    • +
  • Example: pytest tests/
    • +
  • Use case: Traditional Python projects using pip and virtual environments
    • +
+ +

Detection Priority

+ +

SpecFact CLI checks in this order:

+ +
    +
  1. pyproject.toml for tool sections ([tool.hatch], [tool.poetry], [tool.uv])
    2. +
  2. Lock files (poetry.lock, uv.lock, uv.toml)
    3. +
  3. Fallback to requirements.txt or setup.py for pip-based projects
    4. +
+ +

Source Directory Detection

+ +

SpecFact CLI automatically detects source directories:

+ +
    +
  • Standard layouts: src/, lib/
    • +
  • Package name: Extracted from pyproject.toml (e.g., my-package → my_package/)
    • +
  • Root-level: Falls back to root directory if no standard layout found
    • +
+ +

Example: Working with Different Projects

+ +
# Hatch project
+cd /path/to/hatch-project
+specfact repro --repo .  # Automatically uses "hatch run" for tools
+
+# Poetry project
+cd /path/to/poetry-project
+specfact repro --repo .  # Automatically uses "poetry run" for tools
+
+# UV project
+cd /path/to/uv-project
+specfact repro --repo .  # Automatically uses "uv run" for tools
+
+# Pip project
+cd /path/to/pip-project
+specfact repro --repo .  # Uses direct tool invocation
+
+ +

External Repository Support

+ +

SpecFact CLI works seamlessly on external repositories without requiring:

+ +
    +
  • ❌ SpecFact CLI adoption
    • +
  • ❌ Specific project structures
    • +
  • ❌ Manual configuration
    • +
  • ❌ Tool installation in global environment
    • +
+ +

All commands automatically adapt to the target repository’s environment and structure.

+ +

This makes SpecFact CLI ideal for:

+ +
    +
  • OSS validation workflows - Validate external open-source projects
    • +
  • Multi-project environments - Work with different project structures
    • +
  • CI/CD pipelines - Validate any Python project without setup
    • +
+ +

Common Commands

+ +
# Check version
+specfact --version
+
+# Get help
+specfact --help
+specfact <command> --help
+
+# Initialize plan (bundle name as positional argument)
+specfact plan init my-project --interactive
+
+# Add feature
+specfact plan add-feature --key FEATURE-001 --title "My Feature"
+
+# Validate everything
+specfact repro
+
+# Set enforcement level
+specfact enforce stage --preset balanced
+
+ +

Getting Help

+ + + +

Development Setup

+ +

For contributors:

+ +
# Clone repository
+git clone https://github.com/nold-ai/specfact-cli.git
+cd specfact-cli
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+hatch run contract-test-full
+
+# Format code
+hatch run format
+
+# Run linters
+hatch run lint
+
+ +

See CONTRIBUTING.md for detailed contribution guidelines.

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/getting-started/tutorial-openspec-speckit.md b/_site_local/getting-started/tutorial-openspec-speckit.md new file mode 100644 index 0000000..65c1dc9 --- /dev/null +++ b/_site_local/getting-started/tutorial-openspec-speckit.md @@ -0,0 +1,686 @@ +# Tutorial: Using SpecFact with OpenSpec or Spec-Kit + +> **Complete step-by-step guide for new users** +> Learn how to use SpecFact CLI with OpenSpec or Spec-Kit for brownfield code modernization + +**Time**: 15-30 minutes | **Prerequisites**: Python 3.11+, basic command-line knowledge + +**Note**: This tutorial assumes you're using `specfact` command directly. + +--- + +## 🎯 What You'll Learn + +By the end of this tutorial, you'll know how to: + +- ✅ Install and set up SpecFact CLI +- ✅ Use SpecFact with OpenSpec for change tracking and DevOps integration +- ✅ Use SpecFact with Spec-Kit for greenfield + brownfield workflows +- ✅ Sync between tools using bridge adapters +- ✅ Export change proposals to GitHub Issues +- ✅ Track implementation progress automatically + +--- + +## 📋 Prerequisites + +Before starting, ensure you have: + +- **Python 3.11+** installed (`python3 --version`) +- **Git** installed (`git --version`) +- **Command-line access** (Terminal, PowerShell, or WSL) +- **A GitHub account** (for DevOps integration examples) + +**Optional but recommended:** + +- **OpenSpec CLI** installed (`npm install -g @fission-ai/openspec@latest`) - for OpenSpec workflows +- **VS Code or Cursor** - for IDE integration + +--- + +## 🚀 Quick Start: Choose Your Path + +### Path A: Using SpecFact with OpenSpec + +**Best for**: Teams using OpenSpec for specification management and change tracking + +**Use case**: You have OpenSpec change proposals and want to: + +- Export them to GitHub Issues +- Track implementation progress +- Sync OpenSpec specs with code analysis + +👉 **[Jump to OpenSpec Tutorial](#path-a-using-specfact-with-openspec)** + +### Path B: Using SpecFact with Spec-Kit + +**Best for**: Teams using GitHub Spec-Kit for interactive specification authoring + +**Use case**: You have Spec-Kit specs and want to: + +- Add runtime contract enforcement +- Enable team collaboration with shared plans +- Sync Spec-Kit artifacts with SpecFact bundles + +👉 **[Jump to Spec-Kit Tutorial](#path-b-using-specfact-with-spec-kit)** + +--- + +## Path A: Using SpecFact with OpenSpec + +### Step 1: Install SpecFact CLI + +**Option 1: Quick Start (CLI-only)** + +```bash +# No installation needed - works immediately +uvx specfact-cli@latest --help +``` + +**Option 2: Full Installation (Recommended)** + +```bash +# Install SpecFact CLI +pip install specfact-cli + +# Verify installation +specfact --version +``` + +**Expected output**: `specfact-cli, version 0.22.0` + +### Step 2: Set Up Your Project + +**If you already have an OpenSpec project:** + +```bash +# Navigate to your OpenSpec project +cd /path/to/your-openspec-project + +# Verify OpenSpec structure exists +ls openspec/ +# Should show: specs/, changes/, project.md, AGENTS.md +``` + +**If you don't have OpenSpec yet:** + +```bash +# Install OpenSpec CLI +npm install -g @fission-ai/openspec@latest + +# Initialize OpenSpec in your project +cd /path/to/your-project +openspec init + +# This creates openspec/ directory structure +``` + +### Step 3: Analyze Your Legacy Code with SpecFact + +**First, extract specs from your existing code:** + +```bash +# Analyze legacy codebase +cd /path/to/your-openspec-project +specfact import from-code legacy-api --repo . + +# Expected output: +# 🔍 Analyzing codebase... +# ✅ Analyzed X Python files +# ✅ Extracted Y features +# ✅ Generated Z user stories +# ⏱️ Completed in X seconds +# 📁 Project bundle: .specfact/projects/legacy-api/ +# ✅ Import complete! +``` + +**What this does:** + +- Analyzes your Python codebase +- Extracts features and user stories automatically +- Creates a SpecFact project bundle (`.specfact/projects/legacy-api/`) + +**Note**: If using `hatch run specfact`, run from the specfact-cli directory: +```bash +cd /path/to/specfact-cli +hatch run specfact import from-code legacy-api --repo /path/to/your-openspec-project +``` + +### Step 4: Create an OpenSpec Change Proposal + +**Create a change proposal in OpenSpec:** + +```bash +# Create change proposal directory +mkdir -p openspec/changes/modernize-api + +# Create proposal.md +cat > openspec/changes/modernize-api/proposal.md << 'EOF' +# Change: Modernize Legacy API + +## Why +Legacy API needs modernization for better performance and maintainability. + +## What Changes +- Refactor API endpoints +- Add contract validation +- Update database schema + +## Impact +- Affected specs: api, database +- Affected code: src/api/, src/db/ +EOF + +# Create tasks.md +cat > openspec/changes/modernize-api/tasks.md << 'EOF' +## Implementation Tasks + +- [ ] Refactor API endpoints +- [ ] Add contract validation +- [ ] Update database schema +- [ ] Add tests +EOF +``` + +### Step 5: Export OpenSpec Proposal to GitHub Issues + +**Export your change proposal to GitHub Issues:** + +```bash +# Export OpenSpec change proposal to GitHub Issues +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo + +# Expected output: +# ✅ Found change proposal: modernize-api +# ✅ Created GitHub Issue #123: Modernize Legacy API +# ✅ Updated proposal.md with issue tracking +``` + +**What this does:** + +- Reads your OpenSpec change proposal +- Creates a GitHub Issue from the proposal +- Updates the proposal with issue tracking information +- Enables progress tracking + +### Step 6: Track Implementation Progress + +**As you implement changes, track progress automatically:** + +```bash +# Make commits with change ID in commit message +cd /path/to/source-code-repo +git commit -m "feat: modernize-api - refactor endpoints [change:modernize-api]" + +# Track progress (detects commits and adds comments to GitHub Issue) +cd /path/to/openspec-repo +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --track-code-changes \ + --repo . \ + --code-repo /path/to/source-code-repo + +# Expected output: +# ✅ Detected commit: feat: modernize-api - refactor endpoints +# ✅ Added progress comment to Issue #123 +``` + +**Note**: Use `--track-code-changes` flag to enable automatic code change detection. The `--code-repo` option specifies where the source code repository is located (if different from the OpenSpec repo). + +### Step 7: Sync OpenSpec Change Proposals to SpecFact + +**Import OpenSpec change proposals into SpecFact:** + +```bash +# Sync OpenSpec change proposals to SpecFact (read-only) +cd /path/to/openspec-repo +specfact sync bridge --adapter openspec --mode read-only \ + --bundle legacy-api \ + --repo . + +# Expected output: +# ✅ Syncing OpenSpec artifacts (read-only) +# ✅ Found 1 change proposal: modernize-api +# ✅ Synced to SpecFact bundle: legacy-api +# ✅ Change tracking updated +``` + +**What this does:** + +- Reads OpenSpec change proposals from `openspec/changes/` +- Syncs them to SpecFact change tracking +- Enables alignment reports (planned feature) + +**Note**: Currently, OpenSpec adapter sync may show an error about `discover_features` method. This is a known limitation in v0.22.0. The adapter successfully loads change proposals, but alignment report generation may fail. This will be fixed in a future release. + +### Step 8: Add Runtime Contract Enforcement + +**Add contracts to prevent regressions:** + +```bash +# Configure enforcement (global setting, no --bundle or --repo needed) +cd /path/to/your-project +specfact enforce stage --preset balanced + +# Expected output: +# Setting enforcement mode: balanced +# Enforcement Mode: BALANCED +# ┏━━━━━━━━━━┳━━━━━━━━┓ +# ┃ Severity ┃ Action ┃ +# ┡━━━━━━━━╇━━━━━━━━┩ +# │ HIGH │ BLOCK │ +# │ MEDIUM │ WARN │ +# │ LOW │ LOG │ +# ✅ Quality gates configured +``` + +**What this does:** + +- Configures quality gates (global setting for the repository) +- Enables contract enforcement +- Prepares CI/CD integration + +**Note**: `enforce stage` is a global setting and doesn't take `--bundle` or `--repo` options. It configures enforcement for the current repository. + +### Step 9: Archive Completed Change + +**When implementation is complete, archive the change:** + +```bash +# Archive completed change in OpenSpec +openspec archive modernize-api --yes + +# Expected output: +# ✅ Change archived successfully +# ✅ Specs updated in openspec/specs/ +``` + +--- + +## Path B: Using SpecFact with Spec-Kit + +### Step 1: Install SpecFact CLI + +**Option 1: Quick Start (CLI-only)** + +```bash +# No installation needed +uvx specfact-cli@latest --help +``` + +**Option 2: Full Installation (Recommended)** + +```bash +# Install SpecFact CLI +pip install specfact-cli + +# Verify installation +specfact --version +``` + +### Step 2: Set Up Your Spec-Kit Project + +**If you already have a Spec-Kit project:** + +```bash +# Navigate to your Spec-Kit project +cd /path/to/your-speckit-project + +# Verify Spec-Kit structure exists +ls specs/ +# Should show: [###-feature-name]/ directories with spec.md, plan.md, tasks.md +``` + +**If you don't have Spec-Kit yet:** + +```bash +# Spec-Kit is integrated into GitHub Copilot +# Use slash commands in Copilot chat: +# /speckit.specify --feature "User Authentication" +# /speckit.plan --feature "User Authentication" +# /speckit.tasks --feature "User Authentication" +``` + +### Step 3: Preview Spec-Kit Import + +**See what will be imported (safe - no changes):** + +```bash +# Preview import +specfact import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run + +# Expected output: +# 🔍 Analyzing Spec-Kit project via bridge adapter... +# ✅ Found .specify/ directory (modern format) +# ✅ Found specs/001-user-authentication/spec.md +# ✅ Found specs/001-user-authentication/plan.md +# ✅ Found specs/001-user-authentication/tasks.md +# ✅ Found .specify/memory/constitution.md +# +# 📊 Migration Preview: +# - Will create: .specfact/projects// (modular project bundle) +# - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected) +# - Will create: .specfact/gates/config.yaml +# - Will convert: Spec-Kit features → SpecFact Feature models +# - Will convert: Spec-Kit user stories → SpecFact Story models +# +# 🚀 Ready to migrate (use --write to execute) +``` + +### Step 4: Import Spec-Kit Project + +**Import your Spec-Kit project to SpecFact:** + +```bash +# Execute import +specfact import from-bridge \ + --adapter speckit \ + --repo ./my-speckit-project \ + --write + +# Expected output: +# ✅ Parsed Spec-Kit artifacts +# ✅ Generated SpecFact bundle: .specfact/projects// +# ✅ Created quality gates config +# ✅ Preserved Spec-Kit artifacts (original files untouched) +``` + +**What this does:** + +- Parses Spec-Kit artifacts (spec.md, plan.md, tasks.md, constitution.md) +- Generates SpecFact project bundle +- Creates quality gates configuration +- Preserves your original Spec-Kit files + +### Step 5: Review Generated Bundle + +**Review what was created:** + +```bash +# Review plan bundle (bundle name is positional argument, not --bundle) +# IMPORTANT: Must be in the project directory where .specfact/ exists +cd /path/to/your-speckit-project +specfact plan review + +# Note: Bundle name is typically "main" for Spec-Kit imports +# Check actual bundle name: ls .specfact/projects/ + +# Expected output: +# ✅ Features: 5 +# ✅ Stories: 23 +# ✅ Plan bundle reviewed successfully +``` + +**Note**: +- `plan review` takes the bundle name as a positional argument (not `--bundle`) +- It uses the current directory to find `.specfact/projects/` (no `--repo` option) +- You must be in the project directory where the bundle was created + +### Step 6: Enable Bidirectional Sync + +**Keep Spec-Kit and SpecFact in sync:** + +```bash +# One-time sync (bundle name is typically "main" for Spec-Kit imports) +cd /path/to/my-speckit-project +specfact sync bridge --adapter speckit --bundle main --repo . --bidirectional + +# Continuous watch mode (recommended for team collaboration) +specfact sync bridge --adapter speckit --bundle main --repo . --bidirectional --watch --interval 5 + +# Expected output: +# ✅ Detected speckit repository +# ✅ Constitution found and validated +# ✅ Detected SpecFact structure +# ✅ No conflicts detected +# Sync Summary (Bidirectional): +# - speckit → SpecFact: Updated 0, Added 0 features +# - SpecFact → speckit: No features to convert +``` + +**What this does:** + +- **Spec-Kit → SpecFact**: New specs automatically imported +- **SpecFact → Spec-Kit**: Changes synced back to Spec-Kit format +- **Team collaboration**: Multiple developers can work together + +**Note**: Replace `main` with your actual bundle name if different. Check with `ls .specfact/projects/` after import. + +### Step 7: Continue Using Spec-Kit Interactively + +**Keep using Spec-Kit slash commands - sync happens automatically:** + +```bash +# In GitHub Copilot chat: +/speckit.specify --feature "Payment Processing" +/speckit.plan --feature "Payment Processing" +/speckit.tasks --feature "Payment Processing" + +# SpecFact automatically syncs (if watch mode enabled) +# → Detects changes in specs/[###-feature-name]/ +# → Imports new spec.md, plan.md, tasks.md +# → Updates .specfact/projects// aspect files +``` + +### Step 8: Add Runtime Contract Enforcement + +**Add contracts to prevent regressions:** + +```bash +# Configure enforcement (global setting, no --bundle or --repo needed) +cd /path/to/my-speckit-project +specfact enforce stage --preset balanced + +# Expected output: +# Setting enforcement mode: balanced +# Enforcement Mode: BALANCED +# ┏━━━━━━━━━━┳━━━━━━━━┓ +# ┃ Severity ┃ Action ┃ +# ┡━━━━━━━━━━╇━━━━━━━━┩ +# │ HIGH │ BLOCK │ +# │ MEDIUM │ WARN │ +# │ LOW │ LOG │ +# ✅ Quality gates configured +``` + +**Note**: `enforce stage` is a global setting and doesn't take `--bundle` or `--repo` options. + +### Step 9: Detect Code vs Plan Drift + +**Compare intended design vs actual implementation:** + +```bash +# Compare code vs plan (use --bundle to specify bundle name) +# IMPORTANT: Must be in the project directory where .specfact/ exists +cd /path/to/my-speckit-project +specfact plan compare --code-vs-plan --bundle + +# Note: Bundle name is typically "main" for Spec-Kit imports +# Check actual bundle name: ls .specfact/projects/ + +# Expected output: +# ✅ Comparing intended design vs actual implementation +# ✅ Found 3 deviations +# ✅ Auto-derived plans from code analysis +``` + +**What this does:** + +- Compares Spec-Kit plans (what you planned) vs code (what's implemented) +- Identifies deviations automatically +- Helps catch drift between design and code + +**Note**: +- `plan compare` takes `--bundle` as an option (not positional) +- It uses the current directory to find bundles (no `--repo` option) +- You must be in the project directory where the bundle was created + +--- + +## 🎓 Key Concepts + +### Bridge Adapters + +**What are bridge adapters?** + +Bridge adapters are plugin-based connectors that sync between SpecFact and external tools (OpenSpec, Spec-Kit, GitHub Issues, etc.). + +**Available adapters:** + +- `openspec` - OpenSpec integration (read-only sync, v0.22.0+) +- `speckit` - Spec-Kit integration (bidirectional sync) +- `github` - GitHub Issues integration (export-only) + +**How to use:** + +```bash +# View available adapters (shown in help text) +specfact sync bridge --help + +# Use an adapter +specfact sync bridge --adapter --mode --bundle --repo . +``` + +**Note**: Adapters are listed in the help text. There's no `--list-adapters` option, but adapters are shown when you use `--help` or when an adapter is not found (error message shows available adapters). + +### Sync Modes + +**Available sync modes:** + +- `read-only` - Import from external tool (no modifications) +- `export-only` - Export to external tool (no imports) +- `bidirectional` - Two-way sync (read and write) +- `unidirectional` - One-way sync (Spec-Kit → SpecFact only) + +**Which mode to use:** + +- **OpenSpec**: Use `read-only` (v0.22.0+) or `export-only` (GitHub Issues) +- **Spec-Kit**: Use `bidirectional` for team collaboration +- **GitHub Issues**: Use `export-only` for DevOps integration + +--- + +## 🐛 Troubleshooting + +### Issue: "Adapter not found" + +**Solution:** + +```bash +# View available adapters in help text +specfact sync bridge --help + +# Or check error message when adapter is not found (shows available adapters) +# Should show: openspec, speckit, github, generic-markdown +``` + +### Issue: "No change proposals found" + +**Solution:** + +```bash +# Verify OpenSpec structure +ls openspec/changes/ +# Should show change proposal directories + +# Check proposal.md exists +cat openspec/changes//proposal.md +``` + +### Issue: "Spec-Kit artifacts not found" + +**Solution:** + +```bash +# Verify Spec-Kit structure +ls specs/ +# Should show: [###-feature-name]/ directories + +# Check spec.md exists +cat specs/001-user-authentication/spec.md +``` + +### Issue: "GitHub Issues export failed" + +**Solution:** + +```bash +# Verify GitHub token +export GITHUB_TOKEN=your-token + +# Or use GitHub CLI +gh auth login + +# Verify repository access +gh repo view your-org/your-repo +``` + +--- + +## 📚 Next Steps + +### For OpenSpec Users + +1. **[OpenSpec Journey Guide](../guides/openspec-journey.md)** - Complete integration guide +2. **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** - GitHub Issues and backlog tracking +3. **[Commands Reference](../reference/commands.md#sync-bridge)** - Complete `sync bridge` documentation + +### For Spec-Kit Users + +1. **[Spec-Kit Journey Guide](../guides/speckit-journey.md)** - Complete integration guide +2. **[Spec-Kit Comparison](../guides/speckit-comparison.md)** - Understand when to use each tool +3. **[Commands Reference](../reference/commands.md#sync-bridge)** - Complete `sync bridge` documentation + +### General Resources + +1. **[Getting Started Guide](README.md)** - Installation and first commands +2. **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** - Complete brownfield modernization workflow +3. **[Use Cases](../guides/use-cases.md)** - Real-world scenarios + +--- + +## 💡 Tips & Best Practices + +### For OpenSpec Integration + +- ✅ **Separate repositories**: Keep OpenSpec specs in a separate repo from code +- ✅ **Change proposals**: Use OpenSpec for structured change proposals +- ✅ **DevOps export**: Export proposals to GitHub Issues for team visibility +- ✅ **Progress tracking**: Use `--track-code-changes` to auto-track implementation + +### For Spec-Kit Integration + +- ✅ **Bidirectional sync**: Use `--bidirectional --watch` for team collaboration +- ✅ **Interactive authoring**: Keep using Spec-Kit slash commands +- ✅ **Contract enforcement**: Add SpecFact contracts to critical paths +- ✅ **Drift detection**: Regularly run `plan compare` to catch deviations + +### General Tips + +- ✅ **Start small**: Begin with one feature or change proposal +- ✅ **Use watch mode**: Enable `--watch` for automatic synchronization +- ✅ **Review before sync**: Use `--dry-run` to preview changes +- ✅ **Version control**: Commit SpecFact bundles to version control + +--- + +## 🆘 Need Help? + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) +- 📖 [Full Documentation](../README.md) + +--- + +**Happy building!** 🚀 + +--- + +Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold) + +**Trademarks**: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](../../TRADEMARKS.md) for more information. diff --git a/_site_local/guides/README.md b/_site_local/guides/README.md new file mode 100644 index 0000000..00aa0ce --- /dev/null +++ b/_site_local/guides/README.md @@ -0,0 +1,65 @@ +# Guides + +Practical guides for using SpecFact CLI effectively. + +## Available Guides + +### Primary Use Case: Brownfield Modernization ⭐ + +- **[Brownfield Engineer Guide](brownfield-engineer.md)** ⭐ **PRIMARY** - Complete guide for modernizing legacy code +- **[The Brownfield Journey](brownfield-journey.md)** ⭐ **PRIMARY** - Step-by-step modernization workflow +- **[Brownfield ROI](brownfield-roi.md)** ⭐ - Calculate time and cost savings +- **[Brownfield FAQ](brownfield-faq.md)** ⭐ - Common questions about brownfield modernization + +### Secondary Use Case: Spec-Kit & OpenSpec Integration + +- **[Spec-Kit Journey](speckit-journey.md)** - Adding enforcement to Spec-Kit projects +- **[Spec-Kit Comparison](speckit-comparison.md)** - Understand when to use each tool +- **[OpenSpec Journey](openspec-journey.md)** 🆕 ⭐ **START HERE** - Complete integration guide with visual workflows: DevOps export (✅), bridge adapter (⏳), brownfield modernization +- **[Use Cases](use-cases.md)** - Real-world scenarios (brownfield primary, Spec-Kit secondary) + +### General Guides + +- **[Workflows](workflows.md)** - Common daily workflows +- **[IDE Integration](ide-integration.md)** - Set up slash commands in your IDE +- **[CoPilot Mode](copilot-mode.md)** - Using `--mode copilot` on CLI commands +- **[DevOps Adapter Integration](devops-adapter-integration.md)** - Integrate with GitHub Issues, Azure DevOps, Linear, Jira for backlog tracking +- **[Specmatic Integration](specmatic-integration.md)** - API contract testing with Specmatic (validate specs, generate tests, mock servers) +- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions +- **[Competitive Analysis](competitive-analysis.md)** - How SpecFact compares to other tools +- **[Operational Modes](../reference/modes.md)** - CI/CD vs CoPilot modes (reference) + +## Quick Start + +### Modernizing Legacy Code? ⭐ PRIMARY + +1. **[Integration Showcases](../examples/integration-showcases/)** ⭐ **START HERE** - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations +2. **[Brownfield Engineer Guide](brownfield-engineer.md)** ⭐ - Complete modernization guide +3. **[The Brownfield Journey](brownfield-journey.md)** ⭐ - Step-by-step workflow +4. **[Use Cases - Brownfield](use-cases.md#use-case-1-brownfield-code-modernization-primary)** ⭐ - Real-world examples + +### For IDE Users + +1. **[IDE Integration](ide-integration.md)** - Set up slash commands in your IDE +2. **[Use Cases](use-cases.md)** - See real-world examples + +### For CLI Users + +1. **[CoPilot Mode](copilot-mode.md)** - Using `--mode copilot` for enhanced prompts +2. **[Operational Modes](../reference/modes.md)** - Understanding CI/CD vs CoPilot modes +3. **[DevOps Adapter Integration](devops-adapter-integration.md)** - GitHub Issues and backlog tracking +4. **[Specmatic Integration](specmatic-integration.md)** - API contract testing workflow + +### For Spec-Kit & OpenSpec Users (Secondary) + +1. **[Tutorial: Using SpecFact with OpenSpec or Spec-Kit](../getting-started/tutorial-openspec-speckit.md)** ⭐ **START HERE** - Complete beginner-friendly step-by-step tutorial +2. **[Spec-Kit Journey](speckit-journey.md)** - Add enforcement to Spec-Kit projects +3. **[OpenSpec Journey](openspec-journey.md)** 🆕 ⭐ - Complete OpenSpec integration guide with DevOps export and visual workflows +4. **[DevOps Adapter Integration](devops-adapter-integration.md)** 🆕 - Export change proposals to GitHub Issues +5. **[Use Cases - Spec-Kit Migration](use-cases.md#use-case-2-github-spec-kit-migration-secondary)** - Step-by-step migration + +## Need Help? + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_local/guides/adapter-development.md b/_site_local/guides/adapter-development.md new file mode 100644 index 0000000..cf9a229 --- /dev/null +++ b/_site_local/guides/adapter-development.md @@ -0,0 +1,562 @@ +# Adapter Development Guide + +This guide explains how to create new bridge adapters for SpecFact CLI using the adapter registry pattern. + +## Overview + +SpecFact CLI uses a plugin-based adapter architecture that allows external tools (GitHub, Spec-Kit, Linear, Jira, etc.) to integrate seamlessly. All adapters implement the `BridgeAdapter` interface and are registered in the `AdapterRegistry` for automatic discovery and usage. + +## Architecture + +### Adapter Registry Pattern + +The adapter registry provides a centralized way to: + +- **Register adapters**: Auto-discover and register adapters at import time +- **Get adapters**: Retrieve adapters by name (e.g., `"speckit"`, `"github"`, `"openspec"`) +- **List adapters**: Enumerate all registered adapters +- **Check registration**: Verify if an adapter is registered + +### BridgeAdapter Interface + +All adapters must implement the `BridgeAdapter` abstract base class, which defines the following methods: + +```python +class BridgeAdapter(ABC): + @abstractmethod + def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool: + """Detect if this adapter applies to the repository.""" + + @abstractmethod + def get_capabilities(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> ToolCapabilities: + """Get tool capabilities for detected repository.""" + + @abstractmethod + def import_artifact(self, artifact_key: str, artifact_path: Path | dict[str, Any], project_bundle: Any, bridge_config: BridgeConfig | None = None) -> None: + """Import artifact from tool format to SpecFact.""" + + @abstractmethod + def export_artifact(self, artifact_key: str, artifact_data: Any, bridge_config: BridgeConfig | None = None) -> Path | dict[str, Any]: + """Export artifact from SpecFact to tool format.""" + + @abstractmethod + def generate_bridge_config(self, repo_path: Path) -> BridgeConfig: + """Generate bridge configuration for this adapter.""" + + @abstractmethod + def load_change_tracking(self, bundle_dir: Path, bridge_config: BridgeConfig | None = None) -> ChangeTracking | None: + """Load change tracking (adapter-specific storage location).""" + + @abstractmethod + def save_change_tracking(self, bundle_dir: Path, change_tracking: ChangeTracking, bridge_config: BridgeConfig | None = None) -> None: + """Save change tracking (adapter-specific storage location).""" + + @abstractmethod + def load_change_proposal(self, change_id: str, bridge_config: BridgeConfig | None = None) -> ChangeProposal | None: + """Load change proposal from adapter-specific location.""" + + @abstractmethod + def save_change_proposal(self, change_proposal: ChangeProposal, bridge_config: BridgeConfig | None = None) -> None: + """Save change proposal to adapter-specific location.""" +``` + +## Step-by-Step Guide + +### Step 1: Create Adapter Module + +Create a new file `src/specfact_cli/adapters/.py`: + +```python +""" + bridge adapter for . + +This adapter implements the BridgeAdapter interface to sync artifacts +with SpecFact plan bundles and protocols. +""" + +from __future__ import annotations + +from pathlib import Path +from typing import Any + +from beartype import beartype +from icontract import ensure, require + +from specfact_cli.adapters.base import BridgeAdapter +from specfact_cli.models.bridge import BridgeConfig +from specfact_cli.models.capabilities import ToolCapabilities +from specfact_cli.models.change import ChangeProposal, ChangeTracking + + +class MyAdapter(BridgeAdapter): + """ + bridge adapter implementing BridgeAdapter interface. + + This adapter provides sync between artifacts + and SpecFact plan bundles/protocols. + """ + + @beartype + @ensure(lambda result: result is None, "Must return None") + def __init__(self) -> None: + """Initialize adapter.""" + pass + + # Implement all abstract methods... +``` + +### Step 2: Implement Required Methods + +#### 2.1 Implement `detect()` + +Detect if the repository uses your tool: + +```python +@beartype +@require(lambda repo_path: repo_path.exists(), "Repository path must exist") +@require(lambda repo_path: repo_path.is_dir(), "Repository path must be a directory") +@ensure(lambda result: isinstance(result, bool), "Must return bool") +def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool: + """ + Detect if this is a repository. + + Args: + repo_path: Path to repository root + bridge_config: Optional bridge configuration (for cross-repo detection) + + Returns: + True if structure detected, False otherwise + """ + # Check for cross-repo support + base_path = repo_path + if bridge_config and bridge_config.external_base_path: + base_path = bridge_config.external_base_path + + # Check for tool-specific structure + # Example: Check for .tool/ directory or tool-specific files + tool_dir = base_path / ".tool" + config_file = base_path / "tool.config" + + return (tool_dir.exists() and tool_dir.is_dir()) or config_file.exists() +``` + +#### 2.2 Implement `get_capabilities()` + +Return tool capabilities: + +```python +@beartype +@require(lambda repo_path: repo_path.exists(), "Repository path must exist") +@require(lambda repo_path: repo_path.is_dir(), "Repository path must be a directory") +@ensure(lambda result: isinstance(result, ToolCapabilities), "Must return ToolCapabilities") +def get_capabilities(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> ToolCapabilities: + """ + Get adapter capabilities. + + Args: + repo_path: Path to repository root + bridge_config: Optional bridge configuration (for cross-repo detection) + + Returns: + ToolCapabilities instance for adapter + """ + from specfact_cli.models.capabilities import ToolCapabilities + + base_path = repo_path + if bridge_config and bridge_config.external_base_path: + base_path = bridge_config.external_base_path + + # Determine tool-specific capabilities + return ToolCapabilities( + tool="", + layout="", + specs_dir="", + supported_sync_modes=["", ""], # e.g., ["bidirectional", "unidirectional"] + has_custom_hooks=False, # Set to True if tool has custom hooks/constitution + ) +``` + +#### 2.3 Implement `generate_bridge_config()` + +Generate bridge configuration: + +```python +@beartype +@require(lambda repo_path: repo_path.exists(), "Repository path must exist") +@require(lambda repo_path: repo_path.is_dir(), "Repository path must be a directory") +@ensure(lambda result: isinstance(result, BridgeConfig), "Must return BridgeConfig") +def generate_bridge_config(self, repo_path: Path) -> BridgeConfig: + """ + Generate bridge configuration for adapter. + + Args: + repo_path: Path to repository root + + Returns: + BridgeConfig instance for adapter + """ + from specfact_cli.models.bridge import AdapterType, ArtifactMapping, BridgeConfig + + # Auto-detect layout and create appropriate config + # Use existing preset methods if available, or create custom config + return BridgeConfig( + adapter=AdapterType., + artifacts={ + "specification": ArtifactMapping( + path_pattern="", + format="", + ), + # Add other artifact mappings... + }, + ) +``` + +#### 2.4 Implement `import_artifact()` + +Import artifacts from tool format: + +```python +@beartype +@require( + lambda artifact_key: isinstance(artifact_key, str) and len(artifact_key) > 0, "Artifact key must be non-empty" +) +@ensure(lambda result: result is None, "Must return None") +def import_artifact( + self, + artifact_key: str, + artifact_path: Path | dict[str, Any], + project_bundle: Any, # ProjectBundle - avoid circular import + bridge_config: BridgeConfig | None = None, +) -> None: + """ + Import artifact from format to SpecFact. + + Args: + artifact_key: Artifact key (e.g., "specification", "plan", "tasks") + artifact_path: Path to artifact file or dict for API-based artifacts + project_bundle: Project bundle to update + bridge_config: Bridge configuration (may contain adapter-specific settings) + """ + # Parse tool-specific format and update project_bundle + # Store tool-specific paths in source_tracking.source_metadata + pass +``` + +#### 2.5 Implement `export_artifact()` + +Export artifacts to tool format: + +```python +@beartype +@require( + lambda artifact_key: isinstance(artifact_key, str) and len(artifact_key) > 0, "Artifact key must be non-empty" +) +@ensure(lambda result: isinstance(result, (Path, dict)), "Must return Path or dict") +def export_artifact( + self, + artifact_key: str, + artifact_data: Any, # Feature, ChangeProposal, etc. - avoid circular import + bridge_config: BridgeConfig | None = None, +) -> Path | dict[str, Any]: + """ + Export artifact from SpecFact to format. + + Args: + artifact_key: Artifact key (e.g., "specification", "plan", "tasks") + artifact_data: Data to export (Feature, Plan, etc.) + bridge_config: Bridge configuration (may contain adapter-specific settings) + + Returns: + Path to exported file or dict with API response data + """ + # Convert SpecFact models to tool-specific format + # Write to file or send via API + # Return Path for file-based exports, dict for API-based exports + pass +``` + +#### 2.6 Implement Change Tracking Methods + +For adapters that support change tracking: + +```python +@beartype +@require(lambda bundle_dir: isinstance(bundle_dir, Path), "Bundle directory must be Path") +@require(lambda bundle_dir: bundle_dir.exists(), "Bundle directory must exist") +@ensure(lambda result: result is None or isinstance(result, ChangeTracking), "Must return ChangeTracking or None") +def load_change_tracking( + self, bundle_dir: Path, bridge_config: BridgeConfig | None = None +) -> ChangeTracking | None: + """Load change tracking from tool-specific location.""" + # Return None if tool doesn't support change tracking + return None + +@beartype +@require(lambda bundle_dir: isinstance(bundle_dir, Path), "Bundle directory must be Path") +@require(lambda bundle_dir: bundle_dir.exists(), "Bundle directory must exist") +@ensure(lambda result: result is None, "Must return None") +def save_change_tracking( + self, bundle_dir: Path, change_tracking: ChangeTracking, bridge_config: BridgeConfig | None = None +) -> None: + """Save change tracking to tool-specific location.""" + # Raise NotImplementedError if tool doesn't support change tracking + raise NotImplementedError("Change tracking not supported by this adapter") +``` + +#### 2.7 Implement Change Proposal Methods + +For adapters that support change proposals: + +```python +@beartype +@require(lambda change_id: isinstance(change_id, str) and len(change_id) > 0, "Change ID must be non-empty") +@ensure(lambda result: result is None or isinstance(result, ChangeProposal), "Must return ChangeProposal or None") +def load_change_proposal( + self, change_id: str, bridge_config: BridgeConfig | None = None +) -> ChangeProposal | None: + """Load change proposal from tool-specific location.""" + # Return None if tool doesn't support change proposals + return None + +@beartype +@require(lambda change_proposal: isinstance(change_proposal, ChangeProposal), "Must provide ChangeProposal") +@ensure(lambda result: result is None, "Must return None") +def save_change_proposal( + self, change_proposal: ChangeProposal, bridge_config: BridgeConfig | None = None +) -> None: + """Save change proposal to tool-specific location.""" + # Raise NotImplementedError if tool doesn't support change proposals + raise NotImplementedError("Change proposals not supported by this adapter") +``` + +### Step 3: Register Adapter + +Register your adapter in `src/specfact_cli/adapters/__init__.py`: + +```python +from specfact_cli.adapters.my_adapter import MyAdapter +from specfact_cli.adapters.registry import AdapterRegistry + +# Auto-register adapter +AdapterRegistry.register("my-adapter", MyAdapter) + +__all__ = [..., "MyAdapter"] +``` + +**Important**: Use the actual CLI tool name as the registry key (e.g., `"speckit"`, `"github"`, not `"spec-kit"` or `"git-hub"`). + +### Step 4: Add Contract Decorators + +All methods must have contract decorators: + +- `@beartype`: Runtime type checking +- `@require`: Preconditions (input validation) +- `@ensure`: Postconditions (output validation) + +Example: + +```python +@beartype +@require(lambda repo_path: repo_path.exists(), "Repository path must exist") +@require(lambda repo_path: repo_path.is_dir(), "Repository path must be a directory") +@ensure(lambda result: isinstance(result, bool), "Must return bool") +def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool: + # Implementation... +``` + +### Step 5: Add Tests + +Create comprehensive tests in `tests/unit/adapters/test_my_adapter.py`: + +```python +"""Unit tests for MyAdapter.""" + +import pytest +from pathlib import Path + +from specfact_cli.adapters.my_adapter import MyAdapter +from specfact_cli.adapters.registry import AdapterRegistry +from specfact_cli.models.bridge import BridgeConfig + + +class TestMyAdapter: + """Test MyAdapter class.""" + + def test_detect(self, tmp_path: Path): + """Test detect() method.""" + adapter = MyAdapter() + # Create tool-specific structure + (tmp_path / ".tool").mkdir() + + assert adapter.detect(tmp_path) is True + + def test_get_capabilities(self, tmp_path: Path): + """Test get_capabilities() method.""" + adapter = MyAdapter() + capabilities = adapter.get_capabilities(tmp_path) + + assert capabilities.tool == "my-adapter" + assert "bidirectional" in capabilities.supported_sync_modes + + def test_adapter_registry_registration(self): + """Test adapter is registered in registry.""" + assert AdapterRegistry.is_registered("my-adapter") + adapter_class = AdapterRegistry.get_adapter("my-adapter") + assert adapter_class == MyAdapter +``` + +### Step 6: Update Documentation + +1. **Update `docs/reference/architecture.md`**: Add your adapter to the adapters section +2. **Update `README.md`**: Add your adapter to the supported tools list +3. **Update `CHANGELOG.md`**: Document the new adapter addition + +## Examples + +### SpecKitAdapter (Bidirectional Sync) + +The `SpecKitAdapter` is a complete example of a bidirectional sync adapter: + +- **Location**: `src/specfact_cli/adapters/speckit.py` +- **Registry key**: `"speckit"` +- **Features**: Bidirectional sync, classic/modern layout support, constitution management +- **Public helpers**: `discover_features()`, `detect_changes()`, `detect_conflicts()`, `export_bundle()` + +### GitHubAdapter (Export-Only) + +The `GitHubAdapter` is an example of an export-only adapter: + +- **Location**: `src/specfact_cli/adapters/github.py` +- **Registry key**: `"github"` +- **Features**: Export-only (OpenSpec → GitHub Issues), progress tracking, content sanitization + +### OpenSpecAdapter (Bidirectional Sync) + +The `OpenSpecAdapter` is an example of a bidirectional sync adapter with change tracking: + +- **Location**: `src/specfact_cli/adapters/openspec.py` +- **Registry key**: `"openspec"` +- **Features**: Bidirectional sync, change tracking, change proposals + +## Best Practices + +### 1. Use Adapter Registry Pattern + +**✅ DO:** + +```python +# In commands/sync.py +adapter = AdapterRegistry.get_adapter(adapter_name) +if adapter: + adapter_instance = adapter() + if adapter_instance.detect(repo_path, bridge_config): + # Use adapter... +``` + +**❌ DON'T:** + +```python +# Hard-coded adapter checks +if adapter_name == "speckit": + adapter = SpecKitAdapter() +elif adapter_name == "github": + adapter = GitHubAdapter() +``` + +### 2. Support Cross-Repo Detection + +Always check `bridge_config.external_base_path` for cross-repository support: + +```python +base_path = repo_path +if bridge_config and bridge_config.external_base_path: + base_path = bridge_config.external_base_path + +# Use base_path for all file operations +tool_dir = base_path / ".tool" +``` + +### 3. Store Source Metadata + +When importing artifacts, store tool-specific paths in `source_tracking.source_metadata`: + +```python +if hasattr(project_bundle, "source_tracking") and project_bundle.source_tracking: + project_bundle.source_tracking.source_metadata = { + "tool": "my-adapter", + "original_path": str(artifact_path), + "tool_version": "1.0.0", + } +``` + +### 4. Handle Missing Artifacts Gracefully + +Return appropriate error messages when artifacts are not found: + +```python +if not artifact_path.exists(): + raise FileNotFoundError( + f"Artifact '{artifact_key}' not found at {artifact_path}. " + f"Expected location: {expected_path}" + ) +``` + +### 5. Use Contract Decorators + +Always add contract decorators for runtime validation: + +```python +@beartype +@require(lambda artifact_key: len(artifact_key) > 0, "Artifact key must be non-empty") +@ensure(lambda result: result is not None, "Must return non-None value") +def import_artifact(self, artifact_key: str, ...) -> None: + # Implementation... +``` + +## Testing + +### Unit Tests + +Create comprehensive unit tests covering: + +- Detection logic (same-repo and cross-repo) +- Capabilities retrieval +- Artifact import/export for all supported artifact types +- Error handling +- Adapter registry registration + +### Integration Tests + +Create integration tests covering: + +- Full sync workflows +- Bidirectional sync (if supported) +- Cross-repo scenarios +- Error recovery + +## Troubleshooting + +### Adapter Not Detected + +- Check `detect()` method logic +- Verify tool-specific structure exists +- Check `bridge_config.external_base_path` for cross-repo scenarios + +### Import/Export Failures + +- Verify artifact paths are resolved correctly +- Check `bridge_config.external_base_path` for cross-repo scenarios +- Ensure artifact format matches tool expectations + +### Registry Registration Issues + +- Verify adapter is imported in `adapters/__init__.py` +- Check registry key matches actual tool name +- Ensure `AdapterRegistry.register()` is called at module import time + +## Related Documentation + +- **[Architecture Documentation](../reference/architecture.md)**: Adapter architecture overview +- **[Architecture Documentation](../reference/architecture.md)**: Adapter architecture and BridgeConfig/ToolCapabilities models +- **[SpecKitAdapter Example](../../src/specfact_cli/adapters/speckit.py)**: Complete bidirectional sync example +- **[GitHubAdapter Example](../../src/specfact_cli/adapters/github.py)**: Export-only adapter example diff --git a/_site_local/guides/agile-scrum-workflows/index.html b/_site_local/guides/agile-scrum-workflows/index.html new file mode 100644 index 0000000..dcbd2c6 --- /dev/null +++ b/_site_local/guides/agile-scrum-workflows/index.html @@ -0,0 +1,1049 @@ + + + + + + + +Agile/Scrum Workflows with SpecFact CLI | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Agile/Scrum Workflows with SpecFact CLI

+ +

This guide explains how to use SpecFact CLI for agile/scrum workflows, including backlog management, sprint planning, dependency tracking, and Definition of Ready (DoR) validation.

+ +

Overview

+ +

SpecFact CLI supports real-world agile/scrum practices through:

+ +
    +
  • Definition of Ready (DoR): Automatic validation of story readiness for sprint planning
    • +
  • Dependency Management: Track story-to-story and feature-to-feature dependencies
    • +
  • Prioritization: Priority levels, ranking, and business value scoring
    • +
  • Sprint Planning: Target sprint/release assignment and story point tracking
    • +
  • Business Value Focus: User-focused value statements and measurable outcomes
    • +
  • Conflict Resolution: Persona-aware three-way merge with automatic conflict resolution based on section ownership
    • +
+ +

Persona-Based Workflows

+ +

SpecFact uses persona-based workflows where different roles work on different aspects:

+ +
    +
  • Product Owner: Owns requirements, user stories, business value, prioritization, sprint planning
    • +
  • Architect: Owns technical constraints, protocols, contracts, architectural decisions, non-functional requirements, risk assessment, deployment architecture
    • +
  • Developer: Owns implementation tasks, technical design, code mappings, test scenarios, Definition of Done
    • +
+ +

Exporting Persona Artifacts

+ +

Export persona-specific Markdown files for editing:

+ +
# Export Product Owner view
+specfact project export --bundle my-project --persona product-owner
+
+# Export Developer view
+specfact project export --bundle my-project --persona developer
+
+# Export Architect view
+specfact project export --bundle my-project --persona architect
+
+# Export to custom location
+specfact project export --bundle my-project --persona product-owner --output docs/backlog.md
+
+ +

The exported Markdown includes persona-specific content:

+ +

Product Owner Export:

+ +
    +
  • Definition of Ready Checklist: Visual indicators for each DoR criterion
    • +
  • Prioritization Data: Priority, rank, business value scores
    • +
  • Dependencies: Clear dependency chains (depends on, blocks)
    • +
  • Business Value: User-focused value statements and metrics
    • +
  • Sprint Planning: Target dates, sprints, and releases
    • +
+ +

Developer Export:

+ +
    +
  • Acceptance Criteria: Feature and story acceptance criteria
    • +
  • User Stories: Detailed story context with tasks, contracts, scenarios
    • +
  • Implementation Tasks: Granular tasks with file paths
    • +
  • Code Mappings: Source and test function mappings
    • +
  • Sprint Context: Story points, priority, dependencies, target sprint/release
    • +
  • Definition of Done: Completion criteria checklist
    • +
+ +

Architect Export:

+ +
    +
  • Technical Constraints: Feature-level technical constraints
    • +
  • Architectural Decisions: Technology choices, patterns, integration approaches
    • +
  • Non-Functional Requirements: Performance, scalability, availability, security, reliability targets
    • +
  • Protocols & State Machines: Complete protocol definitions with states and transitions
    • +
  • Contracts: OpenAPI/AsyncAPI contract details
    • +
  • Risk Assessment: Technical risks and mitigation strategies
    • +
  • Deployment Architecture: Infrastructure and deployment patterns
    • +
+ +

Importing Persona Edits

+ +

After editing the Markdown file, import changes back:

+ +
# Import Product Owner edits
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md
+
+# Import Developer edits
+specfact project import --bundle my-project --persona developer --source docs/developer.md
+
+# Import Architect edits
+specfact project import --bundle my-project --persona architect --source docs/architect.md
+
+# Dry-run to validate without applying
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md --dry-run
+
+ +

The import process validates:

+ +
    +
  • Template Structure: Required sections present
    • +
  • DoR Completeness: All DoR criteria met
    • +
  • Dependency Integrity: No circular dependencies, all references exist
    • +
  • Priority Consistency: Valid priority formats (P0-P3, MoSCoW)
    • +
  • Date Formats: ISO 8601 date validation
    • +
  • Story Point Ranges: Valid Fibonacci-like values
    • +
+ +

Section Locking

+ +

SpecFact supports section-level locking to prevent concurrent edits and ensure data integrity when multiple personas work on the same project bundle.

+ +

Lock Workflow

+ +

Step 1: Lock Section Before Editing

+ +

Lock the sections you plan to edit to prevent conflicts:

+ +
# Product Owner locks idea section
+specfact project lock --bundle my-project --section idea --persona product-owner
+
+# Architect locks protocols section
+specfact project lock --bundle my-project --section protocols --persona architect
+
+ +

Step 2: Export and Edit

+ +

Export your persona view, make edits, then import back:

+ +
# Export
+specfact project export --bundle my-project --persona product-owner
+
+# Edit the exported Markdown file
+# ... make your changes ...
+
+# Import (will be blocked if section is locked by another persona)
+specfact project import --bundle my-project --persona product-owner --input product-owner.md
+
+ +

Step 3: Unlock After Completing Edits

+ +

Unlock the section when you’re done:

+ +
# Unlock section
+specfact project unlock --bundle my-project --section idea
+
+ +

Lock Enforcement

+ +

The project import command automatically checks locks before saving:

+ +
    +
  • Allowed: Import succeeds if you own the locked section
    • +
  • Blocked: Import fails if section is locked by another persona
    • +
  • Blocked: Import fails if section is locked and you don’t own it
    • +
+ +

Example: Lock Enforcement in Action

+ +
# Product Owner locks idea section
+specfact project lock --bundle my-project --section idea --persona product-owner
+
+# Product Owner imports (succeeds - owns the section)
+specfact project import --bundle my-project --persona product-owner --input backlog.md
+# ✓ Import successful
+
+# Architect tries to import (fails - section is locked)
+specfact project import --bundle my-project --persona architect --input architect.md
+# ✗ Error: Cannot import: Section(s) are locked
+#   - Section 'idea' is locked by 'product-owner' (locked at 2025-12-12T10:00:00Z)
+
+ +

Real-World Workflow Example

+ +

Scenario: Product Owner and Architect working in parallel

+ +
# Morning: Product Owner locks idea and business sections
+specfact project lock --bundle my-project --section idea --persona product-owner
+specfact project lock --bundle my-project --section business --persona product-owner
+
+# Product Owner exports and edits
+specfact project export --bundle my-project --persona product-owner
+# Edit docs/project-plans/my-project/product-owner.md
+
+# Product Owner imports (succeeds)
+specfact project import --bundle my-project --persona product-owner \
+  --input docs/project-plans/my-project/product-owner.md
+
+# Product Owner unlocks after completing edits
+specfact project unlock --bundle my-project --section idea
+specfact project unlock --bundle my-project --section business
+
+# Afternoon: Architect locks protocols section
+specfact project lock --bundle my-project --section protocols --persona architect
+
+# Architect exports and edits
+specfact project export --bundle my-project --persona architect
+# Edit docs/project-plans/my-project/architect.md
+
+# Architect imports (succeeds)
+specfact project import --bundle my-project --persona architect \
+  --input docs/project-plans/my-project/architect.md
+
+# Architect unlocks
+specfact project unlock --bundle my-project --section protocols
+
+ +

Checking Locks

+ +

List all current locks:

+ +
# List all locks
+specfact project locks --bundle my-project
+
+ +

Output:

+ +
Section Locks
+┌─────────────────────┬──────────────────┬─────────────────────────┬──────────────────┐
+│ Section             │ Owner            │ Locked At               │ Locked By        │
+├─────────────────────┼──────────────────┼─────────────────────────┼──────────────────┤
+│ idea                │ product-owner    │ 2025-12-12T10:00:00Z    │ user@hostname    │
+│ protocols           │ architect        │ 2025-12-12T14:00:00Z    │ user@hostname    │
+└─────────────────────┴──────────────────┴─────────────────────────┴──────────────────┘
+
+ +

Lock Best Practices

+ +
    +
  1. Lock Before Editing: Always lock sections before exporting and editing
    2. +
  2. Unlock Promptly: Unlock sections immediately after completing edits
    3. +
  3. Check Locks First: Use project locks to see what’s locked before starting work
    4. +
  4. Coordinate with Team: Communicate lock usage to avoid blocking teammates
    5. +
  5. Use Granular Locks: Lock only the sections you need, not entire bundles
    6. +
+ +

Troubleshooting Locks

+ +

Issue: Import fails with “Section(s) are locked”

+ +

Solution: Check who locked the section and coordinate:

+ +
# Check locks
+specfact project locks --bundle my-project
+
+# Contact the lock owner or wait for them to unlock
+# Or ask them to unlock: specfact project unlock --section <section>
+
+ +

Issue: Can’t lock section - “already locked”

+ +

Solution: Someone else has locked it. Check locks and coordinate:

+ +
# See who locked it
+specfact project locks --bundle my-project
+
+# Wait for unlock or coordinate with lock owner
+
+ +

Issue: Locked section but forgot to unlock

+ +

Solution: Unlock manually:

+ +
# Unlock the section
+specfact project unlock --bundle my-project --section <section>
+
+ +

Conflict Resolution

+ +

When multiple personas work on the same project bundle in parallel, conflicts can occur when merging changes. SpecFact provides persona-aware conflict resolution that automatically resolves conflicts based on section ownership.

+ +

How Persona-Based Conflict Resolution Works

+ +

SpecFact uses a three-way merge algorithm that:

+ +
    +
  1. Detects conflicts: Compares base (common ancestor), ours (current branch), and theirs (incoming branch) versions
    2. +
  2. Checks ownership: Determines which persona owns each conflicting section based on bundle manifest
    3. +
  3. Auto-resolves: Automatically resolves conflicts when ownership is clear: +
      +
    • If only one persona owns the section → that persona’s version wins
      • +
    • If both personas own it and they’re the same → current branch wins
      • +
    • If both personas own it and they’re different → requires manual resolution
      • +
    +
    4. +
  4. Interactive resolution: Prompts for manual resolution when ownership is ambiguous
    5. +
+ +

Merge Workflow

+ +

Step 1: Export and Edit

+ +

Each persona exports their view, edits it, and imports back:

+ +
# Product Owner exports and edits
+specfact project export --bundle my-project --persona product-owner
+# Edit docs/project-plans/my-project/product-owner.md
+specfact project import --bundle my-project --persona product-owner --source docs/project-plans/my-project/product-owner.md
+
+# Architect exports and edits (in parallel)
+specfact project export --bundle my-project --persona architect
+# Edit docs/project-plans/my-project/architect.md
+specfact project import --bundle my-project --persona architect --source docs/project-plans/my-project/architect.md
+
+ +

Step 2: Merge Changes

+ +

When merging branches, use project merge with persona information:

+ +
# Merge with automatic persona-based resolution
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours po-branch \
+  --theirs arch-branch \
+  --persona-ours product-owner \
+  --persona-theirs architect
+
+ +

Step 3: Resolve Remaining Conflicts

+ +

If conflicts remain after automatic resolution, resolve them interactively:

+ +
# The merge command will prompt for each unresolved conflict:
+# Choose resolution: [ours/theirs/base/manual]
+
+ +

Or resolve individual conflicts manually:

+ +
# Resolve a specific conflict
+specfact project resolve-conflict \
+  --bundle my-project \
+  --path features.FEATURE-001.title \
+  --resolution ours
+
+ +

Example: Resolving a Conflict

+ +

Scenario: Product Owner and Architect both modified the same feature title.

+ +

Base version (common ancestor):

+ +
features:
+  FEATURE-001:
+    title: "User Authentication"
+
+ +

Product Owner’s version (ours):

+ +
features:
+  FEATURE-001:
+    title: "Secure User Authentication"
+
+ +

Architect’s version (theirs):

+ +
features:
+  FEATURE-001:
+    title: "OAuth2 User Authentication"
+
+ +

Automatic Resolution:

+ +
    +
  1. SpecFact checks ownership: features.FEATURE-001 is owned by product-owner (based on manifest)
    2. +
  2. Since Product Owner owns this section, their version wins automatically
    3. +
  3. Result: "Secure User Authentication" is kept
    4. +
+ +

Manual Resolution (if both personas own it):

+ +

If both personas own the section, SpecFact prompts:

+ +
Resolving conflict: features.FEATURE-001.title
+Base: User Authentication
+Ours (product-owner): Secure User Authentication
+Theirs (architect): OAuth2 User Authentication
+
+Choose resolution [ours/theirs/base/manual]: manual
+Enter manual value: OAuth2 Secure User Authentication
+
+ +

Conflict Resolution Strategies

+ +

You can specify a merge strategy to override automatic resolution:

+ +
    +
  • auto (default): Persona-based automatic resolution
    • +
  • ours: Always prefer our version
    • +
  • theirs: Always prefer their version
    • +
  • base: Always prefer base version
    • +
  • manual: Require manual resolution for all conflicts
    • +
+ +
# Use manual strategy for full control
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours po-branch \
+  --theirs arch-branch \
+  --persona-ours product-owner \
+  --persona-theirs architect \
+  --strategy manual
+
+ +

CI/CD Integration

+ +

For automated workflows, use --no-interactive:

+ +
# Non-interactive merge (fails if conflicts require manual resolution)
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours HEAD \
+  --theirs origin/feature \
+  --persona-ours product-owner \
+  --persona-theirs architect \
+  --no-interactive
+
+ +

Note: In non-interactive mode, the merge will fail if there are conflicts that require manual resolution. Use this in CI/CD pipelines only when you’re confident conflicts will be auto-resolved.

+ +

Best Practices

+ +
    +
  1. Set Clear Ownership: Ensure persona ownership is clearly defined in bundle manifest
    2. +
  2. Merge Frequently: Merge branches frequently to reduce conflict scope
    3. +
  3. Review Auto-Resolutions: Review automatically resolved conflicts before committing
    4. +
  4. Use Manual Strategy for Complex Conflicts: When in doubt, use --strategy manual for full control
    5. +
  5. Document Resolution Decisions: Add comments explaining why certain resolutions were chosen
    6. +
+ +

Troubleshooting Conflicts

+ +

Issue: Merge fails with “unresolved conflicts”

+ +

Solution: Use interactive mode to resolve conflicts:

+ +
# Run merge in interactive mode
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours po-branch \
+  --theirs arch-branch \
+  --persona-ours product-owner \
+  --persona-theirs architect
+# Follow prompts to resolve each conflict
+
+ +

Issue: Auto-resolution chose wrong version

+ +

Solution: Check persona ownership in manifest, or use manual strategy:

+ +
# Check ownership
+specfact project export --bundle my-project --list-personas
+
+# Use manual strategy
+specfact project merge --strategy manual ...
+
+ +

Issue: Conflict path not found

+ +

Solution: Use correct conflict path format:

+ +
    +
  • idea.title - Idea title
    • +
  • business.value_proposition - Business value proposition
    • +
  • features.FEATURE-001.title - Feature title
    • +
  • features.FEATURE-001.stories.STORY-001.description - Story description
    • +
+ +

Definition of Ready (DoR)

+ +

DoR Checklist

+ +

Each story must meet these criteria before sprint planning:

+ +
    +
  • Story Points: Complexity estimated (1, 2, 3, 5, 8, 13, 21…)
    • +
  • Value Points: Business value estimated (1, 2, 3, 5, 8, 13, 21…)
    • +
  • Priority: Priority level set (P0-P3 or MoSCoW)
    • +
  • Dependencies: Dependencies identified and validated
    • +
  • Business Value: Clear business value description present
    • +
  • Target Date: Target completion date set (optional but recommended)
    • +
  • Target Sprint: Target sprint assigned (optional but recommended)
    • +
+ +

Example: Story with Complete DoR

+ +
**Story 1**: User can login with email
+
+**Definition of Ready**:
+- [x] Story Points: 5 (Complexity)
+- [x] Value Points: 8 (Business Value)
+- [x] Priority: P1
+- [x] Dependencies: 1 identified
+- [x] Business Value: ✓
+- [x] Target Date: 2025-01-15
+- [x] Target Sprint: Sprint 2025-01
+
+**Story Details**:
+- **Story Points**: 5 (Complexity)
+- **Value Points**: 8 (Business Value)
+- **Priority**: P1
+- **Rank**: 1
+- **Target Date**: 2025-01-15
+- **Target Sprint**: Sprint 2025-01
+- **Target Release**: v2.1.0
+
+**Business Value**:
+Enables users to securely access their accounts, reducing support tickets by 30% and improving user satisfaction.
+
+**Business Metrics**:
+- Reduce support tickets by 30%
+- Increase user login success rate to 99.5%
+- Reduce password reset requests by 25%
+
+**Dependencies**:
+**Depends On**:
+- STORY-000: User registration system
+
+**Acceptance Criteria** (User-Focused):
+- [ ] As a user, I can enter my email and password to log in
+- [ ] As a user, I receive clear error messages if login fails
+- [ ] As a user, I am redirected to my dashboard after successful login
+
+ +

Dependency Management

+ +

Story Dependencies

+ +

Track dependencies between stories:

+ +
**Dependencies**:
+**Depends On**:
+- STORY-001: User registration system
+- STORY-002: Email verification
+
+**Blocks**:
+- STORY-010: Password reset flow
+
+ +

Feature Dependencies

+ +

Track dependencies between features:

+ +
### FEATURE-001: User Authentication
+
+#### Dependencies
+
+**Depends On Features**:
+- FEATURE-000: User Management Infrastructure
+
+**Blocks Features**:
+- FEATURE-002: User Profile Management
+
+ +

Validation Rules

+ +

The import process validates:

+ +
    +
  1. Reference Existence: All referenced stories/features exist
    2. +
  2. No Circular Dependencies: Prevents A → B → A cycles
    3. +
  3. Format Validation: Dependency keys match expected format (STORY-001, FEATURE-001)
    4. +
+ +

Example: Circular Dependency Error

+ +
$ specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+Error: Agile/Scrum validation failed:
+  - Story STORY-001: Circular dependency detected with 'STORY-002'
+  - Feature FEATURE-001: Circular dependency detected with 'FEATURE-002'
+
+ +

Prioritization

+ +

Priority Levels

+ +

Use one of these priority formats:

+ +
    +
  • P0-P3: P0=Critical, P1=High, P2=Medium, P3=Low
    • +
  • MoSCoW: Must, Should, Could, Won’t
    • +
  • Descriptive: Critical, High, Medium, Low
    • +
+ +

Ranking

+ +

Use backlog rank (1 = highest priority):

+ +
**Priority**: P1 | **Rank**: 1
+
+ +

Business Value Scoring

+ +

Score features 0-100 for business value:

+ +
**Business Value Score**: 75/100
+
+ +

Example: Prioritized Feature

+ +
### FEATURE-001: User Authentication
+
+**Priority**: P1 | **Rank**: 1  
+**Business Value Score**: 75/100  
+**Target Release**: v2.1.0  
+**Estimated Story Points**: 13
+
+#### Business Value
+
+Enables secure user access, reducing support overhead and improving user experience.
+
+**Target Users**: end-user, admin
+
+**Success Metrics**:
+- Reduce support tickets by 30%
+- Increase user login success rate to 99.5%
+- Reduce password reset requests by 25%
+
+ +

Sprint Planning

+ +

Story Point Estimation

+ +

Use Fibonacci-like values: 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 100

+ +
- **Story Points**: 5 (Complexity)
+- **Value Points**: 8 (Business Value)
+
+ +

Target Sprint Assignment

+ +

Assign stories to specific sprints:

+ +
- **Target Sprint**: Sprint 2025-01
+- **Target Release**: v2.1.0
+- **Target Date**: 2025-01-15
+
+ +

Feature-Level Totals

+ +

Feature story point totals are automatically calculated:

+ +
**Estimated Story Points**: 13
+
+ +

This is the sum of all story points for stories in this feature.

+ +

Business Value Focus

+ +

User-Focused Value Statements

+ +

Write stories with clear user value:

+ +
**Business Value**:
+As a user, I want to securely log in to my account so that I can access my personalized dashboard and manage my data.
+
+**Business Metrics**:
+- Reduce support tickets by 30%
+- Increase user login success rate to 99.5%
+- Reduce password reset requests by 25%
+
+ +

Acceptance Criteria Format

+ +

Use “As a [user], I want [capability] so that [outcome]” format:

+ +
**Acceptance Criteria** (User-Focused):
+- [ ] As a user, I can enter my email and password to log in
+- [ ] As a user, I receive clear error messages if login fails
+- [ ] As a user, I am redirected to my dashboard after successful login
+
+ +

Template Customization

+ +

Override Default Templates

+ +

Create project-specific templates in .specfact/templates/persona/:

+ +
.specfact/
+└── templates/
+    └── persona/
+        └── product-owner.md.j2  # Project-specific template
+
+ +

The project-specific template overrides the default template in resources/templates/persona/.

+ +

Template Structure

+ +

Templates use Jinja2 syntax with these variables:

+ +
    +
  • bundle_name: Project bundle name
    • +
  • features: Dictionary of features (key -> feature dict)
    • +
  • idea: Idea section data
    • +
  • business: Business section data
    • +
  • locks: Section locks information
    • +
+ +

Example: Custom Template Section

+ +
{% if features %}
+## Features & User Stories
+
+{% for feature_key, feature in features.items() %}
+### {{ feature.key }}: {{ feature.title }}
+
+**Priority**: {{ feature.priority | default('Not Set') }}
+**Business Value**: {{ feature.business_value_score | default('Not Set') }}/100
+
+{% if feature.stories %}
+#### User Stories
+
+{% for story in feature.stories %}
+**Story {{ loop.index }}**: {{ story.title }}
+
+**DoR Status**: {{ '✓ Complete' if story.definition_of_ready.values() | all else '✗ Incomplete' }}
+
+{% endfor %}
+{% endif %}
+
+{% endfor %}
+{% endif %}
+
+ +

Validation Examples

+ +

DoR Validation

+ +
$ specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+Error: Agile/Scrum validation failed:
+  - Story STORY-001 (Feature FEATURE-001): Missing story points (required for DoR)
+  - Story STORY-001 (Feature FEATURE-001): Missing value points (required for DoR)
+  - Story STORY-001 (Feature FEATURE-001): Missing priority (required for DoR)
+  - Story STORY-001 (Feature FEATURE-001): Missing business value description (required for DoR)
+
+ +

Dependency Validation

+ +
$ specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+Error: Agile/Scrum validation failed:
+  - Story STORY-001: Dependency 'STORY-999' does not exist
+  - Story STORY-001: Circular dependency detected with 'STORY-002'
+  - Feature FEATURE-001: Dependency 'FEATURE-999' does not exist
+
+ +

Priority Validation

+ +
$ specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+Error: Agile/Scrum validation failed:
+  - Story STORY-001: Invalid priority 'P5' (must be P0-P3, MoSCoW, or Critical/High/Medium/Low)
+  - Feature FEATURE-001: Invalid priority 'Invalid' (must be P0-P3, MoSCoW, or Critical/High/Medium/Low)
+
+ +

Date Format Validation

+ +
$ specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+Error: Agile/Scrum validation failed:
+  - Story STORY-001: Invalid date format '2025/01/15' (expected ISO 8601: YYYY-MM-DD)
+  - Story STORY-001: Warning - target date '2024-01-15' is in the past (may need updating)
+
+ +

Best Practices

+ +

1. Complete DoR Before Sprint Planning

+ +

Ensure all stories meet DoR criteria before assigning to sprints:

+ +
# Validate DoR completeness
+specfact project import --bundle my-project --persona product-owner --source backlog.md --dry-run
+
+ +

2. Track Dependencies Early

+ +

Identify dependencies during story creation to avoid blockers:

+ +
**Dependencies**:
+**Depends On**:
+- STORY-001: User registration (must complete first)
+
+ +

3. Use Consistent Priority Formats

+ +

Choose one priority format per project and use consistently:

+ +
    +
  • Option 1: P0-P3 (recommended for technical teams)
    • +
  • Option 2: MoSCoW (recommended for business-focused teams)
    • +
  • Option 3: Descriptive (Critical/High/Medium/Low)
    • +
+ +

4. Set Business Value for All Stories

+ +

Every story should have a clear business value statement:

+ +
**Business Value**:
+Enables users to securely access their accounts, reducing support tickets by 30%.
+
+ +

5. Use Story Points for Capacity Planning

+ +

Track story points to estimate sprint capacity:

+ +
**Estimated Story Points**: 21  # Sum of all stories in feature
+
+ +

Troubleshooting

+ +

Validation Errors

+ +

If import fails with validation errors:

+ +
    +
  1. Check DoR Completeness: Ensure all required fields are present
    2. +
  2. Verify Dependencies: Check that all referenced stories/features exist
    3. +
  3. Validate Formats: Ensure priority, dates, and story points use correct formats
    4. +
  4. Review Business Value: Ensure business value descriptions are present and meaningful
    5. +
+ +

Template Issues

+ +

If template rendering fails:

+ +
    +
  1. Check Template Syntax: Verify Jinja2 syntax is correct
    2. +
  2. Verify Variables: Ensure template variables match exported data structure
    3. +
  3. Test Template: Use --dry-run to test template without importing
    4. +
+ + + + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/guides/brownfield-faq.md b/_site_local/guides/brownfield-faq.md new file mode 100644 index 0000000..40e2d53 --- /dev/null +++ b/_site_local/guides/brownfield-faq.md @@ -0,0 +1,369 @@ +# Brownfield Modernization FAQ + +> **Frequently asked questions about using SpecFact CLI for legacy code modernization** + +--- + +## General Questions + +### What is brownfield modernization? + +**Brownfield modernization** refers to improving, refactoring, or migrating existing (legacy) codebases, as opposed to greenfield development (starting from scratch). + +SpecFact CLI is designed specifically for brownfield projects where you need to: + +- Understand undocumented legacy code +- Modernize without breaking existing behavior +- Extract specs from existing code (code2spec) +- Enforce contracts during refactoring + +--- + +## Code Analysis + +### Can SpecFact analyze code with no docstrings? + +**Yes.** SpecFact's code2spec analyzes: + +- Function signatures and type hints +- Code patterns and control flow +- Existing validation logic +- Module dependencies +- Commit history and code structure + +No docstrings needed. SpecFact infers behavior from code patterns. + +### What if the legacy code has no type hints? + +**SpecFact infers types** from usage patterns and generates specs. You can add type hints incrementally as part of modernization. + +**Example:** + +```python +# Legacy code (no type hints) +def process_order(user_id, amount): + # SpecFact infers: user_id: int, amount: float + ... + +# SpecFact generates: +# - Precondition: user_id > 0, amount > 0 +# - Postcondition: returns Order object +``` + +### Can SpecFact handle obfuscated or minified code? + +**Limited.** SpecFact works best with: + +- Source code (not compiled bytecode) +- Readable variable names +- Standard Python patterns + +For heavily obfuscated code, consider: + +1. Deobfuscation first (if possible) +2. Manual documentation of critical paths +3. Adding contracts incrementally to deobfuscated sections + +### What about code with no tests? + +**SpecFact doesn't require tests.** In fact, code2spec is designed for codebases with: + +- No tests +- No documentation +- No type hints + +SpecFact extracts specs from code structure and patterns, not from tests. + +--- + +## Contract Enforcement + +### Will contracts slow down my code? + +**Minimal impact.** Contract checks are fast (microseconds per call). For high-performance code: + +- **Development/Testing:** Keep contracts enabled (catch violations) +- **Production:** Optionally disable contracts (performance-critical paths only) + +**Best practice:** Keep contracts in tests, disable only in production hot paths if needed. + +### Can I add contracts incrementally? + +**Yes.** Recommended approach: + +1. **Week 1:** Add contracts to 3-5 critical functions +2. **Week 2:** Expand to 10-15 functions +3. **Week 3:** Add contracts to all public APIs +4. **Week 4+:** Add contracts to internal functions as needed + +Start with shadow mode (observe only), then enable enforcement incrementally. + +### What if a contract is too strict? + +**Contracts are configurable.** You can: + +- **Relax contracts:** Adjust preconditions/postconditions to match actual behavior +- **Shadow mode:** Observe violations without blocking +- **Warn mode:** Log violations but don't raise exceptions +- **Block mode:** Raise exceptions on violations (default) + +Start in shadow mode, then tighten as you understand the code better. + +--- + +## Edge Case Discovery + +### How does CrossHair discover edge cases? + +**CrossHair uses symbolic execution** to explore all possible code paths mathematically. It: + +1. Represents inputs symbolically (not concrete values) +2. Explores all feasible execution paths +3. Finds inputs that violate contracts +4. Generates concrete test cases for violations + +**Example:** + +```python +@icontract.require(lambda numbers: len(numbers) > 0) +@icontract.ensure(lambda numbers, result: min(numbers) > result) +def remove_smallest(numbers: List[int]) -> int: + smallest = min(numbers) + numbers.remove(smallest) + return smallest + +# CrossHair finds: [3, 3, 5] violates postcondition +# (duplicates cause min(numbers) == result after removal) +``` + +### Can CrossHair find all edge cases? + +**No tool can find all edge cases**, but CrossHair is more thorough than: + +- Manual testing (limited by human imagination) +- Random testing (limited by coverage) +- LLM suggestions (probabilistic, not exhaustive) + +CrossHair provides **mathematical guarantees** for explored paths, but complex code may have paths that are computationally infeasible to explore. + +### How long does CrossHair take? + +**Typically 10-60 seconds per function**, depending on: + +- Function complexity +- Number of code paths +- Contract complexity + +For large codebases, run CrossHair on critical functions first, then expand. + +--- + +## Modernization Workflow + +### How do I start modernizing safely? + +**Recommended workflow:** + +1. **Extract specs** (`specfact import from-code`) +2. **Add contracts** to 3-5 critical functions +3. **Run CrossHair** to discover edge cases +4. **Refactor incrementally** (one function at a time) +5. **Verify contracts** still pass after refactoring +6. **Expand contracts** to more functions + +Start in shadow mode, then enable enforcement as you gain confidence. + +### What if I break a contract during refactoring? + +**That's the point!** Contracts catch regressions immediately: + +```python +# Refactored code violates contract +process_payment(user_id=-1, amount=-50, currency="XYZ") + +# Contract violation caught: +# ❌ ContractViolation: Payment amount must be positive (got -50) +# → Fix the bug before it reaches production! +``` + +Contracts are your **safety net** - they prevent breaking changes from being deployed. + +### Can I use SpecFact with existing test suites? + +**Yes.** SpecFact complements existing tests: + +- **Tests:** Verify specific scenarios +- **Contracts:** Enforce behavior at API boundaries +- **CrossHair:** Discover edge cases tests miss + +Use all three together for comprehensive coverage. + +### What's the learning curve for contract-first development? + +**Minimal.** SpecFact is designed for incremental adoption: + +**Week 1 (2-4 hours):** + +- Run `import from-code` to extract specs (10 seconds) +- Review extracted plan bundle +- Add contracts to 3-5 critical functions + +**Week 2 (4-6 hours):** + +- Expand contracts to 10-15 functions +- Run CrossHair on critical paths +- Set up pre-commit hook + +**Week 3+ (ongoing):** + +- Add contracts incrementally as you refactor +- Use shadow mode to observe violations +- Enable enforcement when confident + +**No upfront training required.** Start with shadow mode (observe only), then enable enforcement incrementally as you understand the code better. + +**Resources:** + +- [Brownfield Engineer Guide](brownfield-engineer.md) - Complete walkthrough +- [Integration Showcases](../examples/integration-showcases/) - Real examples +- [Getting Started](../getting-started/README.md) - Quick start guide + +--- + +## Integration + +### Does SpecFact work with GitHub Spec-Kit? + +**Yes.** SpecFact complements Spec-Kit: + +- **Spec-Kit:** Interactive spec authoring (greenfield) +- **SpecFact:** Automated enforcement + brownfield support + +**Use both together:** + +1. Use Spec-Kit for initial spec generation (fast, LLM-powered) +2. Use SpecFact to add runtime contracts to critical paths (safety net) +3. Spec-Kit generates docs, SpecFact prevents regressions + +See [Spec-Kit Comparison Guide](speckit-comparison.md) for details. + +### Can I use SpecFact in CI/CD? + +**Yes.** SpecFact integrates with: + +- **GitHub Actions:** PR annotations, contract validation +- **GitLab CI:** Pipeline integration +- **Jenkins:** Plugin support (planned) +- **Local CI:** Run `specfact enforce` in your pipeline + +Contracts can block merges if violations are detected (configurable). + +### Does SpecFact work with VS Code, Cursor, or other IDEs? + +**Yes.** SpecFact's CLI-first design means it works with **any IDE or editor**: + +- **VS Code:** Pre-commit hooks, tasks, or extensions +- **Cursor:** AI assistant integration with contract validation +- **Any editor:** Pure CLI, no IDE lock-in required +- **Agentic workflows:** Works with any AI coding assistant + +**Example VS Code integration:** + +```bash +# .git/hooks/pre-commit +#!/bin/sh +uvx specfact-cli@latest enforce stage --preset balanced +``` + +**Example Cursor integration:** + +```bash +# Validate AI suggestions before accepting +cursor-agent --validate-with "uvx specfact-cli@latest enforce stage" +``` + +See [Integration Showcases](../examples/integration-showcases/) for real examples of bugs caught via different integrations. + +### Do I need to learn a new platform? + +**No.** SpecFact is **CLI-first**—it integrates into your existing workflow: + +- ✅ Works with your current IDE (VS Code, Cursor, etc.) +- ✅ Works with your current CI/CD (GitHub Actions, GitLab, etc.) +- ✅ Works with your current tools (no new platform to learn) +- ✅ Works offline (no cloud account required) +- ✅ Zero vendor lock-in (OSS forever) + +**No platform migration needed.** Just add SpecFact CLI to your existing workflow. + +--- + +## Performance + +### How fast is code2spec extraction? + +**Typical timing**: + +- **Small codebases** (10-50 files): ~10 seconds to 1-2 minutes +- **Medium codebases** (50-100 files): ~1-2 minutes +- **Large codebases** (100+ files): **2-3 minutes** for AST + Semgrep analysis +- **Large codebases with contracts** (100+ files): **15-30+ minutes** with contract extraction, graph analysis, and parallel processing (8 workers) + +The import process performs AST analysis, Semgrep pattern detection, and (when enabled) extracts OpenAPI contracts, relationships, and graph dependencies in parallel, which can take significant time for large repositories. + +### Does SpecFact require internet? + +**No.** SpecFact works 100% offline: + +- No cloud services required +- No API keys needed +- No telemetry (opt-in only) +- Fully local execution + +Perfect for air-gapped environments or sensitive codebases. + +--- + +## Limitations + +### What are SpecFact's limitations? + +**Known limitations:** + +1. **Python-only** (JavaScript/TypeScript support planned Q1 2026) +2. **Source code required** (not compiled bytecode) +3. **Readable code preferred** (obfuscated code may have lower accuracy) +4. **Complex contracts** may slow CrossHair (timeout configurable) + +**What SpecFact does well:** + +- ✅ Extracts specs from undocumented code +- ✅ Enforces contracts at runtime +- ✅ Discovers edge cases with symbolic execution +- ✅ Prevents regressions during modernization + +--- + +## Support + +### Where can I get help? + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) - Ask questions +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) - Report bugs +- 📧 [hello@noldai.com](mailto:hello@noldai.com) - Direct support + +### Can I contribute? + +**Yes!** SpecFact is open source. See [CONTRIBUTING.md](https://github.com/nold-ai/specfact-cli/blob/main/CONTRIBUTING.md) for guidelines. + +--- + +## Next Steps + +1. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete modernization workflow +2. **[ROI Calculator](brownfield-roi.md)** - Calculate your savings +3. **[Examples](../examples/)** - Real-world brownfield examples + +--- + +**Still have questions?** [Open a discussion](https://github.com/nold-ai/specfact-cli/discussions) or [email us](mailto:hello@noldai.com). diff --git a/_site_local/guides/brownfield-roi.md b/_site_local/guides/brownfield-roi.md new file mode 100644 index 0000000..0fabb32 --- /dev/null +++ b/_site_local/guides/brownfield-roi.md @@ -0,0 +1,224 @@ +# Brownfield Modernization ROI with SpecFact + +> **Calculate your time and cost savings when modernizing legacy Python code** + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow (VS Code, Cursor, GitHub Actions, pre-commit hooks). No platform to learn, no vendor lock-in. + +--- + +## ROI Calculator + +Use this calculator to estimate your savings when using SpecFact CLI for brownfield modernization. + +### Input Your Project Size + +**Number of Python files in legacy codebase:** `[____]` +**Average lines of code per file:** `[____]` +**Hourly rate:** `$[____]` per hour + +--- + +## Manual Approach (Baseline) + +### Time Investment + +| Task | Time (Hours) | Cost | +|------|-------------|------| +| **Documentation** | | | +| - Manually document legacy code | `[files] × 1.5-2.5 hours` | `$[____]` | +| - Write API documentation | `[endpoints] × 2-4 hours` | `$[____]` | +| - Create architecture diagrams | `8-16 hours` | `$[____]` | +| **Testing** | | | +| - Write tests for undocumented code | `[files] × 2-3 hours` | `$[____]` | +| - Manual edge case discovery | `20-40 hours` | `$[____]` | +| **Modernization** | | | +| - Debug regressions during refactor | `40-80 hours` | `$[____]` | +| - Fix production bugs from modernization | `20-60 hours` | `$[____]` | +| **TOTAL** | **`[____]` hours** | **`$[____]`** | + +### Example: 50-File Legacy App + +| Task | Time (Hours) | Cost (@$150/hr) | +|------|-------------|-----------------| +| Manually document 50-file legacy app | 80-120 hours | $12,000-$18,000 | +| Write tests for undocumented code | 100-150 hours | $15,000-$22,500 | +| Debug regression during refactor | 40-80 hours | $6,000-$12,000 | +| **TOTAL** | **220-350 hours** | **$33,000-$52,500** | + +--- + +## SpecFact Automated Approach + +### Time Investment (Automated) + +| Task | Time (Hours) | Cost | +|------|-------------|------| +| **Documentation** | | | +| - Run code2spec extraction | `0.17 hours (10 min)` | `$[____]` | +| - Review and refine extracted specs | `8-16 hours` | `$[____]` | +| **Contract Enforcement** | | | +| - Add contracts to critical paths | `16-24 hours` | `$[____]` | +| - CrossHair edge case discovery | `2-4 hours` | `$[____]` | +| **Modernization** | | | +| - Refactor with contract safety net | `[baseline] × 0.5-0.7` | `$[____]` | +| - Fix regressions (prevented by contracts) | `0-10 hours` | `$[____]` | +| **TOTAL** | **`[____]` hours** | **`$[____]`** | + +### Example: 50-File Legacy App (Automated Results) + +| Task | Time (Hours) | Cost (@$150/hr) | +|------|-------------|-----------------| +| Run code2spec extraction | 0.17 hours (10 min) | $25 | +| Review and refine extracted specs | 8-16 hours | $1,200-$2,400 | +| Add contracts to critical paths | 16-24 hours | $2,400-$3,600 | +| CrossHair edge case discovery | 2-4 hours | $300-$600 | +| **TOTAL** | **26-44 hours** | **$3,925-$6,625** | + +--- + +## ROI Calculation + +### Time Savings + +**Manual approach:** `[____]` hours +**SpecFact approach:** `[____]` hours +**Time saved:** `[____]` hours (**`[____]%`** reduction) + +### Cost Savings + +**Manual approach:** `$[____]` +**SpecFact approach:** `$[____]` +**Cost avoided:** `$[____]` (**`[____]%`** reduction) + +### Example: 50-File Legacy App (Results) + +**Time saved:** 194-306 hours (**87%** reduction) +**Cost avoided:** $26,075-$45,875 (**87%** reduction) + +--- + +## Industry Benchmarks + +### IBM GenAI Modernization Study + +- **70% cost reduction** via automated code discovery +- **50% faster** feature delivery +- **95% reduction** in manual effort + +### SpecFact Alignment + +SpecFact's code2spec provides similar automation: + +- **87% time saved** on documentation (vs. manual) +- **100% detection rate** for contract violations (vs. manual review) +- **6-12 edge cases** discovered automatically (vs. 0-2 manually) + +--- + +## Additional Benefits (Not Quantified) + +### Quality Improvements + +- ✅ **Zero production bugs** from modernization (contracts prevent regressions) +- ✅ **100% API documentation** coverage (extracted automatically) +- ✅ **Hidden edge cases** discovered before production (CrossHair) + +### Team Productivity + +- ✅ **60% faster** developer onboarding (documented codebase) +- ✅ **50% reduction** in code review time (contracts catch issues) +- ✅ **Zero debugging time** for contract violations (caught at runtime) + +### Risk Reduction + +- ✅ **Formal guarantees** vs. probabilistic LLM suggestions +- ✅ **Mathematical verification** vs. manual code review +- ✅ **Safety net** during modernization (contracts enforce behavior) + +--- + +## Real-World Case Studies + +### Case Study 1: Data Pipeline Modernization + +**Challenge:** + +- 5-year-old Python data pipeline (12K LOC) +- No documentation, original developers left +- Needed modernization from Python 2.7 → 3.12 +- Fear of breaking critical ETL jobs + +**Solution:** + +1. Ran `specfact import from-code` → 47 features extracted in 12 seconds +2. Added contracts to 23 critical data transformation functions +3. CrossHair discovered 6 edge cases in legacy validation logic +4. Enforced contracts during migration, blocked 11 regressions +5. Integrated with GitHub Actions CI/CD to prevent bad code from merging + +**Results:** + +- ✅ 87% faster documentation (8 hours vs. 60 hours manual) +- ✅ 11 production bugs prevented during migration +- ✅ Zero downtime migration completed in 3 weeks vs. estimated 8 weeks +- ✅ New team members productive in days vs. weeks + +**ROI:** $42,000 saved, 5-week acceleration + +### Case Study 2: Integration Success Stories + +**See real examples of bugs fixed via integrations:** + +- **[Integration Showcases](../examples/integration-showcases/)** - 5 complete examples: + - VS Code + Pre-commit: Async bug caught before commit + - Cursor Integration: Regression prevented during refactoring + - GitHub Actions: Type mismatch blocked from merging + - Pre-commit Hook: Breaking change detected locally + - Agentic Workflows: Edge cases discovered with symbolic execution + +**Key Finding**: 3 of 5 examples fully validated, showing real bugs fixed through CLI integrations. + +--- + +## When ROI Is Highest + +SpecFact provides maximum ROI for: + +- ✅ **Large codebases** (50+ files) - More time saved on documentation +- ✅ **Undocumented code** - Manual documentation is most expensive +- ✅ **High-risk systems** - Contract enforcement prevents costly production bugs +- ✅ **Complex business logic** - CrossHair discovers edge cases manual testing misses +- ✅ **Team modernization** - Faster onboarding = immediate productivity gains + +--- + +## Try It Yourself + +Calculate your ROI: + +1. **Run code2spec** on your legacy codebase: + + ```bash + specfact import from-code --bundle legacy-api --repo ./your-legacy-app + ``` + +2. **Time the extraction** (typically < 10 seconds) + +3. **Compare to manual documentation time** (typically 1.5-2.5 hours per file) + +4. **Calculate your savings:** + - Time saved = (files × 1.5 hours) - 0.17 hours + - Cost saved = Time saved × hourly rate + +--- + +## Next Steps + +1. **[Integration Showcases](../examples/integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations +2. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete modernization workflow +3. **[Brownfield Journey](brownfield-journey.md)** - Step-by-step modernization guide +4. **[Examples](../examples/)** - Real-world brownfield examples + +--- + +**Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) | [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_local/guides/command-chains/index.html b/_site_local/guides/command-chains/index.html new file mode 100644 index 0000000..f0b7750 --- /dev/null +++ b/_site_local/guides/command-chains/index.html @@ -0,0 +1,922 @@ + + + + + + + +Command Chains Reference | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Command Chains Reference

+ +
+

Complete guide to SpecFact CLI command chains and workflows

+
+ +
+ +

Overview

+ +

Command chains are sequences of SpecFact CLI commands that work together to achieve specific goals. Each chain represents a complete workflow from start to finish, with decision points and expected outcomes documented.

+ +

Why use command chains? Instead of learning individual commands in isolation, command chains show you how to combine commands to solve real-world problems. They provide context, decision points, and links to detailed guides.

+ +

This document covers all 9 identified command chains:

+ +
    +
  • 6 Mature Chains: Well-established workflows with comprehensive documentation
    • +
  • 3 Emerging Chains: AI-assisted workflows that integrate with IDE slash commands
    • +
+ +
+ +

When to Use Which Chain?

+ +

Use this decision tree to find the right chain for your use case:

+ +
Start: What do you want to accomplish?
+
+├─ Modernize existing legacy code?
+│  └─ → Brownfield Modernization Chain
+│
+├─ Plan a new feature from scratch?
+│  └─ → Greenfield Planning Chain
+│
+├─ Integrate with Spec-Kit, OpenSpec, or other tools?
+│  └─ → External Tool Integration Chain
+│
+├─ Develop or validate API contracts?
+│  └─ → API Contract Development Chain
+│
+├─ Promote a plan through stages to release?
+│  └─ → Plan Promotion & Release Chain
+│
+├─ Compare code against specifications?
+│  └─ → Code-to-Plan Comparison Chain
+│
+├─ Use AI to enhance code with contracts?
+│  └─ → AI-Assisted Code Enhancement Chain (Emerging)
+│
+├─ Generate tests from specifications?
+│  └─ → Test Generation from Specifications Chain (Emerging)
+│
+└─ Fix gaps discovered during analysis?
+   └─ → Gap Discovery & Fixing Chain (Emerging)
+
+ +
+ +

1. Brownfield Modernization Chain

+ +

Goal: Modernize legacy code safely by extracting specifications, creating plans, and enforcing contracts.

+ +

When to use: You have existing code that needs modernization, refactoring, or migration.

+ +

Command Sequence:

+ +
# Step 1: Extract specifications from legacy code
+specfact import from-code --bundle legacy-api --repo .
+
+# Step 2: Review the extracted plan
+specfact plan review --bundle legacy-api
+
+# Step 3: Update features based on review findings
+specfact plan update-feature --bundle legacy-api --feature <feature-id>
+
+# Step 4: Enforce SDD (Spec-Driven Development) compliance
+specfact enforce sdd --bundle legacy-api
+
+# Step 5: Run full validation suite
+specfact repro --verbose
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Legacy Codebase] -->|import from-code| B[Extract Specifications]
+    B --> C[Plan Review]
+    C -->|Issues Found| D[Update Features]
+    C -->|No Issues| E[Enforce SDD]
+    D --> E
+    E --> F[Run Validation]
+    F -->|Pass| G[Modernized Code]
+    F -->|Fail| D
+
+ +

Decision Points:

+ +
    +
  • After import from-code: Review the extracted plan. If features are incomplete or incorrect, use plan update-feature to refine them.
    • +
  • After plan review: If ambiguities are found, resolve them before proceeding to enforcement.
    • +
  • After enforce sdd: If compliance fails, update the plan and re-run enforcement.
    • +
  • After repro: If validation fails, fix issues and re-run the chain from the appropriate step.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Complete specification extracted from legacy code
    • +
  • Plan bundle with features, stories, and acceptance criteria
    • +
  • SDD-compliant codebase
    • +
  • Validated contracts and tests
    • +
+ +

Related Guides:

+ + + +
+ +

2. Greenfield Planning Chain

+ +

Goal: Plan new features from scratch using Spec-Driven Development principles.

+ +

When to use: You’re starting a new feature or project and want to plan it properly before coding.

+ +

Command Sequence:

+ +
# Step 1: Initialize a new plan bundle
+specfact plan init --bundle new-feature --interactive
+
+# Step 2: Add features to the plan
+specfact plan add-feature --bundle new-feature --name "User Authentication"
+
+# Step 3: Add user stories to features
+specfact plan add-story --bundle new-feature --feature <feature-id> --story "As a user, I want to log in"
+
+# Step 4: Review the plan for completeness
+specfact plan review --bundle new-feature
+
+# Step 5: Harden the plan (finalize before implementation)
+specfact plan harden --bundle new-feature
+
+# Step 6: Generate contracts from the plan
+specfact generate contracts --bundle new-feature
+
+# Step 7: Enforce SDD compliance
+specfact enforce sdd --bundle new-feature
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[New Feature Idea] -->|plan init| B[Initialize Plan]
+    B -->|plan add-feature| C[Add Features]
+    C -->|plan add-story| D[Add User Stories]
+    D -->|plan review| E[Review Plan]
+    E -->|Issues| D
+    E -->|Complete| F[plan harden]
+    F -->|generate contracts| G[Generate Contracts]
+    G -->|enforce sdd| H[SDD-Compliant Plan]
+
+ +

Decision Points:

+ +
    +
  • After plan init: Choose interactive mode to get guided prompts, or use flags for automation.
    • +
  • After plan add-feature: Add multiple features before adding stories, or add stories immediately.
    • +
  • After plan review: If ambiguities are found, add more details or stories before hardening.
    • +
  • After plan harden: Once hardened, the plan is locked. Generate contracts before enforcement.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Complete plan bundle with features and stories
    • +
  • Generated contracts ready for implementation
    • +
  • SDD-compliant plan ready for development
    • +
+ +

Related Guides:

+ + + +
+ +

3. External Tool Integration Chain

+ +

Goal: Integrate SpecFact with external tools like Spec-Kit, OpenSpec, Linear, or Jira.

+ +

When to use: You want to sync specifications between SpecFact and other tools, or import from external sources.

+ +

Command Sequence:

+ +
# Step 1: Import from external tool via bridge adapter
+specfact import from-bridge --repo . --adapter speckit --write
+
+# Step 2: Review the imported plan
+specfact plan review --bundle <bundle-name>
+
+# Step 3: Set up bidirectional sync (optional)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --bidirectional --watch
+
+# Step 4: Enforce SDD compliance
+specfact enforce sdd --bundle <bundle-name>
+
+ +

Workflow Diagram:

+ +
graph LR
+    A[External Tool] -->|import from-bridge| B[SpecFact Plan]
+    B -->|plan review| C[Review Import]
+    C -->|sync bridge| D[Bidirectional Sync]
+    D -->|enforce sdd| E[SDD-Compliant]
+    E -.->|watch mode| D
+
+ +

Decision Points:

+ +
    +
  • After import from-bridge: Review the imported plan. If it needs refinement, use plan update-feature.
    • +
  • Bidirectional sync: Use --watch mode for continuous synchronization, or run sync manually as needed.
    • +
  • Adapter selection: Choose the appropriate adapter (speckit, openspec, github, linear, jira).
    • +
+ +

Expected Outcomes:

+ +
    +
  • Specifications imported from external tool
    • +
  • Bidirectional synchronization (if enabled)
    • +
  • SDD-compliant integrated workflow
    • +
+ +

Related Guides:

+ + + +
+ +

4. API Contract Development Chain

+ +

Goal: Develop, validate, and test API contracts using SpecFact and Specmatic integration.

+ +

When to use: You’re developing REST APIs and want to ensure contract compliance and backward compatibility.

+ +

Command Sequence:

+ +
# Step 1: Validate API specification
+specfact spec validate --spec openapi.yaml
+
+# Step 2: Check backward compatibility
+specfact spec backward-compat --spec openapi.yaml --previous-spec openapi-v1.yaml
+
+# Step 3: Generate tests from specification
+specfact spec generate-tests --spec openapi.yaml --output tests/
+
+# Step 4: Generate mock server (optional)
+specfact spec mock --spec openapi.yaml --port 8080
+
+# Step 5: Verify contracts at runtime
+specfact contract verify --bundle api-bundle
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[API Specification] -->|spec validate| B[Validate Spec]
+    B -->|spec backward-compat| C[Check Compatibility]
+    C -->|spec generate-tests| D[Generate Tests]
+    C -->|spec mock| E[Mock Server]
+    D -->|contract verify| F[Verified Contracts]
+    E --> F
+
+ +

Decision Points:

+ +
    +
  • After spec validate: If validation fails, fix the specification before proceeding.
    • +
  • Backward compatibility: Check compatibility before releasing new API versions.
    • +
  • Mock server: Use mock server for testing clients before implementation is complete.
    • +
  • Contract verification: Run verification in CI/CD to catch contract violations early.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Validated API specification
    • +
  • Backward compatibility verified
    • +
  • Generated tests from specification
    • +
  • Runtime contract verification
    • +
+ +

Related Guides:

+ + + +
+ +

5. Plan Promotion & Release Chain

+ +

Goal: Promote a plan through stages (draft → review → approved → released) and manage versions.

+ +

When to use: You have a completed plan and want to promote it through your organization’s approval process.

+ +

Command Sequence:

+ +
# Step 1: Review the plan before promotion
+specfact plan review --bundle <bundle-name>
+
+# Step 2: Enforce SDD compliance
+specfact enforce sdd --bundle <bundle-name>
+
+# Step 3: Promote the plan to next stage
+specfact plan promote --bundle <bundle-name> --stage <next-stage>
+
+# Step 4: Bump version when releasing
+specfact project version bump --bundle <bundle-name> --type <major|minor|patch>
+
+ +

Workflow Diagram:

+ +
graph LR
+    A[Draft Plan] -->|plan review| B[Review]
+    B -->|enforce sdd| C[SDD Compliant]
+    C -->|plan promote| D[Next Stage]
+    D -->|version bump| E[Released]
+
+ +

Decision Points:

+ +
    +
  • After plan review: If issues are found, fix them before promotion.
    • +
  • SDD enforcement: Ensure compliance before promoting to production stages.
    • +
  • Version bumping: Choose appropriate version type (major/minor/patch) based on changes.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Plan promoted through approval stages
    • +
  • Version bumped appropriately
    • +
  • Release-ready plan bundle
    • +
+ +

Related Guides:

+ + + +
+ +

6. Code-to-Plan Comparison Chain

+ +

Goal: Detect and resolve drift between code and specifications.

+ +

When to use: You want to ensure your code matches your specifications, or detect when code has diverged.

+ +

Command Sequence:

+ +
# Step 1: Import current code state
+specfact import from-code --bundle current-state --repo .
+
+# Step 2: Compare code against plan
+specfact plan compare --bundle <plan-bundle> --code-vs-plan
+
+# Step 3: Detect drift
+specfact drift detect --bundle <bundle-name>
+
+# Step 4: Sync repository (if drift found)
+specfact sync repository --bundle <bundle-name> --direction <code-to-plan|plan-to-code>
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Code Repository] -->|import from-code| B[Current State]
+    B -->|plan compare| C[Compare]
+    C -->|drift detect| D[Drift Found?]
+    D -->|Yes| E[sync repository]
+    D -->|No| F[In Sync]
+    E --> F
+
+ +

Decision Points:

+ +
    +
  • After plan compare: Review the comparison results to understand differences.
    • +
  • Drift detection: If drift is detected, decide whether to sync code-to-plan or plan-to-code.
    • +
  • Sync direction: Choose code-to-plan to update plan from code, or plan-to-code to update code from plan.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Code and plan synchronized
    • +
  • Drift detected and resolved
    • +
  • Consistent state between code and specifications
    • +
+ +

Related Guides:

+ + + +
+ +

7. AI-Assisted Code Enhancement Chain (Emerging)

+ +

Goal: Use AI IDE integration to enhance code with contracts and validate them.

+ +

When to use: You want to add contracts to existing code using AI assistance in your IDE.

+ +

Command Sequence:

+ +
# Step 1: Generate contract prompt for AI IDE
+specfact generate contracts-prompt --bundle <bundle-name> --feature <feature-id>
+
+# Step 2: [In AI IDE] Use slash command to apply contracts
+# /specfact-cli/contracts-apply <prompt-file>
+
+# Step 3: Check contract coverage
+specfact contract coverage --bundle <bundle-name>
+
+# Step 4: Run validation
+specfact repro --verbose
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Code Without Contracts] -->|generate contracts-prompt| B[AI Prompt]
+    B -->|AI IDE| C[Apply Contracts]
+    C -->|contract coverage| D[Check Coverage]
+    D -->|repro| E[Validated Code]
+
+ +

Decision Points:

+ +
    +
  • After generating prompt: Review the prompt in your AI IDE before applying.
    • +
  • Contract coverage: Ensure coverage meets your requirements before validation.
    • +
  • Validation: If validation fails, review and fix contracts, then re-run.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Contracts added to code via AI assistance
    • +
  • Contract coverage verified
    • +
  • Validated enhanced code
    • +
+ +

Related Guides:

+ + + +
+ +

8. Test Generation from Specifications Chain (Emerging)

+ +

Goal: Generate tests from specifications using AI assistance.

+ +

When to use: You have specifications and want to generate comprehensive tests automatically.

+ +

Command Sequence:

+ +
# Step 1: Generate test prompt for AI IDE
+specfact generate test-prompt --bundle <bundle-name> --feature <feature-id>
+
+# Step 2: [In AI IDE] Use slash command to generate tests
+# /specfact-cli/test-generate <prompt-file>
+
+# Step 3: Generate tests from specification
+specfact spec generate-tests --spec <spec-file> --output tests/
+
+# Step 4: Run tests
+pytest tests/
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Specification] -->|generate test-prompt| B[AI Prompt]
+    B -->|AI IDE| C[Generate Tests]
+    A -->|spec generate-tests| D[Spec-Based Tests]
+    C --> E[Test Suite]
+    D --> E
+    E -->|pytest| F[Test Results]
+
+ +

Decision Points:

+ +
    +
  • Test generation method: Use AI IDE for custom tests, or spec generate-tests for specification-based tests.
    • +
  • Test coverage: Review generated tests to ensure they cover all scenarios.
    • +
  • Test execution: Run tests in CI/CD for continuous validation.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Comprehensive test suite generated
    • +
  • Tests validated and passing
    • +
  • Specification coverage verified
    • +
+ +

Related Guides:

+ + + +
+ +

9. Gap Discovery & Fixing Chain (Emerging)

+ +

Goal: Discover gaps in specifications and fix them using AI assistance.

+ +

When to use: You want to find missing contracts or specifications and add them systematically.

+ +

Command Sequence:

+ +
# Step 1: Run validation with verbose output
+specfact repro --verbose
+
+# Step 2: Generate fix prompt for discovered gaps
+specfact generate fix-prompt --bundle <bundle-name> --gap <gap-id>
+
+# Step 3: [In AI IDE] Use slash command to apply fixes
+# /specfact-cli/fix-apply <prompt-file>
+
+# Step 4: Enforce SDD compliance
+specfact enforce sdd --bundle <bundle-name>
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Codebase] -->|repro --verbose| B[Discover Gaps]
+    B -->|generate fix-prompt| C[AI Fix Prompt]
+    C -->|AI IDE| D[Apply Fixes]
+    D -->|enforce sdd| E[SDD Compliant]
+    E -->|repro| B
+
+ +

Decision Points:

+ +
    +
  • After repro --verbose: Review discovered gaps and prioritize fixes.
    • +
  • Fix application: Review AI-suggested fixes before applying.
    • +
  • SDD enforcement: Ensure compliance after fixes are applied.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Gaps discovered and documented
    • +
  • Fixes applied via AI assistance
    • +
  • SDD-compliant codebase
    • +
+ +

Related Guides:

+ + + +
+ +

10. SDD Constitution Management Chain

+ +

Goal: Manage Spec-Driven Development (SDD) constitutions for Spec-Kit compatibility.

+ +

When to use: You’re working with Spec-Kit format and need to bootstrap, enrich, or validate constitutions.

+ +

Command Sequence:

+ +
# Step 1: Bootstrap constitution from repository
+specfact sdd constitution bootstrap --repo .
+
+# Step 2: Enrich constitution with repository context
+specfact sdd constitution enrich --repo .
+
+# Step 3: Validate constitution completeness
+specfact sdd constitution validate
+
+# Step 4: List SDD manifests
+specfact sdd list
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Repository] -->|sdd constitution bootstrap| B[Bootstrap Constitution]
+    B -->|sdd constitution enrich| C[Enrich Constitution]
+    C -->|sdd constitution validate| D[Validate Constitution]
+    D -->|sdd list| E[SDD Manifests]
+    D -->|Issues Found| C
+
+ +

Decision Points:

+ +
    +
  • Bootstrap vs Enrich: Use bootstrap for new constitutions, enrich for existing ones.
    • +
  • Validation: Run validation after bootstrap/enrich to ensure completeness.
    • +
  • Spec-Kit Compatibility: These commands are for Spec-Kit format only. SpecFact uses modular project bundles internally.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Complete SDD constitution for Spec-Kit compatibility
    • +
  • Validated constitution ready for use
    • +
  • List of SDD manifests in repository
    • +
+ +

Related Guides:

+ + + +
+ +

Orphaned Commands Integration

+ +

The following commands are now integrated into documented workflows:

+ +

plan update-idea

+ +

Integrated into: Greenfield Planning Chain

+ +

When to use: Update feature ideas during planning phase.

+ +

Workflow: Use as part of plan update-feature workflow in Greenfield Planning.

+ +
+ +

project export/import/lock/unlock

+ +

Integrated into: Team Collaboration Workflow and Plan Promotion & Release Chain

+ +

When to use: Team collaboration with persona-based workflows.

+ +

Workflow: See Team Collaboration Workflow for complete workflow.

+ +
+ +

migrate * Commands

+ +

Integrated into: Migration Guide

+ +

When to use: Migrating between versions or from other tools.

+ +

Workflow: See Migration Guide for decision tree and workflows.

+ +
+ +

sdd list

+ +

Integrated into: SDD Constitution Management Chain

+ +

When to use: List SDD manifests in repository.

+ +

Workflow: Use after constitution management to verify manifests.

+ +
+ +

contract verify

+ +

Integrated into: API Contract Development Chain

+ +

When to use: Verify contracts at runtime.

+ +

Workflow: Use as final step in API Contract Development Chain.

+ +
+ +

See Also

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/guides/contract-testing-workflow.md b/_site_local/guides/contract-testing-workflow.md new file mode 100644 index 0000000..471d29a --- /dev/null +++ b/_site_local/guides/contract-testing-workflow.md @@ -0,0 +1,269 @@ +# Contract Testing Workflow - Simple Guide for Developers + +## Quick Start: Verify Your Contract + +The easiest way to verify your OpenAPI contract works is with a single command: + +```bash +# Verify a specific contract +specfact contract verify --bundle my-api --feature FEATURE-001 + +# Verify all contracts in a bundle +specfact contract verify --bundle my-api +``` + +**What this does:** + +1. ✅ Validates your contract schema +2. ✅ Generates examples from the contract +3. ✅ Starts a mock server +4. ✅ Tests connectivity + +**That's it!** Your contract is verified and ready to use. The mock server keeps running so you can test your client code. + +## What You Can Do Without a Real API + +### ✅ Contract Verification (No API Needed) + +Use `contract verify` to ensure your contract is correct: + +```bash +specfact contract verify --bundle my-api --feature FEATURE-001 +``` + +**Output:** + +``` +``` + +Step 1: Validating contracts... +✓ FEATURE-001: Valid (13 endpoints) + +Step 2: Generating examples... +✓ FEATURE-001: Examples generated + +Step 3: Starting mock server for FEATURE-001... +✓ Mock server started at + +Step 4: Testing connectivity... +✓ Health check passed: UP + +✓ Contract verification complete! + +Summary: + • Contracts validated: 1 + • Examples generated: 1 + • Mock server: + +``` + +### ✅ Mock Server for Development + +Start a mock server that generates responses from your contract: + +```bash +# Start mock server with examples +specfact contract serve --bundle my-api --feature FEATURE-001 --examples + +# Or use the verify command (starts mock server automatically) +specfact contract verify --bundle my-api --feature FEATURE-001 +``` + +**Use cases:** + +- Frontend development without backend +- Client library testing +- Integration testing (test your client against the contract) + +### ✅ Contract Validation + +Validate that your contract schema is correct: + +```bash +# Validate a specific contract +specfact contract validate --bundle my-api --feature FEATURE-001 + +# Check coverage across all contracts +specfact contract coverage --bundle my-api +``` + +## Complete Workflow Examples + +### Example 1: New Contract Development + +```bash +# 1. Create a new contract +specfact contract init --bundle my-api --feature FEATURE-001 + +# 2. Edit the contract file +# Edit: .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml + +# 3. Verify everything works +specfact contract verify --bundle my-api --feature FEATURE-001 + +# 4. Test your client code against the mock server +curl http://localhost:9000/api/endpoint +``` + +### Example 2: CI/CD Pipeline + +```bash +# Validate contracts without starting mock server +specfact contract verify --bundle my-api --skip-mock --no-interactive + +# Or just validate +specfact contract validate --bundle my-api --no-interactive +``` + +### Example 3: Multiple Contracts + +```bash +# Verify all contracts in a bundle +specfact contract verify --bundle my-api + +# Check coverage +specfact contract coverage --bundle my-api +``` + +## What Requires a Real API + +### ❌ Contract Testing Against Real Implementation + +The `specmatic test` command requires a **real API implementation**: + +```bash +# This REQUIRES a running API +specmatic test \ + --spec .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml \ + --host http://localhost:8000 +``` + +**When to use:** + +- After implementing your API +- To verify your implementation matches the contract +- In integration tests + +**Workflow:** + +```bash +# 1. Generate test files +specfact contract test --bundle my-api --feature FEATURE-001 + +# 2. Start your real API +python -m uvicorn main:app --port 8000 + +# 3. Run contract tests +specmatic test \ + --spec .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml \ + --host http://localhost:8000 +``` + +## Command Reference + +### `contract verify` - All-in-One Verification + +The simplest way to verify your contract: + +```bash +specfact contract verify [OPTIONS] + +Options: + --bundle TEXT Project bundle name + --feature TEXT Feature key (optional - verifies all if not specified) + --port INTEGER Port for mock server (default: 9000) + --skip-mock Skip mock server (only validate) + --no-interactive Non-interactive mode (CI/CD) +``` + +**What it does:** + +1. Validates contract schema +2. Generates examples +3. Starts mock server (unless `--skip-mock`) +4. Tests connectivity + +### `contract validate` - Schema Validation + +```bash +specfact contract validate --bundle my-api --feature FEATURE-001 +``` + +Validates the OpenAPI schema structure. + +### `contract serve` - Mock Server + +```bash +specfact contract serve --bundle my-api --feature FEATURE-001 --examples +``` + +Starts a mock server that generates responses from your contract. + +### `contract coverage` - Coverage Report + +```bash +specfact contract coverage --bundle my-api +``` + +Shows contract coverage metrics across all features. + +### `contract test` - Generate Tests + +```bash +specfact contract test --bundle my-api --feature FEATURE-001 +``` + +Generates test files that can be run against a real API. + +## Key Insights + +| Task | Requires Real API? | Command | +|------|-------------------|---------| +| **Contract Verification** | ❌ No | `contract verify` | +| **Schema Validation** | ❌ No | `contract validate` | +| **Mock Server** | ❌ No | `contract serve` | +| **Example Generation** | ❌ No | `contract verify` (automatic) | +| **Contract Testing** | ✅ Yes | `specmatic test` (after `contract test`) | + +## Troubleshooting + +### Mock Server Won't Start + +```bash +# Check if Specmatic is installed +npx specmatic --version + +# Install if needed +npm install -g @specmatic/specmatic +``` + +### Contract Validation Fails + +```bash +# Check contract file syntax +cat .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml + +# Validate manually +specfact contract validate --bundle my-api --feature FEATURE-001 +``` + +### Examples Not Generated + +Examples are generated automatically from your OpenAPI schema. If generation fails: + +- Check that your schema has proper request/response definitions +- Ensure data types are properly defined +- Run `contract verify` to see detailed error messages + +## Best Practices + +1. **Start with `contract verify`** - It does everything you need +2. **Use mock servers for development** - No need to wait for backend +3. **Validate in CI/CD** - Use `--skip-mock --no-interactive` for fast validation +4. **Test against real API** - Use `specmatic test` after implementation + +## Next Steps + +- Read the [API Reference](../reference/commands.md) for detailed command options +- Check [Architecture Documentation](../reference/architecture.md) for bundle management +- See [Agile/Scrum Workflows](../guides/agile-scrum-workflows.md) for team collaboration diff --git a/_site_local/guides/devops-adapter-integration.md b/_site_local/guides/devops-adapter-integration.md new file mode 100644 index 0000000..387d6e2 --- /dev/null +++ b/_site_local/guides/devops-adapter-integration.md @@ -0,0 +1,605 @@ +# DevOps Adapter Integration Guide + +This guide explains how to integrate SpecFact CLI with DevOps backlog tools (GitHub Issues, Azure DevOps, Linear, Jira) to sync OpenSpec change proposals and track implementation progress through automated comment annotations. + +## Overview + +SpecFact CLI supports exporting OpenSpec change proposals to DevOps tools and tracking implementation progress: + +- **Issue Creation**: Export OpenSpec change proposals as GitHub Issues (or other DevOps backlog items) +- **Progress Tracking**: Automatically detect code changes and add progress comments to issues +- **Content Sanitization**: Protect internal information when syncing to public repositories +- **Separate Repository Support**: Handle cases where OpenSpec proposals and source code are in different repositories + +## Supported Adapters + +Currently supported DevOps adapters: + +- **GitHub Issues** (`--adapter github`) - Full support for issue creation and progress comments +- **Azure DevOps** (`--adapter ado`) - Planned +- **Linear** (`--adapter linear`) - Planned +- **Jira** (`--adapter jira`) - Planned + +This guide focuses on GitHub Issues integration. Other adapters will follow similar patterns. + +--- + +## Quick Start + +### 1. Create Change Proposal + +Create an OpenSpec change proposal in your OpenSpec repository: + +```bash +# Structure: openspec/changes//proposal.md +mkdir -p openspec/changes/add-feature-x +cat > openspec/changes/add-feature-x/proposal.md << 'EOF' +# Add Feature X + +## Summary + +Add new feature X to improve user experience. + +## Status + +- status: proposed + +## Implementation Plan + +1. Design API endpoints +2. Implement backend logic +3. Add frontend components +4. Write tests +EOF +``` + +### 2. Export to GitHub Issues + +Export the change proposal to create a GitHub issue: + +```bash +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo +``` + +### 3. Track Code Changes + +As you implement the feature, track progress automatically: + +```bash +# Make commits with change ID in commit message +git commit -m "feat: implement add-feature-x - initial API design" + +# Track progress (detects commits and adds comments) +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --track-code-changes \ + --repo /path/to/openspec-repo \ + --code-repo /path/to/source-code-repo # If different from OpenSpec repo +``` + +--- + +## GitHub Issues Integration + +### Prerequisites + +**For Issue Creation:** + +- OpenSpec change proposals in `openspec/changes//proposal.md` +- GitHub token (via `GITHUB_TOKEN` env var, `gh auth token`, or `--github-token`) +- Repository access permissions (read for proposals, write for issues) + +**For Code Change Tracking:** + +- Issues must already exist (created via previous sync) +- Git repository with commits mentioning the change proposal ID in commit messages +- If OpenSpec and source code are in separate repositories, use `--code-repo` parameter + +### Authentication + +SpecFact CLI supports multiple authentication methods: + +**Option 1: GitHub CLI (Recommended)** + +```bash +# Uses gh auth token automatically +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --use-gh-cli +``` + +**Option 2: Environment Variable** + +```bash +export GITHUB_TOKEN=ghp_your_token_here +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo +``` + +**Option 3: Command Line Flag** + +```bash +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --github-token ghp_your_token_here +``` + +### Basic Usage + +#### Create Issues from Change Proposals + +```bash +# Export all active proposals to GitHub Issues +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo +``` + +#### Track Code Changes + +```bash +# Detect code changes and add progress comments +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --track-code-changes \ + --repo /path/to/openspec-repo +``` + +#### Sync Specific Proposals + +```bash +# Export only specific change proposals +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --change-ids add-feature-x,update-api \ + --repo /path/to/openspec-repo +``` + +--- + +## Separate OpenSpec and Source Code Repositories + +When your OpenSpec change proposals are in a different repository than your source code: + +### Architecture + +- **OpenSpec Repository** (`--repo`): Contains change proposals in `openspec/changes/` directory +- **Source Code Repository** (`--code-repo`): Contains actual implementation commits + +### Example Setup + +```bash +# OpenSpec proposals in specfact-cli-internal +# Source code in specfact-cli + +# Step 1: Create issue from proposal +specfact sync bridge --adapter github --mode export-only \ + --repo-owner nold-ai \ + --repo-name specfact-cli-internal \ + --repo /path/to/specfact-cli-internal + +# Step 2: Track code changes from source code repo +specfact sync bridge --adapter github --mode export-only \ + --repo-owner nold-ai \ + --repo-name specfact-cli-internal \ + --track-code-changes \ + --repo /path/to/specfact-cli-internal \ + --code-repo /path/to/specfact-cli +``` + +### Why Use `--code-repo`? + +- **OpenSpec repository** (`--repo`): Contains change proposals and tracks issue metadata +- **Source code repository** (`--code-repo`): Contains actual implementation commits that reference the change proposal ID + +If both are in the same repository, you can omit `--code-repo` and it will use `--repo` for both purposes. + +--- + +## Content Sanitization + +When exporting to public repositories, use content sanitization to protect internal information: + +### What Gets Sanitized + +**Removed:** + +- Competitive analysis sections +- Market positioning statements +- Implementation details (file-by-file changes) +- Effort estimates and timelines +- Technical architecture details +- Internal strategy sections + +**Preserved:** + +- High-level feature descriptions +- User-facing value propositions +- Acceptance criteria +- External documentation links +- Use cases and examples + +### Usage + +```bash +# Public repository: sanitize content +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name public-repo \ + --sanitize \ + --target-repo your-org/public-repo \ + --repo /path/to/openspec-repo + +# Internal repository: use full content +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name internal-repo \ + --no-sanitize \ + --target-repo your-org/internal-repo \ + --repo /path/to/openspec-repo +``` + +### Auto-Detection + +SpecFact CLI automatically detects when to sanitize: + +- **Different repos** (code repo ≠ planning repo): Sanitization recommended (default: yes) +- **Same repo** (code repo = planning repo): Sanitization optional (default: no) + +You can override with `--sanitize` or `--no-sanitize` flags. + +--- + +## Code Change Tracking + +### How It Works + +When `--track-code-changes` is enabled: + +1. **Repository Selection**: Uses `--code-repo` if provided, otherwise uses `--repo` +2. **Git Commit Detection**: Searches git log for commits mentioning the change proposal ID +3. **File Change Tracking**: Extracts files modified in detected commits +4. **Progress Comment Generation**: Formats comment with commit details and file changes +5. **Duplicate Prevention**: Checks against existing comments to avoid duplicates +6. **Source Tracking Update**: Updates `proposal.md` with progress metadata + +### Commit Message Format + +Include the change proposal ID in your commit messages: + +```bash +# Good: Change ID clearly mentioned +git commit -m "feat: implement add-feature-x - initial API design" +git commit -m "fix: add-feature-x - resolve authentication issue" +git commit -m "docs: add-feature-x - update API documentation" + +# Also works: Change ID anywhere in message +git commit -m "Implement new feature + +- Add API endpoints +- Update database schema +- Related to add-feature-x" +``` + +### Progress Comment Format + +Progress comments include: + +- **Commit details**: Hash, message, author, date +- **Files changed**: Up to 10 files listed, then "and X more file(s)" +- **Detection timestamp**: When the change was detected + +**Example Comment:** + +``` +📊 **Code Change Detected** + +**Commit**: `364c8cfb` - feat: implement add-feature-x - initial API design +**Author**: @username +**Date**: 2025-12-30 +**Files Changed**: +- src/api/endpoints.py +- src/models/feature.py +- tests/test_feature.py +- and 2 more file(s) + +*Detected at: 2025-12-30T10:00:00Z* +``` + +### Progress Comment Sanitization + +When `--sanitize` is enabled, progress comments are sanitized: + +- **Commit messages**: Internal keywords removed, long messages truncated +- **File paths**: Replaced with file type counts (e.g., "3 py file(s)") +- **Author emails**: Removed, only username shown +- **Timestamps**: Date only (no time component) + +--- + +## Integration Workflow + +### Initial Setup (One-Time) + +1. **Create Change Proposal**: + + ```bash + mkdir -p openspec/changes/add-feature-x + # Edit openspec/changes/add-feature-x/proposal.md + ``` + +2. **Export to GitHub**: + + ```bash + specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo + ``` + +3. **Verify Issue Created**: + + ```bash + gh issue list --repo your-org/your-repo + ``` + +### Development Workflow (Ongoing) + +1. **Make Commits** with change ID in commit message: + + ```bash + git commit -m "feat: implement add-feature-x - initial API design" + ``` + +2. **Track Progress**: + + ```bash + specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --track-code-changes \ + --repo /path/to/openspec-repo \ + --code-repo /path/to/source-code-repo + ``` + +3. **Verify Comments Added**: + + ```bash + gh issue view --repo your-org/your-repo --json comments + ``` + +### Manual Progress Updates + +Add manual progress comments without code change detection: + +```bash +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --add-progress-comment \ + --repo /path/to/openspec-repo +``` + +--- + +## Advanced Features + +### Update Existing Issues + +Update issue bodies when proposal content changes: + +```bash +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --update-existing \ + --repo /path/to/openspec-repo +``` + +**Note**: Uses content hash to detect changes. Default: `False` for safety. + +### Proposal Filtering + +Proposals are filtered based on target repository type: + +**Public Repositories** (with `--sanitize`): + +- Only syncs proposals with status `"applied"` (archived/completed changes) +- Filters out `"proposed"`, `"in-progress"`, `"deprecated"`, or `"discarded"` + +**Internal Repositories** (with `--no-sanitize`): + +- Syncs all active proposals regardless of status + +### Duplicate Prevention + +Progress comments are deduplicated using SHA-256 hash: + +- First run: Comment added +- Second run: Comment skipped (duplicate detected) +- New commits: New comment added + +--- + +## Verification + +### Check Issue Creation + +```bash +# List issues +gh issue list --repo your-org/your-repo + +# View specific issue +gh issue view --repo your-org/your-repo +``` + +### Check Progress Comments + +```bash +# View latest comment +gh issue view --repo your-org/your-repo --json comments --jq '.comments[-1].body' + +# View all comments +gh issue view --repo your-org/your-repo --json comments +``` + +### Check Source Tracking + +Verify `openspec/changes//proposal.md` was updated: + +```markdown +## Source Tracking + +- **GitHub Issue**: #123 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + +``` + +--- + +## Troubleshooting + +### No Commits Detected + +**Problem**: Code changes not detected even though commits exist. + +**Solutions**: + +- Ensure commit messages include the change proposal ID (e.g., "add-feature-x") +- Verify `--code-repo` points to the correct source code repository +- Check that `last_code_change_detected` timestamp isn't in the future (reset if needed) + +### Wrong Repository + +**Problem**: Commits detected from wrong repository. + +**Solutions**: + +- Verify `--code-repo` parameter points to source code repository +- Check that OpenSpec repository (`--repo`) is correct +- Ensure both repositories are valid Git repositories + +### No Comments Added + +**Problem**: Progress comments not added to issues. + +**Solutions**: + +- Verify issues exist (create them first without `--track-code-changes`) +- Check GitHub token has write permissions +- Verify change proposal ID matches commit messages +- Check for duplicate comments (may be skipped) + +### Sanitization Issues + +**Problem**: Too much or too little content sanitized. + +**Solutions**: + +- Use `--sanitize` for public repos, `--no-sanitize` for internal repos +- Check auto-detection logic (different repos → sanitize, same repo → no sanitization) +- Review proposal content to ensure sensitive information is properly marked + +### Authentication Errors + +**Problem**: GitHub authentication fails. + +**Solutions**: + +- Verify GitHub token is valid: `gh auth status` +- Check token permissions (read/write access) +- Try using `--use-gh-cli` flag +- Verify `GITHUB_TOKEN` environment variable is set correctly + +--- + +## Best Practices + +### Commit Messages + +- Always include change proposal ID in commit messages +- Use descriptive commit messages that explain what was changed +- Follow conventional commit format: `type: change-id - description` + +### Repository Organization + +- Keep OpenSpec proposals in a dedicated repository for better organization +- Use `--code-repo` when OpenSpec and source code are separate +- Document repository structure in your team's documentation + +### Content Sanitization + +- Always sanitize when exporting to public repositories +- Review sanitized content before syncing to ensure nothing sensitive leaks +- Use `--no-sanitize` only for internal repositories + +### Progress Tracking + +- Run `--track-code-changes` regularly (e.g., after each commit or daily) +- Use manual progress comments for non-code updates (meetings, decisions, etc.) +- Verify comments are added correctly after each sync + +### Issue Management + +- Create issues first, then track code changes +- Use `--update-existing` sparingly (only when proposal content changes significantly) +- Monitor issue comments to ensure progress tracking is working + +--- + +## See Also + +### Related Guides + +- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations + +- [Command Chains Reference](command-chains.md) - Complete workflows including [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain) +- [Common Tasks Index](common-tasks.md) - Quick reference for DevOps integration tasks +- [OpenSpec Journey](openspec-journey.md) - OpenSpec integration with DevOps export +- [Agile/Scrum Workflows](agile-scrum-workflows.md) - Persona-based backlog management + +### Related Commands + +- [Command Reference - Sync Bridge](../reference/commands.md#sync-bridge) - Complete `sync bridge` command documentation +- [Command Reference - DevOps Adapters](../reference/commands.md#sync-bridge) - Adapter configuration + +### Related Examples + +- [DevOps Integration Examples](../examples/) - Real-world integration examples + +### Architecture & Troubleshooting + +- [Architecture](../reference/architecture.md) - System architecture and design +- [Troubleshooting](troubleshooting.md) - Common issues and solutions + +--- + +## Future Adapters + +Additional DevOps adapters are planned: + +- **Azure DevOps** (`--adapter ado`) - Work items and progress tracking +- **Linear** (`--adapter linear`) - Issues and progress updates +- **Jira** (`--adapter jira`) - Issues, epics, and sprint tracking + +These will follow similar patterns to GitHub Issues integration. Check the [Commands Reference](../reference/commands.md) for the latest adapter support. + +--- + +**Need Help?** + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_local/guides/dual-stack-enrichment.md b/_site_local/guides/dual-stack-enrichment.md new file mode 100644 index 0000000..be52231 --- /dev/null +++ b/_site_local/guides/dual-stack-enrichment.md @@ -0,0 +1,344 @@ +# Dual-Stack Enrichment Pattern + +**Status**: ✅ **AVAILABLE** (v0.13.0+) +**Last Updated**: 2025-12-23 +**Version**: v0.20.4 (enrichment parser improvements: story merging, format validation) + +--- + +## Overview + +The **Dual-Stack Enrichment Pattern** is SpecFact's approach to combining CLI automation with AI IDE (LLM) capabilities. It ensures that all artifacts are CLI-generated and validated, while allowing LLMs to add semantic understanding and enhancements. + +## Core Principle + +**ALWAYS use the SpecFact CLI as the primary tool**. LLM enrichment is a **secondary layer** that enhances CLI output with semantic understanding, but **never replaces CLI artifact creation**. + +## CLI vs LLM Capabilities + +### CLI-Only Operations (CI/CD Mode - No LLM Required) + +The CLI can perform these operations **without LLM**: + +- ✅ Tool execution (ruff, pylint, basedpyright, mypy, semgrep, specmatic) +- ✅ Bundle management (create, load, save, validate structure) +- ✅ Metadata management (timestamps, hashes, telemetry) +- ✅ Planning operations (init, add-feature, add-story, update-idea, update-feature) +- ✅ AST/Semgrep-based analysis (code structure, patterns, relationships) +- ✅ Specmatic validation (OpenAPI/AsyncAPI contract validation) +- ✅ Format validation (YAML/JSON schema compliance) +- ✅ Source tracking and drift detection + +**CRITICAL LIMITATIONS**: + +- ❌ **CANNOT generate code** - No LLM available in CLI-only mode +- ❌ **CANNOT do reasoning** - No semantic understanding without LLM + +### LLM-Required Operations (AI IDE Mode - Via Slash Prompts) + +These operations **require LLM** and are only available via AI IDE slash prompts: + +- ✅ Code generation (requires LLM reasoning) +- ✅ Code enhancement (contracts, refactoring, improvements) +- ✅ Semantic understanding (business logic, context, priorities) +- ✅ Plan enrichment (missing features, confidence adjustments, business context) +- ✅ Code reasoning (why decisions were made, trade-offs, constraints) + +**Access**: Only available via AI IDE slash prompts (Cursor, CoPilot, etc.) +**Pattern**: Slash prompt → LLM generates → CLI validates → Apply if valid + +## Three-Phase Workflow + +When working with AI IDE slash prompts, follow this three-phase workflow: + +### Phase 1: CLI Grounding (REQUIRED) + +```bash +# Execute CLI to get structured output +specfact [options] --no-interactive +``` + +**Capture**: + +- CLI-generated artifacts (plan bundles, reports) +- Metadata (timestamps, confidence scores) +- Telemetry (execution time, file counts) + +### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only) + +**Purpose**: Add semantic understanding to CLI output + +**What to do**: + +- Read CLI-generated artifacts (use file reading tools for display only) +- Research codebase for additional context +- Identify missing features/stories +- Suggest confidence adjustments +- Extract business context +- **CRITICAL**: Generate enrichment report in the exact format specified below (see "Enrichment Report Format" section) + +**What NOT to do**: + +- ❌ Create YAML/JSON artifacts directly +- ❌ Modify CLI artifacts directly (use CLI commands to update) +- ❌ Bypass CLI validation +- ❌ Write to `.specfact/` folder directly (always use CLI) +- ❌ Use direct file manipulation tools for writing (use CLI commands) +- ❌ Deviate from the enrichment report format (will cause parsing failures) + +**Output**: Generate enrichment report (Markdown) saved to `.specfact/projects//reports/enrichment/` (bundle-specific, Phase 8.5) + +**Enrichment Report Format** (REQUIRED for successful parsing): + +The enrichment parser expects a specific Markdown format. Follow this structure exactly: + +```markdown +# [Bundle Name] Enrichment Report + +**Date**: YYYY-MM-DDTHH:MM:SS +**Bundle**: + +--- + +## Missing Features + +1. **Feature Title** (Key: FEATURE-XXX) + - Confidence: 0.85 + - Outcomes: outcome1, outcome2, outcome3 + - Stories: + 1. Story title here + - Acceptance: criterion1, criterion2, criterion3 + 2. Another story title + - Acceptance: criterion1, criterion2 + +2. **Another Feature** (Key: FEATURE-YYY) + - Confidence: 0.80 + - Outcomes: outcome1, outcome2 + - Stories: + 1. Story title + - Acceptance: criterion1, criterion2, criterion3 + +## Confidence Adjustments + +- FEATURE-EXISTING-KEY: 0.90 (reason: improved understanding after code review) + +## Business Context + +- Priority: High priority feature for core functionality +- Constraint: Must support both REST and GraphQL APIs +- Risk: Potential performance issues with large datasets +``` + +**Format Requirements**: + +1. **Section Header**: Must use `## Missing Features` (case-insensitive, but prefer this exact format) +2. **Feature Format**: + - Numbered list: `1. **Feature Title** (Key: FEATURE-XXX)` + - **Bold title** is required (use `**Title**`) + - **Key in parentheses**: `(Key: FEATURE-XXX)` - must be uppercase, alphanumeric with hyphens/underscores + - Fields on separate lines with `-` prefix: + - `- Confidence: 0.85` (float between 0.0-1.0) + - `- Outcomes: comma-separated or line-separated list` + - `- Stories:` (required - each feature must have at least one story) +3. **Stories Format**: + - Numbered list under `Stories:` section: `1. Story title` + - **Indentation**: Stories must be indented (2-4 spaces) under the feature + - **Acceptance Criteria**: `- Acceptance: criterion1, criterion2, criterion3` + - Can be comma-separated on one line + - Or multi-line (each criterion on new line) + - Must start with `- Acceptance:` +4. **Optional Sections**: + - `## Confidence Adjustments`: List existing features with confidence updates + - `## Business Context`: Priorities, constraints, risks (bullet points) +5. **File Naming**: `-.enrichment.md` (e.g., `djangogoat-2025-12-23T23-50-00.enrichment.md`) + +**Example** (working format): + +```markdown +## Missing Features + +1. **User Authentication** (Key: FEATURE-USER-AUTHENTICATION) + - Confidence: 0.85 + - Outcomes: User registration, login, profile management + - Stories: + 1. User can sign up for new account + - Acceptance: sign_up view processes POST requests, creates User automatically, user is logged in after signup, redirects to profile page + 2. User can log in with credentials + - Acceptance: log_in view authenticates username/password, on success user is logged in and redirected, on failure error message is displayed +``` + +**Common Mistakes to Avoid**: + +- ❌ Missing `(Key: FEATURE-XXX)` - parser needs this to identify features +- ❌ Missing `Stories:` section - every feature must have at least one story +- ❌ Stories not indented - parser expects indented numbered lists +- ❌ Missing `- Acceptance:` prefix - acceptance criteria won't be parsed +- ❌ Using bullet points (`-`) instead of numbers (`1.`) for stories +- ❌ Feature title not in bold (`**Title**`) - parser may not extract title correctly + +**Important Notes**: + +- **Stories are merged**: When updating existing features (not creating new ones), stories from the enrichment report are merged into the existing feature. New stories are added, existing stories are preserved. +- **Feature titles updated**: If a feature exists but has an empty title, the enrichment report will update it. +- **Validation**: The enrichment parser validates the format and will fail with clear error messages if the format is incorrect. + +### Phase 3: CLI Artifact Creation (REQUIRED) + +```bash +# Use enrichment to update plan via CLI +specfact import from-code [] --repo --enrichment --no-interactive +``` + +**Result**: Final artifacts are CLI-generated with validated enrichments + +**What happens during enrichment application**: + +- Missing features are added with their stories and acceptance criteria +- Existing features are updated (confidence, outcomes, title if empty) +- Stories are merged into existing features (new stories added, existing preserved) +- Business context is applied to the plan bundle +- All changes are validated and saved via CLI + +## Standard Validation Loop Pattern (For LLM-Generated Code) + +When generating or enhancing code via LLM, **ALWAYS** follow this pattern: + +```text +1. CLI Prompt Generation (Required) + ↓ + CLI generates structured prompt → saved to .specfact/prompts/ + (e.g., `generate contracts-prompt`, future: `generate code-prompt`) + +2. LLM Execution (Required - AI IDE Only) + ↓ + LLM reads prompt → generates enhanced code → writes to TEMPORARY file + (NEVER writes directly to original artifacts) + Pattern: `enhanced_.py` or `generated_.py` + +3. CLI Validation Loop (Required, up to N retries) + ↓ + CLI validates temp file with all relevant tools: + - Syntax validation (py_compile) + - File size check (must be >= original) + - AST structure comparison (preserve functions/classes) + - Contract imports verification + - Code quality checks (ruff, pylint, basedpyright, mypy) + - Test execution (contract-test, pytest) + ↓ + If validation fails: + - CLI provides detailed error feedback + - LLM fixes issues in temp file + - Re-validate (max 3 attempts) + ↓ + If validation succeeds: + - CLI applies changes to original file + - CLI removes temporary file + - CLI updates metadata/telemetry +``` + +**This pattern must be used for**: + +- ✅ Contract enhancement (`generate contracts-prompt` / `contracts-apply`) - Already implemented +- ⏳ Code generation (future: `generate code-prompt` / `code-apply`) - Needs implementation +- ⏳ Plan enrichment (future: `plan enrich-prompt` / `enrich-apply`) - Needs implementation +- ⏳ Any LLM-enhanced artifact modification - Needs implementation + +## Example: Contract Enhancement Workflow + +This is a real example of the validation loop pattern in action: + +### Step 1: Generate Prompt + +```bash +specfact generate contracts-prompt src/auth/login.py --apply beartype,icontract --bundle legacy-api +``` + +**Result**: Prompt saved to `.specfact/projects/legacy-api/prompts/enhance-login-beartype-icontract.md` + +### Step 2: LLM Enhances Code + +1. AI IDE reads the prompt file +2. AI IDE reads the original file (`src/auth/login.py`) +3. AI IDE generates enhanced code with contracts +4. AI IDE writes to temporary file: `enhanced_login.py` +5. **DO NOT modify original file directly** + +### Step 3: Validate and Apply + +```bash +specfact generate contracts-apply enhanced_login.py --original src/auth/login.py +``` + +**Validation includes**: + +- Syntax validation +- File size check +- AST structure comparison +- Contract imports verification +- Code quality checks +- Test execution + +**If validation fails**: + +- Review error messages +- Fix issues in `enhanced_login.py` +- Re-run validation (up to 3 attempts) + +**If validation succeeds**: + +- CLI applies changes to `src/auth/login.py` +- CLI removes `enhanced_login.py` +- CLI updates metadata/telemetry + +## Why This Pattern? + +### Benefits + +- ✅ **Format Consistency**: All artifacts match CLI schema versions +- ✅ **Traceability**: CLI metadata tracks who/what/when +- ✅ **Validation**: CLI ensures schema compliance +- ✅ **Reliability**: Works in both Copilot and CI/CD +- ✅ **No Format Drift**: CLI-generated artifacts always match current schema + +### What Happens If You Don't Follow + +- ❌ Artifacts may not match CLI schema versions +- ❌ Missing metadata and telemetry +- ❌ Format inconsistencies +- ❌ Validation failures +- ❌ Works only in Copilot mode, fails in CI/CD +- ❌ Code generation attempts in CLI-only mode will fail (no LLM available) + +## Rules + +1. **Execute CLI First**: Always run CLI commands before any analysis +2. **Use CLI for Writes**: All write operations must go through CLI +3. **Read for Display Only**: Use file reading tools for display/analysis only +4. **Never Modify .specfact/**: Do not create/modify files in `.specfact/` directly +5. **Never Bypass Validation**: CLI ensures schema compliance and metadata +6. **Code Generation Requires LLM**: Code generation is only possible via AI IDE slash prompts, not CLI-only +7. **Use Validation Loop**: All LLM-generated code must follow the validation loop pattern + +## Available CLI Commands + +- `specfact plan init ` - Initialize project bundle +- `specfact plan select ` - Set active plan (used as default for other commands) +- `specfact import from-code [] --repo ` - Import from codebase (uses active plan if bundle not specified) +- `specfact plan review []` - Review plan (uses active plan if bundle not specified) +- `specfact plan harden []` - Create SDD manifest (uses active plan if bundle not specified) +- `specfact enforce sdd []` - Validate SDD (uses active plan if bundle not specified) +- `specfact generate contracts-prompt --apply ` - Generate contract enhancement prompt +- `specfact generate contracts-apply --original ` - Validate and apply enhanced code +- `specfact sync bridge --adapter --repo ` - Sync with external tools +- See [Command Reference](../reference/commands.md) for full list + +**Note**: Most commands now support active plan fallback. If `--bundle` is not specified, commands automatically use the active plan set via `plan select`. This improves workflow efficiency in AI IDE environments. + +--- + +## Related Documentation + +- **[Architecture Documentation](../reference/architecture.md)** - Enforcement rules and quality gates +- **[Operational Modes](../reference/modes.md)** - CI/CD vs Copilot modes +- **[IDE Integration](ide-integration.md)** - Setting up slash commands +- **[Command Reference](../reference/commands.md)** - Complete command reference diff --git a/_site_local/guides/ide-integration/index.html b/_site_local/guides/ide-integration/index.html new file mode 100644 index 0000000..fa1f3dd --- /dev/null +++ b/_site_local/guides/ide-integration/index.html @@ -0,0 +1,571 @@ + + + + + + + +IDE Integration with SpecFact CLI | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

IDE Integration with SpecFact CLI

+ +

Status: ✅ AVAILABLE (v0.4.2+)
+Last Updated: 2025-11-09

+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

+ +

Terminal Output: The CLI automatically detects embedded terminals (Cursor, VS Code) and CI/CD environments, adapting output formatting automatically. Progress indicators work in all environments - see Troubleshooting for details.

+ +
+ +

Overview

+ +

SpecFact CLI supports IDE integration through prompt templates that work with various AI-assisted IDEs. These templates are copied to IDE-specific locations and automatically registered by the IDE as slash commands.

+ +

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via IDE integrations

+ +

Supported IDEs:

+ +
    +
  • ✅ Cursor - .cursor/commands/
    • +
  • ✅ VS Code / GitHub Copilot - .github/prompts/ + .vscode/settings.json
    • +
  • ✅ Claude Code - .claude/commands/
    • +
  • ✅ Gemini CLI - .gemini/commands/
    • +
  • ✅ Qwen Code - .qwen/commands/
    • +
  • ✅ opencode - .opencode/command/
    • +
  • ✅ Windsurf - .windsurf/workflows/
    • +
  • ✅ Kilo Code - .kilocode/workflows/
    • +
  • ✅ Auggie - .augment/commands/
    • +
  • ✅ Roo Code - .roo/commands/
    • +
  • ✅ CodeBuddy - .codebuddy/commands/
    • +
  • ✅ Amp - .agents/commands/
    • +
  • ✅ Amazon Q Developer - .amazonq/prompts/
    • +
+ +
+ +

Quick Start

+ +

Step 1: Initialize IDE Integration

+ +

Run the specfact init command in your repository:

+ +
# Auto-detect IDE
+specfact init
+
+# Or specify IDE explicitly
+specfact init --ide cursor
+specfact init --ide vscode
+specfact init --ide copilot
+
+# Install required packages for contract enhancement
+specfact init --install-deps
+
+# Initialize for specific IDE and install dependencies
+specfact init --ide cursor --install-deps
+
+ +

What it does:

+ +
    +
  1. Detects your IDE (or uses --ide flag)
    2. +
  2. Copies prompt templates from resources/prompts/ to IDE-specific location
    3. +
  3. Creates/updates VS Code settings if needed
    4. +
  4. Makes slash commands available in your IDE
    5. +
  5. Optionally installs required packages for contract enhancement (if --install-deps is provided): +
      +
    • beartype>=0.22.4 - Runtime type checking
      • +
    • icontract>=2.7.1 - Design-by-contract decorators
      • +
    • crosshair-tool>=0.0.97 - Contract exploration
      • +
    • pytest>=8.4.2 - Testing framework
      • +
    +
    6. +
+ +

Step 2: Use Slash Commands in Your IDE

+ +

Once initialized, you can use slash commands directly in your IDE’s AI chat:

+ +

In Cursor / VS Code / Copilot:

+ +
# Core workflow commands (numbered for natural progression)
+/specfact.01-import legacy-api --repo .
+/specfact.02-plan init legacy-api
+/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth"
+/specfact.03-review legacy-api
+/specfact.04-sdd legacy-api
+/specfact.05-enforce legacy-api
+/specfact.06-sync --adapter speckit --repo . --bidirectional
+/specfact.07-contracts legacy-api --apply all-contracts  # Analyze, generate prompts, apply contracts sequentially
+
+# Advanced commands
+/specfact.compare --bundle legacy-api
+/specfact.validate --repo .
+
+ +

The IDE automatically recognizes these commands and provides enhanced prompts.

+ +
+ +

How It Works

+ +

Prompt Templates

+ +

Slash commands are markdown prompt templates (not executable CLI commands). They:

+ +
    +
  1. Live in your repository - Templates are stored in resources/prompts/ (packaged with SpecFact CLI)
    2. +
  2. Get copied to IDE locations - specfact init copies them to IDE-specific directories
    3. +
  3. Registered automatically - The IDE reads these files and makes them available as slash commands
    4. +
  4. Provide enhanced prompts - Templates include detailed instructions for the AI assistant
    5. +
+ +

Template Format

+ +

Each template follows this structure:

+ +
---
+description: Command description for IDE display
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+
+ +

Goal

+ +

Detailed instructions for the AI assistant…

+ +

Execution Steps

+ +
    +
  1. +

    Parse arguments…

    +
    2. +
  2. +

    Execute command…

    +
    3. +
  3. +

    Generate output…

    +
    4. +
+ +

+### IDE Registration
+
+**How IDEs discover slash commands:**
+
+- **VS Code / Copilot**: Reads `.github/prompts/*.prompt.md` files listed in `.vscode/settings.json` under `chat.promptFilesRecommendations`
+- **Cursor**: Automatically discovers `.cursor/commands/*.md` files
+- **Other IDEs**: Follow their respective discovery mechanisms
+
+---
+
+## Available Slash Commands
+
+**Complete Reference**: [Prompts README](/specfact-cli/prompts/README.md) - Full slash commands reference with examples
+
+**Workflow Guide**: [AI IDE Workflow Guide](/specfact-cli/ai-ide-workflow/) - Complete workflow from setup to validation
+
+## Available Slash Commands
+
+**Core Workflow Commands** (numbered for workflow ordering):
+
+| Command | Description | CLI Equivalent |
+|---------|-------------|----------------|
+| `/specfact.01-import` | Import codebase into plan bundle | `specfact import from-code <bundle-name>` |
+| `/specfact.02-plan` | Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) | `specfact plan <operation> <bundle-name>` |
+| `/specfact.03-review` | Review plan and promote through stages | `specfact plan review <bundle-name>`, `specfact plan promote <bundle-name>` |
+| `/specfact.04-sdd` | Create SDD manifest from plan | `specfact plan harden <bundle-name>` |
+| `/specfact.05-enforce` | Validate SDD and contracts | `specfact enforce sdd <bundle-name>` |
+| `/specfact.06-sync` | Sync with external tools or repository | `specfact sync bridge --adapter <adapter>` |
+| `/specfact.07-contracts` | Contract enhancement workflow: analyze → generate prompts → apply sequentially | `specfact analyze contracts`, `specfact generate contracts-prompt`, `specfact generate contracts-apply` |
+
+**Advanced Commands** (no numbering):
+
+| Command | Description | CLI Equivalent |
+|---------|-------------|----------------|
+| `/specfact.compare` | Compare manual vs auto plans | `specfact plan compare` |
+| `/specfact.validate` | Run validation suite | `specfact repro` |
+| `/specfact.generate-contracts-prompt` | Generate AI IDE prompt for adding contracts | `specfact generate contracts-prompt <file> --apply <contracts>` |
+
+---
+
+## Examples
+
+### Example 1: Initialize for Cursor
+
+```bash
+# Run init in your repository
+cd /path/to/my-project
+specfact init --ide cursor
+
+# Output:
+# ✓ Initialization Complete
+# Copied 5 template(s) to .cursor/commands/
+#
+# You can now use SpecFact slash commands in Cursor!
+# Example: /specfact.01-import legacy-api --repo .
+
+ +

Now in Cursor:

+ +
    +
  1. Open Cursor AI chat
    2. +
  2. Type /specfact.01-import legacy-api --repo .
    3. +
  3. Cursor recognizes the command and provides enhanced prompts
    4. +
+ +

Example 2: Initialize for VS Code / Copilot

+ +
# Run init in your repository
+specfact init --ide vscode
+
+# Output:
+# ✓ Initialization Complete
+# Copied 5 template(s) to .github/prompts/
+# Updated VS Code settings: .vscode/settings.json
+
+
+ +

VS Code settings.json:

+ +
{
+  "chat": {
+    "promptFilesRecommendations": [
+      ".github/prompts/specfact.01-import.prompt.md",
+      ".github/prompts/specfact.02-plan.prompt.md",
+      ".github/prompts/specfact.03-review.prompt.md",
+      ".github/prompts/specfact.04-sdd.prompt.md",
+      ".github/prompts/specfact.05-enforce.prompt.md",
+      ".github/prompts/specfact.06-sync.prompt.md",
+      ".github/prompts/specfact.07-contracts.prompt.md",
+      ".github/prompts/specfact.compare.prompt.md",
+      ".github/prompts/specfact.validate.prompt.md"
+    ]
+  }
+}
+
+ +

Example 3: Update Templates

+ +

If you update SpecFact CLI, run init again to update templates:

+ +
# Re-run init to update templates (use --force to overwrite)
+specfact init --ide cursor --force
+
+ +
+ +

Advanced Usage

+ +

Custom Template Locations

+ +

By default, templates are copied from SpecFact CLI’s package resources. To use custom templates:

+ +
    +
  1. Create your own templates in a custom location
    2. +
  2. Modify specfact init to use custom path (future feature)
    3. +
+ +

IDE-Specific Customization

+ +

Different IDEs may require different template formats:

+ +
    +
  • Markdown (Cursor, Claude, etc.): Direct .md files
    • +
  • TOML (Gemini, Qwen): Converted to TOML format automatically
    • +
  • VS Code: .prompt.md files with settings.json integration
    • +
+ +

The specfact init command handles all conversions automatically.

+ +
+ +

Troubleshooting

+ +

Slash Commands Not Showing in IDE

+ +

Issue: Commands don’t appear in IDE autocomplete

+ +

Solutions:

+ +
    +
  1. +

    Verify files exist:

    + + 
    ls .cursor/commands/specfact-*.md  # For Cursor
+ls .github/prompts/specfact-*.prompt.md  # For VS Code
+
+
    +
    2. +
  2. +

    Re-run init:

    + + 
    specfact init --ide cursor --force
+
    +
    3. +
  3. +

    Restart IDE: Some IDEs require restart to discover new commands

    +
    4. +
+ +

VS Code Settings Not Updated

+ +

Issue: VS Code settings.json not created or updated

+ +

Solutions:

+ +
    +
  1. +

    Check permissions:

    + + 
    ls -la .vscode/settings.json
+
+
    +
    2. +
  2. +

    Manually verify settings.json:

    + + 
    {
+  "chat": {
+    "promptFilesRecommendations": [...]
+  }
+}
+
+
    +
    3. +
  3. +

    Re-run init:

    + + 
    specfact init --ide vscode --force
+
    +
    4. +
+ +
+ + + + + +
+ +

Next Steps

+ +
    +
  • ⭐ Integration Showcases - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations
    • +
  • ✅ Initialize IDE integration with specfact init
    • +
  • ✅ Use slash commands in your IDE
    • +
  • 📖 Read CoPilot Mode Guide for CLI usage
    • +
  • 📖 Read Command Reference for all commands
    • +
+ +
+ +

Trademarks: All product names, logos, and brands mentioned in this guide are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See TRADEMARKS.md for more information.

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/guides/integrations-overview.md b/_site_local/guides/integrations-overview.md new file mode 100644 index 0000000..79f74cd --- /dev/null +++ b/_site_local/guides/integrations-overview.md @@ -0,0 +1,263 @@ +# Integrations Overview + +> **Comprehensive guide to all SpecFact CLI integrations** +> Understand when to use each integration and how they work together + +--- + +## Overview + +SpecFact CLI integrates with multiple tools and platforms to provide a complete spec-driven development ecosystem. This guide provides an overview of all available integrations, when to use each, and how they complement each other. + +--- + +## Integration Categories + +SpecFact CLI integrations fall into four main categories: + +1. **Specification Tools** - Tools for creating and managing specifications +2. **Testing & Validation** - Tools for contract testing and validation +3. **DevOps & Backlog** - Tools for syncing change proposals and tracking progress +4. **IDE & Development** - Tools for AI-assisted development workflows + +--- + +## Specification Tools + +### Spec-Kit Integration + +**Purpose**: Interactive specification authoring for new features + +**What it provides**: + +- ✅ Interactive slash commands (`/speckit.specify`, `/speckit.plan`) with AI assistance +- ✅ Rapid prototyping workflow: spec → plan → tasks → code +- ✅ Constitution and planning for new features +- ✅ IDE integration with CoPilot chat + +**When to use**: + +- Creating new features from scratch (greenfield development) +- Interactive specification authoring with AI assistance +- Learning and exploration of state machines and contracts +- Single-developer projects and rapid prototyping + +**Key difference**: Spec-Kit focuses on **new feature authoring**, while SpecFact CLI focuses on **brownfield code modernization**. + +**See also**: [Spec-Kit Journey Guide](./speckit-journey.md) + +--- + +### OpenSpec Integration + +**Purpose**: Specification anchoring and change tracking + +**What it provides**: + +- ✅ Source-of-truth specifications (`openspec/specs/`) documenting what IS built +- ✅ Change tracking with delta specs (ADDED/MODIFIED/REMOVED) +- ✅ Structured change proposals (`openspec/changes/`) with rationale and tasks +- ✅ Cross-repository support (specs can live separately from code) +- ✅ Spec-driven development workflow: proposal → delta specs → implementation → archive + +**When to use**: + +- Managing specifications as source of truth +- Tracking changes with structured proposals +- Cross-repository workflows (specs in different repos than code) +- Team collaboration on specifications and change proposals + +**Key difference**: OpenSpec manages **what should be built** (proposals) and **what is built** (specs), while SpecFact CLI adds **brownfield analysis** and **runtime enforcement**. + +**See also**: [OpenSpec Journey Guide](./openspec-journey.md) + +--- + +## Testing & Validation + +### Specmatic Integration + +**Purpose**: API contract testing and validation + +**What it provides**: + +- ✅ OpenAPI/AsyncAPI specification validation +- ✅ Backward compatibility checking between spec versions +- ✅ Mock server generation from specifications +- ✅ Test suite generation from specs +- ✅ Service-level contract testing (complements SpecFact's code-level contracts) + +**When to use**: + +- Validating API specifications (OpenAPI/AsyncAPI) +- Checking backward compatibility when updating API versions +- Running mock servers for frontend/client development +- Generating contract tests from specifications +- Service-level contract validation (complements code-level contracts) + +**Key difference**: Specmatic provides **API-level contract testing**, while SpecFact CLI provides **code-level contract enforcement** (icontract, beartype, CrossHair). + +**See also**: [Specmatic Integration Guide](./specmatic-integration.md) + +--- + +## DevOps & Backlog + +### DevOps Adapter Integration + +**Purpose**: Sync change proposals to DevOps backlog tools and track progress + +**What it provides**: + +- ✅ Export OpenSpec change proposals to GitHub Issues (or other DevOps tools) +- ✅ Automatic progress tracking via code change detection +- ✅ Content sanitization for public repositories +- ✅ Separate repository support (OpenSpec proposals and code in different repos) +- ✅ Automated comment annotations on issues + +**Supported adapters**: + +- **GitHub Issues** (`--adapter github`) - ✅ Full support +- **Azure DevOps** (`--adapter ado`) - Planned +- **Linear** (`--adapter linear`) - Planned +- **Jira** (`--adapter jira`) - Planned + +**When to use**: + +- Syncing OpenSpec change proposals to GitHub Issues +- Tracking implementation progress automatically +- Managing change proposals in DevOps backlog tools +- Coordinating between OpenSpec repositories and code repositories + +**Key difference**: DevOps adapters provide **backlog integration and progress tracking**, while OpenSpec provides **specification management**. + +**See also**: [DevOps Adapter Integration Guide](./devops-adapter-integration.md) + +--- + +## IDE & Development + +### AI IDE Integration + +**Purpose**: AI-assisted development workflows with slash commands + +**What it provides**: + +- ✅ Setup process (`init --ide cursor`) for IDE integration +- ✅ Slash commands for common workflows +- ✅ Prompt generation → AI IDE → validation loop +- ✅ Integration with command chains +- ✅ AI-assisted specification and planning + +**When to use**: + +- AI-assisted development workflows +- Using slash commands for common tasks +- Integrating SpecFact CLI with Cursor, VS Code + Copilot +- Streamlining development workflows with AI assistance + +**Key difference**: AI IDE integration provides **interactive AI assistance**, while command chains provide **automated workflows**. + +**See also**: [AI IDE Workflow Guide](./ai-ide-workflow.md), [IDE Integration Guide](./ide-integration.md) + +--- + +## Integration Decision Tree + +Use this decision tree to determine which integrations to use: + +```text +Start: What do you need? + +├─ Need to work with existing code? +│ └─ ✅ Use SpecFact CLI `import from-code` (brownfield analysis) +│ +├─ Need to create new features interactively? +│ └─ ✅ Use Spec-Kit integration (greenfield development) +│ +├─ Need to manage specifications as source of truth? +│ └─ ✅ Use OpenSpec integration (specification anchoring) +│ +├─ Need API contract testing? +│ └─ ✅ Use Specmatic integration (API-level contracts) +│ +├─ Need to sync change proposals to backlog? +│ └─ ✅ Use DevOps adapter integration (GitHub Issues, etc.) +│ +└─ Need AI-assisted development? + └─ ✅ Use AI IDE integration (slash commands, AI workflows) +``` + +--- + +## Integration Combinations + +### Common Workflows + +#### 1. Brownfield Modernization with OpenSpec + +- Use SpecFact CLI `import from-code` to analyze existing code +- Export to OpenSpec for specification anchoring +- Use OpenSpec change proposals for tracking improvements +- Sync proposals to GitHub Issues via DevOps adapter + +#### 2. Greenfield Development with Spec-Kit + +- Use Spec-Kit for interactive specification authoring +- Add SpecFact CLI enforcement for runtime contracts +- Use Specmatic for API contract testing +- Integrate with AI IDE for streamlined workflows + +#### 3. Full Stack Development + +- Use Spec-Kit/OpenSpec for specification management +- Use SpecFact CLI for code-level contract enforcement +- Use Specmatic for API-level contract testing +- Use DevOps adapter for backlog integration +- Use AI IDE integration for development workflows + +--- + +## Quick Reference + +| Integration | Primary Use Case | Key Command | Documentation | +|------------|------------------|-------------|---------------| +| **Spec-Kit** | Interactive spec authoring for new features | `/speckit.specify` | [Spec-Kit Journey](./speckit-journey.md) | +| **OpenSpec** | Specification anchoring and change tracking | `openspec validate` | [OpenSpec Journey](./openspec-journey.md) | +| **Specmatic** | API contract testing and validation | `spec validate` | [Specmatic Integration](./specmatic-integration.md) | +| **DevOps Adapter** | Sync proposals to backlog tools | `sync bridge --adapter github` | [DevOps Integration](./devops-adapter-integration.md) | +| **AI IDE** | AI-assisted development workflows | `init --ide cursor` | [AI IDE Workflow](./ai-ide-workflow.md) | + +--- + +## Getting Started + +1. **Choose your primary integration** based on your use case: + - Working with existing code? → Start with SpecFact CLI brownfield analysis + - Creating new features? → Start with Spec-Kit integration + - Managing specifications? → Start with OpenSpec integration + +2. **Add complementary integrations** as needed: + - Need API testing? → Add Specmatic + - Need backlog sync? → Add DevOps adapter + - Want AI assistance? → Add AI IDE integration + +3. **Follow the detailed guides** for each integration you choose + +--- + +## See Also + +- [Command Chains Guide](./command-chains.md) - Complete workflows using integrations +- [Common Tasks Guide](./common-tasks.md) - Quick reference for common integration tasks +- [Team Collaboration Workflow](./team-collaboration-workflow.md) - Using integrations in teams +- [Migration Guide](./migration-guide.md) - Migrating between integrations + +--- + +## Related Workflows + +- [Brownfield Modernization Chain](./command-chains.md#brownfield-modernization-chain) - Using SpecFact CLI with existing code +- [API Contract Development Chain](./command-chains.md#api-contract-development-chain) - Using Specmatic for API testing +- [Spec-Driven Development Chain](./command-chains.md#spec-driven-development-chain) - Using OpenSpec for spec management +- [AI IDE Workflow Chain](./command-chains.md#ai-ide-workflow-chain) - Using AI IDE integration diff --git a/_site_local/guides/migration-0.16-to-0.19.md b/_site_local/guides/migration-0.16-to-0.19.md new file mode 100644 index 0000000..646196e --- /dev/null +++ b/_site_local/guides/migration-0.16-to-0.19.md @@ -0,0 +1,174 @@ +# Migration Guide: v0.16.x to v0.20.0 LTS + +This guide helps you upgrade from SpecFact CLI v0.16.x to v0.20.0 LTS (Long-Term Stable). + +## Overview + +v0.17.0 - v0.20.0 are part of the **0.x stabilization track** leading to v0.20.0 LTS. + +### Key Changes + +| Version | Changes | +|---------|---------| +| **0.17.0** | Deprecated `implement` command, added bridge commands, version management | +| **0.18.0** | Updated documentation positioning, AI IDE bridge workflow | +| **0.19.0** | Full test coverage for Phase 7, migration guide | +| **0.20.0 LTS** | Long-Term Stable release - production-ready analysis and enforcement | + +--- + +## Breaking Changes + +### `implement` Command Deprecated + +The `implement tasks` command was deprecated in v0.17.0 and removed in v0.22.0. The `generate tasks` command was also removed in v0.22.0. + +**Before (v0.16.x):** + +```bash +specfact implement tasks .specfact/projects/my-bundle/tasks.yaml +``` + +**After (v0.17.0+):** + +Use the new bridge commands instead: + +```bash +# Set up CrossHair for contract exploration (one-time setup, only available since v0.20.1) +specfact repro setup + +# Analyze and validate your codebase +specfact repro --verbose + +# Generate AI-ready prompt to fix a gap +specfact generate fix-prompt GAP-001 --bundle my-bundle + +# Generate AI-ready prompt to add tests +specfact generate test-prompt src/auth/login.py --bundle my-bundle +``` + +### `run idea-to-ship` Removed + +The `run idea-to-ship` command has been removed in v0.17.0. + +**Rationale:** Code generation features are being redesigned for v1.0 with AI-assisted workflows. + +--- + +## New Features + +### Bridge Commands (v0.17.0) + +New commands that generate AI-ready prompts for your IDE: + +```bash +# Generate fix prompt for a gap +specfact generate fix-prompt GAP-001 + +# Generate test prompt for a file +specfact generate test-prompt src/module.py --type unit +``` + +### Version Management (v0.17.0) + +New commands for managing bundle versions: + +```bash +# Check for recommended version bump +specfact project version check --bundle my-bundle + +# Bump version (major/minor/patch) +specfact project version bump --bundle my-bundle --type minor + +# Set explicit version +specfact project version set --bundle my-bundle --version 2.0.0 +``` + +### CI Version Check (v0.17.0) + +GitHub Actions template now includes version check with configurable modes: + +- `info` - Informational only +- `warn` (default) - Log warnings, continue CI +- `block` - Fail CI if version bump not followed + +--- + +## Upgrade Steps + +### Step 1: Update SpecFact CLI + +```bash +pip install -U specfact-cli +# or +uvx specfact-cli@latest --version +``` + +### Step 2: Verify Version + +```bash +specfact --version +# Should show: SpecFact CLI version 0.19.0 +``` + +### Step 3: Update Workflows + +If you were using `implement tasks` or `run idea-to-ship`, migrate to bridge commands: + +**Old workflow:** + +```bash +# REMOVED in v0.22.0 - Use Spec-Kit, OpenSpec, or other SDD tools instead +# specfact generate tasks --bundle my-bundle +# specfact implement tasks .specfact/projects/my-bundle/tasks.yaml +``` + +**New workflow:** + +```bash +# 1. Analyze and validate your codebase +specfact repro --verbose + +# 2. Generate AI prompts for each gap +specfact generate fix-prompt GAP-001 --bundle my-bundle + +# 3. Copy prompt to AI IDE, get fix, apply + +# 4. Validate +specfact enforce sdd --bundle my-bundle +``` + +### Step 4: Update CI/CD (Optional) + +Add version check to your GitHub Actions: + +```yaml +- name: Version Check + run: specfact project version check --bundle ${{ env.BUNDLE_NAME }} + env: + SPECFACT_VERSION_CHECK_MODE: warn # or 'info' or 'block' +``` + +--- + +## FAQ + +### Q: Why was `implement` deprecated? + +**A:** The `implement` command attempted to generate code directly, but this approach doesn't align with the Ultimate Vision for v1.0. In v1.0, AI copilots will consume structured data from SpecFact and generate code, with SpecFact validating the results. The bridge commands provide a transitional workflow. + +### Q: Can I still use v0.16.x? + +**A:** Yes, v0.16.x will continue to work. However, we recommend upgrading to v0.20.0 LTS for the latest fixes, features, and long-term stability. v0.20.0 is the Long-Term Stable (LTS) release and will receive bug fixes and security updates until v1.0 GA. + +### Q: When will v1.0 be released? + +**A:** See the [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) for the v1.0 roadmap. + +--- + +## Support + +- 💬 **Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 **Found a bug?** [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 **Need help?** [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_local/guides/migration-cli-reorganization.md b/_site_local/guides/migration-cli-reorganization.md new file mode 100644 index 0000000..20c3a2a --- /dev/null +++ b/_site_local/guides/migration-cli-reorganization.md @@ -0,0 +1,293 @@ +# CLI Reorganization Migration Guide + +**Date**: 2025-11-27 +**Version**: 0.9.3+ + +This guide helps you migrate from the old command structure to the new reorganized structure, including parameter standardization, slash command changes, and bundle parameter integration. + +--- + +## Overview of Changes + +The CLI reorganization includes: + +1. **Parameter Standardization** - Consistent parameter names across all commands +2. **Parameter Grouping** - Logical organization (Target → Output → Behavior → Advanced) +3. **Slash Command Reorganization** - Reduced from 13 to 8 commands with numbered workflow ordering +4. **Bundle Parameter Integration** - All commands now use `--bundle` parameter + +--- + +## Parameter Name Changes + +### Standard Parameter Names + +| Old Name | New Name | Commands Affected | +|----------|----------|-------------------| +| `--base-path` | `--repo` | `generate contracts` | +| `--output` | `--out` | `bridge constitution bootstrap` | +| `--format` | `--output-format` | `enforce sdd`, `plan compare` | +| `--non-interactive` | `--no-interactive` | All commands | +| `--name` (bundle name) | `--bundle` | All commands | + +### Deprecation Policy + +- **Transition Period**: 3 months from implementation date (2025-11-27) +- **Deprecation Warnings**: Commands using deprecated names will show warnings +- **Removal**: Deprecated names will be removed after transition period +- **Documentation**: All examples and docs updated immediately + +### Examples + +**Before**: + +```bash +specfact import from-code --bundle legacy-api --repo . +specfact plan compare --bundle legacy-api --output-format json --out report.json +specfact enforce sdd legacy-api --no-interactive +``` + +**After**: + +```bash +specfact import from-code --bundle legacy-api --repo . +specfact plan compare --bundle legacy-api --output-format json --out report.json +specfact enforce sdd legacy-api --no-interactive +``` + +--- + +## Slash Command Changes + +### Old Slash Commands (13 total) → New Slash Commands (8 total) + +| Old Command | New Command | Notes | +|-------------|-------------|-------| +| `/specfact-import-from-code` | `/specfact.01-import` | Numbered for workflow ordering | +| `/specfact-plan-init` | `/specfact.02-plan` | Unified plan management | +| `/specfact-plan-add-feature` | `/specfact.02-plan` | Merged into plan command | +| `/specfact-plan-add-story` | `/specfact.02-plan` | Merged into plan command | +| `/specfact-plan-update-idea` | `/specfact.02-plan` | Merged into plan command | +| `/specfact-plan-update-feature` | `/specfact.02-plan` | Merged into plan command | +| `/specfact-plan-review` | `/specfact.03-review` | Numbered for workflow ordering | +| `/specfact-plan-promote` | `/specfact.03-review` | Merged into review command | +| `/specfact-plan-compare` | `/specfact.compare` | Advanced command (no numbering) | +| `/specfact-enforce` | `/specfact.05-enforce` | Numbered for workflow ordering | +| `/specfact-sync` | `/specfact.06-sync` | Numbered for workflow ordering | +| `/specfact-repro` | `/specfact.validate` | Advanced command (no numbering) | +| `/specfact-plan-select` | *(CLI-only)* | Removed (use CLI directly) | + +### Workflow Ordering + +The new numbered commands follow natural workflow progression: + +1. **Import** (`/specfact.01-import`) - Start by importing existing code +2. **Plan** (`/specfact.02-plan`) - Manage your plan bundle +3. **Review** (`/specfact.03-review`) - Review and promote your plan +4. **SDD** (`/specfact.04-sdd`) - Create SDD manifest +5. **Enforce** (`/specfact.05-enforce`) - Validate SDD and contracts +6. **Sync** (`/specfact.06-sync`) - Sync with external tools + +**Advanced Commands** (no numbering): + +- `/specfact.compare` - Compare plans +- `/specfact.validate` - Validation suite + +### Ordered Workflow Examples + +**Before**: + +```bash +/specfact-import-from-code --repo . --confidence 0.7 +/specfact-plan-init my-project +/specfact-plan-add-feature --key FEATURE-001 --title "User Auth" +/specfact-plan-review my-project +``` + +**After**: + +```bash +/specfact.01-import legacy-api --repo . --confidence 0.7 +/specfact.02-plan init legacy-api +/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth" +/specfact.03-review legacy-api +``` + +--- + +## Bundle Parameter Addition + +### All Commands Now Require `--bundle` + +**Before** (positional argument): + +```bash +specfact import from-code --bundle legacy-api --repo . +specfact plan init --bundle legacy-api +specfact plan review --bundle legacy-api +``` + +**After** (named parameter): + +```bash +specfact import from-code --bundle legacy-api --repo . +specfact plan init --bundle legacy-api +specfact plan review --bundle legacy-api +``` + +### Path Resolution Changes + +- **Old**: Used positional argument or `--name` for bundle identification +- **New**: Uses `--bundle` parameter for bundle name +- **Path**: Bundle path is resolved from bundle name: `.specfact/projects//` + +### Migration Steps + +1. **Update all scripts** to use `--bundle` instead of positional arguments +2. **Update CI/CD pipelines** to use new parameter format +3. **Update IDE slash commands** to use new numbered format +4. **Test workflows** to ensure bundle resolution works correctly + +--- + +## Command Path Changes + +### Constitution Commands + +**Current Command**: + +```bash +specfact sdd constitution bootstrap +specfact sdd constitution enrich +specfact sdd constitution validate +``` + +**Note**: The old `specfact constitution` command has been removed. All constitution functionality is now available under `specfact sdd constitution`. + +--- + +## Why the Change? + +The constitution commands are **Spec-Kit adapter commands** - they're only needed when syncing with Spec-Kit or working in Spec-Kit format. They are now under the `sdd` (Spec-Driven Development) command group, as constitution management is part of the SDD workflow. + +**Benefits**: + +- Clearer command organization (adapters grouped together) +- Better aligns with bridge architecture +- Makes it obvious these are for external tool integration + +--- + +## Command Changes + +The old `specfact constitution` command has been removed. Use `specfact sdd constitution` instead: + +```bash +$ specfact constitution bootstrap --repo . +⚠ Breaking Change: The 'specfact constitution' command has been removed. +Please use 'specfact sdd constitution' instead. +Example: 'specfact constitution bootstrap' → 'specfact sdd constitution bootstrap' + +[bold cyan]Generating bootstrap constitution for:[/bold cyan] . +... +``` + +--- + +## Updated Workflows + +### Brownfield Import Workflow + +```bash +specfact import from-code --bundle legacy-api --repo . +specfact sdd constitution bootstrap --repo . +specfact sync bridge --adapter speckit +``` + +### Constitution Management Workflow + +```bash +specfact sdd constitution bootstrap --repo . +specfact sdd constitution validate +specfact sdd constitution enrich --repo . +``` + +--- + +## CI/CD Updates + +Update your CI/CD pipelines to use the new command paths: + +**GitHub Actions Example**: + +```yaml +- name: Validate Constitution + run: specfact sdd constitution validate +``` + +**GitLab CI Example**: + +```yaml +validate_constitution: + script: + - specfact sdd constitution validate +``` + +--- + +## Script Updates + +Update any scripts that use the old commands: + +**Bash Script Example**: + +```bash +#!/bin/bash +# Old +# specfact constitution bootstrap --repo . + +# New +specfact sdd constitution bootstrap --repo . +``` + +**Python Script Example**: + +```python +# Old +# subprocess.run(["specfact", "constitution", "bootstrap", "--repo", "."]) + +# New +subprocess.run(["specfact", "bridge", "constitution", "bootstrap", "--repo", "."]) +``` + +--- + +## IDE Integration + +If you're using IDE slash commands, update your prompts: + +**Old**: + +```bash +/specfact-constitution-bootstrap --repo . +``` + +**New**: + +```bash +/specfact.bridge.constitution.bootstrap --repo . +``` + +--- + +## Questions? + +If you encounter any issues during migration: + +1. Check the [Command Reference](../reference/commands.md) for updated examples +2. Review the [Troubleshooting Guide](./troubleshooting.md) +3. Open an issue on GitHub + +--- + +**Last Updated**: 2025-01-27 diff --git a/_site_local/guides/openspec-journey.md b/_site_local/guides/openspec-journey.md new file mode 100644 index 0000000..e0d5027 --- /dev/null +++ b/_site_local/guides/openspec-journey.md @@ -0,0 +1,512 @@ +# The Journey: OpenSpec + SpecFact Integration + +> **OpenSpec and SpecFact are complementary, not competitive.** +> **Primary Use Case**: OpenSpec for specification anchoring and change tracking +> **Secondary Use Case**: SpecFact adds brownfield analysis, runtime enforcement, and DevOps integration + +--- + +## 🎯 Why Integrate? + +### **What OpenSpec Does Great** + +OpenSpec is **excellent** for: + +- ✅ **Specification Anchoring** - Source-of-truth specifications (`openspec/specs/`) that document what IS built +- ✅ **Change Tracking** - Delta specs (ADDED/MODIFIED/REMOVED) that document what SHOULD change +- ✅ **Change Proposals** - Structured proposals (`openspec/changes/`) with rationale, impact, and tasks +- ✅ **Cross-Repository Support** - Specifications can live in separate repositories from code +- ✅ **Spec-Driven Development** - Clear workflow: proposal → delta specs → implementation → archive +- ✅ **Team Collaboration** - Shared specifications and change proposals for coordination + +**Note**: OpenSpec excels at **managing specifications and change proposals** - it provides the "what" and "why" for changes, but doesn't analyze existing code or enforce contracts. + +### **What OpenSpec Is Designed For (vs. SpecFact CLI)** + +OpenSpec **is designed primarily for**: + +- ✅ **Specification Management** - Source-of-truth specs (`openspec/specs/`) and change proposals (`openspec/changes/`) +- ✅ **Change Tracking** - Delta specs (ADDED/MODIFIED/REMOVED) that document proposed changes +- ✅ **Cross-Repository Workflows** - Specifications can be in different repos than code +- ✅ **Spec-Driven Development** - Clear proposal → implementation → archive workflow + +OpenSpec **is not designed primarily for** (but SpecFact CLI provides): + +- ⚠️ **Brownfield Analysis** - **Not designed for reverse-engineering from existing code** + - OpenSpec focuses on documenting what SHOULD be built (proposals) and what IS built (specs) + - **This is where SpecFact CLI complements OpenSpec** 🎯 +- ⚠️ **Runtime Contract Enforcement** - Not designed for preventing regressions with executable contracts +- ⚠️ **Code2Spec Extraction** - Not designed for automatically extracting specs from legacy code +- ⚠️ **DevOps Integration** - Not designed for syncing change proposals to GitHub Issues, ADO, Linear, Jira +- ⚠️ **Automated Validation** - Not designed for CI/CD gates or automated contract validation +- ⚠️ **Symbolic Execution** - Not designed for discovering edge cases with CrossHair + +### **When to Integrate** + +| Need | OpenSpec Solution | SpecFact Solution | +|------|------------------|-------------------| +| **Work with existing code** ⭐ **PRIMARY** | ⚠️ **Not designed for** - Focuses on spec authoring | ✅ **`import from-code`** ⭐ - Reverse-engineer existing code to plans (PRIMARY use case) | +| **Sync change proposals to DevOps** | ⚠️ **Not designed for** - Manual process | ✅ **`sync bridge --adapter github`** ✅ - Export proposals to GitHub Issues (IMPLEMENTED) | +| **Track code changes** | ⚠️ **Not designed for** - Manual tracking | ✅ **`--track-code-changes`** ✅ - Auto-detect commits and add progress comments (IMPLEMENTED) | +| **Runtime enforcement** | Manual validation | ✅ **Contract enforcement** - Prevent regressions with executable contracts | +| **Code vs spec alignment** | Manual comparison | ✅ **Alignment reports** ⏳ - Compare SpecFact features vs OpenSpec specs (PLANNED) | +| **Brownfield modernization** | Manual spec authoring | ✅ **Brownfield analysis** ⭐ - Extract specs from legacy code automatically | + +--- + +## 🌱 The Integration Vision + +### **Complete Brownfield Modernization Stack** + +When modernizing legacy code, you can use **both tools together** for maximum value: + +```mermaid +graph TB + subgraph "OpenSpec: Specification Management" + OS1[openspec/specs/
Source-of-Truth Specs] + OS2[openspec/changes/
Change Proposals] + OS3[Delta Specs
ADDED/MODIFIED/REMOVED] + end + + subgraph "SpecFact: Code Analysis & Enforcement" + SF1[import from-code
Extract specs from code] + SF2[Runtime Contracts
Prevent regressions] + SF3[Bridge Adapters
Sync to DevOps] + end + + subgraph "DevOps Integration" + GH[GitHub Issues] + ADO[Azure DevOps] + LIN[Linear] + end + + OS2 -->|Export| SF3 + SF3 -->|Create Issues| GH + SF3 -->|Create Issues| ADO + SF3 -->|Create Issues| LIN + + SF1 -->|Compare| OS1 + OS1 -->|Validate| SF2 + + style OS1 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style OS2 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style OS3 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style SF1 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF2 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF3 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style GH fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff + style ADO fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff + style LIN fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff +``` + +**The Power of Integration:** + +1. **OpenSpec** manages specifications and change proposals (the "what" and "why") +2. **SpecFact** analyzes existing code and enforces contracts (the "how" and "safety") +3. **Bridge Adapters** sync change proposals to DevOps tools (the "tracking") +4. **Together** they form a complete brownfield modernization solution + +--- + +## 🚀 The Integration Journey + +### **Stage 1: DevOps Export** ✅ **IMPLEMENTED** + +**Time**: < 5 minutes + +**What's Available Now:** + +Export OpenSpec change proposals to GitHub Issues and track implementation progress: + +```bash +# Step 1: Create change proposal in OpenSpec +mkdir -p openspec/changes/add-feature-x +cat > openspec/changes/add-feature-x/proposal.md << 'EOF' +# Change: Add Feature X + +## Why +Add new feature X to improve user experience. + +## What Changes +- Add API endpoints +- Update database schema +- Add frontend components + +## Impact +- Affected specs: api, frontend +- Affected code: src/api/, src/frontend/ +EOF + +# Step 2: Export to GitHub Issues +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo +``` + +**What You Get:** + +- ✅ **Issue Creation** - OpenSpec change proposals become GitHub Issues automatically +- ✅ **Progress Tracking** - Code changes detected and progress comments added automatically +- ✅ **Content Sanitization** - Protect internal information when syncing to public repos +- ✅ **Separate Repository Support** - OpenSpec proposals and source code can be in different repos + +**Visual Flow:** + +```mermaid +sequenceDiagram + participant Dev as Developer + participant OS as OpenSpec + participant SF as SpecFact CLI + participant GH as GitHub Issues + + Dev->>OS: Create change proposal
openspec/changes/add-feature-x/ + Dev->>SF: specfact sync bridge --adapter github + SF->>OS: Read proposal.md + SF->>GH: Create issue from proposal + GH-->>SF: Issue #123 created + SF->>OS: Update proposal.md
with issue tracking + + Note over Dev,GH: Implementation Phase + + Dev->>Dev: Make commits with change ID + Dev->>SF: specfact sync bridge --track-code-changes + SF->>SF: Detect commits mentioning
change ID + SF->>GH: Add progress comment
to issue #123 + GH-->>Dev: Progress visible in issue + + rect rgb(59, 130, 246) + Note over OS: OpenSpec
Specification Management + end + + rect rgb(249, 115, 22) + Note over SF: SpecFact CLI
Code Analysis & Enforcement + end + + rect rgb(100, 116, 139) + Note over GH: DevOps
Backlog Tracking + end +``` + +**Key Insight**: OpenSpec proposals become actionable DevOps backlog items automatically! + +--- + +### **Stage 2: OpenSpec Bridge Adapter** ✅ **IMPLEMENTED** + +**Time**: Available now (v0.22.0+) + +**What's Available:** + +Read-only sync from OpenSpec to SpecFact for change proposal tracking: + +```bash +# Sync OpenSpec change proposals to SpecFact +specfact sync bridge --adapter openspec --mode read-only \ + --bundle my-project \ + --repo /path/to/openspec-repo + +# The adapter reads OpenSpec change proposals from openspec/changes/ +# and syncs them to SpecFact change tracking +``` + +**What You Get:** + +- ✅ **Change Proposal Import** - OpenSpec change proposals synced to SpecFact bundles +- ✅ **Change Tracking** - Track OpenSpec proposals in SpecFact format +- ✅ **Read-Only Sync** - Import from OpenSpec without modifying OpenSpec files +- ⏳ **Alignment Reports** - Compare OpenSpec specs vs code-derived features (planned) +- ⏳ **Gap Detection** - Identify OpenSpec specs not found in code (planned) +- ⏳ **Coverage Calculation** - Measure how well code matches specifications (planned) + +**Visual Flow:** + +```mermaid +graph LR + subgraph "OpenSpec Repository" + OS1[openspec/specs/
Source-of-Truth] + OS2[openspec/changes/
Proposals] + end + + subgraph "SpecFact Analysis" + SF1[import from-code
Extract features] + SF2[Alignment Report
Compare specs vs code] + end + + OS1 -->|Import| SF2 + SF1 -->|Compare| SF2 + SF2 -->|Gap Report| Dev[Developer] + + style OS1 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style OS2 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style SF1 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF2 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style Dev fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff +``` + +**Key Insight**: Validate that your code matches OpenSpec specifications automatically! + +--- + +### **Stage 3: Bidirectional Sync** ⏳ **PLANNED** + +**Time**: Future enhancement + +**What's Coming:** + +Full bidirectional sync between OpenSpec and SpecFact: + +```bash +# Bidirectional sync (future) +specfact sync bridge --adapter openspec --bidirectional \ + --bundle my-project \ + --repo /path/to/openspec-repo \ + --watch +``` + +**What You'll Get:** + +- ⏳ **Spec Sync** - OpenSpec specs ↔ SpecFact features +- ⏳ **Change Sync** - OpenSpec proposals ↔ SpecFact change tracking +- ⏳ **Conflict Resolution** - Automatic conflict resolution with priority rules +- ⏳ **Watch Mode** - Real-time sync as files change + +**Visual Flow:** + +```mermaid +graph TB + subgraph "OpenSpec" + OS1[Specs] + OS2[Change Proposals] + end + + subgraph "SpecFact" + SF1[Features] + SF2[Change Tracking] + end + + OS1 <-->|Bidirectional| SF1 + OS2 <-->|Bidirectional| SF2 + + style OS1 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style OS2 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style SF1 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF2 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff +``` + +**Key Insight**: Keep OpenSpec and SpecFact in perfect sync automatically! + +--- + +## 📋 Complete Workflow Example + +### **Brownfield Modernization with OpenSpec + SpecFact** + +Here's how to use both tools together for legacy code modernization: + +```bash +# Step 1: Analyze legacy code with SpecFact +specfact import from-code --bundle legacy-api --repo ./legacy-app +# → Extracts features from existing code +# → Creates SpecFact bundle: .specfact/projects/legacy-api/ + +# Step 2: Create OpenSpec change proposal +mkdir -p openspec/changes/modernize-api +cat > openspec/changes/modernize-api/proposal.md << 'EOF' +# Change: Modernize Legacy API + +## Why +Legacy API needs modernization for better performance and maintainability. + +## What Changes +- Refactor API endpoints +- Add contract validation +- Update database schema + +## Impact +- Affected specs: api, database +- Affected code: src/api/, src/db/ +EOF + +# Step 3: Export proposal to GitHub Issues ✅ IMPLEMENTED +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo + +# Step 4: Implement changes +git commit -m "feat: modernize-api - refactor endpoints" + +# Step 5: Track progress ✅ IMPLEMENTED +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --track-code-changes \ + --repo /path/to/openspec-repo \ + --code-repo /path/to/source-code-repo + +# Step 6: Sync OpenSpec change proposals ✅ AVAILABLE +specfact sync bridge --adapter openspec --mode read-only \ + --bundle legacy-api \ + --repo /path/to/openspec-repo +# → Generates alignment report +# → Shows gaps between OpenSpec specs and code + +# Step 7: Add runtime contracts +specfact enforce stage --preset balanced + +# Step 8: Archive completed change +openspec archive modernize-api +``` + +**Complete Flow:** + +```mermaid +graph TB + Start[Start: Legacy Code] --> SF1[SpecFact: Extract Features] + SF1 --> OS1[OpenSpec: Create Proposal] + OS1 --> SF2[SpecFact: Export to GitHub] + SF2 --> GH[GitHub: Issue Created] + GH --> Dev[Developer: Implement] + Dev --> SF3[SpecFact: Track Progress] + SF3 --> GH2[GitHub: Progress Comments] + GH2 --> SF4[SpecFact: Validate Alignment] + SF4 --> SF5[SpecFact: Add Contracts] + SF5 --> OS2[OpenSpec: Archive Change] + OS2 --> End[End: Modernized Code] + + style Start fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff + style End fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff + style SF1 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF2 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF3 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF4 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF5 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style OS1 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style OS2 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style GH fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff + style GH2 fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff + style Dev fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff +``` + +--- + +## 🎯 Implementation Status + +### ✅ **Implemented Features** + +| Feature | Status | Description | +|---------|--------|-------------| +| **DevOps Export** | ✅ **Available** | Export OpenSpec change proposals to GitHub Issues | +| **Code Change Tracking** | ✅ **Available** | Detect commits and add progress comments automatically | +| **Content Sanitization** | ✅ **Available** | Protect internal information for public repos | +| **Separate Repository Support** | ✅ **Available** | OpenSpec proposals and source code in different repos | +| **Progress Comments** | ✅ **Available** | Automated progress comments with commit details | + +### ⏳ **Planned Features** + +| Feature | Status | Description | +|---------|--------|-------------| +| **OpenSpec Bridge Adapter** | ✅ **Available** | Read-only sync from OpenSpec to SpecFact (v0.22.0+) | +| **Alignment Reports** | ⏳ **Planned** | Compare OpenSpec specs vs code-derived features | +| **Specification Import** | ⏳ **Planned** | Import OpenSpec specs into SpecFact bundles | +| **Bidirectional Sync** | ⏳ **Future** | Full bidirectional sync between OpenSpec and SpecFact | +| **Watch Mode** | ⏳ **Future** | Real-time sync as files change | + +--- + +## 💡 Key Insights + +### **The "Aha!" Moment** + +**OpenSpec** = The "what" and "why" (specifications and change proposals) +**SpecFact** = The "how" and "safety" (code analysis and contract enforcement) +**Together** = Complete brownfield modernization solution + +### **Why This Integration Matters** + +1. **OpenSpec** provides structured change proposals and source-of-truth specifications +2. **SpecFact** extracts features from legacy code and enforces contracts +3. **Bridge Adapters** sync proposals to DevOps tools for team visibility +4. **Alignment Reports** (planned) validate that code matches specifications + +### **The Power of Separation** + +- **OpenSpec Repository**: Specifications and change proposals (the "plan") +- **Source Code Repository**: Actual implementation (the "code") +- **SpecFact**: Bridges the gap between plan and code + +This separation enables: + +- ✅ **Cross-Repository Workflows** - Specs in one repo, code in another +- ✅ **Team Collaboration** - Product owners manage specs, developers implement code +- ✅ **Clear Separation of Concerns** - Specifications separate from implementation + +--- + +## See Also + +### Related Guides + +- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations + +- [Command Chains Reference](command-chains.md) - Complete workflows including [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain) +- [Common Tasks Index](common-tasks.md) - Quick reference for OpenSpec integration tasks +- [DevOps Adapter Integration](devops-adapter-integration.md) - GitHub Issues and backlog tracking +- [Team Collaboration Workflow](team-collaboration-workflow.md) - Team collaboration patterns + +### Related Commands + +- [Command Reference - Import Commands](../reference/commands.md#import---import-from-external-formats) - `import from-bridge` reference +- [Command Reference - Sync Commands](../reference/commands.md#sync-bridge) - `sync bridge` reference +- [Command Reference - DevOps Adapters](../reference/commands.md#sync-bridge) - Adapter configuration + +### Related Examples + +- [OpenSpec Integration Examples](../examples/) - Real-world integration examples + +### Getting Started + +- [Getting Started](../getting-started/README.md) - Quick setup guide +- [Architecture](../reference/architecture.md) - System architecture and design + +--- + +## 📚 Next Steps + +### **Try It Now** ✅ + +1. **[DevOps Adapter Integration Guide](devops-adapter-integration.md)** - Export OpenSpec proposals to GitHub Issues +2. **[Commands Reference](../reference/commands.md#sync-bridge)** - Complete `sync bridge` documentation +3. **[OpenSpec Documentation](https://github.com/nold-ai/openspec)** - Learn OpenSpec basics + +### **Available Now** ✅ + +1. **OpenSpec Bridge Adapter** - Read-only sync for change proposal tracking (v0.22.0+) + +### **Coming Soon** ⏳ + +1. **Alignment Reports** - Compare OpenSpec specs vs code-derived features +2. **Bidirectional Sync** - Keep OpenSpec and SpecFact in sync +3. **Watch Mode** - Real-time synchronization + +--- + +## 🔗 Related Documentation + +- **[DevOps Adapter Integration](devops-adapter-integration.md)** - GitHub Issues and backlog tracking +- **[Spec-Kit Journey](speckit-journey.md)** - Similar guide for Spec-Kit integration +- **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete brownfield modernization workflow +- **[Commands Reference](../reference/commands.md)** - Complete command documentation + +--- + +**Need Help?** + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) + +--- + +**Remember**: OpenSpec manages specifications, SpecFact analyzes code. Together they form a complete brownfield modernization solution! 🚀 diff --git a/_site_local/guides/speckit-comparison.md b/_site_local/guides/speckit-comparison.md new file mode 100644 index 0000000..d80214e --- /dev/null +++ b/_site_local/guides/speckit-comparison.md @@ -0,0 +1,361 @@ +# How SpecFact Compares to GitHub Spec-Kit + +> **Complementary positioning: When to use Spec-Kit, SpecFact, or both together** + +--- + +## TL;DR: Complementary, Not Competitive + +**Spec-Kit excels at:** Documentation, greenfield specs, multi-language support +**SpecFact excels at:** Runtime enforcement, edge case discovery, high-risk brownfield + +**Use both together:** + +1. Use Spec-Kit for initial spec generation (fast, LLM-powered) +2. Use SpecFact to add runtime contracts to critical paths (safety net) +3. Spec-Kit generates docs, SpecFact prevents regressions + +--- + +## Quick Comparison + +| Capability | GitHub Spec-Kit | SpecFact CLI | When to Choose | +|-----------|----------------|--------------|----------------| +| **Code2spec (brownfield analysis)** | ✅ LLM-generated markdown specs | ✅ AST + contracts extraction | SpecFact for executable contracts | +| **Runtime enforcement** | ❌ No | ✅ icontract + beartype | **SpecFact only** | +| **Symbolic execution** | ❌ No | ✅ CrossHair SMT solver | **SpecFact only** | +| **Edge case discovery** | ⚠️ LLM suggests (probabilistic) | ✅ Mathematical proof (deterministic) | SpecFact for formal guarantees | +| **Regression prevention** | ⚠️ Code review (human) | ✅ Contract violation (automated) | SpecFact for automated safety net | +| **Multi-language** | ✅ 10+ languages | ⚠️ Python (Q1: +JS/TS) | Spec-Kit for multi-language | +| **GitHub integration** | ✅ Native slash commands | ✅ GitHub Actions + CLI | Spec-Kit for native integration | +| **Learning curve** | ✅ Low (markdown + slash commands) | ⚠️ Medium (decorators + contracts) | Spec-Kit for ease of use | +| **High-risk brownfield** | ⚠️ Good documentation | ✅ Formal verification | **SpecFact for high-risk** | +| **Free tier** | ✅ Open-source | ✅ Apache 2.0 | Both free | + +--- + +## Detailed Comparison + +### Code Analysis (Brownfield) + +**GitHub Spec-Kit:** + +- Uses LLM (Copilot) to generate markdown specs from code +- Fast, but probabilistic (may miss details) +- Output: Markdown documentation + +**SpecFact CLI:** + +- Uses AST analysis + LLM hybrid for precise extraction +- Generates executable contracts, not just documentation +- Output: YAML plans + Python contract decorators + +**Winner:** SpecFact for executable contracts, Spec-Kit for quick documentation + +### Runtime Enforcement + +**GitHub Spec-Kit:** + +- ❌ No runtime validation +- Specs are documentation only +- Human review catches violations (if reviewer notices) + +**SpecFact CLI:** + +- ✅ Runtime contract enforcement (icontract + beartype) +- Contracts catch violations automatically +- Prevents regressions during modernization + +**Winner:** SpecFact (core differentiation) + +### Edge Case Discovery + +**GitHub Spec-Kit:** + +- ⚠️ LLM suggests edge cases based on training data +- Probabilistic (may miss edge cases) +- Depends on LLM having seen similar patterns + +**SpecFact CLI:** + +- ✅ CrossHair symbolic execution +- Mathematical proof of edge cases +- Explores all feasible code paths + +**Winner:** SpecFact (formal guarantees) + +### Regression Prevention + +**GitHub Spec-Kit:** + +- ⚠️ Code review catches violations (if reviewer notices) +- Spec-code divergence possible (documentation drift) +- No automated enforcement + +**SpecFact CLI:** + +- ✅ Contract violations block execution automatically +- Impossible to diverge (contract = executable truth) +- Automated safety net during modernization + +**Winner:** SpecFact (automated enforcement) + +### Multi-Language Support + +**GitHub Spec-Kit:** + +- ✅ 10+ languages (Python, JS, TS, Go, Ruby, etc.) +- Native support for multiple ecosystems + +**SpecFact CLI:** + +- ⚠️ Python only (Q1 2026: +JavaScript/TypeScript) +- Focused on Python brownfield market + +**Winner:** Spec-Kit (broader language support) + +### GitHub Integration + +**GitHub Spec-Kit:** + +- ✅ Native slash commands in GitHub +- Integrated with Copilot +- Seamless GitHub workflow + +**SpecFact CLI:** + +- ✅ GitHub Actions integration +- CLI tool (works with any Git host) +- Not GitHub-specific + +**Winner:** Spec-Kit for native GitHub integration, SpecFact for flexibility + +--- + +## When to Use Spec-Kit + +### Use Spec-Kit For + +- **Greenfield projects** - Starting from scratch with specs +- **Rapid prototyping** - Fast spec generation with LLM +- **Multi-language teams** - Support for 10+ languages +- **Documentation focus** - Want markdown specs, not runtime enforcement +- **GitHub-native workflows** - Already using Copilot, want native integration + +### Example Use Case (Spec-Kit) + +**Scenario:** Starting a new React + Node.js project + +**Why Spec-Kit:** + +- Multi-language support (React + Node.js) +- Fast spec generation with Copilot +- Native GitHub integration +- Documentation-focused workflow + +--- + +## When to Use SpecFact + +### Use SpecFact For + +- **High-risk brownfield modernization** - Finance, healthcare, government +- **Runtime enforcement needed** - Can't afford production bugs +- **Edge case discovery** - Need formal guarantees, not LLM suggestions +- **Contract-first culture** - Already using Design-by-Contract, TDD +- **Python-heavy codebases** - Data engineering, ML pipelines, DevOps + +### Example Use Case (SpecFact) + +**Scenario:** Modernizing legacy Python payment system + +**Why SpecFact:** + +- Runtime contract enforcement prevents regressions +- CrossHair discovers hidden edge cases +- Formal guarantees (not probabilistic) +- Safety net during modernization + +--- + +## When to Use Both Together + +### ✅ Best of Both Worlds + +**Workflow:** + +1. **Spec-Kit** generates initial specs (fast, LLM-powered) +2. **SpecFact** adds runtime contracts to critical paths (safety net) +3. **Spec-Kit** maintains documentation (living specs) +4. **SpecFact** prevents regressions (contract enforcement) + +### Example Use Case + +**Scenario:** Modernizing multi-language codebase (Python backend + React frontend) + +**Why Both:** + +- **Spec-Kit** for React frontend (multi-language support) +- **SpecFact** for Python backend (runtime enforcement) +- **Spec-Kit** for documentation (markdown specs) +- **SpecFact** for safety net (contract enforcement) + +**Integration:** + +```bash +# Step 1: Use Spec-Kit for initial spec generation +# (Interactive slash commands in GitHub) + +# Step 2: Import Spec-Kit artifacts into SpecFact (via bridge adapter) +specfact import from-bridge --adapter speckit --repo ./my-project + +# Step 3: Add runtime contracts to critical Python paths +# (SpecFact contract decorators) + +# Step 4: Keep both in sync (using adapter registry pattern) +specfact sync bridge --adapter speckit --bundle --repo . --bidirectional +``` + +**Note**: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. + +--- + +## Competitive Positioning + +### Spec-Kit's Strengths + +- ✅ **Multi-language support** - 10+ languages +- ✅ **Native GitHub integration** - Slash commands, Copilot +- ✅ **Fast spec generation** - LLM-powered, interactive +- ✅ **Low learning curve** - Markdown + slash commands +- ✅ **Greenfield focus** - Designed for new projects + +### SpecFact's Strengths + +- ✅ **Runtime enforcement** - Contracts prevent regressions +- ✅ **Symbolic execution** - CrossHair discovers edge cases +- ✅ **Formal guarantees** - Mathematical verification +- ✅ **Brownfield-first** - Designed for legacy code +- ✅ **High-risk focus** - Finance, healthcare, government + +### Where They Overlap + +- ⚠️ **Low-risk brownfield** - Internal tools, non-critical systems + - **Spec-Kit:** Fast documentation, good enough + - **SpecFact:** Slower setup, overkill for low-risk + - **Winner:** Spec-Kit (convenience > rigor for low-risk) + +- ⚠️ **Documentation + enforcement** - Teams want both + - **Spec-Kit:** Use for specs, add tests manually + - **SpecFact:** Use for contracts, generate markdown from contracts + - **Winner:** Depends on team philosophy (docs-first vs. contracts-first) + +--- + +## FAQ + +### Can I use Spec-Kit and SpecFact together? + +**Yes!** They're complementary: + +1. Use Spec-Kit for initial spec generation (fast, LLM-powered) +2. Use SpecFact to add runtime contracts to critical paths (safety net) +3. Keep both in sync with bidirectional sync + +### Which should I choose for brownfield projects? + +**Depends on risk level:** + +- **High-risk** (finance, healthcare, government): **SpecFact** (runtime enforcement) +- **Low-risk** (internal tools, non-critical): **Spec-Kit** (fast documentation) +- **Mixed** (multi-language, some high-risk): **Both** (Spec-Kit for docs, SpecFact for enforcement) + +### Does SpecFact replace Spec-Kit? + +**No.** They serve different purposes: + +- **Spec-Kit:** Documentation, greenfield, multi-language +- **SpecFact:** Runtime enforcement, brownfield, formal guarantees + +Use both together for best results. + +### Does SpecFact work with other specification tools? + +**Yes!** SpecFact CLI uses a plugin-based adapter architecture that supports multiple tools: + +- **Spec-Kit** - Bidirectional sync for interactive authoring +- **OpenSpec** - Read-only sync for change proposal tracking (v0.22.0+) +- **GitHub Issues** - Export change proposals to DevOps backlogs +- **Future**: Linear, Jira, Azure DevOps, and more + +All adapters are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. + +### Can I migrate from Spec-Kit to SpecFact? + +**Yes.** SpecFact can import Spec-Kit artifacts: + +```bash +specfact import from-bridge --adapter speckit --repo ./my-project +``` + +You can also keep using both tools with bidirectional sync via the adapter registry pattern. + +### Does SpecFact work with OpenSpec? + +**Yes!** SpecFact CLI integrates with OpenSpec via the OpenSpec adapter (v0.22.0+): + +```bash +# Read-only sync from OpenSpec to SpecFact +specfact sync bridge --adapter openspec --mode read-only \ + --bundle my-project \ + --repo /path/to/openspec-repo +``` + +OpenSpec focuses on specification anchoring and change tracking, while SpecFact adds brownfield analysis and runtime enforcement. **[Learn more →](openspec-journey.md)** + +--- + +## Decision Matrix + +### Choose Spec-Kit If + +- ✅ Starting greenfield project +- ✅ Need multi-language support +- ✅ Want fast LLM-powered spec generation +- ✅ Documentation-focused workflow +- ✅ Low-risk brownfield project + +### Choose SpecFact If + +- ✅ Modernizing high-risk legacy code +- ✅ Need runtime contract enforcement +- ✅ Want formal guarantees (not probabilistic) +- ✅ Python-heavy codebase +- ✅ Contract-first development culture + +### Choose Both If + +- ✅ Multi-language codebase (some high-risk) +- ✅ Want documentation + enforcement +- ✅ Team uses Spec-Kit, but needs safety net +- ✅ Gradual migration path desired + +--- + +## Next Steps + +1. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete modernization workflow +2. **[Spec-Kit Journey](speckit-journey.md)** - Migration from Spec-Kit +3. **[Examples](../examples/)** - Real-world examples + +--- + +## Support + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) + +--- + +**Questions?** [Open a discussion](https://github.com/nold-ai/specfact-cli/discussions) or [email us](mailto:hello@noldai.com). diff --git a/_site_local/guides/speckit-journey/index.html b/_site_local/guides/speckit-journey/index.html new file mode 100644 index 0000000..c574b29 --- /dev/null +++ b/_site_local/guides/speckit-journey/index.html @@ -0,0 +1,826 @@ + + + + + + + +The Journey: From Spec-Kit to SpecFact | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

The Journey: From Spec-Kit to SpecFact

+ +
+

Spec-Kit and SpecFact are complementary, not competitive.
+Primary Use Case: SpecFact CLI for brownfield code modernization
+Secondary Use Case: Add SpecFact enforcement to Spec-Kit’s interactive authoring for new features

+
+ +
+ +

🎯 Why Level Up?

+ +

What Spec-Kit Does Great

+ +

Spec-Kit is excellent for:

+ +
    +
  • ✅ Interactive Specification - Slash commands (/speckit.specify, /speckit.plan) with AI assistance
    • +
  • ✅ Rapid Prototyping - Quick spec → plan → tasks → code workflow for NEW features
    • +
  • ✅ Learning & Exploration - Great for understanding state machines, contracts, requirements
    • +
  • ✅ IDE Integration - CoPilot chat makes it accessible to less technical developers
    • +
  • ✅ Constitution & Planning - Add constitution, plans, and feature breakdowns for new features
    • +
  • ✅ Single-Developer Projects - Perfect for personal projects and learning
    • +
+ +

Note: Spec-Kit excels at working with new features - you can add constitution, create plans, and break down features for things you’re building from scratch.

+ +

What Spec-Kit Is Designed For (vs. SpecFact CLI)

+ +

Spec-Kit is designed primarily for:

+ +
    +
  • ✅ Greenfield Development - Interactive authoring of new features via slash commands
    • +
  • ✅ Specification-First Workflow - Natural language → spec → plan → tasks → code
    • +
  • ✅ Interactive AI Assistance - CoPilot chat-based specification and planning
    • +
  • ✅ New Feature Planning - Add constitution, plans, and feature breakdowns for new features
    • +
+ +

Spec-Kit is not designed primarily for (but SpecFact CLI provides):

+ +
    +
  • ⚠️ Work with Existing Code - Not designed primarily for analyzing existing repositories or iterating on existing features +
      +
    • Spec-Kit allows you to add constitution, plans, and feature breakdowns for NEW features via interactive slash commands
      • +
    • Current design focuses on greenfield development and interactive authoring
      • +
    • This is the primary area where SpecFact CLI complements Spec-Kit 🎯
      • +
    +
    • +
  • ⚠️ Brownfield Analysis - Not designed primarily for reverse-engineering from existing code
    • +
  • ⚠️ Automated Enforcement - Not designed for CI/CD gates or automated contract validation
    • +
  • ⚠️ Team Collaboration - Not designed for shared plans or deviation detection between developers
    • +
  • ⚠️ Production Quality Gates - Not designed for proof bundles or budget-based enforcement
    • +
  • ⚠️ Multi-Repository Sync - Not designed for cross-repo consistency validation
    • +
  • ⚠️ Deterministic Execution - Designed for interactive AI interactions rather than scriptable automation
    • +
+ +

When to Level Up

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NeedSpec-Kit SolutionSpecFact Solution
Work with existing code ⭐ PRIMARY⚠️ Not designed for - Focuses on new feature authoring✅ import from-code ⭐ - Reverse-engineer existing code to plans (PRIMARY use case)
Iterate on existing features ⭐ PRIMARY⚠️ Not designed for - Focuses on new feature planning✅ Auto-derive plans ⭐ - Understand existing features from code (PRIMARY use case)
Brownfield projects ⭐ PRIMARY⚠️ Not designed for - Designed primarily for greenfield✅ Brownfield analysis ⭐ - Work with existing projects (PRIMARY use case)
Team collaborationManual sharing, no syncShared structured plans (automated bidirectional sync for team collaboration), automated deviation detection
CI/CD integrationManual validationAutomated gates, proof bundles
Production deploymentManual checklistAutomated quality gates
Code reviewManual reviewAutomated deviation detection
ComplianceManual auditProof bundles, reproducible checks
+ +
+ +

🌱 Brownfield Modernization with SpecFact + Spec-Kit

+ +

Best of Both Worlds for Legacy Code

+ +

When modernizing legacy code, you can use both tools together for maximum value:

+ +
    +
  1. Spec-Kit for initial spec generation (fast, LLM-powered)
    2. +
  2. SpecFact for runtime contract enforcement (safety net)
    3. +
  3. Spec-Kit maintains documentation (living specs)
    4. +
  4. SpecFact prevents regressions (contract enforcement)
    5. +
+ +

Workflow: Legacy Code → Modernized Code

+ +
# Step 1: Use SpecFact to extract specs from legacy code
+specfact import from-code --bundle customer-portal --repo ./legacy-app
+
+# Output: Auto-generated project bundle from existing code
+# ✅ Analyzed 47 Python files
+# ✅ Extracted 23 features
+# ✅ Generated 112 user stories
+# ⏱️  Completed in 8.2 seconds
+# 📁 Project bundle: .specfact/projects/customer-portal/
+
+# Step 2: (Optional) Use Spec-Kit to refine specs interactively
+# /speckit.specify --feature "Payment Processing"
+# /speckit.plan --feature "Payment Processing"
+
+# Step 3: Use SpecFact to add runtime contracts
+# Add @icontract decorators to critical paths
+
+# Step 4: Modernize safely with contract safety net
+# Refactor knowing contracts will catch regressions
+
+# Step 5: Keep both in sync
+specfact sync bridge --adapter speckit --bundle customer-portal --repo . --bidirectional --watch
+
+ +

Why This Works

+ +
    +
  • SpecFact code2spec extracts specs from undocumented legacy code automatically
    • +
  • Spec-Kit interactive authoring refines specs with LLM assistance
    • +
  • SpecFact runtime contracts prevent regressions during modernization
    • +
  • Spec-Kit documentation maintains living specs for team
    • +
+ +

Result: Fast spec generation + runtime safety net = confident modernization

+ +

See Also

+ + + +
+ +

🚀 The Onboarding Journey

+ +

Stage 1: Discovery (“What is SpecFact?”)

+ +

Time: < 5 minutes

+ +

Learn how SpecFact complements Spec-Kit:

+ +
# See it in action
+specfact --help
+
+# Read the docs
+cat docs/getting-started.md
+
+ +

What you’ll discover:

+ +
    +
  • ✅ SpecFact imports your Spec-Kit artifacts automatically
    • +
  • ✅ Automated enforcement (CI/CD gates, contract validation)
    • +
  • ✅ Shared plans (bidirectional sync for team collaboration)
    • +
  • ✅ Code vs plan drift detection (automated deviation detection)
    • +
  • ✅ Production readiness (quality gates, proof bundles)
    • +
+ +

Key insight: SpecFact preserves your Spec-Kit workflow - you can use both tools together!

+ +
+ +

Stage 2: First Import (“Try It Out”)

+ +

Time: < 60 seconds

+ +

Import your Spec-Kit project to see what SpecFact adds:

+ +
# 1. Preview what will be imported
+specfact import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run
+
+# 2. Execute import (one command) - bundle name will be auto-detected or you can specify with --bundle
+specfact import from-bridge --adapter speckit --repo ./my-speckit-project --write
+
+# 3. Review generated bundle using CLI commands
+specfact plan review --bundle <bundle-name>
+
+ +

What was created:

+ +
    +
  • Modular project bundle at .specfact/projects/<bundle-name>/ (multiple aspect files)
    • +
  • .specfact/protocols/workflow.protocol.yaml (from FSM if detected)
    • +
  • .specfact/gates/config.yaml (quality gates configuration)
    • +
+ +

Note: Use CLI commands to interact with bundles. Do not edit .specfact files directly.

+ +

What happens:

+ +
    +
  1. Parses Spec-Kit artifacts: specs/[###-feature-name]/spec.md, plan.md, tasks.md, .specify/memory/constitution.md
    2. +
  2. Generates SpecFact plans: Converts Spec-Kit features/stories → SpecFact models
    3. +
  3. Creates enforcement config: Quality gates, CI/CD integration
    4. +
  4. Preserves Spec-Kit artifacts: Your original files remain untouched
    5. +
+ +

Result: Your Spec-Kit specs become production-ready contracts with automated quality gates!

+ +
+ +

Stage 3: Adoption (“Use Both Together”)

+ +

Time: Ongoing (automatic)

+ +

Keep using Spec-Kit interactively, sync automatically with SpecFact:

+ +
# Enable bidirectional sync (bridge-based, adapter-agnostic)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Workflow:

+ +
# 1. Continue using Spec-Kit interactively (slash commands)
+/speckit.specify --feature "User Authentication"
+/speckit.plan --feature "User Authentication"
+/speckit.tasks --feature "User Authentication"
+
+# 2. SpecFact automatically syncs new artifacts (watch mode)
+# → Detects changes in specs/[###-feature-name]/
+# → Imports new spec.md, plan.md, tasks.md
+# → Updates .specfact/projects/<bundle-name>/ aspect files
+# → Enables shared plans for team collaboration
+
+# 3. Detect code vs plan drift automatically
+specfact plan compare --code-vs-plan
+# → Compares intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code)
+# → Identifies deviations automatically (not just artifact consistency like Spec-Kit's /speckit.analyze)
+# → Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift"
+
+# 4. Enable automated enforcement
+specfact enforce stage --preset balanced
+
+# 5. CI/CD automatically validates (GitHub Action)
+# → Runs on every PR
+# → Blocks HIGH severity issues
+# → Generates proof bundles
+
+ +

What you get:

+ +
    +
  • ✅ Interactive authoring (Spec-Kit): Use slash commands for rapid prototyping
    • +
  • ✅ Automated enforcement (SpecFact): CI/CD gates catch issues automatically
    • +
  • ✅ Team collaboration (SpecFact): Shared plans, deviation detection
    • +
  • ✅ Production readiness (SpecFact): Quality gates, proof bundles
    • +
+ +

Best of both worlds: Spec-Kit for authoring, SpecFact for enforcement!

+ +
+ +

Stage 4: Migration (“Full SpecFact Workflow”)

+ +

Time: Progressive (1-4 weeks)

+ +

Optional: Migrate to full SpecFact workflow (or keep using both tools together)

+ +

Week 1: Import + Sync

+ +
# Import existing Spec-Kit project
+specfact import from-bridge --adapter speckit --repo . --write
+
+# Enable bidirectional sync (bridge-based, adapter-agnostic)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Result: Both tools working together seamlessly.

+ +

Week 2-3: Enable Enforcement (Shadow Mode)

+ +
# Start in shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# Set up CrossHair for contract exploration
+specfact repro setup
+
+# Review what would be blocked
+specfact repro --verbose
+
+# Apply auto-fixes for violations (if available)
+specfact repro --fix --verbose
+
+ +

Result: See what SpecFact would catch, no blocking yet. Auto-fixes can be applied for Semgrep violations.

+ +

Week 4: Enable Balanced Enforcement

+ +
# Enable balanced mode (block HIGH, warn MEDIUM)
+specfact enforce stage --preset balanced
+
+# Test with real PR
+git checkout -b test-enforcement
+# Make a change that violates contracts
+specfact repro  # Should block HIGH issues
+
+# Or apply auto-fixes first
+specfact repro --fix  # Apply Semgrep auto-fixes, then validate
+
+ +

Result: Automated enforcement catching critical issues. Auto-fixes can be applied before validation.

+ +

Week 5+: Full SpecFact Workflow (Optional)

+ +
# Enable strict enforcement
+specfact enforce stage --preset strict
+
+# Full automation (CI/CD, brownfield analysis, etc.)
+# (CrossHair setup already done in Week 3)
+specfact repro --budget 120 --verbose
+
+ +

Result: Complete SpecFact workflow - or keep using both tools together!

+ +
+ +

📋 Step-by-Step Migration

+ +

Step 1: Preview Migration

+ +
# See what will be imported (safe - no changes)
+specfact import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run
+
+ +

Expected Output:

+ +
🔍 Analyzing Spec-Kit project via bridge adapter...
+✅ Found .specify/ directory (modern format)
+✅ Found specs/001-user-authentication/spec.md
+✅ Found specs/001-user-authentication/plan.md
+✅ Found specs/001-user-authentication/tasks.md
+✅ Found .specify/memory/constitution.md
+
+**💡 Tip**: If constitution is missing or minimal, run `specfact sdd constitution bootstrap --repo .` to auto-generate from repository analysis.
+
+📊 Migration Preview:
+  - Will create: .specfact/projects/<bundle-name>/ (modular project bundle)
+  - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected)
+  - Will create: .specfact/gates/config.yaml
+  - Will convert: Spec-Kit features → SpecFact Feature models
+  - Will convert: Spec-Kit user stories → SpecFact Story models
+  
+🚀 Ready to migrate (use --write to execute)
+
+ +

Step 2: Execute Migration

+ +
# Execute migration (creates SpecFact artifacts)
+specfact import from-bridge \
+  --adapter speckit \
+  --repo ./my-speckit-project \
+  --write \
+  --report migration-report.md
+
+ +

What it does:

+ +
    +
  1. Parses Spec-Kit artifacts (via bridge adapter): +
      +
    • specs/[###-feature-name]/spec.md → Features, user stories, requirements
      • +
    • specs/[###-feature-name]/plan.md → Technical context, architecture
      • +
    • specs/[###-feature-name]/tasks.md → Tasks, story mappings
      • +
    • .specify/memory/constitution.md → Principles, constraints
      • +
    +
    2. +
  2. Generates SpecFact artifacts: +
      +
    • .specfact/projects/<bundle-name>/ - Modular project bundle (multiple aspect files)
      • +
    • .specfact/protocols/workflow.protocol.yaml - FSM protocol (if detected)
      • +
    • .specfact/gates/config.yaml - Quality gates configuration
      • +
    +
    3. +
  3. Preserves Spec-Kit artifacts: +
      +
    • Original files remain untouched
      • +
    • Bidirectional sync keeps both aligned
      • +
    +
    4. +
+ +

Step 3: Review Generated Artifacts

+ +
# Review plan bundle using CLI commands
+specfact plan review --bundle <bundle-name>
+
+# Review enforcement config using CLI commands
+specfact enforce show-config
+
+# Review migration report
+cat migration-report.md
+
+ +

Note: Use CLI commands to interact with bundles. Do not edit .specfact files directly.

+ +

What to check:

+ +
    +
  • ✅ Features/stories correctly mapped from Spec-Kit
    • +
  • ✅ Acceptance criteria preserved
    • +
  • ✅ Business context extracted from constitution
    • +
  • ✅ Enforcement config matches your needs
    • +
+ +

Step 4: Enable Shared Plans (Bidirectional Sync)

+ +

Shared structured plans enable team collaboration with automated bidirectional sync. Unlike Spec-Kit’s manual markdown sharing, SpecFact automatically keeps plans synchronized across team members.

+ +
# One-time sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Continuous watch mode (recommended for team collaboration)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+ +

What it syncs:

+ +
    +
  • Spec-Kit → SpecFact: New spec.md, plan.md, tasks.md → Updated .specfact/projects/<bundle-name>/ aspect files
    • +
  • SpecFact → Spec-Kit: Changes to .specfact/projects/<bundle-name>/ → Updated Spec-Kit markdown with all required fields auto-generated: +
      +
    • spec.md: Frontmatter, INVSEST criteria, Scenarios (Primary, Alternate, Exception, Recovery)
      • +
    • plan.md: Constitution Check, Phases, Technology Stack (from constraints)
      • +
    • tasks.md: Phase organization, Story mappings ([US1], [US2]), Parallel markers
      • +
    +
    • +
  • Team collaboration: Multiple developers can work on the same plan with automated synchronization
    • +
  • No manual editing required: All Spec-Kit fields are auto-generated - ready for /speckit.analyze without additional work
    • +
+ +

Step 5: Enable Enforcement

+ +
# Week 1-2: Shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# Week 3-4: Balanced mode (block HIGH, warn MEDIUM)
+specfact enforce stage --preset balanced
+
+# Week 5+: Strict mode (block MEDIUM+)
+specfact enforce stage --preset strict
+
+ +

Step 6: Validate

+ +
# Set up CrossHair for contract exploration (one-time setup)
+specfact repro setup
+
+# Run all checks
+specfact repro --verbose
+
+# Check CI/CD integration
+git push origin feat/specfact-migration
+# → GitHub Action runs automatically
+# → PR blocked if HIGH severity issues found
+
+ +
+ +

💡 Best Practices

+ +

1. Start in Shadow Mode

+ +
# Always start with shadow mode (no blocking)
+specfact enforce stage --preset minimal
+specfact repro
+
+ +

Why: See what SpecFact would catch before enabling blocking.

+ +

2. Use Shared Plans (Bidirectional Sync)

+ +
# Enable bidirectional sync for team collaboration
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Why: Shared structured plans enable team collaboration with automated bidirectional sync. Unlike Spec-Kit’s manual markdown sharing, SpecFact automatically keeps plans synchronized across team members. Continue using Spec-Kit interactively, get SpecFact automation automatically.

+ +

3. Progressive Enforcement

+ +
# Week 1: Shadow (observe)
+specfact enforce stage --preset minimal
+
+# Week 2-3: Balanced (block HIGH)
+specfact enforce stage --preset balanced
+
+# Week 4+: Strict (block MEDIUM+)
+specfact enforce stage --preset strict
+
+ +

Why: Gradual adoption reduces disruption and builds team confidence.

+ +

4. Keep Spec-Kit Artifacts

+ +

Don’t delete Spec-Kit files - they’re still useful:

+ +
    +
  • ✅ Interactive authoring (slash commands)
    • +
  • ✅ Fallback if SpecFact has issues
    • +
  • ✅ Team members who prefer Spec-Kit workflow
    • +
+ +

Bidirectional sync keeps both aligned automatically.

+ +
+ +

❓ FAQ

+ +

Q: Do I need to stop using Spec-Kit?

+ +

A: No! SpecFact works alongside Spec-Kit. Use Spec-Kit for interactive authoring (new features), SpecFact for automated enforcement and existing code analysis.

+ +

Q: What happens to my Spec-Kit artifacts?

+ +

A: They’re preserved - SpecFact imports them but doesn’t modify them. Bidirectional sync keeps both aligned.

+ +

Q: Can I export back to Spec-Kit?

+ +

A: Yes! SpecFact can export back to Spec-Kit format. Your original files are never modified.

+ +

Q: What if I prefer Spec-Kit workflow?

+ +

A: Keep using Spec-Kit! Bidirectional sync automatically keeps SpecFact artifacts updated. Use SpecFact for CI/CD enforcement and brownfield analysis.

+ +

Q: Does SpecFact replace Spec-Kit?

+ +

A: No - they’re complementary. Spec-Kit excels at interactive authoring for new features, SpecFact adds automation, enforcement, and brownfield analysis capabilities.

+ +
+ +

See Also

+ + + + + + + + + + + + + +

Getting Started

+ + + +
+ +

Next Steps:

+ +
    +
  1. Try it: specfact import from-bridge --adapter speckit --repo . --dry-run
    2. +
  2. Import: specfact import from-bridge --adapter speckit --repo . --write
    3. +
  3. Sync: specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
    4. +
  4. Enforce: specfact enforce stage --preset minimal (start shadow mode)
    5. +
+ +
+ +
+

Remember: Spec-Kit and SpecFact are complementary. Use Spec-Kit for interactive authoring, add SpecFact for automated enforcement. Best of both worlds! 🚀

+
+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/guides/specmatic-integration.md b/_site_local/guides/specmatic-integration.md new file mode 100644 index 0000000..009b4e3 --- /dev/null +++ b/_site_local/guides/specmatic-integration.md @@ -0,0 +1,646 @@ +# Specmatic Integration Guide + +> **API Contract Testing with Specmatic** +> Validate OpenAPI/AsyncAPI specifications, check backward compatibility, and run mock servers + +--- + +## Overview + +SpecFact CLI integrates with **Specmatic** to provide service-level contract testing for API specifications. This complements SpecFact's code-level contracts (icontract, beartype, CrossHair) by adding API contract validation. + +**What Specmatic adds:** + +- ✅ **OpenAPI/AsyncAPI validation** - Validate specification structure and examples +- ✅ **Backward compatibility checking** - Detect breaking changes between spec versions +- ✅ **Mock server generation** - Run development mock servers from specifications +- ✅ **Test suite generation** - Auto-generate contract tests from specs + +--- + +## Quick Reference: When to Use What + +| Command | Purpose | Output | When to Use | +|---------|---------|--------|-------------| +| `spec validate` | **Check if spec is valid** | Validation report (console) | Before committing spec changes, verify spec correctness | +| `spec generate-tests` | **Create tests to validate API** | Test files (on disk) | To test your API implementation matches the spec | +| `spec mock` | **Run mock server** | Running server | Test client code, frontend development | +| `spec backward-compat` | **Check breaking changes** | Compatibility report | When updating API versions | + +**Key Difference:** + +- `validate` = "Is my spec file correct?" (checks the specification itself) +- `generate-tests` = "Create tests to verify my API matches the spec" (creates executable tests) + +**Typical Workflow:** + +```bash +# 1. Validate spec is correct +specfact spec validate --bundle my-api + +# 2. Generate tests from spec +specfact spec generate-tests --bundle my-api --output tests/ + +# 3. Run tests against your API +specmatic test --spec ... --host http://localhost:8000 +``` + +--- + +## Installation + +**Important**: Specmatic is a **Java CLI tool**, not a Python package. It must be installed separately. + +### Install Specmatic + +Visit the [Specmatic download page](https://docs.specmatic.io/download.html) for detailed installation instructions. + +**Quick install options:** + +```bash +# Option 1: Direct installation (requires Java 17+) +# macOS/Linux +curl https://docs.specmatic.io/install-specmatic.sh | bash + +# Windows (PowerShell) +irm https://docs.specmatic.io/install-specmatic.ps1 | iex + +# Option 2: Via npm/npx (requires Java/JRE and Node.js) +# Run directly without installation +npx specmatic --version + +# Option 3: macOS (Homebrew) +brew install specmatic + +# Verify installation +specmatic --version +``` + +**Note**: SpecFact CLI automatically detects Specmatic whether it's installed directly or available via `npx`. If you have Java/JRE installed, you can use `npx specmatic` without a separate installation. + +### Verify Integration + +SpecFact CLI will automatically detect if Specmatic is available: + +```bash +# Check if Specmatic is detected +specfact spec validate --help + +# If Specmatic is not installed, you'll see: +# ✗ Specmatic not available: Specmatic CLI not found. Install from: https://docs.specmatic.io/ +``` + +--- + +## Commands + +### Validate Specification + +Validate an OpenAPI/AsyncAPI specification. Can validate a single file or all contracts in a project bundle: + +```bash +# Validate a single spec file +specfact spec validate api/openapi.yaml + +# With backward compatibility check +specfact spec validate api/openapi.yaml --previous api/openapi.v1.yaml + +# Validate all contracts in active bundle (interactive selection) +specfact spec validate + +# Validate all contracts in specific bundle +specfact spec validate --bundle legacy-api + +# Non-interactive: validate all contracts in active bundle +specfact spec validate --bundle legacy-api --no-interactive +``` + +**CLI-First Pattern**: The command uses the active plan (from `specfact plan select`) as default, or you can specify `--bundle`. Never requires direct `.specfact` paths - always use the CLI interface. + +**What it checks:** + +- Schema structure validation +- Example generation test +- Backward compatibility (if previous version provided) + +### Check Backward Compatibility + +Compare two specification versions: + +```bash +specfact spec backward-compat api/openapi.v1.yaml api/openapi.v2.yaml +``` + +**Output:** + +- ✓ Compatible - No breaking changes detected +- ✗ Breaking changes - Lists incompatible changes + +### Generate Test Suite + +Auto-generate contract tests from specification. Can generate for a single file or all contracts in a bundle: + +```bash +# Generate for a single spec file +specfact spec generate-tests api/openapi.yaml + +# Generate to custom location +specfact spec generate-tests api/openapi.yaml --output tests/specmatic/ + +# Generate tests for all contracts in active bundle +specfact spec generate-tests --bundle legacy-api + +# Generate tests for all contracts in specific bundle +specfact spec generate-tests --bundle legacy-api --output tests/contract/ +``` + +**CLI-First Pattern**: Uses active plan as default, or specify `--bundle`. Never requires direct `.specfact` paths. + +### What Can You Do With Generated Tests? + +The tests generated by `spec generate-tests` are **executable contract tests** that validate your API implementation against your OpenAPI/AsyncAPI specification. Here's a complete walkthrough: + +#### Understanding Generated Tests + +When you run `specfact spec generate-tests`, Specmatic creates test files that: + +- **Validate request format**: Check that requests match the spec (headers, body, query params) +- **Validate response format**: Verify responses match the spec (status codes, headers, body schema) +- **Test all endpoints**: Ensure all endpoints defined in the spec are implemented +- **Check data types**: Validate that data types and constraints are respected +- **Property-based testing**: Automatically generate diverse test data to find edge cases + +#### Step-by-Step: Using Generated Tests + +**Step 1: Generate Tests from Your Contract** + +```bash +# Generate tests for all contracts in your bundle +specfact spec generate-tests --bundle my-api --output tests/contract/ + +# Output: +# [1/5] Generating test suite from: .specfact/projects/my-api/contracts/api.openapi.yaml +# ✓ Test suite generated: tests/contract/ +# ... +# ✓ Generated tests for 5 contract(s) +``` + +**Step 2: Review Generated Test Files** + +The tests are generated in the output directory (default: `.specfact/specmatic-tests/`): + +```bash +# Check what was generated +ls -la tests/contract/ +# Output shows Specmatic test files (format depends on Specmatic version) +``` + +**Step 3: Start Your API Server** + +Before running tests, start your API implementation: + +```bash +# Example: Start FastAPI server +python -m uvicorn main:app --port 8000 + +# Or Flask +python app.py + +# Or any other API server +# Make sure it's running on the expected host/port +``` + +**Step 4: Run Tests Against Your API** + +Use Specmatic's test runner to execute the generated tests: + +```bash +# Run tests against your running API +specmatic test \ + --spec .specfact/projects/my-api/contracts/api.openapi.yaml \ + --host http://localhost:8000 + +# Output: +# ✓ GET /api/users - Request/Response match contract +# ✓ POST /api/users - Request/Response match contract +# ✗ GET /api/products - Response missing required field 'price' +# ... +``` + +**Step 5: Fix Issues and Re-run** + +If tests fail, fix your API implementation and re-run: + +```bash +# Fix the API code +# ... make changes ... + +# Restart API server +python -m uvicorn main:app --port 8000 + +# Re-run tests +specmatic test --spec ... --host http://localhost:8000 +``` + +#### Complete Example: Contract-Driven Development Workflow + +Here's a full workflow from contract to tested implementation: + +```bash +# 1. Import existing code and extract contracts +specfact import from-code --bundle user-api --repo . + +# 2. Validate contracts are correct +specfact spec validate --bundle user-api + +# Output: +# [1/3] Validating specification: contracts/user-api.openapi.yaml +# ✓ Specification is valid: user-api.openapi.yaml +# ... + +# 3. Generate tests from validated contracts +specfact spec generate-tests --bundle user-api --output tests/contract/ + +# Output: +# [1/3] Generating test suite from: contracts/user-api.openapi.yaml +# ✓ Test suite generated: tests/contract/ +# ✓ Generated tests for 3 contract(s) + +# 4. Start your API server +python -m uvicorn api.main:app --port 8000 & +sleep 3 # Wait for server to start + +# 5. Run contract tests +specmatic test \ + --spec .specfact/projects/user-api/contracts/user-api.openapi.yaml \ + --host http://localhost:8000 + +# Output: +# Running contract tests... +# ✓ GET /api/users - Passed +# ✓ POST /api/users - Passed +# ✓ GET /api/users/{id} - Passed +# All tests passed! ✓ +``` + +#### CI/CD Integration Example + +Add contract testing to your CI/CD pipeline: + +```yaml +# .github/workflows/contract-tests.yml +name: Contract Tests + +on: [push, pull_request] + +jobs: + contract-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Install Specmatic + run: | + curl https://docs.specmatic.io/install-specmatic.sh | bash + + - name: Install SpecFact CLI + run: pip install specfact-cli + + - name: Generate contract tests + run: | + specfact spec generate-tests \ + --bundle my-api \ + --output tests/contract/ \ + --no-interactive + + - name: Start API server + run: | + python -m uvicorn main:app --port 8000 & + sleep 5 + + - name: Run contract tests + run: | + specmatic test \ + --spec .specfact/projects/my-api/contracts/api.openapi.yaml \ + --host http://localhost:8000 +``` + +#### Testing Against Mock Servers + +You can also test your client code against Specmatic mock servers: + +```bash +# Terminal 1: Start mock server +specfact spec mock --bundle my-api --port 9000 + +# Terminal 2: Run your client code against mock +python client.py # Your client code that calls the API + +# The mock server: +# - Validates requests match the spec +# - Returns spec-compliant responses +# - Helps test client code without a real API +``` + +#### Benefits of Using Generated Tests + +1. **Automated Validation**: Catch contract violations automatically +2. **Early Detection**: Find issues before deployment +3. **Documentation**: Tests serve as executable examples +4. **Confidence**: Ensure API changes don't break contracts +5. **Integration Safety**: Prevent breaking changes between services +6. **Property-Based Testing**: Automatically test edge cases and boundary conditions + +#### Troubleshooting Test Execution + +**Tests fail with "Connection refused":** + +```bash +# Make sure your API server is running +curl http://localhost:8000/health # Test server is up + +# Check the host/port in your test command matches your server +specmatic test --spec ... --host http://localhost:8000 +``` + +**Tests fail with "Response doesn't match contract":** + +```bash +# Check what the actual response is +curl -v http://localhost:8000/api/users + +# Compare with your OpenAPI spec +# Fix your API implementation to match the spec +``` + +**Tests pass but you want to see details:** + +```bash +# Use verbose mode (if supported by Specmatic version) +specmatic test --spec ... --host ... --verbose +``` + +### Run Mock Server + +Start a mock server for development. Can use a single spec file or select from bundle contracts: + +```bash +# Auto-detect spec file from current directory +specfact spec mock + +# Specify spec file and port +specfact spec mock --spec api/openapi.yaml --port 9000 + +# Use examples mode (less strict) +specfact spec mock --spec api/openapi.yaml --examples + +# Select contract from active bundle (interactive) +specfact spec mock --bundle legacy-api + +# Use specific bundle (non-interactive, uses first contract) +specfact spec mock --bundle legacy-api --no-interactive +``` + +**CLI-First Pattern**: Uses active plan as default, or specify `--bundle`. Interactive selection when multiple contracts available. + +**Mock server features:** + +- Serves API endpoints based on specification +- Validates requests against spec +- Returns example responses +- Press Ctrl+C to stop + +--- + +## Integration with Other Commands + +Specmatic validation is automatically integrated into: + +### Import Command + +When importing code, SpecFact auto-detects and validates OpenAPI/AsyncAPI specs: + +```bash +# Import with bundle (uses active plan if --bundle not specified) +specfact import from-code --bundle legacy-api --repo . + +# Automatically validates: +# - Repo-level OpenAPI/AsyncAPI specs (openapi.yaml, asyncapi.yaml) +# - Bundle contract files referenced in features +# - Suggests starting mock server if API specs found +``` + +### Enforce Command + +SDD enforcement includes Specmatic validation for all contracts referenced in the bundle: + +```bash +# Enforce SDD (uses active plan if --bundle not specified) +specfact enforce sdd --bundle legacy-api + +# Automatically validates: +# - All contract files referenced in bundle features +# - Includes validation results in enforcement report +# - Reports deviations for invalid contracts +``` + +### Sync Command + +Repository sync validates specs before synchronization: + +```bash +# Sync bridge (uses active plan if --bundle not specified) +specfact sync bridge --bundle legacy-api --repo . + +# Automatically validates: +# - OpenAPI/AsyncAPI specs before sync operation +# - Prevents syncing invalid contracts +# - Reports validation errors before proceeding +``` + +--- + +## How It Works + +### Architecture + +```text +┌─────────────────────────────────────────────────────────┐ +│ SpecFact Complete Stack │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ Layer 1: Code-Level Contracts (Current) │ +│ ├─ icontract: Function preconditions/postconditions │ +│ ├─ beartype: Runtime type validation │ +│ └─ CrossHair: Symbolic execution & counterexamples │ +│ │ +│ Layer 2: Service-Level Contracts (Specmatic) │ +│ ├─ OpenAPI/AsyncAPI validation │ +│ ├─ Backward compatibility checking │ +│ ├─ Mock server for development │ +│ └─ Contract testing automation │ +│ │ +└─────────────────────────────────────────────────────────┘ +``` + +### Integration Pattern + +SpecFact calls Specmatic via subprocess: + +1. **Check availability** - Verifies Specmatic CLI is in PATH +2. **Execute command** - Runs Specmatic CLI with appropriate arguments +3. **Parse results** - Extracts validation results and errors +4. **Display output** - Shows results in SpecFact's rich console format + +--- + +## Examples + +### Example 1: Validate API Spec During Import + +```bash +# Project has openapi.yaml +specfact import from-code --bundle api-service --repo . + +# Output: +# ✓ Import complete! +# 🔍 Found 1 API specification file(s) +# Validating openapi.yaml with Specmatic... +# ✓ openapi.yaml is valid +# Validated 3 bundle contract(s), 0 failed. +# 💡 Tip: Run 'specfact spec mock --bundle api-service' to start a mock server for development +``` + +### Example 2: Check Breaking Changes + +```bash +# Compare API versions +specfact spec backward-compat api/v1/openapi.yaml api/v2/openapi.yaml + +# Output: +# ✗ Breaking changes detected +# Breaking Changes: +# - Removed endpoint /api/v1/users +# - Changed response schema for /api/v1/products +``` + +### Example 3: Development Workflow with Bundle + +```bash +# 1. Set active bundle +specfact plan select api-service + +# 2. Validate all contracts in bundle (interactive selection) +specfact spec validate +# Shows list of contracts, select by number or 'all' + +# 3. Start mock server from bundle (interactive selection) +specfact spec mock --bundle api-service --port 9000 + +# 4. In another terminal, test against mock +curl http://localhost:9000/api/users + +# 5. Generate tests for all contracts +specfact spec generate-tests --bundle api-service --output tests/ +``` + +### Example 4: CI/CD Workflow (Non-Interactive) + +```bash +# 1. Validate all contracts in bundle (non-interactive) +specfact spec validate --bundle api-service --no-interactive + +# 2. Generate tests for all contracts +specfact spec generate-tests --bundle api-service --output tests/ --no-interactive + +# 3. Run generated tests +pytest tests/specmatic/ +``` + +--- + +## Troubleshooting + +### Specmatic Not Found + +**Error:** + +```text +✗ Specmatic not available: Specmatic CLI not found. Install from: https://docs.specmatic.io/ +``` + +**Solution:** + +1. Install Specmatic from [https://docs.specmatic.io/](https://docs.specmatic.io/) +2. Ensure `specmatic` is in your PATH +3. Verify with: `specmatic --version` + +### Validation Failures + +**Error:** + +```text +✗ Specification validation failed +Errors: + - Schema validation failed: missing required field 'info' +``` + +**Solution:** + +1. Check your OpenAPI/AsyncAPI spec format +2. Validate with: `specmatic validate your-spec.yaml` +3. Review Specmatic documentation for spec requirements + +### Mock Server Won't Start + +**Error:** + +```text +✗ Failed to start mock server: Port 9000 already in use +``` + +**Solution:** + +1. Use a different port: `specfact spec mock --port 9001` +2. Stop the existing server on that port +3. Check for other processes: `lsof -i :9000` + +--- + +## Best Practices + +1. **Validate early** - Run `specfact spec validate` before committing spec changes +2. **Check compatibility** - Use `specfact spec backward-compat` when updating API versions +3. **Use mock servers** - Start mock servers during development to test integrations +4. **Generate tests** - Auto-generate tests for CI/CD pipelines +5. **Integrate in workflows** - Let SpecFact auto-validate specs during import/enforce/sync + +--- + +## See Also + +### Related Guides + +- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations +- [Command Chains Reference](command-chains.md) - Complete workflows including [API Contract Development Chain](command-chains.md#4-api-contract-development-chain) +- [Common Tasks Index](common-tasks.md) - Quick reference for API-related tasks +- [Contract Testing Workflow](contract-testing-workflow.md) - Contract testing patterns + +### Related Commands + +- [Command Reference - Spec Commands](../reference/commands.md#spec-commands) - Full command documentation +- [Command Reference - Contract Commands](../reference/commands.md#contract-commands) - Contract verification commands + +### Related Examples + +- [API Contract Development Examples](../examples/) - Real-world examples + +### External Documentation + +- **[Specmatic Official Docs](https://docs.specmatic.io/)** - Specmatic documentation +- **[OpenAPI Specification](https://swagger.io/specification/)** - OpenAPI spec format +- **[AsyncAPI Specification](https://www.asyncapi.com/)** - AsyncAPI spec format + +--- + +**Note**: Specmatic is an external tool and must be installed separately. SpecFact CLI provides integration but does not include Specmatic itself. diff --git a/_site_local/guides/workflows.md b/_site_local/guides/workflows.md new file mode 100644 index 0000000..8cc8c0d --- /dev/null +++ b/_site_local/guides/workflows.md @@ -0,0 +1,546 @@ +# Common Workflows + +Daily workflows for using SpecFact CLI effectively. + +> **Primary Workflow**: Brownfield code modernization +> **Secondary Workflow**: Spec-Kit bidirectional sync + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in. + +--- + +## Brownfield Code Modernization ⭐ PRIMARY + +Reverse engineer existing code and enforce contracts incrementally. + +**Integration**: Works with VS Code, Cursor, GitHub Actions, pre-commit hooks. See [Integration Showcases](../examples/integration-showcases/) for real examples. + +### Step 1: Analyze Legacy Code + +```bash +# Full repository analysis +specfact import from-code --bundle legacy-api --repo . + +# For large codebases, analyze specific modules: +specfact import from-code --bundle core-module --repo . --entry-point src/core +specfact import from-code --bundle api-module --repo . --entry-point src/api +``` + +### Step 2: Review Extracted Specs + +```bash +# Review bundle to understand extracted specs +specfact plan review --bundle legacy-api + +# Or get structured findings for analysis +specfact plan review --bundle legacy-api --list-findings --findings-format json +``` + +**Note**: Use CLI commands to interact with bundles. The bundle structure (`.specfact/projects//`) is managed by SpecFact CLI - use commands like `plan review`, `plan add-feature`, `plan update-feature` to modify bundles, not direct file editing. + +### Step 3: Add Contracts Incrementally + +```bash +# Start in shadow mode +specfact enforce stage --preset minimal +``` + +See [Brownfield Journey Guide](brownfield-journey.md) for complete workflow. + +### Partial Repository Coverage + +For large codebases or monorepos with multiple projects, use `--entry-point` to analyze specific subdirectories: + +```bash +# Analyze individual projects in a monorepo +specfact import from-code --bundle api-service --repo . --entry-point projects/api-service +specfact import from-code --bundle web-app --repo . --entry-point projects/web-app +specfact import from-code --bundle mobile-app --repo . --entry-point projects/mobile-app + +# Analyze specific modules for incremental modernization +specfact import from-code --bundle core-module --repo . --entry-point src/core +specfact import from-code --bundle integrations-module --repo . --entry-point src/integrations +``` + +**Benefits:** + +- **Faster analysis** - Focus on specific modules for quicker feedback +- **Incremental modernization** - Modernize one module at a time +- **Multi-bundle support** - Create separate project bundles for different projects/modules +- **Better organization** - Keep bundles organized by project boundaries + +**Note:** When using `--entry-point`, each analysis creates a separate project bundle. Use `specfact plan compare` to compare different bundles. + +--- + +## Bridge Adapter Sync (Secondary) + +Keep SpecFact synchronized with external tools (Spec-Kit, OpenSpec, GitHub Issues, etc.) via the plugin-based adapter registry. + +**Supported Adapters**: + +- **Spec-Kit** (`--adapter speckit`) - Bidirectional sync for interactive authoring +- **OpenSpec** (`--adapter openspec`) - Read-only sync for change proposal tracking (v0.22.0+) +- **GitHub Issues** (`--adapter github`) - Export change proposals to DevOps backlogs +- **Future**: Linear, Jira, Azure DevOps, and more + +**Note**: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. + +### Spec-Kit Bidirectional Sync + +Keep Spec-Kit and SpecFact synchronized automatically. + +#### One-Time Sync + +```bash +specfact sync bridge --adapter speckit --bundle --repo . --bidirectional +``` + +**What it does**: + +- Syncs Spec-Kit artifacts → SpecFact project bundles +- Syncs SpecFact project bundles → Spec-Kit artifacts +- Resolves conflicts automatically (SpecFact takes priority) + +**When to use**: + +- After migrating from Spec-Kit +- When you want to keep both tools in sync +- Before making changes in either tool + +#### Watch Mode (Continuous Sync) + +```bash +specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 +``` + +**What it does**: + +- Monitors file system for changes +- Automatically syncs when files are created/modified +- Runs continuously until interrupted (Ctrl+C) + +**When to use**: + +- During active development +- When multiple team members use both tools +- For real-time synchronization + +**Example**: + +```bash +# Terminal 1: Start watch mode +specfact sync bridge --adapter speckit --bundle my-project --repo . --bidirectional --watch --interval 5 + +# Terminal 2: Make changes in Spec-Kit +echo "# New Feature" >> specs/002-new-feature/spec.md + +# Watch mode automatically detects and syncs +# Output: "Detected 1 change(s), syncing..." +``` + +#### What Gets Synced + +- `specs/[###-feature-name]/spec.md` ↔ `.specfact/projects//features/FEATURE-*.yaml` +- `specs/[###-feature-name]/plan.md` ↔ `.specfact/projects//product.yaml` +- `specs/[###-feature-name]/tasks.md` ↔ `.specfact/projects//features/FEATURE-*.yaml` +- `.specify/memory/constitution.md` ↔ SpecFact business context (business.yaml) +- `specs/[###-feature-name]/contracts/*.yaml` ↔ `.specfact/protocols/*.yaml` + +**Note**: When syncing from SpecFact to Spec-Kit, all required Spec-Kit fields (frontmatter, INVSEST criteria, Constitution Check, Phases, Technology Stack, Story mappings) are automatically generated. No manual editing required - generated artifacts are ready for `/speckit.analyze`. + +### OpenSpec Read-Only Sync + +Sync OpenSpec change proposals to SpecFact (v0.22.0+): + +```bash +# Read-only sync from OpenSpec to SpecFact +specfact sync bridge --adapter openspec --mode read-only \ + --bundle my-project \ + --repo /path/to/openspec-repo +``` + +**What it does**: + +- Reads OpenSpec change proposals from `openspec/changes/` +- Syncs proposals to SpecFact change tracking +- Read-only mode (does not modify OpenSpec files) + +**When to use**: + +- When working with OpenSpec change proposals +- For tracking OpenSpec proposals in SpecFact format +- Before exporting proposals to DevOps tools + +See [OpenSpec Journey Guide](openspec-journey.md) for complete integration workflow. + +--- + +## Repository Sync Workflow + +Keep plan artifacts updated as code changes. + +### One-Time Repository Sync + +```bash +specfact sync repository --repo . --target .specfact +``` + +**What it does**: + +- Analyzes code changes +- Updates plan artifacts +- Detects deviations from manual plans + +**When to use**: + +- After making code changes +- Before comparing plans +- To update auto-derived plans + +### Repository Watch Mode (Continuous Sync) + +```bash +specfact sync repository --repo . --watch --interval 5 +``` + +**What it does**: + +- Monitors code files for changes +- Automatically updates plan artifacts +- Triggers sync when files are created/modified/deleted + +**When to use**: + +- During active development +- For real-time plan updates +- When code changes frequently + +**Example**: + +```bash +# Terminal 1: Start watch mode +specfact sync repository --repo . --watch --interval 5 + +# Terminal 2: Make code changes +echo "class NewService:" >> src/new_service.py + +# Watch mode automatically detects and syncs +# Output: "Detected 1 change(s), syncing..." +``` + +--- + +## Enforcement Workflow + +Progressive enforcement from observation to blocking. + +### Step 1: Shadow Mode (Observe Only) + +```bash +specfact enforce stage --preset minimal +``` + +**What it does**: + +- Sets enforcement to LOG only +- Observes violations without blocking +- Collects metrics and reports + +**When to use**: + +- Initial setup +- Understanding current state +- Baseline measurement + +### Step 2: Balanced Mode (Warn on Issues) + +```bash +specfact enforce stage --preset balanced +``` + +**What it does**: + +- BLOCKs HIGH severity violations +- WARNs on MEDIUM severity violations +- LOGs LOW severity violations + +**When to use**: + +- After stabilization period +- When ready for warnings +- Before production deployment + +### Step 3: Strict Mode (Block Everything) + +```bash +specfact enforce stage --preset strict +``` + +**What it does**: + +- BLOCKs all violations (HIGH, MEDIUM, LOW) +- Enforces all rules strictly +- Production-ready enforcement + +**When to use**: + +- Production environments +- After full validation +- When all issues are resolved + +### Running Validation + +```bash +# First-time setup: Configure CrossHair for contract exploration +specfact repro setup + +# Quick validation +specfact repro + +# Verbose validation with budget +specfact repro --verbose --budget 120 + +# Apply auto-fixes +specfact repro --fix --budget 120 +``` + +**What it does**: + +- `repro setup` configures CrossHair for contract exploration (one-time setup) +- `repro` validates contracts +- Checks types +- Detects async anti-patterns +- Validates state machines +- Applies auto-fixes (if available) + +--- + +## Plan Comparison Workflow + +Compare manual plans vs auto-derived plans to detect deviations. + +### Quick Comparison + +```bash +specfact plan compare --bundle legacy-api +``` + +**What it does**: + +- Compares two project bundles (manual vs auto-derived) +- Finds bundles in `.specfact/projects/` +- Compares and reports deviations + +**When to use**: + +- After code changes +- Before merging PRs +- Regular validation + +### Detailed Comparison + +```bash +specfact plan compare \ + --manual .specfact/projects/manual-plan \ + --auto .specfact/projects/auto-derived \ + --out comparison-report.md +``` + +**Note**: Commands accept bundle directory paths, not individual files. + +**What it does**: + +- Compares specific plans +- Generates detailed report +- Shows all deviations with severity + +**When to use**: + +- Investigating specific deviations +- Generating reports for review +- Deep analysis + +### Code vs Plan Comparison + +```bash +specfact plan compare --bundle legacy-api --code-vs-plan +``` + +**What it does**: + +- Compares current code state vs manual plan +- Auto-derives plan from code +- Compares in one command + +**When to use**: + +- Quick drift detection +- Before committing changes +- CI/CD validation + +--- + +## Daily Development Workflow + +Typical workflow for daily development. + +### Morning: Check Status + +```bash +# Validate everything +specfact repro --verbose + +# Compare plans +specfact plan compare --bundle legacy-api +``` + +**What it does**: + +- Validates current state +- Detects any deviations +- Reports issues + +### During Development: Watch Mode + +```bash +# Start watch mode for repository sync +specfact sync repository --repo . --watch --interval 5 +``` + +**What it does**: + +- Monitors code changes +- Updates plan artifacts automatically +- Keeps plans in sync + +### Before Committing: Validate + +```bash +# Run validation +specfact repro + +# Compare plans +specfact plan compare --bundle legacy-api +``` + +**What it does**: + +- Ensures no violations +- Detects deviations +- Validates contracts + +### After Committing: CI/CD + +```bash +# CI/CD pipeline runs +specfact repro --verbose --budget 120 +``` + +**What it does**: + +- Validates in CI/CD +- Blocks merges on violations +- Generates reports + +--- + +## Migration Workflow + +Complete workflow for migrating from Spec-Kit or OpenSpec. + +### Spec-Kit Migration + +#### Step 1: Preview + +```bash +specfact import from-bridge --adapter speckit --repo . --dry-run +``` + +**What it does**: + +- Analyzes Spec-Kit project using bridge adapter +- Shows what will be imported +- Does not modify anything + +#### Step 2: Execute + +```bash +specfact import from-bridge --adapter speckit --repo . --write +``` + +**What it does**: + +- Imports Spec-Kit artifacts using bridge adapter +- Creates modular project bundle structure +- Converts to SpecFact format (multiple aspect files) + +#### Step 3: Set Up Sync + +```bash +specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 +``` + +**What it does**: + +- Enables bidirectional sync via Spec-Kit adapter +- Keeps both tools in sync +- Monitors for changes + +### OpenSpec Integration + +Sync with OpenSpec change proposals (v0.22.0+): + +```bash +# Read-only sync from OpenSpec to SpecFact +specfact sync bridge --adapter openspec --mode read-only \ + --bundle my-project \ + --repo /path/to/openspec-repo + +# Export OpenSpec change proposals to GitHub Issues +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo +``` + +**What it does**: + +- Reads OpenSpec change proposals using OpenSpec adapter +- Syncs proposals to SpecFact change tracking +- Exports proposals to DevOps tools via GitHub adapter + +See [OpenSpec Journey Guide](openspec-journey.md) for complete integration workflow. + +### Step 4: Enable Enforcement + +```bash +# Start in shadow mode +specfact enforce stage --preset minimal + +# After stabilization, enable warnings +specfact enforce stage --preset balanced + +# For production, enable strict mode +specfact enforce stage --preset strict +``` + +**What it does**: + +- Progressive enforcement +- Gradual rollout +- Production-ready + +--- + +## Related Documentation + +- **[Integration Showcases](../examples/integration-showcases/)** ⭐ - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations +- [Use Cases](use-cases.md) - Detailed use case scenarios +- [Command Reference](../reference/commands.md) - All commands with examples +- [Troubleshooting](troubleshooting.md) - Common issues and solutions +- [IDE Integration](ide-integration.md) - Set up slash commands + +--- + +**Happy building!** 🚀 diff --git a/_site_local/index.html b/_site_local/index.html new file mode 100644 index 0000000..e33b05a --- /dev/null +++ b/_site_local/index.html @@ -0,0 +1,315 @@ + + + + + + + +SpecFact CLI Documentation | Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

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.

+ +
+ +

🚀 Quick Start

+ +

New to SpecFact CLI?

+ +

Primary Use Case: Modernizing legacy Python codebases

+ +
    +
  1. Installation - Get started in 60 seconds
    2. +
  2. First Steps - Run your first command
    3. +
  3. Modernizing Legacy Code ⭐ PRIMARY - Brownfield-first guide
    4. +
  4. The Brownfield Journey ⭐ - Complete modernization workflow
    5. +
+ +

Using GitHub Spec-Kit?

+ +

Secondary Use Case: Add automated enforcement to your Spec-Kit projects

+ + + +

📚 Documentation

+ +

Guides

+ + + +

Reference

+ + + +

Examples

+ + + +
+ +

🆘 Getting Help

+ +

Documentation

+ +

You’re here! Browse the guides above.

+ +

Community

+ + + +

Direct Support

+ + + +
+ +

🤝 Contributing

+ +

Found an error or want to improve the docs?

+ +
    +
  1. Fork the repository
    2. +
  2. Edit the markdown files in docs/
    3. +
  3. Submit a pull request
    4. +
+ +

See CONTRIBUTING.md for guidelines.

+ +
+ +

Happy building! 🚀

+ +
+ +

Copyright © 2025 Nold AI (Owner: Dominikus Nold)

+ +

Trademarks: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See TRADEMARKS.md for more information.

+ +

License: See LICENSE.md for licensing information.

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/installation/enhanced-analysis-dependencies.md b/_site_local/installation/enhanced-analysis-dependencies.md new file mode 100644 index 0000000..5c01aaa --- /dev/null +++ b/_site_local/installation/enhanced-analysis-dependencies.md @@ -0,0 +1,130 @@ +# Enhanced Analysis Dependencies + +## Python Package Dependencies + +### Already in `pyproject.toml` + +✅ **NetworkX** (`networkx>=3.4.2`) - Already in main dependencies + +- Used for: Dependency graph building and analysis +- Status: ✅ Already configured + +✅ **Graphviz** (`graphviz>=0.20.1`) - Added to main dependencies and optional-dependencies + +- Used for: Architecture diagram generation +- **Important**: Requires system Graphviz to be installed: + - Debian/Ubuntu: `apt-get install graphviz` + - macOS: `brew install graphviz` + - The Python `graphviz` package is a wrapper that requires the system package + +### Quick Setup + +```bash +# Install Python dependencies +pip install -e ".[enhanced-analysis]" + +# Install system dependencies (required for graphviz) +# Debian/Ubuntu: +sudo apt-get install graphviz + +# macOS: +brew install graphviz +``` + +## Optional Python Packages + +These packages are available via pip and can be installed with: + +```bash +pip install -e ".[enhanced-analysis]" +# or +hatch install -e ".[enhanced-analysis]" +``` + +### 1. pyan3 - Python Call Graph Analysis + +**Purpose**: Extract function call graphs from Python code + +**Package**: `pyan3>=1.2.0` (in optional-dependencies.enhanced-analysis) + +**Usage**: The `graph_analyzer.py` module automatically detects if `pyan3` is available and gracefully falls back if not installed. + +**Status**: ✅ **Available** - Install via `pip install -e ".[enhanced-analysis]"` + +### 2. Syft - Software Bill of Materials (SBOM) + +**Purpose**: Generate comprehensive SBOM of all dependencies (direct and transitive) + +**Package**: `syft>=0.9.5` (in optional-dependencies.enhanced-analysis) + +**Usage**: Will be integrated in `sbom_generator.py` (pending implementation) + +**Status**: ✅ **Available** - Install via `pip install -e ".[enhanced-analysis]"` + +### 3. Bearer - Data Flow Analysis + +**Purpose**: Track sensitive data flow through codebase for security analysis + +**Package**: `bearer>=3.1.0` (in optional-dependencies.enhanced-analysis) + +**Note**: Bearer primarily supports Java, Ruby, JS/TS. For Python projects, we may need Python-specific alternatives. + +**Status**: ✅ **Available** - Install via `pip install -e ".[enhanced-analysis]"` + +## Summary + +### Required Python Packages (in pyproject.toml dependencies) + +- ✅ `networkx>=3.4.2` - Already configured +- ✅ `graphviz>=0.20.1` - Added to dependencies + +### Optional Python Packages (in optional-dependencies.enhanced-analysis) + +Install all with: `pip install -e ".[enhanced-analysis]"` + +- ✅ `pyan3>=1.2.0` - Python call graph analysis +- ✅ `syft>=0.9.5` - Software Bill of Materials (SBOM) generation +- ✅ `bearer>=3.1.0` - Data flow analysis for security +- ✅ `graphviz>=0.20.1` - Graph visualization (also in main dependencies) + +### System Dependencies (Required for graphviz) + +- ⏳ `graphviz` (system package) - `apt-get install graphviz` or `brew install graphviz` + - The Python `graphviz` package is a wrapper that requires the system package + +## Installation Guide + +### Quick Install (All Enhanced Analysis Tools) + +```bash +# Install Python dependencies +pip install -e ".[enhanced-analysis]" + +# Install system Graphviz (required for graphviz Python package) +# Debian/Ubuntu: +sudo apt-get install graphviz + +# macOS: +brew install graphviz +``` + +### Individual Package Installation + +```bash +# Install specific packages +pip install pyan3>=1.2.0 +pip install syft>=0.9.5 +pip install bearer>=3.1.0 +pip install graphviz>=0.20.1 +``` + +## Graceful Degradation + +All graph analysis features are designed to work gracefully when optional tools are missing: + +- **pyan3 missing**: Call graph extraction returns empty (no error) +- **graphviz missing**: Diagram generation skipped (no error) +- **syft missing**: SBOM generation skipped (no error) +- **bearer missing**: Data flow analysis skipped (no error) + +The import command will continue to work with whatever tools are available, providing enhanced analysis when tools are present. diff --git a/_site_local/migration-guide/index.html b/_site_local/migration-guide/index.html new file mode 100644 index 0000000..cf21e01 --- /dev/null +++ b/_site_local/migration-guide/index.html @@ -0,0 +1,452 @@ + + + + + + + +Migration Guide | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Migration Guide

+ +
+

Decision tree and workflow for migrating between SpecFact CLI versions and from other tools

+
+ +
+ +

Overview

+ +

This guide helps you decide when and how to migrate:

+ +
    +
  • Between SpecFact CLI versions - When upgrading to a new version
    • +
  • From other tools - When migrating from Spec-Kit, OpenSpec, or other SDD tools
    • +
  • Between project structures - When restructuring your project bundles
    • +
+ +
+ +

Migration Decision Tree

+ +
Start: What do you need to migrate?
+
+├─ Upgrading SpecFact CLI version?
+│  ├─ Minor version (0.19 → 0.20)?
+│  │  └─ → Usually automatic, check [Version-Specific Migration Guides](#version-specific-migrations)
+│  ├─ Major version (0.x → 1.0)?
+│  │  └─ → Check breaking changes, use [Version-Specific Migration Guides](#version-specific-migrations)
+│  └─ CLI reorganization (pre-0.16 → 0.16+)?
+│     └─ → See [CLI Reorganization Migration](/specfact-cli/guides/migration-cli-reorganization.md)
+│
+├─ Migrating from Spec-Kit?
+│  └─ → See [Spec-Kit Journey Guide](/specfact-cli/guides/speckit-journey/)
+│
+├─ Migrating from OpenSpec?
+│  └─ → See [OpenSpec Journey Guide](/specfact-cli/guides/openspec-journey.md)
+│
+└─ Restructuring project bundles?
+   └─ → See [Project Bundle Management](/specfact-cli/reference/commands/#project---project-bundle-management)
+
+ +
+ +

Version-Specific Migrations

+ +

Migration from 0.16 to 0.19+

+ +

Breaking Changes: CLI command reorganization

+ +

Migration Steps:

+ +
    +
  1. Review CLI Reorganization Migration Guide
    2. +
  2. Update scripts and CI/CD pipelines
    3. +
  3. Test commands in development environment
    4. +
  4. Update documentation references
    5. +
+ +

Related: Migration 0.16 to 0.19

+ +
+ +

Migration from Pre-0.16 to 0.16+

+ +

Breaking Changes: Major CLI reorganization

+ +

Migration Steps:

+ +
    +
  1. Review CLI Reorganization Migration Guide
    2. +
  2. Update all command references
    3. +
  3. Migrate plan bundles to new schema
    4. +
  4. Update CI/CD configurations
    5. +
+ +

Related: CLI Reorganization Migration

+ +
+ +

Tool Migration Workflows

+ +

Migrating from Spec-Kit

+ +

Workflow: Use External Tool Integration Chain

+ +
    +
  1. Import from Spec-Kit via bridge adapter
    2. +
  2. Review imported plan
    3. +
  3. Set up bidirectional sync (optional)
    4. +
  4. Enforce SDD compliance
    5. +
+ +

Detailed Guide: Spec-Kit Journey Guide

+ +

Command Chain: External Tool Integration Chain

+ +
+ +

Migrating from OpenSpec

+ +

Workflow: Use External Tool Integration Chain

+ +
    +
  1. Import from OpenSpec via bridge adapter
    2. +
  2. Review imported change proposals
    3. +
  3. Set up DevOps sync (optional)
    4. +
  4. Enforce SDD compliance
    5. +
+ +

Detailed Guide: OpenSpec Journey Guide

+ +

Command Chain: External Tool Integration Chain

+ +
+ +

Project Structure Migrations

+ +

Migrating Between Project Bundles

+ +

When to use: Restructuring projects, splitting/merging bundles

+ +

Commands:

+ +
# Export from old bundle
+specfact project export --bundle old-bundle --persona <persona>
+
+# Create new bundle
+specfact plan init --bundle new-bundle
+
+# Import to new bundle (manual editing may be required)
+specfact project import --bundle new-bundle --persona <persona> --source exported.md
+
+ +

Related: Project Bundle Management

+ +
+ +

Plan Schema Migrations

+ +

Upgrading Plan Bundles

+ +

When to use: When plan bundles are on an older schema version

+ +

Command:

+ +
# Upgrade all bundles
+specfact plan upgrade --all
+
+# Upgrade specific bundle
+specfact plan upgrade --bundle <bundle-name>
+
+ +

Benefits:

+ +
    +
  • Improved performance (44% faster plan select)
    • +
  • New features and metadata
    • +
  • Better compatibility
    • +
+ +

Related: Plan Upgrade

+ +
+ +

Migration Workflow Examples

+ +

Example 1: Upgrading SpecFact CLI

+ +
# 1. Check current version
+specfact --version
+
+# 2. Review migration guide for target version
+# See: guides/migration-*.md
+
+# 3. Upgrade SpecFact CLI
+pip install --upgrade specfact-cli
+
+# 4. Upgrade plan bundles
+specfact plan upgrade --all
+
+# 5. Test commands
+specfact plan select --last 5
+
+ +
+ +

Example 2: Migrating from Spec-Kit

+ +
# 1. Import from Spec-Kit
+specfact import from-bridge --repo . --adapter speckit --write
+
+# 2. Review imported plan
+specfact plan review --bundle <bundle-name>
+
+# 3. Set up bidirectional sync (optional)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --bidirectional --watch
+
+# 4. Enforce SDD compliance
+specfact enforce sdd --bundle <bundle-name>
+
+ +

Related: Spec-Kit Journey Guide

+ +
+ +

Troubleshooting Migrations

+ +

Common Issues

+ +

Issue: Plan bundles fail to upgrade

+ +

Solution:

+ +
# Check bundle schema version
+specfact plan select --bundle <bundle-name> --json | jq '.schema_version'
+
+# Manual upgrade if needed
+specfact plan upgrade --bundle <bundle-name> --force
+
+ +

Issue: Imported plans have missing data

+ +

Solution:

+ +
    +
  1. Review import logs
    2. +
  2. Use plan review to identify gaps
    3. +
  3. Use plan update-feature to fill missing data
    4. +
  4. Re-import if needed
    5. +
+ +

Related: Troubleshooting Guide

+ +
+ +

See Also

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/modes/index.html b/_site_local/modes/index.html new file mode 100644 index 0000000..67f5cab --- /dev/null +++ b/_site_local/modes/index.html @@ -0,0 +1,546 @@ + + + + + + + +Operational Modes | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Operational Modes

+ +

Reference documentation for SpecFact CLI’s operational modes: CI/CD and CoPilot.

+ +

Overview

+ +

SpecFact CLI supports two operational modes for different use cases:

+ +
    +
  • CI/CD Mode (default): Fast, deterministic execution for automated pipelines
    • +
  • CoPilot Mode: Enhanced prompts with context injection for interactive development
    • +
+ +

Mode Detection

+ +

Mode is automatically detected based on:

+ +
    +
  1. Explicit --mode flag (highest priority)
    2. +
  2. CoPilot API availability (environment/IDE detection)
    3. +
  3. IDE integration (VS Code/Cursor with CoPilot enabled)
    4. +
  4. Default to CI/CD mode (fallback)
    5. +
+ +

Testing Mode Detection

+ +

This reference shows how to test mode detection and command routing in practice.

+ +

Quick Test Commands

+ +

Note: The CLI must be run through hatch run or installed first. Use hatch run specfact or install with hatch build && pip install -e ..

+ +

1. Test Explicit Mode Flags

+ +
# Test CI/CD mode explicitly
+hatch run specfact --mode cicd hello
+
+# Test CoPilot mode explicitly
+hatch run specfact --mode copilot hello
+
+# Test invalid mode (should fail)
+hatch run specfact --mode invalid hello
+
+# Test short form -m flag
+hatch run specfact -m cicd hello
+
+ +

Quick Test Script

+ +

Run the automated test script:

+ +
# Python-based test (recommended)
+python3 test_mode_practical.py
+
+# Or using hatch
+hatch run python test_mode_practical.py
+
+ +

This script tests all detection scenarios automatically.

+ +

2. Test Environment Variable

+ +
# Set environment variable and test
+export SPECFACT_MODE=copilot
+specfact hello
+
+# Set to CI/CD mode
+export SPECFACT_MODE=cicd
+specfact hello
+
+# Unset to test default
+unset SPECFACT_MODE
+specfact hello  # Should default to CI/CD
+
+ +

3. Test Auto-Detection

+ +

Test CoPilot API Detection

+ +
# Simulate CoPilot API available
+export COPILOT_API_URL=https://api.copilot.com
+specfact hello  # Should detect CoPilot mode
+
+# Or with token
+export COPILOT_API_TOKEN=token123
+specfact hello  # Should detect CoPilot mode
+
+# Or with GitHub Copilot token
+export GITHUB_COPILOT_TOKEN=token123
+specfact hello  # Should detect CoPilot mode
+
+ +

Test IDE Detection

+ +
# Simulate VS Code environment
+export VSCODE_PID=12345
+export COPILOT_ENABLED=true
+specfact hello  # Should detect CoPilot mode
+
+# Simulate Cursor environment
+export CURSOR_PID=12345
+export CURSOR_COPILOT_ENABLED=true
+specfact hello  # Should detect CoPilot mode
+
+# Simulate VS Code via TERM_PROGRAM
+export TERM_PROGRAM=vscode
+export VSCODE_COPILOT_ENABLED=true
+specfact hello  # Should detect CoPilot mode
+
+ +

4. Test Priority Order

+ +
# Test that explicit flag overrides environment
+export SPECFACT_MODE=copilot
+specfact --mode cicd hello  # Should use CI/CD mode (flag wins)
+
+# Test that explicit flag overrides auto-detection
+export COPILOT_API_URL=https://api.copilot.com
+specfact --mode cicd hello  # Should use CI/CD mode (flag wins)
+
+ +

5. Test Default Behavior

+ +
# Clean environment - should default to CI/CD
+unset SPECFACT_MODE
+unset COPILOT_API_URL
+unset COPILOT_API_TOKEN
+unset GITHUB_COPILOT_TOKEN
+unset VSCODE_PID
+unset CURSOR_PID
+specfact hello  # Should default to CI/CD mode
+
+ +

Python Interactive Testing

+ +

You can also test the detection logic directly in Python using hatch:

+ +
# Test explicit mode
+hatch run python -c "from specfact_cli.modes import OperationalMode, detect_mode; mode = detect_mode(explicit_mode=OperationalMode.CICD); print(f'Explicit CI/CD: {mode}')"
+
+# Test environment variable
+SPECFACT_MODE=copilot hatch run python -c "from specfact_cli.modes import OperationalMode, detect_mode; import os; mode = detect_mode(explicit_mode=None); print(f'Environment Copilot: {mode}')"
+
+# Test default
+hatch run python -c "from specfact_cli.modes import OperationalMode, detect_mode; import os; os.environ.clear(); mode = detect_mode(explicit_mode=None); print(f'Default: {mode}')"
+
+ +

Or use the practical test script:

+ +
hatch run python test_mode_practical.py
+
+ +

Testing Command Routing (Phase 3.2+)

+ +

Current State (Phase 3.2)

+ +

Important: In Phase 3.2, mode detection and routing infrastructure is complete, but actual command execution is identical for both modes. The only difference is the log message. Actual mode-specific behavior will be implemented in Phase 4.

+ +

Test with Actual Commands

+ +

The import from-code command now uses mode-aware routing. You should see mode information in the output (but execution is the same for now):

+ +
# Test with CI/CD mode (bundle name as positional argument)
+hatch run specfact --mode cicd import from-code test-project --repo . --confidence 0.5 --shadow-only
+
+# Expected output:
+# Mode: CI/CD (direct execution)
+# Analyzing repository: .
+# ...
+
+ +
# Test with CoPilot mode (bundle name as positional argument)
+hatch run specfact --mode copilot import from-code test-project --repo . --confidence 0.5 --shadow-only
+
+# Expected output:
+# Mode: CoPilot (agent routing)
+# Analyzing repository: .
+# ...
+
+ +

Test Router Directly

+ +

You can also test the routing logic directly in Python:

+ +
# Test router with CI/CD mode
+hatch run python -c "
+from specfact_cli.modes import OperationalMode, get_router
+router = get_router()
+result = router.route('import from-code', OperationalMode.CICD, {})
+print(f'Mode: {result.mode}')
+print(f'Execution mode: {result.execution_mode}')
+"
+
+# Test router with CoPilot mode
+hatch run python -c "
+from specfact_cli.modes import OperationalMode, get_router
+router = get_router()
+result = router.route('import from-code', OperationalMode.COPILOT, {})
+print(f'Mode: {result.mode}')
+print(f'Execution mode: {result.execution_mode}')
+"
+
+ +

Real-World Scenarios

+ +

Scenario 1: CI/CD Pipeline

+ +
# In GitHub Actions or CI/CD
+# No environment variables set
+# Should auto-detect CI/CD mode (bundle name as positional argument)
+hatch run specfact import from-code my-project --repo . --confidence 0.7
+
+# Expected: Mode: CI/CD (direct execution)
+
+ +

Scenario 2: Developer with CoPilot

+ +
# Developer running in VS Code/Cursor with CoPilot enabled
+# IDE environment variables automatically set
+# Should auto-detect CoPilot mode (bundle name as positional argument)
+hatch run specfact import from-code my-project --repo . --confidence 0.7
+
+# Expected: Mode: CoPilot (agent routing)
+
+ +

Scenario 3: Force Mode Override

+ +
# Developer wants CI/CD mode even though CoPilot is available (bundle name as positional argument)
+hatch run specfact --mode cicd import from-code my-project --repo . --confidence 0.7
+
+# Expected: Mode: CI/CD (direct execution) - flag overrides auto-detection
+
+ +

Verification Script

+ +

Here’s a simple script to test all scenarios:

+ +
#!/bin/bash
+# test-mode-detection.sh
+
+echo "=== Testing Mode Detection ==="
+echo
+
+echo "1. Testing explicit CI/CD mode:"
+specfact --mode cicd hello
+echo
+
+echo "2. Testing explicit CoPilot mode:"
+specfact --mode copilot hello
+echo
+
+echo "3. Testing invalid mode (should fail):"
+specfact --mode invalid hello 2>&1 || echo "✓ Failed as expected"
+echo
+
+echo "4. Testing SPECFACT_MODE environment variable:"
+export SPECFACT_MODE=copilot
+specfact hello
+unset SPECFACT_MODE
+echo
+
+echo "5. Testing CoPilot API detection:"
+export COPILOT_API_URL=https://api.copilot.com
+specfact hello
+unset COPILOT_API_URL
+echo
+
+echo "6. Testing default (no overrides):"
+specfact hello
+echo
+
+echo "=== All Tests Complete ==="
+
+ +

Debugging Mode Detection

+ +

To see what mode is being detected, you can add debug output:

+ +
# In Python
+from specfact_cli.modes import detect_mode, OperationalMode
+import os
+
+mode = detect_mode(explicit_mode=None)
+print(f"Detected mode: {mode}")
+print(f"Environment variables:")
+print(f"  SPECFACT_MODE: {os.environ.get('SPECFACT_MODE', 'not set')}")
+print(f"  COPILOT_API_URL: {os.environ.get('COPILOT_API_URL', 'not set')}")
+print(f"  VSCODE_PID: {os.environ.get('VSCODE_PID', 'not set')}")
+print(f"  CURSOR_PID: {os.environ.get('CURSOR_PID', 'not set')}")
+
+ +

Expected Results

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ScenarioExpected ModeNotes
--mode cicdCICDExplicit flag (highest priority)
--mode copilotCOPILOTExplicit flag (highest priority)
SPECFACT_MODE=copilotCOPILOTEnvironment variable
COPILOT_API_URL setCOPILOTAuto-detection
VSCODE_PID + COPILOT_ENABLED=trueCOPILOTIDE detection
Clean environmentCICDDefault fallback
Invalid modeErrorValidation rejects invalid values
+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/project-plans/speckit-test/architect.md b/_site_local/project-plans/speckit-test/architect.md new file mode 100644 index 0000000..d8d385a --- /dev/null +++ b/_site_local/project-plans/speckit-test/architect.md @@ -0,0 +1,4132 @@ +# Project Plan: speckit-test - Architect View + +**Persona**: Architect +**Bundle**: `speckit-test` +**Created**: 2025-12-11T23:26:08.394471+00:00 +**Status**: active +**Last Updated**: 2025-12-11T23:26:08.394488+00:00 + +## Technical Constraints & Requirements *(mandatory)* + +### FEATURE-PERFORMANCEMETRIC: Performance Metric + +#### Technical Constraints - FEATURE-PERFORMANCEMETRIC + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ARTIFACTMAPPING: Artifact Mapping + +#### Technical Constraints - FEATURE-ARTIFACTMAPPING + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SDDMANIFEST: S D D Manifest + +#### Technical Constraints - FEATURE-SDDMANIFEST + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-TEMPLATEMAPPING: Template Mapping + +#### Technical Constraints - FEATURE-TEMPLATEMAPPING + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CLIARTIFACTMETADATA: C L I Artifact Metadata + +#### Technical Constraints - FEATURE-CLIARTIFACTMETADATA + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-MOCKSERVER: Mock Server + +#### Technical Constraints - FEATURE-MOCKSERVER + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-FEATURESPECIFICATIONTEMPLATE: Feature Specification Template + +#### Technical Constraints - FEATURE-FEATURESPECIFICATIONTEMPLATE + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-TASKLIST: Task List + +#### Technical Constraints - FEATURE-TASKLIST + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-DEVIATIONREPORT: Deviation Report + +#### Technical Constraints - FEATURE-DEVIATIONREPORT + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROGRESSIVEDISCLOSUREGROUP: Progressive Disclosure Group + +#### Technical Constraints - FEATURE-PROGRESSIVEDISCLOSUREGROUP + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-VALIDATIONREPORT: Validation Report + +#### Technical Constraints - FEATURE-VALIDATIONREPORT + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CHECKRESULT: Check Result + +#### Technical Constraints - FEATURE-CHECKRESULT + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-TELEMETRYSETTINGS: Telemetry Settings + +#### Technical Constraints - FEATURE-TELEMETRYSETTINGS + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENRICHMENTPARSER: Enrichment Parser + +#### Technical Constraints - FEATURE-ENRICHMENTPARSER + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-YAMLUTILS: Y A M L Utils + +#### Technical Constraints - FEATURE-YAMLUTILS + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-TEXTUTILS: Text Utils + +#### Technical Constraints - FEATURE-TEXTUTILS + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-STRUCTUREDFORMAT: Structured Format + +#### Technical Constraints - FEATURE-STRUCTUREDFORMAT + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-FILEHASHCACHE: File Hash Cache + +#### Technical Constraints - FEATURE-FILEHASHCACHE + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SOURCETRACKING: Source Tracking + +#### Technical Constraints - FEATURE-SOURCETRACKING + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-TELEMETRYMANAGER: Telemetry Manager + +#### Technical Constraints - FEATURE-TELEMETRYMANAGER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROJECTCONTEXT: Project Context + +#### Technical Constraints - FEATURE-PROJECTCONTEXT + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENFORCEMENTCONFIG: Enforcement Config + +#### Technical Constraints - FEATURE-ENFORCEMENTCONFIG + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTRACTEXTRACTIONTEMPLATE: Contract Extraction Template + +#### Technical Constraints - FEATURE-CONTRACTEXTRACTIONTEMPLATE + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SCHEMAVALIDATOR: Schema Validator + +#### Technical Constraints - FEATURE-SCHEMAVALIDATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-REPROCHECKER: Repro Checker + +#### Technical Constraints - FEATURE-REPROCHECKER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-RELATIONSHIPMAPPER: Relationship Mapper + +#### Technical Constraints - FEATURE-RELATIONSHIPMAPPER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-DRIFTDETECTOR: Drift Detector + +#### Technical Constraints - FEATURE-DRIFTDETECTOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-AMBIGUITYSCANNER: Ambiguity Scanner + +#### Technical Constraints - FEATURE-AMBIGUITYSCANNER + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CHANGEDETECTOR: Change Detector + +#### Technical Constraints - FEATURE-CHANGEDETECTOR + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-AGENTMODE: Agent Mode + +#### Technical Constraints - FEATURE-AGENTMODE + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PERFORMANCEMONITOR: Performance Monitor + +#### Technical Constraints - FEATURE-PERFORMANCEMONITOR + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-FSMVALIDATOR: F S M Validator + +#### Technical Constraints - FEATURE-FSMVALIDATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROMPTVALIDATOR: Prompt Validator + +#### Technical Constraints - FEATURE-PROMPTVALIDATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECVALIDATIONRESULT: Spec Validation Result + +#### Technical Constraints - FEATURE-SPECVALIDATIONRESULT + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-LOGGERSETUP: Logger Setup + +#### Technical Constraints - FEATURE-LOGGERSETUP + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-AGENTREGISTRY: Agent Registry + +#### Technical Constraints - FEATURE-AGENTREGISTRY + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-REPROREPORT: Repro Report + +#### Technical Constraints - FEATURE-REPROREPORT + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-GITOPERATIONS: Git Operations + +#### Technical Constraints - FEATURE-GITOPERATIONS + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PERFORMANCEREPORT: Performance Report + +#### Technical Constraints - FEATURE-PERFORMANCEREPORT + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANENRICHER: Plan Enricher + +#### Technical Constraints - FEATURE-PLANENRICHER + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGEWATCHEVENTHANDLER: Bridge Watch Event Handler + +#### Technical Constraints - FEATURE-BRIDGEWATCHEVENTHANDLER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTRACTDENSITYMETRICS: Contract Density Metrics + +#### Technical Constraints - FEATURE-CONTRACTDENSITYMETRICS + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENRICHMENTREPORT: Enrichment Report + +#### Technical Constraints - FEATURE-ENRICHMENTREPORT + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-IMPLEMENTATIONPLANTEMPLATE: Implementation Plan Template + +#### Technical Constraints - FEATURE-IMPLEMENTATIONPLANTEMPLATE + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SOURCEARTIFACTSCANNER: Source Artifact Scanner + +#### Technical Constraints - FEATURE-SOURCEARTIFACTSCANNER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-REQUIREMENTEXTRACTOR: Requirement Extractor + +#### Technical Constraints - FEATURE-REQUIREMENTEXTRACTOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANCOMPARATOR: Plan Comparator + +#### Technical Constraints - FEATURE-PLANCOMPARATOR + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROTOCOLGENERATOR: Protocol Generator + +#### Technical Constraints - FEATURE-PROTOCOLGENERATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SYNCWATCHER: Sync Watcher + +#### Technical Constraints - FEATURE-SYNCWATCHER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENRICHMENTCONTEXT: Enrichment Context + +#### Technical Constraints - FEATURE-ENRICHMENTCONTEXT + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SYNCAGENT: Sync Agent + +#### Technical Constraints - FEATURE-SYNCAGENT + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGEWATCH: Bridge Watch + +#### Technical Constraints - FEATURE-BRIDGEWATCH + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGECONFIG: Bridge Config + +#### Technical Constraints - FEATURE-BRIDGECONFIG + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-REPORTGENERATOR: Report Generator + +#### Technical Constraints - FEATURE-REPORTGENERATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONSTITUTIONENRICHER: Constitution Enricher + +#### Technical Constraints - FEATURE-CONSTITUTIONENRICHER + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENHANCEDSYNCWATCHER: Enhanced Sync Watcher + +#### Technical Constraints - FEATURE-ENHANCEDSYNCWATCHER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTRACTGENERATOR: Contract Generator + +#### Technical Constraints - FEATURE-CONTRACTGENERATOR + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-WORKFLOWGENERATOR: Workflow Generator + +#### Technical Constraints - FEATURE-WORKFLOWGENERATOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-MESSAGEFLOWFORMATTER: Message Flow Formatter + +#### Technical Constraints - FEATURE-MESSAGEFLOWFORMATTER + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGESYNC: Bridge Sync + +#### Technical Constraints - FEATURE-BRIDGESYNC + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-REPOSITORYSYNC: Repository Sync + +#### Technical Constraints - FEATURE-REPOSITORYSYNC + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROGRESSIVEDISCLOSURECOMMAND: Progressive Disclosure Command + +#### Technical Constraints - FEATURE-PROGRESSIVEDISCLOSURECOMMAND + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANMIGRATOR: Plan Migrator + +#### Technical Constraints - FEATURE-PLANMIGRATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-COMMANDROUTER: Command Router + +#### Technical Constraints - FEATURE-COMMANDROUTER + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTROLFLOWANALYZER: Control Flow Analyzer + +#### Technical Constraints - FEATURE-CONTROLFLOWANALYZER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-GRAPHANALYZER: Graph Analyzer + +#### Technical Constraints - FEATURE-GRAPHANALYZER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SMARTCOVERAGEMANAGER: Smart Coverage Manager + +#### Technical Constraints - FEATURE-SMARTCOVERAGEMANAGER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CODEANALYZER: Code Analyzer + +#### Technical Constraints - FEATURE-CODEANALYZER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SYNCEVENTHANDLER: Sync Event Handler + +#### Technical Constraints - FEATURE-SYNCEVENTHANDLER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECKITCONVERTER: Spec Kit Converter + +#### Technical Constraints - FEATURE-SPECKITCONVERTER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR: Constitution Evidence Extractor + +#### Technical Constraints - FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTRACTEXTRACTOR: Contract Extractor + +#### Technical Constraints - FEATURE-CONTRACTEXTRACTOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROJECTBUNDLE: Project Bundle + +#### Technical Constraints - FEATURE-PROJECTBUNDLE + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-OPENAPIEXTRACTOR: Open A P I Extractor + +#### Technical Constraints - FEATURE-OPENAPIEXTRACTOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must support asynchronous operations for improved performance +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECKITSCANNER: Spec Kit Scanner + +#### Technical Constraints - FEATURE-SPECKITSCANNER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENHANCEDSYNCEVENTHANDLER: Enhanced Sync Event Handler + +#### Technical Constraints - FEATURE-ENHANCEDSYNCEVENTHANDLER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGEPROBE: Bridge Probe + +#### Technical Constraints - FEATURE-BRIDGEPROBE + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANAGENT: Plan Agent + +#### Technical Constraints - FEATURE-PLANAGENT + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ANALYZEAGENT: Analyze Agent + +#### Technical Constraints - FEATURE-ANALYZEAGENT + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANBUNDLE: Plan Bundle + +#### Technical Constraints - FEATURE-PLANBUNDLE + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CODETOSPECSYNC: Code To Spec Sync + +#### Technical Constraints - FEATURE-CODETOSPECSYNC + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGETEMPLATELOADER: Bridge Template Loader + +#### Technical Constraints - FEATURE-BRIDGETEMPLATELOADER + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECTOCODESYNC: Spec To Code Sync + +#### Technical Constraints - FEATURE-SPECTOCODESYNC + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANGENERATOR: Plan Generator + +#### Technical Constraints - FEATURE-PLANGENERATOR + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECKITSYNC: Spec Kit Sync + +#### Technical Constraints - FEATURE-SPECKITSYNC + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECFACTSTRUCTURE: Spec Fact Structure + +#### Technical Constraints - FEATURE-SPECFACTSTRUCTURE + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-OPENAPITESTCONVERTER: Open A P I Test Converter + +#### Technical Constraints - FEATURE-OPENAPITESTCONVERTER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTRACTFIRSTTESTMANAGER: Contract First Test Manager + +#### Technical Constraints - FEATURE-CONTRACTFIRSTTESTMANAGER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support + +## Protocols & State Machines *(mandatory)* + +*[ACTION REQUIRED: Define protocols and state machines]* + +**Note**: Protocols should be defined in `.specfact/projects/speckit-test/protocols/*.protocol.yaml` files. + +## Contracts *(mandatory)* + +### FEATURE-PERFORMANCEREPORT + +**Info**: + +- **Title**: Performance Report +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Performance Report**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/performance-metric/to-dict`: + - `GET`: To Dict +- `/performance-report/add-metric`: + - `POST`: Add Metric +- `/performance-report/get-summary`: + - `GET`: Get Summary +- `/performance-report/print-summary`: + - `GET`: Print Summary +- `/performance-monitor/start`: + - `GET`: Start +- `/performance-monitor/stop`: + - `GET`: Stop +- `/performance-monitor/track`: + - `GET`: Track +- `/performance-monitor/get-report`: + - `GET`: Get Report +- `/performance-monitor/disable`: + - `GET`: Disable +- `/performance-monitor/enable`: + - `GET`: Enable +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String + +---### FEATURE-SPECKITSCANNER + +**Info**: + +- **Title**: Spec Kit Scanner +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec Kit Scanner**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/source-artifact-scanner/scan-repository`: + - `GET`: Scan Repository +- `/source-artifact-scanner/link-to-specs`: + - `GET`: Link To Specs +- `/source-artifact-scanner/extract-function-mappings`: + - `GET`: Extract Function Mappings +- `/source-artifact-scanner/extract-test-mappings`: + - `GET`: Extract Test Mappings +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +- `/ambiguity-scanner/scan`: + - `GET`: Scan +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop + +---### FEATURE-CODETOSPECSYNC + +**Info**: + +- **Title**: Code To Spec Sync +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Code To Spec Sync**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files + +---### FEATURE-SPECVALIDATIONRESULT + +**Info**: + +- **Title**: Spec Validation Result +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec Validation Result**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-ENRICHMENTPARSER + +**Info**: + +- **Title**: Enrichment Parser +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enrichment Parser**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/enrichment-context/add-relationships`: + - `POST`: Add Relationships +- `/enrichment-context/add-contract`: + - `POST`: Add Contract +- `/enrichment-context/add-bundle-metadata`: + - `POST`: Add Bundle Metadata +- `/enrichment-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/to-markdown`: + - `GET`: To Markdown +- `/enrichment-report/add-missing-feature`: + - `POST`: Add Missing Feature +- `/enrichment-report/adjust-confidence`: + - `GET`: Adjust Confidence +- `/enrichment-report/add-business-context`: + - `POST`: Add Business Context +- `/enrichment-parser/parse`: + - `GET`: Parse + +---### FEATURE-VALIDATIONREPORT + +**Info**: + +- **Title**: Validation Report +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Validation Report**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String + +---### FEATURE-ENRICHMENTCONTEXT + +**Info**: + +- **Title**: Enrichment Context +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enrichment Context**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/enrichment-report/add-missing-feature`: + - `POST`: Add Missing Feature +- `/enrichment-report/adjust-confidence`: + - `GET`: Adjust Confidence +- `/enrichment-report/add-business-context`: + - `POST`: Add Business Context +- `/enrichment-parser/parse`: + - `GET`: Parse +- `/project-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/add-relationships`: + - `POST`: Add Relationships +- `/enrichment-context/add-contract`: + - `POST`: Add Contract +- `/enrichment-context/add-bundle-metadata`: + - `POST`: Add Bundle Metadata +- `/enrichment-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/to-markdown`: + - `GET`: To Markdown + +---### FEATURE-PROTOCOLGENERATOR + +**Info**: + +- **Title**: Protocol Generator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Protocol Generator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String +- `/protocol-generator/generate`: + - `GET`: Generate +- `/protocol-generator/generate-from-template`: + - `GET`: Generate From Template +- `/protocol-generator/render-string`: + - `GET`: Render String +**Schemas**: + +- `Transition`: object +- `Protocol`: object + +---### FEATURE-REQUIREMENTEXTRACTOR + +**Info**: + +- **Title**: Requirement Extractor +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Requirement Extractor**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/requirement-extractor/extract-complete-requirement`: + - `GET`: Extract Complete Requirement +- `/requirement-extractor/extract-method-requirement`: + - `GET`: Extract Method Requirement +- `/requirement-extractor/extract-nfrs`: + - `GET`: Extract Nfrs +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/open-a-p-i-extractor/extract-openapi-from-verbose`: + - `GET`: Extract Openapi From Verbose +- `/open-a-p-i-extractor/extract-openapi-from-code`: + - `GET`: Extract Openapi From Code +- `/open-a-p-i-extractor/add-test-examples`: + - `POST`: Add Test Examples +- `/open-a-p-i-extractor/save-openapi-contract`: + - `GET`: Save Openapi Contract +- `/constitution-evidence-extractor/extract-article-vii-evidence`: + - `GET`: Extract Article Vii Evidence +- `/constitution-evidence-extractor/extract-article-viii-evidence`: + - `GET`: Extract Article Viii Evidence +- `/constitution-evidence-extractor/extract-article-ix-evidence`: + - `GET`: Extract Article Ix Evidence +- `/constitution-evidence-extractor/extract-all-evidence`: + - `GET`: Extract All Evidence +- `/constitution-evidence-extractor/generate-constitution-check-section`: + - `GET`: Generate Constitution Check Section + +---### FEATURE-PROJECTBUNDLE + +**Info**: + +- **Title**: Project Bundle +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Project Bundle**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/project-bundle/load-from-directory`: + - `GET`: Load From Directory +- `/project-bundle/save-to-directory`: + - `GET`: Save To Directory +- `/project-bundle/get-feature/{key}`: + - `GET`: Get Feature +- `/project-bundle/add-feature`: + - `POST`: Add Feature +- `/project-bundle/update-feature/{key}`: + - `PUT`: Update Feature +- `/project-bundle/compute-summary`: + - `PUT`: Compute Summary +**Schemas**: + +- `BundleVersions`: object +- `SchemaMetadata`: object +- `ProjectMetadata`: object +- `BundleChecksums`: object +- `SectionLock`: object +- `PersonaMapping`: object +- `FeatureIndex`: object +- `ProtocolIndex`: object +- `BundleManifest`: object +- `ProjectBundle`: object + +---### FEATURE-SPECFACTSTRUCTURE + +**Info**: + +- **Title**: Spec Fact Structure +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec Fact Structure**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop +- `/spec-fact-structure/plan-suffix`: + - `GET`: Plan Suffix +- `/spec-fact-structure/ensure-plan-filename`: + - `GET`: Ensure Plan Filename +- `/spec-fact-structure/strip-plan-suffix`: + - `GET`: Strip Plan Suffix +- `/spec-fact-structure/default-plan-filename`: + - `GET`: Default Plan Filename +- `/spec-fact-structure/ensure-structure`: + - `GET`: Ensure Structure +- `/spec-fact-structure/get-timestamped-report-path`: + - `GET`: Get Timestamped Report Path +- `/spec-fact-structure/get-brownfield-analysis-path`: + - `GET`: Get Brownfield Analysis Path +- `/spec-fact-structure/get-brownfield-plan-path`: + - `GET`: Get Brownfield Plan Path +- `/spec-fact-structure/get-comparison-report-path`: + - `GET`: Get Comparison Report Path +- `/spec-fact-structure/get-default-plan-path`: + - `GET`: Get Default Plan Path +- `/spec-fact-structure/get-active-bundle-name`: + - `GET`: Get Active Bundle Name +- `/spec-fact-structure/set-active-plan`: + - `GET`: Set Active Plan +- `/spec-fact-structure/list-plans`: + - `GET`: List Plans +- `/spec-fact-structure/update-plan-summary`: + - `PUT`: Update Plan Summary +- `/spec-fact-structure/get-enforcement-config-path`: + - `GET`: Get Enforcement Config Path +- `/spec-fact-structure/get-sdd-path`: + - `GET`: Get Sdd Path +- `/spec-fact-structure/sanitize-plan-name/{name}`: + - `GET`: Sanitize Plan Name +- `/spec-fact-structure/get-timestamped-brownfield-report/{name}`: + - `GET`: Get Timestamped Brownfield Report +- `/spec-fact-structure/get-enrichment-report-path`: + - `GET`: Get Enrichment Report Path +- `/spec-fact-structure/get-plan-bundle-from-enrichment`: + - `GET`: Get Plan Bundle From Enrichment +- `/spec-fact-structure/get-enriched-plan-path`: + - `GET`: Get Enriched Plan Path +- `/spec-fact-structure/get-latest-brownfield-report`: + - `GET`: Get Latest Brownfield Report +- `/spec-fact-structure/create-gitignore`: + - `POST`: Create Gitignore +- `/spec-fact-structure/create-readme`: + - `POST`: Create Readme +- `/spec-fact-structure/scaffold-project`: + - `GET`: Scaffold Project +- `/spec-fact-structure/project-dir`: + - `GET`: Project Dir +- `/spec-fact-structure/ensure-project-structure`: + - `GET`: Ensure Project Structure +- `/spec-fact-structure/detect-bundle-format`: + - `GET`: Detect Bundle Format +- `/spec-fact-structure/get-bundle-reports-dir`: + - `GET`: Get Bundle Reports Dir +- `/spec-fact-structure/get-bundle-brownfield-report-path`: + - `GET`: Get Bundle Brownfield Report Path +- `/spec-fact-structure/get-bundle-comparison-report-path`: + - `GET`: Get Bundle Comparison Report Path +- `/spec-fact-structure/get-bundle-enrichment-report-path`: + - `GET`: Get Bundle Enrichment Report Path +- `/spec-fact-structure/get-bundle-enforcement-report-path`: + - `GET`: Get Bundle Enforcement Report Path +- `/spec-fact-structure/get-bundle-sdd-path`: + - `GET`: Get Bundle Sdd Path +- `/spec-fact-structure/get-bundle-tasks-path`: + - `GET`: Get Bundle Tasks Path +- `/spec-fact-structure/get-bundle-logs-dir`: + - `GET`: Get Bundle Logs Dir +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +- `/structured-format/from-string`: + - `GET`: From String +- `/structured-format/from-path`: + - `GET`: From Path + +---### FEATURE-SYNCEVENTHANDLER + +**Info**: + +- **Title**: Sync Event Handler +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Sync Event Handler**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-PERFORMANCEMONITOR + +**Info**: + +- **Title**: Performance Monitor +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Performance Monitor**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/performance-metric/to-dict`: + - `GET`: To Dict +- `/performance-report/add-metric`: + - `POST`: Add Metric +- `/performance-report/get-summary`: + - `GET`: Get Summary +- `/performance-report/print-summary`: + - `GET`: Print Summary +- `/performance-monitor/start`: + - `GET`: Start +- `/performance-monitor/stop`: + - `GET`: Stop +- `/performance-monitor/track`: + - `GET`: Track +- `/performance-monitor/get-report`: + - `GET`: Get Report +- `/performance-monitor/disable`: + - `GET`: Disable +- `/performance-monitor/enable`: + - `GET`: Enable + +---### FEATURE-SPECKITSYNC + +**Info**: + +- **Title**: Spec Kit Sync +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec Kit Sync**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-SYNCWATCHER + +**Info**: + +- **Title**: Sync Watcher +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Sync Watcher**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/file-hash-cache/load`: + - `GET`: Load +- `/file-hash-cache/save`: + - `GET`: Save +- `/file-hash-cache/get-hash`: + - `GET`: Get Hash +- `/file-hash-cache/set-hash`: + - `GET`: Set Hash +- `/file-hash-cache/get-dependencies`: + - `GET`: Get Dependencies +- `/file-hash-cache/set-dependencies`: + - `GET`: Set Dependencies +- `/file-hash-cache/has-changed`: + - `GET`: Has Changed +- `/enhanced-sync-event-handler/on-modified`: + - `GET`: On Modified +- `/enhanced-sync-event-handler/on-created`: + - `POST`: On Created +- `/enhanced-sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/enhanced-sync-watcher/start`: + - `GET`: Start +- `/enhanced-sync-watcher/stop`: + - `GET`: Stop +- `/enhanced-sync-watcher/watch`: + - `GET`: Watch +- `/sync-event-handler/on-modified`: + - `GET`: On Modified +- `/sync-event-handler/on-created`: + - `POST`: On Created +- `/sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/sync-watcher/start`: + - `GET`: Start +- `/sync-watcher/stop`: + - `GET`: Stop +- `/sync-watcher/watch`: + - `GET`: Watch +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-BRIDGEPROBE + +**Info**: + +- **Title**: Bridge Probe +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Probe**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-ANALYZEAGENT + +**Info**: + +- **Title**: Analyze Agent +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Analyze Agent**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/analyze-agent/execute`: + - `GET`: Execute +- `/analyze-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/analyze-codebase`: + - `GET`: Analyze Codebase +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/graph-analyzer/extract-call-graph`: + - `GET`: Extract Call Graph +- `/graph-analyzer/build-dependency-graph`: + - `GET`: Build Dependency Graph +- `/graph-analyzer/get-graph-summary`: + - `GET`: Get Graph Summary +- `/control-flow-analyzer/extract-scenarios-from-method`: + - `GET`: Extract Scenarios From Method + +---### FEATURE-PLANBUNDLE + +**Info**: + +- **Title**: Plan Bundle +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Bundle**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-CONTRACTEXTRACTIONTEMPLATE + +**Info**: + +- **Title**: Contract Extraction Template +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Contract Extraction Template**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator + +---### FEATURE-BRIDGEWATCH + +**Info**: + +- **Title**: Bridge Watch +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Watch**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/file-hash-cache/load`: + - `GET`: Load +- `/file-hash-cache/save`: + - `GET`: Save +- `/file-hash-cache/get-hash`: + - `GET`: Get Hash +- `/file-hash-cache/set-hash`: + - `GET`: Set Hash +- `/file-hash-cache/get-dependencies`: + - `GET`: Get Dependencies +- `/file-hash-cache/set-dependencies`: + - `GET`: Set Dependencies +- `/file-hash-cache/has-changed`: + - `GET`: Has Changed +- `/enhanced-sync-event-handler/on-modified`: + - `GET`: On Modified +- `/enhanced-sync-event-handler/on-created`: + - `POST`: On Created +- `/enhanced-sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/enhanced-sync-watcher/start`: + - `GET`: Start +- `/enhanced-sync-watcher/stop`: + - `GET`: Stop +- `/enhanced-sync-watcher/watch`: + - `GET`: Watch +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +- `/sync-event-handler/on-modified`: + - `GET`: On Modified +- `/sync-event-handler/on-created`: + - `POST`: On Created +- `/sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/sync-watcher/start`: + - `GET`: Start +- `/sync-watcher/stop`: + - `GET`: Stop +- `/sync-watcher/watch`: + - `GET`: Watch +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-PROGRESSIVEDISCLOSURECOMMAND + +**Info**: + +- **Title**: Progressive Disclosure Command +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Progressive Disclosure Command**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/progressive-disclosure-group/get-params`: + - `GET`: Get Params +- `/progressive-disclosure-command/format-help`: + - `GET`: Format Help +- `/progressive-disclosure-command/get-params`: + - `GET`: Get Params + +---### FEATURE-AGENTMODE + +**Info**: + +- **Title**: Agent Mode +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Agent Mode**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/analyze-agent/execute`: + - `GET`: Execute +- `/analyze-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/analyze-codebase`: + - `GET`: Analyze Codebase + +---### FEATURE-PLANENRICHER + +**Info**: + +- **Title**: Plan Enricher +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Enricher**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/constitution-enricher/analyze-repository`: + - `GET`: Analyze Repository +- `/constitution-enricher/suggest-principles`: + - `GET`: Suggest Principles +- `/constitution-enricher/enrich-template`: + - `GET`: Enrich Template +- `/constitution-enricher/bootstrap`: + - `GET`: Bootstrap +- `/constitution-enricher/validate`: + - `GET`: Validate +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-BRIDGETEMPLATELOADER + +**Info**: + +- **Title**: Bridge Template Loader +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Template Loader**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-CONSTITUTIONENRICHER + +**Info**: + +- **Title**: Constitution Enricher +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Constitution Enricher**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/constitution-enricher/analyze-repository`: + - `GET`: Analyze Repository +- `/constitution-enricher/suggest-principles`: + - `GET`: Suggest Principles +- `/constitution-enricher/enrich-template`: + - `GET`: Enrich Template +- `/constitution-enricher/bootstrap`: + - `GET`: Bootstrap +- `/constitution-enricher/validate`: + - `GET`: Validate +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/constitution-evidence-extractor/extract-article-vii-evidence`: + - `GET`: Extract Article Vii Evidence +- `/constitution-evidence-extractor/extract-article-viii-evidence`: + - `GET`: Extract Article Viii Evidence +- `/constitution-evidence-extractor/extract-article-ix-evidence`: + - `GET`: Extract Article Ix Evidence +- `/constitution-evidence-extractor/extract-all-evidence`: + - `GET`: Extract All Evidence +- `/constitution-evidence-extractor/generate-constitution-check-section`: + - `GET`: Generate Constitution Check Section + +---### FEATURE-SOURCETRACKING + +**Info**: + +- **Title**: Source Tracking +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Source Tracking**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/source-tracking/compute-hash`: + - `PUT`: Compute Hash +- `/source-tracking/has-changed`: + - `GET`: Has Changed +- `/source-tracking/update-hash`: + - `PUT`: Update Hash +- `/source-tracking/update-sync-timestamp`: + - `PUT`: Update Sync Timestamp +- `/source-artifact-scanner/scan-repository`: + - `GET`: Scan Repository +- `/source-artifact-scanner/link-to-specs`: + - `GET`: Link To Specs +- `/source-artifact-scanner/extract-function-mappings`: + - `GET`: Extract Function Mappings +- `/source-artifact-scanner/extract-test-mappings`: + - `GET`: Extract Test Mappings +**Schemas**: + +- `SourceTracking`: object + +---### FEATURE-CONTRACTDENSITYMETRICS + +**Info**: + +- **Title**: Contract Density Metrics +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Contract Density Metrics**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator + +---### FEATURE-AMBIGUITYSCANNER + +**Info**: + +- **Title**: Ambiguity Scanner +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Ambiguity Scanner**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/source-artifact-scanner/scan-repository`: + - `GET`: Scan Repository +- `/source-artifact-scanner/link-to-specs`: + - `GET`: Link To Specs +- `/source-artifact-scanner/extract-function-mappings`: + - `GET`: Extract Function Mappings +- `/source-artifact-scanner/extract-test-mappings`: + - `GET`: Extract Test Mappings +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/ambiguity-scanner/scan`: + - `GET`: Scan + +---### FEATURE-ENHANCEDSYNCEVENTHANDLER + +**Info**: + +- **Title**: Enhanced Sync Event Handler +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enhanced Sync Event Handler**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/file-hash-cache/load`: + - `GET`: Load +- `/file-hash-cache/save`: + - `GET`: Save +- `/file-hash-cache/get-hash`: + - `GET`: Get Hash +- `/file-hash-cache/set-hash`: + - `GET`: Set Hash +- `/file-hash-cache/get-dependencies`: + - `GET`: Get Dependencies +- `/file-hash-cache/set-dependencies`: + - `GET`: Set Dependencies +- `/file-hash-cache/has-changed`: + - `GET`: Has Changed +- `/enhanced-sync-event-handler/on-modified`: + - `GET`: On Modified +- `/enhanced-sync-event-handler/on-created`: + - `POST`: On Created +- `/enhanced-sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/enhanced-sync-watcher/start`: + - `GET`: Start +- `/enhanced-sync-watcher/stop`: + - `GET`: Stop +- `/enhanced-sync-watcher/watch`: + - `GET`: Watch +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-CHANGEDETECTOR + +**Info**: + +- **Title**: Change Detector +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Change Detector**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/drift-detector/scan`: + - `GET`: Scan +- `/change-detector/detect-changes`: + - `GET`: Detect Changes + +---### FEATURE-CONTROLFLOWANALYZER + +**Info**: + +- **Title**: Control Flow Analyzer +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Control Flow Analyzer**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/graph-analyzer/extract-call-graph`: + - `GET`: Extract Call Graph +- `/graph-analyzer/build-dependency-graph`: + - `GET`: Build Dependency Graph +- `/graph-analyzer/get-graph-summary`: + - `GET`: Get Graph Summary +- `/control-flow-analyzer/extract-scenarios-from-method`: + - `GET`: Extract Scenarios From Method + +---### FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR + +**Info**: + +- **Title**: Constitution Evidence Extractor +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Constitution Evidence Extractor**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/requirement-extractor/extract-complete-requirement`: + - `GET`: Extract Complete Requirement +- `/requirement-extractor/extract-method-requirement`: + - `GET`: Extract Method Requirement +- `/requirement-extractor/extract-nfrs`: + - `GET`: Extract Nfrs +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/open-a-p-i-extractor/extract-openapi-from-verbose`: + - `GET`: Extract Openapi From Verbose +- `/open-a-p-i-extractor/extract-openapi-from-code`: + - `GET`: Extract Openapi From Code +- `/open-a-p-i-extractor/add-test-examples`: + - `POST`: Add Test Examples +- `/open-a-p-i-extractor/save-openapi-contract`: + - `GET`: Save Openapi Contract +- `/constitution-evidence-extractor/extract-article-vii-evidence`: + - `GET`: Extract Article Vii Evidence +- `/constitution-evidence-extractor/extract-article-viii-evidence`: + - `GET`: Extract Article Viii Evidence +- `/constitution-evidence-extractor/extract-article-ix-evidence`: + - `GET`: Extract Article Ix Evidence +- `/constitution-evidence-extractor/extract-all-evidence`: + - `GET`: Extract All Evidence +- `/constitution-evidence-extractor/generate-constitution-check-section`: + - `GET`: Generate Constitution Check Section +- `/constitution-enricher/analyze-repository`: + - `GET`: Analyze Repository +- `/constitution-enricher/suggest-principles`: + - `GET`: Suggest Principles +- `/constitution-enricher/enrich-template`: + - `GET`: Enrich Template +- `/constitution-enricher/bootstrap`: + - `GET`: Bootstrap +- `/constitution-enricher/validate`: + - `GET`: Validate + +---### FEATURE-TEMPLATEMAPPING + +**Info**: + +- **Title**: Template Mapping +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Template Mapping**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict + +---### FEATURE-PLANMIGRATOR + +**Info**: + +- **Title**: Plan Migrator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Migrator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-TASKLIST + +**Info**: + +- **Title**: Task List +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Task List**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/task-list/get-tasks-by-phase`: + - `GET`: Get Tasks By Phase +- `/task-list/get-task`: + - `GET`: Get Task +- `/task-list/get-dependencies`: + - `GET`: Get Dependencies +**Schemas**: + +- `Task`: object +- `TaskList`: object + +---### FEATURE-OPENAPITESTCONVERTER + +**Info**: + +- **Title**: Open A P I Test Converter +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Open A P I Test Converter**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/open-a-p-i-extractor/extract-openapi-from-verbose`: + - `GET`: Extract Openapi From Verbose +- `/open-a-p-i-extractor/extract-openapi-from-code`: + - `GET`: Extract Openapi From Code +- `/open-a-p-i-extractor/add-test-examples`: + - `POST`: Add Test Examples +- `/open-a-p-i-extractor/save-openapi-contract`: + - `GET`: Save Openapi Contract +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit + +---### FEATURE-ENFORCEMENTCONFIG + +**Info**: + +- **Title**: Enforcement Config +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enforcement Config**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/enforcement-config/from-preset`: + - `GET`: From Preset +- `/enforcement-config/should-block-deviation`: + - `GET`: Should Block Deviation +- `/enforcement-config/get-action`: + - `GET`: Get Action +- `/enforcement-config/to-summary-dict`: + - `GET`: To Summary Dict +**Schemas**: + +- `EnforcementConfig`: object + +---### FEATURE-GRAPHANALYZER + +**Info**: + +- **Title**: Graph Analyzer +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Graph Analyzer**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/graph-analyzer/extract-call-graph`: + - `GET`: Extract Call Graph +- `/graph-analyzer/build-dependency-graph`: + - `GET`: Build Dependency Graph +- `/graph-analyzer/get-graph-summary`: + - `GET`: Get Graph Summary +- `/control-flow-analyzer/extract-scenarios-from-method`: + - `GET`: Extract Scenarios From Method + +---### FEATURE-PROJECTCONTEXT + +**Info**: + +- **Title**: Project Context +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Project Context**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/enrichment-context/add-relationships`: + - `POST`: Add Relationships +- `/enrichment-context/add-contract`: + - `POST`: Add Contract +- `/enrichment-context/add-bundle-metadata`: + - `POST`: Add Bundle Metadata +- `/enrichment-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/to-markdown`: + - `GET`: To Markdown +- `/project-bundle/load-from-directory`: + - `GET`: Load From Directory +- `/project-bundle/save-to-directory`: + - `GET`: Save To Directory +- `/project-bundle/get-feature/{key}`: + - `GET`: Get Feature +- `/project-bundle/add-feature`: + - `POST`: Add Feature +- `/project-bundle/update-feature/{key}`: + - `PUT`: Update Feature +- `/project-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/project-context/to-dict`: + - `GET`: To Dict +**Schemas**: + +- `BundleVersions`: object +- `SchemaMetadata`: object +- `ProjectMetadata`: object +- `BundleChecksums`: object +- `SectionLock`: object +- `PersonaMapping`: object +- `FeatureIndex`: object +- `ProtocolIndex`: object +- `BundleManifest`: object +- `ProjectBundle`: object + +---### FEATURE-PLANCOMPARATOR + +**Info**: + +- **Title**: Plan Comparator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Comparator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-CONTRACTEXTRACTOR + +**Info**: + +- **Title**: Contract Extractor +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Contract Extractor**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/requirement-extractor/extract-complete-requirement`: + - `GET`: Extract Complete Requirement +- `/requirement-extractor/extract-method-requirement`: + - `GET`: Extract Method Requirement +- `/requirement-extractor/extract-nfrs`: + - `GET`: Extract Nfrs +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/open-a-p-i-extractor/extract-openapi-from-verbose`: + - `GET`: Extract Openapi From Verbose +- `/open-a-p-i-extractor/extract-openapi-from-code`: + - `GET`: Extract Openapi From Code +- `/open-a-p-i-extractor/add-test-examples`: + - `POST`: Add Test Examples +- `/open-a-p-i-extractor/save-openapi-contract`: + - `GET`: Save Openapi Contract +- `/constitution-evidence-extractor/extract-article-vii-evidence`: + - `GET`: Extract Article Vii Evidence +- `/constitution-evidence-extractor/extract-article-viii-evidence`: + - `GET`: Extract Article Viii Evidence +- `/constitution-evidence-extractor/extract-article-ix-evidence`: + - `GET`: Extract Article Ix Evidence +- `/constitution-evidence-extractor/extract-all-evidence`: + - `GET`: Extract All Evidence +- `/constitution-evidence-extractor/generate-constitution-check-section`: + - `GET`: Generate Constitution Check Section + +---### FEATURE-ENRICHMENTREPORT + +**Info**: + +- **Title**: Enrichment Report +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enrichment Report**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String +- `/enrichment-report/add-missing-feature`: + - `POST`: Add Missing Feature +- `/enrichment-report/adjust-confidence`: + - `GET`: Adjust Confidence +- `/enrichment-report/add-business-context`: + - `POST`: Add Business Context +- `/enrichment-parser/parse`: + - `GET`: Parse +- `/enrichment-context/add-relationships`: + - `POST`: Add Relationships +- `/enrichment-context/add-contract`: + - `POST`: Add Contract +- `/enrichment-context/add-bundle-metadata`: + - `POST`: Add Bundle Metadata +- `/enrichment-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/to-markdown`: + - `GET`: To Markdown + +---### FEATURE-COMMANDROUTER + +**Info**: + +- **Title**: Command Router +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Command Router**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/command-router/route`: + - `GET`: Route +- `/command-router/route-with-auto-detect`: + - `GET`: Route With Auto Detect +- `/command-router/should-use-agent`: + - `GET`: Should Use Agent +- `/command-router/should-use-direct`: + - `GET`: Should Use Direct + +---### FEATURE-BRIDGESYNC + +**Info**: + +- **Title**: Bridge Sync +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Sync**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-PLANAGENT + +**Info**: + +- **Title**: Plan Agent +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Agent**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/analyze-agent/execute`: + - `GET`: Execute +- `/analyze-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/analyze-codebase`: + - `GET`: Analyze Codebase +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-TEXTUTILS + +**Info**: + +- **Title**: Text Utils +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Text Utils**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/y-a-m-l-utils/load`: + - `GET`: Load +- `/y-a-m-l-utils/load-string`: + - `GET`: Load String +- `/y-a-m-l-utils/dump`: + - `GET`: Dump +- `/y-a-m-l-utils/dump-string`: + - `GET`: Dump String +- `/y-a-m-l-utils/merge-yaml`: + - `GET`: Merge Yaml +- `/project-context/to-dict`: + - `GET`: To Dict +- `/text-utils/shorten-text`: + - `GET`: Shorten Text +- `/text-utils/clean-code`: + - `GET`: Clean Code +- `/enrichment-context/add-relationships`: + - `POST`: Add Relationships +- `/enrichment-context/add-contract`: + - `POST`: Add Contract +- `/enrichment-context/add-bundle-metadata`: + - `POST`: Add Bundle Metadata +- `/enrichment-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/to-markdown`: + - `GET`: To Markdown + +---### FEATURE-PROMPTVALIDATOR + +**Info**: + +- **Title**: Prompt Validator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Prompt Validator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/c-l-i-artifact-metadata/to-dict`: + - `GET`: To Dict +- `/c-l-i-artifact-metadata/from-dict`: + - `GET`: From Dict +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict + +---### FEATURE-SYNCAGENT + +**Info**: + +- **Title**: Sync Agent +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Sync Agent**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/analyze-agent/execute`: + - `GET`: Execute +- `/analyze-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/analyze-codebase`: + - `GET`: Analyze Codebase +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-SCHEMAVALIDATOR + +**Info**: + +- **Title**: Schema Validator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Schema Validator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/schema-validator/validate-json-schema`: + - `GET`: Validate Json Schema +- `/c-l-i-artifact-metadata/to-dict`: + - `GET`: To Dict +- `/c-l-i-artifact-metadata/from-dict`: + - `GET`: From Dict +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict + +---### FEATURE-CHECKRESULT + +**Info**: + +- **Title**: Check Result +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Check Result**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/check-result/to-dict`: + - `GET`: To Dict +- `/repro-report/add-check`: + - `POST`: Add Check +- `/repro-report/get-exit-code`: + - `GET`: Get Exit Code +- `/repro-report/to-dict`: + - `GET`: To Dict +- `/repro-checker/run-check/{name}`: + - `GET`: Run Check +- `/repro-checker/run-all-checks`: + - `GET`: Run All Checks + +---### FEATURE-CONTRACTFIRSTTESTMANAGER + +**Info**: + +- **Title**: Contract First Test Manager +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Contract First Test Manager**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/c-l-i-artifact-metadata/to-dict`: + - `GET`: To Dict +- `/c-l-i-artifact-metadata/from-dict`: + - `GET`: From Dict + +---### FEATURE-OPENAPIEXTRACTOR + +**Info**: + +- **Title**: Open A P I Extractor +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Open A P I Extractor**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/requirement-extractor/extract-complete-requirement`: + - `GET`: Extract Complete Requirement +- `/requirement-extractor/extract-method-requirement`: + - `GET`: Extract Method Requirement +- `/requirement-extractor/extract-nfrs`: + - `GET`: Extract Nfrs +- `/open-a-p-i-extractor/extract-openapi-from-verbose`: + - `GET`: Extract Openapi From Verbose +- `/open-a-p-i-extractor/extract-openapi-from-code`: + - `GET`: Extract Openapi From Code +- `/open-a-p-i-extractor/add-test-examples`: + - `POST`: Add Test Examples +- `/open-a-p-i-extractor/save-openapi-contract`: + - `GET`: Save Openapi Contract +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/constitution-evidence-extractor/extract-article-vii-evidence`: + - `GET`: Extract Article Vii Evidence +- `/constitution-evidence-extractor/extract-article-viii-evidence`: + - `GET`: Extract Article Viii Evidence +- `/constitution-evidence-extractor/extract-article-ix-evidence`: + - `GET`: Extract Article Ix Evidence +- `/constitution-evidence-extractor/extract-all-evidence`: + - `GET`: Extract All Evidence +- `/constitution-evidence-extractor/generate-constitution-check-section`: + - `GET`: Generate Constitution Check Section + +---### FEATURE-REPROCHECKER + +**Info**: + +- **Title**: Repro Checker +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Repro Checker**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/check-result/to-dict`: + - `GET`: To Dict +- `/repro-report/add-check`: + - `POST`: Add Check +- `/repro-report/get-exit-code`: + - `GET`: Get Exit Code +- `/repro-report/to-dict`: + - `GET`: To Dict +- `/repro-checker/run-check/{name}`: + - `GET`: Run Check +- `/repro-checker/run-all-checks`: + - `GET`: Run All Checks + +---### FEATURE-SPECKITCONVERTER + +**Info**: + +- **Title**: Spec Kit Converter +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec Kit Converter**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict + +---### FEATURE-TELEMETRYSETTINGS + +**Info**: + +- **Title**: Telemetry Settings +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Telemetry Settings**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/telemetry-settings/from-env`: + - `GET`: From Env +- `/telemetry-manager/enabled`: + - `GET`: Enabled +- `/telemetry-manager/last-event`: + - `GET`: Last Event +- `/telemetry-manager/track-command`: + - `GET`: Track Command + +---### FEATURE-IMPLEMENTATIONPLANTEMPLATE + +**Info**: + +- **Title**: Implementation Plan Template +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Implementation Plan Template**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-MESSAGEFLOWFORMATTER + +**Info**: + +- **Title**: Message Flow Formatter +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Message Flow Formatter**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/control-flow-analyzer/extract-scenarios-from-method`: + - `GET`: Extract Scenarios From Method + +---### FEATURE-SOURCEARTIFACTSCANNER + +**Info**: + +- **Title**: Source Artifact Scanner +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Source Artifact Scanner**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/source-tracking/compute-hash`: + - `PUT`: Compute Hash +- `/source-tracking/has-changed`: + - `GET`: Has Changed +- `/source-tracking/update-hash`: + - `PUT`: Update Hash +- `/source-tracking/update-sync-timestamp`: + - `PUT`: Update Sync Timestamp +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/source-artifact-scanner/scan-repository`: + - `GET`: Scan Repository +- `/source-artifact-scanner/link-to-specs`: + - `GET`: Link To Specs +- `/source-artifact-scanner/extract-function-mappings`: + - `GET`: Extract Function Mappings +- `/source-artifact-scanner/extract-test-mappings`: + - `GET`: Extract Test Mappings +- `/ambiguity-scanner/scan`: + - `GET`: Scan +**Schemas**: + +- `SourceTracking`: object + +---### FEATURE-BRIDGEWATCHEVENTHANDLER + +**Info**: + +- **Title**: Bridge Watch Event Handler +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Watch Event Handler**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/file-hash-cache/load`: + - `GET`: Load +- `/file-hash-cache/save`: + - `GET`: Save +- `/file-hash-cache/get-hash`: + - `GET`: Get Hash +- `/file-hash-cache/set-hash`: + - `GET`: Set Hash +- `/file-hash-cache/get-dependencies`: + - `GET`: Get Dependencies +- `/file-hash-cache/set-dependencies`: + - `GET`: Set Dependencies +- `/file-hash-cache/has-changed`: + - `GET`: Has Changed +- `/enhanced-sync-event-handler/on-modified`: + - `GET`: On Modified +- `/enhanced-sync-event-handler/on-created`: + - `POST`: On Created +- `/enhanced-sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/enhanced-sync-watcher/start`: + - `GET`: Start +- `/enhanced-sync-watcher/stop`: + - `GET`: Stop +- `/enhanced-sync-watcher/watch`: + - `GET`: Watch +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/sync-event-handler/on-modified`: + - `GET`: On Modified +- `/sync-event-handler/on-created`: + - `POST`: On Created +- `/sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/sync-watcher/start`: + - `GET`: Start +- `/sync-watcher/stop`: + - `GET`: Stop +- `/sync-watcher/watch`: + - `GET`: Watch +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-TELEMETRYMANAGER + +**Info**: + +- **Title**: Telemetry Manager +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Telemetry Manager**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/telemetry-settings/from-env`: + - `GET`: From Env +- `/telemetry-manager/enabled`: + - `GET`: Enabled +- `/telemetry-manager/last-event`: + - `GET`: Last Event +- `/telemetry-manager/track-command`: + - `GET`: Track Command + +---### FEATURE-WORKFLOWGENERATOR + +**Info**: + +- **Title**: Workflow Generator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Workflow Generator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/protocol-generator/generate`: + - `GET`: Generate +- `/protocol-generator/generate-from-template`: + - `GET`: Generate From Template +- `/protocol-generator/render-string`: + - `GET`: Render String +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String + +---### FEATURE-REPROREPORT + +**Info**: + +- **Title**: Repro Report +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Repro Report**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/check-result/to-dict`: + - `GET`: To Dict +- `/repro-report/add-check`: + - `POST`: Add Check +- `/repro-report/get-exit-code`: + - `GET`: Get Exit Code +- `/repro-report/to-dict`: + - `GET`: To Dict +- `/repro-checker/run-check/{name}`: + - `GET`: Run Check +- `/repro-checker/run-all-checks`: + - `GET`: Run All Checks +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String + +---### FEATURE-BRIDGECONFIG + +**Info**: + +- **Title**: Bridge Config +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Config**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-STRUCTUREDFORMAT + +**Info**: + +- **Title**: Structured Format +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Structured Format**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/structured-format/from-string`: + - `GET`: From String +- `/structured-format/from-path`: + - `GET`: From Path + +---### FEATURE-FEATURESPECIFICATIONTEMPLATE + +**Info**: + +- **Title**: Feature Specification Template +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Feature Specification Template**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict + +---### FEATURE-AGENTREGISTRY + +**Info**: + +- **Title**: Agent Registry +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Agent Registry**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/agent-registry/register/{name}`: + - `GET`: Register +- `/agent-registry/{name}`: + - `GET`: Get +- `/agent-registry/get-agent-for-command`: + - `GET`: Get Agent For Command +- `/agent-registry/list-agents`: + - `GET`: List Agents +- `/analyze-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/analyze-agent/execute`: + - `GET`: Execute +- `/analyze-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/analyze-codebase`: + - `GET`: Analyze Codebase + +---### FEATURE-REPORTGENERATOR + +**Info**: + +- **Title**: Report Generator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Report Generator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String +- `/protocol-generator/generate`: + - `GET`: Generate +- `/protocol-generator/generate-from-template`: + - `GET`: Generate From Template +- `/protocol-generator/render-string`: + - `GET`: Render String + +---### FEATURE-DEVIATIONREPORT + +**Info**: + +- **Title**: Deviation Report +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Deviation Report**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/deviation-report/total-deviations`: + - `GET`: Total Deviations +- `/deviation-report/high-count`: + - `GET`: High Count +- `/deviation-report/medium-count`: + - `GET`: Medium Count +- `/deviation-report/low-count`: + - `GET`: Low Count +- `/validation-report/total-deviations`: + - `GET`: Total Deviations +- `/validation-report/add-deviation`: + - `POST`: Add Deviation +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String +**Schemas**: + +- `Deviation`: object +- `DeviationReport`: object +- `ValidationReport`: object + +---### FEATURE-REPOSITORYSYNC + +**Info**: + +- **Title**: Repository Sync +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Repository Sync**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-YAMLUTILS + +**Info**: + +- **Title**: Y A M L Utils +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Y A M L Utils**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/text-utils/shorten-text`: + - `GET`: Shorten Text +- `/text-utils/clean-code`: + - `GET`: Clean Code +- `/y-a-m-l-utils/load`: + - `GET`: Load +- `/y-a-m-l-utils/load-string`: + - `GET`: Load String +- `/y-a-m-l-utils/dump`: + - `GET`: Dump +- `/y-a-m-l-utils/dump-string`: + - `GET`: Dump String +- `/y-a-m-l-utils/merge-yaml`: + - `GET`: Merge Yaml + +---### FEATURE-ENHANCEDSYNCWATCHER + +**Info**: + +- **Title**: Enhanced Sync Watcher +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enhanced Sync Watcher**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/file-hash-cache/load`: + - `GET`: Load +- `/file-hash-cache/save`: + - `GET`: Save +- `/file-hash-cache/get-hash`: + - `GET`: Get Hash +- `/file-hash-cache/set-hash`: + - `GET`: Set Hash +- `/file-hash-cache/get-dependencies`: + - `GET`: Get Dependencies +- `/file-hash-cache/set-dependencies`: + - `GET`: Set Dependencies +- `/file-hash-cache/has-changed`: + - `GET`: Has Changed +- `/enhanced-sync-event-handler/on-modified`: + - `GET`: On Modified +- `/enhanced-sync-event-handler/on-created`: + - `POST`: On Created +- `/enhanced-sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/enhanced-sync-watcher/start`: + - `GET`: Start +- `/enhanced-sync-watcher/stop`: + - `GET`: Stop +- `/enhanced-sync-watcher/watch`: + - `GET`: Watch +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/sync-event-handler/on-modified`: + - `GET`: On Modified +- `/sync-event-handler/on-created`: + - `POST`: On Created +- `/sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/sync-watcher/start`: + - `GET`: Start +- `/sync-watcher/stop`: + - `GET`: Stop +- `/sync-watcher/watch`: + - `GET`: Watch +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-PLANGENERATOR + +**Info**: + +- **Title**: Plan Generator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Generator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String +- `/plan-comparator/compare`: + - `GET`: Compare +- `/protocol-generator/generate`: + - `GET`: Generate +- `/protocol-generator/generate-from-template`: + - `GET`: Generate From Template +- `/protocol-generator/render-string`: + - `GET`: Render String +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-PERFORMANCEMETRIC + +**Info**: + +- **Title**: Performance Metric +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Performance Metric**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/performance-metric/to-dict`: + - `GET`: To Dict +- `/performance-report/add-metric`: + - `POST`: Add Metric +- `/performance-report/get-summary`: + - `GET`: Get Summary +- `/performance-report/print-summary`: + - `GET`: Print Summary +- `/performance-monitor/start`: + - `GET`: Start +- `/performance-monitor/stop`: + - `GET`: Stop +- `/performance-monitor/track`: + - `GET`: Track +- `/performance-monitor/get-report`: + - `GET`: Get Report +- `/performance-monitor/disable`: + - `GET`: Disable +- `/performance-monitor/enable`: + - `GET`: Enable + +---### FEATURE-CONTRACTGENERATOR + +**Info**: + +- **Title**: Contract Generator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Contract Generator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/protocol-generator/generate`: + - `GET`: Generate +- `/protocol-generator/generate-from-template`: + - `GET`: Generate From Template +- `/protocol-generator/render-string`: + - `GET`: Render String +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String + +---### FEATURE-LOGGERSETUP + +**Info**: + +- **Title**: Logger Setup +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Logger Setup**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/message-flow-formatter/format`: + - `GET`: Format +- `/logger-setup/shutdown-listeners`: + - `GET`: Shutdown Listeners +- `/logger-setup/create-agent-flow-logger`: + - `POST`: Create Agent Flow Logger +- `/logger-setup/create-logger/{name}`: + - `POST`: Create Logger +- `/logger-setup/flush-all-loggers`: + - `GET`: Flush All Loggers +- `/logger-setup/flush-logger/{name}`: + - `GET`: Flush Logger +- `/logger-setup/write-test-summary`: + - `GET`: Write Test Summary +- `/logger-setup/get-logger/{name}`: + - `GET`: Get Logger +- `/logger-setup/trace`: + - `GET`: Trace +- `/logger-setup/redact-secrets`: + - `GET`: Redact Secrets + +---### FEATURE-SPECTOCODESYNC + +**Info**: + +- **Title**: Spec To Code Sync +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec To Code Sync**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop + +---### FEATURE-CODEANALYZER + +**Info**: + +- **Title**: Code Analyzer +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Code Analyzer**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/graph-analyzer/extract-call-graph`: + - `GET`: Extract Call Graph +- `/graph-analyzer/build-dependency-graph`: + - `GET`: Build Dependency Graph +- `/graph-analyzer/get-graph-summary`: + - `GET`: Get Graph Summary +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/control-flow-analyzer/extract-scenarios-from-method`: + - `GET`: Extract Scenarios From Method + +---### FEATURE-PROGRESSIVEDISCLOSUREGROUP + +**Info**: + +- **Title**: Progressive Disclosure Group +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Progressive Disclosure Group**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/progressive-disclosure-group/get-params`: + - `GET`: Get Params +- `/progressive-disclosure-command/format-help`: + - `GET`: Format Help +- `/progressive-disclosure-command/get-params`: + - `GET`: Get Params + +---### FEATURE-DRIFTDETECTOR + +**Info**: + +- **Title**: Drift Detector +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Drift Detector**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/drift-detector/scan`: + - `GET`: Scan +- `/change-detector/detect-changes`: + - `GET`: Detect Changes + +---### FEATURE-FSMVALIDATOR + +**Info**: + +- **Title**: F S M Validator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for F S M Validator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/c-l-i-artifact-metadata/to-dict`: + - `GET`: To Dict +- `/c-l-i-artifact-metadata/from-dict`: + - `GET`: From Dict + +---### FEATURE-RELATIONSHIPMAPPER + +**Info**: + +- **Title**: Relationship Mapper +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Relationship Mapper**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/relationship-mapper/analyze-file`: + - `GET`: Analyze File +- `/relationship-mapper/analyze-files`: + - `GET`: Analyze Files +- `/relationship-mapper/get-relationship-graph`: + - `GET`: Get Relationship Graph + +--- +## Ownership & Locks + +No sections currently locked + +## Validation Checklist + +- [ ] All features have technical constraints defined +- [ ] Protocols/state machines are documented +- [ ] Contracts are defined and validated +- [ ] Architecture decisions are documented +- [ ] Non-functional requirements are specified +- [ ] Risk assessment is complete +- [ ] Deployment architecture is documented + +## Notes + +*Use this section for architectural decisions, trade-offs, or technical clarifications.* diff --git a/_site_local/project-plans/speckit-test/developer.md b/_site_local/project-plans/speckit-test/developer.md new file mode 100644 index 0000000..c9d51a4 --- /dev/null +++ b/_site_local/project-plans/speckit-test/developer.md @@ -0,0 +1,203 @@ +# Project Plan: speckit-test - Developer View + +**Persona**: Developer +**Bundle**: `speckit-test` +**Created**: 2025-12-11T23:36:34.742100+00:00 +**Status**: active +**Last Updated**: 2025-12-11T23:36:34.742122+00:00 + +## Acceptance Criteria & Implementation Details *(mandatory)*### FEATURE-TEXTUTILS: Text Utils + +#### Acceptance Criteria - FEATURE-TEXTUTILS- [ ] The system text utils must provide text utils functionality### FEATURE-MOCKSERVER: Mock Server + +#### Acceptance Criteria - FEATURE-MOCKSERVER- [ ] The system mock server must provide mock server functionality### FEATURE-SDDMANIFEST: S D D Manifest + +#### Acceptance Criteria - FEATURE-SDDMANIFEST- [ ] The system sddmanifest must provide sddmanifest functionality### FEATURE-FEATURESPECIFICATIONTEMPLATE: Feature Specification Template + +#### Acceptance Criteria - FEATURE-FEATURESPECIFICATIONTEMPLATE- [ ] The system feature specification template must provide feature specification template functionality### FEATURE-VALIDATIONREPORT: Validation Report + +#### Acceptance Criteria - FEATURE-VALIDATIONREPORT- [ ] The system validation report must provide validation report functionality### FEATURE-CLIARTIFACTMETADATA: C L I Artifact Metadata + +#### Acceptance Criteria - FEATURE-CLIARTIFACTMETADATA- [ ] The system cliartifact metadata must provide cliartifact metadata functionality### FEATURE-TEMPLATEMAPPING: Template Mapping + +#### Acceptance Criteria - FEATURE-TEMPLATEMAPPING- [ ] The system template mapping must provide template mapping functionality### FEATURE-PERFORMANCEMETRIC: Performance Metric + +#### Acceptance Criteria - FEATURE-PERFORMANCEMETRIC- [ ] The system performance metric must provide performance metric functionality### FEATURE-DEVIATIONREPORT: Deviation Report + +#### Acceptance Criteria - FEATURE-DEVIATIONREPORT- [ ] The system deviation report must provide deviation report functionality### FEATURE-ARTIFACTMAPPING: Artifact Mapping + +#### Acceptance Criteria - FEATURE-ARTIFACTMAPPING- [ ] The system artifact mapping must provide artifact mapping functionality### FEATURE-TELEMETRYSETTINGS: Telemetry Settings + +#### Acceptance Criteria - FEATURE-TELEMETRYSETTINGS- [ ] The system telemetry settings must provide telemetry settings functionality### FEATURE-TASKLIST: Task List + +#### Acceptance Criteria - FEATURE-TASKLIST- [ ] The system task list must provide task list functionality### FEATURE-CHECKRESULT: Check Result + +#### Acceptance Criteria - FEATURE-CHECKRESULT- [ ] The system check result must validate CheckResult### FEATURE-ENRICHMENTPARSER: Enrichment Parser + +#### Acceptance Criteria - FEATURE-ENRICHMENTPARSER- [ ] The system enrichment parser must provide enrichment parser functionality### FEATURE-SOURCETRACKING: Source Tracking + +#### Acceptance Criteria - FEATURE-SOURCETRACKING- [ ] The system source tracking must provide source tracking functionality### FEATURE-YAMLUTILS: Y A M L Utils + +#### Acceptance Criteria - FEATURE-YAMLUTILS- [ ] The system yamlutils must provide yamlutils functionality### FEATURE-STRUCTUREDFORMAT: Structured Format + +#### Acceptance Criteria - FEATURE-STRUCTUREDFORMAT- [ ] The system structured format must provide structured format functionality### FEATURE-PROGRESSIVEDISCLOSUREGROUP: Progressive Disclosure Group + +#### Acceptance Criteria - FEATURE-PROGRESSIVEDISCLOSUREGROUP- [ ] The system progressive disclosure group must provide progressive disclosure group functionality### FEATURE-CONTRACTEXTRACTIONTEMPLATE: Contract Extraction Template + +#### Acceptance Criteria - FEATURE-CONTRACTEXTRACTIONTEMPLATE- [ ] The system contract extraction template must provide contract extraction template functionality### FEATURE-TELEMETRYMANAGER: Telemetry Manager + +#### Acceptance Criteria - FEATURE-TELEMETRYMANAGER- [ ] The system telemetry manager must telemetrymanager TelemetryManager### FEATURE-ENFORCEMENTCONFIG: Enforcement Config + +#### Acceptance Criteria - FEATURE-ENFORCEMENTCONFIG- [ ] The system enforcement config must provide enforcement config functionality### FEATURE-REPROCHECKER: Repro Checker + +#### Acceptance Criteria - FEATURE-REPROCHECKER- [ ] The system repro checker must validate ReproChecker### FEATURE-FILEHASHCACHE: File Hash Cache + +#### Acceptance Criteria - FEATURE-FILEHASHCACHE- [ ] The system file hash cache must provide file hash cache functionality### FEATURE-DRIFTDETECTOR: Drift Detector + +#### Acceptance Criteria - FEATURE-DRIFTDETECTOR- [ ] The system drift detector must provide drift detector functionality### FEATURE-AMBIGUITYSCANNER: Ambiguity Scanner + +#### Acceptance Criteria - FEATURE-AMBIGUITYSCANNER- [ ] Scanner for identifying ambiguities in plan bundles### FEATURE-RELATIONSHIPMAPPER: Relationship Mapper + +#### Acceptance Criteria - FEATURE-RELATIONSHIPMAPPER- [ ] The system relationship mapper must provide relationship mapper functionality### FEATURE-PROJECTCONTEXT: Project Context + +#### Acceptance Criteria - FEATURE-PROJECTCONTEXT- [ ] The system project context must provide project context functionality### FEATURE-SCHEMAVALIDATOR: Schema Validator + +#### Acceptance Criteria - FEATURE-SCHEMAVALIDATOR- [ ] The system schema validator must provide schema validator functionality### FEATURE-CHANGEDETECTOR: Change Detector + +#### Acceptance Criteria - FEATURE-CHANGEDETECTOR- [ ] The system change detector must provide change detector functionality### FEATURE-PERFORMANCEMONITOR: Performance Monitor + +#### Acceptance Criteria - FEATURE-PERFORMANCEMONITOR- [ ] The system performance monitor must provide performance monitor functionality### FEATURE-AGENTMODE: Agent Mode + +#### Acceptance Criteria - FEATURE-AGENTMODE- [ ] The system agent mode must provide agent mode functionality### FEATURE-BRIDGEWATCHEVENTHANDLER: Bridge Watch Event Handler + +#### Acceptance Criteria - FEATURE-BRIDGEWATCHEVENTHANDLER- [ ] The system bridge watch event handler must bridgewatcheventhandler BridgeWatchEventHandler### FEATURE-GITOPERATIONS: Git Operations + +#### Acceptance Criteria - FEATURE-GITOPERATIONS- [ ] The system git operations must provide git operations functionality### FEATURE-SPECVALIDATIONRESULT: Spec Validation Result + +#### Acceptance Criteria - FEATURE-SPECVALIDATIONRESULT- [ ] The system spec validation result must provide spec validation result functionality### FEATURE-LOGGERSETUP: Logger Setup + +#### Acceptance Criteria - FEATURE-LOGGERSETUP- [ ] The system logger setup must provide logger setup functionality### FEATURE-PROMPTVALIDATOR: Prompt Validator + +#### Acceptance Criteria - FEATURE-PROMPTVALIDATOR- [ ] The system prompt validator must validates prompt templates### FEATURE-PERFORMANCEREPORT: Performance Report + +#### Acceptance Criteria - FEATURE-PERFORMANCEREPORT- [ ] The system performance report must provide performance report functionality### FEATURE-CONTRACTDENSITYMETRICS: Contract Density Metrics + +#### Acceptance Criteria - FEATURE-CONTRACTDENSITYMETRICS- [ ] The system contract density metrics must provide contract density metrics functionality### FEATURE-PLANENRICHER: Plan Enricher + +#### Acceptance Criteria - FEATURE-PLANENRICHER- [ ] The system plan enricher must provide plan enricher functionality### FEATURE-FSMVALIDATOR: F S M Validator + +#### Acceptance Criteria - FEATURE-FSMVALIDATOR- [ ] The system fsmvalidator must provide fsmvalidator functionality### FEATURE-IMPLEMENTATIONPLANTEMPLATE: Implementation Plan Template + +#### Acceptance Criteria - FEATURE-IMPLEMENTATIONPLANTEMPLATE- [ ] The system implementation plan template must provide implementation plan template functionality### FEATURE-REQUIREMENTEXTRACTOR: Requirement Extractor + +#### Acceptance Criteria - FEATURE-REQUIREMENTEXTRACTOR- [ ] The system requirement extractor must extracts complete requirements from code semantics### FEATURE-ENRICHMENTREPORT: Enrichment Report + +#### Acceptance Criteria - FEATURE-ENRICHMENTREPORT- [ ] The system enrichment report must provide enrichment report functionality### FEATURE-AGENTREGISTRY: Agent Registry + +#### Acceptance Criteria - FEATURE-AGENTREGISTRY- [ ] The system agent registry must provide agent registry functionality### FEATURE-REPROREPORT: Repro Report + +#### Acceptance Criteria - FEATURE-REPROREPORT- [ ] The system repro report must provide repro report functionality### FEATURE-PLANCOMPARATOR: Plan Comparator + +#### Acceptance Criteria - FEATURE-PLANCOMPARATOR- [ ] The system plan comparator must provide plan comparator functionality### FEATURE-PROTOCOLGENERATOR: Protocol Generator + +#### Acceptance Criteria - FEATURE-PROTOCOLGENERATOR- [ ] The system protocol generator must provide protocol generator functionality### FEATURE-ENRICHMENTCONTEXT: Enrichment Context + +#### Acceptance Criteria - FEATURE-ENRICHMENTCONTEXT- [ ] The system enrichment context must provide enrichment context functionality### FEATURE-SOURCEARTIFACTSCANNER: Source Artifact Scanner + +#### Acceptance Criteria - FEATURE-SOURCEARTIFACTSCANNER- [ ] Scanner for discovering and linking source artifacts to specifications### FEATURE-CONTRACTGENERATOR: Contract Generator + +#### Acceptance Criteria - FEATURE-CONTRACTGENERATOR- [ ] The system contract generator must generates contract stubs from sdd how sections### FEATURE-BRIDGECONFIG: Bridge Config + +#### Acceptance Criteria - FEATURE-BRIDGECONFIG- [ ] The system bridge config must provide bridge config functionality### FEATURE-SYNCAGENT: Sync Agent + +#### Acceptance Criteria - FEATURE-SYNCAGENT- [ ] The system sync agent must provide sync agent functionality### FEATURE-BRIDGEWATCH: Bridge Watch + +#### Acceptance Criteria - FEATURE-BRIDGEWATCH- [ ] The system bridge watch must provide bridge watch functionality### FEATURE-CONSTITUTIONENRICHER: Constitution Enricher + +#### Acceptance Criteria - FEATURE-CONSTITUTIONENRICHER- [ ] The system constitution enricher must provide constitution enricher functionality### FEATURE-ENHANCEDSYNCWATCHER: Enhanced Sync Watcher + +#### Acceptance Criteria - FEATURE-ENHANCEDSYNCWATCHER- [ ] The system enhanced sync watcher must provide enhanced sync watcher functionality### FEATURE-REPORTGENERATOR: Report Generator + +#### Acceptance Criteria - FEATURE-REPORTGENERATOR- [ ] The system report generator must provide report generator functionality### FEATURE-SYNCWATCHER: Sync Watcher + +#### Acceptance Criteria - FEATURE-SYNCWATCHER- [ ] The system sync watcher must provide sync watcher functionality### FEATURE-PROGRESSIVEDISCLOSURECOMMAND: Progressive Disclosure Command + +#### Acceptance Criteria - FEATURE-PROGRESSIVEDISCLOSURECOMMAND- [ ] The system progressive disclosure command must provide progressive disclosure command functionality### FEATURE-WORKFLOWGENERATOR: Workflow Generator + +#### Acceptance Criteria - FEATURE-WORKFLOWGENERATOR- [ ] The system workflow generator must provide workflow generator functionality### FEATURE-REPOSITORYSYNC: Repository Sync + +#### Acceptance Criteria - FEATURE-REPOSITORYSYNC- [ ] The system repository sync must provide repository sync functionality### FEATURE-PLANMIGRATOR: Plan Migrator + +#### Acceptance Criteria - FEATURE-PLANMIGRATOR- [ ] The system plan migrator must provide plan migrator functionality### FEATURE-CONTRACTEXTRACTOR: Contract Extractor + +#### Acceptance Criteria - FEATURE-CONTRACTEXTRACTOR- [ ] The system contract extractor must extracts api contracts from function signatures, type hints, and validation logic### FEATURE-BRIDGESYNC: Bridge Sync + +#### Acceptance Criteria - FEATURE-BRIDGESYNC- [ ] The system bridge sync must provide bridge sync functionality### FEATURE-CONTROLFLOWANALYZER: Control Flow Analyzer + +#### Acceptance Criteria - FEATURE-CONTROLFLOWANALYZER- [ ] The system control flow analyzer must analyzes ast to extract control flow patterns and generate scenarios### FEATURE-SYNCEVENTHANDLER: Sync Event Handler + +#### Acceptance Criteria - FEATURE-SYNCEVENTHANDLER- [ ] The system sync event handler must synceventhandler SyncEventHandler### FEATURE-COMMANDROUTER: Command Router + +#### Acceptance Criteria - FEATURE-COMMANDROUTER- [ ] The system command router must provide command router functionality### FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR: Constitution Evidence Extractor + +#### Acceptance Criteria - FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR- [ ] The system constitution evidence extractor must extracts evidence-based constitution checklist from code patterns### FEATURE-SPECKITCONVERTER: Spec Kit Converter + +#### Acceptance Criteria - FEATURE-SPECKITCONVERTER- [ ] The system spec kit converter must provide spec kit converter functionality### FEATURE-SPECKITSCANNER: Spec Kit Scanner + +#### Acceptance Criteria - FEATURE-SPECKITSCANNER- [ ] Scanner for Spec-Kit repositories### FEATURE-MESSAGEFLOWFORMATTER: Message Flow Formatter + +#### Acceptance Criteria - FEATURE-MESSAGEFLOWFORMATTER- [ ] The system message flow formatter must provide message flow formatter functionality### FEATURE-SMARTCOVERAGEMANAGER: Smart Coverage Manager + +#### Acceptance Criteria - FEATURE-SMARTCOVERAGEMANAGER- [ ] The system smart coverage manager must smartcoveragemanager SmartCoverageManager### FEATURE-CODEANALYZER: Code Analyzer + +#### Acceptance Criteria - FEATURE-CODEANALYZER- [ ] The system code analyzer must analyzes python code to auto-derive plan bundles### FEATURE-PROJECTBUNDLE: Project Bundle + +#### Acceptance Criteria - FEATURE-PROJECTBUNDLE- [ ] The system project bundle must provide project bundle functionality### FEATURE-BRIDGEPROBE: Bridge Probe + +#### Acceptance Criteria - FEATURE-BRIDGEPROBE- [ ] The system bridge probe must provide bridge probe functionality### FEATURE-GRAPHANALYZER: Graph Analyzer + +#### Acceptance Criteria - FEATURE-GRAPHANALYZER- [ ] The system graph analyzer must provide graph analyzer functionality### FEATURE-PLANAGENT: Plan Agent + +#### Acceptance Criteria - FEATURE-PLANAGENT- [ ] The system plan agent must provide plan agent functionality### FEATURE-OPENAPIEXTRACTOR: Open A P I Extractor + +#### Acceptance Criteria - FEATURE-OPENAPIEXTRACTOR- [ ] The system open apiextractor must provide open apiextractor functionality### FEATURE-PLANBUNDLE: Plan Bundle + +#### Acceptance Criteria - FEATURE-PLANBUNDLE- [ ] The system plan bundle must provide plan bundle functionality### FEATURE-ENHANCEDSYNCEVENTHANDLER: Enhanced Sync Event Handler + +#### Acceptance Criteria - FEATURE-ENHANCEDSYNCEVENTHANDLER- [ ] The system enhanced sync event handler must enhancedsynceventhandler EnhancedSyncEventHandler### FEATURE-ANALYZEAGENT: Analyze Agent + +#### Acceptance Criteria - FEATURE-ANALYZEAGENT- [ ] The system analyze agent must provide analyze agent functionality### FEATURE-BRIDGETEMPLATELOADER: Bridge Template Loader + +#### Acceptance Criteria - FEATURE-BRIDGETEMPLATELOADER- [ ] The system bridge template loader must provide bridge template loader functionality### FEATURE-SPECTOCODESYNC: Spec To Code Sync + +#### Acceptance Criteria - FEATURE-SPECTOCODESYNC- [ ] The system spec to code sync must provide spec to code sync functionality### FEATURE-CODETOSPECSYNC: Code To Spec Sync + +#### Acceptance Criteria - FEATURE-CODETOSPECSYNC- [ ] The system code to spec sync must provide code to spec sync functionality### FEATURE-PLANGENERATOR: Plan Generator + +#### Acceptance Criteria - FEATURE-PLANGENERATOR- [ ] The system plan generator must provide plan generator functionality### FEATURE-SPECKITSYNC: Spec Kit Sync + +#### Acceptance Criteria - FEATURE-SPECKITSYNC- [ ] The system spec kit sync must provide spec kit sync functionality### FEATURE-SPECFACTSTRUCTURE: Spec Fact Structure + +#### Acceptance Criteria - FEATURE-SPECFACTSTRUCTURE- [ ] Manages the canonical### FEATURE-OPENAPITESTCONVERTER: Open A P I Test Converter + +#### Acceptance Criteria - FEATURE-OPENAPITESTCONVERTER- [ ] The system open apitest converter must provide open apitest converter functionality### FEATURE-CONTRACTFIRSTTESTMANAGER: Contract First Test Manager + +#### Acceptance Criteria - FEATURE-CONTRACTFIRSTTESTMANAGER- [ ] The system contract first test manager must contractfirsttestmanager ContractFirstTestManager## Ownership & Locks + +No sections currently locked + +## Validation Checklist + +- [ ] All features have acceptance criteria defined +- [ ] Acceptance criteria are testable +- [ ] Implementation tasks are documented +- [ ] API contracts are defined +- [ ] Test scenarios are documented +- [ ] Code mappings are complete +- [ ] Edge cases are considered +- [ ] Testing strategy is defined +- [ ] Definition of Done criteria are met + +## Notes + +*Use this section for implementation questions, technical notes, or development clarifications.* diff --git a/_site_local/project-plans/speckit-test/product-owner.md b/_site_local/project-plans/speckit-test/product-owner.md new file mode 100644 index 0000000..63d8373 --- /dev/null +++ b/_site_local/project-plans/speckit-test/product-owner.md @@ -0,0 +1,11214 @@ +# Project Plan: speckit-test - Product Owner View + +**Persona**: Product Owner +**Bundle**: `speckit-test` +**Created**: 2025-12-11T22:36:03.710567+00:00 +**Status**: active +**Last Updated**: 2025-12-11T22:36:03.710581+00:00 + +## Idea & Business Context *(mandatory)* + +### Problem Statement + +*[ACTION REQUIRED: Define the problem this project solves]* + +### Solution Vision + +*[ACTION REQUIRED: Describe the envisioned solution]* + +### Success Metrics + +- *[ACTION REQUIRED: Define measurable success metrics]* + +## Features & User Stories *(mandatory)* + +### FEATURE-PROGRESSIVEDISCLOSUREGROUP: Progressive Disclosure Group + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can view Progressive Disclosure Group data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Override get_params to include hidden options when advanced help is requested. +- [ ] Error handling: Invalid format produces clear validation errors +- [ ] Empty states: Missing format fields use sensible defaults +- [ ] Validation: Required fields validated before format conversion + +--- + +#### Feature Outcomes + +- Custom Typer group that shows hidden options when advanced help is requested. +- Provides CRUD operations: READ params +### FEATURE-MOCKSERVER: Mock Server + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Mock Server features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Check if mock server is running. +- [ ] Stop the mock server. + +--- + +#### Feature Outcomes + +- Mock server instance. +### FEATURE-SDDMANIFEST: S D D Manifest + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 4 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can validate S D D Manifest data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate SDD manifest structure (custom validation beyond Pydantic). + +--- +**Story 2**: As a user, I can update S D D Manifest records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Update the updated_at timestamp. + +--- + +#### Feature Outcomes + +- SDD manifest with WHY/WHAT/HOW, hashes, and coverage thresholds. +- Defines data models: $MODEL +- Provides CRUD operations: UPDATE timestamp +### FEATURE-ARTIFACTMAPPING: Artifact Mapping + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Artifact Mapping features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Resolve dynamic path pattern with context variables. + +--- + +#### Feature Outcomes + +- Maps SpecFact logical concepts to physical tool paths. +- Defines data models: $MODEL +### FEATURE-TEXTUTILS: Text Utils + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Text Utils features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Shorten text to a maximum length, appending '...' if truncated. +- [ ] Extract code from markdown triple-backtick fences. If multiple fenced + +--- + +#### Feature Outcomes + +- A utility class for text manipulation. +### FEATURE-PERFORMANCEMETRIC: Performance Metric + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Performance Metric features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. +- [ ] Error handling: Invalid input produces clear validation errors +- [ ] Empty states: Missing data uses sensible defaults +- [ ] Validation: Required fields validated before processing + +--- + +#### Feature Outcomes + +- Performance metric for a single operation. +### FEATURE-VALIDATIONREPORT: Validation Report + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 4 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Validation Report features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Total number of deviations. + +--- +**Story 2**: As a user, I can create new Validation Report records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add a deviation and update counts. + +--- + +#### Feature Outcomes + +- Validation report model (for backward compatibility). +- Defines data models: $MODEL +- Provides CRUD operations: CREATE deviation +### FEATURE-DEVIATIONREPORT: Deviation Report + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Deviation Report features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Total number of deviations. +- [ ] Number of high severity deviations. +- [ ] Number of medium severity deviations. +- [ ] Number of low severity deviations. + +--- + +#### Feature Outcomes + +- Deviation report model. +- Defines data models: $MODEL +### FEATURE-FEATURESPECIFICATIONTEMPLATE: Feature Specification Template + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Feature Specification Template features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. + +--- + +#### Feature Outcomes + +- Template for feature specifications (brownfield enhancement). +### FEATURE-YAMLUTILS: Y A M L Utils + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Y A M L Utils + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize YAML utilities. + +--- +**Story 2**: As a user, I can use Y A M L Utils features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Load YAML from file. +- [ ] Load YAML from string. +- [ ] Dump data to YAML file. +- [ ] Dump data to YAML string. +- [ ] Deep merge two YAML dictionaries. + +--- + +#### Feature Outcomes + +- Helper class for YAML operations. +### FEATURE-TASKLIST: Task List + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can view Task List data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get task IDs for a specific phase. +- [ ] Get task by ID. +- [ ] Get all dependencies for a task (recursive). + +--- + +#### Feature Outcomes + +- Complete task breakdown for a project bundle. +- Defines data models: $MODEL +- Provides CRUD operations: READ tasks_by_phase, READ task, READ dependencies +### FEATURE-SOURCETRACKING: Source Tracking + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can process data using Source Tracking + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Compute SHA256 hash for change detection. + +--- +**Story 2**: As a user, I can update Source Tracking records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Check if file changed since last sync. +- [ ] Update stored hash for a file. +- [ ] Update last_synced timestamp to current time. + +--- + +#### Feature Outcomes + +- Links specs to actual code/tests with hash-based change detection. +- Defines data models: $MODEL +- Provides CRUD operations: UPDATE hash, UPDATE sync_timestamp +### FEATURE-TELEMETRYSETTINGS: Telemetry Settings + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 8 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Telemetry Settings features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Build telemetry settings from environment variables, config file, and opt-in file. + +--- + +#### Feature Outcomes + +- User-configurable telemetry settings. +### FEATURE-TEMPLATEMAPPING: Template Mapping + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Template Mapping features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Resolve template path for a schema key. +- [ ] Error handling: Invalid data produces clear validation errors +- [ ] Empty states: Missing fields use sensible defaults +- [ ] Validation: Required fields validated before processing + +--- + +#### Feature Outcomes + +- Maps SpecFact schemas to tool prompt templates. +- Defines data models: $MODEL +### FEATURE-CLIARTIFACTMETADATA: C L I Artifact Metadata + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use C L I Artifact Metadata features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. +- [ ] Create from dictionary. +- [ ] Error handling: Invalid input produces clear error messages +- [ ] Empty states: Missing data uses sensible defaults +- [ ] Validation: Required fields validated before processing + +--- + +#### Feature Outcomes + +- Metadata for CLI-generated artifacts. +### FEATURE-ENRICHMENTPARSER: Enrichment Parser + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can analyze data with Enrichment Parser + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Parse Markdown enrichment report. + +--- + +#### Feature Outcomes + +- Parser for Markdown enrichment reports. +### FEATURE-CHECKRESULT: Check Result + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Check Result features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert result to dictionary with structured findings. + +--- + +#### Feature Outcomes + +- Result of a single validation check. +### FEATURE-STRUCTUREDFORMAT: Structured Format + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Structured Format features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert string to StructuredFormat (defaults to YAML). +- [ ] Infer format from file path suffix. +- [ ] Error handling: Invalid data produces clear error messages +- [ ] Empty states: Missing fields use sensible defaults +- [ ] Validation: Required fields validated before processing + +--- + +#### Feature Outcomes + +- Supported structured data formats. +### FEATURE-FILEHASHCACHE: File Hash Cache + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use File Hash Cache features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Load hash cache from disk. +- [ ] Save hash cache to disk. + +--- +**Story 2**: As a user, I can view File Hash Cache data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get cached hash for a file. +- [ ] Get dependencies for a file. + +--- +**Story 3**: As a user, I can update File Hash Cache records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Set hash for a file. +- [ ] Set dependencies for a file. +- [ ] Check if file has changed based on hash. + +--- + +#### Feature Outcomes + +- Cache for file hashes to detect actual changes. +- Provides CRUD operations: READ hash, READ dependencies +### FEATURE-CONTRACTEXTRACTIONTEMPLATE: Contract Extraction Template + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Contract Extraction Template features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. + +--- + +#### Feature Outcomes + +- Template for contract extraction (from legacy code). +### FEATURE-PROJECTCONTEXT: Project Context + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Project Context features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert context to dictionary. + +--- + +#### Feature Outcomes + +- Detected project context information. +### FEATURE-SCHEMAVALIDATOR: Schema Validator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Schema Validator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize schema validator. + +--- +**Story 2**: As a developer, I can validate Schema Validator data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate data against JSON schema. + +--- + +#### Feature Outcomes + +- Schema validator for plan bundles and protocols. +### FEATURE-AMBIGUITYSCANNER: Ambiguity Scanner + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Ambiguity Scanner + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize ambiguity scanner. + +--- +**Story 2**: As a user, I can use Ambiguity Scanner features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Scan plan bundle for ambiguities. + +--- + +#### Feature Outcomes + +- Scanner for identifying ambiguities in plan bundles. +### FEATURE-REPROCHECKER: Repro Checker + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 13 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Repro Checker + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize reproducibility checker. + +--- +**Story 2**: As a developer, I can validate Repro Checker data + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Run a single validation check. +- [ ] Run all validation checks. + +--- + +#### Feature Outcomes + +- Runs validation checks with time budgets and result aggregation. +### FEATURE-ENFORCEMENTCONFIG: Enforcement Config + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can update Enforcement Config records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Create an enforcement config from a preset. + +--- +**Story 2**: As a user, I can use Enforcement Config features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Determine if a deviation should block execution. +- [ ] Convert config to a summary dictionary for display. + +--- +**Story 3**: As a user, I can view Enforcement Config data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get the action for a given severity level. + +--- + +#### Feature Outcomes + +- Configuration for contract enforcement and quality gates. +- Defines data models: $MODEL +- Provides CRUD operations: READ action +### FEATURE-DRIFTDETECTOR: Drift Detector + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Drift Detector + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize drift detector. + +--- +**Story 2**: As a user, I can use Drift Detector features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Comprehensive drift analysis. + +--- + +#### Feature Outcomes + +- Detector for drift between code and specifications. +### FEATURE-TELEMETRYMANAGER: Telemetry Manager + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Telemetry Manager + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) + +--- +**Story 2**: As a user, I can use Telemetry Manager features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Return True if telemetry is active. +- [ ] Expose the last emitted telemetry event (used for tests). +- [ ] Context manager to record anonymized telemetry for a CLI command. + +--- + +#### Feature Outcomes + +- Privacy-first telemetry helper. +### FEATURE-AGENTMODE: Agent Mode + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can generate outputs from Agent Mode + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate enhanced prompt for CoPilot. + +--- +**Story 2**: As a user, I can use Agent Mode features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Execute command with agent mode routing. +- [ ] Inject context information for CoPilot. + +--- + +#### Feature Outcomes + +- Base class for agent modes. +### FEATURE-CHANGEDETECTOR: Change Detector + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Change Detector + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize change detector. + +--- +**Story 2**: As a user, I can update Change Detector records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Detect changes using hash-based comparison. + +--- + +#### Feature Outcomes + +- Detector for changes in code, specs, and tests. +### FEATURE-PERFORMANCEMONITOR: Performance Monitor + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Performance Monitor + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize performance monitor. + +--- +**Story 2**: As a user, I can use Performance Monitor features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Start performance monitoring. +- [ ] Stop performance monitoring. +- [ ] Track an operation's performance. +- [ ] Disable performance monitoring. +- [ ] Enable performance monitoring. + +--- +**Story 3**: As a user, I can view Performance Monitor data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get performance report. + +--- + +#### Feature Outcomes + +- Performance monitor for tracking command execution. +- Provides CRUD operations: READ report +### FEATURE-PROMPTVALIDATOR: Prompt Validator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Prompt Validator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize validator with prompt path. + +--- +**Story 2**: As a developer, I can validate Prompt Validator data + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate prompt structure (required sections). +- [ ] Validate CLI command alignment. +- [ ] Validate wait state rules (optional - only warnings). +- [ ] Validate dual-stack enrichment workflow (if applicable). +- [ ] Validate consistency with other prompts. +- [ ] Run all validations. + +--- + +#### Feature Outcomes + +- Validates prompt templates. +### FEATURE-RELATIONSHIPMAPPER: Relationship Mapper + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Relationship Mapper + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize relationship mapper. + +--- +**Story 2**: As a user, I can analyze data with Relationship Mapper + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Analyze a single file for relationships. +- [ ] Analyze multiple files for relationships (parallelized). + +--- +**Story 3**: As a user, I can view Relationship Mapper data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get relationship graph representation. + +--- + +#### Feature Outcomes + +- Maps relationships, dependencies, and interfaces in a codebase. +- Provides CRUD operations: READ relationship_graph +### FEATURE-FSMVALIDATOR: F S M Validator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure F S M Validator + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize FSM validator. + +--- +**Story 2**: As a developer, I can validate F S M Validator data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate the FSM protocol. +- [ ] Check if transition is valid. + +--- +**Story 3**: As a user, I can view F S M Validator data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get all states reachable from given state. +- [ ] Get all transitions from given state. + +--- + +#### Feature Outcomes + +- FSM validator for protocol validation. +- Provides CRUD operations: READ reachable_states, READ transitions_from +### FEATURE-GITOPERATIONS: Git Operations + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 16 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Git Operations + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize Git operations. + +--- +**Story 2**: As a user, I can use Git Operations features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize a new Git repository. +- [ ] Commit staged changes. +- [ ] Push commits to remote repository. +- [ ] Check if the working directory is clean. + +--- +**Story 3**: As a user, I can create new Git Operations records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Create a new branch. +- [ ] Add files to the staging area. + +--- +**Story 4**: As a developer, I can validate Git Operations data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Checkout an existing branch. + +--- +**Story 5**: As a user, I can view Git Operations data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get the name of the current branch. +- [ ] List all branches. +- [ ] Get list of changed files. + +--- + +#### Feature Outcomes + +- Helper class for Git operations. +- Provides CRUD operations: CREATE branch, READ current_branch, READ changed_files +### FEATURE-LOGGERSETUP: Logger Setup + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can view Logger Setup data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Shuts down all active queue listeners. +- [ ] Get a logger by name + +--- +**Story 2**: As a user, I can create new Logger Setup records + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Creates a dedicated logger for inter-agent message flow. +- [ ] Creates a new logger or returns an existing one with the specified configuration. + +--- +**Story 3**: As a user, I can use Logger Setup features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Flush all active loggers to ensure their output is written +- [ ] Flush a specific logger by name +- [ ] Write test summary in a format that log_analyzer.py can understand +- [ ] Log a message at TRACE level (5) +- [ ] Recursively mask sensitive values (API keys, tokens, passwords, secrets) in dicts/lists/strings. + +--- + +#### Feature Outcomes + +- Utility class for standardized logging setup across all agents +- Provides CRUD operations: CREATE agent_flow_logger, CREATE logger, READ logger +### FEATURE-SPECVALIDATIONRESULT: Spec Validation Result + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Spec Validation Result features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. +- [ ] Convert to JSON string. + +--- + +#### Feature Outcomes + +- Result of Specmatic validation. +### FEATURE-BRIDGEWATCHEVENTHANDLER: Bridge Watch Event Handler + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Bridge Watch Event Handler + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize bridge watch event handler. + +--- + +#### Feature Outcomes + +- Event handler for bridge-based watch mode. +### FEATURE-REPROREPORT: Repro Report + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can create new Repro Report records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add a check result to the report. + +--- +**Story 2**: As a user, I can view Repro Report data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get exit code for the repro command. + +--- +**Story 3**: As a user, I can use Repro Report features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert report to dictionary with structured findings. + +--- + +#### Feature Outcomes + +- Aggregated report of all validation checks. +- Provides CRUD operations: CREATE check, READ exit_code +### FEATURE-PERFORMANCEREPORT: Performance Report + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 6 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can create new Performance Report records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add a performance metric. + +--- +**Story 2**: As a user, I can view Performance Report data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get summary of performance report. + +--- +**Story 3**: As a user, I can use Performance Report features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Print performance summary to console. + +--- + +#### Feature Outcomes + +- Performance report for a command execution. +- Provides CRUD operations: CREATE metric, READ summary +### FEATURE-CONTRACTDENSITYMETRICS: Contract Density Metrics + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 4 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Contract Density Metrics + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize contract density metrics. + +--- +**Story 2**: As a user, I can use Contract Density Metrics features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert metrics to dictionary. + +--- + +#### Feature Outcomes + +- Contract density metrics for a plan bundle. +### FEATURE-AGENTREGISTRY: Agent Registry + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Agent Registry + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize agent registry with default agents. + +--- +**Story 2**: As a user, I can use Agent Registry features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Register an agent instance. + +--- +**Story 3**: As a user, I can view Agent Registry data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get an agent instance by name. +- [ ] Get agent instance for a command. +- [ ] List all registered agent names. + +--- + +#### Feature Outcomes + +- Registry for agent mode instances. +- Provides CRUD operations: READ agent_for_command +### FEATURE-PLANENRICHER: Plan Enricher + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 8 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Plan Enricher features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Enrich plan bundle by enhancing vague acceptance criteria, incomplete requirements, and generic tasks. + +--- + +#### Feature Outcomes + +- Enricher for automatically enhancing plan bundles. +### FEATURE-IMPLEMENTATIONPLANTEMPLATE: Implementation Plan Template + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Implementation Plan Template features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. + +--- + +#### Feature Outcomes + +- Template for implementation plans (modernization roadmap). +### FEATURE-SYNCAGENT: Sync Agent + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can generate outputs from Sync Agent + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate enhanced prompt for sync operation. + +--- +**Story 2**: As a user, I can use Sync Agent features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Execute sync command with enhanced prompts. +- [ ] Inject context information specific to sync operations. + +--- + +#### Feature Outcomes + +- Bidirectional sync agent with conflict resolution. +### FEATURE-ENRICHMENTCONTEXT: Enrichment Context + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Enrichment Context + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize empty enrichment context. + +--- +**Story 2**: As a user, I can create new Enrichment Context records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add relationship data to context. +- [ ] Add contract for a feature. +- [ ] Add bundle metadata to context. + +--- +**Story 3**: As a user, I can use Enrichment Context features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert context to dictionary for LLM consumption. +- [ ] Convert context to Markdown format for LLM prompt. + +--- + +#### Feature Outcomes + +- Context for LLM enrichment workflow. +### FEATURE-SOURCEARTIFACTSCANNER: Source Artifact Scanner + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Source Artifact Scanner + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize scanner with repository path. + +--- +**Story 2**: As a user, I can use Source Artifact Scanner features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Discover existing files and their current state. +- [ ] Map code files → feature specs using AST analysis (parallelized). + +--- +**Story 3**: As a user, I can analyze data with Source Artifact Scanner + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract function names from code. +- [ ] Extract test function names from test file. + +--- + +#### Feature Outcomes + +- Scanner for discovering and linking source artifacts to specifications. +### FEATURE-ENRICHMENTREPORT: Enrichment Report + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 6 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Enrichment Report + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize empty enrichment report. + +--- +**Story 2**: As a user, I can create new Enrichment Report records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add a missing feature discovered by LLM. +- [ ] Add business context items. + +--- +**Story 3**: As a user, I can use Enrichment Report features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Adjust confidence score for a feature. + +--- + +#### Feature Outcomes + +- Parsed enrichment report from LLM. +### FEATURE-REQUIREMENTEXTRACTOR: Requirement Extractor + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Requirement Extractor + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize requirement extractor. + +--- +**Story 2**: As a user, I can analyze data with Requirement Extractor + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract complete requirement statement from class. +- [ ] Extract complete requirement statement from method. +- [ ] Extract Non-Functional Requirements from code patterns. + +--- + +#### Feature Outcomes + +- Extracts complete requirements from code semantics. +### FEATURE-BRIDGEWATCH: Bridge Watch + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Bridge Watch + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize bridge watch mode. + +--- +**Story 2**: As a user, I can use Bridge Watch features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Start watching for file system changes. +- [ ] Stop watching for file system changes. +- [ ] Continuously watch and sync changes. + +--- + +#### Feature Outcomes + +- Bridge-based watch mode for continuous sync operations. +### FEATURE-CONTRACTGENERATOR: Contract Generator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Contract Generator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize contract generator. + +--- +**Story 2**: As a user, I can generate outputs from Contract Generator + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate contract stubs from SDD HOW sections. + +--- + +#### Feature Outcomes + +- Generates contract stubs from SDD HOW sections. +### FEATURE-PLANCOMPARATOR: Plan Comparator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can compare Plan Comparator data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Compare two plan bundles and generate deviation report. + +--- + +#### Feature Outcomes + +- Compares two plan bundles to detect deviations. +### FEATURE-PROTOCOLGENERATOR: Protocol Generator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Protocol Generator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize protocol generator. + +--- +**Story 2**: As a user, I can generate outputs from Protocol Generator + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate protocol YAML file from model. +- [ ] Generate file from custom template. + +--- +**Story 3**: As a user, I can use Protocol Generator features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Render protocol to YAML string without writing to file. + +--- + +#### Feature Outcomes + +- Generator for protocol YAML files. +### FEATURE-REPORTGENERATOR: Report Generator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Report Generator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize report generator. + +--- +**Story 2**: As a user, I can generate outputs from Report Generator + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate validation report file. +- [ ] Generate deviation report file. + +--- +**Story 3**: As a user, I can use Report Generator features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Render report to markdown string without writing to file. + +--- + +#### Feature Outcomes + +- Generator for validation and deviation reports. +### FEATURE-BRIDGECONFIG: Bridge Config + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Bridge Config features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Load bridge configuration from YAML file. +- [ ] Save bridge configuration to YAML file. +- [ ] Resolve dynamic path pattern with context variables. +- [ ] Resolve template path for a schema key. + +--- +**Story 2**: As a user, I can view Bridge Config data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get command mapping by key. + +--- +**Story 3**: As a user, I can update Bridge Config records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Create Spec-Kit classic layout bridge preset. +- [ ] Create Spec-Kit modern layout bridge preset. +- [ ] Create generic markdown bridge preset. + +--- + +#### Feature Outcomes + +- Bridge configuration (translation layer between SpecFact and external tools). +- Defines data models: $MODEL +- Provides CRUD operations: READ command +### FEATURE-SYNCWATCHER: Sync Watcher + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Sync Watcher + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize sync watcher. + +--- +**Story 2**: As a user, I can use Sync Watcher features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Start watching for file system changes. +- [ ] Stop watching for file system changes. +- [ ] Continuously watch and sync changes. + +--- + +#### Feature Outcomes + +- Watch mode for continuous sync operations. +### FEATURE-CONSTITUTIONENRICHER: Constitution Enricher + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can analyze data with Constitution Enricher + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Analyze repository and extract constitution metadata. + +--- +**Story 2**: As a user, I can use Constitution Enricher features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Suggest principles based on repository analysis. +- [ ] Fill constitution template with suggestions. +- [ ] Generate bootstrap constitution from repository analysis. + +--- +**Story 3**: As a developer, I can validate Constitution Enricher data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate constitution completeness. + +--- + +#### Feature Outcomes + +- Enricher for automatically generating and enriching project constitutions. +### FEATURE-BRIDGESYNC: Bridge Sync + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Bridge Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize bridge sync. + +--- +**Story 2**: As a user, I can use Bridge Sync features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Resolve artifact path using bridge configuration. +- [ ] Import artifact from tool format to SpecFact project bundle. +- [ ] Export artifact from SpecFact project bundle to tool format. +- [ ] Perform bidirectional sync for all artifacts. + +--- + +#### Feature Outcomes + +- Adapter-agnostic bidirectional sync using bridge configuration. +### FEATURE-REPOSITORYSYNC: Repository Sync + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Repository Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize repository sync. + +--- +**Story 2**: As a user, I can update Repository Sync records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Sync code changes to SpecFact artifacts. +- [ ] Detect code changes in repository. +- [ ] Update plan artifacts based on code changes. + +--- +**Story 3**: As a user, I can use Repository Sync features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Track deviations from manual plans. + +--- + +#### Feature Outcomes + +- Sync code changes to SpecFact artifacts. +- Provides CRUD operations: UPDATE plan_artifacts +### FEATURE-WORKFLOWGENERATOR: Workflow Generator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Workflow Generator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize workflow generator. + +--- +**Story 2**: As a user, I can generate outputs from Workflow Generator + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate GitHub Action workflow for SpecFact validation. +- [ ] Generate Semgrep async rules for the repository. + +--- + +#### Feature Outcomes + +- Generator for GitHub Actions workflows and Semgrep rules. +### FEATURE-ENHANCEDSYNCWATCHER: Enhanced Sync Watcher + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Enhanced Sync Watcher + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize enhanced sync watcher. + +--- +**Story 2**: As a user, I can use Enhanced Sync Watcher features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Start watching for file system changes. +- [ ] Stop watching for file system changes. +- [ ] Continuously watch and sync changes. + +--- + +#### Feature Outcomes + +- Enhanced watch mode with hash-based change detection, dependency tracking, and LZ4 cache. +### FEATURE-MESSAGEFLOWFORMATTER: Message Flow Formatter + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Message Flow Formatter + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize the formatter with the agent name + +--- +**Story 2**: As a user, I can use Message Flow Formatter features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Format the log record according to message flow patterns + +--- + +#### Feature Outcomes + +- Custom formatter that recognizes message flow patterns and formats them accordingly +### FEATURE-PROGRESSIVEDISCLOSURECOMMAND: Progressive Disclosure Command + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Progressive Disclosure Command features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Override format_help to conditionally show advanced options in docstring. + +--- +**Story 2**: As a user, I can view Progressive Disclosure Command data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Override get_params to include hidden options when advanced help is requested. + +--- + +#### Feature Outcomes + +- Custom Typer command that shows hidden options when advanced help is requested. +- Provides CRUD operations: READ params +### FEATURE-COMMANDROUTER: Command Router + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Command Router features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Route a command based on operational mode. +- [ ] Check if command should use agent routing. +- [ ] Check if command should use direct execution. + +--- +**Story 2**: As a user, I can analyze data with Command Router + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Route a command with automatic mode detection. + +--- + +#### Feature Outcomes + +- Routes commands based on operational mode. +### FEATURE-CONTROLFLOWANALYZER: Control Flow Analyzer + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Control Flow Analyzer + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize control flow analyzer. + +--- +**Story 2**: As a user, I can analyze data with Control Flow Analyzer + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract scenarios from a method's control flow. + +--- + +#### Feature Outcomes + +- Analyzes AST to extract control flow patterns and generate scenarios. +### FEATURE-SPECKITCONVERTER: Spec Kit Converter + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Spec Kit Converter + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize Spec-Kit converter. + +--- +**Story 2**: As a user, I can process data using Spec Kit Converter + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert Spec-Kit features to SpecFact protocol. +- [ ] Convert Spec-Kit markdown artifacts to SpecFact plan bundle. +- [ ] Convert SpecFact plan bundle to Spec-Kit markdown artifacts. + +--- +**Story 3**: As a user, I can generate outputs from Spec Kit Converter + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate Semgrep async rules for the repository. +- [ ] Generate GitHub Action workflow for SpecFact validation. + +--- + +#### Feature Outcomes + +- Converter from Spec-Kit format to SpecFact format. +### FEATURE-CODEANALYZER: Code Analyzer + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 21 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Code Analyzer + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize code analyzer. + +--- +**Story 2**: As a user, I can analyze data with Code Analyzer + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Analyze repository and generate plan bundle. + +--- +**Story 3**: As a user, I can view Code Analyzer data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get status of all analysis plugins. + +--- + +#### Feature Outcomes + +- Analyzes Python code to auto-derive plan bundles. +- Provides CRUD operations: READ plugin_status +### FEATURE-CONTRACTEXTRACTOR: Contract Extractor + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Contract Extractor + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize contract extractor. + +--- +**Story 2**: As a user, I can analyze data with Contract Extractor + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract contracts from a function signature. + +--- +**Story 3**: As a user, I can generate outputs from Contract Extractor + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate JSON Schema from contracts. +- [ ] Generate icontract decorator code from contracts. + +--- + +#### Feature Outcomes + +- Extracts API contracts from function signatures, type hints, and validation logic. +### FEATURE-PLANMIGRATOR: Plan Migrator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Plan Migrator features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Load plan bundle and migrate if needed. + +--- +**Story 2**: As a developer, I can validate Plan Migrator data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Check if plan bundle needs migration. + +--- + +#### Feature Outcomes + +- Plan bundle migrator for upgrading schema versions. +### FEATURE-SMARTCOVERAGEMANAGER: Smart Coverage Manager + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 11 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Smart Coverage Manager + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) + +--- +**Story 2**: As a developer, I can validate Smart Coverage Manager data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Check if a full test run is needed. + +--- +**Story 3**: As a user, I can view Smart Coverage Manager data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get current coverage status. +- [ ] Get recent test log files. + +--- +**Story 4**: As a user, I can use Smart Coverage Manager features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Show recent test log files and their status. +- [ ] Show the latest test log content. +- [ ] Run tests with smart change detection and specified level. +- [ ] Run tests by specified level: unit, folder, integration, e2e, or full. +- [ ] Force a test run regardless of file changes. + +--- + +#### Feature Outcomes + +- Provides Smart Coverage Manager functionality +### FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR: Constitution Evidence Extractor + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 18 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Constitution Evidence Extractor + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize constitution evidence extractor. + +--- +**Story 2**: As a user, I can analyze data with Constitution Evidence Extractor + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract Article VII (Simplicity) evidence from project structure. +- [ ] Extract Article VIII (Anti-Abstraction) evidence from framework usage. +- [ ] Extract Article IX (Integration-First) evidence from contract patterns. +- [ ] Extract evidence for all constitution articles. + +--- +**Story 3**: As a developer, I can validate Constitution Evidence Extractor data + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate constitution check section markdown from evidence. + +--- + +#### Feature Outcomes + +- Extracts evidence-based constitution checklist from code patterns. +### FEATURE-SYNCEVENTHANDLER: Sync Event Handler + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 8 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Sync Event Handler + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize event handler. + +--- +**Story 2**: As a user, I can use Sync Event Handler features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file modification events. + +--- +**Story 3**: As a user, I can create new Sync Event Handler records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file creation events. + +--- +**Story 4**: As a user, I can delete Sync Event Handler records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file deletion events. + +--- + +#### Feature Outcomes + +- Event handler for file system changes during sync operations. +### FEATURE-GRAPHANALYZER: Graph Analyzer + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 17 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Graph Analyzer + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize graph analyzer. + +--- +**Story 2**: As a user, I can analyze data with Graph Analyzer + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract call graph using pyan. + +--- +**Story 3**: As a user, I can generate outputs from Graph Analyzer + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Build comprehensive dependency graph using NetworkX. + +--- +**Story 4**: As a user, I can view Graph Analyzer data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get summary of dependency graph. + +--- + +#### Feature Outcomes + +- Graph-based dependency and call graph analysis. +- Provides CRUD operations: READ graph_summary +### FEATURE-PROJECTBUNDLE: Project Bundle + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 19 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Project Bundle features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Load project bundle from directory structure. +- [ ] Save project bundle to directory structure. + +--- +**Story 2**: As a user, I can view Project Bundle data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get feature by key (lazy load if needed). + +--- +**Story 3**: As a user, I can create new Project Bundle records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add feature (save to file, update registry). + +--- +**Story 4**: As a user, I can update Project Bundle records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Update feature (save to file, update registry). + +--- +**Story 5**: As a user, I can process data using Project Bundle + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Compute summary from all aspects (for compatibility). + +--- + +#### Feature Outcomes + +- Modular project bundle (replaces monolithic PlanBundle). +- Defines data models: $MODEL +- Provides CRUD operations: READ feature, CREATE feature, UPDATE feature +### FEATURE-ANALYZEAGENT: Analyze Agent + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 18 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can generate outputs from Analyze Agent + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate enhanced prompt for brownfield analysis. + +--- +**Story 2**: As a user, I can use Analyze Agent features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Execute brownfield analysis with enhanced prompts. +- [ ] Inject context information specific to analysis operations. + +--- +**Story 3**: As a user, I can analyze data with Analyze Agent + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Analyze codebase using AI-first approach with semantic understanding. + +--- + +#### Feature Outcomes + +- AI-first brownfield analysis agent with semantic understanding. +### FEATURE-ENHANCEDSYNCEVENTHANDLER: Enhanced Sync Event Handler + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 8 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Enhanced Sync Event Handler + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize enhanced event handler. + +--- +**Story 2**: As a user, I can use Enhanced Sync Event Handler features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file modification events. + +--- +**Story 3**: As a user, I can create new Enhanced Sync Event Handler records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file creation events. + +--- +**Story 4**: As a user, I can delete Enhanced Sync Event Handler records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file deletion events. + +--- + +#### Feature Outcomes + +- Enhanced event handler with hash-based change detection and dependency tracking. +### FEATURE-PLANBUNDLE: Plan Bundle + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can process data using Plan Bundle + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Compute summary metadata for fast access without full parsing. + +--- +**Story 2**: As a user, I can update Plan Bundle records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Update the summary metadata in this plan bundle. + +--- + +#### Feature Outcomes + +- Complete plan bundle model. +- Defines data models: $MODEL +- Provides CRUD operations: UPDATE summary +### FEATURE-PLANAGENT: Plan Agent + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can generate outputs from Plan Agent + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate enhanced prompt for plan management. + +--- +**Story 2**: As a user, I can use Plan Agent features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Execute plan command with enhanced prompts. +- [ ] Inject context information specific to plan operations. + +--- + +#### Feature Outcomes + +- Plan management agent with business logic understanding. +### FEATURE-OPENAPIEXTRACTOR: Open A P I Extractor + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 17 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Open A P I Extractor + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize extractor with repository path. + +--- +**Story 2**: As a user, I can analyze data with Open A P I Extractor + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert verbose acceptance criteria to OpenAPI contract. +- [ ] Extract OpenAPI contract from existing code using AST. + +--- +**Story 3**: As a user, I can create new Open A P I Extractor records + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add test examples to OpenAPI specification. + +--- +**Story 4**: As a user, I can use Open A P I Extractor features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Save OpenAPI contract to file. + +--- + +#### Feature Outcomes + +- Extractor for generating OpenAPI contracts from features. +- Provides CRUD operations: CREATE test_examples +### FEATURE-SPECKITSCANNER: Spec Kit Scanner + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Spec Kit Scanner + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize Spec-Kit scanner. + +--- +**Story 2**: As a user, I can use Spec Kit Scanner features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Check if repository is a Spec-Kit project. +- [ ] Check if constitution.md exists and is not empty. +- [ ] Scan Spec-Kit directory structure. +- [ ] Discover all features from specs directory. + +--- +**Story 3**: As a user, I can analyze data with Spec Kit Scanner + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Parse a Spec-Kit spec.md file to extract features, stories, requirements, and success criteria. +- [ ] Parse a Spec-Kit plan.md file to extract technical context and architecture. +- [ ] Parse a Spec-Kit tasks.md file to extract tasks with IDs, story mappings, and dependencies. +- [ ] Parse Spec-Kit memory files (constitution.md, etc.). + +--- + +#### Feature Outcomes + +- Scanner for Spec-Kit repositories. +### FEATURE-CODETOSPECSYNC: Code To Spec Sync + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Code To Spec Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize code-to-spec sync. + +--- +**Story 2**: As a user, I can use Code To Spec Sync features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Sync code changes to specifications using AST analysis. + +--- + +#### Feature Outcomes + +- Sync code changes to specifications using AST analysis. +### FEATURE-BRIDGETEMPLATELOADER: Bridge Template Loader + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 14 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Bridge Template Loader + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize bridge template loader. + +--- +**Story 2**: As a user, I can use Bridge Template Loader features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Resolve template path for a schema key using bridge configuration. +- [ ] Load template for a schema key using bridge configuration. +- [ ] Render template for a schema key with provided context. +- [ ] Check if template exists for a schema key. + +--- +**Story 3**: As a user, I can view Bridge Template Loader data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] List all available templates from bridge configuration. + +--- +**Story 4**: As a user, I can create new Bridge Template Loader records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Create template context with common variables. + +--- + +#### Feature Outcomes + +- Template loader that uses bridge configuration for dynamic template resolution. +- Provides CRUD operations: CREATE template_context +### FEATURE-PLANGENERATOR: Plan Generator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Plan Generator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize plan generator. + +--- +**Story 2**: As a user, I can generate outputs from Plan Generator + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate plan bundle YAML file from model. +- [ ] Generate file from custom template. + +--- +**Story 3**: As a user, I can use Plan Generator features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Render plan bundle to YAML string without writing to file. + +--- + +#### Feature Outcomes + +- Generator for plan bundle YAML files. +### FEATURE-SPECTOCODESYNC: Spec To Code Sync + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Spec To Code Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize spec-to-code sync. + +--- +**Story 2**: As a user, I can use Spec To Code Sync features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Prepare context for LLM code generation. + +--- +**Story 3**: As a user, I can generate outputs from Spec To Code Sync + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate LLM prompt for code generation. + +--- + +#### Feature Outcomes + +- Sync specification changes to code by preparing LLM prompts. +### FEATURE-BRIDGEPROBE: Bridge Probe + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 16 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Bridge Probe + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize bridge probe. + +--- +**Story 2**: As a user, I can analyze data with Bridge Probe + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Detect tool capabilities and configuration. + +--- +**Story 3**: As a user, I can generate outputs from Bridge Probe + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Auto-generate bridge configuration based on detected capabilities. + +--- +**Story 4**: As a developer, I can validate Bridge Probe data + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate bridge configuration and check if paths exist. + +--- +**Story 5**: As a user, I can use Bridge Probe features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Save bridge configuration to `.specfact/config/bridge.yaml`. + +--- + +#### Feature Outcomes + +- Probe for detecting tool configurations and generating bridge configs. +### FEATURE-SPECFACTSTRUCTURE: Spec Fact Structure + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 41 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Spec Fact Structure features + +**Definition of Ready**: + +- [x] Story Points: 13 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 13 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Return canonical plan suffix for format (defaults to YAML). +- [ ] Ensure a plan filename includes the correct suffix. +- [ ] Remove known plan suffix from filename. +- [ ] Compute default plan filename for requested format. +- [ ] Ensure the .specfact directory structure exists. +- [ ] Sanitize plan name for filesystem persistence. +- [ ] Create complete .specfact directory structure. +- [ ] Get path to project bundle directory. +- [ ] Ensure project bundle directory structure exists. + +--- +**Story 2**: As a user, I can view Spec Fact Structure data + +**Definition of Ready**: + +- [x] Story Points: 13 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 13 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get a timestamped report path. +- [ ] Get path for brownfield analysis report. +- [ ] Get path for auto-derived brownfield plan. +- [ ] Get path for comparison report. +- [ ] Get path to active plan bundle (from config or fallback to main.bundle.yaml). +- [ ] Get active bundle name from config. +- [ ] List all available project bundles with metadata. +- [ ] Get path to enforcement configuration file. +- [ ] Get path to SDD manifest file. +- [ ] Get timestamped path for brownfield analysis report (YAML bundle). +- [ ] Get enrichment report path based on plan bundle path. +- [ ] Get original plan bundle path from enrichment report path. +- [ ] Get enriched plan bundle path based on original plan bundle path. +- [ ] Get the latest brownfield report from the plans directory. +- [ ] Get bundle-specific reports directory. +- [ ] Get bundle-specific brownfield report path. +- [ ] Get bundle-specific comparison report path. +- [ ] Get bundle-specific enrichment report path. +- [ ] Get bundle-specific enforcement report path. +- [ ] Get bundle-specific SDD manifest path. +- [ ] Get bundle-specific tasks file path. +- [ ] Get bundle-specific logs directory. + +--- +**Story 3**: As a user, I can update Spec Fact Structure records + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Set the active project bundle in the plans config. +- [ ] Update summary metadata for an existing plan bundle. + +--- +**Story 4**: As a user, I can create new Spec Fact Structure records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Create .gitignore for .specfact directory. +- [ ] Create README for .specfact directory. + +--- +**Story 5**: As a user, I can analyze data with Spec Fact Structure + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Detect if bundle is monolithic or modular. + +--- + +#### Feature Outcomes + +- Manages the canonical .specfact/ directory structure. +### FEATURE-SPECKITSYNC: Spec Kit Sync + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 14 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Spec Kit Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize Spec-Kit sync. + +--- +**Story 2**: As a user, I can use Spec Kit Sync features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Sync changes between Spec-Kit and SpecFact artifacts bidirectionally. +- [ ] Resolve conflicts with merge strategy. +- [ ] Apply resolved conflicts to merged changes. + +--- +**Story 3**: As a user, I can update Spec Kit Sync records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Detect changes in Spec-Kit artifacts. +- [ ] Detect changes in SpecFact artifacts. +- [ ] Merge changes from both sources. + +--- +**Story 4**: As a user, I can analyze data with Spec Kit Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Detect conflicts between Spec-Kit and SpecFact changes. + +--- + +#### Feature Outcomes + +- Bidirectional sync between Spec-Kit and SpecFact. +### FEATURE-OPENAPITESTCONVERTER: Open A P I Test Converter + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Open A P I Test Converter + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize converter with repository path. + +--- +**Story 2**: As a user, I can analyze data with Open A P I Test Converter + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract OpenAPI examples from test files using Semgrep. + +--- + +#### Feature Outcomes + +- Converts test patterns to OpenAPI examples using Semgrep. +### FEATURE-CONTRACTFIRSTTESTMANAGER: Contract First Test Manager + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Contract First Test Manager + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) + +--- +**Story 2**: As a user, I can use Contract First Test Manager features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Run contract-first tests with the 3-layer quality model. + +--- +**Story 3**: As a user, I can view Contract First Test Manager data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get contract-first test status. + +--- + +#### Feature Outcomes + +- Contract-first test manager extending the smart coverage system. +- Provides CRUD operations: READ contract_status + +## Ownership & Locks + +*No sections currently locked* + +## Validation Checklist + +- [ ] All user stories have clear acceptance criteria +- [ ] Success metrics are measurable and defined +- [ ] Target users are identified +- [ ] Business constraints are documented +- [ ] Feature priorities are established + +## Notes + +*Use this section for additional context, questions, or clarifications needed.* diff --git a/_site_local/prompts/PROMPT_VALIDATION_CHECKLIST.md b/_site_local/prompts/PROMPT_VALIDATION_CHECKLIST.md new file mode 100644 index 0000000..b178741 --- /dev/null +++ b/_site_local/prompts/PROMPT_VALIDATION_CHECKLIST.md @@ -0,0 +1,495 @@ +# Prompt Validation Checklist + +This checklist helps ensure prompt templates are correct, aligned with CLI commands, and provide good UX. + +## Automated Validation + +Run the automated validator: + +```bash +# Validate all prompts +hatch run validate-prompts + +# Or directly +python tools/validate_prompts.py +``` + +The validator checks: + +- ✅ Required sections present +- ✅ CLI commands match actual CLI +- ✅ CLI enforcement rules present +- ✅ Wait state rules present +- ✅ Dual-stack workflow (if applicable) +- ✅ Consistency across prompts + +## Manual Review Checklist + +### 1. Structure & Formatting + +- [ ] **Frontmatter present**: YAML frontmatter with `description` field +- [ ] **Required sections present**: + - [ ] `# SpecFact [Command Name]` - Main title (H1) + - [ ] `## User Input` - Contains `$ARGUMENTS` placeholder in code block + - [ ] `## Purpose` - Clear description of what the command does + - [ ] `## Parameters` - Organized by groups (Target/Input, Output/Results, Behavior/Options, Advanced/Configuration) + - [ ] `## Workflow` - Step-by-step execution instructions + - [ ] `## CLI Enforcement` - Rules for using CLI commands + - [ ] `## Expected Output` - Success and error examples + - [ ] `## Common Patterns` - Usage examples + - [ ] `## Context` - Contains `{ARGS}` placeholder +- [ ] **Markdown formatting**: Proper headers, code blocks, lists +- [ ] **$ARGUMENTS placeholder**: Present in "User Input" section within code block +- [ ] **{ARGS} placeholder**: Present in "Context" section + +### 2. CLI Alignment + +- [ ] **CLI command matches**: The command in the prompt matches the actual CLI command +- [ ] **CLI enforcement rules present**: + - [ ] "ALWAYS execute CLI first" + - [ ] "ALWAYS use non-interactive mode for CI/CD" (explicitly requires `--no-interactive` flag to avoid timeouts in Copilot environments) + - [ ] "ALWAYS use tools for read/write" (explicitly requires using file reading tools like `read_file` for display purposes only, CLI commands for all write operations) + - [ ] "NEVER modify .specfact folder directly" (explicitly forbids creating, modifying, or deleting files in `.specfact/` folder directly) + - [ ] "NEVER create YAML/JSON directly" + - [ ] "NEVER bypass CLI validation" + - [ ] "Use CLI output as grounding" + - [ ] "NEVER manipulate internal code" (explicitly forbids direct Python code manipulation) + - [ ] "No internal knowledge required" (explicitly states that internal implementation details should not be needed) + - [ ] "NEVER read artifacts directly for updates" (explicitly forbids reading files directly for update operations, only for display purposes) +- [ ] **Available CLI commands documented**: Prompt lists available CLI commands for plan updates (e.g., `update-idea`, `update-feature`, `add-feature`, `add-story`) +- [ ] **FORBIDDEN examples present**: Prompt shows examples of what NOT to do (direct code manipulation) +- [ ] **CORRECT examples present**: Prompt shows examples of what TO do (using CLI commands) +- [ ] **Command examples**: Examples show actual CLI usage with correct flags +- [ ] **Flag documentation**: All flags are documented with defaults and descriptions +- [ ] **Filter options documented** (for `plan select`): `--current`, `--stages`, `--last`, `--no-interactive` flags are documented with use cases and examples +- [ ] **Positional vs option arguments**: Correctly distinguishes between positional arguments and `--option` flags (e.g., `specfact plan select 20` not `specfact plan select --plan 20`) +- [ ] **Boolean flags documented correctly**: Boolean flags use `--flag/--no-flag` syntax, not `--flag true/false` + - ❌ **WRONG**: `--draft true` or `--draft false` (Typer boolean flags don't accept values) + - ✅ **CORRECT**: `--draft` (sets True) or `--no-draft` (sets False) or omit (leaves unchanged) +- [ ] **Entry point flag documented** (for `import from-code`): `--entry-point` flag is documented with use cases (multi-project repos, partial analysis, incremental modernization) + +### 3. Wait States & User Input + +- [ ] **User Input section**: Contains `$ARGUMENTS` placeholder in code block with `text` language +- [ ] **User Input instruction**: Includes "You **MUST** consider the user input before proceeding (if not empty)" +- [ ] **Wait state rules** (if applicable for interactive workflows): + - [ ] "Never assume" + - [ ] "Never continue" + - [ ] "Be explicit" + - [ ] "Provide options" +- [ ] **Explicit wait markers**: `[WAIT FOR USER RESPONSE - DO NOT CONTINUE]` present where needed (for interactive workflows) +- [ ] **Missing argument handling**: Clear instructions for what to do when arguments are missing +- [ ] **User prompts**: Examples show how to ask for user input (if applicable) +- [ ] **No assumptions**: Prompt doesn't allow LLM to assume values and continue + +### 4. Flow Logic + +- [ ] **Dual-stack workflow** (if applicable): + - [ ] Phase 1: CLI Grounding documented + - [ ] Phase 2: LLM Enrichment documented + - [ ] **CRITICAL**: Stories are required for features in enrichment reports + - [ ] Story format example provided in prompt + - [ ] Explanation: Stories are required for promotion validation + - [ ] Phase 3: CLI Artifact Creation documented + - [ ] Enrichment report location specified (`.specfact/projects//reports/enrichment/`, bundle-specific, Phase 8.5) +- [ ] **Auto-enrichment workflow** (for `plan review`): + - [ ] `--auto-enrich` flag documented with when to use it + - [ ] LLM reasoning guidance for detecting when enrichment is needed + - [ ] Post-enrichment analysis steps documented + - [ ] **MANDATORY automatic refinement**: LLM must automatically refine generic criteria with code-specific details after auto-enrichment + - [ ] Two-phase enrichment strategy (automatic + LLM-enhanced refinement) + - [ ] Continuous improvement loop documented + - [ ] Examples of enrichment output and refinement process + - [ ] **Generic criteria detection**: Instructions to identify and replace generic patterns ("interact with the system", "works correctly") + - [ ] **Code-specific criteria generation**: Instructions to research codebase and create testable criteria with method names, parameters, return values +- [ ] **Feature deduplication** (for `sync`, `plan review`, `import from-code`): + - [ ] **Automated deduplication documented**: CLI automatically deduplicates features using normalized key matching + - [ ] **Deduplication scope explained**: + - [ ] Exact normalized key matches (e.g., `FEATURE-001` vs `001_FEATURE_NAME`) + - [ ] Prefix matches for Spec-Kit features (e.g., `FEATURE-IDEINTEGRATION` vs `041_IDE_INTEGRATION_SYSTEM`) + - [ ] Only matches when at least one key has numbered prefix (Spec-Kit origin) to avoid false positives + - [ ] **LLM semantic deduplication guidance**: Instructions for LLM to identify semantic/logical duplicates that automated deduplication might miss + - [ ] Review feature titles and descriptions for semantic similarity + - [ ] Identify features that represent the same functionality with different names + - [ ] Suggest consolidation when multiple features cover the same code/functionality + - [ ] Use `specfact plan update-feature` or `specfact plan add-feature` to consolidate + - [ ] **Deduplication output**: CLI shows "✓ Removed N duplicate features" - LLM should acknowledge this + - [ ] **Post-deduplication review**: LLM should review remaining features for semantic duplicates +- [ ] **Execution steps**: Clear, sequential steps +- [ ] **Error handling**: Instructions for handling errors +- [ ] **Validation**: CLI validation steps documented +- [ ] **Coverage validation** (for `plan promote`): Documentation of coverage status checks (critical vs important categories) +- [ ] **Copilot-friendly formatting** (if applicable): Instructions for formatting output as Markdown tables for better readability +- [ ] **Interactive workflows** (if applicable): Support for "details" requests and other interactive options (e.g., "20 details" for plan selection) + +### 5. Consistency + +- [ ] **Consistent terminology**: Uses same terms as other prompts +- [ ] **Consistent formatting**: Same markdown style as other prompts +- [ ] **Consistent structure**: Same section order as other prompts +- [ ] **Consistent examples**: Examples follow same pattern + +### 6. UX & Clarity + +- [ ] **Clear goal**: Goal section clearly explains what the command does +- [ ] **Clear constraints**: Operating constraints are explicit +- [ ] **Helpful examples**: Examples are realistic and helpful +- [ ] **Error messages**: Shows what happens if rules aren't followed +- [ ] **User-friendly**: Language is clear and not overly technical + +## Testing with Copilot + +### Step 1: Run Automated Validation + +```bash +hatch run validate-prompts +``` + +All prompts should pass with 0 errors. + +### Step 2: Manual Testing + +For each prompt, test the following scenarios: + +#### Scenario 1: Missing Required Arguments + +1. Invoke the slash command without required arguments +2. Verify the LLM: + - ✅ Asks for missing arguments + - ✅ Shows `[WAIT FOR USER RESPONSE - DO NOT CONTINUE]` + - ✅ Does NOT assume values and continue + - ✅ Provides helpful examples or defaults + +#### Scenario 2: All Arguments Provided + +1. Invoke the slash command with all required arguments +2. Verify the LLM: + - ✅ Executes the CLI command immediately + - ✅ Uses the provided arguments correctly + - ✅ Uses boolean flags correctly (`--draft` not `--draft true`) + - ✅ Uses `--entry-point` when user specifies partial analysis + - ✅ Does NOT create artifacts directly + - ✅ Parses CLI output correctly + +#### Scenario 3: Dual-Stack Workflow (for import-from-code) + +1. Invoke `/specfact.01-import legacy-api --repo .` without `--enrichment` +2. Verify the LLM: + - ✅ Executes Phase 1: CLI Grounding + - ✅ Reads CLI-generated artifacts + - ✅ Generates enrichment report (Phase 2) + - ✅ **CRITICAL**: Each missing feature includes at least one story + - ✅ Stories follow the format shown in prompt example + - ✅ Saves enrichment to `.specfact/projects//reports/enrichment/` with correct naming (bundle-specific, Phase 8.5) + - ✅ Executes Phase 3: CLI Artifact Creation with `--enrichment` flag + - ✅ Final artifacts are CLI-generated + - ✅ Enriched plan can be promoted (features have stories) + +#### Scenario 4: Plan Review Workflow (for plan-review) + +1. Invoke `/specfact.03-review legacy-api` with a plan bundle +2. Verify the LLM: + - ✅ Executes `specfact plan review` CLI command + - ✅ Parses CLI output for ambiguity findings + - ✅ Waits for user input when questions are asked + - ✅ Does NOT create clarifications directly in YAML + - ✅ Uses CLI to save updated plan bundle after each answer + - ✅ Follows interactive Q&A workflow correctly + +#### Scenario 4a: Plan Review with Auto-Enrichment (for plan-review) + +1. Invoke `/specfact.03-review legacy-api` with a plan bundle that has vague acceptance criteria or incomplete requirements +2. Verify the LLM: + - ✅ **Detects need for enrichment**: Recognizes vague patterns ("is implemented", "System MUST Helper class", generic tasks) + - ✅ **Suggests or uses `--auto-enrich`**: Either suggests using `--auto-enrich` flag or automatically uses it based on plan quality indicators + - ✅ **Executes enrichment**: Runs `specfact plan review --auto-enrich` + - ✅ **Parses enrichment results**: Captures enrichment summary (features updated, stories updated, acceptance criteria enhanced, etc.) + - ✅ **Analyzes enrichment quality**: Uses LLM reasoning to review what was enhanced + - ✅ **Identifies generic patterns**: Finds placeholder text like "interact with the system" that needs refinement + - ✅ **Proposes specific refinements**: Suggests domain-specific improvements using CLI commands + - ✅ **Executes refinements**: Uses `specfact plan update-feature --bundle ` to refine generic improvements + - ✅ **Re-runs review**: Executes `specfact plan review` again to verify improvements +3. Test with explicit enrichment request (e.g., "enrich the plan"): + - ✅ Uses `--auto-enrich` flag immediately + - ✅ Reviews enrichment results + - ✅ Suggests further improvements if needed + +#### Scenario 5: Plan Selection Workflow (for plan-select) + +1. Invoke `/specfact.02-plan select` (or use CLI: `specfact plan select`) +2. Verify the LLM: + - ✅ Executes `specfact plan select` CLI command + - ✅ Formats plan list as copilot-friendly Markdown table (not Rich table) + - ✅ Provides selection options (number, "number details", "q" to quit) + - ✅ Waits for user response with `[WAIT FOR USER RESPONSE - DO NOT CONTINUE]` +3. Request plan details (e.g., "20 details"): + - ✅ Loads plan bundle YAML file + - ✅ Extracts and displays detailed information (idea, themes, top features, business context) + - ✅ Asks if user wants to select the plan + - ✅ Waits for user confirmation +4. Select a plan (e.g., "20" or "y" after details): + - ✅ Uses **positional argument** syntax: `specfact plan select 20` (NOT `--plan 20`) + - ✅ Confirms selection with CLI output + - ✅ Does NOT create config.yaml directly +5. Test filter options: + - ✅ Uses `--current` flag to show only active plan: `specfact plan select --current` + - ✅ Uses `--stages` flag to filter by stages: `specfact plan select --stages draft,review` + - ✅ Uses `--last N` flag to show recent plans: `specfact plan select --last 5` +6. Test non-interactive mode (CI/CD): + - ✅ Uses `--no-interactive` flag with `--current`: `specfact plan select --no-interactive --current` + - ✅ Uses `--no-interactive` flag with `--last 1`: `specfact plan select --no-interactive --last 1` + - ✅ Handles error when multiple plans match filters in non-interactive mode + - ✅ Does NOT prompt for input when `--no-interactive` is used + +#### Scenario 6: Plan Promotion with Coverage Validation (for plan-promote) + +1. Invoke `/specfact-plan-promote` with a plan that has missing critical categories +2. Verify the LLM: + - ✅ Executes `specfact plan promote --stage review --validate` CLI command + - ✅ Parses CLI output showing coverage validation errors + - ✅ Shows which critical categories are Missing + - ✅ Suggests running `specfact plan review` to resolve ambiguities + - ✅ Does NOT attempt to bypass validation by creating artifacts directly + - ✅ Waits for user decision (use `--force` or run `plan review` first) +3. Invoke promotion with `--force` flag: + - ✅ Uses `--force` flag correctly: `specfact plan promote --stage review --force` + - ✅ Explains that `--force` bypasses validation (not recommended) + - ✅ Does NOT create plan bundle directly + +#### Scenario 7: Error Handling + +1. Invoke command with invalid arguments or paths +2. Verify the LLM: + - ✅ Shows CLI error messages + - ✅ Doesn't try to fix errors by creating artifacts + - ✅ Asks user for correct input + - ✅ Waits for user response + +### Step 3: Review Output + +After testing, review: + +- [ ] **CLI commands executed**: All commands use `specfact` CLI +- [ ] **Artifacts CLI-generated**: No YAML/JSON created directly by LLM +- [ ] **Wait states respected**: LLM waits for user input when needed +- [ ] **Enrichment workflow** (if applicable): Three-phase workflow followed correctly +- [ ] **Review workflow** (if applicable): Interactive Q&A workflow followed correctly, clarifications saved via CLI +- [ ] **Auto-enrichment workflow** (if applicable): + - [ ] LLM detects when enrichment is needed (vague criteria, incomplete requirements, generic tasks) + - [ ] Uses `--auto-enrich` flag appropriately + - [ ] Analyzes enrichment results with reasoning + - [ ] Proposes and executes specific refinements using CLI commands + - [ ] Iterates until plan quality meets standards +- [ ] **Selection workflow** (if applicable): Copilot-friendly table formatting, details option, correct CLI syntax (positional arguments), filter options (`--current`, `--stages`, `--last`), non-interactive mode (`--no-interactive`) +- [ ] **Promotion workflow** (if applicable): Coverage validation respected, suggestions to run `plan review` when categories are Missing +- [ ] **Error handling**: Errors handled gracefully without assumptions + +## Common Issues to Watch For + +### ❌ LLM Creates Artifacts Directly + +**Symptom**: LLM generates YAML/JSON instead of using CLI + +**Fix**: Strengthen CLI enforcement section, add more examples of what NOT to do + +### ❌ LLM Uses Interactive Mode in CI/CD + +**Symptom**: LLM uses interactive prompts that cause timeouts in Copilot environments + +**Fix**: + +- Add explicit requirement to use `--no-interactive` flag +- Document that interactive mode should only be used when user explicitly requests it +- Add examples showing non-interactive CLI command usage + +### ❌ LLM Modifies .specfact Folder Directly + +**Symptom**: LLM creates, modifies, or deletes files in `.specfact/` folder directly instead of using CLI commands + +**Fix**: + +- Add explicit prohibition against direct `.specfact/` folder modifications +- Emphasize that all operations must go through CLI commands +- Add examples showing correct CLI usage vs incorrect direct file manipulation + +### ❌ LLM Uses Direct File Manipulation Instead of Tools + +**Symptom**: LLM uses direct file write operations instead of CLI commands or file reading tools + +**Fix**: + +- Add explicit requirement to use file reading tools (e.g., `read_file`) for display purposes only +- Emphasize that all write operations must use CLI commands +- Add examples showing correct tool usage vs incorrect direct manipulation + +### ❌ LLM Assumes Values + +**Symptom**: LLM continues without waiting for user input + +**Fix**: Add more explicit wait state markers, show more examples of correct wait behavior + +### ❌ Wrong CLI Command + +**Symptom**: LLM uses incorrect command or flags + +**Fix**: Update command examples, verify CLI help text matches prompt + +### ❌ Wrong Argument Format (Positional vs Option) + +**Symptom**: LLM uses `--option` flag when command expects positional argument (e.g., `specfact plan select --plan 20` instead of `specfact plan select 20`) + +**Fix**: + +- Verify actual CLI command signature (use `specfact --help`) +- Update prompt to explicitly state positional vs option arguments +- Add examples showing correct syntax +- Add warning about common mistakes (e.g., "NOT `specfact plan select --plan 20` (this will fail)") + +### ❌ Wrong Boolean Flag Usage + +**Symptom**: LLM uses `--flag true` or `--flag false` when flag is boolean (e.g., `--draft true` instead of `--draft`) + +**Fix**: + +- Verify actual CLI command signature (use `specfact --help`) +- Update prompt to explicitly state boolean flag syntax: `--flag` sets True, `--no-flag` sets False, omit to leave unchanged +- Add examples showing correct syntax: `--draft` (not `--draft true`) +- Add warning about common mistakes: "NOT `--draft true` (this will fail - Typer boolean flags don't accept values)" +- Document when to use `--no-flag` vs omitting the flag entirely + +### ❌ Missing Enrichment Workflow + +**Symptom**: LLM doesn't follow three-phase workflow for import-from-code + +**Fix**: Strengthen dual-stack workflow section, add more explicit phase markers + +### ❌ Missing Coverage Validation + +**Symptom**: LLM promotes plans without checking coverage status, or doesn't suggest running `plan review` when categories are Missing + +**Fix**: + +- Update prompt to document coverage validation clearly +- Add examples showing validation errors +- Emphasize that `--force` should only be used when explicitly requested +- Document critical vs important categories + +### ❌ Missing Auto-Enrichment + +**Symptom**: LLM doesn't detect or use `--auto-enrich` flag when plan has vague acceptance criteria or incomplete requirements + +**Fix**: + +- Update prompt to document `--auto-enrich` flag and when to use it +- Add LLM reasoning guidance for detecting enrichment needs +- Document decision flow for when to suggest or use auto-enrichment +- Add examples of enrichment output and refinement process +- Emphasize two-phase approach: automatic enrichment + LLM-enhanced refinement + +## Validation Commands + +```bash +# Run automated validation +hatch run validate-prompts + +# Run unit tests for validation +hatch test tests/unit/prompts/test_prompt_validation.py -v + +# Check specific prompt +python tools/validate_prompts.py --prompt specfact.01-import +``` + +## Continuous Improvement + +After each prompt update: + +1. Run automated validation +2. Test with Copilot in real scenarios +3. Document any issues found +4. Update checklist based on learnings +5. Share findings with team + +## Available Prompts + +The following prompts are available for SpecFact CLI commands: + +### Core Workflow Commands (Numbered) + +- `specfact.01-import.md` - Import codebase into plan bundle (replaces `specfact-import-from-code.md`) +- `specfact.02-plan.md` - Plan management: init, add-feature, add-story, update-idea, update-feature, update-story (replaces multiple plan commands) +- `specfact.03-review.md` - Review plan and promote (replaces `specfact-plan-review.md`, `specfact-plan-promote.md`) +- `specfact.04-sdd.md` - Create SDD manifest (new, based on `plan harden`) +- `specfact.05-enforce.md` - SDD enforcement (replaces `specfact-enforce.md`) +- `specfact.06-sync.md` - Sync operations (replaces `specfact-sync.md`) +- `specfact.07-contracts.md` - Contract enhancement workflow: analyze → generate prompts → apply contracts sequentially (new, based on `analyze contracts`, `generate contracts-prompt`, `generate contracts-apply`) + +### Advanced Commands (No Numbering) + +- `specfact.compare.md` - Compare plans (replaces `specfact-plan-compare.md`) +- `specfact.validate.md` - Validation suite (replaces `specfact-repro.md`) + +### Constitution Management + +- Constitution commands are integrated into `specfact.06-sync.md` and `specfact.01-import.md` workflows +- Constitution bootstrap/enrich/validate commands are suggested automatically when constitution is missing or minimal + +--- + +**Last Updated**: 2025-01-XX +**Version**: 1.10 + +## Changelog + +### Version 1.11 (2025-12-06) + +- Added `specfact.07-contracts.md` to available prompts list +- New contract enhancement workflow prompt for sequential contract application +- Workflow: analyze contracts → generate prompts → apply contracts with careful review + +### Version 1.10 (2025-01-XX) + +- Added non-interactive mode enforcement requirements +- Added tool-based read/write instructions requirements +- Added prohibition against direct `.specfact/` folder modifications +- Added new common issues: LLM Uses Interactive Mode in CI/CD, LLM Modifies .specfact Folder Directly, LLM Uses Direct File Manipulation Instead of Tools +- Updated CLI enforcement rules checklist to include new requirements + +### Version 1.9 (2025-11-20) + +- Added filter options validation for `plan select` command (`--current`, `--stages`, `--last`) +- Added non-interactive mode validation for `plan select` command (`--no-interactive`) +- Updated Scenario 5 to include filter options and non-interactive mode testing +- Added filter options documentation requirements to CLI alignment checklist +- Updated selection workflow checklist to include filter options and non-interactive mode + +### Version 1.8 (2025-11-20) + +- Added feature deduplication validation checks +- Added automated deduplication documentation requirements (exact matches, prefix matches for Spec-Kit features) +- Added LLM semantic deduplication guidance (identifying semantic/logical duplicates) +- Added deduplication workflow to testing scenarios +- Added common issue: Missing Semantic Deduplication +- Updated Scenario 2 to verify deduplication acknowledgment and semantic review + +### Version 1.7 (2025-11-19) + +- Added boolean flag validation checks +- Added `--entry-point` flag documentation requirements +- Added common issue: Wrong Boolean Flag Usage +- Updated Scenario 2 to verify boolean flag usage +- Added checks for `--entry-point` usage in partial analysis scenarios + +### Version 1.6 (2025-11-18) + +- Added constitution management commands integration +- Updated sync prompt to include constitution bootstrap/enrich/validate commands +- Added constitution bootstrap suggestion workflow for brownfield projects +- Updated prerequisites section to document constitution command options + +### Version 1.5 (2025-11-18) + +- Added auto-enrichment workflow validation for `plan review` command +- Added Scenario 4a: Plan Review with Auto-Enrichment +- Added checks for enrichment detection, execution, and refinement +- Added common issue: Missing Auto-Enrichment +- Updated flow logic section to include auto-enrichment workflow documentation requirements diff --git a/_site_local/prompts/README.md b/_site_local/prompts/README.md new file mode 100644 index 0000000..9e09cab --- /dev/null +++ b/_site_local/prompts/README.md @@ -0,0 +1,260 @@ +# Prompt Templates and Slash Commands Reference + +This directory contains documentation and tools for validating slash command prompts, as well as a reference for all available slash commands. + +--- + +## Slash Commands Reference + +SpecFact CLI provides slash commands that work with AI-assisted IDEs (Cursor, VS Code + Copilot, Claude Code, etc.). These commands enable a seamless workflow: **SpecFact finds gaps → AI IDE fixes them → SpecFact validates**. + +### Quick Start + +1. **Initialize IDE integration**: + + ```bash + specfact init --ide cursor + ``` + +2. **Use slash commands in your IDE**: + + ```bash + /specfact.01-import legacy-api --repo . + /specfact.03-review legacy-api + /specfact.05-enforce legacy-api + ``` + +**Related**: [AI IDE Workflow Guide](../guides/ai-ide-workflow.md) - Complete workflow guide + +--- + +### Core Workflow Commands + +#### `/specfact.01-import` + +**Purpose**: Import from codebase (brownfield modernization) + +**Equivalent CLI**: `specfact import from-code` + +**Example**: + +```bash +/specfact.01-import legacy-api --repo . +``` + +**Workflow**: [Brownfield Modernization Chain](../guides/command-chains.md#1-brownfield-modernization-chain) + +--- + +#### `/specfact.02-plan` + +**Purpose**: Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) + +**Equivalent CLI**: `specfact plan init/add-feature/add-story/update-idea/update-feature/update-story` + +**Example**: + +```bash +/specfact.02-plan init legacy-api +/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth" +``` + +**Workflow**: [Greenfield Planning Chain](../guides/command-chains.md#2-greenfield-planning-chain) + +--- + +#### `/specfact.03-review` + +**Purpose**: Review plan and promote + +**Equivalent CLI**: `specfact plan review` + +**Example**: + +```bash +/specfact.03-review legacy-api +``` + +**Workflow**: [Brownfield Modernization Chain](../guides/command-chains.md#1-brownfield-modernization-chain), [Greenfield Planning Chain](../guides/command-chains.md#2-greenfield-planning-chain) + +--- + +#### `/specfact.04-sdd` + +**Purpose**: Create SDD manifest + +**Equivalent CLI**: `specfact enforce sdd` + +**Example**: + +```bash +/specfact.04-sdd legacy-api +``` + +**Workflow**: [Brownfield Modernization Chain](../guides/command-chains.md#1-brownfield-modernization-chain) + +--- + +#### `/specfact.05-enforce` + +**Purpose**: SDD enforcement + +**Equivalent CLI**: `specfact enforce sdd` + +**Example**: + +```bash +/specfact.05-enforce legacy-api +``` + +**Workflow**: [Brownfield Modernization Chain](../guides/command-chains.md#1-brownfield-modernization-chain), [Plan Promotion & Release Chain](../guides/command-chains.md#5-plan-promotion--release-chain) + +--- + +#### `/specfact.06-sync` + +**Purpose**: Sync operations + +**Equivalent CLI**: `specfact sync bridge` + +**Example**: + +```bash +/specfact.06-sync --adapter speckit --repo . --bidirectional +``` + +**Workflow**: [External Tool Integration Chain](../guides/command-chains.md#3-external-tool-integration-chain) + +--- + +#### `/specfact.07-contracts` + +**Purpose**: Contract management (analyze, generate prompts, apply contracts sequentially) + +**Equivalent CLI**: `specfact generate contracts-prompt` + +**Example**: + +```bash +/specfact.07-contracts legacy-api --apply all-contracts +``` + +**Workflow**: [AI-Assisted Code Enhancement Chain](../guides/command-chains.md#7-ai-assisted-code-enhancement-chain-emerging) + +--- + +### Advanced Commands + +#### `/specfact.compare` + +**Purpose**: Compare plans + +**Equivalent CLI**: `specfact plan compare` + +**Example**: + +```bash +/specfact.compare --bundle legacy-api +``` + +**Workflow**: [Code-to-Plan Comparison Chain](../guides/command-chains.md#6-code-to-plan-comparison-chain) + +--- + +#### `/specfact.validate` + +**Purpose**: Validation suite + +**Equivalent CLI**: `specfact repro` + +**Example**: + +```bash +/specfact.validate --repo . +``` + +**Workflow**: [Brownfield Modernization Chain](../guides/command-chains.md#1-brownfield-modernization-chain), [Gap Discovery & Fixing Chain](../guides/command-chains.md#9-gap-discovery--fixing-chain-emerging) + +--- + +## Prompt Validation System + +This directory contains documentation and tools for validating slash command prompts to ensure they are correct, aligned with CLI commands, and provide good UX. + +## Quick Start + +### Run Automated Validation + +```bash +# Validate all prompts +hatch run validate-prompts + +# Or directly +python tools/validate_prompts.py +``` + +### Run Tests + +```bash +# Run prompt validation tests +hatch test tests/unit/prompts/test_prompt_validation.py -v +``` + +## What Gets Validated + +The automated validator checks: + +1. **Structure**: Required sections present (CLI Enforcement, Wait States, Goal, Operating Constraints) +2. **CLI Alignment**: CLI commands match actual CLI, enforcement rules present +3. **Wait States**: Wait state rules and markers present +4. **Dual-Stack Workflow**: Three-phase workflow for applicable commands +5. **Consistency**: Consistent formatting and structure across prompts + +## Validation Results + +All 8 prompts currently pass validation: + +- ✅ `specfact.01-import` (20 checks) - Import from codebase +- ✅ `specfact.02-plan` (15 checks) - Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) +- ✅ `specfact.03-review` (15 checks) - Review plan and promote +- ✅ `specfact.04-sdd` (15 checks) - Create SDD manifest +- ✅ `specfact.05-enforce` (15 checks) - SDD enforcement +- ✅ `specfact.06-sync` (15 checks) - Sync operations +- ✅ `specfact.compare` (15 checks) - Compare plans +- ✅ `specfact.validate` (15 checks) - Validation suite + +## Manual Review + +See [PROMPT_VALIDATION_CHECKLIST.md](./PROMPT_VALIDATION_CHECKLIST.md) for: + +- Detailed manual review checklist +- Testing scenarios with Copilot +- Common issues and fixes +- Continuous improvement process + +## Files + +- **`tools/validate_prompts.py`**: Automated validation tool +- **`tests/unit/prompts/test_prompt_validation.py`**: Unit tests for validator +- **`PROMPT_VALIDATION_CHECKLIST.md`**: Manual review checklist +- **`resources/prompts/`**: Prompt template files + +## Integration + +The validation tool is integrated into the development workflow: + +- **Pre-commit**: Run `hatch run validate-prompts` before committing prompt changes +- **CI/CD**: Add validation step to CI pipeline +- **Development**: Run validation after updating any prompt + +## Next Steps + +1. **Test with Copilot**: Use the manual checklist to test each prompt in real scenarios +2. **Document Issues**: Document any issues found during testing +3. **Improve Prompts**: Update prompts based on testing feedback +4. **Expand Validation**: Add more checks as patterns emerge + +--- + +**Last Updated**: 2025-12-02 (v0.11.4 - Active Plan Fallback, SDD Hash Stability) +**Version**: 1.1 diff --git a/_site_local/quick-examples/index.html b/_site_local/quick-examples/index.html new file mode 100644 index 0000000..4b69a95 --- /dev/null +++ b/_site_local/quick-examples/index.html @@ -0,0 +1,547 @@ + + + + + + + +Quick Examples | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Quick Examples

+ +

Quick code snippets for common SpecFact CLI tasks.

+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow (VS Code, Cursor, GitHub Actions, pre-commit hooks). No platform to learn, no vendor lock-in.

+ +

Installation

+ +
# Zero-install (no setup required) - CLI-only mode
+uvx specfact-cli@latest --help
+
+# Install with pip - Interactive AI Assistant mode
+pip install specfact-cli
+
+# Install in virtual environment
+python -m venv .venv
+source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
+pip install specfact-cli
+
+
+ +

Your First Command

+ +
# Starting a new project?
+specfact plan init my-project --interactive
+
+# Have existing code?
+specfact import from-code my-project --repo .
+
+# Using GitHub Spec-Kit?
+specfact import from-bridge --adapter speckit --repo ./my-project --dry-run
+
+
+ +

Import from Spec-Kit (via Bridge)

+ +
# Preview migration
+specfact import from-bridge --adapter speckit --repo ./spec-kit-project --dry-run
+
+# Execute migration
+specfact import from-bridge --adapter speckit --repo ./spec-kit-project --write
+
+
+ +

Import from Code

+ +
# Basic import (bundle name as positional argument)
+specfact import from-code my-project --repo .
+
+# With confidence threshold
+specfact import from-code my-project --repo . --confidence 0.7
+
+# Shadow mode (observe only)
+specfact import from-code my-project --repo . --shadow-only
+
+# CoPilot mode (enhanced prompts)
+specfact --mode copilot import from-code my-project --repo . --confidence 0.7
+
+
+ +

Plan Management

+ +
# Initialize plan (bundle name as positional argument)
+specfact plan init my-project --interactive
+
+# Add feature (bundle name via --bundle option)
+specfact plan add-feature \
+  --bundle my-project \
+  --key FEATURE-001 \
+  --title "User Authentication" \
+  --outcomes "Users can login securely"
+
+# Add story (bundle name via --bundle option)
+specfact plan add-story \
+  --bundle my-project \
+  --feature FEATURE-001 \
+  --title "As a user, I can login with email and password" \
+  --acceptance "Login form validates input"
+
+# Create hard SDD manifest (required for promotion)
+specfact plan harden my-project
+
+# Review plan (checks SDD automatically, bundle name as positional argument)
+specfact plan review my-project --max-questions 5
+
+# Promote plan (requires SDD for review+ stages)
+specfact plan promote my-project --stage review
+
+
+ +

Plan Comparison

+ +
# Quick comparison (auto-detects plans)
+specfact plan compare --repo .
+
+# Explicit comparison (bundle directory paths)
+specfact plan compare \
+  --manual .specfact/projects/manual-plan \
+  --auto .specfact/projects/auto-derived
+
+# Code vs plan comparison
+specfact plan compare --code-vs-plan --repo .
+
+
+ +

Sync Operations

+ +
# One-time Spec-Kit sync (via bridge adapter)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Watch mode (continuous sync)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+# Repository sync
+specfact sync repository --repo . --target .specfact
+
+# Repository watch mode
+specfact sync repository --repo . --watch --interval 5
+
+
+ +

SDD (Spec-Driven Development) Workflow

+ +
# Create hard SDD manifest from plan
+specfact plan harden
+
+# Validate SDD manifest against plan
+specfact enforce sdd
+
+# Validate SDD with custom output format
+specfact enforce sdd --output-format json --out validation-report.json
+
+# Review plan (automatically checks SDD)
+specfact plan review --max-questions 5
+
+# Promote plan (requires SDD for review+ stages)
+specfact plan promote --stage review
+
+# Force promotion despite SDD validation failures
+specfact plan promote --stage review --force
+
+ +

Enforcement

+ +
# Shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# Balanced mode (block HIGH, warn MEDIUM)
+specfact enforce stage --preset balanced
+
+# Strict mode (block everything)
+specfact enforce stage --preset strict
+
+# Enforce SDD validation
+specfact enforce sdd
+
+
+ +

Validation

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Quick validation
+specfact repro
+
+# Verbose validation
+specfact repro --verbose
+
+# With budget
+specfact repro --verbose --budget 120
+
+# Apply auto-fixes
+specfact repro --fix --budget 120
+
+
+ +

IDE Integration

+ +
# Initialize Cursor integration
+specfact init --ide cursor
+
+# Initialize VS Code integration
+specfact init --ide vscode
+
+# Force reinitialize
+specfact init --ide cursor --force
+
+
+ +

Operational Modes

+ +
# Auto-detect mode (default)
+specfact import from-code my-project --repo .
+
+# Force CI/CD mode
+specfact --mode cicd import from-code my-project --repo .
+
+# Force CoPilot mode
+specfact --mode copilot import from-code my-project --repo .
+
+# Set via environment variable
+export SPECFACT_MODE=copilot
+specfact import from-code my-project --repo .
+
+ +

Common Workflows

+ +

Daily Development

+ +
# Morning: Check status
+specfact repro --verbose
+specfact plan compare --repo .
+
+# During development: Watch mode
+specfact sync repository --repo . --watch --interval 5
+
+# Before committing: Validate
+specfact repro
+specfact plan compare --repo .
+
+
+ +

Brownfield Modernization (Hard-SDD Workflow)

+ +
# Step 1: Extract specs from legacy code
+specfact import from-code my-project --repo .
+
+# Step 2: Create hard SDD manifest
+specfact plan harden my-project
+
+# Step 3: Validate SDD before starting work
+specfact enforce sdd my-project
+
+# Step 4: Review plan (checks SDD automatically)
+specfact plan review my-project --max-questions 5
+
+# Step 5: Promote plan (requires SDD for review+ stages)
+specfact plan promote my-project --stage review
+
+# Step 6: Add contracts to critical paths
+# ... (add @icontract decorators to code)
+
+# Step 7: Re-validate SDD after adding contracts
+specfact enforce sdd my-project
+
+# Step 8: Continue modernization with SDD safety net
+
+ +

Migration from Spec-Kit

+ +
# Step 1: Preview
+specfact import from-bridge --adapter speckit --repo . --dry-run
+
+# Step 2: Execute
+specfact import from-bridge --adapter speckit --repo . --write
+
+# Step 3: Set up sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+# Step 4: Enable enforcement
+specfact enforce stage --preset minimal
+
+
+ +

Brownfield Analysis

+ +
# Step 1: Analyze code
+specfact import from-code my-project --repo . --confidence 0.7
+
+# Step 2: Review plan using CLI commands
+specfact plan review my-project
+
+# Step 3: Compare with manual plan
+specfact plan compare --repo .
+
+# Step 4: Set up watch mode
+specfact sync repository --repo . --watch --interval 5
+
+ +

Advanced Examples

+ +

Bundle Name

+ +
# Bundle name is a positional argument (not --name option)
+specfact import from-code my-project --repo .
+
+
+ +

Custom Report

+ +
specfact import from-code \
+  --repo . \
+  --report analysis-report.md
+
+specfact plan compare \
+  --repo . \
+  --out comparison-report.md
+
+
+ +

Feature Key Format

+ +
# Classname format (default for auto-derived)
+specfact import from-code my-project --repo . --key-format classname
+
+# Sequential format (for manual plans)
+specfact import from-code my-project --repo . --key-format sequential
+
+
+ +

Confidence Threshold

+ +
# Lower threshold (more features, lower confidence)
+specfact import from-code my-project --repo . --confidence 0.3
+
+# Higher threshold (fewer features, higher confidence)
+specfact import from-code my-project --repo . --confidence 0.8
+
+ +

Integration Examples

+ + + + + + + +
+ +

Happy building! 🚀

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/redirects/index.json b/_site_local/redirects/index.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/_site_local/redirects/index.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/_site_local/reference/commands/index.html b/_site_local/reference/commands/index.html new file mode 100644 index 0000000..916c51e --- /dev/null +++ b/_site_local/reference/commands/index.html @@ -0,0 +1,5157 @@ + + + + + + + +Command Reference | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Command Reference

+ +

Complete reference for all SpecFact CLI commands.

+ +

Commands by Workflow

+ +

Quick Navigation: Find commands organized by workflow and command chain.

+ +

👉 Command Chains Reference ⭐ NEW - Complete workflows with decision trees and visual diagrams

+ +

Workflow Matrix

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WorkflowPrimary CommandsChain Reference
Brownfield Modernizationimport from-code, plan review, plan update-feature, enforce sdd, reproBrownfield Chain
Greenfield Planningplan init, plan add-feature, plan add-story, plan review, plan harden, generate contracts, enforce sddGreenfield Chain
External Tool Integrationimport from-bridge, plan review, sync bridge, enforce sddIntegration Chain
API Contract Developmentspec validate, spec backward-compat, spec generate-tests, spec mock, contract verifyAPI Chain
Plan Promotion & Releaseplan review, enforce sdd, plan promote, project version bumpPromotion Chain
Code-to-Plan Comparisonimport from-code, plan compare, drift detect, sync repositoryComparison Chain
AI-Assisted Enhancementgenerate contracts-prompt, contracts-apply, contract coverage, reproAI Enhancement Chain
Test Generationgenerate test-prompt, spec generate-tests, pytestTest Generation Chain
Gap Discovery & Fixingrepro --verbose, generate fix-prompt, enforce sddGap Discovery Chain
+ +

Not sure which workflow to use? → Command Chains Decision Tree

+ +
+ +

Quick Reference

+ +

Most Common Commands

+ +
# PRIMARY: Import from existing code (brownfield modernization)
+specfact import from-code --bundle legacy-api --repo .
+
+# SECONDARY: Import from external tools (Spec-Kit, Linear, Jira, etc.)
+specfact import from-bridge --repo . --adapter speckit --write
+
+# Initialize plan (alternative: greenfield workflow)
+specfact plan init --bundle legacy-api --interactive
+
+# Compare plans
+specfact plan compare --bundle legacy-api
+
+# Sync with external tools (bidirectional) - Secondary use case
+specfact sync bridge --adapter speckit --bundle legacy-api --bidirectional --watch
+
+# Set up CrossHair for contract exploration (one-time setup)
+specfact repro setup
+
+# Validate everything
+specfact repro --verbose
+
+ +

Global Flags

+ +
    +
  • --input-format {yaml,json} - Override default structured input detection for CLI commands (defaults to YAML)
    • +
  • --output-format {yaml,json} - Control how plan bundles and reports are written (JSON is ideal for CI/copilot automations)
    • +
  • --interactive/--no-interactive - Force prompt behavior (overrides auto-detection from CI/CD vs Copilot environments)
    • +
+ +

Commands by Workflow

+ +

Import & Analysis:

+ +
    +
  • import from-code ⭐ PRIMARY - Analyze existing codebase (brownfield modernization)
    • +
  • import from-bridge - Import from external tools via bridge architecture (Spec-Kit, Linear, Jira, etc.)
    • +
+ +

Plan Management:

+ +
    +
  • plan init --bundle <bundle-name> - Initialize new project bundle
    • +
  • plan add-feature --bundle <bundle-name> - Add feature to bundle
    • +
  • plan add-story --bundle <bundle-name> - Add story to feature
    • +
  • plan update-feature --bundle <bundle-name> - Update existing feature metadata
    • +
  • plan review --bundle <bundle-name> - Review plan bundle to resolve ambiguities
    • +
  • plan select - Select active plan from available bundles
    • +
  • plan upgrade - Upgrade plan bundles to latest schema version
    • +
  • plan compare - Compare plans (detect drift)
    • +
+ +

Project Bundle Management:

+ +
    +
  • project init-personas - Initialize persona definitions for team collaboration + +
    • +
  • project export --bundle <bundle-name> --persona <persona> - Export persona-specific Markdown artifacts + +
    • +
  • project import --bundle <bundle-name> --persona <persona> --source <file> - Import persona edits from Markdown + +
    • +
  • project lock --bundle <bundle-name> --section <section> --persona <persona> - Lock section for editing + +
    • +
  • project unlock --bundle <bundle-name> --section <section> - Unlock section after editing + +
    • +
  • project locks --bundle <bundle-name> - List all locked sections + +
    • +
  • project version check --bundle <bundle-name> - Recommend version bump (major/minor/patch/none) + +
    • +
  • project version bump --bundle <bundle-name> --type <major|minor|patch> - Apply SemVer bump and record history + +
    • +
  • project version set --bundle <bundle-name> --version <semver> - Set explicit project version and record history + +
    • +
  • CI/CD Integration: The GitHub Action template includes a configurable version check step with three modes: +
      +
    • info: Informational only, logs recommendations without failing CI
      • +
    • warn (default): Logs warnings but continues CI execution
      • +
    • block: Fails CI if version bump recommendation is not followed +Configure via version_check_mode input in workflow_dispatch or set SPECFACT_VERSION_CHECK_MODE environment variable.
      • +
    +
    • +
+ +

Enforcement:

+ + + +

AI IDE Bridge (v0.17+):

+ +
    +
  • generate fix-prompt ⭐ NEW - Generate AI IDE prompt to fix gaps
    • +
  • generate test-prompt ⭐ NEW - Generate AI IDE prompt to create tests
    • +
  • generate tasks - ⚠️ REMOVED in v0.22.0 - Use Spec-Kit, OpenSpec, or other SDD tools instead
    • +
  • generate contracts - Generate contract stubs from SDD
    • +
  • generate contracts-prompt - Generate AI IDE prompt for adding contracts
    • +
+ +

Synchronization:

+ + + +

API Specification Management:

+ + + +

Constitution Management (Spec-Kit Compatibility):

+ +
    +
  • sdd constitution bootstrap - Generate bootstrap constitution from repository analysis (for Spec-Kit format)
    • +
  • sdd constitution enrich - Auto-enrich existing constitution with repository context (for Spec-Kit format)
    • +
  • sdd constitution validate - Validate constitution completeness (for Spec-Kit format)
    • +
+ +

Note: The sdd constitution commands are for Spec-Kit compatibility only. SpecFact itself uses modular project bundles (.specfact/projects/<bundle-name>/) and protocols (.specfact/protocols/*.protocol.yaml) for internal operations. Constitutions are only needed when syncing with Spec-Kit artifacts or working in Spec-Kit format.

+ +

⚠️ Breaking Change: The specfact bridge constitution command has been moved to specfact sdd constitution as part of the bridge adapter refactoring. Please update your scripts and workflows.

+ +

Migration & Utilities:

+ +
    +
  • migrate cleanup-legacy - Remove empty legacy directories
    • +
  • migrate to-contracts - Migrate bundles to contract-centric structure
    • +
  • migrate artifacts - Migrate artifacts between bundle versions
    • +
  • sdd list - List all SDD manifests in repository
    • +
+ +

Setup:

+ +
    +
  • init - Initialize IDE integration
    • +
+ +

⚠️ Deprecated (v0.17.0):

+ +
    +
  • implement tasks - Use generate fix-prompt / generate test-prompt instead
    • +
+ +
+ +

Global Options

+ +
specfact [OPTIONS] COMMAND [ARGS]...
+
+ +

Global Options:

+ +
    +
  • --version, -v - Show version and exit
    • +
  • --help, -h - Show help message and exit
    • +
  • --help-advanced, -ha - Show all options including advanced configuration (progressive disclosure)
    • +
  • --no-banner - Hide ASCII art banner (useful for CI/CD)
    • +
  • --verbose - Enable verbose output
    • +
  • --quiet - Suppress non-error output
    • +
  • --mode {cicd|copilot} - Operational mode (default: auto-detect)
    • +
+ +

Mode Selection:

+ +
    +
  • cicd - CI/CD automation mode (fast, deterministic)
    • +
  • copilot - CoPilot-enabled mode (interactive, enhanced prompts)
    • +
  • Auto-detection: Checks CoPilot API availability and IDE integration
    • +
+ +

Boolean Flags:

+ +

Boolean flags in SpecFact CLI work differently from value flags:

+ +
    +
  • ✅ CORRECT: --flag (sets True) or --no-flag (sets False) or omit (uses default)
    • +
  • ❌ WRONG: --flag true or --flag false (Typer boolean flags don’t accept values)
    • +
+ +

Examples:

+ +
    +
  • --draft sets draft status to True
    • +
  • --no-draft sets draft status to False (when supported)
    • +
  • Omitting the flag leaves the value unchanged (if optional) or uses the default
    • +
+ +

Note: Some boolean flags support --no-flag syntax (e.g., --draft/--no-draft), while others are simple presence flags (e.g., --shadow-only). Check command help with specfact <command> --help for specific flag behavior.

+ +

Banner Display:

+ +

The CLI displays an ASCII art banner by default for brand recognition and visual appeal. The banner shows:

+ +
    +
  • When executing any command (unless --no-banner is specified)
    • +
  • With help output (--help or -h)
    • +
  • With version output (--version or -v)
    • +
+ +

To suppress the banner (useful for CI/CD or automated scripts):

+ +
specfact --no-banner <command>
+
+ +

Examples:

+ +
# Auto-detect mode (default)
+specfact import from-code --bundle legacy-api --repo .
+
+# Force CI/CD mode
+specfact --mode cicd import from-code --bundle legacy-api --repo .
+
+# Force CoPilot mode
+specfact --mode copilot import from-code --bundle legacy-api --repo .
+
+ +

Commands

+ +

import - Import from External Formats

+ +

Convert external project formats to SpecFact format.

+ +

import from-bridge

+ +

Convert external tool projects (Spec-Kit, Linear, Jira, etc.) to SpecFact format using the bridge architecture.

+ +
specfact import from-bridge [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository with external tool artifacts (required)
    • +
  • --dry-run - Preview changes without writing files
    • +
  • --write - Write converted files to repository
    • +
  • --out-branch NAME - Git branch for migration (default: feat/specfact-migration)
    • +
  • --report PATH - Write migration report to file
    • +
  • --force - Overwrite existing files
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --adapter ADAPTER - Adapter type: speckit, generic-markdown (default: auto-detect)
    • +
+ +

Example:

+ +
# Import from Spec-Kit
+specfact import from-bridge \
+  --repo ./my-speckit-project \
+  --adapter speckit \
+  --write \
+  --out-branch feat/specfact-migration \
+  --report migration-report.md
+
+# Auto-detect adapter
+specfact import from-bridge \
+  --repo ./my-project \
+  --write
+
+ +

What it does:

+ +
    +
  • Uses bridge configuration to detect external tool structure
    • +
  • For Spec-Kit: Detects .specify/ directory with markdown artifacts in specs/ folders
    • +
  • Parses tool-specific artifacts (e.g., specs/[###-feature-name]/spec.md, plan.md, tasks.md, .specify/memory/constitution.md for Spec-Kit)
    • +
  • Converts tool features/stories to SpecFact Pydantic models with contracts
    • +
  • Generates .specfact/protocols/workflow.protocol.yaml (if FSM detected)
    • +
  • Creates modular project bundle at .specfact/projects/<bundle-name>/ with features and stories
    • +
  • Adds Semgrep async anti-pattern rules (if async patterns detected)
    • +
+ +
+ +

import from-code

+ +

Import plan bundle from existing codebase (one-way import) using AI-first approach (CoPilot mode) or AST-based fallback (CI/CD mode).

+ +
specfact import from-code [OPTIONS]
+
+ +

Options:

+ +
    +
  • BUNDLE_NAME - Project bundle name (positional argument, required)
    • +
  • --repo PATH - Path to repository to import (required)
    • +
  • --output-format {yaml,json} - Override global output format for this command only (defaults to global flag)
    • +
  • --shadow-only - Observe without blocking
    • +
  • --report PATH - Write import report (default: bundle-specific .specfact/projects/<bundle-name>/reports/brownfield/analysis-<timestamp>.md, Phase 8.5)
    • +
  • --enrich-for-speckit/--no-enrich-for-speckit - Automatically enrich plan for Spec-Kit compliance using PlanEnricher (enhances vague acceptance criteria, incomplete requirements, generic tasks, and adds edge case stories for features with only 1 story). Default: enabled (same enrichment logic as plan review --auto-enrich)
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --confidence FLOAT - Minimum confidence score (0.0-1.0, default: 0.5)
    • +
  • --key-format {classname|sequential} - Feature key format (default: classname)
    • +
  • --entry-point PATH - Subdirectory path for partial analysis (relative to repo root). Analyzes only files within this directory and subdirectories. Useful for: +
      +
    • Multi-project repositories (monorepos): Analyze one project at a time (e.g., --entry-point projects/api-service)
      • +
    • Large codebases: Focus on specific modules or subsystems for faster analysis
      • +
    • Incremental modernization: Modernize one part of the codebase at a time
      • +
    • Example: --entry-point src/core analyzes only src/core/ and its subdirectories
      • +
    +
    • +
  • --enrichment PATH - Path to Markdown enrichment report from LLM (applies missing features, confidence adjustments, business context). The enrichment report must follow a specific format (see Dual-Stack Enrichment Guide for format requirements). When applied: +
      +
    • Missing features are added with their stories and acceptance criteria
      • +
    • Existing features are updated (confidence, outcomes, title if empty)
      • +
    • Stories are merged into existing features (new stories added, existing preserved)
      • +
    • Business context is applied to the plan bundle
      • +
    +
    • +
+ +

Note: The bundle name (positional argument) will be automatically sanitized (lowercased, spaces/special chars removed) for filesystem persistence. The bundle is created at .specfact/projects/<bundle-name>/.

+ +

Mode Behavior:

+ +
    +
  • +

    CoPilot Mode (AI-first - Pragmatic): Uses AI IDE’s native LLM (Cursor, CoPilot, etc.) for semantic understanding. The AI IDE understands the codebase semantically, then calls the SpecFact CLI for structured analysis. No separate LLM API setup needed. Multi-language support, high-quality Spec-Kit artifacts.

    +
    • +
  • +

    CI/CD Mode (AST+Semgrep Hybrid): Uses Python AST + Semgrep pattern detection for fast, deterministic analysis. Framework-aware detection (API endpoints, models, CRUD, code quality). Works offline, no LLM required. Displays plugin status (AST Analysis, Semgrep Pattern Detection, Dependency Graph Analysis).

    +
    • +
+ +

Pragmatic Integration:

+ +
    +
  • ✅ No separate LLM setup - Uses AI IDE’s existing LLM
    • +
  • ✅ No additional API costs - Leverages existing IDE infrastructure
    • +
  • ✅ Simpler architecture - No langchain, API keys, or complex integration
    • +
  • ✅ Better developer experience - Native IDE integration via slash commands
    • +
+ +

Note: The command automatically detects mode based on CoPilot API availability. Use --mode to override.

+ +
    +
  • --mode {cicd|copilot} - Operational mode (default: auto-detect)
    • +
+ +

Examples:

+ +
# Full repository analysis
+specfact import from-code --bundle legacy-api \
+  --repo ./my-project \
+  --confidence 0.7 \
+  --shadow-only \
+  --report reports/analysis.md
+
+# Partial analysis (analyze only specific subdirectory)
+specfact import from-code --bundle core-module \
+  --repo ./my-project \
+  --entry-point src/core \
+  --confidence 0.7
+
+# Multi-project codebase (analyze one project at a time)
+specfact import from-code --bundle api-service \
+  --repo ./monorepo \
+  --entry-point projects/api-service
+
+ +

What it does:

+ +
    +
  • AST Analysis: Extracts classes, methods, imports, docstrings
    • +
  • Semgrep Pattern Detection: Detects API endpoints, database models, CRUD operations, auth patterns, framework usage, code quality issues
    • +
  • Dependency Graph: Builds module dependency graph (when pyan3 and networkx available)
    • +
  • Evidence-Based Confidence Scoring: Systematically combines AST + Semgrep evidence for accurate confidence scores: +
      +
    • Framework patterns (API, models, CRUD) increase confidence
      • +
    • Test patterns increase confidence
      • +
    • Anti-patterns and security issues decrease confidence
      • +
    +
    • +
  • Code Quality Assessment: Identifies anti-patterns and security vulnerabilities
    • +
  • Plugin Status: Displays which analysis tools are enabled and used
    • +
  • Optimized Bundle Size: 81% reduction (18MB → 3.4MB, 5.3x smaller) via test pattern extraction to OpenAPI contracts
    • +
  • Acceptance Criteria: Limited to 1-3 high-level items per story, detailed examples in contract files
    • +
  • Interruptible: Press Ctrl+C during analysis to cancel immediately (all parallel operations support graceful cancellation)
    • +
  • Contract Extraction: Automatically extracts API contracts from function signatures, type hints, and validation logic: +
      +
    • Function parameters → Request schema (JSON Schema format)
      • +
    • Return types → Response schema
      • +
    • Validation logic → Preconditions and postconditions
      • +
    • Error handling → Error contracts
      • +
    • Contracts stored in Story.contracts field for runtime enforcement
      • +
    • Contracts included in Spec-Kit plan.md for Article IX compliance
      • +
    +
    • +
  • Test Pattern Extraction: Extracts test patterns from existing test files: +
      +
    • Parses pytest and unittest test functions
      • +
    • Converts test assertions to Given/When/Then acceptance criteria format
      • +
    • Maps test scenarios to user story scenarios
      • +
    +
    • +
  • Control Flow Analysis: Extracts scenarios from code control flow: +
      +
    • Primary scenarios (happy path)
      • +
    • Alternate scenarios (conditional branches)
      • +
    • Exception scenarios (error handling)
      • +
    • Recovery scenarios (retry logic)
      • +
    +
    • +
  • Requirement Extraction: Extracts complete requirements from code semantics: +
      +
    • Subject + Modal + Action + Object + Outcome format
      • +
    • Non-functional requirements (NFRs) from code patterns
      • +
    • Performance, security, reliability, maintainability patterns
      • +
    +
    • +
  • Generates plan bundle with enhanced confidence scores
    • +
+ +

Partial Repository Coverage:

+ +

The --entry-point parameter enables partial analysis of large codebases:

+ +
    +
  • Multi-project codebases: Analyze individual projects within a monorepo separately
    • +
  • Focused analysis: Analyze specific modules or subdirectories for faster feedback
    • +
  • Incremental modernization: Modernize one module at a time, creating separate plan bundles per module
    • +
  • Performance: Faster analysis when you only need to understand a subset of the codebase
    • +
+ +

Note on Multi-Project Codebases:

+ +

When working with multiple projects in a single repository, external tool integration (via sync bridge) may create artifacts at nested folder levels. For now, it’s recommended to:

+ +
    +
  • Use --entry-point to analyze each project separately
    • +
  • Create separate project bundles for each project (.specfact/projects/<bundle-name>/)
    • +
  • Run specfact init from the repository root to ensure IDE integration works correctly (templates are copied to root-level .github/, .cursor/, etc. directories)
    • +
+ +
+ +

plan - Manage Development Plans

+ +

Create and manage contract-driven development plans.

+ +
+

Plan commands respect both .bundle.yaml and .bundle.json. Use --output-format {yaml,json} (or the global specfact --output-format) to control serialization.

+
+ +

plan init

+ +

Initialize a new plan bundle:

+ +
specfact plan init [OPTIONS]
+
+ +

Options:

+ +
    +
  • --interactive/--no-interactive - Interactive mode with prompts (default: --interactive) +
      +
    • Use --no-interactive for CI/CD automation to avoid interactive prompts
      • +
    +
    • +
  • Bundle name is provided as a positional argument (e.g., plan init my-project)
    • +
  • --scaffold/--no-scaffold - Create complete .specfact/ directory structure (default: --scaffold)
    • +
  • --output-format {yaml,json} - Override global output format for this command only (defaults to global flag)
    • +
+ +

Example:

+ +
# Interactive mode (recommended for manual plan creation)
+specfact plan init --bundle legacy-api --interactive
+
+# Non-interactive mode (CI/CD automation)
+specfact plan init --bundle legacy-api --no-interactive
+
+# Interactive mode with different bundle
+specfact plan init --bundle feature-auth --interactive
+
+ +

plan add-feature

+ +

Add a feature to the plan:

+ +
specfact plan add-feature [OPTIONS]
+
+ +

Options:

+ +
    +
  • --key TEXT - Feature key (FEATURE-XXX) (required)
    • +
  • --title TEXT - Feature title (required)
    • +
  • --outcomes TEXT - Success outcomes (multiple allowed)
    • +
  • --acceptance TEXT - Acceptance criteria (multiple allowed)
    • +
  • --bundle TEXT - Bundle name (default: active bundle or main)
    • +
+ +

Example:

+ +
specfact plan add-feature \
+  --bundle legacy-api \
+  --key FEATURE-001 \
+  --title "Spec-Kit Import" \
+  --outcomes "Zero manual conversion" \
+  --acceptance "Given Spec-Kit repo, When import, Then bundle created"
+
+ +

plan add-story

+ +

Add a story to a feature:

+ +
specfact plan add-story [OPTIONS]
+
+ +

Options:

+ +
    +
  • --feature TEXT - Parent feature key (required)
    • +
  • --key TEXT - Story key (e.g., STORY-001) (required)
    • +
  • --title TEXT - Story title (required)
    • +
  • --acceptance TEXT - Acceptance criteria (comma-separated)
    • +
  • --story-points INT - Story points (complexity: 0-100)
    • +
  • --value-points INT - Value points (business value: 0-100)
    • +
  • --draft - Mark story as draft
    • +
  • --bundle TEXT - Bundle name (default: active bundle or main)
    • +
+ +

Example:

+ +
specfact plan add-story \
+  --bundle legacy-api \
+  --feature FEATURE-001 \
+  --key STORY-001 \
+  --title "Parse Spec-Kit artifacts" \
+  --acceptance "Schema validation passes"
+
+ +

plan update-feature

+ +

Update an existing feature’s metadata in a plan bundle:

+ +
specfact plan update-feature [OPTIONS]
+
+ +

Options:

+ +
    +
  • --key TEXT - Feature key to update (e.g., FEATURE-001) (required unless --batch-updates is provided)
    • +
  • --title TEXT - Feature title
    • +
  • --outcomes TEXT - Expected outcomes (comma-separated)
    • +
  • --acceptance TEXT - Acceptance criteria (comma-separated)
    • +
  • --constraints TEXT - Constraints (comma-separated)
    • +
  • --confidence FLOAT - Confidence score (0.0-1.0)
    • +
  • --draft/--no-draft - Mark as draft (use --draft to set True, --no-draft to set False, omit to leave unchanged) +
      +
    • Note: Boolean flags don’t accept values - use --draft (not --draft true) or --no-draft (not --draft false)
      • +
    +
    • +
  • --batch-updates PATH - Path to JSON/YAML file with multiple feature updates (preferred for bulk updates via Copilot LLM enrichment) +
      +
    • File format: List of objects with key and update fields (title, outcomes, acceptance, constraints, confidence, draft)
      • +
    • +

      Example file (updates.json):

      + + 
      [
+  {
+    "key": "FEATURE-001",
+    "title": "Updated Feature 1",
+    "outcomes": ["Outcome 1", "Outcome 2"],
+    "acceptance": ["Acceptance 1", "Acceptance 2"],
+    "confidence": 0.9
+  },
+  {
+    "key": "FEATURE-002",
+    "title": "Updated Feature 2",
+    "acceptance": ["Acceptance 3"],
+    "confidence": 0.85
+  }
+]
+
      +
      • +
    +
    • +
  • --bundle TEXT - Bundle name (default: active bundle or main)
    • +
+ +

Example:

+ +
# Single feature update
+specfact plan update-feature \
+  --bundle legacy-api \
+  --key FEATURE-001 \
+  --title "Updated Feature Title" \
+  --outcomes "Outcome 1, Outcome 2"
+
+# Update acceptance criteria and confidence
+specfact plan update-feature \
+  --bundle legacy-api \
+  --key FEATURE-001 \
+  --acceptance "Criterion 1, Criterion 2" \
+  --confidence 0.9
+
+# Batch updates from file (preferred for multiple features)
+specfact plan update-feature \
+  --bundle legacy-api \
+  --batch-updates updates.json
+
+# Batch updates with YAML format
+specfact plan update-feature \
+  --bundle main \
+  --batch-updates updates.yaml
+
+ +

Batch Update File Format:

+ +

The --batch-updates file must contain a list of update objects. Each object must have a key field and can include any combination of update fields:

+ +
[
+  {
+    "key": "FEATURE-001",
+    "title": "Updated Feature 1",
+    "outcomes": ["Outcome 1", "Outcome 2"],
+    "acceptance": ["Acceptance 1", "Acceptance 2"],
+    "constraints": ["Constraint 1"],
+    "confidence": 0.9,
+    "draft": false
+  },
+  {
+    "key": "FEATURE-002",
+    "title": "Updated Feature 2",
+    "acceptance": ["Acceptance 3"],
+    "confidence": 0.85
+  }
+]
+
+ +

When to Use Batch Updates:

+ +
    +
  • Multiple features need refinement: After plan review identifies multiple features with missing information
    • +
  • Copilot LLM enrichment: When LLM generates comprehensive updates for multiple features at once
    • +
  • Bulk acceptance criteria updates: When enhancing multiple features with specific file paths, method names, or component references
    • +
  • CI/CD automation: When applying multiple updates programmatically from external tools
    • +
+ +

What it does:

+ +
    +
  • Updates existing feature metadata (title, outcomes, acceptance criteria, constraints, confidence, draft status)
    • +
  • Works in CI/CD, Copilot, and interactive modes
    • +
  • Validates plan bundle structure after update
    • +
  • Preserves existing feature data (only updates specified fields)
    • +
+ +

Use cases:

+ +
    +
  • After enrichment: Update features added via enrichment that need metadata completion
    • +
  • CI/CD automation: Update features programmatically in non-interactive environments
    • +
  • Copilot mode: Update features without needing internal code knowledge
    • +
+ +

plan update-story

+ +

Update an existing story’s metadata in a plan bundle:

+ +
specfact plan update-story [OPTIONS]
+
+ +

Options:

+ +
    +
  • --feature TEXT - Parent feature key (e.g., FEATURE-001) (required unless --batch-updates is provided)
    • +
  • --key TEXT - Story key to update (e.g., STORY-001) (required unless --batch-updates is provided)
    • +
  • --title TEXT - Story title
    • +
  • --acceptance TEXT - Acceptance criteria (comma-separated)
    • +
  • --story-points INT - Story points (complexity: 0-100)
    • +
  • --value-points INT - Value points (business value: 0-100)
    • +
  • --confidence FLOAT - Confidence score (0.0-1.0)
    • +
  • --draft/--no-draft - Mark as draft (use --draft to set True, --no-draft to set False, omit to leave unchanged) +
      +
    • Note: Boolean flags don’t accept values - use --draft (not --draft true) or --no-draft (not --draft false)
      • +
    +
    • +
  • --batch-updates PATH - Path to JSON/YAML file with multiple story updates (preferred for bulk updates via Copilot LLM enrichment) +
      +
    • File format: List of objects with feature, key and update fields (title, acceptance, story_points, value_points, confidence, draft)
      • +
    • +

      Example file (story_updates.json):

      + + 
      [
+  {
+    "feature": "FEATURE-001",
+    "key": "STORY-001",
+    "title": "Updated Story 1",
+    "acceptance": ["Given X, When Y, Then Z"],
+    "story_points": 5,
+    "value_points": 3,
+    "confidence": 0.9
+  },
+  {
+    "feature": "FEATURE-002",
+    "key": "STORY-002",
+    "acceptance": ["Given A, When B, Then C"],
+    "confidence": 0.85
+  }
+]
+
      +
      • +
    +
    • +
  • --bundle TEXT - Bundle name (default: active bundle or main)
    • +
+ +

Example:

+ +
# Single story update
+specfact plan update-story \
+  --feature FEATURE-001 \
+  --key STORY-001 \
+  --title "Updated Story Title" \
+  --acceptance "Given X, When Y, Then Z"
+
+# Update story points and confidence
+specfact plan update-story \
+  --feature FEATURE-001 \
+  --key STORY-001 \
+  --story-points 5 \
+  --confidence 0.9
+
+# Batch updates from file (preferred for multiple stories)
+specfact plan update-story \
+  --bundle main \
+  --batch-updates story_updates.json
+
+# Batch updates with YAML format
+specfact plan update-story \
+  --bundle main \
+  --batch-updates story_updates.yaml
+
+ +

Batch Update File Format:

+ +

The --batch-updates file must contain a list of update objects. Each object must have feature and key fields and can include any combination of update fields:

+ +
[
+  {
+    "feature": "FEATURE-001",
+    "key": "STORY-001",
+    "title": "Updated Story 1",
+    "acceptance": ["Given X, When Y, Then Z"],
+    "story_points": 5,
+    "value_points": 3,
+    "confidence": 0.9,
+    "draft": false
+  },
+  {
+    "feature": "FEATURE-002",
+    "key": "STORY-002",
+    "acceptance": ["Given A, When B, Then C"],
+    "confidence": 0.85
+  }
+]
+
+ +

When to Use Batch Updates:

+ +
    +
  • Multiple stories need refinement: After plan review identifies multiple stories with missing information
    • +
  • Copilot LLM enrichment: When LLM generates comprehensive updates for multiple stories at once
    • +
  • Bulk acceptance criteria updates: When enhancing multiple stories with specific file paths, method names, or component references
    • +
  • CI/CD automation: When applying multiple updates programmatically from external tools
    • +
+ +

What it does:

+ +
    +
  • Updates existing story metadata (title, acceptance criteria, story points, value points, confidence, draft status)
    • +
  • Works in CI/CD, Copilot, and interactive modes
    • +
  • Validates plan bundle structure after update
    • +
  • Preserves existing story data (only updates specified fields)
    • +
+ +

plan review

+ +

Review plan bundle to identify and resolve ambiguities:

+ +
specfact plan review [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle TEXT - Project bundle name (required, e.g., legacy-api)
    • +
  • --list-questions - Output questions in JSON format without asking (for Copilot mode)
    • +
  • --output-questions PATH - Save questions directly to file (JSON format). Use with --list-questions to save instead of stdout. Default: None
    • +
  • --list-findings - Output all findings in structured format (JSON/YAML) or as table (interactive mode). Preferred for bulk updates via Copilot LLM enrichment
    • +
  • --output-findings PATH - Save findings directly to file (JSON/YAML format). Use with --list-findings to save instead of stdout. Default: None
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --auto-enrich - Automatically enrich vague acceptance criteria, incomplete requirements, and generic tasks using LLM-enhanced pattern matching
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --max-questions INT - Maximum questions per session (default: 5, max: 10)
    • +
  • --category TEXT - Focus on specific taxonomy category (optional)
    • +
  • --findings-format {json,yaml,table} - Output format for --list-findings (default: json for non-interactive, table for interactive)
    • +
  • --answers PATH|JSON - JSON file path or JSON string with question_id -> answer mappings (for non-interactive mode)
    • +
+ +

Modes:

+ +
    +
  • Interactive Mode: Asks questions one at a time, integrates answers immediately
    • +
  • Copilot Mode: Three-phase workflow: +
      +
    1. Get findings: specfact plan review --list-findings --findings-format json (preferred for bulk updates)
      2. +
    2. LLM enrichment: Analyze findings and generate batch update files
      3. +
    3. Apply updates: specfact plan update-feature --batch-updates <file> or specfact plan update-story --batch-updates <file>
      4. +
    +
    • +
  • Alternative Copilot Mode: Question-based workflow: +
      +
    1. Get questions: specfact plan review --list-questions
      2. +
    2. Ask user: LLM presents questions and collects answers
      3. +
    3. Feed answers: specfact plan review --answers <file>
      4. +
    +
    • +
  • CI/CD Mode: Use --no-interactive with --answers for automation
    • +
+ +

Example:

+ +
# Interactive review
+specfact plan review --bundle legacy-api
+
+# Get all findings for bulk updates (preferred for Copilot mode)
+specfact plan review --bundle legacy-api --list-findings --findings-format json
+
+# Save findings directly to file (clean JSON, no CLI banner)
+specfact plan review --bundle legacy-api --list-findings --output-findings /tmp/findings.json
+
+# Get findings as table (interactive mode)
+specfact plan review --bundle legacy-api --list-findings --findings-format table
+
+# Get questions for question-based workflow
+specfact plan review --bundle legacy-api --list-questions --max-questions 5
+
+# Save questions directly to file (clean JSON, no CLI banner)
+specfact plan review --bundle legacy-api --list-questions --output-questions /tmp/questions.json
+
+# Feed answers back (question-based workflow)
+specfact plan review --bundle legacy-api --answers answers.json
+
+# CI/CD automation
+specfact plan review --bundle legacy-api --no-interactive --answers answers.json
+
+ +

Findings Output Format:

+ +

The --list-findings option outputs all ambiguities and findings in a structured format:

+ +
{
+  "findings": [
+    {
+      "category": "Feature/Story Completeness",
+      "status": "Missing",
+      "description": "Feature FEATURE-001 has no stories",
+      "impact": 0.9,
+      "uncertainty": 0.8,
+      "priority": 0.72,
+      "question": "What stories should be added to FEATURE-001?",
+      "related_sections": ["features[0]"]
+    }
+  ],
+  "coverage": {
+    "Functional Scope & Behavior": "Missing",
+    "Feature/Story Completeness": "Missing"
+  },
+  "total_findings": 5,
+  "priority_score": 0.65
+}
+
+ +

Bulk Update Workflow (Recommended for Copilot Mode):

+ +
    +
  1. List findings: specfact plan review --list-findings --output-findings /tmp/findings.json (recommended - clean JSON) or specfact plan review --list-findings --findings-format json > findings.json (includes CLI banner)
    2. +
  2. LLM analyzes findings: Generate batch update files based on findings
    3. +
  3. Apply feature updates: specfact plan update-feature --batch-updates feature_updates.json
    4. +
  4. Apply story updates: specfact plan update-story --batch-updates story_updates.json
    5. +
  5. Verify: Run specfact plan review again to confirm improvements
    6. +
+ +

What it does:

+ +
    +
  1. Analyzes plan bundle for ambiguities using structured taxonomy (10 categories)
    2. +
  2. Identifies missing information, unclear requirements, and unknowns
    3. +
  3. Asks targeted questions (max 5 per session) to resolve ambiguities
    4. +
  4. Integrates answers back into plan bundle incrementally
    5. +
  5. Validates plan bundle structure after each update
    6. +
  6. Reports coverage summary and promotion readiness
    7. +
+ +

Taxonomy Categories:

+ +
    +
  • Functional Scope & Behavior
    • +
  • Domain & Data Model
    • +
  • Interaction & UX Flow
    • +
  • Non-Functional Quality Attributes
    • +
  • Integration & External Dependencies
    • +
  • Edge Cases & Failure Handling
    • +
  • Constraints & Tradeoffs
    • +
  • Terminology & Consistency
    • +
  • Completion Signals
    • +
  • Feature/Story Completeness
    • +
+ +

Answers Format:

+ +

The --answers parameter accepts either a JSON file path or JSON string:

+ +
{
+  "Q001": "Answer for question 1",
+  "Q002": "Answer for question 2"
+}
+
+ +

Integration Points:

+ +

Answers are integrated into plan bundle sections based on category:

+ +
    +
  • Functional ambiguity → features[].acceptance[] or idea.narrative
    • +
  • Data model → features[].constraints[]
    • +
  • Non-functional → features[].constraints[] or idea.constraints[]
    • +
  • Edge cases → features[].acceptance[] or stories[].acceptance[]
    • +
+ +

SDD Integration:

+ +

When an SDD manifest (.specfact/projects/<bundle-name>/sdd.yaml, Phase 8.5) is present, plan review automatically:

+ +
    +
  • Validates SDD manifest against the plan bundle (hash match, coverage thresholds)
    • +
  • Displays contract density metrics: +
      +
    • Contracts per story (compared to threshold)
      • +
    • Invariants per feature (compared to threshold)
      • +
    • Architecture facets (compared to threshold)
      • +
    +
    • +
  • Reports coverage threshold warnings if metrics are below thresholds
    • +
  • Suggests running specfact enforce sdd for detailed validation report
    • +
+ +

Example Output with SDD:

+ +
✓ SDD manifest validated successfully
+
+Contract Density Metrics:
+  Contracts/story: 1.50 (threshold: 1.0)
+  Invariants/feature: 2.00 (threshold: 1.0)
+  Architecture facets: 3 (threshold: 3)
+
+Found 0 coverage threshold warning(s)
+
+ +

Output:

+ +
    +
  • Questions asked count
    • +
  • Sections touched (integration points)
    • +
  • Coverage summary (per category status)
    • +
  • Contract density metrics (if SDD present)
    • +
  • Next steps (promotion readiness)
    • +
+ +

plan harden

+ +

Create or update SDD manifest (hard spec) from plan bundle:

+ +
specfact plan harden [OPTIONS]
+
+ +

Options:

+ +
    +
  • Bundle name is provided as a positional argument (e.g., plan harden my-project)
    • +
  • --sdd PATH - Output SDD manifest path (default: bundle-specific .specfact/projects/<bundle-name>/sdd.<format>, Phase 8.5)
    • +
  • --output-format {yaml,json} - SDD manifest format (defaults to global --output-format)
    • +
  • --interactive/--no-interactive - Interactive mode with prompts (default: interactive)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
+ +

What it does:

+ +
    +
  1. Loads plan bundle and computes content hash
    2. +
  2. Extracts SDD sections from plan bundle: +
      +
    • WHY: Intent, constraints, target users, value hypothesis (from idea section)
      • +
    • WHAT: Capabilities, acceptance criteria, out-of-scope (from features section)
      • +
    • HOW: Architecture, invariants, contracts, module boundaries (from features and stories)
      • +
    +
    3. +
  3. Creates SDD manifest with: +
      +
    • Plan bundle linkage (hash and ID)
      • +
    • Coverage thresholds (contracts per story, invariants per feature, architecture facets)
      • +
    • Enforcement budgets (shadow, warn, block time limits)
      • +
    • Promotion status (from plan bundle stage)
      • +
    +
    4. +
  4. Saves plan bundle with updated hash (ensures hash persists for subsequent commands)
    5. +
  5. Saves SDD manifest to .specfact/projects/<bundle-name>/sdd.<format> (bundle-specific, Phase 8.5)
    6. +
+ +

Important Notes:

+ +
    +
  • SDD-Plan Linkage: SDD manifests are linked to specific plan bundles via hash
    • +
  • Multiple Plans: Each bundle has its own SDD manifest in .specfact/projects/<bundle-name>/sdd.yaml (Phase 8.5)
    • +
  • Hash Persistence: Plan bundle is automatically saved with updated hash to ensure consistency
    • +
+ +

Example:

+ +
# Interactive with active plan
+specfact plan harden --bundle legacy-api
+
+# Non-interactive with specific bundle
+specfact plan harden --bundle legacy-api --no-interactive
+
+# Custom SDD path for multiple bundles
+specfact plan harden --bundle feature-auth  # SDD saved to .specfact/projects/feature-auth/sdd.yaml
+
+ +

SDD Manifest Structure:

+ +

The generated SDD manifest includes:

+ +
    +
  • version: Schema version (1.0.0)
    • +
  • plan_bundle_id: First 16 characters of plan hash
    • +
  • plan_bundle_hash: Full plan bundle content hash
    • +
  • why: Intent, constraints, target users, value hypothesis
    • +
  • what: Capabilities, acceptance criteria, out-of-scope
    • +
  • how: Architecture description, invariants, contracts, module boundaries
    • +
  • coverage_thresholds: Minimum contracts/story, invariants/feature, architecture facets
    • +
  • enforcement_budget: Time budgets for shadow/warn/block enforcement levels
    • +
  • promotion_status: Current plan bundle stage
    • +
+ +

plan promote

+ +

Promote a plan bundle through development stages with quality gate validation:

+ +
specfact plan promote <bundle-name> [OPTIONS]
+
+ +

Arguments:

+ +
    +
  • <bundle-name> - Project bundle name (required, positional argument, e.g., legacy-api)
    • +
+ +

Options:

+ +
    +
  • --stage TEXT - Target stage (draft, review, approved, released) (required)
    • +
  • --validate/--no-validate - Run validation before promotion (default: true)
    • +
  • --force - Force promotion even if validation fails (default: false)
    • +
+ +

Stages:

+ +
    +
  • draft: Initial state - can be modified freely
    • +
  • review: Plan is ready for review - should be stable
    • +
  • approved: Plan approved for implementation
    • +
  • released: Plan released and should be immutable
    • +
+ +

Example:

+ +
# Promote to review stage
+specfact plan promote legacy-api --stage review
+
+# Promote to approved with validation
+specfact plan promote legacy-api --stage approved --validate
+
+# Force promotion (bypasses validation)
+specfact plan promote legacy-api --stage released --force
+
+ +

What it does:

+ +
    +
  1. Validates promotion rules: +
      +
    • Draft → Review: All features must have at least one story
      • +
    • Review → Approved: All features and stories must have acceptance criteria
      • +
    • Approved → Released: Implementation verification (future check)
      • +
    +
    2. +
  2. Checks coverage status (when --validate is enabled): +
      +
    • Critical categories (block promotion if Missing): +
        +
      • Functional Scope & Behavior
        • +
      • Feature/Story Completeness
        • +
      • Constraints & Tradeoffs
        • +
      +
      • +
    • Important categories (warn if Missing or Partial): +
        +
      • Domain & Data Model
        • +
      • Integration & External Dependencies
        • +
      • Non-Functional Quality Attributes
        • +
      +
      • +
    +
    3. +
  3. +

    Updates metadata: Sets stage, promoted_at timestamp, and promoted_by user

    +
    4. +
  4. Saves plan bundle with updated metadata
    5. +
+ +

Coverage Validation:

+ +

The promotion command now validates coverage status to ensure plans are complete before promotion:

+ +
    +
  • Blocks promotion if critical categories are Missing (unless --force)
    • +
  • Warns and prompts if important categories are Missing or Partial (unless --force)
    • +
  • Suggests running specfact plan review to resolve missing categories
    • +
+ +

Validation Errors:

+ +

If promotion fails due to validation:

+ +
❌ Cannot promote to review: 1 critical category(ies) are Missing
+Missing critical categories:
+  - Constraints & Tradeoffs
+
+Run 'specfact plan review' to resolve these ambiguities
+
+ +

Use --force to bypass (not recommended):

+ +
specfact plan promote legacy-api --stage review --force
+
+ +

Next Steps:

+ +

After successful promotion, the CLI suggests next actions:

+ +
    +
  • draft → review: Review plan bundle, add stories if missing
    • +
  • review → approved: Plan is ready for implementation
    • +
  • approved → released: Plan is released and should be immutable
    • +
+ +

plan select

+ +

Select active plan from available plan bundles:

+ +
specfact plan select [PLAN] [OPTIONS]
+
+ +

Arguments:

+ +
    +
  • PLAN - Plan name or number to select (optional, for interactive selection)
    • +
+ +

Options:

+ +
    +
  • PLAN - Plan name or number to select (optional, for interactive selection)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation). Disables interactive prompts. Requires exactly one plan to match filters.
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --current - Show only the currently active plan (auto-selects in non-interactive mode)
    • +
  • --stages STAGES - Filter by stages (comma-separated: draft,review,approved,released)
    • +
  • --last N - Show last N plans by modification time (most recent first)
    • +
  • --name NAME - Select plan by exact filename (non-interactive, e.g., main.bundle.yaml)
    • +
  • --id HASH - Select plan by content hash ID (non-interactive, from metadata.summary.content_hash)
    • +
+ +

Example:

+ +
# Interactive selection (displays numbered list)
+specfact plan select
+
+# Select by number
+specfact plan select 1
+
+# Select by name
+specfact plan select main.bundle.yaml
+
+# Show only active plan
+specfact plan select --current
+
+# Filter by stages
+specfact plan select --stages draft,review
+
+# Show last 5 plans
+specfact plan select --last 5
+
+# CI/CD: Get active plan without prompts (auto-selects)
+specfact plan select --no-interactive --current
+
+# CI/CD: Get most recent plan without prompts
+specfact plan select --no-interactive --last 1
+
+# CI/CD: Select by exact filename
+specfact plan select --name main.bundle.yaml
+
+# CI/CD: Select by content hash ID
+specfact plan select --id abc123def456
+
+ +

What it does:

+ +
    +
  • Lists all available plan bundles in .specfact/projects/ with metadata (features, stories, stage, modified date)
    • +
  • Displays numbered list with active plan indicator
    • +
  • Applies filters (current, stages, last N) before display/selection
    • +
  • Updates .specfact/config.yaml to set the active bundle (Phase 8.5: migrated from .specfact/plans/config.yaml)
    • +
  • The active plan becomes the default for all commands with --bundle option: +
      +
    • Plan management: plan compare, plan promote, plan add-feature, plan add-story, plan update-idea, plan update-feature, plan update-story, plan review
      • +
    • Analysis & generation: import from-code, generate contracts, analyze contracts
      • +
    • Synchronization: sync bridge, sync intelligent
      • +
    • Enforcement & migration: enforce sdd, migrate to-contracts, drift detect
      • +
    + +

    Use --bundle <name> to override the active plan for any command.

    +
    • +
+ +

Filter Options:

+ +
    +
  • --current: Filters to show only the currently active plan. In non-interactive mode, automatically selects the active plan without prompts.
    • +
  • --stages: Filters plans by stage (e.g., --stages draft,review shows only draft and review plans)
    • +
  • --last N: Shows the N most recently modified plans (sorted by modification time, most recent first)
    • +
  • --name NAME: Selects plan by exact filename (non-interactive). Useful for CI/CD when you know the exact plan name.
    • +
  • --id HASH: Selects plan by content hash ID from metadata.summary.content_hash (non-interactive). Supports full hash or first 8 characters.
    • +
  • --no-interactive: Disables interactive prompts. If multiple plans match filters, command will error. Use with --current, --last 1, --name, or --id for single plan selection in CI/CD.
    • +
+ +

Performance Notes:

+ +

The plan select command uses optimized metadata reading for fast performance, especially with large plan bundles:

+ +
    +
  • Plan bundles include summary metadata (features count, stories count, content hash) at the top of the file
    • +
  • For large files (>10MB), only the metadata section is read (first 50KB)
    • +
  • This provides 44% faster performance compared to full file parsing
    • +
  • Summary metadata is automatically added when creating or upgrading plan bundles
    • +
+ +

Note: Project bundles are stored in .specfact/projects/<bundle-name>/. All plan commands (compare, promote, add-feature, add-story) use the bundle name specified via --bundle option or positional arguments.

+ +

plan sync

+ +

Enable shared plans for team collaboration (convenience wrapper for sync bridge --adapter speckit --bidirectional):

+ +
specfact plan sync --shared [OPTIONS]
+
+ +

Options:

+ +
    +
  • --shared - Enable shared plans (bidirectional sync for team collaboration)
    • +
  • --watch - Watch mode for continuous sync (monitors file changes in real-time)
    • +
  • --interval INT - Watch interval in seconds (default: 5, minimum: 1)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
  • --bundle BUNDLE_NAME - Project bundle name for SpecFact → tool conversion (default: auto-detect)
    • +
  • --overwrite - Overwrite existing tool artifacts (delete all existing before sync)
    • +
+ +

Shared Plans for Team Collaboration:

+ +

The plan sync --shared command is a convenience wrapper around sync bridge --adapter speckit --bidirectional that emphasizes team collaboration. Shared structured plans enable multiple developers to work on the same plan with automated bidirectional sync. Unlike Spec-Kit’s manual markdown sharing, SpecFact automatically keeps plans synchronized across team members.

+ +

Example:

+ +
# One-time shared plans sync
+specfact plan sync --shared
+
+# Continuous watch mode (recommended for team collaboration)
+specfact plan sync --shared --watch --interval 5
+
+# Sync specific repository and bundle
+specfact plan sync --shared --repo ./project --bundle my-project
+
+# Equivalent direct command:
+specfact sync bridge --adapter speckit --repo . --bundle my-project --bidirectional --watch
+
+ +

What it syncs:

+ +
    +
  • Tool → SpecFact: New spec.md, plan.md, tasks.md → Updated .specfact/projects/<bundle-name>/bundle.yaml
    • +
  • SpecFact → Tool: Changes to .specfact/projects/<bundle-name>/bundle.yaml → Updated tool markdown (preserves structure)
    • +
  • Team collaboration: Multiple developers can work on the same plan with automated synchronization
    • +
+ +

Note: This is a convenience wrapper. The underlying command is sync bridge --adapter speckit --bidirectional. See sync bridge for full details.

+ +

plan upgrade

+ +

Upgrade plan bundles to the latest schema version:

+ +
specfact plan upgrade [OPTIONS]
+
+ +

Options:

+ +
    +
  • --plan PATH - Path to specific plan bundle to upgrade (default: active plan from specfact plan select)
    • +
  • --all - Upgrade all project bundles in .specfact/projects/
    • +
  • --dry-run - Show what would be upgraded without making changes
    • +
+ +

Example:

+ +
# Preview what would be upgraded (active plan)
+specfact plan upgrade --dry-run
+
+# Upgrade active plan (uses bundle selected via `specfact plan select`)
+specfact plan upgrade
+
+# Upgrade specific plan by path
+specfact plan upgrade --plan .specfact/projects/my-project/bundle.manifest.yaml
+
+# Upgrade all plans
+specfact plan upgrade --all
+
+# Preview all upgrades
+specfact plan upgrade --all --dry-run
+
+ +

What it does:

+ +
    +
  • Detects plan bundles with older schema versions or missing summary metadata
    • +
  • Migrates plan bundles from older versions to the current version (1.1)
    • +
  • Adds summary metadata (features count, stories count, content hash) for performance optimization
    • +
  • Preserves all existing plan data while adding new fields
    • +
  • Updates plan bundle version to current schema version
    • +
+ +

Schema Versions:

+ +
    +
  • Version 1.0: Initial schema (no summary metadata)
    • +
  • Version 1.1: Added summary metadata for fast access without full parsing
    • +
+ +

When to use:

+ +
    +
  • After upgrading SpecFact CLI to a version with new schema features
    • +
  • When you notice slow performance with plan select (indicates missing summary metadata)
    • +
  • Before running batch operations on multiple plan bundles
    • +
  • As part of repository maintenance to ensure all plans are up to date
    • +
+ +

Migration Details:

+ +

The upgrade process:

+ +
    +
  1. Detects schema version from plan bundle’s version field
    2. +
  2. Checks for missing summary metadata (backward compatibility)
    3. +
  3. Applies migrations in sequence (supports multi-step migrations)
    4. +
  4. Computes and adds summary metadata with content hash for integrity verification
    5. +
  5. Updates plan bundle file with new schema version
    6. +
+ +

Active Plan Detection:

+ +

When no --plan option is provided, the command automatically uses the active bundle set via specfact plan select. If no active bundle is set, it falls back to the first available bundle in .specfact/projects/ and provides a helpful tip to set it as active.

+ +

Backward Compatibility:

+ +
    +
  • Older bundles (schema 1.0) missing the product field are automatically upgraded with default empty product structure
    • +
  • Missing required fields are provided with sensible defaults during migration
    • +
  • Upgraded plan bundles are backward compatible. Older CLI versions can still read them, but won’t benefit from performance optimizations
    • +
+ +

plan compare

+ +

Compare manual and auto-derived plans to detect code vs plan drift:

+ +
specfact plan compare [OPTIONS]
+
+ +

Options:

+ +
    +
  • --manual PATH - Manual plan bundle directory (intended design - what you planned) (default: active bundle from .specfact/projects/<bundle-name>/ or main)
    • +
  • --auto PATH - Auto-derived plan bundle directory (actual implementation - what’s in your code from import from-code) (default: latest in .specfact/projects/)
    • +
  • --code-vs-plan - Convenience alias for --manual <active-plan> --auto <latest-auto-plan> (detects code vs plan drift)
    • +
  • --output-format TEXT - Output format (markdown, json, yaml) (default: markdown)
    • +
  • --out PATH - Output file (default: bundle-specific .specfact/projects/<bundle-name>/reports/comparison/report-*.md, Phase 8.5, or global .specfact/reports/comparison/ if no bundle context)
    • +
  • --mode {cicd|copilot} - Operational mode (default: auto-detect)
    • +
+ +

Code vs Plan Drift Detection:

+ +

The --code-vs-plan flag is a convenience alias that compares your intended design (manual plan) with actual implementation (code-derived plan from import from-code). Auto-derived plans come from code analysis, so this comparison IS “code vs plan drift” - detecting deviations between what you planned and what’s actually in your code.

+ +

Example:

+ +
# Detect code vs plan drift (convenience alias)
+specfact plan compare --code-vs-plan
+# → Compares intended design (manual plan) vs actual implementation (code-derived plan)
+# → Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift"
+
+# Explicit comparison (bundle directory paths)
+specfact plan compare \
+  --manual .specfact/projects/main \
+  --auto .specfact/projects/my-project-auto \
+  --output-format markdown \
+  --out .specfact/projects/<bundle-name>/reports/comparison/deviation.md
+
+ +

Output includes:

+ +
    +
  • Missing features (in manual but not in auto - planned but not implemented)
    • +
  • Extra features (in auto but not in manual - implemented but not planned)
    • +
  • Mismatched stories
    • +
  • Confidence scores
    • +
  • Deviation severity
    • +
+ +

How it differs from Spec-Kit: Spec-Kit’s /speckit.analyze only checks artifact consistency between markdown files; SpecFact CLI detects actual code vs plan drift by comparing manual plans (intended design) with code-derived plans (actual implementation from code analysis).

+ +
+ +

project - Project Bundle Management

+ +

Manage project bundles with persona-based workflows for agile/scrum teams.

+ +

project export

+ +

Export persona-specific sections from project bundle to Markdown for editing.

+ +
specfact project export [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --persona PERSONA - Persona name: product-owner, developer, or architect (required)
    • +
  • --output PATH - Output file path (default: docs/project-plans/<bundle>/<persona>.md)
    • +
  • --output-dir PATH - Output directory (default: docs/project-plans/<bundle>)
    • +
  • --stdout - Output to stdout instead of file
    • +
  • --template TEMPLATE - Custom template name (default: uses persona-specific template)
    • +
  • --list-personas - List all available personas and exit
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Export Product Owner view
+specfact project export --bundle my-project --persona product-owner
+
+# Export Developer view
+specfact project export --bundle my-project --persona developer
+
+# Export Architect view
+specfact project export --bundle my-project --persona architect
+
+# Export to custom location
+specfact project export --bundle my-project --persona product-owner --output docs/backlog.md
+
+# Output to stdout (for piping/CI)
+specfact project export --bundle my-project --persona product-owner --stdout
+
+ +

What it exports:

+ +

Product Owner Export:

+ +
    +
  • Definition of Ready (DoR) checklist for each story
    • +
  • Prioritization data (priority, rank, business value scores)
    • +
  • Dependencies (story-to-story, feature-to-feature)
    • +
  • Business value descriptions and metrics
    • +
  • Sprint planning data (target dates, sprints, releases)
    • +
+ +

Developer Export:

+ +
    +
  • Acceptance criteria for features and stories
    • +
  • User stories with detailed context
    • +
  • Implementation tasks with file paths
    • +
  • API contracts and test scenarios
    • +
  • Code mappings (source and test functions)
    • +
  • Sprint context (story points, priority, dependencies)
    • +
  • Definition of Done checklist
    • +
+ +

Architect Export:

+ +
    +
  • Technical constraints per feature
    • +
  • Architectural decisions (technology choices, patterns)
    • +
  • Non-functional requirements (performance, scalability, security)
    • +
  • Protocols & state machines (complete definitions)
    • +
  • Contracts (OpenAPI/AsyncAPI details)
    • +
  • Risk assessment and mitigation strategies
    • +
  • Deployment architecture
    • +
+ +

See: Agile/Scrum Workflows Guide for detailed persona workflow documentation.

+ +

project import

+ +

Import persona edits from Markdown back into project bundle.

+ +
specfact project import [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --persona PERSONA - Persona name: product-owner, developer, or architect (required)
    • +
  • --source PATH - Source Markdown file (required)
    • +
  • --dry-run - Validate without applying changes
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Import Product Owner edits
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md
+
+# Import Developer edits
+specfact project import --bundle my-project --persona developer --source docs/developer.md
+
+# Import Architect edits
+specfact project import --bundle my-project --persona architect --source docs/architect.md
+
+# Dry-run to validate without applying
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md --dry-run
+
+ +

What it validates:

+ +
    +
  • Template Structure: Required sections present
    • +
  • DoR Completeness: All Definition of Ready criteria met
    • +
  • Dependency Integrity: No circular dependencies, all references exist
    • +
  • Priority Consistency: Valid priority formats (P0-P3, MoSCoW)
    • +
  • Date Formats: ISO 8601 date validation
    • +
  • Story Point Ranges: Valid Fibonacci-like values
    • +
+ +

See: Agile/Scrum Workflows Guide for detailed validation rules and examples.

+ +

project merge

+ +

Merge project bundles using three-way merge with persona-aware conflict resolution.

+ +
specfact project merge [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --base BRANCH_OR_COMMIT - Base branch/commit (common ancestor, required)
    • +
  • --ours BRANCH_OR_COMMIT - Our branch/commit (current branch, required)
    • +
  • --theirs BRANCH_OR_COMMIT - Their branch/commit (incoming branch, required)
    • +
  • --persona-ours PERSONA - Persona who made our changes (e.g., product-owner, required)
    • +
  • --persona-theirs PERSONA - Persona who made their changes (e.g., architect, required)
    • +
  • --output PATH - Output directory for merged bundle (default: current bundle directory)
    • +
  • --strategy STRATEGY - Merge strategy: auto (persona-based), ours, theirs, base, manual (default: auto)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Merge with automatic persona-based resolution
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours po-branch \
+  --theirs arch-branch \
+  --persona-ours product-owner \
+  --persona-theirs architect
+
+# Merge with manual strategy
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours feature-1 \
+  --theirs feature-2 \
+  --persona-ours developer \
+  --persona-theirs developer \
+  --strategy manual
+
+# Non-interactive merge (for CI/CD)
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours HEAD \
+  --theirs origin/feature \
+  --persona-ours product-owner \
+  --persona-theirs architect \
+  --no-interactive
+
+ +

How it works:

+ +
    +
  1. Loads three versions: Base (common ancestor), ours (current branch), and theirs (incoming branch)
    2. +
  2. Detects conflicts: Compares all three versions to find conflicting changes
    3. +
  3. Resolves automatically: Uses persona ownership rules to auto-resolve conflicts: +
      +
    • If only one persona owns the conflicting section → that persona’s version wins
      • +
    • If both personas own it and they’re the same → ours wins
      • +
    • If both personas own it and they’re different → requires manual resolution
      • +
    +
    4. +
  4. Interactive resolution: For unresolved conflicts, prompts you to choose: +
      +
    • ours - Keep our version
      • +
    • theirs - Keep their version
      • +
    • base - Keep base version
      • +
    • manual - Enter custom value
      • +
    +
    5. +
  5. Saves merged bundle: Writes the resolved bundle to the output directory
    6. +
+ +

Merge Strategies:

+ +
    +
  • auto (default): Persona-based automatic resolution
    • +
  • ours: Always prefer our version for conflicts
    • +
  • theirs: Always prefer their version for conflicts
    • +
  • base: Always prefer base version for conflicts
    • +
  • manual: Require manual resolution for all conflicts
    • +
+ +

See: Conflict Resolution Workflows for detailed workflow examples.

+ +

project resolve-conflict

+ +

Resolve a specific conflict in a project bundle after a merge operation.

+ +
specfact project resolve-conflict [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --path CONFLICT_PATH - Conflict path (e.g., features.FEATURE-001.title, required)
    • +
  • --resolution RESOLUTION - Resolution: ours, theirs, base, or manual value (required)
    • +
  • --persona PERSONA - Persona resolving the conflict (for ownership validation, optional)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Resolve conflict by keeping our version
+specfact project resolve-conflict \
+  --bundle my-project \
+  --path features.FEATURE-001.title \
+  --resolution ours
+
+# Resolve conflict by keeping their version
+specfact project resolve-conflict \
+  --bundle my-project \
+  --path idea.intent \
+  --resolution theirs \
+  --persona product-owner
+
+# Resolve conflict with manual value
+specfact project resolve-conflict \
+  --bundle my-project \
+  --path features.FEATURE-001.title \
+  --resolution "Custom Feature Title"
+
+ +

Conflict Path Format:

+ +
    +
  • idea.title - Idea title
    • +
  • idea.intent - Idea intent
    • +
  • business.value_proposition - Business value proposition
    • +
  • product.themes - Product themes (list)
    • +
  • features.FEATURE-001.title - Feature title
    • +
  • features.FEATURE-001.stories.STORY-001.description - Story description
    • +
+ +

Note: This command is a helper for resolving individual conflicts after a merge. For full merge operations, use project merge.

+ +

See: Conflict Resolution Workflows for detailed workflow examples.

+ +

project lock

+ +

Lock a section for a persona to prevent concurrent edits.

+ +
specfact project lock [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --section SECTION - Section pattern to lock (e.g., idea, features.*.stories, required)
    • +
  • --persona PERSONA - Persona name (e.g., product-owner, architect, required)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Lock idea section for product owner
+specfact project lock --bundle my-project --section idea --persona product-owner
+
+# Lock all feature stories for product owner
+specfact project lock --bundle my-project --section "features.*.stories" --persona product-owner
+
+# Lock protocols for architect
+specfact project lock --bundle my-project --section protocols --persona architect
+
+ +

How it works:

+ +
    +
  1. Validates ownership: Checks that the persona owns the section (based on manifest)
    2. +
  2. Checks existing locks: Fails if section is already locked
    3. +
  3. Creates lock: Adds lock to bundle manifest with timestamp and user info
    4. +
  4. Saves bundle: Updates bundle manifest with lock information
    5. +
+ +

Lock Enforcement: Once locked, only the locking persona (or unlock command) can modify the section. Import operations will be blocked if attempting to edit a locked section owned by a different persona.

+ +

See: Section Locking for detailed workflow examples.

+ +

project unlock

+ +

Unlock a section to allow edits by any persona that owns it.

+ +
specfact project unlock [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --section SECTION - Section pattern to unlock (e.g., idea, features.*.stories, required)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Unlock idea section
+specfact project unlock --bundle my-project --section idea
+
+# Unlock all feature stories
+specfact project unlock --bundle my-project --section "features.*.stories"
+
+ +

How it works:

+ +
    +
  1. Finds lock: Searches for matching lock in bundle manifest
    2. +
  2. Removes lock: Removes lock from manifest
    3. +
  3. Saves bundle: Updates bundle manifest
    4. +
+ +

Note: Unlock doesn’t require a persona parameter - anyone can unlock a section (coordination is expected at team level).

+ +

See: Section Locking for detailed workflow examples.

+ +

project locks

+ +

List all current section locks in a project bundle.

+ +
specfact project locks [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# List all locks
+specfact project locks --bundle my-project
+
+ +

Output Format:

+ +

Displays a table with:

+ +
    +
  • Section: Section pattern that’s locked
    • +
  • Owner: Persona who locked the section
    • +
  • Locked At: ISO 8601 timestamp when lock was created
    • +
  • Locked By: User@hostname who created the lock
    • +
+ +

Use Cases:

+ +
    +
  • Check what’s locked before starting work
    • +
  • Coordinate with team members about lock usage
    • +
  • Identify stale locks that need cleanup
    • +
+ +

See: Section Locking for detailed workflow examples.

+ +
+ +

project init-personas

+ +

Initialize personas in project bundle manifest for persona-based workflows.

+ +
specfact project init-personas [OPTIONS]
+
+ +

Purpose:

+ +

Adds default persona mappings to the bundle manifest if they are missing. Useful for migrating existing bundles to use persona workflows or setting up new bundles for team collaboration.

+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name. If not specified, attempts to auto-detect or prompt.
    • +
  • --persona PERSONA - Specific persona(s) to initialize (can be repeated). If not specified, initializes all default personas.
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Default Personas:

+ +

When no specific personas are specified, the following default personas are initialized:

+ +
    +
  • product-owner: Owns idea, features metadata, and stories acceptance criteria
    • +
  • architect: Owns contracts, protocols, and technical constraints
    • +
  • developer: Owns implementation details, file paths, and technical stories
    • +
+ +

Examples:

+ +
# Initialize all default personas
+specfact project init-personas --bundle legacy-api
+
+# Initialize specific personas only
+specfact project init-personas --bundle legacy-api --persona product-owner --persona architect
+
+# Non-interactive mode for CI/CD
+specfact project init-personas --bundle legacy-api --no-interactive
+
+ +

When to Use:

+ +
    +
  • After creating a new bundle with plan init
    • +
  • When migrating existing bundles to persona workflows
    • +
  • When adding new team members with specific roles
    • +
  • Before using project export/import persona commands
    • +
+ +
+ +

project version check

+ +

Check if a version bump is recommended based on bundle changes.

+ +
specfact project version check [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Output:

+ +

Returns a recommendation (major, minor, patch, or none) based on:

+ +
    +
  • major: Breaking changes detected (API contracts modified, features removed)
    • +
  • minor: New features added, stories added
    • +
  • patch: Bug fixes, documentation changes, story updates
    • +
  • none: No significant changes detected
    • +
+ +

Examples:

+ +
# Check version bump recommendation
+specfact project version check --bundle legacy-api
+
+ +

CI/CD Integration:

+ +

Configure behavior via SPECFACT_VERSION_CHECK_MODE environment variable:

+ +
    +
  • info: Informational only, logs recommendations
    • +
  • warn (default): Logs warnings but continues
    • +
  • block: Fails CI if recommendation is not followed
    • +
+ +
+ +

project version bump

+ +

Apply a SemVer version bump to the project bundle.

+ +
specfact project version bump [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --type TYPE - Bump type: major, minor, patch (required)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Bump minor version (e.g., 1.0.0 → 1.1.0)
+specfact project version bump --bundle legacy-api --type minor
+
+# Bump patch version (e.g., 1.1.0 → 1.1.1)
+specfact project version bump --bundle legacy-api --type patch
+
+ +

What it does:

+ +
    +
  1. Reads current version from bundle manifest
    2. +
  2. Applies SemVer bump based on type
    3. +
  3. Records version history with timestamp
    4. +
  4. Updates bundle hash
    5. +
+ +
+ +

project version set

+ +

Set an explicit version for the project bundle.

+ +
specfact project version set [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --version VERSION - SemVer version string (e.g., 2.0.0, 1.5.0-beta.1)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Set explicit version
+specfact project version set --bundle legacy-api --version 2.0.0
+
+# Set pre-release version
+specfact project version set --bundle legacy-api --version 1.5.0-beta.1
+
+ +

Use Cases:

+ +
    +
  • Initial version setup for new bundles
    • +
  • Aligning with external version requirements
    • +
  • Setting pre-release or build metadata versions
    • +
+ +
+ +

contract - OpenAPI Contract Management

+ +

Manage OpenAPI contracts for project bundles, including initialization, validation, mock server generation, and test generation.

+ +

contract init

+ +

Initialize OpenAPI contract for a feature.

+ +
specfact contract init [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --feature FEATURE_KEY - Feature key (e.g., FEATURE-001, required)
    • +
  • --title TITLE - API title (default: feature title)
    • +
  • --version VERSION - API version (default: 1.0.0)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Initialize contract for a feature
+specfact contract init --bundle legacy-api --feature FEATURE-001
+
+# Initialize with custom title and version
+specfact contract init --bundle legacy-api --feature FEATURE-001 --title "Authentication API" --version 1.0.0
+
+ +

What it does:

+ +
    +
  1. Creates OpenAPI 3.0.3 contract stub in contracts/FEATURE-001.openapi.yaml
    2. +
  2. Links contract to feature in bundle manifest
    3. +
  3. Updates contract index in manifest for fast lookup
    4. +
+ +

Note: Defaults to OpenAPI 3.0.3 for Specmatic compatibility. Validation accepts both 3.0.x and 3.1.x for forward compatibility.

+ +

contract validate

+ +

Validate OpenAPI contract schema.

+ +
specfact contract validate [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --feature FEATURE_KEY - Feature key (optional, validates all contracts if not specified)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Validate specific feature contract
+specfact contract validate --bundle legacy-api --feature FEATURE-001
+
+# Validate all contracts in bundle
+specfact contract validate --bundle legacy-api
+
+ +

What it does:

+ +
    +
  1. Loads OpenAPI contract(s) from bundle
    2. +
  2. Validates schema structure (supports both 3.0.x and 3.1.x)
    3. +
  3. Reports validation results with endpoint counts
    4. +
+ +

Note: For comprehensive validation including Specmatic, use specfact spec validate.

+ +

contract verify

+ +

Verify OpenAPI contract - validate, generate examples, and test mock server. This is a convenience command that combines multiple steps into one.

+ +
specfact contract verify [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --feature FEATURE_KEY - Feature key (optional, verifies all contracts if not specified)
    • +
  • --port PORT - Port number for mock server (default: 9000)
    • +
  • --skip-mock - Skip mock server startup (only validate contract)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Verify a specific contract (validates, generates examples, starts mock server)
+specfact contract verify --bundle legacy-api --feature FEATURE-001
+
+# Verify all contracts in a bundle
+specfact contract verify --bundle legacy-api
+
+# Verify without starting mock server (CI/CD)
+specfact contract verify --bundle legacy-api --feature FEATURE-001 --skip-mock --no-interactive
+
+ +

What it does:

+ +
    +
  1. Step 1: Validates contracts - Checks OpenAPI schema structure
    2. +
  2. Step 2: Generates examples - Creates example JSON files from contract schema
    3. +
  3. Step 3: Starts mock server - Launches Specmatic mock server (unless --skip-mock)
    4. +
  4. Step 4: Tests connectivity - Verifies mock server is responding
    5. +
+ +

Output:

+ +
Step 1: Validating contracts...
+✓ FEATURE-001: Valid (13 endpoints)
+
+Step 2: Generating examples...
+✓ FEATURE-001: Examples generated
+
+Step 3: Starting mock server for FEATURE-001...
+✓ Mock server started at http://localhost:9000
+
+Step 4: Testing connectivity...
+✓ Health check passed: UP
+
+✓ Contract verification complete!
+
+Summary:
+  • Contracts validated: 1
+  • Examples generated: 1
+  • Mock server: http://localhost:9000
+
+ +

When to use:

+ +
    +
  • Quick verification - One command to verify everything works
    • +
  • Development - Start mock server and verify contract is correct
    • +
  • CI/CD - Use --skip-mock --no-interactive for fast validation
    • +
  • Multiple contracts - Verify all contracts in a bundle at once
    • +
+ +

Note: This is the recommended command for most use cases. It combines validation, example generation, and mock server testing into a single, simple workflow.

+ +

contract serve

+ +

Start mock server for OpenAPI contract.

+ +
specfact contract serve [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --feature FEATURE_KEY - Feature key (optional, prompts for selection if multiple contracts)
    • +
  • --port PORT - Port number for mock server (default: 9000)
    • +
  • --strict/--examples - Use strict validation mode or examples mode (default: strict)
    • +
  • --no-interactive - Non-interactive mode (uses first contract if multiple available)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Start mock server for specific feature contract
+specfact contract serve --bundle legacy-api --feature FEATURE-001
+
+# Start mock server on custom port with examples mode
+specfact contract serve --bundle legacy-api --feature FEATURE-001 --port 8080 --examples
+
+ +

What it does:

+ +
    +
  1. Loads OpenAPI contract from bundle
    2. +
  2. Launches Specmatic mock server
    3. +
  3. Serves API endpoints based on contract
    4. +
  4. Validates requests against spec
    5. +
  5. Returns example responses
    6. +
+ +

Requirements: Specmatic must be installed (npm install -g @specmatic/specmatic)

+ +
+

Press Ctrl+C to stop the server

+
+ +

contract test

+ +

Generate contract tests from OpenAPI contract.

+ +
specfact contract test [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --feature FEATURE_KEY - Feature key (optional, generates tests for all contracts if not specified)
    • +
  • --output PATH - Output directory for generated tests (default: bundle-specific .specfact/projects/<bundle-name>/tests/contracts/)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Generate tests for specific feature contract
+specfact contract test --bundle legacy-api --feature FEATURE-001
+
+# Generate tests for all contracts in bundle
+specfact contract test --bundle legacy-api
+
+# Generate tests to custom output directory
+specfact contract test --bundle legacy-api --output tests/contracts/
+
+ +

What it does:

+ +
    +
  1. Loads OpenAPI contract(s) from bundle
    2. +
  2. Generates Specmatic test suite(s) using specmatic generate-tests
    3. +
  3. Saves tests to bundle-specific or custom output directory
    4. +
  4. Creates feature-specific test directories for organization
    5. +
+ +

Requirements: Specmatic must be installed (npm install -g @specmatic/specmatic)

+ +

Output Structure:

+ +
.specfact/projects/<bundle-name>/tests/contracts/
+├── feature-001/
+│   └── [Specmatic-generated test files]
+├── feature-002/
+│   └── [Specmatic-generated test files]
+└── ...
+
+ +

contract coverage

+ +

Calculate contract coverage for a project bundle.

+ +
specfact contract coverage [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Get coverage report for bundle
+specfact contract coverage --bundle legacy-api
+
+ +

What it does:

+ +
    +
  1. Loads all features from bundle
    2. +
  2. Checks which features have contracts
    3. +
  3. Calculates coverage percentage (features with contracts / total features)
    4. +
  4. Counts total API endpoints across all contracts
    5. +
  5. Displays coverage table with status indicators
    6. +
+ +

Output:

+ +
    +
  • Coverage table showing feature, contract file, endpoint count, and status
    • +
  • Coverage summary with percentage and total endpoints
    • +
  • Warning if coverage is below 100%
    • +
+ +

See: Specmatic Integration Guide for detailed contract testing workflow.

+ +
+ +

enforce - Configure Quality Gates

+ +

Set contract enforcement policies.

+ +

enforce sdd

+ +

Validate SDD manifest against plan bundle and contracts:

+ +
specfact enforce sdd [OPTIONS]
+
+ +

Options:

+ +
    +
  • Bundle name is provided as a positional argument (e.g., plan harden my-project)
    • +
  • --sdd PATH - SDD manifest path (default: bundle-specific .specfact/projects/<bundle-name>/sdd.<format>, Phase 8.5)
    • +
  • --output-format {markdown,json,yaml} - Output format (default: markdown)
    • +
  • --out PATH - Output report path (optional)
    • +
+ +

What it validates:

+ +
    +
  1. Hash Match: Verifies SDD manifest is linked to the correct plan bundle
    2. +
  2. Coverage Thresholds: Validates contract density metrics: +
      +
    • Contracts per story (must meet threshold)
      • +
    • Invariants per feature (must meet threshold)
      • +
    • Architecture facets (must meet threshold)
      • +
    +
    3. +
  3. SDD Structure: Validates SDD manifest schema and completeness
    4. +
+ +

Contract Density Metrics:

+ +

The command calculates and validates:

+ +
    +
  • Contracts per story: Total contracts divided by total stories
    • +
  • Invariants per feature: Total invariants divided by total features
    • +
  • Architecture facets: Number of architecture-related constraints
    • +
+ +

Example:

+ +
# Validate SDD against active plan
+specfact enforce sdd
+
+# Validate with specific bundle and SDD (bundle name as positional argument)
+specfact enforce sdd main  # Uses .specfact/projects/main/sdd.yaml (Phase 8.5)
+
+# Generate JSON report
+specfact enforce sdd --output-format json --out validation-report.json
+
+ +

Output:

+ +
    +
  • Validation status (pass/fail)
    • +
  • Contract density metrics with threshold comparisons
    • +
  • Deviations report with severity levels (HIGH/MEDIUM/LOW)
    • +
  • Fix hints for each deviation
    • +
+ +

Deviations:

+ +

The command reports deviations when:

+ +
    +
  • Hash mismatch (SDD linked to different plan)
    • +
  • Contracts per story below threshold
    • +
  • Invariants per feature below threshold
    • +
  • Architecture facets below threshold
    • +
+ +

Integration:

+ +
    +
  • Automatically called by plan review when SDD is present
    • +
  • Required for plan promote to “review” or higher stages
    • +
  • Part of standard SDD enforcement workflow
    • +
+ +

enforce stage

+ +

Configure enforcement stage:

+ +
specfact enforce stage [OPTIONS]
+
+ +

Options:

+ +
    +
  • --preset TEXT - Enforcement preset (minimal, balanced, strict) (required)
    • +
  • --config PATH - Enforcement config file
    • +
+ +

Presets:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PresetHIGH SeverityMEDIUM SeverityLOW Severity
minimalLog onlyLog onlyLog only
balancedBlockWarnLog only
strictBlockBlockWarn
+ +

Example:

+ +
# Start with minimal
+specfact enforce stage --preset minimal
+
+# Move to balanced after stabilization
+specfact enforce stage --preset balanced
+
+# Strict for production
+specfact enforce stage --preset strict
+
+ +
+ +

drift - Detect Drift Between Code and Specifications

+ +

Detect misalignment between code and specifications.

+ +

drift detect

+ +

Detect drift between code and specifications.

+ +
specfact drift detect [BUNDLE] [OPTIONS]
+
+ +

Arguments:

+ +
    +
  • BUNDLE - Project bundle name (e.g., legacy-api). Default: active plan from specfact plan select
    • +
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository. Default: current directory (.)
    • +
  • --format {table,json,yaml} - Output format. Default: table
    • +
  • --out PATH - Output file path (for JSON/YAML format). Default: stdout
    • +
+ +

What it detects:

+ +
    +
  • Added code - Files with no spec (untracked implementation files)
    • +
  • Removed code - Deleted files but spec still exists
    • +
  • Modified code - Files with hash changed (implementation modified)
    • +
  • Orphaned specs - Specifications with no source tracking (no linked code)
    • +
  • Test coverage gaps - Stories missing test functions
    • +
  • Contract violations - Implementation doesn’t match contract (requires Specmatic)
    • +
+ +

Examples:

+ +
# Detect drift for active plan
+specfact drift detect
+
+# Detect drift for specific bundle
+specfact drift detect legacy-api --repo .
+
+# Output to JSON file
+specfact drift detect my-bundle --format json --out drift-report.json
+
+# Output to YAML file
+specfact drift detect my-bundle --format yaml --out drift-report.yaml
+
+ +

Output Formats:

+ +
    +
  • Table (default) - Rich formatted table with color-coded sections
    • +
  • JSON - Machine-readable JSON format for CI/CD integration
    • +
  • YAML - Human-readable YAML format
    • +
+ +

Integration:

+ +

The drift detection command integrates with:

+ +
    +
  • Source tracking (hash-based change detection)
    • +
  • Project bundles (feature and story tracking)
    • +
  • Specmatic (contract validation, if available)
    • +
+ +

See also:

+ +
    +
  • plan compare - Compare plans to detect code vs plan drift
    • +
  • sync intelligent - Continuous sync with drift detection
    • +
+ +
+ +

repro - Reproducibility Validation

+ +

Run full validation suite for reproducibility.

+ +
specfact repro [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: current directory)
    • +
  • --verbose - Show detailed output
    • +
  • --fix - Apply auto-fixes where available (Semgrep auto-fixes)
    • +
  • --fail-fast - Stop on first failure
    • +
  • --out PATH - Output report path (default: bundle-specific .specfact/projects/<bundle-name>/reports/enforcement/report-<timestamp>.yaml, Phase 8.5, or global .specfact/reports/enforcement/ if no bundle context)
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --budget INT - Time budget in seconds (default: 120)
    • +
+ +

Subcommands:

+ +
    +
  • repro setup - Set up CrossHair configuration for contract exploration +
      +
    • Automatically generates [tool.crosshair] configuration in pyproject.toml
      • +
    • Detects source directories and environment manager
      • +
    • Checks for crosshair-tool availability
      • +
    • Provides installation guidance if needed
      • +
    +
    • +
+ +

Example:

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Standard validation (current directory)
+specfact repro --verbose --budget 120
+
+# Validate external repository
+specfact repro --repo /path/to/external/repo --verbose
+
+# Apply auto-fixes for violations
+specfact repro --fix --budget 120
+
+# Stop on first failure
+specfact repro --fail-fast
+
+ +

What it runs:

+ +
    +
  1. Lint checks - ruff, semgrep async rules
    2. +
  2. Type checking - mypy/basedpyright
    3. +
  3. Contract exploration - CrossHair
    4. +
  4. Property tests - Hypothesis
    5. +
  5. Smoke tests - Event loop lag, orphaned tasks
    6. +
  6. Plan validation - Schema compliance
    7. +
+ +

External Repository Support:

+ +

The repro command automatically detects the target repository’s environment manager and adapts commands accordingly:

+ +
    +
  • Environment Detection: Automatically detects hatch, poetry, uv, or pip-based projects
    • +
  • Tool Availability: All tools are optional - missing tools are skipped with clear messages
    • +
  • Source Detection: Automatically detects source directories (src/, lib/, or package name from pyproject.toml)
    • +
  • Cross-Repository: Works on external repositories without requiring SpecFact CLI adoption
    • +
+ +

Supported Environment Managers:

+ +

SpecFact CLI automatically detects and works with the following project management tools:

+ +
    +
  • hatch - Detected from [tool.hatch] in pyproject.toml +
      +
    • Commands prefixed with: hatch run
      • +
    • Example: hatch run pytest tests/
      • +
    +
    • +
  • poetry - Detected from [tool.poetry] in pyproject.toml or poetry.lock +
      +
    • Commands prefixed with: poetry run
      • +
    • Example: poetry run pytest tests/
      • +
    +
    • +
  • uv - Detected from [tool.uv] in pyproject.toml, uv.lock, or uv.toml +
      +
    • Commands prefixed with: uv run
      • +
    • Example: uv run pytest tests/
      • +
    +
    • +
  • pip - Detected from requirements.txt or setup.py (uses direct tool invocation) +
      +
    • Commands use: Direct tool invocation (no prefix)
      • +
    • Example: pytest tests/
      • +
    +
    • +
+ +

Detection Priority:

+ +
    +
  1. Checks pyproject.toml for tool sections ([tool.hatch], [tool.poetry], [tool.uv])
    2. +
  2. Checks for lock files (poetry.lock, uv.lock, uv.toml)
    3. +
  3. Falls back to requirements.txt or setup.py for pip-based projects
    4. +
+ +

Source Directory Detection:

+ +
    +
  • Automatically detects: src/, lib/, or package name from pyproject.toml
    • +
  • Works with any project structure without manual configuration
    • +
+ +

Tool Requirements:

+ +

Tools are checked for availability and skipped if not found:

+ +
    +
  • ruff - Optional, for linting
    • +
  • semgrep - Optional, only runs if tools/semgrep/async.yml config exists
    • +
  • basedpyright - Optional, for type checking
    • +
  • crosshair - Optional, for contract exploration (requires [tool.crosshair] config in pyproject.toml - use specfact repro setup to generate)
    • +
  • pytest - Optional, only runs if tests/contracts/ or tests/smoke/ directories exist
    • +
+ +

Auto-fixes:

+ +

When using --fix, Semgrep will automatically apply fixes for violations that have fix: fields in the rules. For example, blocking-sleep-in-async rule will automatically replace time.sleep(...) with asyncio.sleep(...) in async functions.

+ +

Exit codes:

+ +
    +
  • 0 - All checks passed
    • +
  • 1 - Validation failed
    • +
  • 2 - Budget exceeded
    • +
+ +

Report Format:

+ +

Reports are written as YAML files to .specfact/projects/<bundle-name>/reports/enforcement/report-<timestamp>.yaml (bundle-specific, Phase 8.5). Each report includes:

+ +

Summary Statistics:

+ +
    +
  • total_duration - Total time taken (seconds)
    • +
  • total_checks - Number of checks executed
    • +
  • passed_checks, failed_checks, timeout_checks, skipped_checks - Status counts
    • +
  • budget_exceeded - Whether time budget was exceeded
    • +
+ +

Check Details:

+ +
    +
  • checks - List of check results with: +
      +
    • name - Human-readable check name
      • +
    • tool - Tool used (ruff, semgrep, basedpyright, crosshair, pytest)
      • +
    • status - Check status (passed, failed, timeout, skipped)
      • +
    • duration - Time taken (seconds)
      • +
    • exit_code - Tool exit code
      • +
    • timeout - Whether check timed out
      • +
    • output_length - Length of output (truncated in report)
      • +
    • error_length - Length of error output (truncated in report)
      • +
    +
    • +
+ +

Metadata (Context):

+ +
    +
  • timestamp - When the report was generated (ISO format)
    • +
  • repo_path - Repository path (absolute)
    • +
  • budget - Time budget used (seconds)
    • +
  • active_plan_path - Active plan bundle path (relative to repo, if exists)
    • +
  • enforcement_config_path - Enforcement config path (relative to repo, if exists)
    • +
  • enforcement_preset - Enforcement preset used (minimal, balanced, strict, if config exists)
    • +
  • fix_enabled - Whether --fix flag was used (true/false)
    • +
  • fail_fast - Whether --fail-fast flag was used (true/false)
    • +
+ +

Example Report:

+ +
total_duration: 89.09
+total_checks: 4
+passed_checks: 1
+failed_checks: 2
+timeout_checks: 1
+skipped_checks: 0
+budget_exceeded: false
+checks:
+  - name: Linting (ruff)
+    tool: ruff
+    status: failed
+    duration: 0.03
+    exit_code: 1
+    timeout: false
+    output_length: 39324
+    error_length: 0
+  - name: Async patterns (semgrep)
+    tool: semgrep
+    status: passed
+    duration: 0.21
+    exit_code: 0
+    timeout: false
+    output_length: 0
+    error_length: 164
+metadata:
+  timestamp: '2025-11-06T00:43:42.062620'
+  repo_path: /home/user/my-project
+  budget: 120
+  active_plan_path: .specfact/projects/main/
+  enforcement_config_path: .specfact/gates/config/enforcement.yaml
+  enforcement_preset: balanced
+  fix_enabled: false
+  fail_fast: false
+
+ +
+ +

generate - Generate Artifacts

+ +

Generate contract stubs and other artifacts from SDD manifests.

+ +

generate contracts

+ +

Generate contract stubs from SDD manifest:

+ +
specfact generate contracts [OPTIONS]
+
+ +

Options:

+ +
    +
  • Bundle name is provided as a positional argument (e.g., plan harden my-project)
    • +
  • --sdd PATH - SDD manifest path (default: bundle-specific .specfact/projects/<bundle-name>/sdd.<format>, Phase 8.5)
    • +
  • --out PATH - Output directory (default: .specfact/contracts/)
    • +
  • --output-format {yaml,json} - SDD manifest format (default: auto-detect)
    • +
+ +

What it generates:

+ +
    +
  1. Contract stubs with icontract decorators: +
      +
    • Preconditions (@require)
      • +
    • Postconditions (@ensure)
      • +
    • Invariants (@invariant)
      • +
    +
    2. +
  2. Type checking with beartype decorators
    3. +
  3. CrossHair harnesses for property-based testing
    4. +
  4. One file per feature/story in .specfact/contracts/
    5. +
+ +

Validation:

+ +
    +
  • Hash match: Verifies SDD manifest is linked to the correct plan bundle
    • +
  • Plan bundle hash: Must match SDD manifest’s plan_bundle_hash
    • +
  • Error handling: Reports hash mismatch with clear error message
    • +
+ +

Example:

+ +
# Generate contracts from active plan and SDD
+specfact generate contracts
+
+# Generate with specific bundle and SDD (bundle name as positional argument)
+specfact generate contracts --bundle main  # Uses .specfact/projects/main/sdd.yaml (Phase 8.5)
+
+# Custom output directory
+specfact generate contracts --out src/contracts/
+
+ +

Workflow:

+ +
    +
  1. Create SDD: specfact plan harden (creates SDD manifest and saves plan with hash)
    2. +
  2. Generate contracts: specfact generate contracts (validates hash match, generates stubs)
    3. +
  3. Implement contracts: Add contract logic to generated stubs
    4. +
  4. Enforce: specfact enforce sdd (validates contract density)
    5. +
+ +

Important Notes:

+ +
    +
  • Hash validation: Command validates that SDD manifest’s plan_bundle_hash matches the plan bundle’s current hash
    • +
  • Plan bundle must be saved: Ensure plan harden has saved the plan bundle with updated hash before running generate contracts
    • +
  • Contract density: After generation, run specfact enforce sdd to validate contract density metrics
    • +
+ +

Output Structure:

+ +
.specfact/contracts/
+├── feature_001_contracts.py
+├── feature_002_contracts.py
+└── ...
+
+ +

Each file includes:

+ +
    +
  • Contract decorators (@icontract, @beartype)
    • +
  • CrossHair harnesses for property testing
    • +
  • Backlink metadata to SDD IDs
    • +
  • Plan bundle story/feature references
    • +
+ +
+ +

generate contracts-prompt

+ +

Generate AI IDE prompts for adding contracts to existing code files:

+ +
specfact generate contracts-prompt [FILE] [OPTIONS]
+
+ +

Purpose:

+ +

Creates structured prompt files that you can use with your AI IDE (Cursor, CoPilot, etc.) to add beartype, icontract, or CrossHair contracts to existing Python code. The CLI generates the prompt, your AI IDE’s LLM applies the contracts.

+ +

Options:

+ +
    +
  • FILE - Path to file to enhance (optional if --bundle provided)
    • +
  • --bundle BUNDLE_NAME - Project bundle name. If provided, selects files from bundle. Default: active plan from specfact plan select
    • +
  • --apply CONTRACTS - Required. Contracts to apply: all-contracts, beartype, icontract, crosshair, or comma-separated list (e.g., beartype,icontract)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation). Disables interactive prompts.
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --output PATH - Output file path (currently unused, prompt saved to .specfact/prompts/)
    • +
+ +

Contract Types:

+ +
    +
  • all-contracts - Apply all available contract types (beartype, icontract, crosshair)
    • +
  • beartype - Type checking decorators (@beartype)
    • +
  • icontract - Pre/post condition decorators (@require, @ensure, @invariant)
    • +
  • crosshair - Property-based test functions
    • +
+ +

Examples:

+ +
# Apply all contract types to a specific file
+specfact generate contracts-prompt src/auth/login.py --apply all-contracts
+
+# Apply specific contract types
+specfact generate contracts-prompt src/auth/login.py --apply beartype,icontract
+
+# Apply to all files in a bundle (interactive selection)
+specfact generate contracts-prompt --bundle legacy-api --apply all-contracts
+
+# Apply to all files in a bundle (non-interactive)
+specfact generate contracts-prompt --bundle legacy-api --apply all-contracts --no-interactive
+
+ +

How It Works:

+ +
    +
  1. CLI generates prompt: Reads the file and creates a structured prompt
    2. +
  2. Prompt saved: Saved to .specfact/projects/<bundle-name>/prompts/enhance-<filename>-<contracts>.md (or .specfact/prompts/ if no bundle)
    3. +
  3. You copy prompt: Copy the prompt to your AI IDE (Cursor, CoPilot, etc.)
    4. +
  4. AI IDE enhances code: AI IDE reads the file and provides enhanced code (does NOT modify file directly)
    5. +
  5. AI IDE writes to temp file: Enhanced code written to enhanced_<filename>.py
    6. +
  6. Validate with CLI: AI IDE runs specfact generate contracts-apply enhanced_<filename>.py --original <original-file>
    7. +
  7. Iterative validation: If validation fails, AI IDE fixes issues and re-validates (up to 3 attempts)
    8. +
  8. Apply changes: If validation succeeds, CLI applies changes automatically
    9. +
  9. Verify and test: Run specfact analyze contracts --bundle <bundle> and your test suite
    10. +
+ +

Prompt File Location:

+ +
    +
  • With bundle: .specfact/projects/<bundle-name>/prompts/enhance-<filename>-<contracts>.md
    • +
  • Without bundle: .specfact/prompts/enhance-<filename>-<contracts>.md
    • +
+ +

Why This Approach:

+ +
    +
  • Uses your existing AI IDE infrastructure (no separate LLM API setup)
    • +
  • No additional API costs (leverages IDE’s native LLM)
    • +
  • You maintain control (review before committing)
    • +
  • Works with any AI IDE (Cursor, CoPilot, Claude, etc.)
    • +
  • Iterative validation ensures code quality before applying changes
    • +
+ +

Complete Workflow:

+ +
# 1. Generate prompt
+specfact generate contracts-prompt src/auth/login.py --apply all-contracts
+
+# 2. Open prompt file
+cat .specfact/projects/my-bundle/prompts/enhance-login-beartype-icontract-crosshair.md
+
+# 3. Copy prompt to your AI IDE (Cursor, CoPilot, etc.)
+
+# 4. AI IDE reads the file and provides enhanced code (does NOT modify file directly)
+
+# 5. AI IDE writes enhanced code to temporary file: enhanced_login.py
+
+# 6. AI IDE runs validation
+specfact generate contracts-apply enhanced_login.py --original src/auth/login.py
+
+# 7. If validation fails, AI IDE fixes issues and re-validates (up to 3 attempts)
+
+# 8. If validation succeeds, CLI applies changes automatically
+
+# 9. Verify contract coverage
+specfact analyze contracts --bundle my-bundle
+
+# 10. Run your test suite
+pytest
+
+# 11. Commit the enhanced code
+git add src/auth/login.py && git commit -m "feat: add contracts to login module"
+
+ +

Validation Steps (performed by contracts-apply):

+ +

The contracts-apply command performs rigorous validation before applying changes:

+ +
    +
  1. File size check: Enhanced file must not be smaller than original
    2. +
  2. Python syntax validation: Uses python -m py_compile
    3. +
  3. AST structure comparison: Ensures no functions or classes are accidentally removed
    4. +
  4. Contract imports verification: Checks for required imports (beartype, icontract)
    5. +
  5. Test execution: Runs specfact repro or pytest to ensure code functions correctly
    6. +
  6. Diff preview: Displays changes before applying
    7. +
+ +

Only if all validation steps pass are changes applied to the original file.

+ +

Error Messages:

+ +

If --apply is missing or invalid, the CLI shows helpful error messages with:

+ +
    +
  • Available contract types and descriptions
    • +
  • Usage examples
    • +
  • Link to full documentation
    • +
+ +
+ +

generate fix-prompt

+ +

Generate AI IDE prompt for fixing a specific gap identified by analysis:

+ +
specfact generate fix-prompt [GAP_ID] [OPTIONS]
+
+ +

Purpose:

+ +

Creates a structured prompt file for your AI IDE (Cursor, Copilot, etc.) to fix identified gaps in your codebase. This is the recommended workflow for v0.17+ and replaces direct code generation.

+ +

Arguments:

+ +
    +
  • GAP_ID - Gap ID to fix (e.g., GAP-001). If not provided, lists available gaps.
    • +
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name. Default: active plan from specfact plan select
    • +
  • --output PATH, -o PATH - Output file path. Default: .specfact/prompts/fix-<gap-id>.md
    • +
  • --top N - Show top N gaps when listing. Default: 5
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
+ +

Workflow:

+ +
    +
  1. Run analysis to identify gaps (via import from-code + repro)
    2. +
  2. Run specfact generate fix-prompt to list available gaps
    3. +
  3. Run specfact generate fix-prompt GAP-001 to generate fix prompt
    4. +
  4. Copy the prompt to your AI IDE (Cursor, Copilot, Claude, etc.)
    5. +
  5. AI IDE provides the fix
    6. +
  6. Validate with specfact enforce sdd --bundle <bundle>
    7. +
+ +

Examples:

+ +
# List available gaps
+specfact generate fix-prompt
+
+# Generate fix prompt for specific gap
+specfact generate fix-prompt GAP-001
+
+# List gaps for specific bundle
+specfact generate fix-prompt --bundle legacy-api
+
+# Save to specific file
+specfact generate fix-prompt GAP-001 --output fix.md
+
+# Show more gaps in listing
+specfact generate fix-prompt --top 10
+
+ +

Gap Report Location:

+ +

Gap reports are stored at .specfact/projects/<bundle-name>/reports/gaps.json. If no gap report exists, the command provides guidance on how to generate one.

+ +

Why This Approach:

+ +
    +
  • AI IDE native: Uses your existing AI infrastructure (no separate LLM API setup)
    • +
  • No additional costs: Leverages IDE’s native LLM
    • +
  • You maintain control: Review fixes before committing
    • +
  • Works with any AI IDE: Cursor, Copilot, Claude, Windsurf, etc.
    • +
+ +
+ +

generate test-prompt

+ +

Generate AI IDE prompt for creating tests for a file:

+ +
specfact generate test-prompt [FILE] [OPTIONS]
+
+ +

Purpose:

+ +

Creates a structured prompt file for your AI IDE to generate comprehensive tests for your code. This is the recommended workflow for v0.17+.

+ +

Arguments:

+ +
    +
  • FILE - File to generate tests for. If not provided with --bundle, shows files without tests.
    • +
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name. Default: active plan from specfact plan select
    • +
  • --output PATH, -o PATH - Output file path. Default: .specfact/prompts/test-<filename>.md
    • +
  • --type TYPE - Test type: unit, integration, or both. Default: unit
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
+ +

Workflow:

+ +
    +
  1. Run specfact generate test-prompt src/module.py to get a test prompt
    2. +
  2. Copy the prompt to your AI IDE
    3. +
  3. AI IDE generates tests
    4. +
  4. Save tests to appropriate location (e.g., tests/unit/test_module.py)
    5. +
  5. Run tests with pytest
    6. +
+ +

Examples:

+ +
# List files that may need tests
+specfact generate test-prompt --bundle legacy-api
+
+# Generate unit test prompt for specific file
+specfact generate test-prompt src/auth/login.py
+
+# Generate integration test prompt
+specfact generate test-prompt src/api.py --type integration
+
+# Generate both unit and integration test prompts
+specfact generate test-prompt src/core/engine.py --type both
+
+# Save to specific file
+specfact generate test-prompt src/utils.py --output tests-prompt.md
+
+ +

Test Coverage Analysis:

+ +

When run without a file argument, the command analyzes the repository for Python files without corresponding test files and displays them in a table.

+ +

Generated Prompt Content:

+ +

The generated prompt includes:

+ +
    +
  • File path and content
    • +
  • Test type requirements (unit/integration/both)
    • +
  • Testing framework guidance (pytest, fixtures, parametrize)
    • +
  • Coverage requirements based on test type
    • +
  • AAA pattern (Arrange-Act-Assert) guidelines
    • +
+ +
+ +

generate tasks - Removed

+ +
+

⚠️ REMOVED in v0.22.0: The specfact generate tasks command has been removed. Per SPECFACT_0x_TO_1x_BRIDGE_PLAN.md, SpecFact CLI does not create plan → feature → task (that’s the job for spec-kit, openspec, etc.). We complement those SDD tools to enforce tests and quality.

+
+ +

Previous functionality (removed):

+ +

Generate task breakdown from project bundle and SDD manifest:

+ +
specfact generate tasks [BUNDLE] [OPTIONS]
+
+ +

Purpose:

+ +

Creates a dependency-ordered task list organized by development phase, linking tasks to user stories with acceptance criteria, file paths, dependencies, and parallelization markers.

+ +

Arguments:

+ +
    +
  • BUNDLE - Project bundle name (e.g., legacy-api). Default: active plan from specfact plan select
    • +
+ +

Options:

+ +
    +
  • --sdd PATH - Path to SDD manifest. Default: auto-discover from bundle name
    • +
  • --output-format FORMAT - Output format: yaml, json, markdown. Default: yaml
    • +
  • --out PATH - Output file path. Default: .specfact/projects/<bundle-name>/tasks.yaml
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
+ +

Task Phases:

+ +

Tasks are organized into four phases:

+ +
    +
  1. Setup: Project structure, dependencies, configuration
    2. +
  2. Foundational: Core models, base classes, contracts
    3. +
  3. User Stories: Feature implementation tasks (linked to stories)
    4. +
  4. Polish: Tests, documentation, optimization
    5. +
+ +

Previous Examples (command removed):

+ +
# REMOVED in v0.22.0 - Do not use
+# specfact generate tasks
+# specfact generate tasks legacy-api
+# specfact generate tasks auth-module --output-format json
+# specfact generate tasks legacy-api --output-format markdown
+# specfact generate tasks legacy-api --out custom-tasks.yaml
+
+ +

Migration: Use Spec-Kit, OpenSpec, or other SDD tools to create tasks. SpecFact CLI focuses on enforcing tests and quality gates for existing code.

+ +

Output Structure (YAML):

+ +
version: "1.0"
+bundle: legacy-api
+phases:
+  - name: Setup
+    tasks:
+      - id: TASK-001
+        title: Initialize project structure
+        story_ref: null
+        dependencies: []
+        parallel: false
+        files: [pyproject.toml, src/__init__.py]
+  - name: User Stories
+    tasks:
+      - id: TASK-010
+        title: Implement user authentication
+        story_ref: STORY-001
+        acceptance_criteria:
+          - Users can log in with email/password
+        dependencies: [TASK-001, TASK-005]
+        parallel: true
+        files: [src/auth/login.py]
+
+ +

Note: An SDD manifest (from plan harden) is recommended but not required. Without an SDD, tasks are generated based on plan bundle features and stories only.

+ +
+ +

sync - Synchronize Changes

+ +

Bidirectional synchronization for consistent change management.

+ +

sync bridge

+ +

Sync changes between external tool artifacts (Spec-Kit, Linear, Jira, etc.) and SpecFact using the bridge architecture:

+ +
specfact sync bridge [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
  • --adapter ADAPTER - Adapter type: speckit, generic-markdown, openspec, github, ado, linear, jira, notion (default: auto-detect)
    • +
  • --bundle BUNDLE_NAME - Project bundle name for SpecFact → tool conversion (default: auto-detect)
    • +
  • --mode MODE - Sync mode: read-only (OpenSpec → SpecFact), export-only (OpenSpec → DevOps), import-annotation (DevOps → SpecFact). Default: bidirectional if --bidirectional, else unidirectional
    • +
  • --external-base-path PATH - Base path for external tool repository (for cross-repo integrations, e.g., OpenSpec in different repo)
    • +
  • --bidirectional - Enable bidirectional sync (default: one-way import)
    • +
  • --overwrite - Overwrite existing tool artifacts (delete all existing before sync)
    • +
  • --watch - Watch mode for continuous sync (monitors file changes in real-time)
    • +
  • --interval INT - Watch interval in seconds (default: 5, minimum: 1)
    • +
  • --ensure-compliance - Validate and auto-enrich plan bundle for tool compliance before sync
    • +
+ +

DevOps Backlog Tracking (export-only mode):

+ +

When using --mode export-only with DevOps adapters (GitHub, ADO, Linear, Jira), the command exports OpenSpec change proposals to DevOps backlog tools, creating GitHub issues and tracking implementation progress through automated comment annotations.

+ +

Quick Start:

+ +
    +
  1. Create change proposals in openspec/changes/<change-id>/proposal.md
    2. +
  2. +

    Export to GitHub to create issues:

    + + 
    specfact sync bridge --adapter github --mode export-only \
+  --repo-owner owner --repo-name repo \
+  --repo /path/to/openspec-repo
+
    +
    3. +
  3. +

    Track code changes by adding progress comments:

    + + 
    specfact sync bridge --adapter github --mode export-only \
+  --repo-owner owner --repo-name repo \
+  --track-code-changes \
+  --repo /path/to/openspec-repo \
+  --code-repo /path/to/source-code-repo  # If different from OpenSpec repo
+
    +
    4. +
+ +

Basic Options:

+ +
    +
  • --adapter github - GitHub Issues adapter (requires GitHub API token)
    • +
  • --repo-owner OWNER - GitHub repository owner (optional, can use bridge config)
    • +
  • --repo-name NAME - GitHub repository name (optional, can use bridge config)
    • +
  • --github-token TOKEN - GitHub API token (optional, uses GITHUB_TOKEN env var or gh CLI if not provided)
    • +
  • --use-gh-cli/--no-gh-cli - Use GitHub CLI (gh auth token) to get token automatically (default: True). Useful in enterprise environments where PAT creation is restricted
    • +
  • --sanitize/--no-sanitize - Sanitize proposal content for public issues (default: auto-detect based on repo setup) +
      +
    • Auto-detection: If code repo != planning repo → sanitize, if same repo → no sanitization
      • +
    • --sanitize: Force sanitization (removes competitive analysis, internal strategy, implementation details)
      • +
    • --no-sanitize: Skip sanitization (use full proposal content)
      • +
    +
    • +
  • --target-repo OWNER/REPO - Target repository for issue creation (format: owner/repo). Default: same as code repository
    • +
  • --interactive - Interactive mode for AI-assisted sanitization (requires slash command)
    • +
  • --change-ids ID1,ID2 - Comma-separated list of change proposal IDs to export (default: all active proposals)
    • +
+ +

Environment Variables:

+ +
    +
  • GITHUB_TOKEN - GitHub API token (used if --github-token not provided and --use-gh-cli is False)
    • +
+ +

Watch Mode Features:

+ +
    +
  • Hash-based change detection: Only processes files that actually changed (SHA256 hash verification)
    • +
  • Real-time monitoring: Automatically detects file changes in tool artifacts, SpecFact bundles, and repository code
    • +
  • Dependency tracking: Tracks file dependencies for incremental processing
    • +
  • Debouncing: Prevents rapid file change events (500ms debounce interval)
    • +
  • Change type detection: Automatically detects whether changes are in tool artifacts, SpecFact bundles, or code
    • +
  • LZ4 cache compression: Faster cache I/O when LZ4 is available (optional)
    • +
  • Graceful shutdown: Press Ctrl+C to stop watch mode cleanly
    • +
  • Resource efficient: Minimal CPU/memory usage
    • +
+ +

Examples:

+ +
# One-time bidirectional sync with Spec-Kit
+specfact sync bridge --adapter speckit --repo . --bundle my-project --bidirectional
+
+# Auto-detect adapter and bundle
+specfact sync bridge --repo . --bidirectional
+
+# Overwrite tool artifacts with SpecFact bundle
+specfact sync bridge --adapter speckit --repo . --bundle my-project --bidirectional --overwrite
+
+# Continuous watch mode
+specfact sync bridge --adapter speckit --repo . --bundle my-project --bidirectional --watch --interval 5
+
+# OpenSpec read-only sync (Phase 1 - import only)
+specfact sync bridge --adapter openspec --mode read-only --bundle my-project --repo .
+
+# OpenSpec cross-repository sync (OpenSpec in different repo)
+specfact sync bridge --adapter openspec --mode read-only --bundle my-project --repo . --external-base-path ../specfact-cli-internal
+
+ +

Export OpenSpec change proposals to GitHub issues (auto-detect sanitization)

+

specfact sync bridge –adapter github –mode export-only

+ +

Export with explicit repository and sanitization

+

specfact sync bridge –adapter github –mode export-only
+ –repo-owner owner –repo-name repo
+ –sanitize
+ –target-repo public-owner/public-repo

+ +

Export without sanitization (use full proposal content)

+

specfact sync bridge –adapter github –mode export-only
+ –no-sanitize

+ +

Export using GitHub CLI for token (enterprise-friendly)

+

specfact sync bridge –adapter github –mode export-only
+ –use-gh-cli

+ +

Export specific change proposals only

+

specfact sync bridge –adapter github –mode export-only
+ –repo-owner owner –repo-name repo
+ –change-ids add-feature-x,update-api
+ –repo /path/to/openspec-repo

+

+**What it syncs (Spec-Kit adapter):**
+
+- `specs/[###-feature-name]/spec.md`, `plan.md`, `tasks.md` ↔ `.specfact/projects/<bundle-name>/bundle.yaml`
+- `.specify/memory/constitution.md` ↔ SpecFact business context
+- `specs/[###-feature-name]/research.md`, `data-model.md`, `quickstart.md` ↔ SpecFact supporting artifacts
+- `specs/[###-feature-name]/contracts/*.yaml` ↔ SpecFact protocol definitions
+- Automatic conflict resolution with priority rules
+
+**Spec-Kit Field Auto-Generation:**
+
+When syncing from SpecFact to Spec-Kit (`--bidirectional`), the CLI automatically generates all required Spec-Kit fields:
+
+- **spec.md**: Frontmatter (Feature Branch, Created date, Status), INVSEST criteria, Scenarios (Primary, Alternate, Exception, Recovery)
+- **plan.md**: Constitution Check (Article VII, VIII, IX), Phases (Phase 0, 1, 2, -1), Technology Stack (from constraints), Constraints, Unknowns
+- **tasks.md**: Phase organization (Phase 1: Setup, Phase 2: Foundational, Phase 3+: User Stories), Story mappings ([US1], [US2]), Parallel markers [P]
+
+**All Spec-Kit fields are auto-generated** - no manual editing required unless you want to customize defaults. Generated artifacts are ready for `/speckit.analyze` without additional work.
+
+**Content Sanitization (export-only mode):**
+
+When exporting OpenSpec change proposals to public repositories, content sanitization removes internal/competitive information while preserving user-facing value:
+
+**What's Removed:**
+
+- Competitive analysis sections
+- Market positioning statements
+- Implementation details (file-by-file changes)
+- Effort estimates and timelines
+- Technical architecture details
+- Internal strategy sections
+
+**What's Preserved:**
+
+- High-level feature descriptions
+- User-facing value propositions
+- Acceptance criteria
+- External documentation links
+- Use cases and examples
+
+**When to Use Sanitization:**
+
+- **Different repos** (code repo ≠ planning repo): Sanitization recommended (default: yes)
+- **Same repo** (code repo = planning repo): Sanitization optional (default: no, user can override)
+- **Breaking changes**: Use sanitization to communicate changes early without exposing internal strategy
+- **OSS collaboration**: Use sanitization for public issues to keep contributors informed
+
+**Sanitization Auto-Detection:**
+
+- Automatically detects if code and planning are in different repositories
+- Defaults to sanitize when repos differ (protects internal information)
+- Defaults to no sanitization when repos are the same (user can choose full disclosure)
+- User can override with `--sanitize` or `--no-sanitize` flags
+
+**AI-Assisted Sanitization:**
+
+- Use slash command `/specfact.sync-backlog` for interactive, AI-assisted content rewriting
+- AI analyzes proposal content and suggests sanitized version
+- User can review and approve sanitized content before issue creation
+- Useful for complex proposals requiring nuanced content adaptation
+
+**Proposal Filtering (export-only mode):**
+
+When exporting OpenSpec change proposals to DevOps tools, proposals are filtered based on target repository type and status:
+
+**Public Repositories** (with `--sanitize`):
+
+- **Only syncs proposals with status `"applied"`** (archived/completed changes)
+- Filters out proposals with status `"proposed"`, `"in-progress"`, `"deprecated"`, or `"discarded"`
+- Applies regardless of whether proposals have existing source tracking entries
+- Prevents premature exposure of work-in-progress proposals to public repositories
+- Warning message displayed when proposals are filtered out
+
+**Internal Repositories** (with `--no-sanitize` or auto-detected as internal):
+
+- Syncs all active proposals regardless of status:
+  - `"proposed"` - New proposals not yet started
+  - `"in-progress"` - Proposals currently being worked on
+  - `"applied"` - Completed/archived proposals
+  - `"deprecated"` - Deprecated proposals
+  - `"discarded"` - Discarded proposals
+- If proposal has source tracking entry for target repo: syncs it (for updates)
+- If proposal doesn't have entry: syncs if status is active
+
+**Examples:**
+
+```bash
+# Public repo: only syncs "applied" proposals (archived changes)
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli \
+  --sanitize \
+  --target-repo nold-ai/specfact-cli
+
+# Internal repo: syncs all active proposals (proposed, in-progress, applied, etc.)
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --no-sanitize \
+  --target-repo nold-ai/specfact-cli-internal
+
+ +

Code Change Tracking and Progress Comments (export-only mode):

+ +

When using --mode export-only with DevOps adapters, you can track implementation progress by detecting code changes and adding progress comments to existing GitHub issues:

+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --track-code-changes/--no-track-code-changes - Detect code changes (git commits, file modifications) and add progress comments to existing issues (default: False)
    • +
  • --add-progress-comment/--no-add-progress-comment - Add manual progress comment to existing issues without code change detection (default: False)
    • +
  • --code-repo PATH - Path to source code repository for code change detection (default: same as --repo). Required when OpenSpec repository differs from source code repository. For example, if OpenSpec proposals are in specfact-cli-internal but source code is in specfact-cli, use --repo /path/to/specfact-cli-internal --code-repo /path/to/specfact-cli.
    • +
  • --update-existing/--no-update-existing - Update existing issue bodies when proposal content changes (default: False for safety). Uses content hash to detect changes.
    • +
+ +

Code Change Detection:

+ +

When --track-code-changes is enabled:

+ +
    +
  1. Git Commit Detection: Searches git log for commits mentioning the change proposal ID (e.g., add-code-change-tracking)
    2. +
  2. File Change Tracking: Extracts files modified in detected commits
    3. +
  3. Progress Comment Generation: Formats progress comment with: +
      +
    • Commit details (hash, message, author, date)
      • +
    • Files changed summary
      • +
    • Detection timestamp
      • +
    +
    4. +
  4. Duplicate Prevention: Calculates SHA-256 hash of comment text and checks against existing progress comments
    5. +
  5. Source Tracking Update: Stores progress comment in source_metadata.progress_comments and updates last_code_change_detected timestamp
    6. +
+ +

Progress Comment Sanitization:

+ +

When --sanitize is enabled (for public repositories), progress comments are automatically sanitized:

+ +
    +
  • Commit messages: Internal/confidential/competitive keywords removed, long messages truncated
    • +
  • File paths: Replaced with file type counts (e.g., “3 py file(s)” instead of full paths)
    • +
  • Author emails: Removed, only username shown
    • +
  • Timestamps: Date only (no time component)
    • +
+ +

Examples:

+ +
# Detect code changes and add progress comments (internal repo)
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --track-code-changes \
+  --repo .
+
+# Detect code changes with sanitization (public repo)
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli \
+  --track-code-changes \
+  --sanitize \
+  --repo .
+
+# Add manual progress comment (without code change detection)
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --add-progress-comment \
+  --repo .
+
+# Update existing issues AND add progress comments
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --update-existing \
+  --track-code-changes \
+  --repo .
+
+# Sync specific change proposal with code change tracking
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --track-code-changes \
+  --change-ids add-code-change-tracking \
+  --repo .
+
+# Separate OpenSpec and source code repositories
+# OpenSpec proposals in specfact-cli-internal, source code in specfact-cli
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --track-code-changes \
+  --change-ids add-code-change-tracking \
+  --repo /path/to/specfact-cli-internal \
+  --code-repo /path/to/specfact-cli
+
+ +

Prerequisites:

+ +

For Issue Creation:

+ +
    +
  • Change proposals must exist in openspec/changes/<change-id>/proposal.md directory (in the OpenSpec repository specified by --repo)
    • +
  • GitHub token (via GITHUB_TOKEN env var, gh auth token, or --github-token)
    • +
  • Repository access permissions (read for proposals, write for issues)
    • +
+ +

For Code Change Tracking:

+ +
    +
  • Issues must already exist (created via previous sync)
    • +
  • Git repository with commits mentioning the change proposal ID in commit messages: +
      +
    • If --code-repo is provided, commits must be in that repository
      • +
    • Otherwise, commits must be in the OpenSpec repository (--repo)
      • +
    +
    • +
  • Commit messages should include the change proposal ID (e.g., “feat: implement add-code-change-tracking”)
    • +
+ +

Separate OpenSpec and Source Code Repositories:

+ +

When your OpenSpec change proposals are in a different repository than your source code:

+ +
# Example: OpenSpec in specfact-cli-internal, source code in specfact-cli
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --track-code-changes \
+  --repo /path/to/specfact-cli-internal \
+  --code-repo /path/to/specfact-cli
+
+ +

Why use --code-repo?

+ +
    +
  • OpenSpec repository (--repo): Contains change proposals in openspec/changes/ directory
    • +
  • Source code repository (--code-repo): Contains actual implementation commits that reference the change proposal ID
    • +
+ +

If both are in the same repository, you can omit --code-repo and it will use --repo for both purposes.

+ +

Integration Workflow:

+ +
    +
  1. +

    Initial Setup (one-time):

    + + 
    # Create change proposal in openspec/changes/<change-id>/proposal.md
+# Export to GitHub to create issue
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner owner --repo-name repo \
+  --repo /path/to/openspec-repo
+
    +
    2. +
  2. +

    Development Workflow (ongoing):

    + + 
    # Make commits with change ID in commit message
+git commit -m "feat: implement add-code-change-tracking - initial implementation"
+   
+# Track progress automatically
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner owner --repo-name repo \
+  --track-code-changes \
+  --repo /path/to/openspec-repo \
+  --code-repo /path/to/source-code-repo
+
    +
    3. +
  3. +

    Manual Progress Updates (when needed):

    + + 
    # Add manual progress comment without code change detection
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner owner --repo-name repo \
+  --add-progress-comment \
+  --repo /path/to/openspec-repo
+
    +
    4. +
+ +

Verification:

+ +

After running the command, verify:

+ +
    +
  1. +

    GitHub Issue: Check that progress comment was added to the issue:

    + + 
    gh issue view <issue-number> --repo owner/repo --json comments --jq '.comments[-1].body'
+
    +
    2. +
  2. +

    Source Tracking: Verify openspec/changes/<change-id>/proposal.md was updated with:

    + + 
    ## Source Tracking
+   
+- **GitHub Issue**: #123
+- **Issue URL**: <https://github.com/owner/repo/issues/123>
+- **Last Synced Status**: proposed
+- **Sanitized**: false
+<!-- last_code_change_detected: 2025-12-30T10:00:00Z -->
+
    +
    3. +
  3. +

    Duplicate Prevention: Run the same command twice - second run should skip duplicate comment (no new comment added)

    +
    4. +
+ +

Troubleshooting:

+ +
    +
  • No commits detected: Ensure commit messages include the change proposal ID (e.g., “add-code-change-tracking”)
    • +
  • Wrong repository: Verify --code-repo points to the correct source code repository
    • +
  • No comments added: Check that issues exist (create them first without --track-code-changes)
    • +
  • Sanitization issues: Use --sanitize for public repos, --no-sanitize for internal repos
    • +
+ +

Constitution Evidence Extraction:

+ +

When generating Spec-Kit plan.md files, SpecFact automatically extracts evidence-based constitution alignment from your codebase:

+ +
    +
  • Article VII (Simplicity): Analyzes project structure, directory depth, file organization, and naming patterns to determine PASS/FAIL status with rationale
    • +
  • Article VIII (Anti-Abstraction): Detects framework usage, abstraction layers, and framework-specific patterns to assess anti-abstraction compliance
    • +
  • Article IX (Integration-First): Analyzes contract patterns (icontract decorators, OpenAPI definitions, type hints) to verify integration-first approach
    • +
+ +

Evidence-Based Status: Constitution check sections include PASS/FAIL status (not PENDING) with:

+ +
    +
  • Evidence citations from code patterns
    • +
  • Rationale explaining why each article passes or fails
    • +
  • Actionable recommendations for improvement (if FAIL)
    • +
+ +

This evidence extraction happens automatically during sync bridge --adapter speckit when generating Spec-Kit artifacts. No additional configuration required.

+ +

sync repository

+ +

Sync code changes to SpecFact artifacts:

+ +
specfact sync repository [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
  • --target PATH - Target directory for artifacts (default: .specfact)
    • +
  • --watch - Watch mode for continuous sync (monitors code changes in real-time)
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --interval INT - Watch interval in seconds (default: 5, minimum: 1)
    • +
  • --confidence FLOAT - Minimum confidence threshold for feature detection (default: 0.5, range: 0.0-1.0)
    • +
+ +

Watch Mode Features:

+ +
    +
  • Hash-based change detection: Only processes files that actually changed (SHA256 hash verification)
    • +
  • Real-time monitoring: Automatically detects code changes in repository
    • +
  • Automatic sync: Triggers sync when code changes are detected
    • +
  • Deviation tracking: Tracks deviations from manual plans as code changes
    • +
  • Dependency tracking: Tracks file dependencies for incremental processing
    • +
  • Debouncing: Prevents rapid file change events (500ms debounce interval)
    • +
  • LZ4 cache compression: Faster cache I/O when LZ4 is available (optional)
    • +
  • Graceful shutdown: Press Ctrl+C to stop watch mode cleanly
    • +
+ +

Example:

+ +
# One-time sync
+specfact sync repository --repo . --target .specfact
+
+# Continuous watch mode (monitors for code changes every 5 seconds)
+specfact sync repository --repo . --watch --interval 5
+
+# Watch mode with custom interval and confidence threshold
+specfact sync repository --repo . --watch --interval 2 --confidence 0.7
+
+ +

What it tracks:

+ +
    +
  • Code changes → Plan artifact updates
    • +
  • Deviations from manual plans
    • +
  • Feature/story extraction from code
    • +
+ +
+ +

spec - API Specification Management (Specmatic Integration)

+ +

Manage API specifications with Specmatic for OpenAPI/AsyncAPI validation, backward compatibility checking, and mock server functionality.

+ +

Note: Specmatic is a Java CLI tool that must be installed separately from https://docs.specmatic.io/. SpecFact CLI will check for Specmatic availability and provide helpful error messages if it’s not found.

+ +

spec validate

+ +

Validate OpenAPI/AsyncAPI specification using Specmatic. Can validate a single file or all contracts in a project bundle.

+ +
specfact spec validate [<spec-path>] [OPTIONS]
+
+ +

Arguments:

+ +
    +
  • <spec-path> - Path to OpenAPI/AsyncAPI specification file (optional if –bundle provided)
    • +
+ +

Options:

+ +
    +
  • --bundle NAME - Project bundle name (e.g., legacy-api). If provided, validates all contracts in bundle. Default: active plan from ‘specfact plan select’
    • +
  • --previous PATH - Path to previous version for backward compatibility check
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation). Disables interactive prompts.
    • +
+ +

Examples:

+ +
# Validate a single spec file
+specfact spec validate api/openapi.yaml
+
+# With backward compatibility check
+specfact spec validate api/openapi.yaml --previous api/openapi.v1.yaml
+
+# Validate all contracts in active bundle (interactive selection)
+specfact spec validate
+
+# Validate all contracts in specific bundle
+specfact spec validate --bundle legacy-api
+
+# Non-interactive: validate all contracts
+specfact spec validate --bundle legacy-api --no-interactive
+
+ +

CLI-First Pattern: Uses active plan (from specfact plan select) as default, or specify --bundle. Never requires direct .specfact paths - always use the CLI interface. When multiple contracts are available, shows interactive list for selection.

+ +

What it checks:

+ +
    +
  • Schema structure validation
    • +
  • Example generation test
    • +
  • Backward compatibility (if previous version provided)
    • +
+ +

Output:

+ +
    +
  • Validation results table with status for each check
    • +
  • ✓ PASS or ✗ FAIL for each validation step
    • +
  • Detailed errors if validation fails
    • +
  • Summary when validating multiple contracts
    • +
+ +

spec backward-compat

+ +

Check backward compatibility between two spec versions.

+ +
specfact spec backward-compat <old-spec> <new-spec>
+
+ +

Arguments:

+ +
    +
  • <old-spec> - Path to old specification version (required)
    • +
  • <new-spec> - Path to new specification version (required)
    • +
+ +

Example:

+ +
specfact spec backward-compat api/openapi.v1.yaml api/openapi.v2.yaml
+
+ +

Output:

+ +
    +
  • ✓ Compatible - No breaking changes detected
    • +
  • ✗ Breaking changes - Lists incompatible changes
    • +
+ +

spec generate-tests

+ +

Generate Specmatic test suite from specification. Can generate for a single file or all contracts in a bundle.

+ +
specfact spec generate-tests [<spec-path>] [OPTIONS]
+
+ +

Arguments:

+ +
    +
  • <spec-path> - Path to OpenAPI/AsyncAPI specification (optional if –bundle provided)
    • +
+ +

Options:

+ +
    +
  • --bundle NAME - Project bundle name (e.g., legacy-api). If provided, generates tests for all contracts in bundle. Default: active plan from ‘specfact plan select’
    • +
  • --out PATH - Output directory for generated tests (default: .specfact/specmatic-tests/)
    • +
+ +

Examples:

+ +
# Generate for a single spec file
+specfact spec generate-tests api/openapi.yaml
+
+# Generate to custom location
+specfact spec generate-tests api/openapi.yaml --out tests/specmatic/
+
+# Generate tests for all contracts in active bundle
+specfact spec generate-tests --bundle legacy-api
+
+# Generate tests for all contracts in specific bundle
+specfact spec generate-tests --bundle legacy-api --out tests/contract/
+
+ +

CLI-First Pattern: Uses active plan as default, or specify --bundle. Never requires direct .specfact paths.

+ +

Caching: +Test generation results are cached in .specfact/cache/specmatic-tests.json based on file content hashes. Unchanged contracts are automatically skipped on subsequent runs. Use --force to bypass cache.

+ +

Output:

+ +
    +
  • ✓ Test suite generated with path to output directory
    • +
  • Instructions to run the generated tests
    • +
  • Summary when generating tests for multiple contracts
    • +
+ +

What to Do With Generated Tests:

+ +

The generated tests are executable contract tests that validate your API implementation against the OpenAPI/AsyncAPI specification. Here’s how to use them:

+ +
    +
  1. +

    Generate tests (you just did this):

    + + 
    specfact spec generate-tests --bundle my-api --output tests/contract/
+
    +
    2. +
  2. +

    Start your API server:

    + + 
    python -m uvicorn main:app --port 8000
+
    +
    3. +
  3. +

    Run tests against your API:

    + + 
    specmatic test \
+  --spec .specfact/projects/my-api/contracts/api.openapi.yaml \
+  --host http://localhost:8000
+
    +
    4. +
  4. +

    Tests validate:

    +
      +
    • Request format matches spec (headers, body, query params)
      • +
    • Response format matches spec (status codes, headers, body schema)
      • +
    • All endpoints are implemented
      • +
    • Data types and constraints are respected
      • +
    +
    5. +
+ +

CI/CD Integration:

+ +
- name: Generate contract tests
+  run: specfact spec generate-tests --bundle my-api --output tests/contract/
+
+- name: Start API server
+  run: python -m uvicorn main:app --port 8000 &
+
+- name: Run contract tests
+  run: specmatic test --spec ... --host http://localhost:8000
+
+ +

See Specmatic Integration Guide for complete walkthrough.

+ +

spec mock

+ +

Launch Specmatic mock server from specification. Can use a single spec file or select from bundle contracts.

+ +
specfact spec mock [OPTIONS]
+
+ +

Options:

+ +
    +
  • --spec PATH - Path to OpenAPI/AsyncAPI specification (default: auto-detect from current directory)
    • +
  • --bundle NAME - Project bundle name (e.g., legacy-api). If provided, selects contract from bundle. Default: active plan from ‘specfact plan select’
    • +
  • --port INT - Port number for mock server (default: 9000)
    • +
  • --strict/--examples - Use strict validation mode or examples mode (default: strict)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation). Uses first contract if multiple available.
    • +
+ +

Examples:

+ +
# Auto-detect spec file from current directory
+specfact spec mock
+
+# Specify spec file and port
+specfact spec mock --spec api/openapi.yaml --port 9000
+
+# Use examples mode (less strict)
+specfact spec mock --spec api/openapi.yaml --examples
+
+# Select contract from active bundle (interactive)
+specfact spec mock --bundle legacy-api
+
+# Use specific bundle (non-interactive, uses first contract)
+specfact spec mock --bundle legacy-api --no-interactive
+
+ +

CLI-First Pattern: Uses active plan as default, or specify --bundle. Interactive selection when multiple contracts available.

+ +

Features:

+ +
    +
  • Serves API endpoints based on specification
    • +
  • Validates requests against spec
    • +
  • Returns example responses
    • +
  • Press Ctrl+C to stop
    • +
+ +

Common locations for auto-detection:

+ +
    +
  • openapi.yaml, openapi.yml, openapi.json
    • +
  • asyncapi.yaml, asyncapi.yml, asyncapi.json
    • +
  • api/openapi.yaml
    • +
  • specs/openapi.yaml
    • +
+ +

Integration:

+ +

The spec commands are automatically integrated into:

+ +
    +
  • import from-code - Auto-validates OpenAPI/AsyncAPI specs after import
    • +
  • enforce sdd - Validates API specs during SDD enforcement
    • +
  • sync bridge and sync repository - Auto-validates specs after sync
    • +
+ +

See Specmatic Integration Guide for detailed documentation.

+ +
+ +
+ +

sdd constitution - Manage Project Constitutions (Spec-Kit Compatibility)

+ +

Note: Constitution management commands are part of the sdd (Spec-Driven Development) command group. The specfact bridge command group has been removed in v0.22.0 as part of the bridge adapter refactoring. Bridge adapters are now internal connectors accessed via specfact sync bridge --adapter <adapter-name>, not user-facing commands.

+ +

Manage project constitutions for Spec-Kit format compatibility. Auto-generate bootstrap templates from repository analysis.

+ +

Note: These commands are for Spec-Kit format compatibility only. SpecFact itself uses modular project bundles (.specfact/projects/<bundle-name>/) and protocols (.specfact/protocols/*.protocol.yaml) for internal operations. Constitutions are only needed when:

+ +
    +
  • +

    Syncing with Spec-Kit artifacts (specfact sync bridge --adapter speckit)

    +
    • +
  • +

    Working in Spec-Kit format (using /speckit.* commands)

    +
    • +
  • +

    Migrating from Spec-Kit to SpecFact format

    +
    • +
+ +

If you’re using SpecFact standalone (without Spec-Kit), you don’t need constitutions - use specfact plan commands instead.

+ +

⚠️ Breaking Change: The specfact bridge constitution command has been moved to specfact sdd constitution as part of the bridge adapter refactoring. Please update your scripts and workflows.

+ +
sdd constitution bootstrap
+ +

Generate bootstrap constitution from repository analysis:

+ +
specfact sdd constitution bootstrap [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Repository path (default: current directory)
    • +
  • --out PATH - Output path for constitution (default: .specify/memory/constitution.md)
    • +
  • --overwrite - Overwrite existing constitution if it exists
    • +
+ +

Example:

+ +
# Generate bootstrap constitution
+specfact sdd constitution bootstrap --repo .
+
+# Generate with custom output path
+specfact sdd constitution bootstrap --repo . --out custom-constitution.md
+
+# Overwrite existing constitution
+specfact sdd constitution bootstrap --repo . --overwrite
+
+ +

What it does:

+ +
    +
  • Analyzes repository context (README.md, pyproject.toml, .cursor/rules/, docs/rules/)
    • +
  • Extracts project metadata (name, description, technology stack)
    • +
  • Extracts development principles from rule files
    • +
  • Generates bootstrap constitution template with: +
      +
    • Project name and description
      • +
    • Core principles (extracted from repository)
      • +
    • Development workflow guidelines
      • +
    • Quality standards
      • +
    • Governance rules
      • +
    +
    • +
  • Creates constitution at .specify/memory/constitution.md (Spec-Kit convention)
    • +
+ +

When to use:

+ +
    +
  • Spec-Kit sync operations: Required before specfact sync bridge --adapter speckit (bidirectional sync)
    • +
  • Spec-Kit format projects: When working with Spec-Kit artifacts (using /speckit.* commands)
    • +
  • After brownfield import (if syncing to Spec-Kit): Run specfact import from-code → Suggested automatically if Spec-Kit sync is planned
    • +
  • Manual setup: Generate constitution for new Spec-Kit projects
    • +
+ +

Note: If you’re using SpecFact standalone (without Spec-Kit), you don’t need constitutions. Use specfact plan commands instead for plan management.

+ +

Integration:

+ +
    +
  • Auto-suggested during specfact import from-code (brownfield imports)
    • +
  • Auto-detected during specfact sync bridge --adapter speckit (if constitution is minimal)
    • +
+ +
+ +
sdd constitution enrich
+ +

Auto-enrich existing constitution with repository context (Spec-Kit format):

+ +
specfact sdd constitution enrich [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Repository path (default: current directory)
    • +
  • --constitution PATH - Path to constitution file (default: .specify/memory/constitution.md)
    • +
+ +

Example:

+ +
# Enrich existing constitution
+specfact sdd constitution enrich --repo .
+
+# Enrich specific constitution file
+specfact sdd constitution enrich --repo . --constitution custom-constitution.md
+
+ +

What it does:

+ +
    +
  • Analyzes repository context (same as bootstrap)
    • +
  • Fills remaining placeholders in existing constitution
    • +
  • Adds additional principles extracted from repository
    • +
  • Updates workflow and quality standards sections
    • +
+ +

When to use:

+ +
    +
  • Constitution has placeholders that need filling
    • +
  • Repository context has changed (new rules, updated README)
    • +
  • Manual constitution needs enrichment with repository details
    • +
+ +
+ +
sdd constitution validate
+ +

Validate constitution completeness (Spec-Kit format):

+ +
specfact sdd constitution validate [OPTIONS]
+
+ +

Options:

+ +
    +
  • --constitution PATH - Path to constitution file (default: .specify/memory/constitution.md)
    • +
+ +

Example:

+ +
# Validate default constitution
+specfact sdd constitution validate
+
+# Validate specific constitution file
+specfact sdd constitution validate --constitution custom-constitution.md
+
+ +

What it checks:

+ +
    +
  • Constitution exists and is not empty
    • +
  • No unresolved placeholders remain
    • +
  • Has “Core Principles” section
    • +
  • Has at least one numbered principle
    • +
  • Has “Governance” section
    • +
  • Has version and ratification date
    • +
+ +

Output:

+ +
    +
  • ✅ Valid: Constitution is complete and ready for use
    • +
  • ❌ Invalid: Lists specific issues found (placeholders, missing sections, etc.)
    • +
+ +

When to use:

+ +
    +
  • Before syncing with Spec-Kit (specfact sync bridge --adapter speckit requires valid constitution)
    • +
  • After manual edits to verify completeness
    • +
  • In CI/CD pipelines to ensure constitution quality
    • +
+ +
+ +
+ +
+ +

Note: The specfact constitution command has been moved to specfact sdd constitution. See the sdd constitution section above for complete documentation.

+ +

Migration: Replace specfact constitution <command> or specfact bridge constitution <command> with specfact sdd constitution <command>.

+ +

Example Migration:

+ +
    +
  • specfact constitution bootstrap → specfact sdd constitution bootstrap
    • +
  • specfact bridge constitution bootstrap → specfact sdd constitution bootstrap
    • +
  • specfact constitution enrich → specfact sdd constitution enrich
    • +
  • specfact bridge constitution enrich → specfact sdd constitution enrich
    • +
  • specfact constitution validate → specfact sdd constitution validate
    • +
  • specfact bridge constitution validate → specfact sdd constitution validate
    • +
+ +
+ +

migrate - Migration Helpers

+ +

Helper commands for migrating legacy artifacts and cleaning up deprecated structures.

+ +

migrate cleanup-legacy

+ +

Remove empty legacy top-level directories (Phase 8.5 cleanup).

+ +
specfact migrate cleanup-legacy [OPTIONS]
+
+ +

Purpose:

+ +

Removes legacy directories that are no longer created by newer SpecFact versions:

+ +
    +
  • .specfact/plans/ (deprecated: no monolithic bundles, active bundle config moved to config.yaml)
    • +
  • .specfact/contracts/ (now bundle-specific: .specfact/projects/<bundle-name>/contracts/)
    • +
  • .specfact/protocols/ (now bundle-specific: .specfact/projects/<bundle-name>/protocols/)
    • +
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
  • --dry-run - Show what would be removed without actually removing
    • +
  • --force - Remove directories even if they contain files (default: only removes empty directories)
    • +
+ +

Examples:

+ +
# Preview what would be removed
+specfact migrate cleanup-legacy --dry-run
+
+# Remove empty legacy directories
+specfact migrate cleanup-legacy
+
+# Force removal even if directories contain files
+specfact migrate cleanup-legacy --force
+
+ +

Safety:

+ +

By default, the command only removes empty directories. Use --force to remove directories containing files (use with caution).

+ +
+ +

migrate to-contracts

+ +

Migrate legacy bundles to contract-centric structure.

+ +
specfact migrate to-contracts [BUNDLE] [OPTIONS]
+
+ +

Purpose:

+ +

Converts legacy plan bundles to the new contract-centric structure, extracting OpenAPI contracts from verbose acceptance criteria and validating with Specmatic.

+ +

Arguments:

+ +
    +
  • BUNDLE - Project bundle name. Default: active plan from specfact plan select
    • +
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
  • --extract-openapi/--no-extract-openapi - Extract OpenAPI contracts from verbose acceptance criteria (default: enabled)
    • +
  • --validate-with-specmatic/--no-validate-with-specmatic - Validate generated contracts with Specmatic (default: enabled)
    • +
  • --dry-run - Preview changes without writing
    • +
  • --no-interactive - Non-interactive mode
    • +
+ +

Examples:

+ +
# Migrate bundle to contract-centric structure
+specfact migrate to-contracts legacy-api
+
+# Preview migration without writing
+specfact migrate to-contracts legacy-api --dry-run
+
+# Skip OpenAPI extraction
+specfact migrate to-contracts legacy-api --no-extract-openapi
+
+ +

What it does:

+ +
    +
  1. Scans acceptance criteria for API-related patterns
    2. +
  2. Extracts OpenAPI contract definitions
    3. +
  3. Creates contract files in bundle-specific location
    4. +
  4. Validates contracts with Specmatic (if available)
    5. +
  5. Updates bundle manifest with contract references
    6. +
+ +
+ +

migrate artifacts

+ +

Migrate artifacts between bundle versions or locations.

+ +
specfact migrate artifacts [BUNDLE] [OPTIONS]
+
+ +

Purpose:

+ +

Migrates artifacts (reports, contracts, SDDs) from legacy locations to the current bundle-specific structure.

+ +

Arguments:

+ +
    +
  • BUNDLE - Project bundle name. If not specified, migrates artifacts for all bundles found in .specfact/projects/
    • +
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
  • --dry-run - Show what would be migrated without actually migrating
    • +
  • --backup/--no-backup - Create backups of original files (default: enabled)
    • +
+ +

Examples:

+ +
# Migrate artifacts for specific bundle
+specfact migrate artifacts legacy-api
+
+# Migrate artifacts for all bundles
+specfact migrate artifacts
+
+# Preview migration
+specfact migrate artifacts legacy-api --dry-run
+
+# Skip backups (faster, but no rollback)
+specfact migrate artifacts legacy-api --no-backup
+
+ +

What it migrates:

+ +
    +
  • Reports from legacy locations to .specfact/projects/<bundle>/reports/
    • +
  • Contracts from root-level to bundle-specific locations
    • +
  • SDD manifests from legacy paths to bundle-specific paths
    • +
+ +
+ +

sdd - SDD Manifest Utilities

+ +

Utilities for working with SDD (Software Design Document) manifests.

+ +

sdd list

+ +

List all SDD manifests in the repository.

+ +
specfact sdd list [OPTIONS]
+
+ +

Purpose:

+ +

Shows all SDD manifests found in the repository, including:

+ +
    +
  • Bundle-specific locations (.specfact/projects/<bundle-name>/sdd.yaml, Phase 8.5)
    • +
  • Legacy multi-SDD layout (.specfact/sdd/*.yaml)
    • +
  • Legacy single-SDD layout (.specfact/sdd.yaml)
    • +
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# List all SDD manifests
+specfact sdd list
+
+# List SDDs in specific repository
+specfact sdd list --repo /path/to/repo
+
+ +

Output:

+ +

Displays a table with:

+ +
    +
  • Path: Location of the SDD manifest
    • +
  • Bundle: Associated bundle name (if applicable)
    • +
  • Version: SDD schema version
    • +
  • Features: Number of features defined
    • +
+ +

Use Cases:

+ +
    +
  • Discover existing SDD manifests in a repository
    • +
  • Verify SDD locations after migration
    • +
  • Debug SDD-related issues
    • +
+ +
+ +

implement - Removed Task Execution

+ +
+

⚠️ REMOVED in v0.22.0: The implement command group has been removed. Per SPECFACT_0x_TO_1x_BRIDGE_PLAN.md, SpecFact CLI does not create plan → feature → task (that’s the job for spec-kit, openspec, etc.). We complement those SDD tools to enforce tests and quality. Use the AI IDE bridge commands (specfact generate fix-prompt, specfact generate test-prompt, etc.) instead.

+
+ +

implement tasks (Removed)

+ +

Direct task execution was removed in v0.22.0. Use AI IDE bridge workflows instead.

+ +
# DEPRECATED - Do not use for new projects
+specfact implement tasks [OPTIONS]
+
+ +

Migration Guide:

+ +

Replace implement tasks with the new AI IDE bridge workflow:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Old CommandNew Workflow
specfact implement tasks1. specfact generate fix-prompt GAP-ID
 2. Copy prompt to AI IDE
 3. AI IDE provides the implementation
 4. specfact enforce sdd to validate
+ +

Why Deprecated:

+ +
    +
  • AI IDE integration provides better context awareness
    • +
  • Human-in-the-loop validation before code changes
    • +
  • Works with any AI IDE (Cursor, Copilot, Claude, etc.)
    • +
  • More reliable and controllable than direct code generation
    • +
+ +

Recommended Replacements:

+ +
    +
  • Fix gaps: specfact generate fix-prompt
    • +
  • Add tests: specfact generate test-prompt
    • +
  • Add contracts: specfact generate contracts-prompt
    • +
+ +
+

⚠️ REMOVED in v0.22.0: The specfact generate tasks command has been removed. Per SPECFACT_0x_TO_1x_BRIDGE_PLAN.md, SpecFact CLI does not create plan → feature → task (that’s the job for spec-kit, openspec, etc.). We complement those SDD tools to enforce tests and quality.

+
+ +

See: Migration Guide (0.16 to 0.19) for detailed migration instructions.

+ +
+ +

init - Initialize IDE Integration

+ +

Set up SpecFact CLI for IDE integration by copying prompt templates to IDE-specific locations.

+ +
specfact init [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Repository path (default: current directory)
    • +
  • --force - Overwrite existing files
    • +
  • --install-deps - Install required packages for contract enhancement (beartype, icontract, crosshair-tool, pytest) via pip
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --ide TEXT - IDE type (auto, cursor, vscode, copilot, claude, gemini, qwen, opencode, windsurf, kilocode, auggie, roo, codebuddy, amp, q) (default: auto)
    • +
+ +

Examples:

+ +
# Auto-detect IDE
+specfact init
+
+# Specify IDE explicitly
+specfact init --ide cursor
+specfact init --ide vscode
+specfact init --ide copilot
+
+# Force overwrite existing files
+specfact init --ide cursor --force
+
+# Install required packages for contract enhancement
+specfact init --install-deps
+
+# Initialize IDE integration and install dependencies
+specfact init --ide cursor --install-deps
+
+ +

What it does:

+ +
    +
  1. Detects your IDE (or uses --ide flag)
    2. +
  2. Copies prompt templates from resources/prompts/ to IDE-specific location at the repository root level
    3. +
  3. Creates/updates VS Code settings.json if needed (for VS Code/Copilot)
    4. +
  4. Makes slash commands available in your IDE
    5. +
  5. Optionally installs required packages for contract enhancement (if --install-deps is provided): +
      +
    • beartype>=0.22.4 - Runtime type checking
      • +
    • icontract>=2.7.1 - Design-by-contract decorators
      • +
    • crosshair-tool>=0.0.97 - Contract exploration
      • +
    • pytest>=8.4.2 - Testing framework
      • +
    +
    6. +
+ +

Important: Templates are always copied to the repository root level (where .github/, .cursor/, etc. directories must reside for IDE recognition). The --repo parameter specifies the repository root path. For multi-project codebases, run specfact init from the repository root to ensure IDE integration works correctly.

+ +

IDE-Specific Locations:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDEDirectoryFormat
Cursor.cursor/commands/Markdown
VS Code / Copilot.github/prompts/.prompt.md
Claude Code.claude/commands/Markdown
Gemini.gemini/commands/TOML
Qwen.qwen/commands/TOML
And more…See IDE Integration GuideMarkdown
+ +

See IDE Integration Guide for detailed setup instructions and all supported IDEs.

+ +
+ +

IDE Integration (Slash Commands)

+ +

Slash commands provide an intuitive interface for IDE integration (VS Code, Cursor, GitHub Copilot, etc.).

+ +

Available Slash Commands

+ +

Core Workflow Commands (numbered for workflow ordering):

+ +
    +
  1. /specfact.01-import [args] - Import codebase into plan bundle (replaces specfact-import-from-code)
    2. +
  2. /specfact.02-plan [args] - Plan management: init, add-feature, add-story, update-idea, update-feature, update-story (replaces specfact-plan-init, specfact-plan-add-feature, specfact-plan-add-story, specfact-plan-update-idea, specfact-plan-update-feature)
    3. +
  3. /specfact.03-review [args] - Review plan and promote (replaces specfact-plan-review, specfact-plan-promote)
    4. +
  4. /specfact.04-sdd [args] - Create SDD manifest (new, based on plan harden)
    5. +
  5. /specfact.05-enforce [args] - SDD enforcement (replaces specfact-enforce)
    6. +
  6. /specfact.06-sync [args] - Sync operations (replaces specfact-sync)
    7. +
  7. /specfact.07-contracts [args] - Contract enhancement workflow: analyze → generate prompts → apply contracts sequentially
    8. +
+ +

Advanced Commands (no numbering):

+ +
    +
  • /specfact.compare [args] - Compare plans (replaces specfact-plan-compare)
    • +
  • /specfact.validate [args] - Validation suite (replaces specfact-repro)
    • +
  • /specfact.generate-contracts-prompt [args] - Generate AI IDE prompt for adding contracts (see generate contracts-prompt)
    • +
+ +

Setup

+ +
# Initialize IDE integration (one-time setup)
+specfact init --ide cursor
+
+# Or auto-detect IDE
+specfact init
+
+# Initialize and install required packages for contract enhancement
+specfact init --install-deps
+
+# Initialize for specific IDE and install dependencies
+specfact init --ide cursor --install-deps
+
+ +

Usage

+ +

After initialization, use slash commands directly in your IDE’s AI chat:

+ +
# In IDE chat (Cursor, VS Code, Copilot, etc.)
+# Core workflow (numbered for natural progression)
+/specfact.01-import legacy-api --repo .
+/specfact.02-plan init legacy-api
+/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth"
+/specfact.03-review legacy-api
+/specfact.04-sdd legacy-api
+/specfact.05-enforce legacy-api
+/specfact.06-sync --repo . --adapter speckit
+/specfact.07-contracts legacy-api --apply all-contracts  # Analyze, generate prompts, apply contracts sequentially
+
+# Advanced commands
+/specfact.compare --bundle legacy-api
+/specfact.validate --repo .
+
+ +

How it works:

+ +

Slash commands are prompt templates (markdown files) that are copied to IDE-specific locations by specfact init. The IDE automatically discovers and registers them as slash commands.

+ +

See IDE Integration Guide for detailed setup instructions and supported IDEs.

+ +
+ +

Environment Variables

+ +
    +
  • SPECFACT_CONFIG - Path to config file (default: .specfact/config.yaml)
    • +
  • SPECFACT_VERBOSE - Enable verbose output (0/1)
    • +
  • SPECFACT_NO_COLOR - Disable colored output (0/1)
    • +
  • SPECFACT_MODE - Operational mode (cicd or copilot)
    • +
  • COPILOT_API_URL - CoPilot API endpoint (for CoPilot mode detection)
    • +
+ +
+ +

Configuration File

+ +

Create .specfact.yaml in project root:

+ +
version: "1.0"
+
+# Enforcement settings
+enforcement:
+  preset: balanced
+  custom_rules: []
+
+# Analysis settings
+analysis:
+  confidence_threshold: 0.7
+  include_tests: true
+  exclude_patterns:
+    - "**/__pycache__/**"
+    - "**/node_modules/**"
+
+# Import settings
+import:
+  default_branch: feat/specfact-migration
+  preserve_history: true
+
+# Repro settings
+repro:
+  budget: 120
+  parallel: true
+  fail_fast: false
+
+ +
+ +

Exit Codes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeMeaning
0Success
1Validation/enforcement failed
2Time budget exceeded
3Configuration error
4File not found
5Invalid arguments
+ +
+ +

Shell Completion

+ +

SpecFact CLI supports native shell completion for bash, zsh, and fish without requiring any extensions. Completion works automatically once installed.

+ +

Quick Install

+ +

Use Typer’s built-in completion commands:

+ +
# Auto-detect shell and install (recommended)
+specfact --install-completion
+
+# Explicitly specify shell
+specfact --install-completion bash   # or zsh, fish
+
+ +

Show Completion Script

+ +

To view the completion script without installing:

+ +
# Auto-detect shell
+specfact --show-completion
+
+# Explicitly specify shell
+specfact --show-completion bash
+
+ +

Manual Installation

+ +

You can also manually add completion to your shell config:

+ +

Bash

+ +
# Add to ~/.bashrc
+eval "$(_SPECFACT_COMPLETE=bash_source specfact)"
+
+ +

Zsh

+ +
# Add to ~/.zshrc
+eval "$(_SPECFACT_COMPLETE=zsh_source specfact)"
+
+ +

Fish

+ +
# Add to ~/.config/fish/config.fish
+eval (env _SPECFACT_COMPLETE=fish_source specfact)
+
+ +

PowerShell

+ +

PowerShell completion requires the click-pwsh extension:

+ +
pip install click-pwsh
+python -m click_pwsh install specfact
+
+ +

Ubuntu/Debian Notes

+ +

On Ubuntu and Debian systems, /bin/sh points to dash instead of bash. SpecFact CLI automatically normalizes shell detection to use bash for completion, so auto-detection works correctly even on these systems.

+ +

If you encounter “Shell sh not supported” errors, explicitly specify the shell:

+ +
specfact --install-completion bash
+
+ +
+ + + + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/reference/feature-keys.md b/_site_local/reference/feature-keys.md new file mode 100644 index 0000000..c97005c --- /dev/null +++ b/_site_local/reference/feature-keys.md @@ -0,0 +1,250 @@ +# Feature Key Normalization + +Reference documentation for feature key formats and normalization in SpecFact CLI. + +## Overview + +SpecFact CLI supports multiple feature key formats to accommodate different use cases and historical plans. The normalization system ensures consistent comparison and merging across different formats. + +## Supported Key Formats + +### 1. Classname Format (Default) + +**Format**: `FEATURE-CLASSNAME` + +**Example**: `FEATURE-CONTRACTFIRSTTESTMANAGER` + +**Use case**: Auto-derived plans from brownfield analysis + +**Generation**: + +```bash +specfact import from-code --key-format classname +``` + +### 2. Sequential Format + +**Format**: `FEATURE-001`, `FEATURE-002`, `FEATURE-003`, ... + +**Example**: `FEATURE-001` + +**Use case**: Manual plans and greenfield development + +**Generation**: + +```bash +specfact import from-code --key-format sequential +``` + +**Manual creation**: When creating plans interactively, use `FEATURE-001` format: + +```bash +specfact plan init +# Enter feature key: FEATURE-001 +``` + +### 3. Underscore Format (Legacy) + +**Format**: `000_FEATURE_NAME` or `001_FEATURE_NAME` + +**Example**: `000_CONTRACT_FIRST_TEST_MANAGER` + +**Use case**: Legacy plans or plans imported from other systems + +**Note**: This format is supported for comparison but not generated by the analyzer. + +## Normalization + +The normalization system automatically handles different formats when comparing plans: + +### How It Works + +1. **Normalize keys**: Remove prefixes (`FEATURE-`, `000_`) and underscores +2. **Compare**: Match features by normalized key +3. **Display**: Show original keys in reports + +### Example + +```python +from specfact_cli.utils.feature_keys import normalize_feature_key + +# These all normalize to the same key: +normalize_feature_key("000_CONTRACT_FIRST_TEST_MANAGER") +# → "CONTRACTFIRSTTESTMANAGER" + +normalize_feature_key("FEATURE-CONTRACTFIRSTTESTMANAGER") +# → "CONTRACTFIRSTTESTMANAGER" + +normalize_feature_key("FEATURE-001") +# → "001" +``` + +## Automatic Normalization + +### Plan Comparison + +The `plan compare` command automatically normalizes keys: + +```bash +specfact plan compare --manual main.bundle.yaml --auto auto-derived.yaml +``` + +**Behavior**: Features with different key formats but the same normalized key are matched correctly. + +### Plan Merging + +When merging plans (e.g., via `sync bridge --adapter speckit`), normalization ensures features are matched correctly: + +```bash +specfact sync bridge --adapter speckit --bundle --bidirectional +``` + +**Behavior**: Features are matched by normalized key, not exact key format. + +## Converting Key Formats + +### Using Python Utilities + +```python +from specfact_cli.utils.feature_keys import ( + convert_feature_keys, + to_sequential_key, + to_classname_key, +) + +# Convert to sequential format +features_seq = convert_feature_keys(features, target_format="sequential", start_index=1) + +# Convert to classname format +features_class = convert_feature_keys(features, target_format="classname") +``` + +### Command-Line (Future) + +A `plan normalize` command may be added in the future to convert existing plans: + +```bash +# (Future) Convert plan to sequential format +specfact plan normalize --from main.bundle.yaml --to main-sequential.yaml --output-format sequential +``` + +## Best Practices + +### 1. Choose a Consistent Format + +**Recommendation**: Use **sequential format** (`FEATURE-001`) for new plans: + +- ✅ Easy to reference in documentation +- ✅ Clear ordering +- ✅ Standard format for greenfield plans + +**Auto-derived plans**: Use **classname format** (`FEATURE-CLASSNAME`): + +- ✅ Directly maps to codebase classes +- ✅ Self-documenting +- ✅ Easy to trace back to source code + +### 2. Don't Worry About Format Differences + +**Key insight**: The normalization system handles format differences automatically: + +- ✅ Comparison works across formats +- ✅ Merging works across formats +- ✅ Reports show original keys + +**Action**: Choose the format that fits your workflow; the system handles the rest. + +### 3. Use Sequential for Manual Plans + +When creating plans manually or interactively: + +```bash +specfact plan init +# Enter feature key: FEATURE-001 # ← Use sequential format +# Enter feature title: User Authentication +``` + +**Why**: Sequential format is easier to reference and understand in documentation. + +### 4. Let Analyzer Use Classname Format + +When analyzing existing codebases: + +```bash +specfact import from-code --key-format classname # ← Default, explicit for clarity +``` + +**Why**: Classname format directly maps to codebase structure, making it easy to trace features back to classes. + +## Migration Guide + +### Converting Existing Plans + +If you have a plan with `000_FEATURE_NAME` format and want to convert: + +1. **Load the plan**: + + ```python + from specfact_cli.utils import load_yaml + from specfact_cli.utils.feature_keys import convert_feature_keys + + plan_data = load_yaml("main.bundle.yaml") + features = plan_data["features"] + ``` + +2. **Convert to sequential**: + + ```python + converted = convert_feature_keys(features, target_format="sequential", start_index=1) + plan_data["features"] = converted + ``` + +3. **Save the plan**: + + ```python + from specfact_cli.utils import dump_yaml + + dump_yaml(plan_data, "main-sequential.yaml") + ``` + +### Recommended Migration + +**For existing plans**: Keep the current format; normalization handles comparison automatically. + +**For new plans**: Use sequential format (`FEATURE-001`) for consistency. + +## Troubleshooting + +### Feature Not Matching Between Plans + +**Issue**: Features appear as "missing" even though they exist in both plans. + +**Solution**: Check if keys normalize to the same value: + +```python +from specfact_cli.utils.feature_keys import normalize_feature_key + +key1 = "000_CONTRACT_FIRST_TEST_MANAGER" +key2 = "FEATURE-CONTRACTFIRSTTESTMANAGER" + +print(normalize_feature_key(key1)) # Should match +print(normalize_feature_key(key2)) # Should match +``` + +### Key Format Not Recognized + +**Issue**: Key format doesn't match expected patterns. + +**Solution**: The normalization system is flexible and handles variations: + +- `FEATURE-XXX` → normalized +- `000_XXX` → normalized +- `XXX` → normalized (no prefix) + +**Note**: If normalization fails, check the key manually for special characters or unusual formats. + +## See Also + +- [Brownfield Analysis](../guides/use-cases.md#use-case-2-brownfield-code-hardening) - Explains why different formats exist +- [Plan Comparison](../reference/commands.md#plan-compare) - How comparison works with normalization +- [Plan Sync](../reference/commands.md#sync) - How sync handles different formats diff --git a/_site_local/reference/index.html b/_site_local/reference/index.html new file mode 100644 index 0000000..7a2f1a0 --- /dev/null +++ b/_site_local/reference/index.html @@ -0,0 +1,272 @@ + + + + + + + +Reference Documentation | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Reference Documentation

+ +

Complete technical reference for SpecFact CLI.

+ +

Available References

+ + + +

Quick Reference

+ +

Commands

+ +
    +
  • specfact import from-bridge --adapter speckit - Import from external tools via bridge adapter
    • +
  • specfact import from-code <bundle-name> - Reverse-engineer plans from code
    • +
  • specfact plan init <bundle-name> - Initialize new development plan
    • +
  • specfact plan compare - Compare manual vs auto plans
    • +
  • specfact enforce stage - Configure quality gates
    • +
  • specfact repro - Run full validation suite
    • +
  • specfact sync bridge --adapter <adapter> --bundle <bundle-name> - Sync with external tools via bridge adapter
    • +
  • specfact spec validate [--bundle <name>] - Validate OpenAPI/AsyncAPI specifications
    • +
  • specfact spec generate-tests [--bundle <name>] - Generate contract tests from specifications
    • +
  • specfact spec mock [--bundle <name>] - Launch mock server for development
    • +
  • specfact init - Initialize IDE integration
    • +
+ +

Modes

+ +
    +
  • CI/CD Mode - Fast, deterministic execution
    • +
  • CoPilot Mode - Enhanced prompts with context injection
    • +
+ +

IDE Integration

+ + + +

Technical Details

+ + + + + + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/reference/parameter-standard.md b/_site_local/reference/parameter-standard.md new file mode 100644 index 0000000..1462839 --- /dev/null +++ b/_site_local/reference/parameter-standard.md @@ -0,0 +1,246 @@ +# Parameter Standard + +**Date**: 2025-11-26 +**Status**: Active +**Purpose**: Standardize parameter names and grouping across all SpecFact CLI commands + +--- + +## 📋 Overview + +This document defines the standard parameter names, groupings, and conventions for all SpecFact CLI commands. All commands must follow these standards for consistency and improved user experience. + +--- + +## 🎯 Parameter Naming Conventions + +### Standard Parameter Names + +| Concept | Standard Name | Deprecated Names | Notes | +|---------|--------------|------------------|-------| +| Repository path | `--repo` | `--base-path` | Use `--repo` for repository root path | +| Output file path | `--out` | `--output` | Use `--out` for output file paths | +| Output format | `--output-format` | `--format` | Use `--output-format` for format specification | +| Interactive mode | `--interactive/--no-interactive` | `--non-interactive` | Use `--interactive/--no-interactive` for mode control | +| Project bundle | `--bundle` | `--name`, `--plan` (when used for bundle name) | Use `--bundle` for project bundle name | +| Plan bundle path | `--plan` | N/A | Use `--plan` for plan bundle file/directory path | +| SDD manifest path | `--sdd` | N/A | Use `--sdd` for SDD manifest file path | + +### Deprecation Policy + +- **Transition Period**: 3 months from implementation date +- **Deprecation Warnings**: Commands using deprecated names will show warnings +- **Removal**: Deprecated names will be removed after transition period +- **Documentation**: All examples and docs updated immediately + +--- + +## 📊 Parameter Grouping + +Parameters must be organized into logical groups in the following order: + +### Group 1: Target/Input (Required) + +**Purpose**: What to operate on + +**Parameters**: + +- `--bundle NAME` - Project bundle name (required for modular structure) +- `--repo PATH` - Repository path (default: ".") +- `--plan PATH` - Plan bundle path (default: active plan for bundle) +- `--sdd PATH` - SDD manifest path (default: bundle-specific .specfact/projects//sdd.yaml, Phase 8.5, with fallback to legacy .specfact/sdd/.yaml) +- `--constitution PATH` - Constitution path (default: .specify/memory/constitution.md) + +**Help Text Format**: + +```python +# Target/Input +--bundle NAME # Project bundle name (required) +--repo PATH # Repository path (default: ".") +--plan PATH # Plan bundle path (default: active plan for bundle) +``` + +### Group 2: Output/Results + +**Purpose**: Where to write results + +**Parameters**: + +- `--out PATH` - Output file path (default: auto-generated) +- `--report PATH` - Report file path (default: auto-generated) +- `--output-format FMT` - Output format: yaml, json, markdown (default: yaml) + +**Help Text Format**: + +```python +# Output/Results +--out PATH # Output file path (default: auto-generated) +--report PATH # Report file path (default: auto-generated) +--output-format FMT # Output format: yaml, json, markdown (default: yaml) +``` + +### Group 3: Behavior/Options + +**Purpose**: How to operate + +**Parameters**: + +- `--interactive/--no-interactive` - Interactive mode (default: auto-detect) +- `--force` - Overwrite existing files +- `--dry-run` - Preview without writing +- `--verbose` - Verbose output +- `--shadow-only` - Observe without enforcing + +**Help Text Format**: + +```python +# Behavior/Options +--interactive # Interactive mode (default: auto-detect) +--no-interactive # Non-interactive mode (for CI/CD) +--force # Overwrite existing files +--dry-run # Preview without writing +--verbose # Verbose output +``` + +### Group 4: Advanced/Configuration + +**Purpose**: Advanced settings and configuration + +**Parameters**: + +- `--confidence FLOAT` - Confidence threshold: 0.0-1.0 (default: 0.5) +- `--budget SECONDS` - Time budget in seconds (default: 120) +- `--preset PRESET` - Enforcement preset: minimal, balanced, strict (default: balanced) +- `--max-questions INT` - Maximum questions per session (default: 5) + +**Help Text Format**: + +```python +# Advanced/Configuration +--confidence FLOAT # Confidence threshold: 0.0-1.0 (default: 0.5) +--budget SECONDS # Time budget in seconds (default: 120) +--preset PRESET # Enforcement preset: minimal, balanced, strict (default: balanced) +``` + +--- + +## 🔄 Parameter Changes Required + +### Phase 1.2: Rename Inconsistent Parameters ✅ **COMPLETED** + +The following parameters have been renamed: + +1. **`--base-path` → `--repo`** ✅ + - **File**: `src/specfact_cli/commands/generate.py` + - **Command**: `generate contracts` + - **Status**: Completed - Parameter renamed and all references updated + +2. **`--output` → `--out`** ✅ + - **File**: `src/specfact_cli/commands/constitution.py` + - **Command**: `constitution bootstrap` + - **Status**: Completed - Parameter renamed and all references updated + +3. **`--format` → `--output-format`** ✅ + - **Files**: + - `src/specfact_cli/commands/plan.py` (plan compare command) + - `src/specfact_cli/commands/enforce.py` (enforce sdd command) + - **Status**: Completed - Parameters renamed and all references updated + +4. **`--non-interactive` → `--no-interactive`** ✅ + - **Files**: + - `src/specfact_cli/cli.py` (global flag) + - `src/specfact_cli/commands/plan.py` (multiple commands) + - `src/specfact_cli/commands/enforce.py` (enforce sdd command) + - `src/specfact_cli/commands/generate.py` (generate contracts command) + - **Status**: Completed - Global flag and all command flags updated, interaction logic fixed + +### Phase 1.3: Verify `--bundle` Parameter ✅ **COMPLETED** + +**Commands with `--bundle` Parameter**: + +| Command | Parameter Type | Status | Notes | +|---------|---------------|--------|-------| +| `plan init` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `plan review` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `plan promote` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `plan harden` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `enforce sdd` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `import from-code` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `plan add-feature` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` with validation | +| `plan add-story` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` with validation | +| `plan update-idea` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` with validation | +| `plan update-feature` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` with validation | +| `plan update-story` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` with validation | +| `plan compare` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` - Added for consistency | +| `generate contracts` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` - Added, prioritizes bundle over plan/sdd | +| `sync bridge` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` - Auto-detects if not provided | + +**Validation Improvements**: + +- ✅ Enhanced `_find_bundle_dir()` function with better error messages +- ✅ Lists available bundles when bundle not found +- ✅ Suggests similar bundle names +- ✅ Provides clear creation instructions +- ✅ All commands with optional `--bundle` have fallback logic to find default bundle +- ✅ Help text updated to indicate when `--bundle` is required vs optional + +--- + +## ✅ Validation Checklist + +Before marking a command as compliant: + +- [ ] All parameters use standard names (no deprecated names) +- [ ] Parameters grouped in correct order (Target → Output → Behavior → Advanced) +- [ ] Help text shows parameter groups with comments +- [ ] Defaults shown explicitly in help text +- [ ] Deprecation warnings added for old names (if applicable) +- [ ] Tests updated to use new parameter names +- [ ] Documentation updated with new parameter names + +--- + +## 📝 Examples + +### Before (Inconsistent) + +```python +@app.command("contracts") +def generate_contracts( + base_path: Path | None = typer.Option(None, "--base-path", help="Base directory"), + non_interactive: bool = typer.Option(False, "--non-interactive", help="Non-interactive mode"), +) -> None: + ... +``` + +### After (Standardized) + +```python +@app.command("contracts") +def generate_contracts( + # Target/Input + repo: Path | None = typer.Option(None, "--repo", help="Repository path (default: current directory)"), + + # Behavior/Options + no_interactive: bool = typer.Option(False, "--no-interactive", help="Non-interactive mode (for CI/CD automation)"), +) -> None: + ... +``` + +--- + +## 🔗 Related Documentation + +- **[CLI Reorganization Implementation Plan](../../specfact-cli-internal/docs/internal/implementation/CLI_REORGANIZATION_IMPLEMENTATION_PLAN.md)** - Full reorganization plan +- **[Command Reference](./commands.md)** - Complete command reference +- **[Project Bundle Refactoring Plan](../../specfact-cli-internal/docs/internal/implementation/PROJECT_BUNDLE_REFACTORING_PLAN.md)** - Bundle parameter requirements + +--- + +**Rulesets Applied**: + +- Clean Code Principles (consistent naming, logical grouping) +- Estimation Bias Prevention (evidence-based standards) +- Markdown Rules (proper formatting, comprehensive structure) + +**AI Model**: Claude Sonnet 4.5 (claude-sonnet-4-20250514) diff --git a/_site_local/reference/specmatic.md b/_site_local/reference/specmatic.md new file mode 100644 index 0000000..c264673 --- /dev/null +++ b/_site_local/reference/specmatic.md @@ -0,0 +1,371 @@ +# Specmatic API Reference + +> **API Reference for Specmatic Integration** +> Complete reference for Specmatic functions, classes, and integration points + +--- + +## Overview + +The Specmatic integration module (`specfact_cli.integrations.specmatic`) provides functions and classes for validating OpenAPI/AsyncAPI specifications, checking backward compatibility, generating test suites, and running mock servers using Specmatic. + +**Module**: `specfact_cli.integrations.specmatic` + +--- + +## Functions + +### `check_specmatic_available() -> tuple[bool, str | None]` + +Check if Specmatic CLI is available (either directly or via npx). + +**Returns**: + +- `tuple[bool, str | None]`: `(is_available, error_message)` + - `is_available`: `True` if Specmatic is available, `False` otherwise + - `error_message`: Error message if not available, `None` if available + +**Example**: + +```python +from specfact_cli.integrations.specmatic import check_specmatic_available + +is_available, error_msg = check_specmatic_available() +if is_available: + print("Specmatic is available") +else: + print(f"Specmatic not available: {error_msg}") +``` + +--- + +### `validate_spec_with_specmatic(spec_path: Path, previous_version: Path | None = None) -> SpecValidationResult` + +Validate OpenAPI/AsyncAPI specification using Specmatic. + +**Parameters**: + +- `spec_path` (Path): Path to OpenAPI/AsyncAPI specification file +- `previous_version` (Path | None, optional): Optional path to previous version for backward compatibility check + +**Returns**: + +- `SpecValidationResult`: Validation result with status and details + +**Raises**: + +- No exceptions (returns result with `is_valid=False` if validation fails) + +**Example**: + +```python +from pathlib import Path +from specfact_cli.integrations.specmatic import validate_spec_with_specmatic +import asyncio + +spec_path = Path("api/openapi.yaml") +result = asyncio.run(validate_spec_with_specmatic(spec_path)) + +if result.is_valid: + print("Specification is valid") +else: + print(f"Validation failed: {result.errors}") +``` + +**Validation Checks**: + +1. **Schema Validation**: Validates OpenAPI/AsyncAPI schema structure +2. **Example Generation**: Tests that examples can be generated from the spec +3. **Backward Compatibility** (if `previous_version` provided): Checks for breaking changes + +--- + +### `check_backward_compatibility(old_spec: Path, new_spec: Path) -> tuple[bool, list[str]]` + +Check backward compatibility between two spec versions. + +**Parameters**: + +- `old_spec` (Path): Path to old specification version +- `new_spec` (Path): Path to new specification version + +**Returns**: + +- `tuple[bool, list[str]]`: `(is_compatible, breaking_changes)` + - `is_compatible`: `True` if backward compatible, `False` otherwise + - `breaking_changes`: List of breaking change descriptions + +**Raises**: + +- No exceptions (returns `(False, [])` if check fails) + +**Example**: + +```python +from pathlib import Path +from specfact_cli.integrations.specmatic import check_backward_compatibility +import asyncio + +old_spec = Path("api/openapi.v1.yaml") +new_spec = Path("api/openapi.v2.yaml") + +is_compatible, breaking_changes = asyncio.run( + check_backward_compatibility(old_spec, new_spec) +) + +if is_compatible: + print("Specifications are backward compatible") +else: + print(f"Breaking changes: {breaking_changes}") +``` + +--- + +### `generate_specmatic_tests(spec_path: Path, output_dir: Path | None = None) -> Path` + +Generate Specmatic test suite from specification. + +**Parameters**: + +- `spec_path` (Path): Path to OpenAPI/AsyncAPI specification +- `output_dir` (Path | None, optional): Optional output directory (default: `.specfact/specmatic-tests/`) + +**Returns**: + +- `Path`: Path to generated test directory + +**Raises**: + +- `RuntimeError`: If Specmatic is not available or test generation fails + +**Example**: + +```python +from pathlib import Path +from specfact_cli.integrations.specmatic import generate_specmatic_tests +import asyncio + +spec_path = Path("api/openapi.yaml") +output_dir = Path("tests/specmatic") + +test_dir = asyncio.run(generate_specmatic_tests(spec_path, output_dir)) +print(f"Tests generated in: {test_dir}") +``` + +--- + +### `create_mock_server(spec_path: Path, port: int = 9000, strict_mode: bool = True) -> MockServer` + +Create Specmatic mock server from specification. + +**Parameters**: + +- `spec_path` (Path): Path to OpenAPI/AsyncAPI specification +- `port` (int, optional): Port number for mock server (default: 9000) +- `strict_mode` (bool, optional): Use strict validation mode (default: True) + +**Returns**: + +- `MockServer`: Mock server instance + +**Raises**: + +- `RuntimeError`: If Specmatic is not available or mock server fails to start + +**Example**: + +```python +from pathlib import Path +from specfact_cli.integrations.specmatic import create_mock_server +import asyncio + +spec_path = Path("api/openapi.yaml") +mock_server = asyncio.run(create_mock_server(spec_path, port=8080)) + +print(f"Mock server running at http://localhost:{mock_server.port}") +# ... use mock server ... +mock_server.stop() +``` + +--- + +## Classes + +### `SpecValidationResult` + +Result of Specmatic validation. + +**Attributes**: + +- `is_valid` (bool): Overall validation status +- `schema_valid` (bool): Schema validation status +- `examples_valid` (bool): Example generation validation status +- `backward_compatible` (bool | None): Backward compatibility status (None if not checked) +- `errors` (list[str]): List of error messages +- `warnings` (list[str]): List of warning messages +- `breaking_changes` (list[str]): List of breaking changes (if backward compatibility checked) + +**Methods**: + +- `to_dict() -> dict[str, Any]`: Convert to dictionary +- `to_json(indent: int = 2) -> str`: Convert to JSON string + +**Example**: + +```python +from specfact_cli.integrations.specmatic import SpecValidationResult + +result = SpecValidationResult( + is_valid=True, + schema_valid=True, + examples_valid=True, + backward_compatible=True, +) + +print(result.to_json()) +# { +# "is_valid": true, +# "schema_valid": true, +# "examples_valid": true, +# "backward_compatible": true, +# "errors": [], +# "warnings": [], +# "breaking_changes": [] +# } +``` + +--- + +### `MockServer` + +Mock server instance. + +**Attributes**: + +- `port` (int): Port number +- `process` (subprocess.Popen[str] | None): Process handle (None if not running) +- `spec_path` (Path | None): Path to specification file + +**Methods**: + +- `is_running() -> bool`: Check if mock server is running +- `stop() -> None`: Stop the mock server + +**Example**: + +```python +from specfact_cli.integrations.specmatic import MockServer + +mock_server = MockServer(port=9000, spec_path=Path("api/openapi.yaml")) + +if mock_server.is_running(): + print("Mock server is running") + mock_server.stop() +``` + +--- + +## Integration Points + +### Import Command Integration + +The `import from-code` command automatically validates bundle contracts with Specmatic after import. + +**Location**: `specfact_cli.commands.import_cmd._validate_bundle_contracts()` + +**Behavior**: + +- Validates all contracts referenced in bundle features +- Shows validation results in console output +- Suggests mock server if contracts are found + +**Example Output**: + +``` +🔍 Validating 3 contract(s) in bundle with Specmatic... +Validating contracts/FEATURE-001.openapi.yaml (from FEATURE-001)... + ✓ FEATURE-001.openapi.yaml is valid +💡 Tip: Run 'specfact spec mock' to start a mock server for development +``` + +--- + +### Enforce Command Integration + +The `enforce sdd` command validates bundle contracts and reports failures as deviations. + +**Location**: `specfact_cli.commands.enforce.enforce_sdd()` + +**Behavior**: + +- Validates contracts referenced in bundle features +- Reports validation failures as `CONTRACT_VIOLATION` deviations +- Includes validation results in enforcement report + +**Example Output**: + +``` +Validating API contracts with Specmatic... +Found 2 contract(s) referenced in bundle +Validating contracts/FEATURE-001.openapi.yaml (from FEATURE-001)... + ⚠ FEATURE-001.openapi.yaml has validation issues + - Schema validation failed: Invalid schema +``` + +--- + +### Sync Command Integration + +The `sync bridge` command validates contracts before sync operation. + +**Location**: `specfact_cli.commands.sync.sync_bridge()` + +**Behavior**: + +- Validates contracts in bundle before sync +- Checks backward compatibility (if previous versions stored) +- Continues with sync even if validation fails (with warning) + +**Example Output**: + +``` +🔍 Validating OpenAPI contracts before sync... +Validating 2 contract(s)... +Validating contracts/FEATURE-001.openapi.yaml... + ✓ FEATURE-001.openapi.yaml is valid +✓ All contracts validated successfully +``` + +--- + +## Error Handling + +All functions handle errors gracefully: + +- **Specmatic Not Available**: Functions return appropriate error states or raise `RuntimeError` with helpful messages +- **Validation Failures**: Return `SpecValidationResult` with `is_valid=False` and error details +- **Timeout Errors**: Caught and reported in validation results +- **Process Errors**: Mock server creation failures raise `RuntimeError` with details + +--- + +## Command Detection + +Specmatic is automatically detected via: + +1. **Direct Installation**: `specmatic` command in PATH +2. **NPM/NPX**: `npx specmatic` (requires Java/JRE and Node.js) + +The module caches the detection result to avoid repeated checks. + +--- + +## Related Documentation + +- **[Specmatic Integration Guide](../guides/specmatic-integration.md)** - User guide with examples +- **[Spec Commands Reference](./commands.md#spec-commands)** - CLI command reference +- **[Specmatic Documentation](https://docs.specmatic.io/)** - Official Specmatic documentation + +--- + +**Last Updated**: 2025-12-05 diff --git a/_site_local/reference/telemetry.md b/_site_local/reference/telemetry.md new file mode 100644 index 0000000..410a626 --- /dev/null +++ b/_site_local/reference/telemetry.md @@ -0,0 +1,512 @@ +# Privacy-First Telemetry (Optional) + +> **Opt-in analytics that highlight how SpecFact prevents brownfield regressions.** + +SpecFact CLI ships with an **enterprise-grade, privacy-first telemetry system** that is **disabled by default** and only activates when you explicitly opt in. When enabled, we collect high-level, anonymized metrics to quantify outcomes like "what percentage of prevented regressions came from contract violations vs. plan drift." These insights help us communicate the value of SpecFact to the broader brownfield community (e.g., "71% of bugs caught by early adopters were surfaced only after contracts were introduced"). + +**Key Features:** + +- ✅ **Disabled by default** - Privacy-first, requires explicit opt-in +- ✅ **Local storage** - Data stored in `~/.specfact/telemetry.log` (you own it) +- ✅ **OTLP HTTP** - Standard OpenTelemetry Protocol, works with any collector +- ✅ **Test-aware** - Automatically disabled in test environments +- ✅ **Configurable** - Service name, batch settings, timeouts all customizable +- ✅ **Enterprise-ready** - Graceful error handling, retry logic, production-grade reliability + +--- + +## How to Opt In + +### Option 1: Local-only (No endpoint or auth needed) ⭐ Simplest + +**No authentication required!** Telemetry works out-of-the-box with local storage only. + +**Quick start:** + +```bash +# Enable telemetry (local storage only) +echo "true" > ~/.specfact/telemetry.opt-in +``` + +That's it! Telemetry data will be stored in `~/.specfact/telemetry.log` (JSONL format). You can inspect, rotate, or delete this file anytime. + +**Note:** If you later create `~/.specfact/telemetry.yaml` with `enabled: true`, the config file takes precedence and the `.opt-in` file is no longer needed. + +**Benefits:** + +- ✅ No setup required - works immediately +- ✅ No authentication needed +- ✅ Your data stays local (privacy-first) +- ✅ You own the data file + +### Option 2: Remote export (Requires endpoint and auth) + +If you want to send telemetry to a remote collector (for dashboards, analytics, etc.), you'll need: + +1. **An OTLP collector endpoint** (self-hosted or cloud service like Grafana Cloud) +2. **Authentication credentials** (if your collector requires auth) + +**When you need auth:** + +- Using a **cloud service** (Grafana Cloud, Honeycomb, etc.) - you sign up and get API keys +- Using a **self-hosted collector with auth** - you configure your own auth +- Using a **company's existing observability stack** - your team provides credentials + +**When you DON'T need auth:** + +- Using a **self-hosted collector without auth** (local development) +- **Local-only mode** (no endpoint = no auth needed) + +### Recommended: Config file (persistent) + +For remote export (or local-only with persistent config), create `~/.specfact/telemetry.yaml` with your telemetry configuration. + +**Important:** If you have `enabled: true` in `telemetry.yaml`, you **do NOT need** the `.opt-in` file. The config file takes precedence. The `.opt-in` file is only used as a fallback if the config file doesn't exist or has `enabled: false`. + +**Quick start:** Copy the example template: + +```bash +# Copy the example template +cp resources/templates/telemetry.yaml.example ~/.specfact/telemetry.yaml + +# Or if installed via pip/uvx, find it in the package: +# On Linux/Mac: ~/.local/share/specfact-cli/resources/templates/telemetry.yaml.example +# Then edit ~/.specfact/telemetry.yaml with your settings +``` + +**Manual setup:** Create `~/.specfact/telemetry.yaml` with your telemetry configuration: + +```yaml +# Enable telemetry +enabled: true + +# OTLP endpoint (HTTPS recommended for corporate environments) +# Example for Grafana Cloud: +endpoint: "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp/v1/traces" + +# Authentication headers +# For Grafana Cloud, use Basic auth with your instance-id:api-key (base64 encoded) +headers: + Authorization: "Basic YOUR_BASE64_ENCODED_CREDENTIALS_HERE" + +# Optional: Advanced configuration +service_name: "specfact-cli" # Custom service name (default: "specfact-cli") +batch_size: 512 # Batch size (default: 512) +batch_timeout: 5 # Batch timeout in seconds (default: 5) +export_timeout: 10 # Export timeout in seconds (default: 10) +debug: false # Enable console output for debugging (default: false) +local_path: "~/.specfact/telemetry.log" # Local log file path (default: ~/.specfact/telemetry.log) +``` + +**Benefits:** + +- Persistent configuration (survives shell restarts) +- All settings in one place +- Easy to version control or share with team +- Environment variables can still override (for temporary changes) + +### Alternative: Environment variables (temporary) + +```bash +# Basic opt-in (local storage only) +export SPECFACT_TELEMETRY_OPT_IN=true + +# Optional: send events to your own OTLP collector +export SPECFACT_TELEMETRY_ENDPOINT="https://telemetry.yourcompany.com/v1/traces" +export SPECFACT_TELEMETRY_HEADERS="Authorization: Bearer xxxx" + +# Advanced configuration (optional) +export SPECFACT_TELEMETRY_SERVICE_NAME="my-specfact-instance" # Custom service name +export SPECFACT_TELEMETRY_BATCH_SIZE="1024" # Batch size (default: 512) +export SPECFACT_TELEMETRY_BATCH_TIMEOUT="10" # Batch timeout in seconds (default: 5) +export SPECFACT_TELEMETRY_EXPORT_TIMEOUT="30" # Export timeout in seconds (default: 10) +export SPECFACT_TELEMETRY_DEBUG="true" # Enable console output for debugging +``` + +**Note:** Environment variables override config file settings (useful for temporary testing). + +### Legacy: Simple opt-in file (backward compatibility) + +Create `~/.specfact/telemetry.opt-in` with: + +```text +true +``` + +Remove the file (or set it to `false`) to opt out again. + +**Note:** This method only enables telemetry with local storage. For OTLP export, use the config file or environment variables. + +**Precedence:** If you have both `telemetry.yaml` (with `enabled: true`) and `telemetry.opt-in`, the config file takes precedence. The `.opt-in` file is only checked if the config file doesn't exist or has `enabled: false`. + +### Local storage only (default) + +If no OTLP endpoint is provided, telemetry is persisted as JSON lines in `~/.specfact/telemetry.log`. You own this file—feel free to rotate, inspect, or delete it at any time. + +--- + +## Data We Collect (and Why) + +| Field | Description | Example | +| --- | --- | --- | +| `command` | CLI command identifier | `import.from_code` | +| `mode` | High-level command family | `repro` | +| `execution_mode` | How the command ran (agent vs. AST) | `agent` | +| `files_analyzed` | Count of Python files scanned (rounded) | `143` | +| `features_detected` | Number of features plan import discovered | `27` | +| `stories_detected` | Total stories extracted from code | `112` | +| `checks_total` | Number of validation checks executed | `6` | +| `checks_failed` / `violations_detected` | How many checks or contracts failed | `2` | +| `duration_ms` | Command duration (auto-calculated) | `4280` | +| `success` | Whether the CLI exited successfully | `true` | + +**We never collect:** + +- Repository names or paths +- File contents or snippets +- Usernames, emails, or hostnames + +--- + +## Why Opt In? (Win-Win-Win) + +Telemetry creates a **mutual benefit cycle**: you help us build better features, we prioritize what you need, and the community benefits from collective insights. + +### 🎯 For You (The User) + +**Shape the roadmap:** + +- Your usage patterns directly influence what we build next +- Features you use get prioritized and improved +- Pain points you experience get fixed faster + +**Validate your approach:** + +- Compare your metrics against community benchmarks +- See if your results align with other users +- Build confidence that you're using SpecFact effectively + +**Get better features:** + +- Data-driven prioritization means we build what matters +- Your usage helps us understand real-world needs +- You benefit from features built based on actual usage patterns + +**Prove value:** + +- Community metrics help justify adoption to your team +- "X% of users prevented Y violations" is more convincing than anecdotes +- Helps make the case for continued investment + +### 🚀 For SpecFact (The Project) + +**Understand real usage:** + +- See which commands are actually used most +- Identify pain points and unexpected use cases +- Discover patterns we wouldn't know otherwise + +**Prioritize effectively:** + +- Focus development on high-impact features +- Fix bugs that affect many users +- Avoid building features nobody uses + +**Prove the tool works:** + +- Aggregate metrics demonstrate real impact +- "Contracts caught 3.7x more bugs than tests" is more credible with data +- Helps attract more users and contributors + +**Build credibility:** + +- Public dashboards show transparency +- Data-backed claims are more trustworthy +- Helps the project grow and succeed + +### 🌍 For the Community + +**Collective proof:** + +- Aggregate metrics validate the contract-driven approach +- Helps others decide whether to adopt SpecFact +- Builds momentum for the methodology + +**Knowledge sharing:** + +- See what works for other teams +- Learn from community patterns +- Avoid common pitfalls + +**Open source contribution:** + +- Low-effort way to contribute to the project +- Helps SpecFact succeed, which benefits everyone +- Your anonymized data helps the entire community + +### Real-World Impact + +**Without telemetry:** + +- Roadmap based on assumptions +- Hard to prove impact +- Features may not match real needs + +**With telemetry:** + +- "71% of bugs caught by early adopters were contract violations" +- "Average user prevented 12 regressions per week" +- "Most-used command: `import.from_code` (67% of sessions)" +- Roadmap based on real usage data + +### The Privacy Trade-Off + +**What you share:** + +- Anonymized usage patterns (commands, metrics, durations) +- No personal data, repository names, or file contents + +**What you get:** + +- Better tool (features you need get prioritized) +- Validated approach (compare against community) +- Community insights (learn from others' patterns) + +**You're in control:** + +- Can opt-out anytime +- Data stays local by default +- Choose where to send data (if anywhere) + +--- + +## Routing Telemetry to Your Stack + +### Scenario 1: Local-only (No setup needed) + +If you just want to track your own usage locally, **no endpoint or authentication is required**: + +```bash +# Enable telemetry (local storage only) +echo "true" > ~/.specfact/telemetry.opt-in +``` + +Data will be stored in `~/.specfact/telemetry.log`. That's it! + +### Scenario 2: Self-hosted collector (No auth required) + +If you're running your own OTLP collector locally or on your network without authentication: + +```yaml +# ~/.specfact/telemetry.yaml +enabled: true +endpoint: "http://localhost:4318/v1/traces" # Your local collector +# No headers needed if collector doesn't require auth +``` + +### Scenario 3: Cloud service (Auth required) + +If you're using a cloud service like Grafana Cloud, you'll need to: + +1. **Sign up for the service** (e.g., ) +2. **Get your API credentials** from the service dashboard +3. **Configure SpecFact** with the endpoint and credentials + +**Example for Grafana Cloud:** + +1. Sign up at (free tier available) +2. Go to "Connections" → "OpenTelemetry" → "Send traces" +3. Copy your endpoint URL and API key +4. Configure SpecFact: + +```yaml +# ~/.specfact/telemetry.yaml +enabled: true +endpoint: "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp/v1/traces" +headers: + Authorization: "Basic YOUR_BASE64_ENCODED_CREDENTIALS_HERE" + +# Optional: Resource attributes (recommended for Grafana Cloud) +service_name: "specfact-cli" # Service name (default: "specfact-cli") +service_namespace: "cli" # Service namespace (default: "cli") +deployment_environment: "production" # Deployment environment (default: "production") +``` + +**Where to get credentials:** + +- **Grafana Cloud**: Dashboard → Connections → OpenTelemetry → API key +- **Honeycomb**: Settings → API Keys → Create new key +- **SigNoz Cloud**: Settings → API Keys +- **Your company's stack**: Ask your DevOps/Platform team + +### Scenario 4: Company observability stack (Team provides credentials) + +If your company already has an observability stack (Tempo, Jaeger, etc.): + +1. **Ask your team** for the OTLP endpoint URL +2. **Get authentication credentials** (API key, token, etc.) +3. **Configure SpecFact** with the provided endpoint and auth + +### Using Config File (Recommended for remote export) + +1. Deploy or reuse an OTLP collector that supports HTTPS (Tempo, Honeycomb, SigNoz, Grafana Cloud, etc.). +2. Copy the example template and customize it: + +```bash +# Copy the template +cp resources/templates/telemetry.yaml.example ~/.specfact/telemetry.yaml + +# Edit with your settings +nano ~/.specfact/telemetry.yaml +``` + +Or create `~/.specfact/telemetry.yaml` manually with your endpoint and authentication: + +```yaml +enabled: true +endpoint: "https://your-collector.com/v1/traces" +headers: + Authorization: "Bearer your-token-here" +``` + +### Using Environment Variables + +1. Deploy or reuse an OTLP collector that supports HTTPS. +2. Set `SPECFACT_TELEMETRY_ENDPOINT` to your collector URL. +3. (Optional) Provide HTTP headers via `SPECFACT_TELEMETRY_HEADERS` for tokens or custom auth. +4. Keep `SPECFACT_TELEMETRY_OPT_IN=true`. + +**Note:** Environment variables override config file settings. + +SpecFact will continue writing the local JSON log **and** stream spans to your collector using the OpenTelemetry data model. + +--- + +## Inspecting & Deleting Data + +```bash +# View the most recent events +tail -n 20 ~/.specfact/telemetry.log | jq + +# Delete everything (immediate opt-out) +rm ~/.specfact/telemetry.log +unset SPECFACT_TELEMETRY_OPT_IN +``` + +--- + +## Advanced Configuration + +### Service Name Customization + +Customize the service name in your telemetry data: + +```bash +export SPECFACT_TELEMETRY_SERVICE_NAME="my-project-specfact" +``` + +This is useful when routing multiple projects to the same collector and want to distinguish between them. + +### Batch Processing Tuning + +Optimize batch processing for your use case: + +```bash +# Larger batches for high-volume scenarios +export SPECFACT_TELEMETRY_BATCH_SIZE="2048" + +# Longer timeouts for slower networks +export SPECFACT_TELEMETRY_BATCH_TIMEOUT="15" +export SPECFACT_TELEMETRY_EXPORT_TIMEOUT="60" +``` + +**Defaults:** + +- `BATCH_SIZE`: 512 spans +- `BATCH_TIMEOUT`: 5 seconds +- `EXPORT_TIMEOUT`: 10 seconds + +### Test Environment Detection + +Telemetry is **automatically disabled** in test environments. No configuration needed - we detect: + +- `TEST_MODE=true` environment variable +- `PYTEST_CURRENT_TEST` (set by pytest) + +This ensures tests run cleanly without telemetry overhead. + +### Debug Mode + +Enable console output to see telemetry events in real-time: + +```bash +export SPECFACT_TELEMETRY_DEBUG=true +``` + +Useful for troubleshooting telemetry configuration or verifying data collection. + +## FAQ + +**Do I need authentication to use telemetry?** + +**No!** Authentication is only required if you want to send telemetry to a remote collector (cloud service or company stack). For local-only mode, just enable telemetry - no endpoint or auth needed: + +```bash +echo "true" > ~/.specfact/telemetry.opt-in +``` + +**Where do I get authentication credentials?** + +**It depends on your setup:** + +- **Local-only mode**: No credentials needed ✅ +- **Self-hosted collector (no auth)**: No credentials needed ✅ +- **Grafana Cloud**: Sign up at → Get API key from dashboard +- **Honeycomb**: Sign up at → Settings → API Keys +- **Company stack**: Ask your DevOps/Platform team for endpoint and credentials + +**Do I need to set up my own collector?** + +**No!** Telemetry works with **local storage only** by default. If you want dashboards or remote analytics, you can optionally route to your own OTLP collector (self-hosted or cloud service). + +**Does telemetry affect performance?** + +No. We buffer metrics in-memory and write to disk at the end of each command. When OTLP export is enabled, spans are batched and sent asynchronously. Telemetry operations are non-blocking and won't slow down your CLI commands. + +**Can enterprises keep data on-prem?** +Yes. Point `SPECFACT_TELEMETRY_ENDPOINT` to an internal collector. Nothing leaves your network unless you decide to forward it. All data is stored locally in `~/.specfact/telemetry.log` by default. + +**Can I prove contracts are preventing bugs?** +Absolutely. We surface `violations_detected` from commands like `specfact repro` so you can compare "bugs caught by contracts" vs. "bugs caught by legacy tests" over time, and we aggregate the ratios (anonymously) to showcase SpecFact's brownfield impact publicly. + +**What happens if the collector is unavailable?** +Telemetry gracefully degrades - events are still written to local storage (`~/.specfact/telemetry.log`), and export failures are logged but don't affect your CLI commands. You can retry exports later by processing the local log file. + +**Is telemetry enabled in CI/CD?** +Only if you explicitly opt in. We recommend enabling telemetry in CI/CD to track brownfield adoption metrics, but it's completely optional. Test environments automatically disable telemetry. + +**How do I verify telemetry is working?** + +1. Enable debug mode: `export SPECFACT_TELEMETRY_DEBUG=true` +2. Run a command: `specfact import from-code --repo .` +3. Check local log: `tail -f ~/.specfact/telemetry.log` +4. Verify events appear in your OTLP collector (if configured) + +**Do I need both `telemetry.yaml` and `telemetry.opt-in`?** + +**No!** If you have `enabled: true` in `telemetry.yaml`, you **don't need** the `.opt-in` file. The config file takes precedence. The `.opt-in` file is only used as a fallback for backward compatibility or if you're using the simple local-only method without a config file. + +**Precedence order:** + +1. Environment variables (highest priority) +2. Config file (`telemetry.yaml` with `enabled: true`) +3. Simple opt-in file (`telemetry.opt-in`) - only if config file doesn't enable it +4. Defaults (disabled) + +--- + +**Related docs:** + +- [`docs/guides/brownfield-faq.md`](../guides/brownfield-faq.md) – Brownfield workflows +- [`docs/guides/brownfield-roi.md`](../guides/brownfield-roi.md) – Quantifying the savings +- [`docs/examples/brownfield-django-modernization.md`](../examples/brownfield-django-modernization.md) – Example pipeline diff --git a/_site_local/robots/index.txt b/_site_local/robots/index.txt new file mode 100644 index 0000000..b004bd4 --- /dev/null +++ b/_site_local/robots/index.txt @@ -0,0 +1 @@ +Sitemap: https://nold-ai.github.io/specfact-cli/sitemap.xml diff --git a/_site_local/schema-versioning/index.html b/_site_local/schema-versioning/index.html new file mode 100644 index 0000000..e72facd --- /dev/null +++ b/_site_local/schema-versioning/index.html @@ -0,0 +1,417 @@ + + + + + + + +Schema Versioning | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Schema Versioning

+ +

This document describes bundle schema versions and backward compatibility in SpecFact CLI.

+ +

Overview

+ +

SpecFact CLI uses semantic versioning for bundle schemas to ensure backward compatibility while allowing new features. Bundle schemas are versioned independently from the CLI version.

+ +

Schema Versions

+ +

v1.0 (Original)

+ +

Introduced: v0.1.0
+Status: Stable, fully supported

+ +

Features:

+ +
    +
  • Project bundle structure (modular aspect files)
    • +
  • Feature and story definitions
    • +
  • Protocol FSM definitions
    • +
  • Contract definitions
    • +
  • Basic bundle metadata
    • +
+ +

Bundle Manifest:

+ +
schema_metadata:
+  schema_version: "1.0"
+  project_version: "0.1.0"
+
+ +

v1.1 (Change Tracking)

+ +

Introduced: v0.21.1
+Status: Stable, fully supported

+ +

New Features:

+ +
    +
  • Change tracking data models (ChangeTracking, ChangeProposal, FeatureDelta, ChangeArchive)
    • +
  • Optional change_tracking field in BundleManifest and ProjectBundle
    • +
  • Optional change_archive field in BundleManifest
    • +
  • Bridge adapter interface extensions for change tracking
    • +
+ +

Bundle Manifest:

+ +
schema_metadata:
+  schema_version: "1.1"
+  project_version: "0.1.0"
+change_tracking:  # Optional - only present in v1.1+
+  proposals:
+    add-user-feedback:
+      name: "add-user-feedback"
+      title: "Add User Feedback Feature"
+      # ... change proposal fields
+  feature_deltas:
+    add-user-feedback:
+      - feature_key: "FEATURE-001"
+        change_type: "added"
+        # ... feature delta fields
+change_archive: []  # Optional - only present in v1.1+
+
+ +

Backward Compatibility

+ +

Automatic Compatibility

+ +

v1.0 bundles work with v1.1 CLI:

+ +
    +
  • All change tracking fields are optional
    • +
  • v1.0 bundles load with change_tracking = None and change_archive = []
    • +
  • No migration required - bundles continue to work without modification
    • +
+ +

v1.1 bundles work with v1.0 CLI (if CLI supports it):

+ +
    +
  • Change tracking fields are ignored if CLI doesn’t support v1.1
    • +
  • Core bundle functionality (features, stories, protocols) remains accessible
    • +
+ +

Version Detection

+ +

The bundle loader automatically detects schema version:

+ +
from specfact_cli.models.project import ProjectBundle, _is_schema_v1_1
+
+bundle = ProjectBundle.load_from_directory(bundle_dir)
+
+# Check if bundle uses v1.1 schema
+if _is_schema_v1_1(bundle.manifest):
+    # Bundle supports change tracking
+    if bundle.change_tracking:
+        active_changes = bundle.get_active_changes()
+        # ... work with change tracking
+else:
+    # v1.0 bundle - change tracking not available
+    # All other functionality works normally
+
+ +

Loading Change Tracking

+ +

Change tracking is loaded via bridge adapters (if available):

+ +
# In ProjectBundle.load_from_directory()
+if _is_schema_v1_1(manifest):
+    try:
+        adapter = AdapterRegistry.get_adapter(bridge_config.adapter.value)
+        change_tracking = adapter.load_change_tracking(bundle_dir, bridge_config)
+    except (ImportError, AttributeError, FileNotFoundError):
+        # Adapter or change tracking not available - continue without it
+        change_tracking = None
+
+ +

Migration

+ +

No Migration Required

+ +

v1.0 → v1.1: No migration needed - bundles are automatically compatible.

+ +
    +
  • v1.0 bundles continue to work without modification
    • +
  • To enable change tracking, update schema_version to "1.1" in bundle.manifest.yaml
    • +
  • Change tracking will be loaded via adapters when available
    • +
+ +

Manual Schema Upgrade (Optional)

+ +

If you want to explicitly upgrade a bundle to v1.1:

+ +
    +
  1. Update bundle manifest:
    2. +
+ +
# .specfact/projects/<bundle-name>/bundle.manifest.yaml
+schema_metadata:
+  schema_version: "1.1"  # Changed from "1.0"
+  project_version: "0.1.0"
+
+ +
    +
  1. Change tracking will be loaded automatically:
    2. +
+ +
    +
  • If bridge adapter is configured, change tracking loads from adapter-specific storage
    • +
  • If no adapter, change_tracking remains None (still valid v1.1 bundle)
    • +
+ +
    +
  1. No data loss:
    2. +
+ +
    +
  • All existing features, stories, and protocols remain unchanged
    • +
  • Change tracking fields are optional - bundle remains valid without them
    • +
+ +

Version Support Matrix

+ + + + + + + + + + + + + + + + + + + + + +
CLI Versionv1.0 Supportv1.1 Support
v0.1.0 - v0.21.0✅ Full❌ Not available
v0.21.1+✅ Full✅ Full
+ +

Best Practices

+ +

For Bundle Authors

+ +
    +
  1. Use latest schema version: Set schema_version: "1.1" for new bundles
    2. +
  2. Keep change tracking optional: Don’t require change tracking for core functionality
    3. +
  3. Document schema version: Include schema version in bundle documentation
    4. +
+ +

For Adapter Developers

+ +
    +
  1. Support both versions: Check schema version before loading change tracking
    2. +
  2. Graceful degradation: Return None if change tracking not available
    3. +
  3. Cross-repository support: Use external_base_path for cross-repo configurations
    4. +
+ + + + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/sitemap/index.xml b/_site_local/sitemap/index.xml new file mode 100644 index 0000000..de46fe6 --- /dev/null +++ b/_site_local/sitemap/index.xml @@ -0,0 +1,93 @@ + + + +https://nold-ai.github.io/specfact-cli/examples/ + + +https://nold-ai.github.io/specfact-cli/reference/ + + +https://nold-ai.github.io/specfact-cli/guides/agile-scrum-workflows/ + + +https://nold-ai.github.io/specfact-cli/ai-ide-workflow/ + + +https://nold-ai.github.io/specfact-cli/architecture/ + + +https://nold-ai.github.io/specfact-cli/brownfield-engineer/ + + +https://nold-ai.github.io/specfact-cli/brownfield-journey/ + + +https://nold-ai.github.io/specfact-cli/guides/command-chains/ + + +https://nold-ai.github.io/specfact-cli/reference/commands/ + + +https://nold-ai.github.io/specfact-cli/common-tasks/ + + +https://nold-ai.github.io/specfact-cli/competitive-analysis/ + + +https://nold-ai.github.io/specfact-cli/copilot-mode/ + + +https://nold-ai.github.io/specfact-cli/directory-structure/ + + +https://nold-ai.github.io/specfact-cli/getting-started/first-steps/ + + +https://nold-ai.github.io/specfact-cli/guides/ide-integration/ + + +https://nold-ai.github.io/specfact-cli/ + + +https://nold-ai.github.io/specfact-cli/getting-started/installation/ + + +https://nold-ai.github.io/specfact-cli/migration-guide/ + + +https://nold-ai.github.io/specfact-cli/modes/ + + +https://nold-ai.github.io/specfact-cli/quick-examples/ + + +https://nold-ai.github.io/specfact-cli/schema-versioning/ + + +https://nold-ai.github.io/specfact-cli/guides/speckit-journey/ + + +https://nold-ai.github.io/specfact-cli/team-collaboration-workflow/ + + +https://nold-ai.github.io/specfact-cli/testing-terminal-output/ + + +https://nold-ai.github.io/specfact-cli/troubleshooting/ + + +https://nold-ai.github.io/specfact-cli/use-cases/ + + +https://nold-ai.github.io/specfact-cli/ux-features/ + + +https://nold-ai.github.io/specfact-cli/redirects/ + + +https://nold-ai.github.io/specfact-cli/sitemap/ + + +https://nold-ai.github.io/specfact-cli/robots/ + + diff --git a/_site_local/team-collaboration-workflow/index.html b/_site_local/team-collaboration-workflow/index.html new file mode 100644 index 0000000..abf58c8 --- /dev/null +++ b/_site_local/team-collaboration-workflow/index.html @@ -0,0 +1,404 @@ + + + + + + + +Team Collaboration Workflow | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Team Collaboration Workflow

+ +
+

Complete guide to using SpecFact CLI for team collaboration with persona-based workflows

+
+ +
+ +

Overview

+ +

SpecFact CLI supports team collaboration through persona-based workflows where different roles (Product Owner, Architect, Developer) work on different aspects of the project using Markdown files. This guide explains when and how to use the team collaboration commands.

+ +

Related: Agile/Scrum Workflows - Complete persona-based collaboration guide

+ +
+ +

When to Use Team Collaboration Commands

+ +

Use these commands when:

+ +
    +
  • Multiple team members need to work on the same project bundle
    • +
  • Different roles (Product Owner, Architect, Developer) need to edit different sections
    • +
  • Concurrent editing needs to be managed safely
    • +
  • Version control integration is needed for team workflows
    • +
+ +
+ +

Core Commands

+ +

project init-personas

+ +

Initialize persona definitions for a project bundle.

+ +

When to use: First-time setup for team collaboration.

+ +

Example:

+ +
specfact project init-personas --bundle my-project
+
+ +

Related: Agile/Scrum Workflows - Persona Setup

+ +
+ +

project export

+ +

Export persona-specific Markdown artifacts for editing.

+ +

When to use: When a team member needs to edit their role-specific sections.

+ +

Example:

+ +
# Export Product Owner view
+specfact project export --bundle my-project --persona product-owner
+
+# Export Developer view
+specfact project export --bundle my-project --persona developer
+
+# Export Architect view
+specfact project export --bundle my-project --persona architect
+
+ +

Workflow: Export → Edit in Markdown → Import back

+ +

Related: Agile/Scrum Workflows - Exporting Persona Artifacts

+ +
+ +

project import

+ +

Import persona edits from Markdown files back into the project bundle.

+ +

When to use: After editing exported Markdown files.

+ +

Example:

+ +
# Import Product Owner edits
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md
+
+# Dry-run to validate without applying
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md --dry-run
+
+ +

Workflow: Export → Edit → Import → Validate

+ +

Related: Agile/Scrum Workflows - Importing Persona Edits

+ +
+ +

project lock / project unlock

+ +

Lock sections to prevent concurrent edits.

+ +

When to use: When multiple team members might edit the same section simultaneously.

+ +

Example:

+ +
# Lock a section for editing
+specfact project lock --bundle my-project --section idea --persona product-owner
+
+# Edit and import
+specfact project export --bundle my-project --persona product-owner
+# ... edit exported file ...
+specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+# Unlock when done
+specfact project unlock --bundle my-project --section idea
+
+ +

Workflow: Lock → Export → Edit → Import → Unlock

+ +

Related: Agile/Scrum Workflows - Section Locking

+ +
+ +

project locks

+ +

List all locked sections.

+ +

When to use: Before starting work to see what’s locked.

+ +

Example:

+ +
specfact project locks --bundle my-project
+
+ +

Related: Agile/Scrum Workflows - Checking Locks

+ +
+ +

Complete Workflow Example

+ +

Scenario: Product Owner Updates Backlog

+ +
# 1. Check what's locked
+specfact project locks --bundle my-project
+
+# 2. Lock the section you need
+specfact project lock --bundle my-project --section idea --persona product-owner
+
+# 3. Export your view
+specfact project export --bundle my-project --persona product-owner --output backlog.md
+
+# 4. Edit backlog.md in your preferred editor
+
+# 5. Import changes back
+specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+# 6. Unlock the section
+specfact project unlock --bundle my-project --section idea
+
+ +
+ +

Integration with Version Management

+ +

Team collaboration integrates with version management:

+ +
# After importing changes, check if version bump is needed
+specfact project version check --bundle my-project
+
+# If needed, bump version
+specfact project version bump --bundle my-project --type minor
+
+ +

Related: Project Version Management

+ +
+ +

Integration with Command Chains

+ +

Team collaboration commands are part of the Plan Promotion & Release Chain:

+ +
    +
  1. Export persona views
    2. +
  2. Edit in Markdown
    3. +
  3. Import back
    4. +
  4. Review plan
    5. +
  5. Enforce SDD
    6. +
  6. Promote plan
    7. +
  7. Bump version
    8. +
+ +

Related: Plan Promotion & Release Chain

+ +
+ +

See Also

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/technical/README.md b/_site_local/technical/README.md new file mode 100644 index 0000000..f924182 --- /dev/null +++ b/_site_local/technical/README.md @@ -0,0 +1,36 @@ +# Technical Deep Dives + +Technical documentation for contributors and developers working on SpecFact CLI. + +## Available Documentation + +- **[Code2Spec Analysis Logic](code2spec-analysis-logic.md)** - AI-first approach for code analysis +- **[Testing Procedures](testing.md)** - Comprehensive testing guide for contributors + +## Developer Tools + +### Maintenance Scripts + +For maintenance scripts and developer utilities, see the [Contributing Guide](../../CONTRIBUTING.md#developer-tools) section on Developer Tools. This includes: + +- **Cleanup Acceptance Criteria Script** - Removes duplicate replacement instruction text from acceptance criteria +- Other maintenance and development utilities in the `scripts/` directory + +## Overview + +This section contains deep technical documentation for: + +- Implementation details +- Testing procedures +- Architecture internals +- Development workflows + +## Related Documentation + +- [Architecture](../reference/architecture.md) - Technical design and principles +- [Commands](../reference/commands.md) - Complete command reference +- [Getting Started](../getting-started/README.md) - Installation and setup + +--- + +**Note**: This section is intended for contributors and developers. For user guides, see [Guides](../guides/README.md). diff --git a/_site_local/technical/code2spec-analysis-logic.md b/_site_local/technical/code2spec-analysis-logic.md new file mode 100644 index 0000000..51a6ebb --- /dev/null +++ b/_site_local/technical/code2spec-analysis-logic.md @@ -0,0 +1,756 @@ +# Code2Spec Analysis Logic: How It Works + +> **TL;DR**: SpecFact CLI uses **AI-first approach** via AI IDE integration (Cursor, CoPilot, etc.) for semantic understanding, with **AST-based fallback** for CI/CD mode. The AI IDE's native LLM understands the codebase semantically, then calls the SpecFact CLI for structured analysis. This avoids separate LLM API setup, langchain, or additional API keys while providing high-quality, semantic-aware analysis that works with all languages and generates Spec-Kit compatible artifacts. + +--- + +## Overview + +The `code2spec` command analyzes existing codebases and reverse-engineers them into plan bundles (features, stories, tasks). It uses **two approaches** depending on operational mode: + +### **Mode 1: AI-First (CoPilot Mode)** - Recommended + +Uses **AI IDE's native LLM** for semantic understanding via pragmatic integration: + +**Workflow**: + +1. **AI IDE's LLM** understands codebase semantically (via slash command prompt) +2. **AI calls SpecFact CLI** (`specfact import from-code `) for structured analysis +3. **AI enhances results** with semantic understanding (priorities, constraints, unknowns) +4. **CLI handles structured work** (file I/O, YAML generation, validation) + +**Benefits**: + +- ✅ **No separate LLM setup** - Uses AI IDE's existing LLM (Cursor, CoPilot, etc.) +- ✅ **No additional API costs** - Leverages existing IDE infrastructure +- ✅ **Simpler architecture** - No langchain, API keys, or complex integration +- ✅ **Multi-language support** - Works with Python, TypeScript, JavaScript, PowerShell, Go, Rust, etc. + +- ✅ **Semantic understanding** - AI understands business logic, not just structure +- ✅ **High-quality output** - Generates meaningful priorities, constraints, unknowns +- ✅ **Spec-Kit compatible** - Produces artifacts that pass `/speckit.analyze` validation +- ✅ **Bidirectional sync** - Preserves semantics during Spec-Kit ↔ SpecFact sync + +**Why this approach?** + +- ✅ **Pragmatic** - Uses existing IDE infrastructure, no extra setup +- ✅ **Cost-effective** - No additional API costs +- ✅ **Streamlined** - Native IDE integration, better developer experience +- ✅ **Maintainable** - Simpler architecture, less code to maintain + +### **Mode 2: AST+Semgrep Hybrid (CI/CD Mode)** - Enhanced Fallback + +Uses **Python's AST + Semgrep pattern matching** for comprehensive structural analysis when LLM is unavailable: + +1. **AST Parsing** - Python's built-in Abstract Syntax Tree for structural analysis +2. **Semgrep Pattern Detection** - Framework-aware pattern matching (API endpoints, models, CRUD, auth) +3. **Pattern Matching** - Heuristic-based method grouping enhanced with Semgrep findings +4. **Confidence Scoring** - Evidence-based quality metrics combining AST + Semgrep evidence +5. **Code Quality Assessment** - Anti-pattern detection and maturity scoring +6. **Deterministic Algorithms** - No randomness, 100% reproducible + +**Why AST+Semgrep hybrid?** + +- ✅ **Fast** - Analyzes thousands of lines in seconds (parallelized) +- ✅ **Deterministic** - Same code always produces same results +- ✅ **Offline** - No cloud services or API calls +- ✅ **Framework-Aware** - Detects FastAPI, Flask, SQLAlchemy, Pydantic patterns +- ✅ **Enhanced Detection** - API endpoints, database models, CRUD operations, auth patterns +- ✅ **Code Quality** - Identifies anti-patterns and code smells +- ✅ **Multi-language Ready** - Semgrep supports TypeScript, JavaScript, Go (patterns ready) +- ⚠️ **Python-Focused** - Currently optimized for Python (other languages pending) + +--- + +## Architecture + +```mermaid +flowchart TD + A["code2spec Command
specfact import from-code my-project --repo . --confidence 0.5"] --> B{Operational Mode} + + B -->|CoPilot Mode| C["AnalyzeAgent (AI-First)
• LLM semantic understanding
• Multi-language support
• Semantic extraction (priorities, constraints, unknowns)
• High-quality Spec-Kit artifacts"] + + B -->|CI/CD Mode| D["CodeAnalyzer (AST+Semgrep Hybrid)
• AST parsing (Python's built-in ast module)
• Semgrep pattern detection (API, models, CRUD, auth)
• Pattern matching (method name + Semgrep findings)
• Confidence scoring (AST + Semgrep evidence)
• Code quality assessment (anti-patterns)
• Story point calculation (Fibonacci sequence)"] + + C --> E["Features with Semantic Understanding
• Actual priorities from code context
• Actual constraints from code/docs
• Actual unknowns from code analysis
• Meaningful scenarios from acceptance criteria"] + + D --> F["Features from Structure + Patterns
• Framework-aware outcomes (API endpoints, models)
• CRUD operation detection
• Code quality constraints (anti-patterns)
• Enhanced confidence scores
• Python-focused (multi-language ready)"] + + style A fill:#2196F3,stroke:#1976D2,stroke-width:2px,color:#fff + style C fill:#4CAF50,stroke:#388E3C,stroke-width:2px,color:#fff + style D fill:#FF9800,stroke:#F57C00,stroke-width:2px,color:#fff + style E fill:#9C27B0,stroke:#7B1FA2,stroke-width:2px,color:#fff + style F fill:#FF5722,stroke:#E64A19,stroke-width:2px,color:#fff +``` + +--- + +## Step-by-Step Process + +### Step 1: File Discovery and Filtering + +```python +# Find all Python files +python_files = repo_path.rglob("*.py") + +# Skip certain directories +skip_patterns = [ + "__pycache__", ".git", "venv", ".venv", + "env", ".pytest_cache", "htmlcov", + "dist", "build", ".eggs" +] + +# Test files: Included by default for comprehensive analysis +# Use --exclude-tests flag to skip test files for faster processing (~30-50% speedup) +# Rationale: Test files are consumers of production code (one-way dependency), +# so skipping them doesn't affect production dependency graph +``` + +**Rationale**: Only analyze production code, not test files or dependencies. + +--- + +### Step 2: AST Parsing + Semgrep Pattern Detection + +For each Python file, we use **two complementary approaches**: + +#### 2.1 AST Parsing + +```python +content = file_path.read_text(encoding="utf-8") +tree = ast.parse(content) # Built-in Python AST parser +``` + +**What AST gives us:** + +- ✅ Class definitions (`ast.ClassDef`) +- ✅ Function/method definitions (`ast.FunctionDef`) +- ✅ Import statements (`ast.Import`, `ast.ImportFrom`) +- ✅ Docstrings (via `ast.get_docstring()`) +- ✅ Method signatures and bodies + +**Why AST?** + +- Built into Python (no dependencies) +- Preserves exact structure (not text parsing) +- Handles all Python syntax correctly +- Extracts metadata (docstrings, names, structure) + +#### 2.2 Semgrep Pattern Detection + +```python +# Run Semgrep for pattern detection (parallel-safe) +semgrep_findings = self._run_semgrep_patterns(file_path) +``` + +**What Semgrep gives us:** + +- ✅ **API Endpoints**: FastAPI, Flask, Express, Gin routes (method + path) +- ✅ **Database Models**: SQLAlchemy, Django, Pydantic, TortoiseORM, Peewee +- ✅ **CRUD Operations**: Function naming patterns (create_*, get_*, update_*, delete_*) +- ✅ **Authentication**: Auth decorators, permission checks +- ✅ **Framework Patterns**: Async/await, context managers, type hints +- ✅ **Code Quality**: Anti-patterns, code smells, security vulnerabilities + +**Why Semgrep?** + +- Framework-aware pattern detection +- Multi-language support (Python, TypeScript, JavaScript, Go) +- Fast pattern matching (parallel execution) +- Rule-based (no hardcoded logic) + +--- + +### Step 3: Feature Extraction from Classes (AST + Semgrep Enhanced) + +**Rule**: Each public class (not starting with `_`) becomes a potential feature. + +```python +def _extract_feature_from_class(node: ast.ClassDef, file_path: Path) -> Feature | None: + # Skip private classes + if node.name.startswith("_") or node.name.startswith("Test"): + return None + + # Generate feature key: FEATURE-CLASSNAME + feature_key = f"FEATURE-{node.name.upper()}" + + # Extract docstring as outcome + docstring = ast.get_docstring(node) + if docstring: + outcomes = [docstring.split("\n\n")[0].strip()] + else: + outcomes = [f"Provides {humanize_name(node.name)} functionality"] +``` + +**Example**: + +- `EnforcementConfig` class → `FEATURE-ENFORCEMENTCONFIG` feature +- Docstring "Configuration for contract enforcement" → Outcome +- Methods grouped into stories (see Step 4) + +--- + +### Step 4: Story Extraction from Methods + +**Key Insight**: Methods are grouped by **functionality patterns**, not individually. + +#### 4.1 Method Grouping (Pattern Matching) + +Methods are grouped using **keyword matching** on method names: + +```python +def _group_methods_by_functionality(methods: list[ast.FunctionDef]) -> dict[str, list]: + groups = defaultdict(list) + + for method in public_methods: + name_lower = method.name.lower() + + # CRUD Operations + if any(crud in name_lower for crud in ["create", "add", "insert", "new"]): + groups["Create Operations"].append(method) + elif any(read in name_lower for read in ["get", "read", "fetch", "find", "list"]): + groups["Read Operations"].append(method) + elif any(update in name_lower for update in ["update", "modify", "edit"]): + groups["Update Operations"].append(method) + elif any(delete in name_lower for delete in ["delete", "remove", "destroy"]): + groups["Delete Operations"].append(method) + + # Validation + elif any(val in name_lower for val in ["validate", "check", "verify"]): + groups["Validation"].append(method) + + # Processing + elif any(proc in name_lower for proc in ["process", "compute", "transform"]): + groups["Processing"].append(method) + + # Analysis + elif any(an in name_lower for an in ["analyze", "parse", "extract"]): + groups["Analysis"].append(method) + + # ... more patterns +``` + +**Pattern Groups**: + +| Group | Keywords | Example Methods | +|-------|----------|----------------| +| **Create Operations** | `create`, `add`, `insert`, `new` | `create_user()`, `add_item()` | +| **Read Operations** | `get`, `read`, `fetch`, `find`, `list` | `get_user()`, `list_items()` | +| **Update Operations** | `update`, `modify`, `edit`, `change` | `update_profile()`, `modify_settings()` | +| **Delete Operations** | `delete`, `remove`, `destroy` | `delete_user()`, `remove_item()` | +| **Validation** | `validate`, `check`, `verify` | `validate_input()`, `check_permissions()` | +| **Processing** | `process`, `compute`, `transform` | `process_data()`, `transform_json()` | +| **Analysis** | `analyze`, `parse`, `extract` | `analyze_code()`, `parse_config()` | +| **Generation** | `generate`, `build`, `make` | `generate_report()`, `build_config()` | +| **Comparison** | `compare`, `diff`, `match` | `compare_plans()`, `diff_files()` | +| **Configuration** | `setup`, `configure`, `initialize` | `setup_logger()`, `configure_db()` | + +**Why Pattern Matching?** + +- ✅ Fast - Simple string matching, no ML overhead +- ✅ Deterministic - Same patterns always grouped together +- ✅ Interpretable - You can see why methods are grouped +- ✅ Customizable - Easy to add new patterns + +--- + +#### 4.2 Story Creation from Method Groups + +Each method group becomes a **user story**: + +```python +def _create_story_from_method_group(group_name, methods, class_name, story_number): + # Generate story key: STORY-CLASSNAME-001 + story_key = f"STORY-{class_name.upper()}-{story_number:03d}" + + # Create user-centric title + title = f"As a user, I can {group_name.lower()} {class_name}" + + # Extract tasks (method names) + tasks = [f"{method.name}()" for method in methods] + + # Extract acceptance from docstrings (Phase 4: Simple text format) + acceptance = [] + for method in methods: + docstring = ast.get_docstring(method) + if docstring: + # Phase 4: Use simple text description (not verbose GWT) + # Examples are stored in OpenAPI contracts, not in feature YAML + first_line = docstring.split("\n")[0].strip() + # Convert to simple format: "Feature works correctly (see contract examples)" + method_name = method.name.replace("_", " ").title() + acceptance.append(f"{method_name} works correctly (see contract examples)") + + # Calculate story points and value points + story_points = _calculate_story_points(methods) + value_points = _calculate_value_points(methods, group_name) +``` + +**Example** (Phase 4 Format): + +```python +# EnforcementConfig class has methods: +# - validate_input() +# - check_permissions() +# - verify_config() + +# → Grouped into "Validation" story: +{ + "key": "STORY-ENFORCEMENTCONFIG-001", + "title": "As a developer, I can validate EnforcementConfig data", + "tasks": ["validate_input()", "check_permissions()", "verify_config()"], + "acceptance": [ + "Validate Input works correctly (see contract examples)", + "Check Permissions works correctly (see contract examples)", + "Verify Config works correctly (see contract examples)" + ], + "contract": "contracts/enforcement-config.openapi.yaml", # Examples stored here + "story_points": 5, + "value_points": 3 +} +``` + +**Phase 4 & 5 Changes (GWT Elimination + Test Pattern Extraction)**: + +- ❌ **BEFORE**: Verbose GWT format ("Given X, When Y, Then Z") - one per test function +- ✅ **AFTER Phase 4**: Simple text format ("Feature works correctly (see contract examples)") +- ✅ **AFTER Phase 5**: Limited to 1-3 high-level acceptance criteria per story, all detailed test patterns in OpenAPI contracts +- ✅ **Benefits**: 81% bundle size reduction (18MB → 3.4MB, 5.3x smaller), examples in OpenAPI contracts for Specmatic integration +- ✅ **Quality**: All test patterns preserved in contract files, no information loss + +--- + +### Step 3: Feature Enhancement with Semgrep + +After extracting features from AST, we enhance them with Semgrep findings: + +```python +def _enhance_feature_with_semgrep(feature, semgrep_findings, file_path, class_name): + """Enhance feature with Semgrep pattern detection results.""" + for finding in semgrep_findings: + # API endpoint detection → +0.1 confidence, add "API" theme + # Database model detection → +0.15 confidence, add "Database" theme + # CRUD operation detection → +0.1 confidence, add to outcomes + # Auth pattern detection → +0.1 confidence, add "Security" theme + # Anti-pattern detection → -0.05 confidence, add to constraints + # Security issues → -0.1 confidence, add to constraints +``` + +**Semgrep Enhancements**: + +- **API Endpoints**: Adds `"Exposes API endpoints: GET /users, POST /users"` to outcomes +- **Database Models**: Adds `"Defines data models: UserModel, ProductModel"` to outcomes +- **CRUD Operations**: Adds `"Provides CRUD operations: CREATE user, GET user"` to outcomes +- **Code Quality**: Adds constraints like `"Code quality: Bare except clause detected - antipattern"` +- **Confidence Adjustments**: Framework patterns increase confidence, anti-patterns decrease it + +--- + +### Step 5: Confidence Scoring (AST + Semgrep Evidence) + +**Goal**: Determine how confident we are that this is a real feature (not noise), combining AST and Semgrep evidence. + +```python +def _calculate_feature_confidence(node: ast.ClassDef, stories: list[Story]) -> float: + score = 0.3 # Base score (30%) + + # Has docstring (+20%) + if ast.get_docstring(node): + score += 0.2 + + # Has stories (+20%) + if stories: + score += 0.2 + + # Has multiple stories (+20%) + if len(stories) > 2: + score += 0.2 + + # Stories are well-documented (+10%) + documented_stories = sum(1 for s in stories if s.acceptance and len(s.acceptance) > 1) + if stories and documented_stories > len(stories) / 2: + score += 0.1 + + return min(score, 1.0) # Cap at 100% +``` + +**Confidence Factors**: + +| Factor | Weight | Rationale | +|--------|--------|-----------| +| **Base Score** | 30% | Every class starts with baseline | +| **Has Docstring** | +20% | Documented classes are more likely real features | +| **Has Stories** | +20% | Methods grouped into stories indicate functionality | +| **Multiple Stories** | +20% | More stories = more complete feature | +| **Well-Documented Stories** | +10% | Docstrings in methods indicate intentional design | + +**Example**: + +- `EnforcementConfig` with docstring + 3 well-documented stories → **0.9 confidence** (90%) +- `InternalHelper` with no docstring + 1 story → **0.5 confidence** (50%) + +**Filtering**: Features below `--confidence` threshold (default 0.5) are excluded. + +**Semgrep Confidence Enhancements** (Systematic Evidence-Based Scoring): + +| Semgrep Finding | Confidence Adjustment | Rationale | +|----------------|----------------------|-----------| +| **API Endpoint Detected** | +0.1 | Framework patterns indicate real features | +| **Database Model Detected** | +0.15 | Data models are core features | +| **CRUD Operations Detected** | +0.1 | Complete CRUD indicates well-defined feature | +| **Auth Pattern Detected** | +0.1 | Security features are important | +| **Framework Patterns Detected** | +0.05 | Framework usage indicates intentional design | +| **Test Patterns Detected** | +0.1 | Tests indicate validated feature | +| **Anti-Pattern Detected** | -0.05 | Code quality issues reduce maturity | +| **Security Issue Detected** | -0.1 | Security vulnerabilities are critical | + +**How It Works**: + +1. **Evidence Extraction**: Semgrep findings are categorized into evidence flags (API endpoints, models, CRUD, etc.) +2. **Confidence Calculation**: Base AST confidence (0.3-0.9) is adjusted with Semgrep evidence weights +3. **Systematic Scoring**: Each pattern type has a documented weight, ensuring consistent confidence across features +4. **Quality Assessment**: Anti-patterns and security issues reduce confidence, indicating lower code maturity + +**Example**: + +- `UserService` with API endpoints + CRUD operations → **Base 0.6 + 0.1 (API) + 0.1 (CRUD) = 0.8 confidence** +- `BadService` with anti-patterns → **Base 0.6 - 0.05 (anti-pattern) = 0.55 confidence** + +--- + +### Step 6: Story Points Calculation + +**Goal**: Estimate complexity using **Fibonacci sequence** (1, 2, 3, 5, 8, 13, 21...) + +```python +def _calculate_story_points(methods: list[ast.FunctionDef]) -> int: + method_count = len(methods) + + # Count total lines + total_lines = sum(len(ast.unparse(m).split("\n")) for m in methods) + avg_lines = total_lines / method_count if method_count > 0 else 0 + + # Heuristic: complexity based on count and size + if method_count <= 2 and avg_lines < 20: + base_points = 2 # Small + elif method_count <= 5 and avg_lines < 40: + base_points = 5 # Medium + elif method_count <= 8: + base_points = 8 # Large + else: + base_points = 13 # Extra Large + + # Return nearest Fibonacci number + return min(FIBONACCI, key=lambda x: abs(x - base_points)) +``` + +**Heuristic Table**: + +| Methods | Avg Lines | Base Points | Fibonacci Result | +|---------|-----------|-------------|------------------| +| 1-2 | < 20 | 2 | **2** | +| 3-5 | < 40 | 5 | **5** | +| 6-8 | Any | 8 | **8** | +| 9+ | Any | 13 | **13** | + +**Why Fibonacci?** + +- ✅ Industry standard (Scrum/Agile) +- ✅ Non-linear (reflects uncertainty) +- ✅ Widely understood by teams + +--- + +### Step 7: Value Points Calculation + +**Goal**: Estimate **business value** (not complexity, but importance). + +```python +def _calculate_value_points(methods: list[ast.FunctionDef], group_name: str) -> int: + # CRUD operations are high value + crud_groups = ["Create Operations", "Read Operations", "Update Operations", "Delete Operations"] + if group_name in crud_groups: + base_value = 8 # High business value + + # User-facing operations + elif group_name in ["Processing", "Analysis", "Generation", "Comparison"]: + base_value = 5 # Medium-high value + + # Developer/internal operations + elif group_name in ["Validation", "Configuration"]: + base_value = 3 # Medium value + + else: + base_value = 3 # Default + + # Adjust for public API exposure + public_count = sum(1 for m in methods if not m.name.startswith("_")) + if public_count >= 3: + base_value = min(base_value + 2, 13) + + return min(FIBONACCI, key=lambda x: abs(x - base_value)) +``` + +**Value Hierarchy**: + +| Group Type | Base Value | Rationale | +|------------|------------|-----------| +| **CRUD Operations** | 8 | Direct user value (create, read, update, delete) | +| **User-Facing** | 5 | Processing, analysis, generation - users see results | +| **Developer/Internal** | 3 | Validation, configuration - infrastructure | +| **Public API Bonus** | +2 | More public methods = higher exposure = more value | + +--- + +### Step 8: Theme Detection from Imports + +**Goal**: Identify what kind of application this is (API, CLI, Database, etc.). + +```python +def _extract_themes_from_imports(tree: ast.AST) -> None: + theme_keywords = { + "fastapi": "API", + "flask": "API", + "django": "Web", + "typer": "CLI", + "click": "CLI", + "pydantic": "Validation", + "redis": "Caching", + "postgres": "Database", + "mysql": "Database", + "asyncio": "Async", + "pytest": "Testing", + # ... more keywords + } + + # Scan all imports + for node in ast.walk(tree): + if isinstance(node, (ast.Import, ast.ImportFrom)): + # Match keywords in import names + for keyword, theme in theme_keywords.items(): + if keyword in import_name.lower(): + self.themes.add(theme) +``` + +**Example**: + +- `import typer` → Theme: **CLI** +- `import pydantic` → Theme: **Validation** +- `from fastapi import FastAPI` → Theme: **API** + +--- + +## Why AI-First? + +### ✅ Advantages of AI-First Approach + +| Aspect | AI-First (CoPilot Mode) | AST-Based (CI/CD Mode) | +|-------|------------------------|------------------------| +| **Language Support** | ✅ All languages | ❌ Python only | +| **Semantic Understanding** | ✅ Understands business logic | ❌ Structure only | +| **Priorities** | ✅ Actual from code context | ⚠️ Generic (hardcoded) | +| **Constraints** | ✅ Actual from code/docs | ⚠️ Generic (hardcoded) | +| **Unknowns** | ✅ Actual from code analysis | ⚠️ Generic (hardcoded) | +| **Scenarios** | ✅ Actual from acceptance criteria | ⚠️ Generic (hardcoded) | +| **Spec-Kit Compatibility** | ✅ High-quality artifacts | ⚠️ Low-quality artifacts | +| **Bidirectional Sync** | ✅ Semantic preservation | ⚠️ Structure-only | + +### When AST Fallback Is Used + +AST-based analysis is used in **CI/CD mode** when: + +- LLM is unavailable (no API access) +- Fast, deterministic analysis is required +- Offline analysis is needed +- Python-only codebase analysis is sufficient + +**Trade-offs**: + +- ✅ Fast and deterministic +- ✅ Works offline +- ❌ Python-only +- ❌ Generic content (hardcoded fallbacks) + +--- + +## Accuracy and Limitations + +### ✅ AI-First Approach (CoPilot Mode) + +**What It Does Well**: + +1. **Semantic Understanding**: Understands business logic and domain concepts +2. **Multi-language Support**: Works with Python, TypeScript, JavaScript, PowerShell, Go, Rust, etc. + +3. **Semantic Extraction**: Extracts actual priorities, constraints, unknowns from code context +4. **High-quality Artifacts**: Generates Spec-Kit compatible artifacts with semantic content +5. **Bidirectional Sync**: Preserves semantics during Spec-Kit ↔ SpecFact sync + +**Limitations**: + +1. **Requires LLM Access**: Needs CoPilot API or IDE integration +2. **Variable Response Time**: Depends on LLM API response time +3. **Token Costs**: May incur API costs for large codebases +4. **Non-deterministic**: May produce slightly different results on repeated runs + +### ⚠️ AST-Based Fallback (CI/CD Mode) + +**What It Does Well**: + +1. **Structural Analysis**: Classes, methods, imports are 100% accurate (AST parsing) +2. **Pattern Recognition**: CRUD, validation, processing patterns are well-defined +3. **Confidence Scoring**: Evidence-based (docstrings, stories, documentation) +4. **Deterministic**: Same code always produces same results +5. **Fast**: Analyzes thousands of lines in seconds +6. **Offline**: Works without API access + +**Limitations**: + +1. **Python-only**: Cannot analyze TypeScript, JavaScript, PowerShell, etc. + +2. **Generic Content**: Produces generic priorities, constraints, unknowns (hardcoded fallbacks) +3. **No Semantic Understanding**: Cannot understand business logic or domain concepts +4. **Method Name Dependency**: If methods don't follow naming conventions, grouping may be less accurate +5. **Docstring Dependency**: Features/stories without docstrings have lower confidence +6. **False Positives**: Internal helper classes might be detected as features + +--- + +## Real Example: EnforcementConfig + +Let's trace how `EnforcementConfig` class becomes a feature: + +```python +class EnforcementConfig: + """Configuration for contract enforcement and quality gates.""" + + def __init__(self, preset: EnforcementPreset): + ... + + def should_block_deviation(self, severity: str) -> bool: + ... + + def get_action(self, severity: str) -> EnforcementAction: + ... +``` + +**Step-by-Step Analysis**: + +1. **AST Parse** → Finds `EnforcementConfig` class with 3 methods +2. **Feature Extraction**: + - Key: `FEATURE-ENFORCEMENTCONFIG` + - Title: `Enforcement Config` (humanized) + - Outcome: `"Configuration for contract enforcement and quality gates."` +3. **Method Grouping**: + - `__init__()` → **Configuration** group + - `should_block_deviation()` → **Validation** group (has "check" pattern) + - `get_action()` → **Read Operations** group (has "get" pattern) +4. **Story Creation**: + - Story 1: "As a developer, I can configure EnforcementConfig" (Configuration group) + - Story 2: "As a developer, I can validate EnforcementConfig data" (Validation group) + - Story 3: "As a user, I can view EnforcementConfig data" (Read Operations group) +5. **Confidence**: 0.9 (has docstring + 3 stories + well-documented) +6. **Story Points**: 5 (3 methods, medium complexity) +7. **Value Points**: 3 (Configuration group = medium value) + +**Result**: + +```yaml +feature: + key: FEATURE-ENFORCEMENTCONFIG + title: Enforcement Config + confidence: 0.9 + stories: + - key: STORY-ENFORCEMENTCONFIG-001 + title: As a developer, I can configure EnforcementConfig + story_points: 2 + value_points: 3 + tasks: ["__init__()"] + - key: STORY-ENFORCEMENTCONFIG-002 + title: As a developer, I can validate EnforcementConfig data + story_points: 2 + value_points: 3 + tasks: ["should_block_deviation()"] + - key: STORY-ENFORCEMENTCONFIG-003 + title: As a user, I can view EnforcementConfig data + story_points: 2 + value_points: 5 + tasks: ["get_action()"] +``` + +--- + +## Validation and Quality Assurance + +### Built-in Validations + +1. **Plan Bundle Schema**: Generated plans are validated against JSON schema +2. **Confidence Threshold**: Low-confidence features are filtered +3. **AST Error Handling**: Invalid Python files are skipped gracefully +4. **File Filtering**: Test files and dependencies are excluded + +### How to Improve Accuracy + +1. **Add Docstrings**: Increases confidence scores +2. **Use Descriptive Names**: Follow naming conventions (CRUD patterns) +3. **Group Related Methods**: Co-locate related functionality in same class +4. **Adjust Confidence Threshold**: Use `--confidence 0.7` for stricter filtering + +--- + +## Performance + +### Benchmarks + +| Repository Size | Files | Time | Throughput | Notes | +|----------------|-------|------|------------|-------| +| **Small** (10 files) | 10 | ~10-30s | ~0.3-1 files/sec | AST + Semgrep analysis | +| **Medium** (50 files) | 50 | ~1-2 min | ~0.4-0.8 files/sec | AST + Semgrep analysis | +| **Large** (100+ files) | 100+ | 2-3 min | ~0.5-0.8 files/sec | AST + Semgrep analysis | +| **Large with Contracts** (100+ files) | 100+ | 15-30+ min | Varies | With contract extraction, graph analysis, and parallel processing (8 workers) | + +**SpecFact CLI on itself**: 19 files in ~30-60 seconds = **~0.3-0.6 files/second** (AST + Semgrep analysis) + +**Note**: + +- **Basic analysis** (AST + Semgrep): Takes **2-3 minutes** for large codebases (100+ files) even without contract extraction +- **With contract extraction** (default in `import from-code`): The process uses parallel workers to extract OpenAPI contracts, relationships, and graph dependencies. For large codebases, this can take **15-30+ minutes** even with 8 parallel workers + +### Bundle Size Optimization (2025-11-30) + +- ✅ **81% Reduction**: 18MB → 3.4MB (5.3x smaller) via test pattern extraction to OpenAPI contracts +- ✅ **Acceptance Criteria**: Limited to 1-3 high-level items per story (detailed examples in contract files) +- ✅ **Quality Preserved**: All test patterns preserved in contract files (no information loss) +- ✅ **Specmatic Integration**: Examples in OpenAPI format enable contract testing + +### Optimization Opportunities + +1. ✅ **Parallel Processing**: Contract extraction uses 8 parallel workers (implemented) +2. ✅ **Interruptible Operations**: All parallel operations support Ctrl+C for immediate cancellation (implemented) +3. **Caching**: Cache AST parsing results (future enhancement) +4. **Incremental Analysis**: Only analyze changed files (future enhancement) + +--- + +## Conclusion + +The `code2spec` analysis is **deterministic, fast, and transparent** because it uses: + +1. ✅ **Python AST** - Built-in, reliable parsing +2. ✅ **Pattern Matching** - Simple, interpretable heuristics +3. ✅ **Confidence Scoring** - Evidence-based quality metrics +4. ✅ **Fibonacci Estimation** - Industry-standard story/value points + +**No AI required** - just solid engineering principles and proven algorithms. + +--- + +## Further Reading + +- [Python AST Documentation](https://docs.python.org/3/library/ast.html) +- [Scrum Story Points](https://www.scrum.org/resources/blog/what-are-story-points) +- [Dogfooding Example](../examples/dogfooding-specfact-cli.md) - See it in action + +--- + +**Questions or improvements?** Open an issue or PR on GitHub! diff --git a/_site_local/technical/dual-stack-pattern.md b/_site_local/technical/dual-stack-pattern.md new file mode 100644 index 0000000..62af053 --- /dev/null +++ b/_site_local/technical/dual-stack-pattern.md @@ -0,0 +1,153 @@ +# Dual-Stack Enrichment Pattern - Technical Specification + +**Status**: ✅ **IMPLEMENTED** (v0.13.0+) +**Last Updated**: 2025-12-02 + +--- + +## Overview + +The Dual-Stack Enrichment Pattern is a technical architecture that enforces CLI-first principles while allowing LLM enrichment in AI IDE environments. It ensures all artifacts are CLI-generated and validated, preventing format drift and ensuring consistency. + +## Architecture + +### Stack 1: CLI (REQUIRED) + +**Purpose**: Generate and validate all artifacts + +**Capabilities**: + +- Tool execution (ruff, pylint, basedpyright, mypy, semgrep, specmatic) +- Bundle management (create, load, save, validate structure) +- Metadata management (timestamps, hashes, telemetry) +- Planning operations (init, add-feature, add-story, update-idea, update-feature) +- AST/Semgrep-based analysis (code structure, patterns, relationships) +- Specmatic validation (OpenAPI/AsyncAPI contract validation) +- Format validation (YAML/JSON schema compliance) +- Source tracking and drift detection + +**Limitations**: + +- ❌ Cannot generate code (no LLM available) +- ❌ Cannot do reasoning (no semantic understanding) + +### Stack 2: LLM (OPTIONAL, AI IDE Only) + +**Purpose**: Add semantic understanding and generate code + +**Capabilities**: + +- Code generation (requires LLM reasoning) +- Code enhancement (contracts, refactoring, improvements) +- Semantic understanding (business logic, context, priorities) +- Plan enrichment (missing features, confidence adjustments, business context) +- Code reasoning (why decisions were made, trade-offs, constraints) + +**Access**: Only via AI IDE slash prompts (Cursor, CoPilot, etc.) + +## Validation Loop Pattern + +### Implementation + +The validation loop pattern is implemented in: + +- `src/specfact_cli/commands/generate.py`: + - `generate_contracts_prompt()` - Generates structured prompts + - `apply_enhanced_contracts()` - Validates and applies enhanced code + +### Validation Steps + +1. **Syntax Validation**: `python -m py_compile` +2. **File Size Check**: Enhanced file must be >= original file size +3. **AST Structure Comparison**: Logical structure integrity check +4. **Contract Imports Verification**: Required imports present +5. **Code Quality Checks**: ruff, pylint, basedpyright, mypy (if available) +6. **Test Execution**: Run tests via specfact (contract-test) + +### Retry Mechanism + +- Maximum 3 attempts +- CLI provides detailed error feedback after each attempt +- LLM fixes issues in temporary file +- Re-validate until success or max attempts reached + +## CLI Metadata + +### Metadata Structure + +```python +@dataclass +class CLIArtifactMetadata: + cli_generated: bool = True + cli_version: str | None = None + generated_at: str | None = None + generated_by: str = "specfact-cli" +``` + +### Metadata Detection + +The `cli_first_validator.py` module provides: + +- `is_cli_generated()` - Check if artifact was CLI-generated +- `extract_cli_metadata()` - Extract CLI metadata from artifact +- `validate_artifact_format()` - Validate artifact format +- `detect_direct_manipulation()` - Detect files that may have been directly manipulated + +## Enforcement Rules + +### For Slash Commands + +1. Every slash command MUST execute the specfact CLI at least once +2. Artifacts are ALWAYS CLI-generated (never LLM-generated directly) +3. Enrichment is additive (LLM adds context, CLI validates and creates) +4. Code generation MUST follow validation loop pattern (temp file → validate → apply) + +### For CLI Commands + +1. All write operations go through CLI +2. Never modify `.specfact/` folder directly +3. Always use `--no-interactive` flag in CI/CD environments +4. Use file reading tools for display only, CLI commands for writes + +## Implementation Status + +### ✅ Implemented + +- Contract enhancement workflow (`generate contracts-prompt` / `contracts-apply`) +- Validation loop pattern with retry mechanism +- CLI metadata detection utilities +- Prompt templates with dual-stack workflow documentation + +### ⏳ Pending + +- Code generation workflow (`generate code-prompt` / `code-apply`) +- Plan enrichment workflow (`plan enrich-prompt` / `enrich-apply`) +- CLI metadata injection into all generated artifacts +- Enhanced validation logic for format consistency + +## Testing + +### Unit Tests + +- `tests/unit/validators/test_cli_first_validator.py` - CLI-first validation utilities +- 23 test cases covering metadata extraction, format validation, and detection + +### Integration Tests + +- Contract enhancement workflow tests in `tests/integration/test_generate_contracts.py` +- Validation loop pattern tests in `tests/integration/test_contracts_apply.py` + +## Related Code + +- `src/specfact_cli/validators/cli_first_validator.py` - Validation utilities +- `src/specfact_cli/commands/generate.py` - Contract enhancement commands +- `resources/prompts/shared/cli-enforcement.md` - CLI enforcement rules +- `resources/prompts/specfact.*.md` - Slash command prompts with dual-stack workflow + +--- + +## Related Documentation + +- **[Dual-Stack Enrichment Guide](../guides/dual-stack-enrichment.md)** - End-user guide +- **[Architecture Documentation](../reference/architecture.md)** - Enforcement rules and quality gates +- **[Operational Modes](../reference/modes.md)** - CI/CD vs Copilot modes diff --git a/_site_local/technical/testing.md b/_site_local/technical/testing.md new file mode 100644 index 0000000..ad13d91 --- /dev/null +++ b/_site_local/technical/testing.md @@ -0,0 +1,901 @@ +# Testing Guide + +This document provides comprehensive guidance on testing the SpecFact CLI, including examples of how to test the `.specfact/` directory structure. + +## Table of Contents + +- [Test Organization](#test-organization) +- [Running Tests](#running-tests) +- [Unit Tests](#unit-tests) +- [Integration Tests](#integration-tests) +- [End-to-End Tests](#end-to-end-tests) +- [Testing Operational Modes](#testing-operational-modes) +- [Testing Sync Operations](#testing-sync-operations) +- [Testing Directory Structure](#testing-directory-structure) +- [Test Fixtures](#test-fixtures) +- [Best Practices](#best-practices) + +## Test Organization + +Tests are organized into three layers: + +```bash +tests/ +├── unit/ # Unit tests for individual modules +│ ├── analyzers/ # Code analyzer tests +│ ├── comparators/ # Plan comparator tests +│ ├── generators/ # Generator tests +│ ├── models/ # Data model tests +│ ├── utils/ # Utility tests +│ └── validators/ # Validator tests +├── integration/ # Integration tests for CLI commands +│ ├── analyzers/ # Analyze command tests +│ ├── comparators/ # Plan compare command tests +│ └── test_directory_structure.py # Directory structure tests +└── e2e/ # End-to-end workflow tests + ├── test_complete_workflow.py + └── test_directory_structure_workflow.py +``` + +## Running Tests + +### All Tests + +```bash +# Run all tests with coverage +hatch test --cover -v + +# Run specific test file +hatch test --cover -v tests/integration/test_directory_structure.py + +# Run specific test class +hatch test --cover -v tests/integration/test_directory_structure.py::TestDirectoryStructure + +# Run specific test method +hatch test --cover -v tests/integration/test_directory_structure.py::TestDirectoryStructure::test_ensure_structure_creates_directories +``` + +### Contract Testing (Brownfield & Greenfield) + +```bash +# Run contract tests +hatch run contract-test + +# Run contract validation +hatch run contract-test-contracts + +# Run scenario tests +hatch run contract-test-scenarios +``` + +## Unit Tests + +Unit tests focus on individual modules and functions. + +### Example: Testing CodeAnalyzer + +```python +def test_code_analyzer_extracts_features(tmp_path): + """Test that CodeAnalyzer extracts features from classes.""" + # Create test file + code = ''' +class UserService: + """User management service.""" + + def create_user(self, name): + """Create new user.""" + pass +''' + repo_path = tmp_path / "src" + repo_path.mkdir() + (repo_path / "service.py").write_text(code) + + # Analyze + analyzer = CodeAnalyzer(repo_path, confidence_threshold=0.5) + plan = analyzer.analyze() + + # Verify + assert len(plan.features) > 0 + assert any("User" in f.title for f in plan.features) +``` + +### Example: Testing PlanComparator + +```python +def test_plan_comparator_detects_missing_feature(): + """Test that PlanComparator detects missing features.""" + # Create plans + feature = Feature( + key="FEATURE-001", + title="Auth", + outcomes=["Login works"], + acceptance=["Users can login"], + ) + + manual_plan = PlanBundle( + version="1.0", + idea=None, + business=None, + product=Product(themes=[], releases=[]), + features=[feature], + ) + + auto_plan = PlanBundle( + version="1.0", + idea=None, + business=None, + product=Product(themes=[], releases=[]), + features=[], # Missing feature + ) + + # Compare + comparator = PlanComparator() + report = comparator.compare(manual_plan, auto_plan) + + # Verify + assert report.total_deviations == 1 + assert report.high_count == 1 + assert "FEATURE-001" in report.deviations[0].description +``` + +## Integration Tests + +Integration tests verify CLI commands work correctly. + +### Example: Testing `import from-code` + +```python +def test_analyze_code2spec_basic_repository(): + """Test analyzing a basic Python repository.""" + runner = CliRunner() + + with tempfile.TemporaryDirectory() as tmpdir: + # Create sample code + src_dir = Path(tmpdir) / "src" + src_dir.mkdir() + + code = ''' +class PaymentProcessor: + """Process payments.""" + def process_payment(self, amount): + """Process a payment.""" + pass +''' + (src_dir / "payment.py").write_text(code) + + # Run command (bundle name as positional argument) + result = runner.invoke( + app, + [ + "import", + "from-code", + "test-project", + "--repo", + tmpdir, + ], + ) + + # Verify + assert result.exit_code == 0 + assert "Analysis complete" in result.stdout or "Project bundle written" in result.stdout + + # Verify output in .specfact/ (modular bundle structure) + bundle_dir = Path(tmpdir) / ".specfact" / "projects" / "test-project" + assert bundle_dir.exists() + assert (bundle_dir / "bundle.manifest.yaml").exists() +``` + +### Example: Testing `plan compare` + +```python +def test_plan_compare_with_smart_defaults(tmp_path): + """Test plan compare finds plans using smart defaults.""" + # Create manual plan + manual_plan = PlanBundle( + version="1.0", + idea=Idea(title="Test", narrative="Test"), + business=None, + product=Product(themes=[], releases=[]), + features=[], + ) + + # Create modular project bundle (new structure) + bundle_dir = tmp_path / ".specfact" / "projects" / "main" + bundle_dir.mkdir(parents=True) + # Save as modular bundle structure + from specfact_cli.utils.bundle_loader import save_project_bundle + from specfact_cli.utils.bundle_loader import _convert_plan_bundle_to_project_bundle + project_bundle = _convert_plan_bundle_to_project_bundle(manual_plan, "main") + save_project_bundle(project_bundle, bundle_dir, atomic=True) + + # Create auto-derived plan (also as modular bundle) + auto_bundle_dir = tmp_path / ".specfact" / "projects" / "auto-derived" + auto_bundle_dir.mkdir(parents=True) + auto_project_bundle = _convert_plan_bundle_to_project_bundle(manual_plan, "auto-derived") + save_project_bundle(auto_project_bundle, auto_bundle_dir, atomic=True) + + # Run compare with --repo only + runner = CliRunner() + result = runner.invoke( + app, + [ + "plan", + "compare", + "--repo", + str(tmp_path), + ], + ) + + assert result.exit_code == 0 + assert "No deviations found" in result.stdout +``` + +## End-to-End Tests + +E2E tests verify complete workflows from start to finish. + +### Example: Complete Greenfield Workflow + +```python +def test_greenfield_workflow_with_scaffold(tmp_path): + """ + Test complete greenfield workflow: + 1. Init project with scaffold + 2. Verify structure created + 3. Edit plan manually + 4. Validate plan + """ + runner = CliRunner() + + # Step 1: Initialize project with scaffold (bundle name as positional argument) + result = runner.invoke( + app, + [ + "plan", + "init", + "e2e-test-project", + "--repo", + str(tmp_path), + "--scaffold", + "--no-interactive", + ], + ) + + assert result.exit_code == 0 + assert "Scaffolded .specfact directory structure" in result.stdout + + # Step 2: Verify structure (modular bundle structure) + specfact_dir = tmp_path / ".specfact" + bundle_dir = specfact_dir / "projects" / "e2e-test-project" + assert (bundle_dir / "bundle.manifest.yaml").exists() + assert (specfact_dir / "protocols").exists() + assert (specfact_dir / "reports" / "brownfield").exists() + assert (specfact_dir / ".gitignore").exists() + + # Step 3: Load and verify plan (modular bundle) + from specfact_cli.utils.bundle_loader import load_project_bundle + project_bundle = load_project_bundle(bundle_dir, validate_hashes=False) + assert project_bundle.manifest.versions.schema == "1.0" + assert project_bundle.idea.title == "E2E Test Project" +``` + +### Example: Complete Brownfield Workflow + +```python +def test_brownfield_analysis_workflow(tmp_path): + """ + Test complete brownfield workflow: + 1. Analyze existing codebase + 2. Verify project bundle generated in .specfact/projects// + 3. Create manual plan in .specfact/projects// + 4. Compare plans + 5. Verify comparison report in .specfact/projects//reports/comparison/ (bundle-specific, Phase 8.5) + """ + runner = CliRunner() + + # Step 1: Create sample codebase + src_dir = tmp_path / "src" + src_dir.mkdir() + + (src_dir / "users.py").write_text(''' +class UserService: + """Manages user operations.""" + def create_user(self, name, email): + """Create a new user account.""" + pass + def get_user(self, user_id): + """Retrieve user by ID.""" + pass +''') + + # Step 2: Run brownfield analysis (bundle name as positional argument) + result = runner.invoke( + app, + ["import", "from-code", "brownfield-test", "--repo", str(tmp_path)], + ) + assert result.exit_code == 0 + + # Step 3: Verify project bundle (modular structure) + bundle_dir = tmp_path / ".specfact" / "projects" / "brownfield-test" + auto_reports = list(brownfield_dir.glob("auto-derived.*.yaml")) + assert len(auto_reports) > 0 + + # Step 4: Create manual plan + # ... (create and save manual plan) + + # Step 5: Run comparison + result = runner.invoke( + app, + ["plan", "compare", "--repo", str(tmp_path)], + ) + assert result.exit_code == 0 + + # Step 6: Verify comparison report + comparison_dir = tmp_path / ".specfact" / "reports" / "comparison" + comparison_reports = list(comparison_dir.glob("report-*.md")) + assert len(comparison_reports) > 0 +``` + +## Testing Operational Modes + +SpecFact CLI supports two operational modes that should be tested: + +### Testing CI/CD Mode + +```python +def test_analyze_cicd_mode(tmp_path): + """Test analyze command in CI/CD mode.""" + runner = CliRunner() + + # Create sample code + src_dir = tmp_path / "src" + src_dir.mkdir() + (src_dir / "service.py").write_text(''' +class UserService: + """User management service.""" + def create_user(self, name): + """Create new user.""" + pass +''') + + # Run in CI/CD mode + result = runner.invoke( + app, + [ + "--mode", + "cicd", + "analyze", + "code2spec", + "--repo", + str(tmp_path), + ], + ) + + assert result.exit_code == 0 + assert "Analysis complete" in result.stdout + + # Verify deterministic output + brownfield_dir = tmp_path / ".specfact" / "reports" / "brownfield" + reports = list(brownfield_dir.glob("auto-derived.*.yaml")) + assert len(reports) > 0 +``` + +### Testing CoPilot Mode + +```python +def test_analyze_copilot_mode(tmp_path): + """Test analyze command in CoPilot mode.""" + runner = CliRunner() + + # Create sample code + src_dir = tmp_path / "src" + src_dir.mkdir() + (src_dir / "service.py").write_text(''' +class UserService: + """User management service.""" + def create_user(self, name): + """Create new user.""" + pass +''') + + # Run in CoPilot mode + result = runner.invoke( + app, + [ + "--mode", + "copilot", + "analyze", + "code2spec", + "--repo", + str(tmp_path), + "--confidence", + "0.7", + ], + ) + + assert result.exit_code == 0 + assert "Analysis complete" in result.stdout + + # CoPilot mode may provide enhanced prompts + # (behavior depends on CoPilot availability) +``` + +### Testing Mode Auto-Detection + +```python +def test_mode_auto_detection(tmp_path): + """Test that mode is auto-detected correctly.""" + runner = CliRunner() + + # Without explicit mode, should auto-detect (bundle name as positional argument) + result = runner.invoke( + app, + ["import", "from-code", "test-project", "--repo", str(tmp_path)], + ) + + assert result.exit_code == 0 + # Default to CI/CD mode if CoPilot not available +``` + +## Testing Sync Operations + +Sync operations require thorough testing for bidirectional synchronization: + +### Testing Spec-Kit Sync + +```python +def test_sync_speckit_one_way(tmp_path): + """Test one-way Spec-Kit sync (import).""" + # Create Spec-Kit structure + spec_dir = tmp_path / "spec" + spec_dir.mkdir() + (spec_dir / "components.yaml").write_text(''' +states: + - INIT + - PLAN +transitions: + - from_state: INIT + on_event: start + to_state: PLAN +''') + + runner = CliRunner() + result = runner.invoke( + app, + [ + "sync", + "bridge", + "--adapter", + "speckit", + "--repo", + str(tmp_path), + "--bundle", + "main", + ], + ) + + assert result.exit_code == 0 + # Verify SpecFact artifacts created (modular bundle structure) + bundle_dir = tmp_path / ".specfact" / "projects" / "main" + assert bundle_dir.exists() + assert (bundle_dir / "bundle.manifest.yaml").exists() +``` + +### Testing Bidirectional Sync + +```python +def test_sync_speckit_bidirectional(tmp_path): + """Test bidirectional Spec-Kit sync.""" + # Create Spec-Kit structure + spec_dir = tmp_path / "spec" + spec_dir.mkdir() + (spec_dir / "components.yaml").write_text(''' +states: + - INIT + - PLAN +transitions: + - from_state: INIT + on_event: start + to_state: PLAN +''') + + # Create SpecFact project bundle (modular structure) + from specfact_cli.models.project import ProjectBundle + from specfact_cli.models.bundle import BundleManifest, BundleVersions + from specfact_cli.models.plan import PlanBundle, Idea, Product, Feature + from specfact_cli.utils.bundle_loader import save_project_bundle + + plan_bundle = PlanBundle( + version="1.0", + idea=Idea(title="Test", narrative="Test"), + product=Product(themes=[], releases=[]), + features=[Feature(key="FEATURE-001", title="Test Feature")], + ) + bundle_dir = tmp_path / ".specfact" / "projects" / "main" + bundle_dir.mkdir(parents=True) + from specfact_cli.utils.bundle_loader import _convert_plan_bundle_to_project_bundle + project_bundle = _convert_plan_bundle_to_project_bundle(plan_bundle, "main") + save_project_bundle(project_bundle, bundle_dir, atomic=True) + + runner = CliRunner() + result = runner.invoke( + app, + [ + "sync", + "bridge", + "--adapter", + "speckit", + "--repo", + str(tmp_path), + "--bundle", + "main", + "--bidirectional", + ], + ) + + assert result.exit_code == 0 + # Verify both directions synced +``` + +### Testing Repository Sync + +```python +def test_sync_repository(tmp_path): + """Test repository sync.""" + # Create sample code + src_dir = tmp_path / "src" + src_dir.mkdir() + (src_dir / "service.py").write_text(''' +class UserService: + """User management service.""" + def create_user(self, name): + """Create new user.""" + pass +''') + + runner = CliRunner() + result = runner.invoke( + app, + [ + "sync", + "repository", + "--repo", + str(tmp_path), + "--target", + ".specfact", + ], + ) + + assert result.exit_code == 0 + # Verify plan artifacts updated + brownfield_dir = tmp_path / ".specfact" / "reports" / "sync" + assert brownfield_dir.exists() +``` + +### Testing Watch Mode + +```python +import time +from unittest.mock import patch + +def test_sync_watch_mode(tmp_path): + """Test watch mode for continuous sync.""" + # Create sample code + src_dir = tmp_path / "src" + src_dir.mkdir() + (src_dir / "service.py").write_text(''' +class UserService: + """User management service.""" + def create_user(self, name): + """Create new user.""" + pass +''') + + runner = CliRunner() + + # Test watch mode with short interval + with patch('time.sleep') as mock_sleep: + result = runner.invoke( + app, + [ + "sync", + "repository", + "--repo", + str(tmp_path), + "--watch", + "--interval", + "1", + ], + input="\n", # Press Enter to stop after first iteration + ) + + # Watch mode should run at least once + assert mock_sleep.called +``` + +## Testing Directory Structure + +The `.specfact/` directory structure is a core feature that requires thorough testing. + +### Testing Directory Creation + +```python +def test_ensure_structure_creates_directories(tmp_path): + """Test that ensure_structure creates all required directories.""" + repo_path = tmp_path / "test_repo" + repo_path.mkdir() + + # Ensure structure + SpecFactStructure.ensure_structure(repo_path) + + # Verify all directories exist (modular bundle structure) + specfact_dir = repo_path / ".specfact" + assert specfact_dir.exists() + assert (specfact_dir / "projects").exists() # Modular bundles directory + assert (specfact_dir / "protocols").exists() + assert (specfact_dir / "reports" / "brownfield").exists() + assert (specfact_dir / "reports" / "comparison").exists() + assert (specfact_dir / "gates" / "results").exists() + assert (specfact_dir / "cache").exists() +``` + +### Testing Scaffold Functionality + +```python +def test_scaffold_project_creates_full_structure(tmp_path): + """Test that scaffold_project creates complete directory structure.""" + repo_path = tmp_path / "test_repo" + repo_path.mkdir() + + # Scaffold project + SpecFactStructure.scaffold_project(repo_path) + + # Verify directories (modular bundle structure) + specfact_dir = repo_path / ".specfact" + assert (specfact_dir / "projects").exists() # Modular bundles directory + assert (specfact_dir / "protocols").exists() + assert (specfact_dir / "reports" / "brownfield").exists() + assert (specfact_dir / "gates" / "config").exists() + + # Verify .gitignore + gitignore = specfact_dir / ".gitignore" + assert gitignore.exists() + + gitignore_content = gitignore.read_text() + assert "reports/" in gitignore_content + assert "gates/results/" in gitignore_content + assert "cache/" in gitignore_content + assert "!projects/" in gitignore_content # Projects directory should be versioned +``` + +### Testing Smart Defaults + +```python +def test_analyze_default_paths(tmp_path): + """Test that analyze uses .specfact/ paths by default.""" + # Create sample code + src_dir = tmp_path / "src" + src_dir.mkdir() + (src_dir / "test.py").write_text(''' +class TestService: + """Test service.""" + def test_method(self): + """Test method.""" + pass +''') + + runner = CliRunner() + result = runner.invoke( + app, + ["import", "from-code", "test-project", "--repo", str(tmp_path)], + ) + + assert result.exit_code == 0 + + # Verify files in .specfact/ + brownfield_dir = tmp_path / ".specfact" / "reports" / "brownfield" + assert brownfield_dir.exists() + reports = list(brownfield_dir.glob("auto-derived.*.yaml")) + assert len(reports) > 0 +``` + +## Test Fixtures + +Use pytest fixtures to reduce code duplication. + +### Common Fixtures + +```python +@pytest.fixture +def tmp_repo(tmp_path): + """Create a temporary repository with .specfact structure.""" + repo_path = tmp_path / "test_repo" + repo_path.mkdir() + SpecFactStructure.scaffold_project(repo_path) + return repo_path + +@pytest.fixture +def sample_plan(): + """Create a sample plan bundle.""" + return PlanBundle( + version="1.0", + idea=Idea(title="Test Project", narrative="Test"), + business=None, + product=Product(themes=["Testing"], releases=[]), + features=[], + ) + +@pytest.fixture +def sample_code(tmp_path): + """Create sample Python code for testing.""" + src_dir = tmp_path / "src" + src_dir.mkdir() + code = ''' +class SampleService: + """Sample service for testing.""" + def sample_method(self): + """Sample method.""" + pass +''' + (src_dir / "sample.py").write_text(code) + return tmp_path +``` + +### Using Fixtures + +```python +def test_with_fixtures(tmp_repo, sample_plan): + """Test using fixtures.""" + # Use pre-configured repository (modular bundle structure) + from specfact_cli.utils.bundle_loader import save_project_bundle, _convert_plan_bundle_to_project_bundle + bundle_dir = tmp_repo / ".specfact" / "projects" / "main" + bundle_dir.mkdir(parents=True) + project_bundle = _convert_plan_bundle_to_project_bundle(sample_plan, "main") + save_project_bundle(project_bundle, bundle_dir, atomic=True) + + assert bundle_dir.exists() + assert (bundle_dir / "bundle.manifest.yaml").exists() +``` + +## Best Practices + +### 1. Test Isolation + +Ensure tests don't depend on each other or external state: + +```python +def test_isolated(tmp_path): + """Each test gets its own tmp_path.""" + # Use tmp_path for all file operations + repo_path = tmp_path / "repo" + repo_path.mkdir() + # Test logic... +``` + +### 2. Clear Test Names + +Use descriptive test names that explain what is being tested: + +```python +def test_plan_compare_detects_missing_feature_in_auto_plan(): + """Good: Clear what is being tested.""" + pass + +def test_compare(): + """Bad: Unclear what is being tested.""" + pass +``` + +### 3. Arrange-Act-Assert Pattern + +Structure tests clearly: + +```python +def test_example(): + # Arrange: Setup test data + plan = create_test_plan() + + # Act: Execute the code being tested + result = process_plan(plan) + + # Assert: Verify results + assert result.success is True +``` + +### 4. Test Both Success and Failure Cases + +```python +def test_valid_plan_passes_validation(): + """Test success case.""" + plan = create_valid_plan() + report = validate_plan_bundle(plan) + assert report.passed is True + +def test_invalid_plan_fails_validation(): + """Test failure case.""" + plan = create_invalid_plan() + report = validate_plan_bundle(plan) + assert report.passed is False + assert len(report.deviations) > 0 +``` + +### 5. Use Assertions Effectively + +```python +def test_with_good_assertions(): + """Use specific assertions with helpful messages.""" + result = compute_value() + + # Good: Specific assertion + assert result == 42, f"Expected 42, got {result}" + + # Good: Multiple specific assertions + assert result > 0, "Result should be positive" + assert result < 100, "Result should be less than 100" +``` + +### 6. Mock External Dependencies + +```python +from unittest.mock import Mock, patch + +def test_with_mocking(): + """Mock external API calls.""" + with patch('module.external_api_call') as mock_api: + mock_api.return_value = {"status": "success"} + + result = function_that_calls_api() + + assert result.status == "success" + mock_api.assert_called_once() +``` + +## Running Specific Test Suites + +```bash +# Run only unit tests +hatch test --cover -v tests/unit/ + +# Run only integration tests +hatch test --cover -v tests/integration/ + +# Run only E2E tests +hatch test --cover -v tests/e2e/ + +# Run tests matching a pattern +hatch test --cover -v -k "directory_structure" + +# Run tests with verbose output +hatch test --cover -vv tests/ + +# Run tests and stop on first failure +hatch test --cover -v -x tests/ +``` + +## Coverage Goals + +- **Unit tests**: Target 90%+ coverage for individual modules +- **Integration tests**: Cover all CLI commands and major workflows +- **E2E tests**: Cover complete user journeys +- **Operational modes**: Test both CI/CD and CoPilot modes +- **Sync operations**: Test bidirectional sync, watch mode, and conflict resolution + +## Continuous Integration + +Tests run automatically on: + +- Every commit +- Pull requests +- Before releases + +CI configuration ensures: + +- All tests pass +- Coverage thresholds met +- No linter errors + +## Additional Resources + +- [pytest documentation](https://docs.pytest.org/) +- [Typer testing guide](https://typer.tiangolo.com/tutorial/testing/) +- [Python testing best practices](https://docs.python-guide.org/writing/tests/) diff --git a/_site_local/testing-terminal-output/index.html b/_site_local/testing-terminal-output/index.html new file mode 100644 index 0000000..54097ad --- /dev/null +++ b/_site_local/testing-terminal-output/index.html @@ -0,0 +1,417 @@ + + + + + + + +Testing Terminal Output Modes | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Testing Terminal Output Modes

+ +

This guide explains how to test SpecFact CLI’s terminal output auto-detection on Ubuntu/GNOME systems.

+ +

Quick Test Methods

+ +

Method 1: Use NO_COLOR (Easiest)

+ +

The NO_COLOR environment variable is the standard way to disable colors:

+ +
# Test in current terminal session
+NO_COLOR=1 specfact --help
+
+# Or export for the entire session
+export NO_COLOR=1
+specfact import from-code my-bundle
+unset NO_COLOR  # Re-enable colors
+
+ +

Method 2: Simulate CI/CD Environment

+ +

Simulate a CI/CD pipeline (BASIC mode):

+ +
# Set CI environment variable
+CI=true specfact --help
+
+# Or simulate GitHub Actions
+GITHUB_ACTIONS=true specfact import from-code my-bundle
+
+ +

Method 3: Use Dumb Terminal Type

+ +

Force a “dumb” terminal that doesn’t support colors:

+ +
# Start a terminal with dumb TERM
+TERM=dumb specfact --help
+
+# Or use vt100 (minimal terminal)
+TERM=vt100 specfact --help
+
+ +

Method 4: Redirect to Non-TTY

+ +

Redirect output to a file or pipe (non-interactive):

+ +
# Redirect to file (non-TTY)
+specfact --help > output.txt 2>&1
+cat output.txt
+
+# Pipe to another command (non-TTY)
+specfact --help | cat
+
+ +

Method 5: Use script Command

+ +

The script command can create a non-interactive session:

+ +
# Create a script session (records to typescript file)
+script -c "specfact --help" output.txt
+
+# Or use script with dumb terminal
+TERM=dumb script -c "specfact --help" output.txt
+
+ +

Testing in GNOME Terminal

+ +

Option A: Launch Terminal with NO_COLOR

+ +
# Launch gnome-terminal with NO_COLOR set
+gnome-terminal -- bash -c "export NO_COLOR=1; specfact --help; exec bash"
+
+ +

Option B: Create a Test Script

+ +

Create a test script test-no-color.sh:

+ +
#!/bin/bash
+export NO_COLOR=1
+specfact --help
+
+ +

Then run:

+ +
chmod +x test-no-color.sh
+./test-no-color.sh
+
+ +

Option C: Use Different Terminal Emulators

+ +

Install and test with different terminal emulators:

+ +
# Install alternative terminals
+sudo apt install xterm terminator
+
+# Test with xterm (can be configured for minimal support)
+xterm -e "NO_COLOR=1 specfact --help"
+
+# Test with terminator
+terminator -e "NO_COLOR=1 specfact --help"
+
+ +

Verifying Terminal Mode Detection

+ +

You can verify which mode is detected:

+ +
# Check detected terminal mode
+python3 -c "from specfact_cli.runtime import get_terminal_mode; print(get_terminal_mode())"
+
+# Check terminal capabilities
+python3 -c "
+from specfact_cli.utils.terminal import detect_terminal_capabilities
+caps = detect_terminal_capabilities()
+print(f'Color: {caps.supports_color}')
+print(f'Animations: {caps.supports_animations}')
+print(f'Interactive: {caps.is_interactive}')
+print(f'CI: {caps.is_ci}')
+"
+
+ +

Expected Behavior

+ +

GRAPHICAL Mode (Default in Full Terminal)

+ +
    +
  • ✅ Colors enabled
    • +
  • ✅ Animations enabled
    • +
  • ✅ Full progress bars
    • +
  • ✅ Rich formatting
    • +
+ +

BASIC Mode (NO_COLOR or CI/CD)

+ +
    +
  • ❌ No colors
    • +
  • ❌ No animations
    • +
  • ✅ Plain text progress updates
    • +
  • ✅ Readable output
    • +
+ +

MINIMAL Mode (TEST_MODE)

+ +
    +
  • ❌ No colors
    • +
  • ❌ No animations
    • +
  • ❌ Minimal output
    • +
  • ✅ Test-friendly
    • +
+ +

Complete Test Workflow

+ +
# 1. Test with colors (default)
+specfact --help
+
+# 2. Test without colors (NO_COLOR)
+NO_COLOR=1 specfact --help
+
+# 3. Test CI/CD mode
+CI=true specfact --help
+
+# 4. Test minimal mode
+TEST_MODE=true specfact --help
+
+# 5. Verify detection
+python3 -c "from specfact_cli.runtime import get_terminal_mode; print(get_terminal_mode())"
+
+ +

Troubleshooting

+ +

If terminal detection isn’t working as expected:

+ +
    +
  1. +

    Check environment variables:

    + + 
    echo "NO_COLOR: $NO_COLOR"
+echo "FORCE_COLOR: $FORCE_COLOR"
+echo "TERM: $TERM"
+echo "CI: $CI"
+
    +
    2. +
  2. +

    Verify TTY status:

    + + 
    python3 -c "import sys; print('Is TTY:', sys.stdout.isatty())"
+
    +
    3. +
  3. +

    Check terminal capabilities:

    + + 
    python3 -c "
+from specfact_cli.utils.terminal import detect_terminal_capabilities
+import json
+caps = detect_terminal_capabilities()
+print(json.dumps({
+    'supports_color': caps.supports_color,
+    'supports_animations': caps.supports_animations,
+    'is_interactive': caps.is_interactive,
+    'is_ci': caps.is_ci
+}, indent=2))
+"
+
    +
    4. +
+ + + +
    +
  • Troubleshooting - Terminal output issues and auto-detection
    • +
  • UX Features - User experience features including terminal output
    • +
+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/troubleshooting/index.html b/_site_local/troubleshooting/index.html new file mode 100644 index 0000000..2ac22df --- /dev/null +++ b/_site_local/troubleshooting/index.html @@ -0,0 +1,987 @@ + + + + + + + +Troubleshooting | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Troubleshooting

+ +

Common issues and solutions for SpecFact CLI.

+ +

Installation Issues

+ +

Command Not Found

+ +

Issue: specfact: command not found

+ +

Solutions:

+ +
    +
  1. +

    Check installation:

    + + 
    pip show specfact-cli
+
    +
    2. +
  2. +

    Reinstall:

    + + 
    pip install --upgrade specfact-cli
+
    +
    3. +
+ +

Plan Select Command is Slow

+ +

Symptom: specfact plan select takes a long time (5+ seconds) to list plans.

+ +

Cause: Plan bundles may be missing summary metadata (older schema version 1.0).

+ +

Solution:

+ +
# Upgrade all plan bundles to latest schema (adds summary metadata)
+specfact plan upgrade --all
+
+# Verify upgrade worked
+specfact plan select --last 5
+
+ +

Performance Improvement: After upgrade, plan select is 44% faster (3.6s vs 6.5s) and scales better with large plan bundles.

+ +
    +
  1. +

    Use uvx (no installation needed):

    + + 
    uvx specfact-cli@latest --help
+
    +
    2. +
+ +

Permission Denied

+ +

Issue: Permission denied when running commands

+ +

Solutions:

+ +
    +
  1. +

    Use user install:

    + + 
    pip install --user specfact-cli
+
    +
    2. +
  2. +

    Check PATH:

    + + 
    echo $PATH
+# Should include ~/.local/bin
+
    +
    3. +
  3. +

    Add to PATH:

    + + 
    export PATH="$HOME/.local/bin:$PATH"
+
    +
    4. +
+ +
+ +

Import Issues

+ +

Spec-Kit Not Detected

+ +

Issue: No Spec-Kit project found when running import from-bridge --adapter speckit

+ +

Solutions:

+ +
    +
  1. +

    Check directory structure:

    + + 
    ls -la .specify/
+ls -la specs/
+
    +
    2. +
  2. +

    Verify Spec-Kit format:

    + +
      +
    • Should have .specify/ directory
      • +
    • Should have specs/ directory with feature folders
      • +
    • Should have specs/[###-feature-name]/spec.md files
      • +
    +
    3. +
  3. +

    Use explicit path:

    + + 
    specfact import from-bridge --adapter speckit --repo /path/to/speckit-project
+
    +
    4. +
+ +

Code Analysis Fails (Brownfield) ⭐

+ +

Issue: Analysis failed or No features detected when analyzing legacy code

+ +

Solutions:

+ +
    +
  1. +

    Check repository path:

    + + 
    specfact import from-code --bundle legacy-api --repo . --verbose
+
    +
    2. +
  2. +

    Lower confidence threshold (for legacy code with less structure):

    + + 
    specfact import from-code --bundle legacy-api --repo . --confidence 0.3
+
    +
    3. +
  3. +

    Check file structure:

    + + 
    find . -name "*.py" -type f | head -10
+
    +
    4. +
  4. +

    Use CoPilot mode (recommended for brownfield - better semantic understanding):

    + + 
    specfact --mode copilot import from-code --bundle legacy-api --repo . --confidence 0.7
+
    +
    5. +
  5. +

    For legacy codebases, start with minimal confidence and review extracted features:

    + + 
    specfact import from-code --bundle legacy-api --repo . --confidence 0.2
+
    +
    6. +
+ +
+ +

Sync Issues

+ +

Watch Mode Not Starting

+ +

Issue: Watch mode exits immediately or doesn’t detect changes

+ +

Solutions:

+ +
    +
  1. +

    Check repository path:

    + + 
    specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --watch --interval 5 --verbose
+
    +
    2. +
  2. +

    Verify directory exists:

    + + 
    ls -la .specify/
+ls -la .specfact/
+
    +
    3. +
  3. +

    Check permissions:

    + + 
    ls -la .specfact/projects/
+
    +
    4. +
  4. +

    Try one-time sync first:

    + + 
    specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
    +
    5. +
+ +

Bidirectional Sync Conflicts

+ +

Issue: Conflicts during bidirectional sync

+ +

Solutions:

+ +
    +
  1. +

    Check conflict resolution:

    + +
      +
    • SpecFact takes priority by default
      • +
    • Manual resolution may be needed
      • +
    +
    2. +
  2. +

    Review changes:

    + + 
    git status
+git diff
+
    +
    3. +
  3. +

    Use one-way sync:

    + + 
    # Spec-Kit → SpecFact only
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo .
+
+# SpecFact → Spec-Kit only (manual)
+# Edit Spec-Kit files manually
+
    +
    4. +
+ +
+ +

Enforcement Issues

+ +

Enforcement Not Working

+ +

Issue: Violations not being blocked or warned

+ +

Solutions:

+ +
    +
  1. +

    Check enforcement configuration (use CLI commands):

    + + 
    specfact enforce show-config
+
    +
    2. +
  2. +

    Verify enforcement mode:

    + + 
    specfact enforce stage --preset balanced
+
    +
    3. +
  3. +

    Run validation:

    + + 
    specfact repro --verbose
+
    +
    4. +
  4. +

    Check severity levels:

    + +
      +
    • HIGH → BLOCK (in balanced/strict mode)
      • +
    • MEDIUM → WARN (in balanced/strict mode)
      • +
    • LOW → LOG (in all modes)
      • +
    +
    5. +
+ +

False Positives

+ +

Issue: Valid code being flagged as violations

+ +

Solutions:

+ +
    +
  1. +

    Review violation details:

    + + 
    specfact repro --verbose
+
    +
    2. +
  2. +

    Adjust confidence threshold:

    + + 
    specfact import from-code --bundle legacy-api --repo . --confidence 0.7
+
    +
    3. +
  3. +

    Check enforcement rules (use CLI commands):

    + + 
    specfact enforce show-config
+
    +
    4. +
  4. +

    Use minimal mode (observe only):

    + + 
    specfact enforce stage --preset minimal
+
    +
    5. +
+ +
+ +

Constitution Issues

+ +

Constitution Missing or Minimal

+ +

Issue: Constitution required or Constitution is minimal when running sync bridge --adapter speckit

+ +

Solutions:

+ +
    +
  1. +

    Auto-generate bootstrap constitution (recommended for brownfield):

    + + 
    specfact sdd constitution bootstrap --repo .
+
    + +

    This analyzes your repository (README.md, pyproject.toml, .cursor/rules/, docs/rules/) and generates a bootstrap constitution.

    +
    2. +
  2. +

    Enrich existing minimal constitution:

    + + 
    specfact sdd constitution enrich --repo .
+
    + +

    This fills placeholders in an existing constitution with repository context.

    +
    3. +
  3. +

    Validate constitution completeness:

    + + 
    specfact sdd constitution validate
+
    + +

    This checks if the constitution is complete and ready for use.

    +
    4. +
  4. +

    Manual creation (for greenfield):

    + +
      +
    • Run /speckit.constitution command in your AI assistant
      • +
    • Fill in the constitution template manually
      • +
    +
    5. +
+ +

When to use each option:

+ +
    +
  • Bootstrap (brownfield): Use when you want to extract principles from existing codebase
    • +
  • Enrich (existing constitution): Use when you have a minimal constitution with placeholders
    • +
  • Manual (greenfield): Use when starting a new project and want full control
    • +
+ +

Constitution Validation Fails

+ +

Issue: specfact sdd constitution validate reports issues

+ +

Solutions:

+ +
    +
  1. +

    Check for placeholders:

    + + 
    grep -r "\[.*\]" .specify/memory/constitution.md
+
    +
    2. +
  2. +

    Run enrichment:

    + + 
    specfact sdd constitution enrich --repo .
+
    +
    3. +
  3. +

    Review validation output:

    + + 
    specfact sdd constitution validate --constitution .specify/memory/constitution.md
+
    + +

    The output will list specific issues (missing sections, placeholders, etc.).

    +
    4. +
  4. +

    Fix issues manually or re-run bootstrap:

    + + 
    specfact sdd constitution bootstrap --repo . --overwrite
+
    +
    5. +
+ +
+ +

Plan Comparison Issues

+ +

Plans Not Found

+ +

Issue: Plan not found when running plan compare

+ +

Solutions:

+ +
    +
  1. +

    Check plan locations:

    + + 
    ls -la .specfact/projects/
+ls -la .specfact/projects/<bundle-name>/reports/brownfield/
+
    +
    2. +
  2. +

    Use explicit paths (bundle directory paths):

    + + 
    specfact plan compare \
+  --manual .specfact/projects/manual-plan \
+  --auto .specfact/projects/auto-derived
+
    +
    3. +
  3. +

    Generate auto-derived plan first:

    + + 
    specfact import from-code --bundle legacy-api --repo .
+
    +
    4. +
+ +

No Deviations Found (Expected Some)

+ +

Issue: Comparison shows no deviations but you expect some

+ +

Solutions:

+ +
    +
  1. +

    Check feature key normalization:

    + +
      +
    • Different key formats may normalize to the same key
      • +
    • Check reference/feature-keys.md for details
      • +
    +
    2. +
  2. +

    Verify plan contents (use CLI commands):

    + + 
    specfact plan review <bundle-name>
+
    +
    3. +
  3. +

    Use verbose mode:

    + + 
    specfact plan compare --bundle legacy-api --verbose
+
    +
    4. +
+ +
+ +

IDE Integration Issues

+ +

Slash Commands Not Working

+ +

Issue: Slash commands not recognized in IDE

+ +

Solutions:

+ +
    +
  1. +

    Reinitialize IDE integration:

    + + 
    specfact init --ide cursor --force
+
    +
    2. +
  2. +

    Check command files:

    + + 
    ls -la .cursor/commands/specfact-*.md
+
    +
    3. +
  3. +

    Restart IDE: Some IDEs require restart to discover new commands

    +
    4. +
  4. +

    Check IDE settings:

    + +
      +
    • VS Code: Check .vscode/settings.json
      • +
    • Cursor: Check .cursor/settings.json
      • +
    +
    5. +
+ +

Command Files Not Created

+ +

Issue: Command files not created after specfact init

+ +

Solutions:

+ +
    +
  1. +

    Check permissions:

    + + 
    ls -la .cursor/commands/
+
    +
    2. +
  2. +

    Use force flag:

    + + 
    specfact init --ide cursor --force
+
    +
    3. +
  3. +

    Check IDE type:

    + + 
    specfact init --ide cursor  # For Cursor
+specfact init --ide vscode  # For VS Code
+
    +
    4. +
+ +
+ +

Mode Detection Issues

+ +

Wrong Mode Detected

+ +

Issue: CI/CD mode when CoPilot should be detected (or vice versa)

+ +

Solutions:

+ +
    +
  1. +

    Use explicit mode:

    + + 
    specfact --mode copilot import from-code my-project --repo .
+
    +
    2. +
  2. +

    Check environment variables:

    + + 
    echo $COPILOT_API_URL
+echo $VSCODE_PID
+
    +
    3. +
  3. +

    Set mode explicitly:

    + + 
    export SPECFACT_MODE=copilot
+specfact import from-code --bundle legacy-api --repo .
+
    +
    4. +
  4. +

    See Operational Modes for details

    +
    5. +
+ +
+ +

Performance Issues

+ +

Slow Analysis

+ +

Issue: Code analysis takes too long

+ +

Solutions:

+ +
    +
  1. +

    Use CI/CD mode (faster):

    + + 
    specfact --mode cicd import from-code my-project --repo .
+
    +
    2. +
  2. +

    Increase confidence threshold (fewer features):

    + + 
    specfact import from-code --bundle legacy-api --repo . --confidence 0.8
+
    +
    3. +
  3. +

    Exclude directories:

    + + 
    # Use .gitignore or exclude patterns
+specfact import from-code --bundle legacy-api --repo . --exclude "tests/"
+
    +
    4. +
+ +

Watch Mode High CPU

+ +

Issue: Watch mode uses too much CPU

+ +

Solutions:

+ +
    +
  1. +

    Increase interval:

    + + 
    specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --watch --interval 10
+
    +
    2. +
  2. +

    Use one-time sync:

    + + 
    specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
    +
    3. +
  3. +

    Check file system events:

    + +
      +
    • Too many files being watched
      • +
    • Consider excluding directories
      • +
    +
    4. +
+ +
+ +

Terminal Output Issues

+ +

SpecFact CLI automatically detects terminal capabilities and adjusts output formatting for optimal user experience across different environments. No manual configuration required - the CLI adapts to your terminal environment.

+ +

How Terminal Auto-Detection Works

+ +

The CLI automatically detects terminal capabilities in this order:

+ +
    +
  1. Test Mode Detection: +
      +
    • TEST_MODE=true or PYTEST_CURRENT_TEST → MINIMAL mode
      • +
    +
    2. +
  2. CI/CD Detection: +
      +
    • CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, TRAVIS, JENKINS_URL, BUILDKITE → BASIC mode
      • +
    +
    3. +
  3. Color Support Detection: +
      +
    • NO_COLOR → Disables colors (respects NO_COLOR standard)
      • +
    • FORCE_COLOR=1 → Forces colors
      • +
    • TERM and COLORTERM environment variables → Additional hints
      • +
    +
    4. +
  4. Terminal Type Detection: +
      +
    • TTY detection (sys.stdout.isatty()) → Interactive vs non-interactive
      • +
    • Interactive TTY with animations → GRAPHICAL mode
      • +
    • Non-interactive → BASIC mode
      • +
    +
    5. +
  5. Default Fallback: +
      +
    • If uncertain → BASIC mode (safe, readable output)
      • +
    +
    6. +
+ +

Terminal Modes

+ +

The CLI supports three terminal modes (auto-selected based on detection):

+ +
    +
  • GRAPHICAL - Full Rich features (colors, animations, progress bars) for interactive terminals
    • +
  • BASIC - Plain text, no animations, simple progress updates for CI/CD and embedded terminals
    • +
  • MINIMAL - Minimal output for test mode
    • +
+ +

Environment Variables (Optional Overrides)

+ +

You can override auto-detection using standard environment variables:

+ +
    +
  • NO_COLOR - Disables all colors (respects NO_COLOR standard)
    • +
  • FORCE_COLOR=1 - Forces color output even in non-interactive terminals
    • +
  • CI=true - Explicitly enables basic mode (no animations, plain text)
    • +
  • TEST_MODE=true - Enables minimal mode for testing
    • +
+ +

Examples

+ +
# Auto-detection (default behavior)
+specfact import from-code my-bundle
+# → Automatically detects terminal and uses appropriate mode
+
+# Manual override: Disable colors
+NO_COLOR=1 specfact import from-code my-bundle
+
+# Manual override: Force colors in CI/CD
+FORCE_COLOR=1 specfact sync bridge
+
+# Manual override: Explicit CI/CD mode
+CI=true specfact import from-code my-bundle
+
+ +

No Progress Visible in Embedded Terminals

+ +

Issue: No progress indicators visible when running commands in Cursor, VS Code, or other embedded terminals.

+ +

Cause: Embedded terminals are non-interactive and may not support Rich animations.

+ +

Solution: The CLI automatically detects embedded terminals and switches to basic mode with plain text progress updates. If you still don’t see progress:

+ +
    +
  1. +

    Verify auto-detection is working:

    + + 
    # Check terminal mode (should show BASIC in embedded terminals)
+python -c "from specfact_cli.runtime import get_terminal_mode; print(get_terminal_mode())"
+
    +
    2. +
  2. +

    Check environment variables:

    + + 
    # Ensure NO_COLOR is not set (unless you want plain text)
+unset NO_COLOR
+
    +
    3. +
  3. Verify terminal supports stdout: +
      +
    • Embedded terminals should support stdout (not stderr-only)
      • +
    • Progress updates are throttled - wait a few seconds for updates
      • +
    +
    4. +
  4. +

    Manual override (if needed):

    + + 
    # Force basic mode
+CI=true specfact import from-code my-bundle
+
    +
    5. +
+ +

Colors Not Working in CI/CD

+ +

Issue: No colors in CI/CD pipeline output.

+ +

Cause: CI/CD environments are automatically detected and use basic mode (no colors) for better log readability.

+ +

Solution: This is expected behavior. CI/CD logs are more readable without colors. To force colors:

+ +
FORCE_COLOR=1 specfact import from-code my-bundle
+
+ +
+ +

Getting Help

+ +

If you’re still experiencing issues:

+ +
    +
  1. +

    Check logs:

    + + 
    specfact repro --verbose 2>&1 | tee debug.log
+
    +
    2. +
  2. +

    Search documentation:

    + + +
    3. +
  3. +

    Community support:

    + + +
    4. +
  4. +

    Direct support:

    + + +
    5. +
+ +

Happy building! 🚀

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/use-cases/index.html b/_site_local/use-cases/index.html new file mode 100644 index 0000000..66f711d --- /dev/null +++ b/_site_local/use-cases/index.html @@ -0,0 +1,868 @@ + + + + + + + +Use Cases | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Use Cases

+ +

Detailed use cases and examples for SpecFact CLI.

+ +
+

Primary Use Case: Brownfield code modernization (Use Case 1)
+Secondary Use Case: Adding enforcement to Spec-Kit projects (Use Case 2)
+Alternative: Greenfield spec-first development (Use Case 3)

+
+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

+ +
+ +

Use Case 1: Brownfield Code Modernization ⭐ PRIMARY

+ +

Problem: Existing codebase with no specs, no documentation, or outdated documentation. Need to understand legacy code and add quality gates incrementally without breaking existing functionality.

+ +

Solution: Reverse engineer existing code into documented specs, then progressively enforce contracts to prevent regressions during modernization.

+ +

Steps

+ +

1. Analyze Code

+ +
# CI/CD mode (fast, deterministic) - Full repository
+specfact import from-code \
+  --repo . \
+  --shadow-only \
+  --confidence 0.7 \
+  --report analysis.md
+
+# Partial analysis (large codebases or monorepos)
+specfact import from-code \
+  --repo . \
+  --entry-point src/core \
+  --confidence 0.7 \
+  --name core-module \
+  --report analysis-core.md
+
+# CoPilot mode (enhanced prompts, interactive)
+specfact --mode copilot import from-code \
+  --repo . \
+  --confidence 0.7 \
+  --report analysis.md
+
+ +

With IDE Integration:

+ +
# First, initialize IDE integration
+specfact init --ide cursor
+
+# Then use slash command in IDE chat
+/specfact.01-import legacy-api --repo . --confidence 0.7
+
+ +

See IDE Integration Guide for setup instructions. See Integration Showcases for real examples of bugs fixed via IDE integrations.

+ +

What it analyzes (AI-First / CoPilot Mode):

+ +
    +
  • Semantic understanding of codebase (LLM)
    • +
  • Multi-language support (Python, TypeScript, JavaScript, PowerShell, etc.)
    • +
  • Actual priorities, constraints, unknowns from code context
    • +
  • Meaningful scenarios from acceptance criteria
    • +
  • High-quality Spec-Kit compatible artifacts
    • +
+ +

What it analyzes (AST-Based / CI/CD Mode):

+ +
    +
  • Module dependency graph (Python-only)
    • +
  • Commit history for feature boundaries
    • +
  • Test files for acceptance criteria
    • +
  • Type hints for API surfaces
    • +
  • Async patterns for anti-patterns
    • +
+ +

CoPilot Enhancement:

+ +
    +
  • Context injection (current file, selection, workspace)
    • +
  • Enhanced prompts for semantic understanding
    • +
  • Interactive assistance for complex codebases
    • +
  • Multi-language analysis support
    • +
+ +

2. Review Auto-Generated Plan

+ +
cat analysis.md
+
+ +

Expected sections:

+ +
    +
  • Features Detected - With confidence scores
    • +
  • Stories Inferred - From commit messages
    • +
  • API Surface - Public functions/classes
    • +
  • Async Patterns - Detected issues
    • +
  • State Machine - Inferred from code flow
    • +
+ +

3. Sync Repository Changes (Optional)

+ +

Keep plan artifacts updated as code changes:

+ +
# One-time sync
+specfact sync repository --repo . --target .specfact
+
+# Continuous watch mode
+specfact sync repository --repo . --watch --interval 5
+
+ +

What it tracks:

+ +
    +
  • Code changes → Plan artifact updates
    • +
  • Deviations from manual plans
    • +
  • Feature/story extraction from code
    • +
+ +

4. Compare with Manual Plan (if exists)

+ +
specfact plan compare \
+  --manual .specfact/projects/manual-plan \
+  --auto .specfact/projects/auto-derived \
+  --output-format markdown \
+  --out .specfact/projects/<bundle-name>/reports/comparison/deviation-report.md
+
+ +

With CoPilot:

+ +
# Use slash command in IDE chat (after specfact init)
+/specfact.compare --bundle legacy-api
+# Or with explicit paths: /specfact.compare --manual main.bundle.yaml --auto auto.bundle.yaml
+
+ +

CoPilot Enhancement:

+ +
    +
  • Deviation explanations
    • +
  • Fix suggestions
    • +
  • Interactive deviation review
    • +
+ +

Output:

+ +
# Deviation Report
+
+## Missing Features (in manual but not in auto)
+
+- FEATURE-003: User notifications
+  - Confidence: N/A (not detected in code)
+  - Recommendation: Implement or remove from manual plan
+
+## Extra Features (in auto but not in manual)
+
+- FEATURE-AUTO-001: Database migrations
+  - Confidence: 0.85
+  - Recommendation: Add to manual plan
+
+## Mismatched Stories
+
+- STORY-001: User login
+  - Manual acceptance: "OAuth 2.0 support"
+  - Auto acceptance: "Basic auth only"
+  - Severity: HIGH
+  - Recommendation: Update implementation or manual plan
+
+ +

5. Fix High-Severity Deviations

+ +

Focus on:

+ +
    +
  • Async anti-patterns - Blocking I/O in async functions
    • +
  • Missing contracts - APIs without validation
    • +
  • State machine gaps - Unreachable states
    • +
  • Test coverage - Missing acceptance tests
    • +
+ +

6. Progressive Enforcement

+ +
# Week 1-2: Shadow mode (observe)
+specfact enforce stage --preset minimal
+
+# Week 3-4: Balanced mode (warn on medium, block high)
+specfact enforce stage --preset balanced
+
+# Week 5+: Strict mode (block medium+)
+specfact enforce stage --preset strict
+
+ +

Expected Timeline (Brownfield Modernization)

+ +
    +
  • Analysis: 2-5 minutes
    • +
  • Review: 1-2 hours
    • +
  • High-severity fixes: 1-3 days
    • +
  • Shadow mode: 1-2 weeks
    • +
  • Production enforcement: After validation stabilizes
    • +
+ +
+ +

Use Case 2: GitHub Spec-Kit Migration (Secondary)

+ +

Problem: You have a Spec-Kit project but need automated enforcement, team collaboration, and production deployment quality gates.

+ +

Solution: Import Spec-Kit artifacts into SpecFact CLI for automated contract enforcement while keeping Spec-Kit for interactive authoring.

+ +

Steps (Spec-Kit Migration)

+ +

1. Preview Migration

+ +
specfact import from-bridge --adapter speckit --repo ./spec-kit-project --dry-run
+
+ +

Expected Output:

+ +
🔍 Analyzing Spec-Kit project via bridge adapter...
+✅ Found .specify/ directory (modern format)
+✅ Found specs/001-user-authentication/spec.md
+✅ Found specs/001-user-authentication/plan.md
+✅ Found specs/001-user-authentication/tasks.md
+✅ Found .specify/memory/constitution.md
+
+📊 Migration Preview:
+  - Will create: .specfact/projects/<bundle-name>/ (modular project bundle)
+  - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected)
+  - Will create: .specfact/gates/config.yaml
+  - Will convert: Spec-Kit features → SpecFact Feature models
+  - Will convert: Spec-Kit user stories → SpecFact Story models
+  
+🚀 Ready to migrate (use --write to execute)
+
+ +

2. Execute Migration

+ +
specfact import from-bridge \
+  --adapter speckit \
+  --repo ./spec-kit-project \
+  --write \
+  --report migration-report.md
+
+ +

3. Review Generated Contracts

+ +
# Review using CLI commands
+specfact plan review <bundle-name>
+
+ +

Review:

+ +
    +
  • .specfact/projects/<bundle-name>/ - Modular project bundle (converted from Spec-Kit artifacts)
    • +
  • .specfact/protocols/workflow.protocol.yaml - FSM definition (if protocol detected)
    • +
  • .specfact/enforcement/config.yaml - Quality gates configuration
    • +
  • .semgrep/async-anti-patterns.yaml - Anti-pattern rules (if async patterns detected)
    • +
  • .github/workflows/specfact-gate.yml - CI workflow (optional)
    • +
+ +

4: Generate Constitution (If Missing)

+ +

Before syncing, ensure you have a valid constitution:

+ +
# Auto-generate from repository analysis (recommended for brownfield)
+specfact sdd constitution bootstrap --repo .
+
+# Validate completeness
+specfact sdd constitution validate
+
+# Or enrich existing minimal constitution
+specfact sdd constitution enrich --repo .
+
+ +

Note: The sync bridge --adapter speckit command will detect if the constitution is missing or minimal and suggest bootstrap automatically.

+ +

5. Enable Bidirectional Sync (Optional)

+ +

Keep Spec-Kit and SpecFact synchronized:

+ +
# One-time bidirectional sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Continuous watch mode
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+ +

What it syncs:

+ +
    +
  • specs/[###-feature-name]/spec.md, plan.md, tasks.md ↔ .specfact/projects/<bundle-name>/ aspect files
    • +
  • .specify/memory/constitution.md ↔ SpecFact business context
    • +
  • specs/[###-feature-name]/research.md, data-model.md, quickstart.md ↔ SpecFact supporting artifacts
    • +
  • specs/[###-feature-name]/contracts/*.yaml ↔ SpecFact protocol definitions
    • +
  • Automatic conflict resolution with priority rules
    • +
+ +

6. Enable Enforcement

+ +
# Start in shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# After stabilization, enable warnings
+specfact enforce stage --preset balanced
+
+# For production, enable strict mode
+specfact enforce stage --preset strict
+
+ +

7. Validate

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Run validation
+specfact repro --verbose
+
+ +

Expected Timeline (Spec-Kit Migration)

+ +
    +
  • Preview: < 1 minute
    • +
  • Migration: 2-5 minutes
    • +
  • Review: 15-30 minutes
    • +
  • Stabilization: 1-2 weeks (shadow mode)
    • +
  • Production: After validation passes
    • +
+ +
+ +

Use Case 3: Greenfield Spec-First Development (Alternative)

+ +

Problem: Starting a new project, want contract-driven development from day 1.

+ +

Solution: Use SpecFact CLI for spec-first planning and strict enforcement.

+ +

Steps (Greenfield Development)

+ +

1. Create Plan Interactively

+ +
# Standard interactive mode
+specfact plan init --interactive
+
+# CoPilot mode (enhanced prompts)
+specfact --mode copilot plan init --interactive
+
+ +

With CoPilot (IDE Integration):

+ +
# Use slash command in IDE chat (after specfact init)
+/specfact.02-plan init legacy-api
+# Or update idea: /specfact.02-plan update-idea --bundle legacy-api --title "My Project"
+
+ +

Interactive prompts:

+ +
🎯 SpecFact CLI - Plan Initialization
+
+What's your idea title?
+> Real-time collaboration platform
+
+What's the narrative? (high-level vision)
+> Enable teams to collaborate in real-time with contract-driven quality
+
+What are the product themes? (comma-separated)
+> Developer Experience, Real-time Sync, Quality Assurance
+
+What's the first release name?
+> v0.1
+
+What are the release objectives? (comma-separated)
+> WebSocket server, Client SDK, Basic presence
+
+✅ Plan initialized: .specfact/projects/<bundle-name>/
+
+ +

2. Add Features and Stories

+ +
# Add feature
+specfact plan add-feature \
+  --key FEATURE-001 \
+  --title "WebSocket Server" \
+  --outcomes "Handle 1000 concurrent connections" \
+  --outcomes "< 100ms message latency" \
+  --acceptance "Given client connection, When message sent, Then delivered within 100ms"
+
+# Add story
+specfact plan add-story \
+  --feature FEATURE-001 \
+  --key STORY-001 \
+  --title "Connection handling" \
+  --acceptance "Accept WebSocket connections" \
+  --acceptance "Maintain heartbeat every 30s" \
+  --acceptance "Graceful disconnect cleanup"
+
+ +

3. Define Protocol

+ +

Create contracts/protocols/workflow.protocol.yaml:

+ +
states:
+  - DISCONNECTED
+  - CONNECTING
+  - CONNECTED
+  - RECONNECTING
+  - DISCONNECTING
+
+start: DISCONNECTED
+
+transitions:
+  - from_state: DISCONNECTED
+    on_event: connect
+    to_state: CONNECTING
+
+  - from_state: CONNECTING
+    on_event: connection_established
+    to_state: CONNECTED
+    guard: handshake_valid
+
+  - from_state: CONNECTED
+    on_event: connection_lost
+    to_state: RECONNECTING
+    guard: should_reconnect
+
+  - from_state: RECONNECTING
+    on_event: reconnect_success
+    to_state: CONNECTED
+
+  - from_state: CONNECTED
+    on_event: disconnect
+    to_state: DISCONNECTING
+
+ +

4. Enable Strict Enforcement

+ +
specfact enforce stage --preset strict
+
+ +

5. Validate Continuously

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# During development
+specfact repro
+
+# In CI/CD
+specfact repro --budget 120 --verbose
+
+ +

Expected Timeline (Greenfield Development)

+ +
    +
  • Planning: 1-2 hours
    • +
  • Protocol design: 30 minutes
    • +
  • Implementation: Per feature/story
    • +
  • Validation: Continuous (< 90s per check)
    • +
+ +
+ +

Use Case 4: CI/CD Integration

+ +

Problem: Need automated quality gates in pull requests.

+ +

Solution: Add SpecFact GitHub Action to PR workflow.

+ +

Terminal Output: The CLI automatically detects CI/CD environments and uses plain text output (no colors, no animations) for better log readability. Progress updates are visible in CI/CD logs. See Troubleshooting for details.

+ +

Steps (CI/CD Integration)

+ +

1. Add GitHub Action

+ +

Create .github/workflows/specfact.yml:

+ +
name: SpecFact CLI Validation
+
+on:
+  pull_request:
+    branches: [main, dev]
+  push:
+    branches: [main, dev]
+  workflow_dispatch:
+    inputs:
+      budget:
+        description: "Time budget in seconds"
+        required: false
+        default: "90"
+        type: string
+
+jobs:
+  specfact-validation:
+    name: Contract Validation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      checks: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install SpecFact CLI
+        run: pip install specfact-cli
+
+      - name: Set up CrossHair Configuration
+        run: specfact repro setup
+
+      - name: Run Contract Validation
+        run: specfact repro --verbose --budget 90
+
+      - name: Generate PR Comment
+        if: github.event_name == 'pull_request'
+        run: python -m specfact_cli.utils.github_annotations
+        env:
+          SPECFACT_REPORT_PATH: .specfact/projects/<bundle-name>/reports/enforcement/report-*.yaml
+
+ +

Features:

+ +
    +
  • ✅ PR annotations for violations
    • +
  • ✅ PR comments with violation summaries
    • +
  • ✅ Auto-fix suggestions in PR comments
    • +
  • ✅ Budget-based blocking
    • +
  • ✅ Manual workflow dispatch support
    • +
+ +

2. Configure Enforcement

+ +

Create .specfact.yaml:

+ +
version: "1.0"
+
+enforcement:
+  preset: balanced  # Block HIGH, warn MEDIUM
+
+repro:
+  budget: 120
+  parallel: true
+  fail_fast: false
+
+analysis:
+  confidence_threshold: 0.7
+  exclude_patterns:
+    - "**/__pycache__/**"
+    - "**/node_modules/**"
+
+ +

3. Test Locally

+ +
# Before pushing
+specfact repro --verbose
+
+# Apply auto-fixes for violations
+specfact repro --fix --verbose
+
+# If issues found
+specfact enforce stage --preset minimal  # Temporarily allow
+# Fix issues
+specfact enforce stage --preset balanced  # Re-enable
+
+ +

4. Monitor PR Checks

+ +

The GitHub Action will:

+ +
    +
  • Run contract validation
    • +
  • Check for async anti-patterns
    • +
  • Validate state machine transitions
    • +
  • Generate deviation reports
    • +
  • Block PR if HIGH severity issues found
    • +
+ +

Expected Results

+ +
    +
  • Clean PRs: Pass in < 90s
    • +
  • Blocked PRs: Clear deviation report
    • +
  • False positives: < 5% (use override mechanism)
    • +
+ +
+ +

Use Case 5: Multi-Repository Consistency

+ +

Problem: Multiple microservices need consistent contract enforcement.

+ +

Solution: Share common plan bundle and enforcement config.

+ +

Steps (Multi-Repository)

+ +

1. Create Shared Plan Bundle

+ +

In a shared repository:

+ +
# Create shared plan
+specfact plan init --interactive
+
+# Add common features
+specfact plan add-feature \
+  --key FEATURE-COMMON-001 \
+  --title "API Standards" \
+  --outcomes "Consistent REST patterns" \
+  --outcomes "Standardized error responses"
+
+ +

2. Distribute to Services

+ +
# In each microservice
+git submodule add https://github.com/org/shared-contracts contracts/shared
+
+# Or copy files
+cp ../shared-contracts/plan.bundle.yaml contracts/shared/
+
+ +

3. Validate Against Shared Plan

+ +
# In each service
+specfact plan compare \
+  --manual contracts/shared/plan.bundle.yaml \
+  --auto contracts/service/plan.bundle.yaml \
+  --output-format markdown
+
+ +

4. Enforce Consistency

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Add to CI
+specfact repro
+specfact plan compare --manual contracts/shared/plan.bundle.yaml --auto .
+
+ +

Expected Benefits

+ +
    +
  • Consistency: All services follow same patterns
    • +
  • Reusability: Shared contracts and protocols
    • +
  • Maintainability: Update once, apply everywhere
    • +
+ +
+ +

See Commands for detailed command reference and Getting Started for quick setup.

+ +

Integration Examples

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_local/ux-features/index.html b/_site_local/ux-features/index.html new file mode 100644 index 0000000..e99e6e9 --- /dev/null +++ b/_site_local/ux-features/index.html @@ -0,0 +1,552 @@ + + + + + + + +UX Features Guide | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

UX Features Guide

+ +

This guide covers the user experience features that make SpecFact CLI intuitive and efficient.

+ +

Progressive Disclosure

+ +

SpecFact CLI uses progressive disclosure to show the most important options first, while keeping advanced options accessible when needed. This reduces cognitive load for new users while maintaining full functionality for power users.

+ +

Regular Help

+ +

By default, --help shows only the most commonly used options:

+ +
specfact import from-code --help
+
+ +

This displays:

+ +
    +
  • Required arguments
    • +
  • Common options (bundle, repo, output)
    • +
  • Behavior flags (interactive, verbose, dry-run, force)
    • +
  • Essential workflow options
    • +
+ +

Advanced Help

+ +

To see all options including advanced configuration, use --help-advanced (alias: -ha):

+ +
specfact import from-code --help-advanced
+
+ +

This reveals:

+ +
    +
  • Advanced configuration options: Confidence thresholds, key formats, adapter types
    • +
  • Fine-tuning parameters: Watch intervals, time budgets, session limits
    • +
  • Expert-level settings: Taxonomy filtering, content hash matching, backward compatibility checks
    • +
  • CI/CD automation options: Non-interactive JSON inputs, exact name matching
    • +
+ +

Hidden Options Summary

+ +

The following options are hidden by default across commands:

+ +

Import Commands:

+ +
    +
  • --entry-point - Partial analysis (subdirectory only)
    • +
  • --enrichment - LLM enrichment workflow
    • +
  • --adapter - Adapter type configuration (auto-detected)
    • +
  • --confidence - Feature detection threshold
    • +
  • --key-format - Feature key format (classname vs sequential)
    • +
+ +

Sync Commands:

+ +
    +
  • --adapter - Adapter type configuration (auto-detected)
    • +
  • --interval - Watch mode interval tuning
    • +
  • --confidence - Feature detection threshold
    • +
+ +

Plan Commands:

+ +
    +
  • --max-questions - Review session limit
    • +
  • --category - Taxonomy category filtering
    • +
  • --findings-format - Output format for findings
    • +
  • --answers - Non-interactive JSON input
    • +
  • --stages - Filter by promotion stages
    • +
  • --last - Show last N plans
    • +
  • --current - Show only active plan
    • +
  • --name - Exact bundle name matching
    • +
  • --id - Content hash ID matching
    • +
+ +

Spec Commands:

+ +
    +
  • --previous - Backward compatibility check
    • +
+ +

Other Commands:

+ +
    +
  • repro --budget - Time budget configuration
    • +
  • generate contracts-prompt --output - Custom output path
    • +
  • init --ide - IDE selection override (auto-detection works)
    • +
+ +

Tip: Advanced options are still functional even when hidden - you can use them directly without --help-advanced/-ha. The flag only affects what’s shown in help text.

+ +

Example:

+ +
# This works even though --confidence is hidden in regular help:
+specfact import from-code my-bundle --confidence 0.7 --key-format sequential
+
+# To see all options in help:
+specfact import from-code --help-advanced  # or -ha
+
+ +

Context Detection

+ +

SpecFact CLI automatically detects your project context to provide smart defaults and suggestions.

+ +

Auto-Detection

+ +

When you run commands, SpecFact automatically detects:

+ +
    +
  • Project Type: Python, JavaScript, etc.
    • +
  • Framework: FastAPI, Django, Flask, etc.
    • +
  • Existing Specs: OpenAPI/AsyncAPI specifications
    • +
  • Plan Bundles: Existing SpecFact project bundles
    • +
  • Configuration: Specmatic configuration files
    • +
+ +

Smart Defaults

+ +

Based on detected context, SpecFact provides intelligent defaults:

+ +
# If OpenAPI spec detected, suggests validation
+specfact spec validate --bundle <auto-detected>
+
+# If low contract coverage detected, suggests analysis
+specfact analyze --bundle <auto-detected>
+
+ +

Explicit Context

+ +

You can also explicitly check your project context:

+ +
# Context detection is automatic, but you can verify
+specfact import from-code --bundle my-bundle --repo .
+# CLI automatically detects Python, FastAPI, existing specs, etc.
+
+ +

Intelligent Suggestions

+ +

SpecFact provides context-aware suggestions to guide your workflow.

+ +

Next Steps

+ +

After running commands, SpecFact suggests logical next steps:

+ +
$ specfact import from-code --bundle legacy-api
+✓ Import complete
+
+💡 Suggested next steps:
+  • specfact analyze --bundle legacy-api  # Analyze contract coverage
+  • specfact enforce sdd --bundle legacy-api  # Enforce quality gates
+  • specfact sync intelligent --bundle legacy-api  # Sync code and specs
+
+ +

Error Fixes

+ +

When errors occur, SpecFact suggests specific fixes:

+ +
$ specfact analyze --bundle missing-bundle
+✗ Error: Bundle 'missing-bundle' not found
+
+💡 Suggested fixes:
+  • specfact plan select  # Select an active plan bundle
+  • specfact import from-code --bundle missing-bundle  # Create a new bundle
+
+ +

Improvements

+ +

Based on analysis, SpecFact suggests improvements:

+ +
$ specfact analyze --bundle legacy-api
+⚠ Low contract coverage detected (30%)
+
+💡 Suggested improvements:
+  • specfact analyze --bundle legacy-api  # Identify missing contracts
+  • specfact import from-code --bundle legacy-api  # Extract contracts from code
+
+ +

Template-Driven Quality

+ +

SpecFact uses templates to ensure high-quality, consistent specifications.

+ +

Feature Specification Templates

+ +

When creating features, templates guide you to focus on:

+ +
    +
  • WHAT users need (not HOW to implement)
    • +
  • WHY the feature is valuable
    • +
  • Uncertainty markers for ambiguous requirements: [NEEDS CLARIFICATION: specific question]
    • +
  • Completeness checklists to ensure nothing is missed
    • +
+ +

Implementation Plan Templates

+ +

Implementation plans follow templates that:

+ +
    +
  • Keep high-level steps readable
    • +
  • Extract detailed algorithms to separate files
    • +
  • Enforce test-first thinking (contracts → tests → implementation)
    • +
  • Include phase gates for architectural principles
    • +
+ +

Contract Extraction Templates

+ +

Contract extraction uses templates to:

+ +
    +
  • Extract contracts from legacy code patterns
    • +
  • Identify validation logic
    • +
  • Map to formal contracts (icontract, beartype)
    • +
  • Mark uncertainties for later clarification
    • +
+ +

Enhanced Watch Mode

+ +

Watch mode has been enhanced with intelligent change detection.

+ +

Hash-Based Detection

+ +

Watch mode only processes files that actually changed:

+ +
specfact sync intelligent --bundle my-bundle --watch
+
+ +

Features:

+ +
    +
  • SHA256 hash-based change detection
    • +
  • Only processes files with actual content changes
    • +
  • Skips unchanged files (even if modified timestamp changed)
    • +
  • Faster sync operations
    • +
+ +

Dependency Tracking

+ +

Watch mode tracks file dependencies:

+ +
    +
  • Identifies dependent files
    • +
  • Processes dependencies when source files change
    • +
  • Incremental processing (only changed files and dependencies)
    • +
+ +

Cache Optimization

+ +

Watch mode uses an optimized cache:

+ +
    +
  • LZ4 compression (when available) for faster I/O
    • +
  • Persistent cache across sessions
    • +
  • Automatic cache management
    • +
+ +

Unified Progress Display

+ +

All commands use consistent progress indicators that automatically adapt to your terminal environment.

+ +

Progress Format

+ +

Progress displays use a consistent n/m format:

+ +
Loading artifact 3/12: FEATURE-001.yaml
+
+ +

This shows:

+ +
    +
  • Current item number (3)
    • +
  • Total items (12)
    • +
  • Current artifact name (FEATURE-001.yaml)
    • +
  • Elapsed time
    • +
+ +

Automatic Terminal Adaptation

+ +

The CLI automatically detects terminal capabilities and adjusts progress display:

+ +
    +
  • Interactive terminals → Full Rich progress with animations, colors, and progress bars
    • +
  • Embedded terminals (Cursor, VS Code) → Plain text progress updates (no animations)
    • +
  • CI/CD pipelines → Plain text progress updates for readable logs
    • +
  • Test mode → Minimal output
    • +
+ +

No manual configuration required - the CLI adapts automatically. See Troubleshooting for details.

+ +

Visibility

+ +

Progress is shown for:

+ +
    +
  • All bundle load/save operations
    • +
  • Long-running operations (>1 second)
    • +
  • File processing operations
    • +
  • Analysis operations
    • +
+ +

No “dark” periods - you always know what’s happening, regardless of terminal type.

+ +

Best Practices

+ +

Using Progressive Disclosure

+ +
    +
  1. Start with regular help - Most users only need common options
    2. +
  2. Use --help-advanced (-ha) when you need fine-grained control
    3. +
  3. Advanced options work without help - You can use them directly
    4. +
+ +

Leveraging Context Detection

+ +
    +
  1. Let SpecFact auto-detect - It’s usually correct
    2. +
  2. Verify context - Check suggestions match your project
    3. +
  3. Use explicit flags - Override auto-detection when needed
    4. +
+ +

Following Suggestions

+ +
    +
  1. Read suggestions carefully - They’re context-aware
    2. +
  2. Follow the workflow - Suggestions guide logical next steps
    3. +
  3. Use error suggestions - They provide specific fixes
    4. +
+ +

Using Templates

+ +
    +
  1. Follow template structure - Ensures quality and consistency
    2. +
  2. Mark uncertainties - Use [NEEDS CLARIFICATION] markers
    3. +
  3. Complete checklists - Templates include completeness checks
    4. +
+ +
+ +

Related Documentation:

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/LICENSE.md b/_site_test/LICENSE.md new file mode 100644 index 0000000..dd8dba5 --- /dev/null +++ b/_site_test/LICENSE.md @@ -0,0 +1,202 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (which shall not include Communications that are clearly marked or + otherwise designated in writing by the copyright owner as "Not a Work"). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is clearly marked or otherwise designated + in writing by the copyright owner as "Not a Contribution". + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2025 Nold AI (Owner: Dominikus Nold) + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/_site_test/README.md b/_site_test/README.md new file mode 100644 index 0000000..ba58b30 --- /dev/null +++ b/_site_test/README.md @@ -0,0 +1,236 @@ +# SpecFact CLI Documentation + +> **Everything you need to know about using SpecFact CLI** + +--- + +## Why SpecFact? + +### **Built for Real-World Agile Teams** + +SpecFact isn't just a technical tool—it's designed for **real-world agile/scrum teams** with role-based workflows: + +- 👤 **Product Owners** → Work with backlog, DoR checklists, prioritization, dependencies, and sprint planning +- 🏗️ **Architects** → Work with technical constraints, protocols, contracts, architectural decisions, and risk assessments +- 💻 **Developers** → Work with implementation tasks, code mappings, test scenarios, and Definition of Done criteria + +**Each role works in their own Markdown files** (no YAML editing), and SpecFact syncs everything together automatically. Perfect for teams using agile/scrum practices with clear role separation. + +👉 **[Agile/Scrum Workflows Guide](guides/agile-scrum-workflows.md)** ⭐ **START HERE** - Complete guide to persona-based team collaboration + +--- + +### **Love GitHub Spec-Kit or OpenSpec? SpecFact Adds What's Missing** + +**Use together:** Keep using Spec-Kit for new features, OpenSpec for change tracking, add SpecFact for legacy code modernization. + +**If you've tried GitHub Spec-Kit or OpenSpec**, you know they're great for documenting new features and tracking changes. SpecFact adds what's missing for legacy code modernization: + +👉 **[OpenSpec Journey Guide](guides/openspec-journey.md)** 🆕 ⭐ - Complete integration guide with DevOps export, visual workflows, and brownfield modernization examples + +- ✅ **Runtime contract enforcement** → Spec-Kit/OpenSpec generate docs; SpecFact prevents regressions with executable contracts +- ✅ **Brownfield-first** → Spec-Kit/OpenSpec excel at new features; SpecFact understands existing code +- ✅ **Formal verification** → Spec-Kit/OpenSpec use LLM suggestions; SpecFact uses mathematical proof (CrossHair) +- ✅ **Team collaboration** → Spec-Kit is single-user focused; SpecFact supports persona-based workflows for agile teams +- ✅ **DevOps integration** → Bridge adapters sync change proposals to GitHub Issues, ADO, Linear, Jira +- ✅ **GitHub Actions integration** → Works seamlessly with your existing GitHub workflows + +**Perfect together:** + +- ✅ **Spec-Kit** for new features → Fast spec generation with Copilot +- ✅ **OpenSpec** for change tracking → Specification anchoring and delta tracking +- ✅ **SpecFact** for legacy code → Runtime enforcement prevents regressions +- ✅ **Bridge adapters** → Sync between all tools automatically +- ✅ **Team workflows** → SpecFact adds persona-based collaboration for agile/scrum teams + +**Bottom line:** Use Spec-Kit for documenting new features. Use OpenSpec for change tracking. Use SpecFact for modernizing legacy code safely and enabling team collaboration. Use all three together for the best of all worlds. + +👉 **[See detailed comparison](guides/speckit-comparison.md)** | **[Journey from Spec-Kit](guides/speckit-journey.md)** | **[OpenSpec Journey](guides/openspec-journey.md)** 🆕 | **[Integrations Overview](guides/integrations-overview.md)** 🆕 | **[Bridge Adapters](reference/commands.md#sync-bridge)** + +--- + +## 🎯 Find Your Path + +### New to SpecFact? + +**Primary Goal**: Analyze legacy Python → find gaps → enforce contracts + +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. **[See It In Action](examples/dogfooding-specfact-cli.md)** - Real example (< 10 seconds) +5. **[Use Cases](guides/use-cases.md)** - Common scenarios + +**Time**: < 10 minutes | **Result**: Running your first brownfield analysis + +--- + +### Using AI IDEs? (Cursor, Copilot, Claude) 🆕 + +**Primary Goal**: Let SpecFact find gaps, use your AI IDE to fix them + +```bash +# 1. Run brownfield analysis and validation +specfact import from-code my-project --repo . +specfact repro --verbose + +# 2. Generate AI-ready prompt for a specific gap +specfact generate fix-prompt GAP-001 --bundle my-project + +# 3. Copy to AI IDE → AI generates fix → Validate with SpecFact +specfact enforce sdd --bundle my-project +``` + +**Why this approach?** + +- ✅ **You control the AI** - Use your preferred AI model +- ✅ **SpecFact validates** - Ensure AI-generated code meets contracts +- ✅ **No lock-in** - Works with any AI IDE + +👉 **[Command Reference - Generate Commands](reference/commands.md#generate---generate-artifacts)** - `fix-prompt` and `test-prompt` commands + +--- + +### Working with an Agile/Scrum Team? + +**Primary Goal**: Enable team collaboration with role-based workflows + +1. **[Agile/Scrum Workflows](guides/agile-scrum-workflows.md)** ⭐ **START HERE** - Persona-based team collaboration +2. **[Command Reference - Project Commands](reference/commands.md#project---project-bundle-management)** - `project export` and `project import` commands +3. **[Persona Workflows](guides/agile-scrum-workflows.md#persona-based-workflows)** - How Product Owners, Architects, and Developers work together +4. **[Definition of Ready](guides/agile-scrum-workflows.md#definition-of-ready-dor)** - DoR validation and sprint planning + +**Time**: 15-30 minutes | **Result**: Understanding how your team can collaborate with SpecFact + +--- + +### Love GitHub Spec-Kit or OpenSpec? + +**Why SpecFact?** Keep using Spec-Kit for new features, OpenSpec for change tracking, add SpecFact for legacy code modernization. + +**Use together:** + +- ✅ **Spec-Kit** for new features → Fast spec generation with Copilot +- ✅ **OpenSpec** for change tracking → Specification anchoring and delta tracking +- ✅ **SpecFact** for legacy code → Runtime enforcement prevents regressions +- ✅ **Bridge adapters** → Sync between all tools automatically +- ✅ **GitHub Actions** → SpecFact integrates with your existing GitHub workflows + +1. **[Tutorial: Using SpecFact with OpenSpec or Spec-Kit](getting-started/tutorial-openspec-speckit.md)** ⭐ **START HERE** - Complete beginner-friendly step-by-step tutorial +2. **[How SpecFact Compares to Spec-Kit](guides/speckit-comparison.md)** - See what SpecFact adds +3. **[The Journey: From Spec-Kit to SpecFact](guides/speckit-journey.md)** - Add enforcement to Spec-Kit projects +4. **[The Journey: OpenSpec + SpecFact Integration](guides/openspec-journey.md)** 🆕 - Complete OpenSpec integration guide with DevOps export (✅) and bridge adapter (✅) +5. **[DevOps Adapter Integration](guides/devops-adapter-integration.md)** - GitHub Issues and backlog tracking +6. **[Bridge Adapters](reference/commands.md#sync-bridge)** - OpenSpec and DevOps integration +7. **[Migration Use Case](guides/use-cases.md#use-case-2-github-spec-kit-migration)** - Step-by-step +8. **[Bidirectional Sync](guides/use-cases.md#use-case-2-github-spec-kit-migration)** - Keep both tools in sync + +**Time**: 15-30 minutes | **Result**: Understand how SpecFact complements Spec-Kit and OpenSpec for legacy code modernization + +--- + +### Using SpecFact Daily? + +**Goal**: Use SpecFact effectively in your workflow + +1. **[Command Chains Reference](guides/command-chains.md)** ⭐ **NEW** - Complete workflows and command sequences +2. **[Common Tasks Index](guides/common-tasks.md)** ⭐ **NEW** - Quick "How do I X?" reference +3. **[Command Reference](reference/commands.md)** - All commands with examples +4. **[Use Cases](guides/use-cases.md)** - Real-world scenarios +5. **[IDE Integration](guides/ide-integration.md)** - Set up slash commands +6. **[CoPilot Mode](guides/copilot-mode.md)** - Enhanced prompts + +**Time**: 30-60 minutes | **Result**: Master daily workflows + +--- + +### Contributing to SpecFact? + +**Goal**: Understand internals and contribute + +1. **[Architecture](reference/architecture.md)** - Technical design +2. **[Development Setup](getting-started/installation.md#development-setup)** - Local setup +3. **[Testing Procedures](technical/testing.md)** - How we test +4. **[Technical Deep Dives](technical/README.md)** - Implementation details + +**Time**: 2-4 hours | **Result**: Ready to contribute + +--- + +## 📚 Documentation Sections + +### Getting Started + +- [Installation](getting-started/installation.md) - All installation options +- [Enhanced Analysis Dependencies](installation/enhanced-analysis-dependencies.md) - Optional dependencies for graph-based analysis +- [First Steps](getting-started/first-steps.md) - Step-by-step first commands + +### User Guides + +#### Primary Use Case: Brownfield Modernization ⭐ + +- [Brownfield Engineer Guide](guides/brownfield-engineer.md) ⭐ **PRIMARY** - Complete modernization guide +- [The Brownfield Journey](guides/brownfield-journey.md) ⭐ **PRIMARY** - Step-by-step workflow +- [Brownfield ROI](guides/brownfield-roi.md) ⭐ - Calculate savings +- [Use Cases](guides/use-cases.md) ⭐ - Real-world scenarios (brownfield primary) + +#### Secondary Use Case: Spec-Kit & OpenSpec Integration + +- [Spec-Kit Journey](guides/speckit-journey.md) - Add enforcement to Spec-Kit projects +- [Spec-Kit Comparison](guides/speckit-comparison.md) - Understand when to use each tool +- [OpenSpec Journey](guides/openspec-journey.md) 🆕 - OpenSpec integration with SpecFact (DevOps export ✅, bridge adapter ⏳) +- [DevOps Adapter Integration](guides/devops-adapter-integration.md) - GitHub Issues, backlog tracking, and progress comments +- [Bridge Adapters](reference/commands.md#sync-bridge) - OpenSpec and DevOps integration + +#### Team Collaboration & Agile/Scrum + +- [Agile/Scrum Workflows](guides/agile-scrum-workflows.md) ⭐ **NEW** - Persona-based team collaboration with Product Owners, Architects, and Developers +- [Persona Workflows](guides/agile-scrum-workflows.md#persona-based-workflows) - Role-based workflows for agile teams +- [Definition of Ready](guides/agile-scrum-workflows.md#definition-of-ready-dor) - DoR validation and sprint planning +- [Dependency Management](guides/agile-scrum-workflows.md#dependency-management) - Track story and feature dependencies +- [Conflict Resolution](guides/agile-scrum-workflows.md#conflict-resolution) - Persona-aware merge conflict resolution + +#### General Guides + +- [UX Features](guides/ux-features.md) - Progressive disclosure, context detection, intelligent suggestions, templates +- [Workflows](guides/workflows.md) - Common daily workflows +- [IDE Integration](guides/ide-integration.md) - Slash commands +- [CoPilot Mode](guides/copilot-mode.md) - Enhanced prompts +- [Troubleshooting](guides/troubleshooting.md) - Common issues and solutions + +### Reference + +- [Commands](reference/commands.md) - Complete command reference +- [Architecture](reference/architecture.md) - Technical design +- [Operational Modes](reference/modes.md) - CI/CD vs CoPilot modes +- [Telemetry](reference/telemetry.md) - Privacy-first, opt-in analytics +- [Feature Keys](reference/feature-keys.md) - Key normalization +- [Directory Structure](reference/directory-structure.md) - Project layout + +### Examples + +- [Dogfooding Example](examples/dogfooding-specfact-cli.md) - Main example +- [Quick Examples](examples/quick-examples.md) - Code snippets + +### Technical + +- [Code2Spec Analysis](technical/code2spec-analysis-logic.md) - AI-first approach +- [Testing Procedures](technical/testing.md) - Testing guidelines + +--- + +## 🆘 Getting Help + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) + +--- + +**Happy building!** 🚀 + +--- + +Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold) + +**Trademarks**: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](../TRADEMARKS.md) for more information. diff --git a/_site_test/TRADEMARKS.md b/_site_test/TRADEMARKS.md new file mode 100644 index 0000000..03d6262 --- /dev/null +++ b/_site_test/TRADEMARKS.md @@ -0,0 +1,58 @@ +# Trademarks + +## NOLD AI Trademark + +**NOLD AI** (also referred to as **NOLDAI**) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). + +All rights to the NOLD AI trademark are reserved. + +## Third-Party Trademarks + +This project may reference or use trademarks, service marks, and trade names of other companies and organizations. These trademarks are the property of their respective owners. + +### AI and IDE Tools + +- **Claude** and **Claude Code** are trademarks of Anthropic PBC +- **Gemini** is a trademark of Google LLC +- **Cursor** is a trademark of Anysphere, Inc. +- **GitHub Copilot** is a trademark of GitHub, Inc. (Microsoft Corporation) +- **VS Code** (Visual Studio Code) is a trademark of Microsoft Corporation +- **Windsurf** is a trademark of Codeium, Inc. +- **Qwen Code** is a trademark of Alibaba Group +- **opencode** is a trademark of its respective owner +- **Codex CLI** is a trademark of OpenAI, L.P. +- **Amazon Q Developer** is a trademark of Amazon.com, Inc. +- **Amp** is a trademark of its respective owner +- **CodeBuddy CLI** is a trademark of its respective owner +- **Kilo Code** is a trademark of its respective owner +- **Auggie CLI** is a trademark of its respective owner +- **Roo Code** is a trademark of its respective owner + +### Development Tools and Platforms + +- **GitHub** is a trademark of GitHub, Inc. (Microsoft Corporation) +- **Spec-Kit** is a trademark of its respective owner +- **Python** is a trademark of the Python Software Foundation +- **Semgrep** is a trademark of Semgrep, Inc. +- **PyPI** (Python Package Index) is a trademark of the Python Software Foundation + +### Standards and Protocols + +- **OpenAPI** is a trademark of The Linux Foundation +- **JSON Schema** is a trademark of its respective owner + +## Trademark Usage + +When referencing trademarks in this project: + +1. **Always use proper capitalization** as shown above +2. **Include trademark notices** where trademarks are prominently displayed +3. **Respect trademark rights** - do not use trademarks in a way that suggests endorsement or affiliation without permission + +## Disclaimer + +The mention of third-party trademarks in this project does not imply endorsement, sponsorship, or affiliation with the trademark owners. All product names, logos, and brands are property of their respective owners. + +--- + +**Last Updated**: 2025-11-05 diff --git a/_site_test/ai-ide-workflow/index.html b/_site_test/ai-ide-workflow/index.html new file mode 100644 index 0000000..60ce867 --- /dev/null +++ b/_site_test/ai-ide-workflow/index.html @@ -0,0 +1,532 @@ + + + + + + + +AI IDE Workflow Guide | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

AI IDE Workflow Guide

+ +
+

Complete guide to using SpecFact CLI with AI IDEs (Cursor, VS Code + Copilot, Claude Code, etc.)

+
+ +
+ +

Overview

+ +

SpecFact CLI integrates with AI-assisted IDEs through slash commands that enable a seamless workflow: SpecFact finds gaps → AI IDE fixes them → SpecFact validates. This guide explains the complete workflow from setup to validation.

+ +

Key Benefits:

+ +
    +
  • ✅ You control the AI - Use your preferred AI model
    • +
  • ✅ SpecFact validates - Ensure AI-generated code meets contracts
    • +
  • ✅ No lock-in - Works with any AI IDE
    • +
  • ✅ CLI-first - Works offline, no account required
    • +
+ +
+ +

Setup Process

+ +

Step 1: Initialize IDE Integration

+ +

Run the init --ide command in your repository:

+ +
# Auto-detect IDE
+specfact init
+
+# Or specify IDE explicitly
+specfact init --ide cursor
+specfact init --ide vscode
+specfact init --ide copilot
+
+# Install required packages for contract enhancement
+specfact init --ide cursor --install-deps
+
+ +

What it does:

+ +
    +
  1. Detects your IDE (or uses --ide flag)
    2. +
  2. Copies prompt templates from resources/prompts/ to IDE-specific location
    3. +
  3. Creates/updates IDE settings if needed
    4. +
  4. Makes slash commands available in your IDE
    5. +
  5. Optionally installs required packages (beartype, icontract, crosshair-tool, pytest)
    6. +
+ +

Related: IDE Integration Guide - Complete setup instructions

+ +
+ +

Available Slash Commands

+ +

Once initialized, the following slash commands are available in your IDE:

+ +

Core Workflow Commands

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Slash CommandPurposeEquivalent CLI Command
/specfact.01-importImport from codebasespecfact import from-code
/specfact.02-planPlan managementspecfact plan init/add-feature/add-story
/specfact.03-reviewReview planspecfact plan review
/specfact.04-sddCreate SDD manifestspecfact enforce sdd
/specfact.05-enforceSDD enforcementspecfact enforce sdd
/specfact.06-syncSync operationsspecfact sync bridge
/specfact.07-contractsContract managementspecfact generate contracts-prompt
+ +

Advanced Commands

+ + + + + + + + + + + + + + + + + + + + + +
Slash CommandPurposeEquivalent CLI Command
/specfact.compareCompare plansspecfact plan compare
/specfact.validateValidation suitespecfact repro
+ +

Related: IDE Integration - Available Slash Commands

+ +
+ +

Complete Workflow: Prompt Generation → AI IDE → Validation Loop

+ +

Workflow Overview

+ +
graph TD
+    A[SpecFact Analysis] -->|Find Gaps| B[Generate Prompt]
+    B -->|Copy to IDE| C[AI IDE]
+    C -->|Generate Fix| D[Apply Changes]
+    D -->|SpecFact Validate| E[Validation]
+    E -->|Pass| F[Complete]
+    E -->|Fail| B
+
+ +

Step-by-Step Workflow

+ +

1. Run SpecFact Analysis

+ +
# Import from codebase
+specfact import from-code --bundle my-project --repo .
+
+# Run validation to find gaps
+specfact repro --verbose
+
+ +

2. Generate AI-Ready Prompt

+ +
# Generate fix prompt for a specific gap
+specfact generate fix-prompt GAP-001 --bundle my-project
+
+# Or generate contract prompt
+specfact generate contracts-prompt --bundle my-project --feature FEATURE-001
+
+# Or generate test prompt
+specfact generate test-prompt src/auth/login.py --bundle my-project
+
+ +

3. Use AI IDE to Apply Fixes

+ +

In Cursor / VS Code / Copilot:

+ +
    +
  1. Open the generated prompt file
    2. +
  2. Copy the prompt content
    3. +
  3. Paste into AI IDE chat
    4. +
  4. AI generates the fix
    5. +
  5. Review and apply the changes
    6. +
+ +

Example:

+ +
# After generating prompt
+cat .specfact/prompts/fix-prompt-GAP-001.md
+
+# Copy content to AI IDE chat
+# AI generates fix
+# Apply changes to code
+
+ +

4. Validate with SpecFact

+ +
# Check contract coverage
+specfact contract coverage --bundle my-project
+
+# Run validation
+specfact repro --verbose
+
+# Enforce SDD compliance
+specfact enforce sdd --bundle my-project
+
+ +

5. Iterate if Needed

+ +

If validation fails, return to step 2 and generate a new prompt for the remaining issues.

+ +
+ +

Integration with Command Chains

+ +

The AI IDE workflow integrates with several command chains:

+ +

AI-Assisted Code Enhancement Chain

+ +

Workflow: generate contracts-prompt → [AI IDE] → contracts-apply → contract coverage → repro

+ +

Related: AI-Assisted Code Enhancement Chain

+ +

Test Generation from Specifications Chain

+ +

Workflow: generate test-prompt → [AI IDE] → spec generate-tests → pytest

+ +

Related: Test Generation from Specifications Chain

+ +

Gap Discovery & Fixing Chain

+ +

Workflow: repro --verbose → generate fix-prompt → [AI IDE] → enforce sdd

+ +

Related: Gap Discovery & Fixing Chain

+ +
+ +

Example: Complete AI IDE Workflow

+ +

Scenario: Add Contracts to Existing Code

+ +
# 1. Analyze codebase
+specfact import from-code --bundle legacy-api --repo .
+
+# 2. Find gaps
+specfact repro --verbose
+
+# 3. Generate contract prompt
+specfact generate contracts-prompt --bundle legacy-api --feature FEATURE-001
+
+# 4. [In AI IDE] Use slash command or paste prompt
+# /specfact.generate-contracts-prompt legacy-api FEATURE-001
+# AI generates contracts
+# Apply contracts to code
+
+# 5. Validate
+specfact contract coverage --bundle legacy-api
+specfact repro --verbose
+specfact enforce sdd --bundle legacy-api
+
+ +
+ +

Supported IDEs

+ +

SpecFact CLI supports the following AI IDEs:

+ +
    +
  • ✅ Cursor - .cursor/commands/
    • +
  • ✅ VS Code / GitHub Copilot - .github/prompts/ + .vscode/settings.json
    • +
  • ✅ Claude Code - .claude/commands/
    • +
  • ✅ Gemini CLI - .gemini/commands/
    • +
  • ✅ Qwen Code - .qwen/commands/
    • +
  • ✅ opencode - .opencode/command/
    • +
  • ✅ Windsurf - .windsurf/workflows/
    • +
  • ✅ Kilo Code - .kilocode/workflows/
    • +
  • ✅ Auggie - .augment/commands/
    • +
  • ✅ Roo Code - .roo/commands/
    • +
  • ✅ CodeBuddy - .codebuddy/commands/
    • +
  • ✅ Amp - .agents/commands/
    • +
  • ✅ Amazon Q Developer - .amazonq/prompts/
    • +
+ +

Related: IDE Integration - Supported IDEs

+ +
+ +

Troubleshooting

+ +

Slash Commands Not Showing

+ +

Issue: Slash commands don’t appear in IDE

+ +

Solution:

+ +
# Re-initialize with force
+specfact init --ide cursor --force
+
+ +

Related: IDE Integration - Troubleshooting

+ +
+ +

AI-Generated Code Fails Validation

+ +

Issue: AI-generated code doesn’t pass SpecFact validation

+ +

Solution:

+ +
    +
  1. Review validation errors
    2. +
  2. Generate a new prompt with more specific requirements
    3. +
  3. Re-run AI generation
    4. +
  4. Validate again
    5. +
+ +
+ +

See Also

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/architecture/index.html b/_site_test/architecture/index.html new file mode 100644 index 0000000..9e1b6a9 --- /dev/null +++ b/_site_test/architecture/index.html @@ -0,0 +1,1210 @@ + + + + + + + +Architecture | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Architecture

+ +

Technical architecture and design principles of SpecFact CLI.

+ +

Quick Overview

+ +

For Users: SpecFact CLI is a brownfield-first tool that reverse engineers legacy Python code into documented specs, then enforces them as runtime contracts. It works in two modes: CI/CD mode (fast, automated) and CoPilot mode (interactive, AI-enhanced). Primary use case: Analyze existing codebases. Secondary use case: Add enforcement to Spec-Kit projects.

+ +

For Contributors: SpecFact CLI implements a contract-driven development framework through three layers: Specification (plans and protocols), Contract (runtime validation), and Enforcement (quality gates). The architecture supports dual-mode operation (CI/CD and CoPilot) with agent-based routing for complex operations.

+ +
+ +

Overview

+ +

SpecFact CLI implements a contract-driven development framework through three core layers:

+ +
    +
  1. Specification Layer - Plan bundles and protocol definitions
    2. +
  2. Contract Layer - Runtime contracts, static checks, and property tests
    3. +
  3. Enforcement Layer - No-escape gates with budgets and staged enforcement
    4. +
+ + + + + +

Operational Modes

+ +

SpecFact CLI supports two operational modes for different use cases:

+ +

Mode 1: CI/CD Automation (Default)

+ +

Best for:

+ +
    +
  • Clean-code repositories
    • +
  • Self-explaining codebases
    • +
  • Lower complexity projects
    • +
  • Automated CI/CD pipelines
    • +
+ +

Characteristics:

+ +
    +
  • Fast, deterministic execution (< 10s typical)
    • +
  • No AI copilot dependency
    • +
  • Direct command execution
    • +
  • Structured JSON/Markdown output
    • +
  • Enhanced Analysis: AST + Semgrep hybrid pattern detection (API endpoints, models, CRUD, code quality)
    • +
  • Optimized Bundle Size: 81% reduction (18MB → 3.4MB, 5.3x smaller) via test pattern extraction to OpenAPI contracts
    • +
  • Interruptible: All parallel operations support Ctrl+C for immediate cancellation
    • +
+ +

Usage:

+ +
# Auto-detected (default)
+specfact import from-code my-project --repo .
+
+# Explicit CI/CD mode
+specfact --mode cicd import from-code my-project --repo .
+
+ +

Mode 2: CoPilot-Enabled

+ +

Best for:

+ +
    +
  • Brownfield repositories
    • +
  • High complexity codebases
    • +
  • Mixed code quality
    • +
  • Interactive development with AI assistants
    • +
+ +

Characteristics:

+ +
    +
  • Enhanced prompts for better analysis
    • +
  • IDE integration via prompt templates (slash commands)
    • +
  • Agent mode routing for complex operations
    • +
  • Interactive assistance
    • +
+ +

Usage:

+ +
# Auto-detected (if CoPilot available)
+specfact import from-code my-project --repo .
+
+# Explicit CoPilot mode
+specfact --mode copilot import from-code my-project --repo .
+
+# IDE integration (slash commands)
+# First, initialize: specfact init --ide cursor
+# Then use in IDE chat:
+/specfact.01-import legacy-api --repo . --confidence 0.7
+/specfact.02-plan init legacy-api
+/specfact.06-sync --adapter speckit --repo . --bidirectional
+
+ +

Mode Detection

+ +

Mode is automatically detected based on:

+ +
    +
  1. Explicit --mode flag (highest priority)
    2. +
  2. CoPilot API availability (environment/IDE detection)
    3. +
  3. IDE integration (VS Code/Cursor with CoPilot enabled)
    4. +
  4. Default to CI/CD mode (fallback)
    5. +
+ +
+ +

Agent Modes

+ +

Agent modes provide enhanced prompts and routing for CoPilot-enabled operations:

+ +

Available Agent Modes

+ +
    +
  • analyze agent mode: Brownfield analysis with code understanding
    • +
  • plan agent mode: Plan management with business logic understanding
    • +
  • sync agent mode: Bidirectional sync with conflict resolution
    • +
+ +

Agent Mode Routing

+ +

Each command uses specialized agent mode routing:

+ +
# Analyze agent mode
+/specfact.01-import legacy-api --repo . --confidence 0.7
+# → Enhanced prompts for code understanding
+# → Context injection (current file, selection, workspace)
+# → Interactive assistance for complex codebases
+
+# Plan agent mode
+/specfact.02-plan init legacy-api
+# → Guided wizard mode
+# → Natural language prompts
+# → Context-aware feature extraction
+
+# Sync agent mode
+/specfact.06-sync --adapter speckit --repo . --bidirectional
+# → Automatic source detection via bridge adapter
+# → Conflict resolution assistance
+# → Change explanation and preview
+
+ +
+ +

Sync Operation

+ +

SpecFact CLI supports bidirectional synchronization for consistent change management:

+ +

Bridge-Based Sync (Adapter-Agnostic)

+ +

Bidirectional synchronization between external tools (e.g., Spec-Kit, OpenSpec) and SpecFact via configurable bridge:

+ +
# Spec-Kit bidirectional sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# OpenSpec read-only sync (Phase 1)
+specfact sync bridge --adapter openspec --mode read-only --bundle <bundle-name> --repo .
+
+# OpenSpec cross-repository sync
+specfact sync bridge --adapter openspec --mode read-only --bundle <bundle-name> --repo . --external-base-path ../specfact-cli-internal
+
+# Continuous watch mode
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+ +

What it syncs:

+ +
    +
  • specs/[###-feature-name]/spec.md, plan.md, tasks.md ↔ .specfact/projects/<bundle-name>/ aspect files
    • +
  • .specify/memory/constitution.md ↔ SpecFact business context
    • +
  • specs/[###-feature-name]/research.md, data-model.md, quickstart.md ↔ SpecFact supporting artifacts
    • +
  • specs/[###-feature-name]/contracts/*.yaml ↔ SpecFact protocol definitions
    • +
  • Automatic conflict resolution with priority rules
    • +
+ +

Bridge Architecture: The sync layer uses a configurable bridge (.specfact/config/bridge.yaml) that maps SpecFact logical concepts to physical tool artifacts, making it adapter-agnostic and extensible for future tool integrations (OpenSpec, Linear, Jira, Notion, etc.). The architecture uses a plugin-based adapter registry pattern - all adapters are registered in AdapterRegistry and accessed via AdapterRegistry.get_adapter(), eliminating hard-coded adapter checks in core components like BridgeProbe and BridgeSync.

+ +

Repository Sync

+ +

Sync code changes to SpecFact artifacts:

+ +
# One-time sync
+specfact sync repository --repo . --target .specfact
+
+# Continuous watch mode
+specfact sync repository --repo . --watch --interval 5
+
+ +

What it tracks:

+ +
    +
  • Code changes → Plan artifact updates
    • +
  • Deviations from manual plans
    • +
  • Feature/story extraction from code
    • +
+ +

Contract Layers

+ +
graph TD
+    A[Specification] --> B[Runtime Contracts]
+    B --> C[Static Checks]
+    B --> D[Property Tests]
+    B --> E[Runtime Sentinels]
+    C --> F[No-Escape Gate]
+    D --> F
+    E --> F
+    F --> G[PR Approved/Blocked]
+
+ +

1. Specification Layer

+ +

Project Bundle (.specfact/projects/<bundle-name>/ - modular structure with multiple aspect files):

+ +
version: "1.0"
+idea:
+  title: "SpecFact CLI Tool"
+  narrative: "Enable contract-driven development"
+product:
+  themes:
+    - "Developer Experience"
+  releases:
+    - name: "v0.1"
+      objectives: ["Import", "Analyze", "Enforce"]
+features:
+  - key: FEATURE-001
+    title: "Spec-Kit Import"
+    outcomes:
+      - "Zero manual conversion"
+    stories:
+      - key: STORY-001
+        title: "Parse Spec-Kit artifacts"
+        acceptance:
+          - "Schema validation passes"
+
+ +

Protocol (.specfact/protocols/workflow.protocol.yaml):

+ +
states:
+  - INIT
+  - PLAN
+  - REQUIREMENTS
+  - ARCHITECTURE
+  - CODE
+  - REVIEW
+  - DEPLOY
+start: INIT
+transitions:
+  - from_state: INIT
+    on_event: start_planning
+    to_state: PLAN
+  - from_state: PLAN
+    on_event: approve_plan
+    to_state: REQUIREMENTS
+    guard: plan_quality_gate_passes
+
+ +

2. Contract Layer

+ +

Runtime Contracts (icontract)

+ +
from icontract import require, ensure
+from beartype import beartype
+
+@require(lambda plan: plan.version == "1.0")
+@ensure(lambda result: len(result.features) > 0)
+@beartype
+def validate_plan(plan: PlanBundle) -> ValidationResult:
+    """Validate plan bundle against contracts."""
+    return ValidationResult(valid=True)
+
+ +

Static Checks (Semgrep)

+ +
# .semgrep/async-anti-patterns.yaml
+rules:
+  - id: async-without-await
+    pattern: |
+      async def $FUNC(...):
+        ...
+    pattern-not: |
+      async def $FUNC(...):
+        ...
+        await ...
+    message: "Async function without await"
+    severity: ERROR
+
+ +

Property Tests (Hypothesis)

+ +
from hypothesis import given
+from hypothesis.strategies import text
+
+@given(text())
+def test_plan_key_format(feature_key: str):
+    """All feature keys must match FEATURE-\d+ format."""
+    if feature_key.startswith("FEATURE-"):
+        assert feature_key[8:].isdigit()
+
+ +

Runtime Sentinels

+ +
import asyncio
+from typing import Optional
+
+class EventLoopMonitor:
+    """Monitor event loop health."""
+    
+    def __init__(self, lag_threshold_ms: float = 100.0):
+        self.lag_threshold_ms = lag_threshold_ms
+    
+    async def check_lag(self) -> Optional[float]:
+        """Return lag in ms if above threshold."""
+        start = asyncio.get_event_loop().time()
+        await asyncio.sleep(0)
+        lag_ms = (asyncio.get_event_loop().time() - start) * 1000
+        return lag_ms if lag_ms > self.lag_threshold_ms else None
+
+ +

3. Enforcement Layer

+ +

No-Escape Gate

+ +
# .github/workflows/specfact-gate.yml
+name: No-Escape Gate
+on: [pull_request]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: SpecFact Validation
+        run: |
+          specfact repro --budget 120 --verbose
+          if [ $? -ne 0 ]; then
+            echo "::error::Contract violations detected"
+            exit 1
+          fi
+
+ +

Staged Enforcement

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
StageDescriptionViolations
ShadowLog only, never blockAll logged, none block
WarnWarn on medium+, block highHIGH blocks, MEDIUM warns
BlockBlock all medium+MEDIUM+ blocks
+ +

Budget-Based Execution

+ +
from typing import Optional
+import time
+
+class BudgetedValidator:
+    """Validator with time budget."""
+    
+    def __init__(self, budget_seconds: int = 120):
+        self.budget_seconds = budget_seconds
+        self.start_time: Optional[float] = None
+    
+    def start(self):
+        """Start budget timer."""
+        self.start_time = time.time()
+    
+    def check_budget(self) -> bool:
+        """Return True if budget exceeded."""
+        if self.start_time is None:
+            return False
+        elapsed = time.time() - self.start_time
+        return elapsed > self.budget_seconds
+
+ +

Data Models

+ +

PlanBundle

+ +
from pydantic import BaseModel, Field
+from typing import List
+
+class Idea(BaseModel):
+    """High-level idea."""
+    title: str
+    narrative: str
+
+class Story(BaseModel):
+    """User story."""
+    key: str = Field(pattern=r"^STORY-\d+$")
+    title: str
+    acceptance: List[str]
+
+class Feature(BaseModel):
+    """Feature with stories."""
+    key: str = Field(pattern=r"^FEATURE-\d+$")
+    title: str
+    outcomes: List[str]
+    stories: List[Story]
+
+class PlanBundle(BaseModel):
+    """Complete plan bundle."""
+    version: str = "1.0"
+    idea: Idea
+    features: List[Feature]
+
+ +

ProtocolSpec

+ +
from pydantic import BaseModel
+from typing import List, Optional
+
+class Transition(BaseModel):
+    """State machine transition."""
+    from_state: str
+    on_event: str
+    to_state: str
+    guard: Optional[str] = None
+
+class ProtocolSpec(BaseModel):
+    """FSM protocol specification."""
+    states: List[str]
+    start: str
+    transitions: List[Transition]
+
+ +

Deviation

+ +
from enum import Enum
+from pydantic import BaseModel
+
+class DeviationSeverity(str, Enum):
+    """Severity levels."""
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+    CRITICAL = "CRITICAL"
+
+class Deviation(BaseModel):
+    """Detected deviation."""
+    type: str
+    severity: DeviationSeverity
+    description: str
+    location: str
+    suggestion: Optional[str] = None
+
+ +

Change Tracking Models (v1.1 Schema)

+ +

Introduced in v0.21.1: Tool-agnostic change tracking models for delta spec tracking and change proposals. These models support OpenSpec and other tools (Linear, Jira, etc.) that track changes to specifications.

+ +
from enum import Enum
+from pydantic import BaseModel
+from typing import Optional, Dict, List, Any
+
+class ChangeType(str, Enum):
+    """Change type for delta specs (tool-agnostic)."""
+    ADDED = "added"
+    MODIFIED = "modified"
+    REMOVED = "removed"
+
+class FeatureDelta(BaseModel):
+    """Delta tracking for a feature change (tool-agnostic)."""
+    feature_key: str
+    change_type: ChangeType
+    original_feature: Optional[Feature] = None  # For MODIFIED/REMOVED
+    proposed_feature: Optional[Feature] = None  # For ADDED/MODIFIED
+    change_rationale: Optional[str] = None
+    change_date: Optional[str] = None  # ISO timestamp
+    validation_status: Optional[str] = None  # pending, passed, failed
+    validation_results: Optional[Dict[str, Any]] = None
+    source_tracking: Optional[SourceTracking] = None  # Tool-specific metadata
+
+class ChangeProposal(BaseModel):
+    """Change proposal (tool-agnostic, used by OpenSpec and other tools)."""
+    name: str  # Change identifier (e.g., 'add-user-feedback')
+    title: str
+    description: str  # What: Description of the change
+    rationale: str  # Why: Rationale and business value
+    timeline: Optional[str] = None  # When: Timeline and dependencies
+    owner: Optional[str] = None  # Who: Owner and stakeholders
+    stakeholders: List[str] = []
+    dependencies: List[str] = []
+    status: str = "proposed"  # proposed, in-progress, applied, archived
+    created_at: str  # ISO timestamp
+    applied_at: Optional[str] = None
+    archived_at: Optional[str] = None
+    source_tracking: Optional[SourceTracking] = None  # Tool-specific metadata
+
+class ChangeTracking(BaseModel):
+    """Change tracking for a bundle (tool-agnostic capability)."""
+    proposals: Dict[str, ChangeProposal] = {}  # change_name -> ChangeProposal
+    feature_deltas: Dict[str, List[FeatureDelta]] = {}  # change_name -> [FeatureDelta]
+
+class ChangeArchive(BaseModel):
+    """Archive entry for completed changes (tool-agnostic)."""
+    change_name: str
+    applied_at: str  # ISO timestamp
+    applied_by: Optional[str] = None
+    pr_number: Optional[str] = None
+    commit_hash: Optional[str] = None
+    feature_deltas: List[FeatureDelta] = []
+    validation_results: Optional[Dict[str, Any]] = None
+    source_tracking: Optional[SourceTracking] = None  # Tool-specific metadata
+
+ +

Key Design Principles:

+ +
    +
  • Tool-Agnostic: All tool-specific metadata stored in source_tracking, not in core models
    • +
  • Cross-Repository Support: Adapters can load change tracking from external repositories
    • +
  • Backward Compatible: All fields optional - v1.0 bundles work without modification
    • +
  • Validation Integration: Change proposals can include SpecFact validation results
    • +
+ +

Schema Versioning:

+ +
    +
  • v1.0: Original bundle format (no change tracking)
    • +
  • v1.1: Extended with optional change_tracking and change_archive fields
    • +
  • Automatic Detection: Bundle loader checks schema version and conditionally loads change tracking via adapters
    • +
+ +

Module Structure

+ +
src/specfact_cli/
+├── cli.py                 # Main CLI entry point
+├── commands/              # CLI command implementations
+│   ├── import_cmd.py     # Import from external formats
+│   ├── analyze.py        # Code analysis
+│   ├── plan.py           # Plan management
+│   ├── enforce.py        # Enforcement configuration
+│   ├── repro.py          # Reproducibility validation
+│   └── sync.py           # Sync operations (Spec-Kit, repository)
+├── modes/                 # Operational mode management
+│   ├── detector.py       # Mode detection logic
+│   └── router.py         # Command routing
+├── utils/                 # Utilities
+│   └── ide_setup.py      # IDE integration (template copying)
+├── agents/                # Agent mode implementations
+│   ├── base.py           # Agent mode base class
+│   ├── analyze_agent.py # Analyze agent mode
+│   ├── plan_agent.py    # Plan agent mode
+│   └── sync_agent.py    # Sync agent mode
+├── adapters/              # Bridge adapter implementations
+│   ├── base.py           # BridgeAdapter base interface
+│   ├── registry.py       # AdapterRegistry for plugin-based architecture
+│   ├── openspec.py       # OpenSpec adapter (read-only sync)
+│   └── speckit.py        # Spec-Kit adapter (bidirectional sync)
+├── sync/                  # Sync operation modules
+│   ├── bridge_sync.py    # Bridge-based bidirectional sync (adapter-agnostic)
+│   ├── bridge_probe.py   # Bridge detection and auto-generation
+│   ├── bridge_watch.py   # Bridge-based watch mode
+│   ├── repository_sync.py # Repository sync
+│   └── watcher.py        # Watch mode for continuous sync
+├── models/               # Pydantic data models
+│   ├── plan.py          # Plan bundle models (legacy compatibility)
+│   ├── project.py       # Project bundle models (modular structure)
+│   ├── change.py         # Change tracking models (v1.1 schema)
+│   ├── bridge.py        # Bridge configuration models
+│   ├── protocol.py      # Protocol FSM models
+│   └── deviation.py     # Deviation models
+├── validators/          # Schema validators
+│   ├── schema.py        # Schema validation
+│   ├── contract.py      # Contract validation
+│   └── fsm.py           # FSM validation
+├── generators/          # Code generators
+│   ├── protocol.py      # Protocol generator
+│   ├── plan.py          # Plan generator
+│   └── report.py        # Report generator
+├── utils/               # CLI utilities
+│   ├── console.py       # Rich console output
+│   ├── git.py           # Git operations
+│   └── yaml_utils.py    # YAML helpers
+├── analyzers/          # Code analysis engines
+│   ├── code_analyzer.py # AST+Semgrep hybrid analysis
+│   ├── graph_analyzer.py # Dependency graph analysis
+│   └── relationship_mapper.py # Relationship extraction
+└── common/              # Shared utilities
+    ├── logger_setup.py  # Logging infrastructure
+    ├── logging_utils.py # Logging helpers
+    ├── text_utils.py    # Text utilities
+    └── utils.py         # File/JSON utilities
+
+ +

Analysis Components

+ +

AST+Semgrep Hybrid Analysis

+ +

The CodeAnalyzer uses a hybrid approach combining AST parsing with Semgrep pattern detection:

+ +

AST Analysis (Core):

+ +
    +
  • Structural code analysis (classes, methods, imports)
    • +
  • Type hint extraction
    • +
  • Parallelized processing (2-4x speedup)
    • +
  • Interruptible with Ctrl+C (graceful cancellation)
    • +
+ +

Recent Improvements (2025-11-30):

+ +
    +
  • ✅ Bundle Size Optimization: 81% reduction (18MB → 3.4MB, 5.3x smaller) via test pattern extraction to OpenAPI contracts
    • +
  • ✅ Acceptance Criteria Limiting: 1-3 high-level items per story (detailed examples in contract files)
    • +
  • ✅ KeyboardInterrupt Handling: All parallel operations support immediate cancellation
    • +
  • ✅ Semgrep Detection Fix: Increased timeout from 1s to 5s for reliable detection
    • +
  • Async pattern detection
    • +
  • Theme detection from imports
    • +
+ +

Semgrep Pattern Detection (Enhancement):

+ +
    +
  • API Endpoint Detection: FastAPI, Flask, Express, Gin routes
    • +
  • Database Model Detection: SQLAlchemy, Django, Pydantic, TortoiseORM, Peewee
    • +
  • CRUD Operation Detection: Function naming patterns (create_, get_, update_, delete_)
    • +
  • Authentication Patterns: Auth decorators, permission checks
    • +
  • Code Quality Assessment: Anti-patterns, code smells, security vulnerabilities
    • +
  • Framework Patterns: Async/await, context managers, type hints, configuration
    • +
+ +

Plugin Status: The import command displays plugin status (AST Analysis, Semgrep Pattern Detection, Dependency Graph Analysis) showing which tools are enabled and used.

+ +

Benefits:

+ +
    +
  • Framework-aware feature detection
    • +
  • Enhanced confidence scores (AST + Semgrep evidence)
    • +
  • Code quality maturity assessment
    • +
  • Multi-language ready (TypeScript, JavaScript, Go patterns available)
    • +
+ +

Testing Strategy

+ +

Contract-First Testing

+ +

SpecFact CLI uses contracts as specifications:

+ +
    +
  1. Runtime Contracts - @icontract decorators on public APIs
    2. +
  2. Type Validation - @beartype for runtime type checking
    3. +
  3. Contract Exploration - CrossHair to discover counterexamples
    4. +
  4. Scenario Tests - Focus on business workflows
    5. +
+ +

Test Pyramid

+ +
         /\
+        /  \  E2E Tests (Scenario)
+       /____\
+      /      \  Integration Tests (Contract)
+     /________\
+    /          \  Unit Tests (Property)
+   /____________\
+
+ +

Running Tests

+ +
# Contract validation
+hatch run contract-test-contracts
+
+# Contract exploration (CrossHair)
+hatch run contract-test-exploration
+
+# Scenario tests
+hatch run contract-test-scenarios
+
+# E2E tests
+hatch run contract-test-e2e
+
+# Full test suite
+hatch run contract-test-full
+
+ +

Bridge Adapter Interface

+ +

Introduced in v0.21.1: The BridgeAdapter interface has been extended with change tracking methods to support OpenSpec and other tools that track specification changes.

+ +

Core Interface Methods

+ +

All adapters must implement these base methods:

+ +
from abc import ABC, abstractmethod
+from pathlib import Path
+from specfact_cli.models.bridge import BridgeConfig
+from specfact_cli.models.change import ChangeProposal, ChangeTracking
+
+class BridgeAdapter(ABC):
+    @abstractmethod
+    def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool:
+        """Detect if adapter applies to repository."""
+
+    @abstractmethod
+    def import_artifact(self, artifact_key: str, artifact_path: Path | dict, project_bundle: Any, bridge_config: BridgeConfig | None = None) -> None:
+        """Import artifact from tool format to SpecFact."""
+
+    @abstractmethod
+    def export_artifact(self, artifact_key: str, artifact_data: Any, bridge_config: BridgeConfig | None = None) -> Path | dict:
+        """Export artifact from SpecFact to tool format."""
+
+    @abstractmethod
+    def generate_bridge_config(self, repo_path: Path) -> BridgeConfig:
+        """Generate bridge configuration for adapter."""
+    
+    @abstractmethod
+    def get_capabilities(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> ToolCapabilities:
+        """Get adapter capabilities (sync modes, layout, etc.)."""
+
+ +

Change Tracking Methods (v0.21.1+)

+ +

Introduced in v0.21.1: Adapters that support change tracking must implement these additional methods:

+ +
@abstractmethod
+def load_change_tracking(
+    self, bundle_dir: Path, bridge_config: BridgeConfig | None = None
+) -> ChangeTracking | None:
+    """
+    Load change tracking from adapter-specific storage location.
+    
+    Args:
+        bundle_dir: Path to bundle directory (.specfact/projects/<bundle-name>/)
+        bridge_config: Bridge configuration (may contain external_base_path for cross-repo)
+    
+    Returns:
+        ChangeTracking instance or None if not available
+    """
+
+@abstractmethod
+def save_change_tracking(
+    self, bundle_dir: Path, change_tracking: ChangeTracking, bridge_config: BridgeConfig | None = None
+) -> None:
+    """
+    Save change tracking to adapter-specific storage location.
+    
+    Args:
+        bundle_dir: Path to bundle directory
+        change_tracking: ChangeTracking instance to save
+        bridge_config: Bridge configuration (may contain external_base_path for cross-repo)
+    """
+
+@abstractmethod
+def load_change_proposal(
+    self, bundle_dir: Path, change_name: str, bridge_config: BridgeConfig | None = None
+) -> ChangeProposal | None:
+    """
+    Load change proposal from adapter-specific storage location.
+    
+    Args:
+        bundle_dir: Path to bundle directory
+        change_name: Change identifier (e.g., 'add-user-feedback')
+        bridge_config: Bridge configuration (may contain external_base_path for cross-repo)
+    
+    Returns:
+        ChangeProposal instance or None if not found
+    """
+
+@abstractmethod
+def save_change_proposal(
+    self, bundle_dir: Path, proposal: ChangeProposal, bridge_config: BridgeConfig | None = None
+) -> None:
+    """
+    Save change proposal to adapter-specific storage location.
+    
+    Args:
+        bundle_dir: Path to bundle directory
+        proposal: ChangeProposal instance to save
+        bridge_config: Bridge configuration (may contain external_base_path for cross-repo)
+    """
+
+ +

Cross-Repository Support

+ +

Adapters must support loading change tracking from external repositories:

+ +
    +
  • external_base_path: If bridge_config.external_base_path is set, adapters should load change tracking from that location instead of bundle_dir
    • +
  • Tool-Specific Storage: Each adapter determines where change tracking is stored (e.g., OpenSpec uses openspec/changes/, Linear uses API)
    • +
  • Source Tracking: Tool-specific metadata (issue IDs, file paths, etc.) stored in source_tracking field
    • +
+ +

Implementation Examples

+ +

OpenSpec Adapter (v0.21.1+):

+ +

The OpenSpec adapter provides read-only sync (Phase 1) for importing OpenSpec specifications and change tracking:

+ +
class OpenSpecAdapter(BridgeAdapter):
+    def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool:
+        # Detects openspec/project.md or openspec/specs/ directory
+        base_path = bridge_config.external_base_path if bridge_config and bridge_config.external_base_path else repo_path
+        return (base_path / "openspec" / "project.md").exists() or (base_path / "openspec" / "specs").exists()
+    
+    def get_capabilities(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> ToolCapabilities:
+        # Returns OpenSpec-specific capabilities
+        return ToolCapabilities(tool="openspec", layout="openspec", specs_dir="openspec/specs")
+    
+    def load_change_tracking(self, bundle_dir: Path, bridge_config: BridgeConfig | None = None) -> ChangeTracking | None:
+        # Load from openspec/changes/ directory
+        base_path = bridge_config.external_base_path if bridge_config and bridge_config.external_base_path else bundle_dir.parent.parent.parent
+        changes_dir = base_path / "openspec" / "changes"
+        # Parse change proposals and feature deltas
+        return ChangeTracking(...)
+    
+    def import_artifact(self, artifact_key: str, artifact_path: Path, project_bundle: Any, bridge_config: BridgeConfig | None = None) -> None:
+        # Supports: specification, project_context, change_proposal, change_spec_delta
+        # Parses OpenSpec markdown and updates project bundle
+        pass
+
+ +

Key Features:

+
    +
  • Read-only sync (Phase 1): Import only, export methods raise NotImplementedError
    • +
  • Cross-repository support: Uses external_base_path for OpenSpec in different repositories
    • +
  • Change tracking: Loads change proposals and feature deltas from openspec/changes/
    • +
  • Source tracking: Stores OpenSpec paths in source_tracking.source_metadata
    • +
+ +

SpecKit Adapter (v0.22.0+):

+ +

The SpecKit adapter provides full bidirectional sync for Spec-Kit markdown artifacts:

+ +
class SpecKitAdapter(BridgeAdapter):
+    def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool:
+        # Detects .specify/ directory or specs/ directory (classic/modern layouts)
+        base_path = bridge_config.external_base_path if bridge_config and bridge_config.external_base_path else repo_path
+        return (base_path / ".specify").exists() or (base_path / "specs").exists() or (base_path / "docs" / "specs").exists()
+    
+    def get_capabilities(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> ToolCapabilities:
+        # Returns Spec-Kit-specific capabilities (bidirectional sync supported)
+        return ToolCapabilities(
+            tool="speckit",
+            layout="classic" or "modern",
+            specs_dir="specs" or "docs/specs",
+            supported_sync_modes=["bidirectional", "unidirectional"]
+        )
+    
+    def import_artifact(self, artifact_key: str, artifact_path: Path, project_bundle: Any, bridge_config: BridgeConfig | None = None) -> None:
+        # Supports: specification, plan, tasks, constitution
+        # Parses Spec-Kit markdown and updates project bundle
+        pass
+    
+    def export_artifact(self, artifact_key: str, artifact_data: Any, bridge_config: BridgeConfig | None = None) -> Path:
+        # Supports: specification, plan, tasks, constitution
+        # Exports SpecFact models to Spec-Kit markdown format
+        pass
+
+ +

Key Features:

+
    +
  • Bidirectional sync: Full import and export support for Spec-Kit artifacts
    • +
  • Classic and modern layouts: Supports both specs/ (classic) and docs/specs/ (modern) directory structures
    • +
  • Public helper methods: discover_features(), detect_changes(), detect_conflicts(), export_bundle() for advanced operations
    • +
  • Contract-first: All methods have @beartype, @require, and @ensure decorators for runtime validation
    • +
  • Adapter registry: Registered in AdapterRegistry for plugin-based architecture
    • +
+ +

GitHub Adapter (export-only):

+ +
class GitHubAdapter(BridgeAdapter):
+    def load_change_tracking(self, bundle_dir: Path, bridge_config: BridgeConfig | None = None) -> ChangeTracking | None:
+        # GitHub adapter is export-only (OpenSpec → GitHub Issues)
+        return None
+    
+    def save_change_tracking(self, bundle_dir: Path, change_tracking: ChangeTracking, bridge_config: BridgeConfig | None = None) -> None:
+        # Export change proposals to GitHub Issues
+        pass
+    
+    def export_artifact(self, artifact_key: str, artifact_data: Any, bridge_config: BridgeConfig | None = None) -> dict:
+        # Supports artifact keys: change_proposal, change_status, change_proposal_update, code_change_progress
+        if artifact_key == "code_change_progress":
+            # Add progress comment to existing GitHub issue based on code changes
+            return self._add_progress_comment(artifact_data, ...)
+
+ +

Schema Version Handling

+ +
    +
  • v1.0 Bundles: load_change_tracking() returns None (backward compatible)
    • +
  • v1.1 Bundles: Bundle loader calls load_change_tracking() via adapter if schema version is 1.1+
    • +
  • Automatic Detection: ProjectBundle.load_from_directory() checks schema version before loading change tracking
    • +
+ +

Dependencies

+ +

Core

+ +
    +
  • typer - CLI framework
    • +
  • pydantic - Data validation
    • +
  • rich - Terminal output
    • +
  • networkx - Graph analysis
    • +
  • ruamel.yaml - YAML processing
    • +
+ +

Validation

+ +
    +
  • icontract - Runtime contracts
    • +
  • beartype - Type checking
    • +
  • crosshair-tool - Contract exploration
    • +
  • hypothesis - Property-based testing
    • +
+ +

Development

+ +
    +
  • hatch - Build and environment management
    • +
  • basedpyright - Type checking
    • +
  • ruff - Linting
    • +
  • pytest - Test runner
    • +
+ +

See pyproject.toml for complete dependency list.

+ +

Design Principles

+ +
    +
  1. Contract-Driven - Contracts are specifications
    2. +
  2. Evidence-Based - Claims require reproducible evidence
    3. +
  3. Offline-First - No SaaS required for core functionality
    4. +
  4. Progressive Enhancement - Shadow → Warn → Block
    5. +
  5. Fast Feedback - < 90s CI overhead
    6. +
  6. Escape Hatches - Override mechanisms for emergencies
    7. +
  7. Quality-First - TDD with quality gates from day 1
    8. +
  8. Dual-Mode Operation - CI/CD automation or CoPilot-enabled assistance
    9. +
  9. Bidirectional Sync - Consistent change management across tools
    10. +
+ +

Performance Characteristics

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationTypical TimeBudget
Plan validation< 1s5s
Contract exploration10-30s60s
Full repro suite60-90s120s
Brownfield analysis2-5 min300s
+ +

Security Considerations

+ +
    +
  1. No external dependencies for core validation
    2. +
  2. Secure defaults - Shadow mode by default
    3. +
  3. No data exfiltration - Works offline
    4. +
  4. Contract provenance - SHA256 hashes in reports
    5. +
  5. Reproducible builds - Deterministic outputs
    6. +
+ +
+ +

See Commands for command reference and Technical Deep Dives for testing procedures.

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/assets/main.css b/_site_test/assets/main.css new file mode 100644 index 0000000..54a47ce --- /dev/null +++ b/_site_test/assets/main.css @@ -0,0 +1 @@ +body,h1,h2,h3,h4,h5,h6,p,blockquote,pre,hr,dl,dd,ol,ul,figure{margin:0;padding:0}body{font:400 16px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";color:#111;background-color:#fdfdfd;-webkit-text-size-adjust:100%;-webkit-font-feature-settings:"kern" 1;-moz-font-feature-settings:"kern" 1;-o-font-feature-settings:"kern" 1;font-feature-settings:"kern" 1;font-kerning:normal;display:flex;min-height:100vh;flex-direction:column}h1,h2,h3,h4,h5,h6,p,blockquote,pre,ul,ol,dl,figure,.highlight{margin-bottom:15px}main{display:block}img{max-width:100%;vertical-align:middle}figure>img{display:block}figcaption{font-size:14px}ul,ol{margin-left:30px}li>ul,li>ol{margin-bottom:0}h1,h2,h3,h4,h5,h6{font-weight:400}a{color:#2a7ae2;text-decoration:none}a:visited{color:#1756a9}a:hover{color:#111;text-decoration:underline}.social-media-list a:hover{text-decoration:none}.social-media-list a:hover .username{text-decoration:underline}blockquote{color:#828282;border-left:4px solid #e8e8e8;padding-left:15px;font-size:18px;letter-spacing:-1px;font-style:italic}blockquote>:last-child{margin-bottom:0}pre,code{font-size:15px;border:1px solid #e8e8e8;border-radius:3px;background-color:#eef}code{padding:1px 5px}pre{padding:8px 12px;overflow-x:auto}pre>code{border:0;padding-right:0;padding-left:0}.wrapper{max-width:-webkit-calc(800px - (30px * 2));max-width:calc(800px - 30px*2);margin-right:auto;margin-left:auto;padding-right:30px;padding-left:30px}@media screen and (max-width: 800px){.wrapper{max-width:-webkit-calc(800px - (30px));max-width:calc(800px - (30px));padding-right:15px;padding-left:15px}}.footer-col-wrapper:after,.wrapper:after{content:"";display:table;clear:both}.svg-icon{width:16px;height:16px;display:inline-block;fill:#828282;padding-right:5px;vertical-align:text-top}.social-media-list li+li{padding-top:5px}table{margin-bottom:30px;width:100%;text-align:left;color:#3f3f3f;border-collapse:collapse;border:1px solid #e8e8e8}table tr:nth-child(even){background-color:#f7f7f7}table th,table td{padding:9.999999999px 15px}table th{background-color:#f0f0f0;border:1px solid #dedede;border-bottom-color:#c9c9c9}table td{border:1px solid #e8e8e8}.site-header{border-top:5px solid #424242;border-bottom:1px solid #e8e8e8;min-height:55.95px;position:relative}.site-title{font-size:26px;font-weight:300;line-height:54px;letter-spacing:-1px;margin-bottom:0;float:left}.site-title,.site-title:visited{color:#424242}.site-nav{float:right;line-height:54px}.site-nav .nav-trigger{display:none}.site-nav .menu-icon{display:none}.site-nav .page-link{color:#111;line-height:1.5}.site-nav .page-link:not(:last-child){margin-right:20px}@media screen and (max-width: 600px){.site-nav{position:absolute;top:9px;right:15px;background-color:#fdfdfd;border:1px solid #e8e8e8;border-radius:5px;text-align:right}.site-nav label[for=nav-trigger]{display:block;float:right;width:36px;height:36px;z-index:2;cursor:pointer}.site-nav .menu-icon{display:block;float:right;width:36px;height:26px;line-height:0;padding-top:10px;text-align:center}.site-nav .menu-icon>svg{fill:#424242}.site-nav input~.trigger{clear:both;display:none}.site-nav input:checked~.trigger{display:block;padding-bottom:5px}.site-nav .page-link{display:block;margin-left:20px;padding:5px 10px}.site-nav .page-link:not(:last-child){margin-right:0}}.site-footer{border-top:1px solid #e8e8e8;padding:30px 0}.footer-heading{font-size:18px;margin-bottom:15px}.contact-list,.social-media-list{list-style:none;margin-left:0}.footer-col-wrapper{font-size:15px;color:#828282;margin-left:-15px}.footer-col{float:left;margin-bottom:15px;padding-left:15px}.footer-col-1{width:-webkit-calc(35% - (30px / 2));width:calc(35% - 30px/2)}.footer-col-2{width:-webkit-calc(20% - (30px / 2));width:calc(20% - 30px/2)}.footer-col-3{width:-webkit-calc(45% - (30px / 2));width:calc(45% - 30px/2)}@media screen and (max-width: 800px){.footer-col-1,.footer-col-2{width:-webkit-calc(50% - (30px / 2));width:calc(50% - 30px/2)}.footer-col-3{width:-webkit-calc(100% - (30px / 2));width:calc(100% - 30px/2)}}@media screen and (max-width: 600px){.footer-col{float:none;width:-webkit-calc(100% - (30px / 2));width:calc(100% - 30px/2)}}.page-content{padding:30px 0;flex:1}.page-heading{font-size:32px}.post-list-heading{font-size:28px}.post-list{margin-left:0;list-style:none}.post-list>li{margin-bottom:30px}.post-meta{font-size:14px;color:#828282}.post-link{display:block;font-size:24px}.post-header{margin-bottom:30px}.post-title{font-size:42px;letter-spacing:-1px;line-height:1}@media screen and (max-width: 800px){.post-title{font-size:36px}}.post-content{margin-bottom:30px}.post-content h2{font-size:32px}@media screen and (max-width: 800px){.post-content h2{font-size:28px}}.post-content h3{font-size:26px}@media screen and (max-width: 800px){.post-content h3{font-size:22px}}.post-content h4{font-size:20px}@media screen and (max-width: 800px){.post-content h4{font-size:18px}}.highlight{background:#fff}.highlighter-rouge .highlight{background:#eef}.highlight .c{color:#998;font-style:italic}.highlight .err{color:#a61717;background-color:#e3d2d2}.highlight .k{font-weight:bold}.highlight .o{font-weight:bold}.highlight .cm{color:#998;font-style:italic}.highlight .cp{color:#999;font-weight:bold}.highlight .c1{color:#998;font-style:italic}.highlight .cs{color:#999;font-weight:bold;font-style:italic}.highlight .gd{color:#000;background-color:#fdd}.highlight .gd .x{color:#000;background-color:#faa}.highlight .ge{font-style:italic}.highlight .gr{color:#a00}.highlight .gh{color:#999}.highlight .gi{color:#000;background-color:#dfd}.highlight .gi .x{color:#000;background-color:#afa}.highlight .go{color:#888}.highlight .gp{color:#555}.highlight .gs{font-weight:bold}.highlight .gu{color:#aaa}.highlight .gt{color:#a00}.highlight .kc{font-weight:bold}.highlight .kd{font-weight:bold}.highlight .kp{font-weight:bold}.highlight .kr{font-weight:bold}.highlight .kt{color:#458;font-weight:bold}.highlight .m{color:#099}.highlight .s{color:#d14}.highlight .na{color:teal}.highlight .nb{color:#0086b3}.highlight .nc{color:#458;font-weight:bold}.highlight .no{color:teal}.highlight .ni{color:purple}.highlight .ne{color:#900;font-weight:bold}.highlight .nf{color:#900;font-weight:bold}.highlight .nn{color:#555}.highlight .nt{color:navy}.highlight .nv{color:teal}.highlight .ow{font-weight:bold}.highlight .w{color:#bbb}.highlight .mf{color:#099}.highlight .mh{color:#099}.highlight .mi{color:#099}.highlight .mo{color:#099}.highlight .sb{color:#d14}.highlight .sc{color:#d14}.highlight .sd{color:#d14}.highlight .s2{color:#d14}.highlight .se{color:#d14}.highlight .sh{color:#d14}.highlight .si{color:#d14}.highlight .sx{color:#d14}.highlight .sr{color:#009926}.highlight .s1{color:#d14}.highlight .ss{color:#990073}.highlight .bp{color:#999}.highlight .vc{color:teal}.highlight .vg{color:teal}.highlight .vi{color:teal}.highlight .il{color:#099}:root{--primary-color: #64ffda;--primary-hover: #7affeb;--text-color: #ccd6f6;--text-light: #8892b0;--text-muted: #495670;--bg-color: #0a192f;--bg-light: #112240;--bg-alt: #1d2d50;--border-color: rgba(100, 255, 218, 0.1);--border-hover: rgba(100, 255, 218, 0.3);--code-bg: #1d2d50;--link-color: #64ffda;--link-hover: #7affeb}body{font-family:"Inter",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif !important;line-height:1.7 !important;color:var(--text-color) !important;background-color:var(--bg-color) !important;-webkit-font-smoothing:antialiased}.site-header{border-bottom:2px solid var(--border-color);background-color:var(--bg-light);padding:1rem 0}.site-header .site-title{font-size:1.5rem;font-weight:700;color:var(--primary-color);text-decoration:none}.site-header .site-title:hover{color:var(--primary-hover)}.site-header .site-nav .page-link{color:var(--text-color);font-weight:500;margin:0 .5rem;text-decoration:none;transition:color .2s}.site-header .site-nav .page-link:hover{color:var(--primary-color)}.page-content{padding:2rem 0;color:var(--text-color) !important;background-color:var(--bg-color) !important}.page-content,.page-content *{color:inherit}.docs-content{padding:2rem 0;color:var(--text-color) !important;background-color:var(--bg-color) !important}.docs-content h1{font-size:2.5rem;font-weight:800;margin-bottom:1rem;color:var(--text-color) !important;border-bottom:3px solid var(--primary-color);padding-bottom:.5rem}.docs-content h2{font-size:2rem;font-weight:700;margin-top:2rem;margin-bottom:1rem;color:var(--text-color) !important}.docs-content h3{font-size:1.5rem;font-weight:600;margin-top:1.5rem;margin-bottom:.75rem;color:var(--text-color) !important}.docs-content h4{font-size:1.25rem;font-weight:600;margin-top:1rem;margin-bottom:.5rem;color:var(--text-color) !important}.docs-content p{margin-bottom:1rem;color:var(--text-color) !important}.docs-content *{color:inherit}.docs-content a{color:var(--link-color);text-decoration:none;font-weight:500;transition:color .2s}.docs-content a:hover{color:var(--link-hover);text-decoration:underline}.docs-content ul,.docs-content ol{margin-bottom:1rem;padding-left:2rem;color:var(--text-color) !important}.docs-content ul li,.docs-content ol li{margin-bottom:.5rem;color:var(--text-color) !important}.docs-content ul li a,.docs-content ol li a{color:var(--link-color) !important}.docs-content ul li a:hover,.docs-content ol li a:hover{color:var(--link-hover) !important}.docs-content table{width:100%;border-collapse:collapse;margin:1.5rem 0;background-color:var(--bg-color) !important}.docs-content table th,.docs-content table td{padding:.75rem;border:1px solid var(--border-color);color:var(--text-color) !important}.docs-content table th{background-color:var(--bg-light) !important;font-weight:600;color:var(--text-color) !important}.docs-content table tr{background-color:var(--bg-color) !important}.docs-content table tr:nth-child(even){background-color:var(--bg-light) !important}.docs-content .highlighter-rouge{background-color:var(--code-bg) !important;border:1px solid var(--border-color);border-radius:.5rem;margin-bottom:1rem;font-family:"JetBrains Mono","Fira Code",monospace !important}.docs-content .highlighter-rouge .highlight{background-color:var(--code-bg) !important}.docs-content .highlighter-rouge .highlight pre{background-color:var(--code-bg) !important;border:none;border-radius:.5rem;padding:1rem;overflow-x:auto;margin:0;color:var(--text-color) !important}.docs-content .highlighter-rouge .highlight pre code{background-color:rgba(0,0,0,0) !important;padding:0;border:none;color:var(--text-color) !important;font-family:"JetBrains Mono","Fira Code",monospace !important}.docs-content pre{background-color:var(--code-bg) !important;border:1px solid var(--border-color);border-radius:.5rem;padding:1rem;overflow-x:auto;margin-bottom:1rem;color:var(--text-color) !important;font-family:"JetBrains Mono","Fira Code",monospace !important}.docs-content pre code{background-color:rgba(0,0,0,0) !important;padding:0;border:none;color:var(--text-color) !important;font-family:"JetBrains Mono","Fira Code",monospace !important}.docs-content code{background-color:var(--code-bg) !important;padding:.2rem .4rem;border-radius:.25rem;font-size:.9em;border:1px solid var(--border-color);color:var(--text-color) !important;font-family:"JetBrains Mono","Fira Code",monospace !important}.docs-content .highlight span{background-color:rgba(0,0,0,0) !important;color:var(--text-color) !important}.docs-content .highlight .c{color:#6a737d !important}.docs-content .highlight .k{color:#d73a49 !important}.docs-content .highlight .l{color:#005cc5 !important}.docs-content .highlight .n{color:var(--text-color) !important}.docs-content .highlight .o{color:#d73a49 !important}.docs-content .highlight .p{color:var(--text-color) !important}.docs-content .highlight .cm{color:#6a737d !important}.docs-content .highlight .cp{color:#6a737d !important}.docs-content .highlight .c1{color:#6a737d !important}.docs-content .highlight .cs{color:#6a737d !important}.docs-content .highlight .gd{color:#d73a49 !important}.docs-content .highlight .ge{font-style:italic !important}.docs-content .highlight .gr{color:#d73a49 !important}.docs-content .highlight .gh{color:var(--text-color) !important;font-weight:bold !important}.docs-content .highlight .gi{color:#28a745 !important}.docs-content .highlight .go{color:#6a737d !important}.docs-content .highlight .gp{color:#6a737d !important}.docs-content .highlight .gs{font-weight:bold !important}.docs-content .highlight .gu{color:var(--text-color) !important;font-weight:bold !important}.docs-content .highlight .gt{color:#d73a49 !important}.docs-content .highlight .kc{color:#005cc5 !important}.docs-content .highlight .kd{color:#d73a49 !important}.docs-content .highlight .kn{color:#d73a49 !important}.docs-content .highlight .kp{color:#d73a49 !important}.docs-content .highlight .kr{color:#d73a49 !important}.docs-content .highlight .kt{color:#d73a49 !important}.docs-content .highlight .ld{color:#032f62 !important}.docs-content .highlight .m{color:#005cc5 !important}.docs-content .highlight .s{color:#032f62 !important}.docs-content .highlight .na{color:#005cc5 !important}.docs-content .highlight .nb{color:#005cc5 !important}.docs-content .highlight .nc{color:#6f42c1 !important}.docs-content .highlight .no{color:#005cc5 !important}.docs-content .highlight .nd{color:#6f42c1 !important}.docs-content .highlight .ni{color:purple !important}.docs-content .highlight .ne{color:#900 !important;font-weight:bold !important}.docs-content .highlight .nf{color:#6f42c1 !important}.docs-content .highlight .nl{color:#005cc5 !important}.docs-content .highlight .nn{color:var(--text-color) !important}.docs-content .highlight .nx{color:var(--text-color) !important}.docs-content .highlight .py{color:var(--text-color) !important}.docs-content .highlight .nt{color:#22863a !important}.docs-content .highlight .nv{color:#e36209 !important}.docs-content .highlight .ow{color:#d73a49 !important}.docs-content .highlight .w{color:#bbb !important}.docs-content .highlight .mf{color:#005cc5 !important}.docs-content .highlight .mh{color:#005cc5 !important}.docs-content .highlight .mi{color:#005cc5 !important}.docs-content .highlight .mo{color:#005cc5 !important}.docs-content .highlight .sb{color:#032f62 !important}.docs-content .highlight .sc{color:#032f62 !important}.docs-content .highlight .sd{color:#6a737d !important}.docs-content .highlight .s2{color:#032f62 !important}.docs-content .highlight .se{color:#032f62 !important}.docs-content .highlight .sh{color:#032f62 !important}.docs-content .highlight .si{color:#032f62 !important}.docs-content .highlight .sx{color:#032f62 !important}.docs-content .highlight .sr{color:#032f62 !important}.docs-content .highlight .s1{color:#032f62 !important}.docs-content .highlight .ss{color:#032f62 !important}.docs-content .highlight .bp{color:var(--text-color) !important}.docs-content .highlight .vc{color:#e36209 !important}.docs-content .highlight .vg{color:#e36209 !important}.docs-content .highlight .vi{color:#e36209 !important}.docs-content .highlight .il{color:#005cc5 !important}.docs-content blockquote{border-left:4px solid var(--primary-color);padding-left:1rem;margin:1rem 0;color:var(--text-light);font-style:italic}.docs-content hr{border:none;border-top:2px solid var(--border-color);margin:2rem 0}.docs-content .emoji{font-size:1.2em}.docs-content .primary{background-color:var(--bg-light);border-left:4px solid var(--primary-color);padding:1rem;margin:1.5rem 0;border-radius:.25rem}.wrapper.docs-layout{max-width:1200px;margin:0 auto;padding:2rem 1rem;display:flex;gap:2rem;align-items:flex-start}.docs-sidebar{flex:0 0 260px;border-right:1px solid var(--border-color);background-color:var(--bg-light);padding:1.5rem 1rem;position:sticky;top:4rem;max-height:calc(100vh - 4rem);overflow-y:auto}.docs-sidebar-title{font-size:1.25rem;font-weight:700;margin:0 0 1rem 0}.docs-sidebar-title a{color:var(--primary-color);text-decoration:none}.docs-sidebar-title a:hover{color:var(--primary-hover);text-decoration:underline}.docs-nav{font-size:.95rem}.docs-nav-section{font-weight:600;margin:1rem 0 .5rem 0;color:var(--text-light);text-transform:uppercase;letter-spacing:.05em;font-size:.8rem}.docs-nav ul{list-style:none;margin:0 0 .5rem 0;padding-left:0}.docs-nav li{margin-bottom:.35rem}.docs-nav a{color:var(--text-color);text-decoration:none}.docs-nav a:hover{color:var(--primary-color);text-decoration:underline}.docs-content{flex:1 1 auto;min-width:0}.site-footer{border-top:2px solid var(--border-color);background-color:var(--bg-light);padding:2rem 0;margin-top:3rem;text-align:center;color:var(--text-light);font-size:.9rem}.site-footer .footer-heading{font-weight:600;margin-bottom:.5rem;color:var(--text-color)}.site-footer .footer-col-wrapper{display:flex;justify-content:center;flex-wrap:wrap;gap:2rem}.site-footer a{color:var(--link-color)}.site-footer a:hover{color:var(--link-hover)}@media screen and (max-width: 768px){.docs-layout{padding:1.5rem 1rem;flex-direction:column}.docs-sidebar{position:static;max-height:none;border-right:none;border-bottom:1px solid var(--border-color);margin-bottom:1rem}.site-header .site-title{font-size:1.25rem}.site-header .site-nav .page-link{margin:0 .25rem;font-size:.9rem}.page-content h1{font-size:2rem}.page-content h2{font-size:1.75rem}.page-content h3{font-size:1.25rem}.site-footer .footer-col-wrapper{flex-direction:column;gap:1rem}}.mermaid{background-color:var(--bg-light) !important;padding:1.5rem;border-radius:.5rem;border:1px solid var(--border-color);margin:1.5rem 0;overflow-x:auto}.mermaid svg{background-color:rgba(0,0,0,0) !important}.mermaid text{fill:var(--text-color) !important}.mermaid .node rect,.mermaid .node circle,.mermaid .node ellipse,.mermaid .node polygon{fill:var(--bg-alt) !important;stroke:var(--primary-color) !important}.mermaid .edgePath path,.mermaid .flowchart-link{stroke:var(--primary-color) !important}.mermaid .arrowheadPath{fill:var(--primary-color) !important}.mermaid .edgeLabel{background-color:var(--bg-light) !important;color:var(--text-color) !important}.mermaid .edgeLabel text{fill:var(--text-color) !important}@media print{.site-header,.site-footer{display:none}.page-content{max-width:100%;padding:0}} \ No newline at end of file diff --git a/_site_test/assets/minima-social-icons.svg b/_site_test/assets/minima-social-icons.svg new file mode 100644 index 0000000..fa7399f --- /dev/null +++ b/_site_test/assets/minima-social-icons.svg @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/_site_test/brownfield-engineer/index.html b/_site_test/brownfield-engineer/index.html new file mode 100644 index 0000000..e97995d --- /dev/null +++ b/_site_test/brownfield-engineer/index.html @@ -0,0 +1,648 @@ + + + + + + + +Modernizing Legacy Code (Brownfield Engineer Guide) | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Guide for Legacy Modernization Engineers

+ +
+

Complete walkthrough for modernizing legacy Python code with SpecFact CLI

+
+ +
+ +

Your Challenge

+ +

You’re responsible for modernizing a legacy Python system that:

+ +
    +
  • Has minimal or no documentation
    • +
  • Was built by developers who have left
    • +
  • Contains critical business logic you can’t risk breaking
    • +
  • Needs migration to modern Python, cloud infrastructure, or microservices
    • +
+ +

Sound familiar? You’re not alone. 70% of IT budgets are consumed by legacy maintenance, and the legacy modernization market is $25B+ and growing.

+ +
+ +

SpecFact for Brownfield: Your Safety Net

+ +

SpecFact CLI is designed specifically for your situation. It provides:

+ +
    +
  1. Automated spec extraction (code2spec) - Understand what your code does in < 10 seconds
    2. +
  2. Runtime contract enforcement - Prevent regressions during modernization
    3. +
  3. Symbolic execution - Discover hidden edge cases with CrossHair
    4. +
  4. Formal guarantees - Mathematical verification, not probabilistic LLM suggestions
    5. +
  5. CLI-first integration - Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. Works offline, no account required, no vendor lock-in.
    6. +
+ +
+ +

Step 1: Understand What You Have

+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

+ +

Extract Specs from Legacy Code

+ +
# Analyze your legacy codebase
+specfact import from-code --bundle legacy-api --repo ./legacy-app
+
+# For large codebases or multi-project repos, analyze specific modules:
+specfact import from-code --bundle core-module --repo ./legacy-app --entry-point src/core
+specfact import from-code --bundle api-module --repo ./legacy-app --entry-point src/api
+
+ +

What you get:

+ +
    +
  • ✅ Auto-generated feature map of existing functionality
    • +
  • ✅ Extracted user stories from code patterns
    • +
  • ✅ Dependency graph showing module relationships
    • +
  • ✅ Business logic documentation from function signatures
    • +
  • ✅ Edge cases discovered via symbolic execution
    • +
+ +

Example output:

+ +
✅ Analyzed 47 Python files
+✅ Extracted 23 features:
+
+   - FEATURE-001: User Authentication (95% confidence)
+   - FEATURE-002: Payment Processing (92% confidence)
+   - FEATURE-003: Order Management (88% confidence)
+   ...
+✅ Generated 112 user stories from existing code patterns
+✅ Detected 6 edge cases with CrossHair symbolic execution
+⏱️  Completed in 8.2 seconds
+
+ +

Time saved: 60-120 hours of manual documentation work → 8 seconds

+ +

💡 Partial Repository Coverage:

+ +

For large codebases or monorepos with multiple projects, you can analyze specific subdirectories using --entry-point:

+ +
# Analyze only the core module
+specfact import from-code --bundle core-module --repo . --entry-point src/core
+
+# Analyze only the API service
+specfact import from-code --bundle api-service --repo . --entry-point projects/api-service
+
+ +

This enables:

+ +
    +
  • Faster analysis - Focus on specific modules for quicker feedback
    • +
  • Incremental modernization - Modernize one module at a time
    • +
  • Multi-plan support - Create separate plan bundles for different projects/modules
    • +
  • Better organization - Keep plans organized by project boundaries
    • +
+ +

💡 Tip: After importing, the CLI may suggest generating a bootstrap constitution for Spec-Kit integration. This auto-generates a constitution from your repository analysis:

+ +
# If suggested, accept to auto-generate
+# Or run manually:
+specfact sdd constitution bootstrap --repo .
+
+ +

This is especially useful if you plan to sync with Spec-Kit later.

+ +
+ +

Step 2: Add Contracts to Critical Paths

+ +

Identify Critical Functions

+ +

SpecFact helps you identify which functions are critical (high risk, high business value):

+ +
# Review extracted plan to identify critical paths
+cat .specfact/projects/<bundle-name>/bundle.manifest.yaml
+
+ +

Add Runtime Contracts

+ +

Add contract decorators to critical functions:

+ +
# Before: Undocumented legacy function
+def process_payment(user_id, amount, currency):
+    # 80 lines of legacy code with hidden business rules
+    ...
+
+# After: Contract-enforced function
+import icontract
+
+@icontract.require(lambda amount: amount > 0, "Payment amount must be positive")
+@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP'])
+@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED'])
+def process_payment(user_id, amount, currency):
+    # Same 80 lines of legacy code
+    # Now with runtime enforcement
+    ...
+
+ +

What this gives you:

+ +
    +
  • ✅ Runtime validation catches invalid inputs immediately
    • +
  • ✅ Prevents regressions during refactoring
    • +
  • ✅ Documents expected behavior (executable documentation)
    • +
  • ✅ CrossHair discovers edge cases automatically
    • +
+ +
+ +

Step 3: Modernize with Confidence

+ +

Refactor Safely

+ +

With contracts in place, you can refactor knowing that violations will be caught:

+ +
# Refactored version (same contracts)
+@icontract.require(lambda amount: amount > 0, "Payment amount must be positive")
+@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP'])
+@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED'])
+def process_payment(user_id, amount, currency):
+    # Modernized implementation
+    # If contract violated → exception raised immediately
+    ...
+
+
+ +

Catch Regressions Automatically

+ +
# During modernization, accidentally break contract:
+process_payment(user_id=-1, amount=-50, currency="XYZ")
+
+# Runtime enforcement catches it:
+# ❌ ContractViolation: Payment amount must be positive (got -50)
+#    at process_payment() call from refactored checkout.py:142
+#    → Prevented production bug during modernization!
+
+ +
+ +

Step 4: Discover Hidden Edge Cases

+ +

CrossHair Symbolic Execution

+ +

SpecFact uses CrossHair to discover edge cases that manual testing misses:

+ +
# Legacy function with hidden edge case
+@icontract.require(lambda numbers: len(numbers) > 0)
+@icontract.ensure(lambda numbers, result: len(numbers) == 0 or min(numbers) > result)
+def remove_smallest(numbers: List[int]) -> int:
+    """Remove and return smallest number from list"""
+    smallest = min(numbers)
+    numbers.remove(smallest)
+    return smallest
+
+# CrossHair finds counterexample:
+# Input: [3, 3, 5] → After removal: [3, 5], min=3, returned=3
+# ❌ Postcondition violated: min(numbers) > result fails when duplicates exist!
+# CrossHair generates concrete failing input: [3, 3, 5]
+
+ +

Why this matters:

+ +
    +
  • ✅ Discovers edge cases LLMs miss
    • +
  • ✅ Mathematical proof of violations (not probabilistic)
    • +
  • ✅ Generates concrete test inputs automatically
    • +
  • ✅ Prevents production bugs before they happen
    • +
+ +
+ +

Real-World Example: Django Legacy App

+ +

The Problem

+ +

You inherited a 3-year-old Django app with:

+ +
    +
  • No documentation
    • +
  • No type hints
    • +
  • No tests
    • +
  • 15 undocumented API endpoints
    • +
  • Business logic buried in views
    • +
+ +

The Solution

+ +
# Step 1: Extract specs
+specfact import from-code --bundle customer-portal --repo ./legacy-django-app
+
+# Output:
+✅ Analyzed 47 Python files
+✅ Extracted 23 features (API endpoints, background jobs, integrations)
+✅ Generated 112 user stories from existing code patterns
+✅ Time: 8 seconds
+
+ +

The Results

+ +
    +
  • ✅ Legacy app fully documented in < 10 minutes
    • +
  • ✅ Prevented 4 production bugs during refactoring
    • +
  • ✅ New developers onboard 60% faster
    • +
  • ✅ CrossHair discovered 6 hidden edge cases
    • +
+ +
+ +

ROI: Time and Cost Savings

+ +

Manual Approach

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TaskTime InvestmentCost (@$150/hr)
Manually document 50-file legacy app80-120 hours$12,000-$18,000
Write tests for undocumented code100-150 hours$15,000-$22,500
Debug regression during refactor40-80 hours$6,000-$12,000
TOTAL220-350 hours$33,000-$52,500
+ +

SpecFact Automated Approach

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TaskTime InvestmentCost (@$150/hr)
Run code2spec extraction10 minutes$25
Review and refine extracted specs8-16 hours$1,200-$2,400
Add contracts to critical paths16-24 hours$2,400-$3,600
CrossHair edge case discovery2-4 hours$300-$600
TOTAL26-44 hours$3,925-$6,625
+ +

ROI: 87% time saved, $26,000-$45,000 cost avoided

+ +
+ +

Integration with Your Workflow

+ +

SpecFact CLI integrates seamlessly with your existing tools:

+ +
    +
  • VS Code: Use pre-commit hooks to catch breaking changes before commit
    • +
  • Cursor: AI assistant workflows catch regressions during refactoring
    • +
  • GitHub Actions: CI/CD integration blocks bad code from merging
    • +
  • Pre-commit hooks: Local validation prevents breaking changes
    • +
  • Any IDE: Pure CLI-first approach—works with any editor
    • +
+ +

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via integrations

+ +

Best Practices

+ +

1. Start with Shadow Mode

+ +

Begin in shadow mode to observe without blocking:

+ +
specfact import from-code --bundle legacy-api --repo . --shadow-only
+
+ +

2. Add Contracts Incrementally

+ +

Don’t try to contract everything at once:

+ +
    +
  1. Week 1: Add contracts to 3-5 critical functions
    2. +
  2. Week 2: Expand to 10-15 functions
    3. +
  3. Week 3: Add contracts to all public APIs
    4. +
  4. Week 4+: Add contracts to internal functions as needed
    5. +
+ +

3. Use CrossHair for Edge Case Discovery

+ +

Run CrossHair on critical functions before refactoring:

+ +
hatch run contract-explore src/payment.py
+
+ +

4. Document Your Findings

+ +

Keep notes on:

+ +
    +
  • Edge cases discovered
    • +
  • Contract violations caught
    • +
  • Time saved on documentation
    • +
  • Bugs prevented during modernization
    • +
+ +
+ +

Common Questions

+ +

Can SpecFact analyze code with no docstrings?

+ +

Yes. code2spec analyzes:

+ +
    +
  • Function signatures and type hints
    • +
  • Code patterns and control flow
    • +
  • Existing validation logic
    • +
  • Module dependencies
    • +
+ +

No docstrings needed.

+ +

What if the legacy code has no type hints?

+ +

SpecFact infers types from usage patterns and generates specs. You can add type hints incrementally as part of modernization.

+ +

Can SpecFact handle obfuscated or minified code?

+ +

Limited. SpecFact works best with:

+ +
    +
  • Source code (not compiled bytecode)
    • +
  • Readable variable names
    • +
+ +

For heavily obfuscated code, consider deobfuscation first.

+ +

Will contracts slow down my code?

+ +

Minimal impact. Contract checks are fast (microseconds per call). For high-performance code, you can disable contracts in production while keeping them in tests.

+ +
+ +

Next Steps

+ +
    +
  1. Integration Showcases - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations
    2. +
  2. ROI Calculator - Calculate your time and cost savings
    3. +
  3. Brownfield Journey - Complete modernization workflow
    4. +
  4. Examples - Real-world brownfield examples
    5. +
  5. FAQ - More brownfield-specific questions
    6. +
+ +
+ +

Support

+ + + +
+ +

Happy modernizing! 🚀

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/brownfield-journey/index.html b/_site_test/brownfield-journey/index.html new file mode 100644 index 0000000..7a3401a --- /dev/null +++ b/_site_test/brownfield-journey/index.html @@ -0,0 +1,701 @@ + + + + + + + +Brownfield Modernization Journey | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Brownfield Modernization Journey

+ +
+

Complete step-by-step workflow for modernizing legacy Python code with SpecFact CLI

+
+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

+ +
+ +

Overview

+ +

This guide walks you through the complete brownfield modernization journey:

+ +
    +
  1. Understand - Extract specs from legacy code
    2. +
  2. Protect - Add contracts to critical paths
    3. +
  3. Discover - Find hidden edge cases
    4. +
  4. Modernize - Refactor safely with contract safety net
    5. +
  5. Validate - Verify modernization success
    6. +
+ +

Time investment: 26-44 hours (vs. 220-350 hours manual)
+ROI: 87% time saved, $26,000-$45,000 cost avoided

+ +
+ +

Phase 1: Understand Your Legacy Code

+ +

Step 1.1: Extract Specs Automatically

+ +

CLI-First Integration: Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. See Integration Showcases for real examples.

+ +
# Analyze your legacy codebase
+specfact import from-code --bundle legacy-api --repo ./legacy-app
+
+ +

What happens:

+ +
    +
  • SpecFact analyzes all Python files
    • +
  • Extracts features, user stories, and business logic
    • +
  • Generates dependency graphs
    • +
  • Creates plan bundle with extracted specs
    • +
+ +

Output:

+ +
✅ Analyzed 47 Python files
+✅ Extracted 23 features
+✅ Generated 112 user stories
+⏱️  Completed in 8.2 seconds
+
+ +

Time saved: 60-120 hours of manual documentation → 8 seconds

+ +

💡 Tip: After importing, the CLI may suggest generating a bootstrap constitution for Spec-Kit integration. This auto-generates a constitution from your repository analysis:

+ +
# If suggested, accept to auto-generate
+# Or run manually:
+specfact sdd constitution bootstrap --repo .
+
+ +

This is especially useful if you plan to sync with Spec-Kit later.

+ +

Step 1.2: Review Extracted Specs

+ +
# Review the extracted plan using CLI commands
+specfact plan review --bundle legacy-api
+
+ +

What to look for:

+ +
    +
  • High-confidence features (95%+) - These are well-understood
    • +
  • Low-confidence features (<70%) - These need manual review
    • +
  • Missing features - May indicate incomplete extraction
    • +
  • Edge cases - Already discovered by CrossHair
    • +
+ +

Step 1.3: Validate Extraction Quality

+ +
# Compare extracted plan to your understanding (bundle directory paths)
+specfact plan compare \
+  --manual .specfact/projects/manual-plan \
+  --auto .specfact/projects/your-project
+
+ +

What you get:

+ +
    +
  • Deviations between manual and auto-derived plans
    • +
  • Missing features in extraction
    • +
  • Extra features in extraction (may be undocumented functionality)
    • +
+ +
+ +

Phase 2: Protect Critical Paths

+ +

Step 2.1: Identify Critical Functions

+ +

Criteria for “critical”:

+ +
    +
  • High business value (payment, authentication, data processing)
    • +
  • High risk (production bugs would be costly)
    • +
  • Complex logic (hard to understand, easy to break)
    • +
  • Frequently called (high impact if broken)
    • +
+ +

Review extracted plan:

+ +
# Review plan using CLI commands
+specfact plan review --bundle legacy-api
+
+ +

Step 2.2: Add Contracts Incrementally

+ +

Week 1: Start with 3-5 critical functions

+ +
# Example: Add contracts to payment processing
+import icontract
+
+@icontract.require(lambda amount: amount > 0, "Amount must be positive")
+@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP'])
+@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED'])
+def process_payment(user_id, amount, currency):
+    # Legacy code with contracts
+    ...
+
+ +

Week 2: Expand to 10-15 functions

+ +

Week 3: Add contracts to all public APIs

+ +

Week 4+: Add contracts to internal functions as needed

+ +

Step 2.3: Start in Shadow Mode

+ +

Shadow mode observes violations without blocking:

+ +
# Run in shadow mode (observe only)
+specfact enforce --mode shadow
+
+ +

Benefits:

+ +
    +
  • See violations without breaking workflow
    • +
  • Understand contract behavior before enforcing
    • +
  • Build confidence gradually
    • +
+ +

Graduation path:

+ +
    +
  1. Shadow mode (Week 1) - Observe only
    2. +
  2. Warn mode (Week 2) - Log violations, don’t block
    3. +
  3. Block mode (Week 3+) - Raise exceptions on violations
    4. +
+ +
+ +

Phase 3: Discover Hidden Edge Cases

+ +

Step 3.1: Run CrossHair on Critical Functions

+ +
# Discover edge cases in payment processing
+hatch run contract-explore src/payment.py
+
+ +

What CrossHair does:

+ +
    +
  • Explores all possible code paths symbolically
    • +
  • Finds inputs that violate contracts
    • +
  • Generates concrete test cases for violations
    • +
+ +

Example output:

+ +
❌ Postcondition violation found:
+   Function: process_payment
+   Input: amount=0.0, currency='USD'
+   Issue: Amount must be positive (got 0.0)
+
+
+ +

Step 3.2: Fix Discovered Edge Cases

+ +
# Add validation for edge cases
+@icontract.require(
+    lambda amount: amount > 0 and amount <= 1000000,
+    "Amount must be between 0 and 1,000,000"
+)
+def process_payment(...):
+    # Now handles edge cases discovered by CrossHair
+    ...
+
+ +

Step 3.3: Document Edge Cases

+ +

Keep notes on:

+ +
    +
  • Edge cases discovered
    • +
  • Contract violations found
    • +
  • Fixes applied
    • +
  • Test cases generated
    • +
+ +

Why this matters:

+ +
    +
  • Prevents regressions in future refactoring
    • +
  • Documents hidden business rules
    • +
  • Helps new team members understand code
    • +
+ +
+ +

Phase 4: Modernize Safely

+ +

Step 4.1: Refactor Incrementally

+ +

One function at a time:

+ +
    +
  1. Add contracts to function (if not already done)
    2. +
  2. Run CrossHair to discover edge cases
    3. +
  3. Refactor function implementation
    4. +
  4. Verify contracts still pass
    5. +
  5. Move to next function
    6. +
+ +

Example:

+ +
# Before: Legacy implementation
+@icontract.require(lambda amount: amount > 0)
+def process_payment(user_id, amount, currency):
+    # 80 lines of legacy code
+    ...
+
+# After: Modernized implementation (same contracts)
+@icontract.require(lambda amount: amount > 0)
+def process_payment(user_id, amount, currency):
+    # Modernized code (same contracts protect behavior)
+    payment_service = PaymentService()
+    return payment_service.process(user_id, amount, currency)
+
+ +

Step 4.2: Catch Regressions Automatically

+ +

Contracts catch violations during refactoring:

+ +
# During modernization, accidentally break contract:
+process_payment(user_id=-1, amount=-50, currency="XYZ")
+
+# Runtime enforcement catches it:
+# ❌ ContractViolation: Amount must be positive (got -50)
+#    → Fix the bug before it reaches production!
+
+
+ +

Step 4.3: Verify Modernization Success

+ +
# Run contract validation
+hatch run contract-test-full
+
+# Check for violations
+specfact enforce --mode block
+
+ +

Success criteria:

+ +
    +
  • ✅ All contracts pass
    • +
  • ✅ No new violations introduced
    • +
  • ✅ Edge cases still handled
    • +
  • ✅ Performance acceptable
    • +
+ +
+ +

Phase 5: Validate and Measure

+ +

Step 5.1: Measure ROI

+ +

Track metrics:

+ +
    +
  • Time saved on documentation
    • +
  • Bugs prevented during modernization
    • +
  • Edge cases discovered
    • +
  • Developer onboarding time reduction
    • +
+ +

Example metrics:

+ +
    +
  • Documentation: 87% time saved (8 hours vs. 60 hours)
    • +
  • Bugs prevented: 4 production bugs
    • +
  • Edge cases: 6 discovered automatically
    • +
  • Onboarding: 60% faster (3-5 days vs. 2-3 weeks)
    • +
+ +

Step 5.2: Document Success

+ +

Create case study:

+ +
    +
  • Problem statement
    • +
  • Solution approach
    • +
  • Quantified results
    • +
  • Lessons learned
    • +
+ +

Why this matters:

+ +
    +
  • Validates approach for future projects
    • +
  • Helps other teams learn from your experience
    • +
  • Builds confidence in brownfield modernization
    • +
+ +
+ +

Real-World Example: Complete Journey

+ +

The Problem

+ +

Legacy Django app:

+ +
    +
  • 47 Python files
    • +
  • No documentation
    • +
  • No type hints
    • +
  • No tests
    • +
  • 15 undocumented API endpoints
    • +
+ +

The Journey

+ +

Week 1: Understand

+ +
    +
  • Ran specfact import from-code --bundle legacy-api --repo . → 23 features extracted in 8 seconds
    • +
  • Reviewed extracted plan → Identified 5 critical features
    • +
  • Time: 2 hours (vs. 60 hours manual)
    • +
+ +

Week 2: Protect

+ +
    +
  • Added contracts to 5 critical functions
    • +
  • Started in shadow mode → Observed 3 violations
    • +
  • Time: 16 hours
    • +
+ +

Week 3: Discover

+ +
    +
  • Ran CrossHair on critical functions → Discovered 6 edge cases
    • +
  • Fixed edge cases → Added validation
    • +
  • Time: 4 hours
    • +
+ +

Week 4: Modernize

+ +
    +
  • Refactored 5 critical functions with contract safety net
    • +
  • Caught 4 regressions automatically (contracts prevented bugs)
    • +
  • Time: 24 hours
    • +
+ +

Week 5: Validate

+ +
    +
  • All contracts passing
    • +
  • No production bugs from modernization
    • +
  • New developers productive in 3 days (vs. 2-3 weeks)
    • +
+ +

The Results

+ +
    +
  • ✅ 87% time saved on documentation (8 hours vs. 60 hours)
    • +
  • ✅ 4 production bugs prevented during modernization
    • +
  • ✅ 6 edge cases discovered automatically
    • +
  • ✅ 60% faster onboarding (3-5 days vs. 2-3 weeks)
    • +
  • ✅ Zero downtime modernization
    • +
+ +

ROI: $42,000 saved, 5-week acceleration

+ +
+ +

Best Practices

+ +

1. Start Small

+ +
    +
  • Don’t try to contract everything at once
    • +
  • Start with 3-5 critical functions
    • +
  • Expand incrementally
    • +
+ +

2. Use Shadow Mode First

+ +
    +
  • Observe violations before enforcing
    • +
  • Build confidence gradually
    • +
  • Graduate to warn → block mode
    • +
+ +

3. Run CrossHair Early

+ +
    +
  • Discover edge cases before refactoring
    • +
  • Fix issues proactively
    • +
  • Document findings
    • +
+ +

4. Refactor Incrementally

+ +
    +
  • One function at a time
    • +
  • Verify contracts after each refactor
    • +
  • Don’t rush
    • +
+ +

5. Document Everything

+ +
    +
  • Edge cases discovered
    • +
  • Contract violations found
    • +
  • Fixes applied
    • +
  • Lessons learned
    • +
+ +
+ +

Common Pitfalls

+ +

❌ Trying to Contract Everything at Once

+ +

Problem: Overwhelming, slows down development

+ +

Solution: Start with 3-5 critical functions, expand incrementally

+ +

❌ Skipping Shadow Mode

+ +

Problem: Too many violations, breaks workflow

+ +

Solution: Always start in shadow mode, graduate gradually

+ +

❌ Ignoring CrossHair Findings

+ +

Problem: Edge cases discovered but not fixed

+ +

Solution: Fix edge cases before refactoring

+ +

❌ Refactoring Too Aggressively

+ +

Problem: Breaking changes, contract violations

+ +

Solution: Refactor incrementally, verify contracts after each change

+ +
+ +

Next Steps

+ +
    +
  1. Integration Showcases - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations
    2. +
  2. Brownfield Engineer Guide - Complete persona guide
    3. +
  3. ROI Calculator - Calculate your savings
    4. +
  4. Examples - Real-world brownfield examples
    5. +
  5. FAQ - More brownfield questions
    6. +
+ +
+ +

Support

+ + + +
+ +

Happy modernizing! 🚀

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/common-tasks/index.html b/_site_test/common-tasks/index.html new file mode 100644 index 0000000..15fd2cd --- /dev/null +++ b/_site_test/common-tasks/index.html @@ -0,0 +1,632 @@ + + + + + + + +Common Tasks Quick Reference | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Common Tasks Quick Reference

+ +
+

Quick answers to “How do I X?” questions

+
+ +
+ +

Overview

+ +

This guide maps common user goals to recommended SpecFact CLI commands or command chains. Each entry includes a task description, recommended approach, link to detailed guide, and a quick example.

+ +

Not sure which task matches your goal? Use the Command Chains Decision Tree to find the right workflow.

+ +
+ +

Getting Started

+ +

I want to analyze my legacy code

+ +

Recommended: Brownfield Modernization Chain

+ +

Command: import from-code

+ +

Quick Example:

+ +
specfact import from-code --bundle legacy-api --repo .
+
+ +

Detailed Guide: Brownfield Engineer Guide

+ +
+ +

I want to plan a new feature from scratch

+ +

Recommended: Greenfield Planning Chain

+ +

Command: plan init → plan add-feature → plan add-story

+ +

Quick Example:

+ +
specfact plan init --bundle new-feature --interactive
+specfact plan add-feature --bundle new-feature --name "User Authentication"
+specfact plan add-story --bundle new-feature --feature <feature-id> --story "As a user, I want to log in"
+
+ +

Detailed Guide: Agile/Scrum Workflows

+ +
+ +

I want to sync with Spec-Kit or OpenSpec

+ +

Recommended: External Tool Integration Chain

+ +

Command: import from-bridge → sync bridge

+ +

Quick Example:

+ +
specfact import from-bridge --repo . --adapter speckit --write
+specfact sync bridge --adapter speckit --bundle <bundle-name> --bidirectional --watch
+
+ + + + + + + + +
Detailed Guide: Spec-Kit JourneyOpenSpec Journey
+ +
+ +

Brownfield Modernization

+ +

I want to extract specifications from existing code

+ +

Recommended: import from-code

+ +

Quick Example:

+ +
specfact import from-code --bundle legacy-api --repo ./legacy-app
+
+ +

Detailed Guide: Brownfield Engineer Guide

+ +
+ +

I want to review and update extracted features

+ +

Recommended: plan review → plan update-feature

+ +

Quick Example:

+ +
specfact plan review --bundle legacy-api
+specfact plan update-feature --bundle legacy-api --feature <feature-id>
+
+ +

Detailed Guide: Brownfield Engineer Guide

+ +
+ +

I want to detect code-spec drift

+ +

Recommended: Code-to-Plan Comparison Chain

+ +

Command: plan compare → drift detect

+ +

Quick Example:

+ +
specfact import from-code --bundle current-state --repo .
+specfact plan compare --bundle <plan-bundle> --code-vs-plan
+specfact drift detect --bundle <bundle-name>
+
+ +

Detailed Guide: Drift Detection

+ +
+ +

I want to add contracts to existing code

+ +

Recommended: AI-Assisted Code Enhancement Chain

+ +

Command: generate contracts-prompt → [AI IDE] → contracts-apply

+ +

Quick Example:

+ +
specfact generate contracts-prompt --bundle <bundle-name> --feature <feature-id>
+# Then use AI IDE slash command: /specfact-cli/contracts-apply <prompt-file>
+specfact contract coverage --bundle <bundle-name>
+
+ +

Detailed Guide: AI IDE Workflow

+ +
+ +

API Development

+ +

I want to validate API contracts

+ +

Recommended: API Contract Development Chain

+ +

Command: spec validate → spec backward-compat

+ +

Quick Example:

+ +
specfact spec validate --spec openapi.yaml
+specfact spec backward-compat --spec openapi.yaml --previous-spec openapi-v1.yaml
+
+ +

Detailed Guide: Specmatic Integration

+ +
+ +

I want to generate tests from API specifications

+ +

Recommended: spec generate-tests

+ +

Quick Example:

+ +
specfact spec generate-tests --spec openapi.yaml --output tests/
+pytest tests/
+
+ +

Detailed Guide: Contract Testing Workflow

+ +
+ +

I want to create a mock server for API development

+ +

Recommended: spec mock

+ +

Quick Example:

+ +
specfact spec mock --spec openapi.yaml --port 8080
+
+ +

Detailed Guide: Specmatic Integration

+ +
+ +

Team Collaboration

+ +

I want to set up team collaboration

+ +

Recommended: Team Collaboration Workflow

+ +

Command: project export → project import → project lock/unlock

+ +

Quick Example:

+ +
specfact project init-personas --bundle <bundle-name>
+specfact project export --bundle <bundle-name> --persona product-owner
+# Edit exported Markdown files
+specfact project import --bundle <bundle-name> --persona product-owner --source exported-plan.md
+
+ +

Detailed Guide: Agile/Scrum Workflows

+ +
+ +

I want to export persona-specific views

+ +

Recommended: project export

+ +

Quick Example:

+ +
specfact project export --bundle <bundle-name> --persona product-owner
+specfact project export --bundle <bundle-name> --persona architect
+specfact project export --bundle <bundle-name> --persona developer
+
+ +

Detailed Guide: Agile/Scrum Workflows

+ +
+ +

I want to manage project versions

+ +

Recommended: project version check → project version bump

+ +

Quick Example:

+ +
specfact project version check --bundle <bundle-name>
+specfact project version bump --bundle <bundle-name> --type minor
+
+ +

Detailed Guide: Project Version Management

+ +
+ +

Plan Management

+ +

I want to promote a plan through stages

+ +

Recommended: Plan Promotion & Release Chain

+ +

Command: plan review → enforce sdd → plan promote

+ +

Quick Example:

+ +
specfact plan review --bundle <bundle-name>
+specfact enforce sdd --bundle <bundle-name>
+specfact plan promote --bundle <bundle-name> --stage approved
+
+ +

Detailed Guide: Agile/Scrum Workflows

+ +
+ +

I want to compare two plans

+ +

Recommended: plan compare

+ +

Quick Example:

+ +
specfact plan compare --bundle plan-v1 plan-v2
+
+ +

Detailed Guide: Plan Comparison

+ +
+ +

Validation & Enforcement

+ +

I want to validate everything

+ +

Recommended: repro

+ +

Quick Example:

+ +
specfact repro --verbose
+
+ +

Detailed Guide: Validation Workflow

+ +
+ +

I want to enforce SDD compliance

+ +

Recommended: enforce sdd

+ +

Quick Example:

+ +
specfact enforce sdd --bundle <bundle-name>
+
+ +

Detailed Guide: SDD Enforcement

+ +
+ +

I want to find gaps in my code

+ +

Recommended: Gap Discovery & Fixing Chain

+ +

Command: repro --verbose → generate fix-prompt

+ +

Quick Example:

+ +
specfact repro --verbose
+specfact generate fix-prompt --bundle <bundle-name> --gap <gap-id>
+# Then use AI IDE to apply fixes
+
+ +

Detailed Guide: AI IDE Workflow

+ +
+ +

AI IDE Integration

+ +

I want to set up AI IDE slash commands

+ +

Recommended: init --ide cursor

+ +

Quick Example:

+ +
specfact init --ide cursor
+
+ + + + + + + + +
Detailed Guide: AI IDE WorkflowIDE Integration
+ +
+ +

I want to generate tests using AI

+ +

Recommended: Test Generation from Specifications Chain

+ +

Command: generate test-prompt → [AI IDE] → spec generate-tests

+ +

Quick Example:

+ +
specfact generate test-prompt --bundle <bundle-name> --feature <feature-id>
+# Then use AI IDE slash command: /specfact-cli/test-generate <prompt-file>
+specfact spec generate-tests --spec <spec-file> --output tests/
+
+ +

Detailed Guide: AI IDE Workflow

+ +
+ +

DevOps Integration

+ +

I want to sync change proposals to GitHub Issues

+ +

Recommended: sync bridge --mode export-only

+ +

Quick Example:

+ +
specfact sync bridge --adapter github --mode export-only --repo-owner owner --repo-name repo
+
+ +

Detailed Guide: DevOps Adapter Integration

+ +
+ +

I want to track changes in GitHub Projects

+ +

Recommended: DevOps bridge adapter with project linking

+ +

Quick Example:

+ +
specfact sync bridge --adapter github --mode export-only --project "SpecFact CLI Development Board"
+
+ +

Detailed Guide: DevOps Adapter Integration

+ +
+ +

Migration & Troubleshooting

+ +

I want to migrate from an older version

+ +

Recommended: Check migration guides

+ +

Quick Example:

+ +
# Check current version
+specfact --version
+
+# Review migration guide for your version
+# See: guides/migration-*.md
+
+ + + + + + + + +
Detailed Guide: Migration GuideTroubleshooting
+ +
+ +

I want to troubleshoot an issue

+ +

Recommended: Troubleshooting Guide

+ +

Quick Example:

+ +
# Run validation with verbose output
+specfact repro --verbose
+
+# Check plan for issues
+specfact plan review --bundle <bundle-name>
+
+ +

Detailed Guide: Troubleshooting

+ +
+ +

See Also

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/competitive-analysis/index.html b/_site_test/competitive-analysis/index.html new file mode 100644 index 0000000..f18695e --- /dev/null +++ b/_site_test/competitive-analysis/index.html @@ -0,0 +1,634 @@ + + + + + + + +Competitive Analysis | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

What You Gain with SpecFact CLI

+ +

How SpecFact CLI complements and extends other development tools.

+ +

Overview

+ +

SpecFact CLI is a brownfield-first legacy code modernization tool that reverse engineers existing Python code into documented specs, then enforces them as runtime contracts. It builds on the strengths of specification tools like GitHub Spec-Kit and works alongside AI coding platforms to provide production-ready quality gates for legacy codebases.

+ +
+ +

Building on Specification Tools

+ +

SpecFact CLI integrates with multiple specification and planning tools through a plugin-based adapter architecture:

+ +
    +
  • GitHub Spec-Kit - Interactive specification authoring
    • +
  • OpenSpec - Specification anchoring and change tracking (v0.22.0+)
    • +
  • GitHub Issues - DevOps backlog integration
    • +
  • Future: Linear, Jira, Azure DevOps, and more
    • +
+ +

Building on GitHub Spec-Kit

+ +

What Spec-Kit Does Great

+ +

GitHub Spec-Kit pioneered the concept of living specifications with interactive slash commands. It’s excellent for:

+ +
    +
  • ✅ Interactive Specification - Slash commands (/speckit.specify, /speckit.plan) with AI assistance
    • +
  • ✅ Rapid Prototyping - Quick spec → plan → tasks → code workflow for new features
    • +
  • ✅ Learning & Exploration - Great for understanding state machines, contracts, requirements
    • +
  • ✅ IDE Integration - CoPilot chat makes it accessible to less technical developers
    • +
  • ✅ Constitution & Planning - Add constitution, plans, and feature breakdowns for new features
    • +
  • ✅ Single-Developer Projects - Perfect for personal projects and learning
    • +
+ +

Note: Spec-Kit excels at working with new features - you can add constitution, create plans, and break down features for things you’re building from scratch.

+ +

What SpecFact CLI Adds To GitHub Spec-Kit

+ +

SpecFact CLI complements Spec-Kit by adding automation and enforcement:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EnhancementWhat You Get
Automated enforcementRuntime + static contract validation, CI/CD gates
Shared plansShared structured plans enable team collaboration with automated bidirectional sync (not just manual markdown sharing like Spec-Kit)
Code vs plan drift detectionAutomated comparison of intended design (manual plan) vs actual implementation (code-derived plan from import from-code)
CI/CD integrationAutomated quality gates in your pipeline
Brownfield supportAnalyze existing code to complement Spec-Kit’s greenfield focus
Property testingFSM fuzzing, Hypothesis-based validation
No-escape gatesBudget-based enforcement prevents violations
Bidirectional syncKeep using Spec-Kit interactively, sync automatically with SpecFact
+ +

The Journey: From Spec-Kit to SpecFact

+ +

Spec-Kit and SpecFact are complementary, not competitive:

+ +
    +
  • Stage 1: Spec-Kit - Interactive authoring with slash commands (/speckit.specify, /speckit.plan)
    • +
  • Stage 2: SpecFact - Automated enforcement (CI/CD gates, contract validation)
    • +
  • Stage 3: Bidirectional Sync - Use both tools together (Spec-Kit authoring + SpecFact enforcement)
    • +
+ +

Learn the full journey →

+ +

Working With OpenSpec

+ +

OpenSpec is another complementary tool that focuses on specification anchoring and change tracking. SpecFact CLI integrates with OpenSpec via the OpenSpec adapter (available in v0.22.0+):

+ +
    +
  • OpenSpec manages specifications and change proposals (the “what” and “why”)
    • +
  • SpecFact analyzes existing code and enforces contracts (the “how” and “safety”)
    • +
  • Bridge Adapters sync change proposals to DevOps tools (the “tracking”)
    • +
+ +

Integration:

+ +
# Read-only sync from OpenSpec to SpecFact (v0.22.0+)
+specfact sync bridge --adapter openspec --mode read-only \
+  --bundle my-project \
+  --repo /path/to/openspec-repo
+
+# Export OpenSpec change proposals to GitHub Issues
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner your-org \
+  --repo-name your-repo \
+  --repo /path/to/openspec-repo
+
+ +

Learn the full OpenSpec integration journey →

+ +

Seamless Migration

+ +

Already using Spec-Kit? SpecFact CLI imports your work in one command:

+ +
specfact import from-bridge --adapter speckit --repo ./my-speckit-project --write
+
+ +

Result: Your Spec-Kit artifacts (spec.md, plan.md, tasks.md) become production-ready contracts with zero manual work.

+ +

Ongoing: Keep using Spec-Kit interactively, sync automatically with SpecFact:

+ +
# Enable bidirectional sync (bridge-based, adapter-agnostic)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Best of both worlds: Interactive authoring (Spec-Kit) + Automated enforcement (SpecFact)

+ +

Note: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in AdapterRegistry and accessed via specfact sync bridge --adapter <adapter-name>, making the architecture extensible for future tool integrations.

+ +

Team collaboration: Shared structured plans enable multiple developers to work on the same plan with automated deviation detection. Unlike Spec-Kit’s manual markdown sharing, SpecFact provides automated bidirectional sync that keeps plans synchronized across team members:

+ +
# Enable bidirectional sync for team collaboration
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+# → Automatically syncs Spec-Kit artifacts ↔ SpecFact project bundles
+# → Multiple developers can work on the same plan with automated synchronization
+# → No manual markdown sharing required
+
+# Detect code vs plan drift automatically
+specfact plan compare --bundle legacy-api --code-vs-plan
+# → Compares intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code)
+# → Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift"
+# → Identifies deviations automatically (not just artifact consistency like Spec-Kit's /speckit.analyze)
+
+ +
+ +

Working With AI Coding Tools

+ +

What AI Tools Do Great

+ +

Tools like Replit Agent 3, Lovable, Cursor, and Copilot excel at:

+ +
    +
  • ✅ Rapid code generation
    • +
  • ✅ Quick prototyping
    • +
  • ✅ Learning and exploration
    • +
  • ✅ Boilerplate reduction
    • +
+ +

What SpecFact CLI Adds To AI Coding Tools

+ +

SpecFact CLI validates AI-generated code with:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EnhancementWhat You Get
Contract validationEnsure AI code meets your specs
Runtime sentinelsCatch async anti-patterns automatically
No-escape gatesBlock broken code from merging
Offline validationWorks in air-gapped environments
Evidence trailsReproducible proof of quality
Team standardsEnforce consistent patterns across AI-generated code
CoPilot integrationSlash commands for seamless IDE workflow
Agent mode routingEnhanced prompts for better AI assistance
+ +

Perfect Combination

+ +

AI tools generate code fast → SpecFact CLI ensures it’s correct

+ +

Use AI for speed, use SpecFact for quality.

+ +

CoPilot-Enabled Mode

+ +

When using Cursor, Copilot, or other AI assistants, SpecFact CLI integrates seamlessly:

+ +
# Slash commands in IDE (after specfact init)
+specfact init --ide cursor
+/specfact.01-import legacy-api --repo . --confidence 0.7
+/specfact.02-plan init legacy-api
+/specfact.06-sync --repo . --bidirectional
+
+ +

Benefits:

+ +
    +
  • Automatic mode detection - Switches to CoPilot mode when available
    • +
  • Context injection - Uses current file, selection, and workspace context
    • +
  • Enhanced prompts - Optimized for AI understanding
    • +
  • Agent mode routing - Specialized prompts for different operations
    • +
+ +
+ +

Key Capabilities

+ +

1. Temporal Contracts

+ +

What it means: State machines with runtime validation

+ +

Why developers love it: Catches state transition bugs automatically

+ +

Example:

+ +
# Protocol enforces valid state transitions
+transitions:
+  - from_state: CONNECTED
+    on_event: disconnect
+    to_state: DISCONNECTING
+    guard: no_pending_messages  # ✅ Checked at runtime
+
+ +

2. Proof-Carrying Promotion

+ +

What it means: Evidence required before code merges

+ +

Why developers love it: “Works on my machine” becomes provable

+ +

Example:

+ +
# PR includes reproducible evidence
+specfact repro --budget 120 --report evidence.md
+
+ +

3. Brownfield-First ⭐ PRIMARY

+ +

What it means: Primary use case - Reverse engineer existing legacy code into documented specs, then enforce contracts to prevent regressions during modernization.

+ +

Why developers love it: Understand undocumented legacy code in minutes, not weeks. Modernize with confidence knowing contracts catch regressions automatically.

+ +

Example:

+ +
# Primary use case: Analyze legacy code
+specfact import from-code --bundle legacy-api --repo ./legacy-app
+
+# Extract specs from existing code in < 10 seconds
+# Then enforce contracts to prevent regressions
+specfact enforce stage --preset balanced
+
+ +

How it complements Spec-Kit: Spec-Kit focuses on new feature authoring (greenfield); SpecFact CLI’s primary focus is brownfield code modernization with runtime enforcement.

+ +

4. Code vs Plan Drift Detection

+ +

What it means: Automated comparison of intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what’s in your code). Auto-derived plans come from import from-code (code analysis), so comparison IS “code vs plan drift”.

+ +

Why developers love it: Detects code vs plan drift automatically (not just artifact consistency like Spec-Kit’s /speckit.analyze). Spec-Kit’s /speckit.analyze only checks artifact consistency between markdown files; SpecFact CLI detects actual code vs plan drift by comparing manual plans (intended design) with code-derived plans (actual implementation from code analysis).

+ +

Example:

+ +
# Detect code vs plan drift automatically
+specfact plan compare --bundle legacy-api --code-vs-plan
+# → Compares intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code)
+# → Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift"
+# → Identifies deviations automatically (not just artifact consistency like Spec-Kit's /speckit.analyze)
+
+ +

How it complements Spec-Kit: Spec-Kit’s /speckit.analyze only checks artifact consistency between markdown files; SpecFact CLI detects code vs plan drift by comparing manual plans (intended design) with code-derived plans (actual implementation from import from-code).

+ +

5. Evidence-Based

+ +

What it means: Reproducible validation and reports

+ +

Why developers love it: Debug failures with concrete data

+ +

Example:

+ +
# Generate reproducible evidence
+specfact repro --report evidence.md
+
+ +

6. Offline-First

+ +

What it means: Works without internet connection

+ +

Why developers love it: Air-gapped environments, no data exfiltration, fast

+ +

Example:

+ +
# Works completely offline
+uvx specfact-cli@latest plan init --interactive
+
+ +
+ +

When to Use SpecFact CLI

+ +

SpecFact CLI is Perfect For ⭐ PRIMARY

+ +
    +
  • ✅ Legacy code modernization ⭐ - Reverse engineer undocumented code into specs
    • +
  • ✅ Brownfield projects ⭐ - Understand and modernize existing Python codebases
    • +
  • ✅ High-risk refactoring ⭐ - Prevent regressions with runtime contract enforcement
    • +
  • ✅ Production systems - Need quality gates and validation
    • +
  • ✅ Team projects - Multiple developers need consistent standards
    • +
  • ✅ Compliance environments - Evidence-based validation required
    • +
  • ✅ Air-gapped deployments - Offline-first architecture
    • +
  • ✅ Open source projects - Transparent, inspectable tooling
    • +
+ +

SpecFact CLI Works Alongside

+ +
    +
  • ✅ AI coding assistants - Validate AI-generated code
    • +
  • ✅ Spec-Kit projects - One-command import
    • +
  • ✅ Existing CI/CD - Drop-in quality gates
    • +
  • ✅ Your IDE - Command-line or extension (v0.2)
    • +
+ +
+ +

Getting Started With SpecFact CLI

+ +

Modernizing Legacy Code? ⭐ PRIMARY

+ +

Reverse engineer existing code:

+ +
# Primary use case: Analyze legacy codebase
+specfact import from-code --bundle legacy-api --repo ./legacy-app
+
+ +

See Use Cases: Brownfield Modernization ⭐

+ +

Already Using Spec-Kit? (Secondary)

+ +

One-command import:

+ +
specfact import from-bridge --adapter speckit --repo . --write
+
+ +

See Use Cases: Spec-Kit Migration

+ +

Using AI Coding Tools?

+ +

Add validation layer:

+ +
    +
  1. Let AI generate code as usual
    2. +
  2. Run specfact import from-code --repo . (auto-detects CoPilot mode)
    3. +
  3. Review auto-generated plan
    4. +
  4. Enable specfact enforce stage --preset balanced
    5. +
+ +

With CoPilot Integration:

+ +

Use slash commands directly in your IDE:

+ +
# First, initialize IDE integration
+specfact init --ide cursor
+
+# Then use slash commands in IDE chat
+/specfact.01-import legacy-api --repo . --confidence 0.7
+/specfact.compare --bundle legacy-api
+/specfact.06-sync --repo . --bidirectional
+
+ +

SpecFact CLI automatically detects CoPilot and switches to enhanced mode.

+ +

Starting From Scratch?

+ +

Greenfield approach:

+ +
    +
  1. specfact plan init --bundle legacy-api --interactive
    2. +
  2. Add features and stories
    3. +
  3. Enable strict enforcement
    4. +
  4. Let SpecFact guide development
    5. +
+ +

See Getting Started for detailed setup.

+ +
+ +

See Getting Started for quick setup and Use Cases for detailed scenarios.

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/copilot-mode/index.html b/_site_test/copilot-mode/index.html new file mode 100644 index 0000000..5747f5d --- /dev/null +++ b/_site_test/copilot-mode/index.html @@ -0,0 +1,478 @@ + + + + + + + +Using CoPilot Mode | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Using CoPilot Mode

+ +

Status: ✅ AVAILABLE (v0.4.2+)
+Last Updated: 2025-11-02

+ +
+ +

Overview

+ +

SpecFact CLI supports two operational modes:

+ +
    +
  • CI/CD Mode (Default): Fast, deterministic execution for automation
    • +
  • CoPilot Mode: Interactive assistance with enhanced prompts for IDEs
    • +
+ +

Mode is auto-detected based on environment, or you can explicitly set it with --mode cicd or --mode copilot.

+ +
+ +

Quick Start

+ +

Quick Start Using CoPilot Mode

+ +
# Explicitly enable CoPilot mode
+specfact --mode copilot import from-code --bundle legacy-api --repo . --confidence 0.7
+
+# Mode is auto-detected based on environment (IDE integration, CoPilot API availability)
+specfact import from-code --bundle legacy-api --repo . --confidence 0.7  # Auto-detects CoPilot if available
+
+ +

What You Get with CoPilot Mode

+ +
    +
  • ✅ Enhanced prompts with context injection (current file, selection, workspace)
    • +
  • ✅ Agent routing for better analysis and planning
    • +
  • ✅ Context-aware execution optimized for interactive use
    • +
  • ✅ Better AI steering with detailed instructions
    • +
+ +
+ +

How It Works

+ +

Mode Detection

+ +

SpecFact CLI automatically detects the operational mode:

+ +
    +
  1. Explicit flag - --mode cicd or --mode copilot (highest priority)
    2. +
  2. Environment detection - Checks for CoPilot API availability, IDE integration
    3. +
  3. Default - Falls back to CI/CD mode if no CoPilot environment detected
    4. +
+ +

Agent Routing

+ +

In CoPilot mode, commands are routed through specialized agents:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandAgentPurpose
import from-codeAnalyzeAgentAI-first brownfield analysis with semantic understanding (multi-language support)
plan initPlanAgentPlan management with business logic understanding
plan comparePlanAgentPlan comparison with deviation analysis
sync bridge --adapter speckitSyncAgentBidirectional sync with conflict resolution
+ +

Context Injection

+ +

CoPilot mode automatically injects relevant context:

+ +
    +
  • Current file: Active file in IDE
    • +
  • Selection: Selected text/code
    • +
  • Workspace: Repository root path
    • +
  • Git context: Current branch, recent commits
    • +
  • Codebase context: Directory structure, files, dependencies
    • +
+ +

This context is used to generate enhanced prompts that instruct the AI IDE to:

+ +
    +
  • Understand the codebase semantically
    • +
  • Call the SpecFact CLI with appropriate arguments
    • +
  • Enhance CLI results with semantic understanding
    • +
+ +

Pragmatic Integration Benefits

+ +
    +
  • ✅ No separate LLM setup - Uses AI IDE’s existing LLM (Cursor, CoPilot, etc.)
    • +
  • ✅ No additional API costs - Leverages existing IDE infrastructure
    • +
  • ✅ Simpler architecture - No langchain, API keys, or complex integration
    • +
  • ✅ Better developer experience - Native IDE integration via slash commands
    • +
  • ✅ Streamlined workflow - AI understands codebase, CLI handles structured work
    • +
+ +
+ +

Examples

+ +

Example 1: Brownfield Analysis ⭐ PRIMARY

+ +
# CI/CD mode (fast, deterministic, Python-only)
+specfact --mode cicd import from-code --repo . --confidence 0.7
+
+# CoPilot mode (AI-first, semantic understanding, multi-language)
+specfact --mode copilot import from-code --repo . --confidence 0.7
+
+# Output (CoPilot mode):
+# Mode: CoPilot (AI-first analysis)
+# 🤖 AI-powered analysis (semantic understanding)...
+# ✓ AI analysis complete
+# ✓ Found X features
+# ✓ Detected themes: ...
+
+ +

Key Differences:

+ +
    +
  • CoPilot Mode: Uses LLM for semantic understanding, supports all languages, generates high-quality Spec-Kit artifacts
    • +
  • CI/CD Mode: Uses Python AST for fast analysis, Python-only, generates generic content (hardcoded fallbacks)
    • +
+ +

Example 2: Plan Initialization

+ +
# CI/CD mode (minimal prompts)
+specfact --mode cicd plan init --no-interactive
+
+# CoPilot mode (enhanced interactive prompts)
+specfact --mode copilot plan init --interactive
+
+# Output:
+# Mode: CoPilot (agent routing)
+# Agent prompt generated (XXX chars)
+# [enhanced interactive prompts]
+
+ +

Example 3: Plan Comparison

+ +
# CoPilot mode with enhanced deviation analysis (bundle directory paths)
+specfact --mode copilot plan compare \
+  --manual .specfact/projects/main \
+  --auto .specfact/projects/my-project-auto
+
+# Output:
+# Mode: CoPilot (agent routing)
+# Agent prompt generated (XXX chars)
+# [enhanced deviation analysis with context]
+
+ +
+ +

Mode Differences

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureCI/CD ModeCoPilot Mode
SpeedFast, deterministicSlightly slower, context-aware
OutputStructured, minimalEnhanced, detailed
PromptsStandardEnhanced with context
ContextMinimalFull context injection
Agent RoutingDirect executionAgent-based routing
Use CaseAutomation, CI/CDInteractive development, IDE
+ +
+ +

When to Use Each Mode

+ +

Use CI/CD Mode When

+ +
    +
  • ✅ Running in CI/CD pipelines
    • +
  • ✅ Automating workflows
    • +
  • ✅ Need fast, deterministic execution
    • +
  • ✅ Don’t need enhanced prompts
    • +
+ +

Use CoPilot Mode When

+ +
    +
  • ✅ Working in IDE with AI assistance
    • +
  • ✅ Need enhanced prompts for better AI steering
    • +
  • ✅ Want context-aware execution
    • +
  • ✅ Interactive development workflows
    • +
+ +
+ +

IDE Integration

+ +

For IDE integration with slash commands, see:

+ + + +
+ + + + + +
+ +

Next Steps

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/directory-structure/index.html b/_site_test/directory-structure/index.html new file mode 100644 index 0000000..b7aeafb --- /dev/null +++ b/_site_test/directory-structure/index.html @@ -0,0 +1,1064 @@ + + + + + + + +SpecFact CLI Directory Structure | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

SpecFact CLI Directory Structure

+ +

This document defines the canonical directory structure for SpecFact CLI artifacts.

+ +
+

Primary Use Case: SpecFact CLI is designed for brownfield code modernization - reverse-engineering existing codebases into documented specs with runtime contract enforcement. The directory structure reflects this brownfield-first approach.

+
+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

+ +

Overview

+ +

All SpecFact artifacts are stored under .specfact/ in the repository root. This ensures:

+ +
    +
  • Consistency: All artifacts in one predictable location
    • +
  • Multiple plans: Support for multiple plan bundles in a single repository
    • +
  • Gitignore-friendly: Easy to exclude reports from version control
    • +
  • Clear separation: Plans (versioned) vs reports (ephemeral)
    • +
  • CLI-first: All artifacts are local, no cloud storage required
    • +
+ +

Canonical Structure

+ +
.specfact/
+├── config.yaml              # SpecFact configuration (optional)
+├── config/                  # Global configuration (optional)
+│   ├── bridge.yaml          # Bridge configuration for external tools
+│   └── ...
+├── cache/                   # Shared cache (gitignored, global for performance)
+│   ├── dependency-graph.json
+│   └── commit-history.json
+├── projects/                # Modular project bundles (versioned in git)
+│   ├── <bundle-name>/       # Project bundle directory
+│   │   ├── bundle.manifest.yaml  # Bundle metadata, versioning, and checksums
+│   │   ├── idea.yaml             # Product vision (optional)
+│   │   ├── business.yaml         # Business context (optional)
+│   │   ├── product.yaml          # Releases, themes (required)
+│   │   ├── clarifications.yaml   # Clarification sessions (optional)
+│   │   ├── sdd.yaml              # SDD manifest (bundle-specific, Phase 8.5)
+│   │   ├── tasks.yaml            # Task breakdown (bundle-specific, Phase 8.5)
+│   │   ├── features/             # Individual feature files
+│   │   │   ├── FEATURE-001.yaml
+│   │   │   ├── FEATURE-002.yaml
+│   │   │   └── ...
+│   │   ├── contracts/            # OpenAPI contracts (bundle-specific)
+│   │   │   └── ...
+│   │   ├── protocols/            # FSM protocols (bundle-specific)
+│   │   │   └── ...
+│   │   ├── reports/              # Bundle-specific reports (gitignored, Phase 8.5)
+│   │   │   ├── brownfield/
+│   │   │   │   └── analysis-2025-10-31T14-30-00.md
+│   │   │   ├── comparison/
+│   │   │   │   └── report-2025-10-31T14-30-00.md
+│   │   │   ├── enrichment/
+│   │   │   │   └── <bundle-name>-2025-10-31T14-30-00.enrichment.md
+│   │   │   └── enforcement/
+│   │   │       └── report-2025-10-31T14-30-00.yaml
+│   │   ├── logs/                 # Bundle-specific logs (gitignored, Phase 8.5)
+│   │   │   └── 2025-10-31T14-30-00.log
+│   │   └── prompts/              # AI IDE contract enhancement prompts (optional)
+│   │       └── enhance-<filename>-<contracts>.md
+│   ├── legacy-api/         # Example: Brownfield-derived bundle
+│   │   ├── bundle.manifest.yaml
+│   │   ├── product.yaml
+│   │   ├── sdd.yaml
+│   │   ├── tasks.yaml
+│   │   ├── features/
+│   │   ├── reports/
+│   │   └── logs/
+│   └── my-project/          # Example: Main project bundle
+│       ├── bundle.manifest.yaml
+│       ├── idea.yaml
+│       ├── business.yaml
+│       ├── product.yaml
+│       ├── sdd.yaml
+│       ├── tasks.yaml
+│       ├── features/
+│       ├── reports/
+│       └── logs/
+└── gates/                   # Enforcement configuration (global)
+    └── config.yaml          # Enforcement settings (versioned)
+
+ +

Directory Purposes

+ +

.specfact/projects/ (Versioned)

+ +

Purpose: Store modular project bundles that define the contract for the project.

+ +

Guidelines:

+ +
    +
  • Each project bundle is stored in its own directory: .specfact/projects/<bundle-name>/
    • +
  • Each bundle directory contains multiple aspect files: +
      +
    • bundle.manifest.yaml - Bundle metadata, versioning, checksums, and feature index (required) +
        +
      • Schema Versioning: Set schema_metadata.schema_version to "1.1" to enable change tracking (v0.21.1+)
        • +
      • Change Tracking (v1.1+): Optional change_tracking and change_archive fields are loaded via bridge adapters (not stored in bundle directory) +
          +
        • change_tracking: Active change proposals and feature deltas (loaded from external tools like OpenSpec)
          • +
        • change_archive: Completed changes with audit trail (loaded from external tools)
          • +
        • Both fields are optional and backward compatible - v1.0 bundles work without them
          • +
        +
        • +
      • See Schema Versioning for details
        • +
      +
      • +
    • product.yaml - Product definition with themes and releases (required)
      • +
    • idea.yaml - Product vision and intent (optional)
      • +
    • business.yaml - Business context and market segments (optional)
      • +
    • clarifications.yaml - Clarification sessions and Q&A (optional)
      • +
    • sdd.yaml - SDD manifest (bundle-specific, Phase 8.5, versioned)
      • +
    • tasks.yaml - Task breakdown (bundle-specific, Phase 8.5, versioned)
      • +
    • features/ - Directory containing individual feature files: +
        +
      • FEATURE-001.yaml - Individual feature with stories
        • +
      • FEATURE-002.yaml - Individual feature with stories
        • +
      • Each feature file is self-contained with its stories, acceptance criteria, etc.
        • +
      +
      • +
    • contracts/ - OpenAPI contract files (bundle-specific, versioned)
      • +
    • protocols/ - FSM protocol definitions (bundle-specific, versioned)
      • +
    • reports/ - Bundle-specific analysis reports (gitignored, Phase 8.5)
      • +
    • logs/ - Bundle-specific execution logs (gitignored, Phase 8.5)
      • +
    +
    • +
  • Always committed to git - these are the source of truth (except reports/ and logs/)
    • +
  • Phase 8.5: All bundle-specific artifacts are stored within bundle folders for better isolation
    • +
  • Use descriptive bundle names: legacy-api, my-project, feature-auth
    • +
  • Supports multiple bundles per repository for brownfield modernization, monorepos, or feature branches
    • +
  • Aspect files are YAML format (JSON support may be added in future)
    • +
+ +

Plan Bundle Structure:

+ +

Plan bundles are YAML (or JSON) files with the following structure:

+ +
version: "1.1"  # Schema version (current: 1.1)
+
+metadata:
+  stage: "draft"  # draft, review, approved, released
+  summary:  # Summary metadata for fast access (added in v1.1)
+    features_count: 5
+    stories_count: 12
+    themes_count: 2
+    releases_count: 1
+    content_hash: "abc123def456..."  # SHA256 hash for integrity
+    computed_at: "2025-01-15T10:30:00"
+
+idea:
+  title: "Project Title"
+  narrative: "Project description"
+  # ... other idea fields
+
+product:
+  themes: ["Theme1", "Theme2"]
+  releases: [...]
+
+features:
+  - key: "FEATURE-001"
+    title: "Feature Title"
+    stories: [...]
+    # ... other feature fields
+
+ +

Bundle Manifest Structure (bundle.manifest.yaml):

+ +

The bundle.manifest.yaml file contains bundle metadata and (in v1.1+) optional change tracking fields:

+ +
schema_metadata:
+  schema_version: "1.1"  # Set to "1.1" to enable change tracking (v0.21.1+)
+  project_version: "0.1.0"
+
+# ... other manifest fields (checksums, feature index, etc.)
+
+# Optional change tracking fields (v1.1+, loaded via bridge adapters)
+change_tracking: null  # Optional - loaded via bridge adapters (not stored in bundle directory)
+change_archive: []     # Optional - list of archived changes (not stored in bundle directory)
+
+ +

Note: The change_tracking and change_archive fields are optional and loaded dynamically via bridge adapters (e.g., OpenSpec adapter) rather than being stored directly in the bundle directory. This allows change tracking to be managed by external tools while keeping bundles tool-agnostic. See Schema Versioning for details.

+ +

Summary Metadata (v1.1+):

+ +

Plan bundles version 1.1 and later include summary metadata in the metadata.summary section. This provides:

+ +
    +
  • Fast access: Read plan counts without parsing entire file (44% faster performance)
    • +
  • Integrity verification: Content hash detects plan modifications
    • +
  • Performance optimization: Only reads first 50KB for large files (>10MB)
    • +
+ +

Upgrading Plan Bundles:

+ +

Use specfact plan upgrade to migrate older plan bundles to the latest schema:

+ +
# Upgrade active plan
+specfact plan upgrade
+
+# Upgrade all plans
+specfact plan upgrade --all
+
+# Preview upgrades
+specfact plan upgrade --dry-run
+
+ +

See plan upgrade for details.

+ +

Example:

+ +
.specfact/projects/
+├── my-project/                    # Primary project bundle
+│   ├── bundle.manifest.yaml       # Metadata, checksums, feature index
+│   ├── idea.yaml                  # Product vision
+│   ├── business.yaml              # Business context
+│   ├── product.yaml               # Themes and releases
+│   ├── features/                  # Individual feature files
+│   │   ├── FEATURE-001.yaml
+│   │   ├── FEATURE-002.yaml
+│   │   └── FEATURE-003.yaml
+│   └── prompts/                   # AI IDE contract enhancement prompts (optional)
+│       └── enhance-<filename>-<contracts>.md
+├── legacy-api/                    # ⭐ Reverse-engineered from existing API (brownfield)
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   ├── features/
+│   │   ├── FEATURE-AUTH.yaml
+│   │   └── FEATURE-PAYMENT.yaml
+│   └── prompts/                   # Bundle-specific prompts (avoids conflicts)
+│       └── enhance-<filename>-<contracts>.md
+├── legacy-payment/                 # ⭐ Reverse-engineered from existing payment system (brownfield)
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   └── features/
+│       └── FEATURE-PAYMENT.yaml
+└── feature-auth/                   # Auth feature bundle
+    ├── bundle.manifest.yaml
+    ├── product.yaml
+    └── features/
+        └── FEATURE-AUTH.yaml
+
+ +

.specfact/protocols/ (Versioned)

+ +

Purpose: Store FSM (Finite State Machine) protocol definitions.

+ +

Guidelines:

+ +
    +
  • Define valid states and transitions
    • +
  • Always committed to git
    • +
  • Used for workflow validation
    • +
+ +

Example:

+ +
.specfact/protocols/
+├── development-workflow.protocol.yaml
+└── deployment-pipeline.protocol.yaml
+
+ +

Bundle-Specific Artifacts (Phase 8.5)

+ +

Phase 8.5 Update: All bundle-specific artifacts are now stored within .specfact/projects/<bundle-name>/ folders for better isolation and organization.

+ +

Bundle-Specific Artifacts:

+ +
    +
  • Reports: .specfact/projects/<bundle-name>/reports/ (gitignored) +
      +
    • brownfield/ - Brownfield analysis reports
      • +
    • comparison/ - Plan comparison reports
      • +
    • enrichment/ - LLM enrichment reports
      • +
    • enforcement/ - SDD enforcement validation reports
      • +
    +
    • +
  • SDD Manifests: .specfact/projects/<bundle-name>/sdd.yaml (versioned)
    • +
  • Tasks: .specfact/projects/<bundle-name>/tasks.yaml (versioned)
    • +
  • Logs: .specfact/projects/<bundle-name>/logs/ (gitignored)
    • +
+ +

Migration: Use specfact migrate artifacts to move existing artifacts from global locations to bundle-specific folders.

+ +

Example:

+ +
.specfact/projects/legacy-api/
+├── bundle.manifest.yaml
+├── product.yaml
+├── sdd.yaml                    # Bundle-specific SDD manifest
+├── tasks.yaml                  # Bundle-specific task breakdown
+├── reports/                    # Bundle-specific reports (gitignored)
+│   ├── brownfield/
+│   │   └── analysis-2025-10-31T14-30-00.md
+│   ├── comparison/
+│   │   └── report-2025-10-31T14-30-00.md
+│   ├── enrichment/
+│   │   └── legacy-api-2025-10-31T14-30-00.enrichment.md
+│   └── enforcement/
+│       └── report-2025-10-31T14-30-00.yaml
+└── logs/                       # Bundle-specific logs (gitignored)
+    └── 2025-10-31T14-30-00.log
+
+ +

Legacy Global Locations (Removed)

+ +

Note: The following global locations have been removed (Phase 8.5):

+ +
    +
  • ❌ .specfact/plans/ - Removed (active bundle config migrated to .specfact/config.yaml)
    • +
  • ❌ .specfact/gates/results/ - Removed (enforcement reports are bundle-specific)
    • +
  • ❌ .specfact/reports/ - Removed (reports are bundle-specific)
    • +
  • ❌ .specfact/sdd/ - Removed (SDD manifests are bundle-specific)
    • +
  • ❌ .specfact/tasks/ - Removed (task files are bundle-specific)
    • +
+ +

Migration: Use specfact migrate cleanup-legacy to remove empty legacy directories, and specfact migrate artifacts to migrate existing artifacts to bundle-specific locations.

+ +

.specfact/gates/ (Versioned)

+ +

Purpose: Global enforcement configuration.

+ +

Guidelines:

+ +
    +
  • config.yaml is versioned (defines enforcement policy)
    • +
  • Enforcement reports are bundle-specific (stored in .specfact/projects/<bundle-name>/reports/enforcement/)
    • +
+ +

Example:

+ +
.specfact/gates/
+└── config.yaml              # Versioned: enforcement policy
+
+ +

Note: Enforcement execution reports are stored in bundle-specific locations (Phase 8.5):

+ +
    +
  • .specfact/projects/<bundle-name>/reports/enforcement/report-<timestamp>.yaml
    • +
+ +

.specfact/cache/ (Gitignored)

+ +

Purpose: Tool caches for faster execution.

+ +

Guidelines:

+ +
    +
  • Gitignored - optimization only
    • +
  • Safe to delete anytime
    • +
  • Automatically regenerated
    • +
+ +

Default Command Paths

+ +

specfact import from-code ⭐ PRIMARY

+ +

Primary use case: Reverse-engineer existing codebases into project bundles.

+ +
# Command syntax
+specfact import from-code <bundle-name> --repo . [OPTIONS]
+
+# Creates modular bundle at:
+.specfact/projects/<bundle-name>/
+├── bundle.manifest.yaml  # Bundle metadata, versioning, checksums, feature index
+├── product.yaml          # Product definition (required)
+├── idea.yaml            # Product vision (if provided)
+├── business.yaml        # Business context (if provided)
+└── features/            # Individual feature files
+    ├── FEATURE-001.yaml
+    ├── FEATURE-002.yaml
+    └── ...
+
+# Analysis report (bundle-specific, gitignored, Phase 8.5)
+.specfact/projects/<bundle-name>/reports/brownfield/analysis-<timestamp>.md
+
+ +

Example (brownfield modernization):

+ +
# Analyze legacy codebase
+specfact import from-code legacy-api --repo . --confidence 0.7
+
+# Creates:
+# - .specfact/projects/legacy-api/bundle.manifest.yaml (versioned)
+# - .specfact/projects/legacy-api/product.yaml (versioned)
+# - .specfact/projects/legacy-api/features/FEATURE-*.yaml (versioned, one per feature)
+# - .specfact/reports/brownfield/analysis-2025-10-31T14-30-00.md (gitignored)
+
+ +

specfact plan init (Alternative)

+ +

Alternative use case: Create new project bundles for greenfield projects.

+ +
# Command syntax
+specfact plan init <bundle-name> [OPTIONS]
+
+# Creates modular bundle at:
+.specfact/projects/<bundle-name>/
+├── bundle.manifest.yaml  # Bundle metadata and versioning
+├── product.yaml         # Product definition (required)
+├── idea.yaml           # Product vision (if provided via prompts)
+└── features/           # Empty features directory (created when first feature added)
+
+# Also creates (if --interactive):
+.specfact/config.yaml
+
+ +

specfact plan compare

+ +
# Compare two bundles (explicit paths to bundle directories)
+specfact plan compare \
+  --manual .specfact/projects/manual-plan \
+  --auto .specfact/projects/auto-derived \
+  --out .specfact/reports/comparison/report-*.md
+
+# Note: Commands accept bundle directory paths, not individual files
+
+ +

specfact sync bridge

+ +
# Sync with external tools (Spec-Kit, Linear, Jira, etc.)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Watch mode
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+# Sync files are tracked in .specfact/reports/sync/
+
+ +

specfact sync repository

+ +
# Sync code changes
+specfact sync repository --repo . --target .specfact
+
+# Watch mode
+specfact sync repository --repo . --watch --interval 5
+
+# Sync reports in .specfact/reports/sync/
+
+ +

specfact enforce stage

+ +
# Reads/writes
+.specfact/gates/config.yaml
+
+ +

specfact init

+ +

Initializes IDE integration by copying prompt templates to IDE-specific locations:

+ +
# Auto-detect IDE
+specfact init
+
+# Specify IDE explicitly
+specfact init --ide cursor
+specfact init --ide vscode
+specfact init --ide copilot
+
+ +

Creates IDE-specific directories:

+ +
    +
  • Cursor: .cursor/commands/ (markdown files)
    • +
  • VS Code / Copilot: .github/prompts/ (.prompt.md files) + .vscode/settings.json
    • +
  • Claude Code: .claude/commands/ (markdown files)
    • +
  • Gemini: .gemini/commands/ (TOML files)
    • +
  • Qwen: .qwen/commands/ (TOML files)
    • +
  • Other IDEs: See IDE Integration Guide
    • +
+ +

See IDE Integration Guide for complete setup instructions.

+ +

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via IDE integrations

+ +

Configuration File

+ +

.specfact/config.yaml (optional):

+ +
version: "1.0"
+
+# Default bundle to use (optional)
+default_bundle: my-project
+
+# Analysis settings
+analysis:
+  confidence_threshold: 0.7
+  exclude_patterns:
+    - "**/__pycache__/**"
+    - "**/node_modules/**"
+    - "**/venv/**"
+
+# Enforcement settings
+enforcement:
+  preset: balanced  # strict, balanced, minimal, shadow
+  budget_seconds: 120
+  fail_fast: false
+
+# Repro settings
+repro:
+  parallel: true
+  timeout: 300
+
+ +

IDE Integration Directories

+ +

When you run specfact init, prompt templates are copied to IDE-specific locations for slash command integration.

+ +

IDE-Specific Locations

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDEDirectoryFormatSettings File
Cursor.cursor/commands/MarkdownNone
VS Code / Copilot.github/prompts/.prompt.md.vscode/settings.json
Claude Code.claude/commands/MarkdownNone
Gemini.gemini/commands/TOMLNone
Qwen.qwen/commands/TOMLNone
opencode.opencode/command/MarkdownNone
Windsurf.windsurf/workflows/MarkdownNone
Kilo Code.kilocode/workflows/MarkdownNone
Auggie.augment/commands/MarkdownNone
Roo Code.roo/commands/MarkdownNone
CodeBuddy.codebuddy/commands/MarkdownNone
Amp.agents/commands/MarkdownNone
Amazon Q.amazonq/prompts/MarkdownNone
+ +

Example Structure (Cursor)

+ +
.cursor/
+└── commands/
+    ├── specfact.01-import.md
+    ├── specfact.02-plan.md
+    ├── specfact.03-review.md
+    ├── specfact.04-sdd.md
+    ├── specfact.05-enforce.md
+    ├── specfact.06-sync.md
+    ├── specfact.compare.md
+    └── specfact.validate.md
+
+ +

Example Structure (VS Code / Copilot)

+ +
.github/
+└── prompts/
+    ├── specfact.01-import.prompt.md
+    ├── specfact.02-plan.prompt.md
+    ├── specfact.03-review.prompt.md
+    ├── specfact.04-sdd.prompt.md
+    ├── specfact.05-enforce.prompt.md
+    ├── specfact.06-sync.prompt.md
+    ├── specfact.compare.prompt.md
+    └── specfact.validate.prompt.md
+.vscode/
+└── settings.json  # Updated with promptFilesRecommendations
+
+ +

Guidelines:

+ +
    +
  • Versioned - IDE directories are typically committed to git (team-shared configuration)
    • +
  • Templates - Prompt templates are read-only for the IDE, not modified by users
    • +
  • Settings - VS Code settings.json is merged (not overwritten) to preserve existing settings
    • +
  • Auto-discovery - IDEs automatically discover and register templates as slash commands
    • +
  • CLI-first - Works offline, no account required, no vendor lock-in
    • +
+ +

See IDE Integration Guide for detailed setup and usage.

+ +

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via IDE integrations

+ +
+ +

SpecFact CLI Package Structure

+ +

The SpecFact CLI package includes prompt templates that are copied to IDE locations:

+ +
specfact-cli/
+└── resources/
+    └── prompts/              # Prompt templates (in package)
+        ├── specfact.01-import.md
+        ├── specfact.02-plan.md
+        ├── specfact.03-review.md
+        ├── specfact.04-sdd.md
+        ├── specfact.05-enforce.md
+        ├── specfact.06-sync.md
+        ├── specfact.compare.md
+        ├── specfact.validate.md
+        └── shared/
+            └── cli-enforcement.md
+
+ +

These templates are:

+ +
    +
  • Packaged with SpecFact CLI
    • +
  • Copied to IDE locations by specfact init
    • +
  • Not modified by users (read-only templates)
    • +
+ +
+ +

.gitignore Recommendations

+ +

Add to .gitignore:

+ +
# SpecFact ephemeral artifacts
+.specfact/projects/*/reports/
+.specfact/projects/*/logs/
+.specfact/cache/
+
+# Keep these versioned
+!.specfact/projects/
+!.specfact/config.yaml
+!.specfact/gates/config.yaml
+
+# IDE integration directories (optional - typically versioned)
+# Uncomment if you don't want to commit IDE integration files
+# .cursor/commands/
+# .github/prompts/
+# .vscode/settings.json
+# .claude/commands/
+# .gemini/commands/
+# .qwen/commands/
+
+ +

Note: IDE integration directories are typically versioned (committed to git) so team members share the same slash commands. However, you can gitignore them if preferred.

+ +

Migration from Old Structure

+ +

If you have existing artifacts in other locations:

+ +
# Old structure (monolithic bundles, deprecated)
+.specfact/plans/<name>.bundle.<format>
+.specfact/reports/analysis.md
+
+# New structure (modular bundles)
+.specfact/projects/my-project/
+├── bundle.manifest.yaml
+└── bundle.yaml
+.specfact/reports/brownfield/analysis.md
+
+# Migration
+mkdir -p .specfact/projects/my-project .specfact/reports/brownfield
+# Convert monolithic bundle to modular bundle structure
+# (Use 'specfact plan upgrade' or manual conversion)
+mv reports/analysis.md .specfact/reports/brownfield/
+
+ +

Multiple Plans in One Repository

+ +

SpecFact supports multiple plan bundles for:

+ +
    +
  • Brownfield modernization ⭐ PRIMARY: Separate plans for legacy components vs modernized code
    • +
  • Monorepos: One plan per service
    • +
  • Feature branches: Feature-specific plans
    • +
+ +

Example (Brownfield Modernization):

+ +
.specfact/projects/
+├── my-project/                      # Overall project bundle
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   └── features/
+│       └── ...
+├── legacy-api/                      # ⭐ Reverse-engineered from existing API (brownfield)
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   └── features/
+│       ├── FEATURE-AUTH.yaml
+│       └── FEATURE-API.yaml
+├── legacy-payment/                  # ⭐ Reverse-engineered from existing payment system (brownfield)
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   └── features/
+│       └── FEATURE-PAYMENT.yaml
+├── modernized-api/                  # New API bundle (after modernization)
+│   ├── bundle.manifest.yaml
+│   ├── product.yaml
+│   └── features/
+│       └── ...
+└── feature-new-auth/                # Experimental feature bundle
+    ├── bundle.manifest.yaml
+    ├── product.yaml
+    └── features/
+        └── FEATURE-AUTH.yaml
+
+ +

Usage (Brownfield Workflow):

+ +
# Step 1: Reverse-engineer legacy codebase
+specfact import from-code legacy-api \
+  --repo src/legacy-api \
+  --confidence 0.7
+
+# Step 2: Compare legacy vs modernized (use bundle directories, not files)
+specfact plan compare \
+  --manual .specfact/projects/legacy-api \
+  --auto .specfact/projects/modernized-api
+
+# Step 3: Analyze specific legacy component
+specfact import from-code legacy-payment \
+  --repo src/legacy-payment \
+  --confidence 0.7
+
+ +

Summary

+ +

SpecFact Artifacts

+ +
    +
  • .specfact/ - All SpecFact artifacts live here
    • +
  • projects/ and protocols/ - Versioned (git)
    • +
  • reports/, gates/results/, cache/ - Gitignored (ephemeral)
    • +
  • Modular bundles - Each bundle in its own directory with manifest and content files
    • +
  • Use descriptive bundle names - Supports multiple bundles per repo
    • +
  • Default paths always start with .specfact/ - Consistent and predictable
    • +
  • Timestamped reports - Auto-generated reports include timestamps for tracking
    • +
  • Bridge architecture - Bidirectional sync with external tools (Spec-Kit, Linear, Jira, etc.) via bridge adapters
    • +
+ +

IDE Integration

+ +
    +
  • IDE directories - Created by specfact init (e.g., .cursor/commands/, .github/prompts/)
    • +
  • Prompt templates - Copied from resources/prompts/ in SpecFact CLI package
    • +
  • Typically versioned - IDE directories are usually committed to git for team sharing
    • +
  • Auto-discovery - IDEs automatically discover and register templates as slash commands
    • +
  • Settings files - VS Code settings.json is merged (not overwritten)
    • +
+ +

Quick Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeLocationGit StatusPurpose
Project Bundles.specfact/projects/<bundle-name>/VersionedModular contract definitions
Bundle Prompts.specfact/projects/<bundle-name>/prompts/Versioned (optional)AI IDE contract enhancement prompts
Protocols.specfact/protocols/VersionedFSM definitions
Reports.specfact/reports/GitignoredAnalysis reports
Cache.specfact/cache/GitignoredTool caches
IDE Templates.cursor/commands/, .github/prompts/, etc.Versioned (recommended)Slash command templates
+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/examples/brownfield-data-pipeline.md b/_site_test/examples/brownfield-data-pipeline.md new file mode 100644 index 0000000..e3b1888 --- /dev/null +++ b/_site_test/examples/brownfield-data-pipeline.md @@ -0,0 +1,400 @@ +# Brownfield Example: Modernizing Legacy Data Pipeline + +> **Complete walkthrough: From undocumented ETL pipeline to contract-enforced data processing** + +--- + +## The Problem + +You inherited a 5-year-old Python data pipeline with: + +- ❌ No documentation +- ❌ No type hints +- ❌ No data validation +- ❌ Critical ETL jobs (can't risk breaking) +- ❌ Business logic embedded in transformations +- ❌ Original developers have left + +**Challenge:** Modernize from Python 2.7 → 3.12 without breaking production ETL jobs. + +--- + +## Step 1: Reverse Engineer Data Pipeline + +> **Note**: This example demonstrates the complete hard-SDD workflow, including SDD manifest creation, validation, and plan promotion gates. The SDD manifest serves as your "hard spec" - a canonical reference that prevents drift during modernization. + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. + +### Extract Specs from Legacy Pipeline + +```bash +# Analyze the legacy data pipeline +specfact import from-code customer-etl \ + --repo ./legacy-etl-pipeline \ + --language python + +``` + +### Output + +```text +✅ Analyzed 34 Python files +✅ Extracted 18 ETL jobs: + + - JOB-001: Customer Data Import (95% confidence) + - JOB-002: Order Data Transformation (92% confidence) + - JOB-003: Payment Data Aggregation (88% confidence) + ... +✅ Generated 67 user stories from pipeline code +✅ Detected 6 edge cases with CrossHair symbolic execution +⏱️ Completed in 7.5 seconds +``` + +### What You Get + +**Auto-generated pipeline documentation:** + +```yaml +features: + + - key: JOB-002 + name: Order Data Transformation + description: Transform raw order data into normalized format + stories: + + - key: STORY-002-001 + title: Transform order records + description: Transform order data with validation + acceptance_criteria: + + - Input: Raw order records (CSV/JSON) + - Validation: Order ID must be positive integer + - Validation: Amount must be positive decimal + - Output: Normalized order records +``` + +--- + +## Step 2: Create Hard SDD Manifest + +After extracting the plan, create a hard SDD manifest: + +```bash +# Create SDD manifest from the extracted plan +specfact plan harden customer-etl +``` + +### Output + +```text +✅ SDD manifest created: .specfact/projects//sdd.yaml + +📋 SDD Summary: + WHY: Modernize legacy ETL pipeline with zero data corruption + WHAT: 18 ETL jobs, 67 stories extracted from legacy code + HOW: Runtime contracts, data validation, incremental enforcement + +🔗 Linked to plan: customer-etl (hash: ghi789jkl012...) +📊 Coverage thresholds: + - Contracts per story: 1.0 (minimum) + - Invariants per feature: 2.0 (minimum) + - Architecture facets: 3 (minimum) +``` + +--- + +## Step 3: Validate SDD Before Modernization + +Validate that your SDD manifest matches your plan: + +```bash +# Validate SDD manifest against plan +specfact enforce sdd customer-etl +``` + +### Output + +```text +✅ Hash match verified +✅ Contracts/story: 1.1 (threshold: 1.0) ✓ +✅ Invariants/feature: 2.3 (threshold: 2.0) ✓ +✅ Architecture facets: 4 (threshold: 3) ✓ + +✅ SDD validation passed +``` + +--- + +## Step 4: Promote Plan with SDD Validation + +Promote your plan to "review" stage (requires valid SDD): + +```bash +# Promote plan to review stage +specfact plan promote customer-etl --stage review +``` + +**Why this matters**: Plan promotion enforces SDD presence, ensuring you have a hard spec before starting modernization work. + +--- + +## Step 5: Add Contracts to Data Transformations + +### Before: Undocumented Legacy Transformation + +```python +# transformations/orders.py (legacy code) +def transform_order(raw_order): + """Transform raw order data""" + order_id = raw_order.get('id') + amount = float(raw_order.get('amount', 0)) + customer_id = raw_order.get('customer_id') + + # 50 lines of legacy transformation logic + # Hidden business rules: + # - Order ID must be positive integer + # - Amount must be positive decimal + # - Customer ID must be valid + ... + + return { + 'order_id': order_id, + 'amount': amount, + 'customer_id': customer_id, + 'status': 'processed' + } + +``` + +### After: Contract-Enforced Transformation + +```python +# transformations/orders.py (modernized with contracts) +import icontract +from typing import Dict, Any + +@icontract.require( + lambda raw_order: isinstance(raw_order.get('id'), int) and raw_order['id'] > 0, + "Order ID must be positive integer" +) +@icontract.require( + lambda raw_order: float(raw_order.get('amount', 0)) > 0, + "Order amount must be positive decimal" +) +@icontract.require( + lambda raw_order: raw_order.get('customer_id') is not None, + "Customer ID must be present" +) +@icontract.ensure( + lambda result: 'order_id' in result and 'amount' in result, + "Result must contain order_id and amount" +) +def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]: + """Transform raw order data with runtime contract enforcement""" + order_id = raw_order['id'] + amount = float(raw_order['amount']) + customer_id = raw_order['customer_id'] + + # Same 50 lines of legacy transformation logic + # Now with runtime enforcement + + return { + 'order_id': order_id, + 'amount': amount, + 'customer_id': customer_id, + 'status': 'processed' + } +``` + +### Re-validate SDD After Adding Contracts + +After adding contracts, re-validate your SDD: + +```bash +specfact enforce sdd customer-etl +``` + +--- + +## Step 6: Discover Data Edge Cases + +### Run CrossHair on Data Transformations + +```bash +# Discover edge cases in order transformation +hatch run contract-explore transformations/orders.py + +``` + +### CrossHair Output + +```text +🔍 Exploring contracts in transformations/orders.py... + +❌ Precondition violation found: + Function: transform_order + Input: raw_order={'id': 0, 'amount': '100.50', 'customer_id': 123} + Issue: Order ID must be positive integer (got 0) + +❌ Precondition violation found: + Function: transform_order + Input: raw_order={'id': 456, 'amount': '-50.00', 'customer_id': 123} + Issue: Order amount must be positive decimal (got -50.0) + +✅ Contract exploration complete + - 2 violations found + - 0 false positives + - Time: 10.2 seconds + +``` + +### Add Data Validation + +```python +# Add data validation based on CrossHair findings +@icontract.require( + lambda raw_order: isinstance(raw_order.get('id'), int) and raw_order['id'] > 0, + "Order ID must be positive integer" +) +@icontract.require( + lambda raw_order: isinstance(raw_order.get('amount'), (int, float, str)) and + float(raw_order.get('amount', 0)) > 0, + "Order amount must be positive decimal" +) +def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]: + """Transform with enhanced validation""" + # Handle string amounts (common in CSV imports) + amount = float(raw_order['amount']) if isinstance(raw_order['amount'], str) else raw_order['amount'] + ... +``` + +--- + +## Step 7: Modernize Pipeline Safely + +### Refactor with Contract Safety Net + +```python +# Modernized version (same contracts) +@icontract.require(...) # Same contracts as before +def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]: + """Modernized order transformation with contract safety net""" + + # Modernized implementation (Python 3.12) + order_id: int = raw_order['id'] + amount: float = float(raw_order['amount']) if isinstance(raw_order['amount'], str) else raw_order['amount'] + customer_id: int = raw_order['customer_id'] + + # Modernized transformation logic + transformed = OrderTransformer().transform( + order_id=order_id, + amount=amount, + customer_id=customer_id + ) + + return { + 'order_id': transformed.order_id, + 'amount': transformed.amount, + 'customer_id': transformed.customer_id, + 'status': 'processed' + } + +``` + +### Catch Data Pipeline Regressions + +```python +# During modernization, accidentally break contract: +# Missing amount validation in refactored code + +# Runtime enforcement catches it: +# ❌ ContractViolation: Order amount must be positive decimal (got -50.0) +# at transform_order() call from etl_job.py:142 +# → Prevented data corruption in production ETL! +``` + +--- + +## Results + +### Quantified Outcomes + +| Metric | Before SpecFact | After SpecFact | Improvement | +|--------|----------------|----------------|-------------| +| **Pipeline documentation** | 0% (none) | 100% (auto-generated) | **∞ improvement** | +| **Data validation** | Manual (error-prone) | Automated (contracts) | **100% coverage** | +| **Edge cases discovered** | 0-2 (manual) | 6 (CrossHair) | **3x more** | +| **Data corruption prevented** | 0 (no safety net) | 11 incidents | **∞ improvement** | +| **Migration time** | 8 weeks (cautious) | 3 weeks (confident) | **62% faster** | + +### Case Study: Customer ETL Pipeline + +**Challenge:** + +- 5-year-old Python data pipeline (12K LOC) +- No documentation, original developers left +- Needed modernization from Python 2.7 → 3.12 +- Fear of breaking critical ETL jobs + +**Solution:** + +1. Ran `specfact import from-code` → 47 features extracted in 12 seconds +2. Added contracts to 23 critical data transformation functions +3. CrossHair discovered 6 edge cases in legacy validation logic +4. Enforced contracts during migration, blocked 11 regressions + +**Results:** + +- ✅ 87% faster documentation (8 hours vs. 60 hours manual) +- ✅ 11 production bugs prevented during migration +- ✅ Zero downtime migration completed in 3 weeks vs. estimated 8 weeks +- ✅ New team members productive in days vs. weeks + +**ROI:** $42,000 saved, 5-week acceleration + +--- + +## Integration with Your Workflow + +SpecFact CLI integrates seamlessly with your existing tools: + +- **VS Code**: Use pre-commit hooks to catch breaking changes before commit +- **Cursor**: AI assistant workflows catch regressions during refactoring +- **GitHub Actions**: CI/CD integration blocks bad code from merging +- **Pre-commit hooks**: Local validation prevents breaking changes +- **Any IDE**: Pure CLI-first approach—works with any editor + +**See real examples**: [Integration Showcases](integration-showcases/) - 5 complete examples showing bugs fixed via integrations + +## Key Takeaways + +### What Worked Well + +1. ✅ **code2spec** extracted pipeline structure automatically +2. ✅ **SDD manifest** created hard spec reference, preventing drift +3. ✅ **SDD validation** ensured coverage thresholds before modernization +4. ✅ **Plan promotion gates** required SDD presence, enforcing discipline +5. ✅ **Contracts** enforced data validation at runtime +6. ✅ **CrossHair** discovered edge cases in data transformations +7. ✅ **Incremental modernization** reduced risk +8. ✅ **CLI-first integration** - Works offline, no account required, no vendor lock-in + +### Lessons Learned + +1. **Start with critical jobs** - Maximum impact, minimum risk +2. **Validate data early** - Contracts catch bad data before processing +3. **Test edge cases** - Run CrossHair on data transformations +4. **Monitor in production** - Keep contracts enabled to catch regressions + +--- + +## Next Steps + +1. **[Integration Showcases](integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations +2. **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** - Complete modernization workflow +3. **[Django Example](brownfield-django-modernization.md)** - Web app modernization +4. **[Flask API Example](brownfield-flask-api.md)** - API modernization + +--- + +**Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) | [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_test/examples/brownfield-django-modernization.md b/_site_test/examples/brownfield-django-modernization.md new file mode 100644 index 0000000..d204565 --- /dev/null +++ b/_site_test/examples/brownfield-django-modernization.md @@ -0,0 +1,496 @@ +# Brownfield Example: Modernizing Legacy Django Code + +> **Complete walkthrough: From undocumented legacy Django app to contract-enforced modern codebase** + +--- + +## The Problem + +You inherited a 3-year-old Django app with: + +- ❌ No documentation +- ❌ No type hints +- ❌ No tests +- ❌ 15 undocumented API endpoints +- ❌ Business logic buried in views +- ❌ Original developers have left + +**Sound familiar?** This is a common brownfield scenario. + +--- + +## Step 1: Reverse Engineer with SpecFact + +> **Note**: This example demonstrates the complete hard-SDD workflow, including SDD manifest creation, validation, and plan promotion gates. The SDD manifest serves as your "hard spec" - a canonical reference that prevents drift during modernization. + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. + +### Extract Specs from Legacy Code + +```bash +# Analyze the legacy Django app +specfact import from-code customer-portal \ + --repo ./legacy-django-app \ + --language python + +``` + +### Output + +```text +✅ Analyzed 47 Python files +✅ Extracted 23 features: + + - FEATURE-001: User Authentication (95% confidence) + - Stories: Login, Logout, Password Reset, Session Management + - FEATURE-002: Payment Processing (92% confidence) + - Stories: Process Payment, Refund, Payment History + - FEATURE-003: Order Management (88% confidence) + - Stories: Create Order, Update Order, Cancel Order + ... +✅ Generated 112 user stories from existing code patterns +✅ Dependency graph: 8 modules, 23 dependencies +⏱️ Completed in 8.2 seconds +``` + +### What You Get + +**Auto-generated project bundle** (`.specfact/projects/customer-portal/` - modular structure): + +```yaml +features: + + - key: FEATURE-002 + name: Payment Processing + description: Process payments for customer orders + stories: + + - key: STORY-002-001 + title: Process payment for order + description: Process payment with amount and currency + acceptance_criteria: + + - Amount must be positive decimal + - Supported currencies: USD, EUR, GBP + - Returns SUCCESS or FAILED status +``` + +**Time saved:** 60-120 hours of manual documentation → **8 seconds** + +--- + +## Step 2: Create Hard SDD Manifest + +After extracting the plan, create a hard SDD (Spec-Driven Development) manifest that captures WHY, WHAT, and HOW: + +```bash +# Create SDD manifest from the extracted plan +specfact plan harden customer-portal +``` + +### Output + +```text +✅ SDD manifest created: .specfact/projects//sdd.yaml + +📋 SDD Summary: + WHY: Modernize legacy Django customer portal with zero downtime + WHAT: 23 features, 112 stories extracted from legacy code + HOW: Runtime contracts, symbolic execution, incremental enforcement + +🔗 Linked to plan: customer-portal (hash: abc123def456...) +📊 Coverage thresholds: + - Contracts per story: 1.0 (minimum) + - Invariants per feature: 2.0 (minimum) + - Architecture facets: 3 (minimum) + +✅ SDD manifest saved to .specfact/projects//sdd.yaml +``` + +### What You Get + +**SDD manifest** (`.specfact/projects//sdd.yaml`, Phase 8.5) captures: + +- **WHY**: Intent, constraints, target users, value hypothesis +- **WHAT**: Capabilities, acceptance criteria, out-of-scope items +- **HOW**: Architecture, invariants, contracts, module boundaries +- **Coverage thresholds**: Minimum contracts/story, invariants/feature, architecture facets +- **Plan linkage**: Hash-linked to plan bundle for drift detection + +**Why this matters**: The SDD manifest serves as your "hard spec" - a canonical reference that prevents drift between your plan and implementation during modernization. + +--- + +## Step 3: Validate SDD Before Modernization + +Before starting modernization, validate that your SDD manifest matches your plan: + +```bash +# Validate SDD manifest against plan +specfact enforce sdd customer-portal +``` + +### Output + +```text +✅ Loading SDD manifest: .specfact/projects/customer-portal/sdd.yaml +✅ Loading project bundle: .specfact/projects/customer-portal/ + +🔍 Validating hash match... +✅ Hash match verified + +🔍 Validating coverage thresholds... +✅ Contracts/story: 1.2 (threshold: 1.0) ✓ +✅ Invariants/feature: 2.5 (threshold: 2.0) ✓ +✅ Architecture facets: 4 (threshold: 3) ✓ + +✅ SDD validation passed +📄 Report saved to: .specfact/projects//reports/enforcement/report-2025-01-23T10-30-45.yaml +``` + +**If validation fails**, you'll see specific deviations: + +```text +❌ SDD validation failed + +🔍 Validating coverage thresholds... +⚠️ Contracts/story: 0.8 (threshold: 1.0) - Below threshold +⚠️ Invariants/feature: 1.5 (threshold: 2.0) - Below threshold + +📊 Validation report: + - 2 medium severity deviations + - Fix: Add contracts to stories or adjust thresholds + +💡 Run 'specfact plan harden' to update SDD manifest +``` + +--- + +## Step 4: Review Plan with SDD Validation + +Review your plan to identify ambiguities and ensure SDD compliance: + +```bash +# Review plan (automatically checks SDD, bundle name as positional argument) +specfact plan review customer-portal --max-questions 5 +``` + +### Output + +```text +📋 SpecFact CLI - Plan Review + +✅ Loading project bundle: .specfact/projects/customer-portal/ +✅ Current stage: draft + +🔍 Checking SDD manifest... +✅ SDD manifest validated successfully +ℹ️ Found 2 coverage threshold warning(s) + +❓ Questions to resolve ambiguities: + 1. Q001: What is the expected response time for payment processing? + 2. Q002: Should password reset emails expire after 24 or 48 hours? + ... + +✅ Review complete: 5 questions identified +💡 Run 'specfact plan review --answers answers.json' to resolve in bulk +``` + +**SDD integration**: The review command automatically checks for SDD presence and validates coverage thresholds, warning you if thresholds aren't met. + +--- + +## Step 5: Promote Plan with SDD Validation + +Before starting modernization, promote your plan to "review" stage. This requires a valid SDD manifest: + +```bash +# Promote plan to review stage (requires SDD, bundle name as positional argument) +specfact plan promote customer-portal --stage review +``` + +### Output (Success) + +```text +📋 SpecFact CLI - Plan Promotion + +✅ Loading project bundle: .specfact/projects/customer-portal/ +✅ Current stage: draft +✅ Target stage: review + +🔍 Checking promotion rules... +🔍 Checking SDD manifest... +✅ SDD manifest validated successfully +ℹ️ Found 2 coverage threshold warning(s) + +✅ Promoted plan to stage: review +💡 Plan is now ready for modernization work +``` + +### Output (SDD Missing) + +```text +❌ SDD manifest is required for promotion to 'review' or higher stages +💡 Run 'specfact plan harden' to create SDD manifest +``` + +**Why this matters**: Plan promotion now enforces SDD presence, ensuring you have a hard spec before starting modernization work. This prevents drift and ensures coverage thresholds are met. + +--- + +## Step 6: Add Contracts to Critical Paths + +### Identify Critical Functions + +Review the extracted plan to identify high-risk functions: + +```bash +# Review extracted plan using CLI commands +specfact plan review customer-portal + +``` + +### Before: Undocumented Legacy Function + +```python +# views/payment.py (legacy code) +def process_payment(request, order_id): + """Process payment for order""" + order = Order.objects.get(id=order_id) + amount = float(request.POST.get('amount')) + currency = request.POST.get('currency') + + # 80 lines of legacy payment logic + # Hidden business rules: + # - Amount must be positive + # - Currency must be USD, EUR, or GBP + # - Returns PaymentResult with status + ... + + return PaymentResult(status='SUCCESS') + +``` + +### After: Contract-Enforced Function + +```python +# views/payment.py (modernized with contracts) +import icontract +from typing import Literal + +@icontract.require( + lambda amount: amount > 0, + "Payment amount must be positive" +) +@icontract.require( + lambda currency: currency in ['USD', 'EUR', 'GBP'], + "Currency must be USD, EUR, or GBP" +) +@icontract.ensure( + lambda result: result.status in ['SUCCESS', 'FAILED'], + "Payment result must have valid status" +) +def process_payment( + request, + order_id: int, + amount: float, + currency: Literal['USD', 'EUR', 'GBP'] +) -> PaymentResult: + """Process payment for order with runtime contract enforcement""" + order = Order.objects.get(id=order_id) + + # Same 80 lines of legacy payment logic + # Now with runtime enforcement + + return PaymentResult(status='SUCCESS') +``` + +**What this gives you:** + +- ✅ Runtime validation catches invalid inputs immediately +- ✅ Prevents regressions during refactoring +- ✅ Documents expected behavior (executable documentation) +- ✅ CrossHair discovers edge cases automatically + +### Re-validate SDD After Adding Contracts + +After adding contracts, re-validate your SDD to ensure coverage thresholds are met: + +```bash +# Re-validate SDD after adding contracts +specfact enforce sdd customer-portal +``` + +This ensures your SDD manifest reflects the current state of your codebase and that coverage thresholds are maintained. + +--- + +## Step 7: Discover Hidden Edge Cases + +### Run CrossHair Symbolic Execution + +```bash +# Discover edge cases in payment processing +hatch run contract-explore views/payment.py + +``` + +### CrossHair Output + +```text +🔍 Exploring contracts in views/payment.py... + +❌ Postcondition violation found: + Function: process_payment + Input: amount=0.0, currency='USD' + Issue: Amount must be positive (got 0.0) + +❌ Postcondition violation found: + Function: process_payment + Input: amount=-50.0, currency='USD' + Issue: Amount must be positive (got -50.0) + +✅ Contract exploration complete + - 2 violations found + - 0 false positives + - Time: 12.3 seconds + +``` + +### Fix Edge Cases + +```python +# Add validation for edge cases discovered by CrossHair +@icontract.require( + lambda amount: amount > 0 and amount <= 1000000, + "Payment amount must be between 0 and 1,000,000" +) +def process_payment(...): + # Now handles edge cases discovered by CrossHair + ... +``` + +--- + +## Step 8: Prevent Regressions During Modernization + +### Refactor Safely + +With contracts in place, refactor knowing violations will be caught: + +```python +# Refactored version (same contracts) +@icontract.require(lambda amount: amount > 0, "Payment amount must be positive") +@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP']) +@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED']) +def process_payment(request, order_id: int, amount: float, currency: str) -> PaymentResult: + """Modernized payment processing with contract safety net""" + + # Modernized implementation + order = get_order_or_404(order_id) + payment_service = PaymentService() + + try: + result = payment_service.process( + order=order, + amount=amount, + currency=currency + ) + return PaymentResult(status='SUCCESS', transaction_id=result.id) + except PaymentError as e: + return PaymentResult(status='FAILED', error=str(e)) + +``` + +### Catch Regressions Automatically + +```python +# During modernization, accidentally break contract: +process_payment(request, order_id=-1, amount=-50, currency="XYZ") + +# Runtime enforcement catches it: +# ❌ ContractViolation: Payment amount must be positive (got -50) +# at process_payment() call from refactored checkout.py:142 +# → Prevented production bug during modernization! +``` + +--- + +## Results + +### Quantified Outcomes + +| Metric | Before SpecFact | After SpecFact | Improvement | +|--------|----------------|----------------|-------------| +| **Documentation time** | 60-120 hours | 8 seconds | **99.9% faster** | +| **Production bugs prevented** | 0 (no safety net) | 4 bugs | **∞ improvement** | +| **Developer onboarding** | 2-3 weeks | 3-5 days | **60% faster** | +| **Edge cases discovered** | 0-2 (manual) | 6 (CrossHair) | **3x more** | +| **Refactoring confidence** | Low (fear of breaking) | High (contracts catch violations) | **Qualitative improvement** | + +### Time and Cost Savings + +**Manual approach:** + +- Documentation: 80-120 hours ($12,000-$18,000) +- Testing: 100-150 hours ($15,000-$22,500) +- Debugging regressions: 40-80 hours ($6,000-$12,000) +- **Total: 220-350 hours ($33,000-$52,500)** + +**SpecFact approach:** + +- code2spec extraction: 10 minutes ($25) +- Review and refine specs: 8-16 hours ($1,200-$2,400) +- Add contracts: 16-24 hours ($2,400-$3,600) +- CrossHair edge case discovery: 2-4 hours ($300-$600) +- **Total: 26-44 hours ($3,925-$6,625)** + +**ROI: 87% time saved, $26,000-$45,000 cost avoided** + +--- + +## Integration with Your Workflow + +SpecFact CLI integrates seamlessly with your existing tools: + +- **VS Code**: Use pre-commit hooks to catch breaking changes before commit +- **Cursor**: AI assistant workflows catch regressions during refactoring +- **GitHub Actions**: CI/CD integration blocks bad code from merging +- **Pre-commit hooks**: Local validation prevents breaking changes +- **Any IDE**: Pure CLI-first approach—works with any editor + +**See real examples**: [Integration Showcases](integration-showcases/) - 5 complete examples showing bugs fixed via integrations + +## Key Takeaways + +### What Worked Well + +1. ✅ **code2spec extraction** provided immediate value (< 10 seconds) +2. ✅ **SDD manifest** created hard spec reference, preventing drift during modernization +3. ✅ **SDD validation** ensured coverage thresholds before starting work +4. ✅ **Plan promotion gates** required SDD presence, enforcing discipline +5. ✅ **Runtime contracts** prevented 4 production bugs during refactoring +6. ✅ **CrossHair** discovered 6 edge cases manual testing missed +7. ✅ **Incremental approach** (shadow → warn → block) reduced risk +8. ✅ **CLI-first integration** - Works offline, no account required, no vendor lock-in + +### Lessons Learned + +1. **Start with critical paths** - Don't try to contract everything at once +2. **Use shadow mode first** - Observe violations before enforcing +3. **Run CrossHair early** - Discover edge cases before refactoring +4. **Document findings** - Keep notes on violations and edge cases + +--- + +## Next Steps + +1. **[Integration Showcases](integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations +2. **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** - Complete modernization workflow +3. **[ROI Calculator](../guides/brownfield-roi.md)** - Calculate your savings +4. **[Flask API Example](brownfield-flask-api.md)** - Another brownfield scenario +5. **[Data Pipeline Example](brownfield-data-pipeline.md)** - ETL modernization + +--- + +**Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) | [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_test/examples/brownfield-flask-api.md b/_site_test/examples/brownfield-flask-api.md new file mode 100644 index 0000000..30797c0 --- /dev/null +++ b/_site_test/examples/brownfield-flask-api.md @@ -0,0 +1,381 @@ +# Brownfield Example: Modernizing Legacy Flask API + +> **Complete walkthrough: From undocumented Flask API to contract-enforced modern service** + +--- + +## The Problem + +You inherited a 2-year-old Flask REST API with: + +- ❌ No OpenAPI/Swagger documentation +- ❌ No type hints +- ❌ No request validation +- ❌ 12 undocumented API endpoints +- ❌ Business logic mixed with route handlers +- ❌ No error handling standards + +--- + +## Step 1: Reverse Engineer API Endpoints + +> **Note**: This example demonstrates the complete hard-SDD workflow, including SDD manifest creation, validation, and plan promotion gates. The SDD manifest serves as your "hard spec" - a canonical reference that prevents drift during modernization. + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. + +### Extract Specs from Legacy Flask Code + +```bash +# Analyze the legacy Flask API +specfact import from-code customer-api \ + --repo ./legacy-flask-api \ + --language python + +``` + +### Output + +```text +✅ Analyzed 28 Python files +✅ Extracted 12 API endpoints: + + - POST /api/v1/users (User Registration) + - GET /api/v1/users/{id} (Get User) + - POST /api/v1/orders (Create Order) + - PUT /api/v1/orders/{id} (Update Order) + ... +✅ Generated 45 user stories from route handlers +✅ Detected 4 edge cases with CrossHair symbolic execution +⏱️ Completed in 6.8 seconds +``` + +### What You Get + +**Auto-generated API documentation** from route handlers: + +```yaml +features: + + - key: FEATURE-003 + name: Order Management API + description: REST API for order management + stories: + + - key: STORY-003-001 + title: Create order via POST /api/v1/orders + description: Create new order with items and customer ID + acceptance_criteria: + + - Request body must contain items array + - Each item must have product_id and quantity + - Customer ID must be valid integer + - Returns order object with status +``` + +--- + +## Step 2: Create Hard SDD Manifest + +After extracting the plan, create a hard SDD manifest: + +```bash +# Create SDD manifest from the extracted plan +specfact plan harden customer-api +``` + +### Output + +```text +✅ SDD manifest created: .specfact/projects//sdd.yaml + +📋 SDD Summary: + WHY: Modernize legacy Flask API with zero downtime + WHAT: 12 API endpoints, 45 stories extracted from legacy code + HOW: Runtime contracts, request validation, incremental enforcement + +🔗 Linked to plan: customer-api (hash: def456ghi789...) +📊 Coverage thresholds: + - Contracts per story: 1.0 (minimum) + - Invariants per feature: 2.0 (minimum) + - Architecture facets: 3 (minimum) +``` + +--- + +## Step 3: Validate SDD Before Modernization + +Validate that your SDD manifest matches your plan: + +```bash +# Validate SDD manifest against plan +specfact enforce sdd customer-api +``` + +### Output + +```text +✅ Hash match verified +✅ Contracts/story: 1.3 (threshold: 1.0) ✓ +✅ Invariants/feature: 2.8 (threshold: 2.0) ✓ +✅ Architecture facets: 4 (threshold: 3) ✓ + +✅ SDD validation passed +``` + +--- + +## Step 4: Promote Plan with SDD Validation + +Promote your plan to "review" stage (requires valid SDD): + +```bash +# Promote plan to review stage +specfact plan promote customer-api --stage review +``` + +**Why this matters**: Plan promotion enforces SDD presence, ensuring you have a hard spec before starting modernization work. + +--- + +## Step 5: Add Contracts to API Endpoints + +### Before: Undocumented Legacy Route + +```python +# routes/orders.py (legacy code) +@app.route('/api/v1/orders', methods=['POST']) +def create_order(): + """Create new order""" + data = request.get_json() + customer_id = data.get('customer_id') + items = data.get('items', []) + + # 60 lines of legacy order creation logic + # Hidden business rules: + # - Customer ID must be positive integer + # - Items must be non-empty array + # - Each item must have product_id and quantity > 0 + ... + + return jsonify({'order_id': order.id, 'status': 'created'}), 201 + +``` + +### After: Contract-Enforced Route + +```python +# routes/orders.py (modernized with contracts) +import icontract +from typing import List, Dict +from flask import request, jsonify + +@icontract.require( + lambda data: isinstance(data.get('customer_id'), int) and data['customer_id'] > 0, + "Customer ID must be positive integer" +) +@icontract.require( + lambda data: isinstance(data.get('items'), list) and len(data['items']) > 0, + "Items must be non-empty array" +) +@icontract.require( + lambda data: all( + isinstance(item, dict) and + 'product_id' in item and + 'quantity' in item and + item['quantity'] > 0 + for item in data.get('items', []) + ), + "Each item must have product_id and quantity > 0" +) +@icontract.ensure( + lambda result: result[1] == 201, + "Must return 201 status code" +) +@icontract.ensure( + lambda result: 'order_id' in result[0].json, + "Response must contain order_id" +) +def create_order(): + """Create new order with runtime contract enforcement""" + data = request.get_json() + customer_id = data['customer_id'] + items = data['items'] + + # Same 60 lines of legacy order creation logic + # Now with runtime enforcement + + return jsonify({'order_id': order.id, 'status': 'created'}), 201 +``` + +### Re-validate SDD After Adding Contracts + +After adding contracts, re-validate your SDD: + +```bash +specfact enforce sdd customer-api +``` + +--- + +## Step 6: Discover API Edge Cases + +### Run CrossHair on API Endpoints + +```bash +# Discover edge cases in order creation +hatch run contract-explore routes/orders.py + +``` + +### CrossHair Output + +```text +🔍 Exploring contracts in routes/orders.py... + +❌ Precondition violation found: + Function: create_order + Input: data={'customer_id': 0, 'items': [...]} + Issue: Customer ID must be positive integer (got 0) + +❌ Precondition violation found: + Function: create_order + Input: data={'customer_id': 123, 'items': []} + Issue: Items must be non-empty array (got []) + +✅ Contract exploration complete + - 2 violations found + - 0 false positives + - Time: 8.5 seconds + +``` + +### Add Request Validation + +```python +# Add Flask request validation based on CrossHair findings +from flask import request +from marshmallow import Schema, fields, ValidationError + +class CreateOrderSchema(Schema): + customer_id = fields.Int(required=True, validate=lambda x: x > 0) + items = fields.List( + fields.Dict(keys=fields.Str(), values=fields.Raw()), + required=True, + validate=lambda x: len(x) > 0 + ) + +@app.route('/api/v1/orders', methods=['POST']) +@icontract.require(...) # Keep contracts for runtime enforcement +def create_order(): + """Create new order with request validation + contract enforcement""" + try: + data = CreateOrderSchema().load(request.get_json()) + except ValidationError as e: + return jsonify({'error': e.messages}), 400 + + # Process order with validated data + ... +``` + +--- + +## Step 7: Modernize API Safely + +### Refactor with Contract Safety Net + +```python +# Modernized version (same contracts) +@icontract.require(...) # Same contracts as before +def create_order(): + """Modernized order creation with contract safety net""" + + # Modernized implementation + data = CreateOrderSchema().load(request.get_json()) + order_service = OrderService() + + try: + order = order_service.create_order( + customer_id=data['customer_id'], + items=data['items'] + ) + return jsonify({ + 'order_id': order.id, + 'status': order.status + }), 201 + except OrderCreationError as e: + return jsonify({'error': str(e)}), 400 + +``` + +### Catch API Regressions + +```python +# During modernization, accidentally break contract: +# Missing customer_id validation in refactored code + +# Runtime enforcement catches it: +# ❌ ContractViolation: Customer ID must be positive integer (got 0) +# at create_order() call from test_api.py:42 +# → Prevented API bug from reaching production! +``` + +--- + +## Results + +### Quantified Outcomes + +| Metric | Before SpecFact | After SpecFact | Improvement | +|--------|----------------|----------------|-------------| +| **API documentation** | 0% (none) | 100% (auto-generated) | **∞ improvement** | +| **Request validation** | Manual (error-prone) | Automated (contracts) | **100% coverage** | +| **Edge cases discovered** | 0-1 (manual) | 4 (CrossHair) | **4x more** | +| **API bugs prevented** | 0 (no safety net) | 3 bugs | **∞ improvement** | +| **Refactoring time** | 4-6 weeks (cautious) | 2-3 weeks (confident) | **50% faster** | + +--- + +## Integration with Your Workflow + +SpecFact CLI integrates seamlessly with your existing tools: + +- **VS Code**: Use pre-commit hooks to catch breaking changes before commit +- **Cursor**: AI assistant workflows catch regressions during refactoring +- **GitHub Actions**: CI/CD integration blocks bad code from merging +- **Pre-commit hooks**: Local validation prevents breaking changes +- **Any IDE**: Pure CLI-first approach—works with any editor + +**See real examples**: [Integration Showcases](integration-showcases/) - 5 complete examples showing bugs fixed via integrations + +## Key Takeaways + +### What Worked Well + +1. ✅ **code2spec** extracted API endpoints automatically +2. ✅ **SDD manifest** created hard spec reference, preventing drift +3. ✅ **SDD validation** ensured coverage thresholds before modernization +4. ✅ **Plan promotion gates** required SDD presence, enforcing discipline +5. ✅ **Contracts** enforced request validation at runtime +6. ✅ **CrossHair** discovered edge cases in API inputs +7. ✅ **Incremental modernization** reduced risk +8. ✅ **CLI-first integration** - Works offline, no account required, no vendor lock-in + +### Lessons Learned + +1. **Start with high-traffic endpoints** - Maximum impact +2. **Combine validation + contracts** - Request validation + runtime enforcement +3. **Test edge cases early** - Run CrossHair before refactoring +4. **Document API changes** - Keep changelog of modernized endpoints + +--- + +## Next Steps + +1. **[Integration Showcases](integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations +2. **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** - Complete modernization workflow +3. **[Django Example](brownfield-django-modernization.md)** - Web app modernization +4. **[Data Pipeline Example](brownfield-data-pipeline.md)** - ETL modernization + +--- + +**Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) | [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_test/examples/dogfooding-specfact-cli.md b/_site_test/examples/dogfooding-specfact-cli.md new file mode 100644 index 0000000..83d638d --- /dev/null +++ b/_site_test/examples/dogfooding-specfact-cli.md @@ -0,0 +1,683 @@ +# Real-World Example: SpecFact CLI Analyzing Itself + +> **TL;DR**: We ran SpecFact CLI on its own codebase in two ways: (1) **Brownfield analysis** discovered **19 features** and **49 stories** in **under 3 seconds**, found **24 deviations**, and blocked the merge (as configured). (2) **Contract enhancement** added beartype, icontract, and CrossHair contracts to our core telemetry module with **7-step validation** (all tests passed, code quality maintained). Total time: **< 10 seconds** for analysis, **~3 minutes** for contract enhancement. 🚀 +> **Note**: "Dogfooding" is a well-known tech term meaning "eating your own dog food" - using your own product. It's a common practice in software development to validate that tools work in real-world scenarios. + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in. + +--- + +## The Challenge + +We built SpecFact CLI and wanted to validate that it actually works in the real world. So we did what every good developer does: **we dogfooded it**. + +**Goal**: Analyze the SpecFact CLI codebase itself and demonstrate: + +1. How fast brownfield analysis is +2. How enforcement actually blocks bad code +3. How the complete workflow works end-to-end +4. How contract enhancement works on real production code + +--- + +## Step 1: Brownfield Analysis (3 seconds ⚡) + +First, we analyzed the existing codebase to see what features it discovered: + +```bash +specfact import from-code specfact-cli --repo . --confidence 0.5 +``` + +**Output**: + +```bash +🔍 Analyzing Python files... +✓ Found 19 features +✓ Detected themes: CLI, Validation +✓ Total stories: 49 + +✓ Analysis complete! +Project bundle written to: .specfact/projects/specfact-cli/ +``` + +### What It Discovered + +The brownfield analysis extracted **19 features** from our codebase: + +| Feature | Stories | Confidence | What It Does | +|---------|---------|------------|--------------| +| Enforcement Config | 3 | 0.9 | Configuration for contract enforcement and quality gates | +| Code Analyzer | 2 | 0.7 | Analyzes Python code to auto-derive plan bundles | +| Plan Comparator | 1 | 0.7 | Compares two plan bundles to detect deviations | +| Report Generator | 3 | 0.9 | Generator for validation and deviation reports | +| Protocol Generator | 3 | 0.9 | Generator for protocol YAML files | +| Plan Generator | 3 | 0.9 | Generator for plan bundle YAML files | +| FSM Validator | 3 | 1.0 | FSM validator for protocol validation | +| Schema Validator | 2 | 0.7 | Schema validator for plan bundles and protocols | +| Git Operations | 5 | 1.0 | Helper class for Git operations | +| Logger Setup | 3 | 1.0 | Utility class for standardized logging setup | +| ... and 9 more | 21 | - | Supporting utilities and infrastructure | + +**Total**: **49 user stories** auto-generated with Fibonacci story points (1, 2, 3, 5, 8, 13...) + +### Sample Auto-Generated Story + +Here's what the analyzer extracted from our `EnforcementConfig` class: + +```yaml +- key: STORY-ENFORCEMENTCONFIG-001 + title: As a developer, I can configure Enforcement Config + acceptance: + - Configuration functionality works as expected + tags: [] + story_points: 2 + value_points: 3 + tasks: + - __init__() + confidence: 0.6 + draft: false +``` + +**Time taken**: ~3 seconds for 19 Python files + +> **💡 How does it work?** SpecFact CLI uses **AI-first approach** (LLM) in CoPilot mode for semantic understanding and multi-language support, with **AST-based fallback** in CI/CD mode for fast, deterministic Python-only analysis. [Read the technical deep dive →](../technical/code2spec-analysis-logic.md) + +--- + +## Step 2: Set Enforcement Rules (1 second 🎯) + +Next, we configured quality gates to block HIGH severity violations: + +```bash +specfact enforce stage --preset balanced +``` + +**Output**: + +```bash +Setting enforcement mode: balanced + Enforcement Mode: + BALANCED +┏━━━━━━━━━━┳━━━━━━━━┓ +┃ Severity ┃ Action ┃ +┡━━━━━━━━━━╇━━━━━━━━┩ +│ HIGH │ BLOCK │ +│ MEDIUM │ WARN │ +│ LOW │ LOG │ +└──────────┴────────┘ + +✓ Enforcement mode set to balanced +Configuration saved to: .specfact/gates/config/enforcement.yaml +``` + +**What this means**: + +- 🚫 **HIGH** severity deviations → **BLOCK** the merge (exit code 1) +- ⚠️ **MEDIUM** severity deviations → **WARN** but allow (exit code 0) +- 📝 **LOW** severity deviations → **LOG** silently (exit code 0) + +--- + +## Step 3: Create Manual Plan (30 seconds ✍️) + +We created a minimal manual plan with just 2 features we care about: + +```yaml +features: + - key: FEATURE-ENFORCEMENT + title: Contract Enforcement System + outcomes: + - Developers can set and enforce quality gates + - Automated blocking of contract violations + stories: + - key: STORY-ENFORCEMENT-001 + title: As a developer, I want to set enforcement presets + story_points: 5 + value_points: 13 + + - key: FEATURE-BROWNFIELD + title: Brownfield Code Analysis + outcomes: + - Automatically derive plans from existing codebases + - Identify features and stories from Python code + stories: + - key: STORY-BROWNFIELD-001 + title: As a developer, I want to analyze existing code + story_points: 8 + value_points: 21 +``` + +**Saved to**: `.specfact/projects/main/` (modular project bundle structure) + +--- + +## Step 4: Compare Plans with Enforcement (5 seconds 🔍) + +Now comes the magic - compare the manual plan against what's actually implemented: + +```bash +specfact plan compare +``` + +### Results + +**Deviations Found**: 24 total + +- 🔴 **HIGH**: 2 (Missing features from manual plan) +- 🟡 **MEDIUM**: 19 (Extra implementations found in code) +- 🔵 **LOW**: 3 (Metadata mismatches) + +### Detailed Breakdown + +#### 🔴 HIGH Severity (BLOCKED) + +```table +┃ 🔴 HIGH │ Missing Feature │ Feature 'FEATURE-ENFORCEMENT' │ features[FEATURE-E… │ +┃ │ │ (Contract Enforcement System) │ │ +┃ │ │ in manual plan but not implemented │ │ +``` + +**Wait, what?** We literally just built the enforcement feature! 🤔 + +**Explanation**: The brownfield analyzer found `FEATURE-ENFORCEMENTCONFIG` (the model class), but our manual plan calls it `FEATURE-ENFORCEMENT` (the complete system). This is a **real deviation** - our naming doesn't match! + +#### ⚠️ MEDIUM Severity (WARNED) + +```table +┃ 🟡 MEDIUM │ Extra Implementation │ Feature 'FEATURE-YAMLUTILS' │ features[FEATURE-Y… │ +┃ │ │ (Y A M L Utils) found in code │ │ +┃ │ │ but not in manual plan │ │ +``` + +**Explanation**: We have 19 utility features (YAML utils, Git operations, validators, etc.) that exist in code but aren't documented in our minimal manual plan. + +**Value**: This is exactly what we want! It shows us **undocumented features** that should either be: + +1. Added to the manual plan, or +2. Removed if they're not needed + +#### 📝 LOW Severity (LOGGED) + +```table +┃ 🔵 LOW │ Mismatch │ Idea title differs: │ idea.title │ +┃ │ │ manual='SpecFact CLI', │ │ +┃ │ │ auto='Unknown Project' │ │ +``` + +**Explanation**: Brownfield analysis couldn't detect our project name, so it used "Unknown Project". Minor metadata issue. + +--- + +## Step 5: Enforcement In Action 🚫 + +Here's where it gets interesting. With **balanced enforcement** enabled: + +### Enforcement Report + +```bash +============================================================ +Enforcement Rules +============================================================ + +Using enforcement config: .specfact/gates/config/enforcement.yaml + +📝 [LOW] mismatch: LOG +📝 [LOW] mismatch: LOG +📝 [LOW] mismatch: LOG +🚫 [HIGH] missing_feature: BLOCK +🚫 [HIGH] missing_feature: BLOCK +⚠️ [MEDIUM] extra_implementation: WARN +⚠️ [MEDIUM] extra_implementation: WARN +⚠️ [MEDIUM] extra_implementation: WARN +... (16 more MEDIUM warnings) + +❌ Enforcement BLOCKED: 2 deviation(s) violate quality gates +Fix the blocking deviations or adjust enforcement config +``` + +**Exit Code**: 1 (BLOCKED) ❌ + +**What happened**: The 2 HIGH severity deviations violated our quality gate, so the command **blocked** execution. + +**In CI/CD**: This would **fail the PR** and prevent the merge until we fix the deviations or update the enforcement config. + +--- + +## Step 6: Switch to Minimal Enforcement (1 second 🔄) + +Let's try again with **minimal enforcement** (never blocks): + +```bash +specfact enforce stage --preset minimal +specfact plan compare +``` + +### New Enforcement Report + +```bash +============================================================ +Enforcement Rules +============================================================ + +Using enforcement config: .specfact/gates/config/enforcement.yaml + +📝 [LOW] mismatch: LOG +📝 [LOW] mismatch: LOG +📝 [LOW] mismatch: LOG +⚠️ [HIGH] missing_feature: WARN ← Changed from BLOCK +⚠️ [HIGH] missing_feature: WARN ← Changed from BLOCK +⚠️ [MEDIUM] extra_implementation: WARN +... (all 24 deviations) + +✅ Enforcement PASSED: No blocking deviations +``` + +**Exit Code**: 0 (PASSED) ✅ + +**Same deviations, different outcome**: With minimal enforcement, even HIGH severity issues are downgraded to warnings. Perfect for exploration phase! + +--- + +## Part 2: Contract Enhancement Workflow (Production Use Case) 🎯 + +After validating the brownfield analysis workflow, we took it a step further: **we used SpecFact CLI to enhance one of our own core modules with contracts**. This demonstrates the complete contract enhancement workflow in a real production scenario. + +**Goal**: Add beartype, icontract, and CrossHair contracts to `src/specfact_cli/telemetry.py` - a core module that handles privacy-first telemetry. + +--- + +## Step 7: Generate Contract Enhancement Prompt (1 second 📝) + +First, we generated a structured prompt for our AI IDE (Cursor) to enhance the telemetry module: + +```bash +specfact generate contracts-prompt src/specfact_cli/telemetry.py --bundle specfact-cli-test --apply all-contracts --no-interactive +``` + +**Output**: + +```bash +✓ Analyzing file: src/specfact_cli/telemetry.py +✓ Generating prompt for: beartype, icontract, crosshair +✓ Prompt saved to: .specfact/projects/specfact-cli-test/prompts/enhance-telemetry-beartype-icontract-crosshair.md +``` + +**What happened**: + +- CLI analyzed the telemetry module (543 lines) +- Generated a structured prompt with: + - **CRITICAL REQUIREMENT**: Add contracts to ALL eligible functions (no asking the user) + - Detailed instructions for each contract type (beartype, icontract, crosshair) + - Code quality guidance (follow project formatting rules) + - Step-by-step validation workflow +- Saved prompt to bundle-specific directory (prevents conflicts with multiple bundles) + +--- + +## Step 8: AI IDE Enhancement (2-3 minutes 🤖) + +We copied the prompt to Cursor (our AI IDE), which: + +1. **Read the file** from the provided path +2. **Added contracts to ALL eligible functions**: + - `@beartype` decorators on all functions/methods + - `@require` and `@ensure` decorators where appropriate + - CrossHair property-based test functions +3. **Wrote enhanced code** to `enhanced_telemetry.py` (temporary file) +4. **Ran validation** using SpecFact CLI (see Step 9) + +**Key Point**: The AI IDE followed the prompt's **CRITICAL REQUIREMENT** and added contracts to all eligible functions automatically, without asking for confirmation. + +--- + +## Step 9: Comprehensive Validation (7-step process ✅) + +The AI IDE ran SpecFact CLI validation on the enhanced code: + +```bash +specfact generate contracts-apply enhanced_telemetry.py --original src/specfact_cli/telemetry.py +``` + +### Validation Results + +**Step 1/7: File Size Check** ✅ + +- Enhanced file: 678 lines (was 543 lines) +- Validation: Passed (enhanced file is larger, indicating contracts were added) + +**Step 2/7: Syntax Validation** ✅ + +- Python syntax check: Passed +- File compiles successfully + +**Step 3/7: AST Structure Comparison** ✅ + +- Original: 23 definitions (functions, classes, methods) +- Enhanced: 23 definitions preserved +- Validation: All definitions maintained (no functions removed) + +**Step 4/7: Contract Imports Verification** ✅ + +- Required imports present: + - `from beartype import beartype` + - `from icontract import require, ensure` +- Validation: All imports verified + +**Step 5/7: Code Quality Checks** ✅ + +- **Ruff linting**: Passed (1 tool checked, 1 passed) +- **Pylint**: Not available (skipped) +- **BasedPyright**: Not available (skipped) +- **MyPy**: Not available (skipped) +- Note: Tools run automatically if installed (non-blocking) + +**Step 6/7: Test Execution** ✅ + +- **Scoped test run**: `pytest tests/unit/specfact_cli/test_telemetry.py` +- **Results**: 10/10 tests passed +- **Time**: Seconds (optimized scoped run, not full repository validation) +- Note: Tests always run for validation, even in `--dry-run` mode + +**Step 7/7: Diff Preview** ✅ + +- Previewed changes before applying +- All validations passed + +### Final Result + +```bash +✓ All validations passed! +✓ Enhanced code applied to: src/specfact_cli/telemetry.py +✓ Temporary file cleaned up: enhanced_telemetry.py +``` + +**Total validation time**: < 10 seconds (7-step comprehensive validation) + +--- + +## What We Achieved + +### Contracts Applied + +1. **beartype decorators**: Added `@beartype` to all eligible functions and methods + - Regular functions, class methods, static methods, async functions + - Runtime type checking for all public APIs + +2. **icontract decorators**: Added `@require` and `@ensure` where appropriate + - Preconditions for parameter validation and state checks + - Postconditions for return value validation and guarantees + +3. **CrossHair tests**: Added property-based test functions + - `test_coerce_bool_property()` - Validates boolean coercion + - `test_parse_headers_property()` - Validates header parsing + - `test_telemetry_settings_from_env_property()` - Validates settings creation + - `test_telemetry_manager_sanitize_property()` - Validates data sanitization + - `test_telemetry_manager_normalize_value_property()` - Validates value normalization + +### Validation Quality + +- ✅ **File size check**: Ensured no code was removed +- ✅ **Syntax validation**: Python compilation successful +- ✅ **AST structure**: All 23 definitions preserved +- ✅ **Contract imports**: All required imports verified +- ✅ **Code quality**: Ruff linting passed +- ✅ **Tests**: 10/10 tests passed +- ✅ **Diff preview**: Changes reviewed before applying + +### Production Value + +This demonstrates **real production use**: + +- Enhanced a **core module** (telemetry) used throughout the CLI +- Applied **all three contract types** (beartype, icontract, crosshair) +- **All tests passed** (10/10) - no regressions introduced +- **Code quality maintained** (ruff linting passed) +- **Fast validation** (< 10 seconds for comprehensive 7-step process) + +--- + +## Complete Contract Enhancement Workflow + +```bash +# 1. Generate prompt (1 second) +specfact generate contracts-prompt src/specfact_cli/telemetry.py \ + --bundle specfact-cli-test \ + --apply all-contracts \ + --no-interactive +# ✅ Prompt saved to: .specfact/projects/specfact-cli-test/prompts/ + +# 2. AI IDE enhancement (2-3 minutes) +# - Copy prompt to Cursor/CoPilot/etc. +# - AI IDE reads file and adds contracts +# - AI IDE writes to enhanced_telemetry.py + +# 3. Validate and apply (10 seconds) +specfact generate contracts-apply enhanced_telemetry.py \ + --original src/specfact_cli/telemetry.py +# ✅ 7-step validation passed +# ✅ All tests passed (10/10) +# ✅ Code quality checks passed +# ✅ Changes applied to original file + +# Total time: ~3 minutes (mostly AI IDE processing) +# Total value: Production-ready contract-enhanced code +``` + +--- + +## What We Learned (Part 2) + +### 1. **Comprehensive Validation** 🛡️ + +The 7-step validation process caught potential issues: + +- File size check prevents accidental code removal +- AST structure comparison ensures no functions are deleted +- Contract imports verification prevents missing dependencies +- Code quality checks (if tools available) catch linting issues +- Test execution validates functionality (10/10 passed) + +### 2. **Production-Ready Workflow** 🚀 + +- **Fast**: Validation completes in < 10 seconds +- **Thorough**: 7-step comprehensive validation +- **Safe**: Only applies changes if all validations pass +- **Flexible**: Works with any AI IDE (Cursor, CoPilot, etc.) +- **Non-blocking**: Code quality tools optional (run if available) + +### 3. **Real-World Validation** 💎 + +We enhanced a **real production module**: + +- Core telemetry module (used throughout CLI) +- 543 lines → 678 lines (contracts added) +- All tests passing (10/10) +- Code quality maintained (ruff passed) +- No regressions introduced + +### 4. **Self-Improvement** 🔄 + +This demonstrates **true dogfooding**: + +- We used SpecFact CLI to enhance SpecFact CLI +- Validated the workflow on real production code +- Proved the tool works for its intended purpose +- Enhanced our own codebase with contracts + +--- + +## What We Learned + +### 1. **Speed** ⚡ + +| Task | Time | +|------|------| +| Analyze 19 Python files | 3 seconds | +| Set enforcement | 1 second | +| Compare plans | 5 seconds | +| **Total** | **< 10 seconds** | + +### 2. **Accuracy** 🎯 + +- Discovered **19 features** we actually built +- Generated **49 user stories** with meaningful titles +- Calculated story points using Fibonacci (1, 2, 3, 5, 8...) +- Detected real naming inconsistencies (e.g., `FEATURE-ENFORCEMENT` vs `FEATURE-ENFORCEMENTCONFIG`) + +### 3. **Enforcement Works** 🚫 + +- **Balanced mode**: Blocked execution due to 2 HIGH deviations (exit 1) +- **Minimal mode**: Passed with warnings (exit 0) +- **CI/CD ready**: Exit codes work perfectly with GitHub Actions, GitLab CI, etc. + +### 4. **Real Value** 💎 + +The tool found **real issues**: + +1. **Naming inconsistency**: Manual plan uses `FEATURE-ENFORCEMENT`, but code has `FEATURE-ENFORCEMENTCONFIG` +2. **Undocumented features**: 19 utility features exist in code but aren't in the manual plan +3. **Documentation gap**: Should we document all utilities, or are they internal implementation details? + +These are **actual questions** that need answers, not false positives! + +--- + +## Complete Workflow (< 10 seconds) + +```bash +# 1. Analyze existing codebase (3 seconds) +specfact import from-code specfact-cli --repo . --confidence 0.5 +# ✅ Discovers 19 features, 49 stories + +# 2. Set quality gates (1 second) +specfact enforce stage --preset balanced +# ✅ BLOCK HIGH, WARN MEDIUM, LOG LOW + +# 3. Compare plans (5 seconds) - uses active plan or default bundle +specfact plan compare +# ✅ Finds 24 deviations +# ❌ BLOCKS execution (2 HIGH violations) + +# Total time: < 10 seconds +# Total value: Priceless 💎 +``` + +--- + +## Use Cases Demonstrated + +### ✅ Brownfield Analysis + +**Problem**: "We have 10,000 lines of code and no documentation" + +**Solution**: Run `import from-code` → get instant plan bundle with features and stories + +**Time**: Seconds, not days + +### ✅ Quality Gates + +**Problem**: "How do I prevent bad code from merging?" + +**Solution**: Set enforcement preset → configure CI to run `plan compare` + +**Result**: PRs blocked automatically if they violate contracts + +### ✅ CI/CD Integration + +**Problem**: "I need consistent exit codes for automation" + +**Solution**: SpecFact CLI uses standard exit codes: + +- 0 = success (no blocking deviations) +- 1 = failure (enforcement blocked) + +**Integration**: Works with any CI system (GitHub Actions, GitLab, Jenkins, etc.) + +--- + +## Next Steps + +### Try It Yourself + +```bash +# Clone SpecFact CLI +git clone https://github.com/nold-ai/specfact-cli.git +cd specfact-cli + +# Run the same analysis +hatch run python -c "import sys; sys.path.insert(0, 'src'); from specfact_cli.cli import app; app()" import from-code specfact-cli --repo . --confidence 0.5 + +# Set enforcement +hatch run python -c "import sys; sys.path.insert(0, 'src'); from specfact_cli.cli import app; app()" enforce stage --preset balanced + +# Compare plans +hatch run python -c "import sys; sys.path.insert(0, 'src'); from specfact_cli.cli import app; app()" plan compare +``` + +### Learn More + +- ⭐ **[Integration Showcases](integration-showcases/)** - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations +- 🔧 [How Code2Spec Works](../technical/code2spec-analysis-logic.md) - Deep dive into AST-based analysis +- 📖 [Getting Started Guide](../getting-started/README.md) +- 📋 [Command Reference](../reference/commands.md) +- 💡 [More Use Cases](../guides/use-cases.md) + +--- + +## Files Generated + +All artifacts are stored in `.specfact/`: + +```shell +.specfact/ +├── plans/ +│ └── main.bundle.yaml # Manual plan (versioned) +├── reports/ +│ ├── brownfield/ +│ │ ├── auto-derived.2025-10-30T16-57-51.bundle.yaml # Auto-derived plan +│ │ └── report-2025-10-30-16-57.md # Analysis report +│ └── comparison/ +│ └── report-2025-10-30-16-58.md # Deviation report +└── gates/ + └── config/ + └── enforcement.yaml # Enforcement config (versioned) +``` + +**Versioned** (commit to git): `plans/`, `gates/config/` + +**Gitignored** (ephemeral): `reports/` + +--- + +## Conclusion + +SpecFact CLI **works**. We proved it by running it on itself in two real-world scenarios: + +### Part 1: Brownfield Analysis + +- ⚡ **Fast**: Analyzed 19 files → 19 features, 49 stories in **3 seconds** +- 🎯 **Accurate**: Found **24 real deviations** (naming inconsistencies, undocumented features) +- 🚫 **Blocks bad code**: Enforcement prevented merge with 2 HIGH violations +- 🔄 **CI/CD ready**: Standard exit codes, works everywhere + +### Part 2: Contract Enhancement + +- 🛡️ **Comprehensive**: 7-step validation process (file size, syntax, AST, imports, quality, tests, diff) +- ✅ **Production-ready**: Enhanced core telemetry module (543 → 678 lines) +- 🧪 **All tests passed**: 10/10 tests passed, no regressions +- 🚀 **Fast validation**: < 10 seconds for complete validation workflow + +**Key Takeaways**: + +1. ⚡ **Fast**: Analyze thousands of lines in seconds, validate contracts in < 10 seconds +2. 🎯 **Accurate**: Finds real deviations, not false positives +3. 🚫 **Blocks bad code**: Enforcement actually prevents merges +4. 🛡️ **Comprehensive validation**: 7-step process ensures code quality +5. 🔄 **CI/CD ready**: Standard exit codes, works everywhere +6. 🐕 **True dogfooding**: We use it on our own production code + +**Try it yourself** and see how much time you save! + +--- + +> **Built by dogfooding** - This example is real, not fabricated. We ran SpecFact CLI on itself in two ways: (1) brownfield analysis workflow, and (2) contract enhancement workflow on our core telemetry module. All results are actual, documented outcomes from production use. diff --git a/_site_test/examples/index.html b/_site_test/examples/index.html new file mode 100644 index 0000000..ff1b5fd --- /dev/null +++ b/_site_test/examples/index.html @@ -0,0 +1,283 @@ + + + + + + + +Examples | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Examples

+ +

Real-world examples of using SpecFact CLI.

+ +

Available Examples

+ +
    +
  • Integration Showcases ⭐ START HERE - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations + +
    • +
  • Brownfield Examples ⭐ NEW - Complete hard-SDD workflow demonstrations +
      +
    • Django Modernization - Legacy Django app → contract-enforced modern codebase
      • +
    • Flask API - Legacy Flask API → contract-enforced modern service
      • +
    • Data Pipeline - Legacy ETL pipeline → contract-enforced data processing
      • +
    • All examples now include: plan harden, enforce sdd, plan review, and plan promote with SDD validation
      • +
    +
    • +
  • Quick Examples - Quick code snippets for common tasks, including SDD workflow
    • +
  • Dogfooding SpecFact CLI - We ran SpecFact CLI on itself (< 10 seconds!)
    • +
+ +

Quick Start

+ +

See It In Action

+ +

For Brownfield Modernization (Recommended):

+ +

Read the complete brownfield examples to see the hard-SDD workflow:

+ +

Django Modernization Example

+ +

This example shows the complete workflow:

+ +
    +
  1. ⚡ Extract specs from legacy code → 23 features, 112 stories in 8 seconds
    2. +
  2. 📋 Create SDD manifest → Hard spec with WHY/WHAT/HOW, coverage thresholds
    3. +
  3. ✅ Validate SDD → Hash match, coverage threshold validation
    4. +
  4. 📊 Review plan → SDD validation integrated, ambiguity resolution
    5. +
  5. 🚀 Promote plan → SDD required for “review” or higher stages
    6. +
  6. 🔒 Add contracts → Runtime enforcement prevents regressions
    7. +
  7. 🔍 Re-validate SDD → Ensure coverage thresholds maintained
    8. +
+ +

For Quick Testing:

+ +

Dogfooding SpecFact CLI

+ +

This example shows:

+ +
    +
  • ⚡ Analyzed 19 Python files → Discovered 19 features and 49 stories in 3 seconds
    • +
  • 🚫 Set enforcement to “balanced” → Blocked 2 HIGH violations (as configured)
    • +
  • 📊 Compared manual vs auto-derived plans → Found 24 deviations in 5 seconds
    • +
+ + + + + + + + +
Total time: < 10 secondsTotal value: Found real naming inconsistencies and undocumented features
+ + + + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/examples/integration-showcases/README.md b/_site_test/examples/integration-showcases/README.md new file mode 100644 index 0000000..80b035b --- /dev/null +++ b/_site_test/examples/integration-showcases/README.md @@ -0,0 +1,164 @@ +# Integration Showcases + +> **Core USP**: SpecFact CLI works seamlessly with VS Code, Cursor, GitHub Actions, and any agentic workflow. This folder contains real examples of bugs that were caught and fixed through different integration points. + +--- + +## 📚 What's in This Folder + +This folder contains everything you need to understand and test SpecFact CLI integrations: + +### Main Documents + +1. **[`integration-showcases.md`](integration-showcases.md)** ⭐ **START HERE** + + - **Purpose**: Real-world examples of bugs fixed via CLI integrations + - **Content**: 5 complete examples showing how SpecFact catches bugs in different workflows + - **Best for**: Understanding what SpecFact can do and seeing real bug fixes + - **Time**: 15-20 minutes to read + +2. **[`integration-showcases-testing-guide.md`](integration-showcases-testing-guide.md)** 🔧 **TESTING GUIDE** + + - **Purpose**: Step-by-step guide to test and validate all 5 examples + - **Content**: Detailed instructions, expected outputs, validation status + - **Best for**: Developers who want to verify the examples work as documented + - **Time**: 2-4 hours to complete all tests + +3. **[`integration-showcases-quick-reference.md`](integration-showcases-quick-reference.md)** ⚡ **QUICK REFERENCE** + + - **Purpose**: Quick command reference for all 5 examples + - **Content**: Essential commands, setup steps, common workflows + - **Best for**: Quick lookups when you know what you need + - **Time**: 5 minutes to scan + +### Setup Script + +1. **[`setup-integration-tests.sh`](setup-integration-tests.sh)** 🚀 **AUTOMATED SETUP** + + - **Purpose**: Automated script to create test cases for all examples + - **Content**: Creates test directories, sample code, and configuration files + - **Best for**: Setting up test environment quickly + - **Time**: < 1 minute to run + +--- + +## 🎯 Quick Start Guide + +### For First-Time Users + +**Step 1**: Read the main showcase document +→ **[`integration-showcases.md`](integration-showcases.md)** + +This gives you a complete overview of what SpecFact can do with real examples. + +**Step 2**: Choose your path: + +- **Want to test the examples?** → Use [`setup-integration-tests.sh`](setup-integration-tests.sh) then follow [`integration-showcases-testing-guide.md`](integration-showcases-testing-guide.md) + +- **Just need quick commands?** → Check [`integration-showcases-quick-reference.md`](integration-showcases-quick-reference.md) + +- **Ready to integrate?** → Pick an example from [`integration-showcases.md`](integration-showcases.md) and adapt it to your workflow + +### For Developers Testing Examples + +**Step 1**: Run the setup script + +```bash +./docs/examples/integration-showcases/setup-integration-tests.sh +``` + +**Step 2**: Follow the testing guide + +→ **[`integration-showcases-testing-guide.md`](integration-showcases-testing-guide.md)** + +**Step 3**: Verify validation status + +- Example 1: ✅ **FULLY VALIDATED** +- Example 2: ✅ **FULLY VALIDATED** +- Example 3: ⚠️ **COMMANDS VERIFIED** (end-to-end testing deferred) +- Example 4: ✅ **FULLY VALIDATED** +- Example 5: ⏳ **PENDING VALIDATION** + +--- + +## 📋 Examples Overview + +### Example 1: VS Code Integration - Async Bug Detection + +- **Integration**: VS Code + Pre-commit Hook +- **Bug**: Blocking I/O call in async context +- **Result**: Caught before commit, prevented production race condition +- **Status**: ✅ **FULLY VALIDATED** + +### Example 2: Cursor Integration - Regression Prevention + +- **Integration**: Cursor AI Assistant +- **Bug**: Missing None check in data processing +- **Result**: Prevented regression during refactoring +- **Status**: ✅ **FULLY VALIDATED** + +### Example 3: GitHub Actions - CI/CD Integration + +- **Integration**: GitHub Actions workflow +- **Bug**: Type mismatch in API endpoint +- **Result**: Blocked bad code from merging +- **Status**: ✅ **FULLY VALIDATED** (CI/CD workflow validated in production) + +### Example 4: Pre-commit Hook - Breaking Change Detection + +- **Integration**: Git pre-commit hook +- **Bug**: Function signature change (breaking change) +- **Result**: Blocked commit locally before pushing +- **Status**: ✅ **FULLY VALIDATED** + +### Example 5: Agentic Workflows - Edge Case Discovery + +- **Integration**: AI assistant workflows +- **Bug**: Edge cases in data validation +- **Result**: Discovered hidden bugs with symbolic execution +- **Status**: ⏳ **PENDING VALIDATION** + +--- + +## 🔗 Related Documentation + +- **[Examples README](../README.md)** - Overview of all SpecFact examples +- **[Brownfield FAQ](../../guides/brownfield-faq.md)** - Common questions about brownfield modernization +- **[Getting Started](../../getting-started/README.md)** - Installation and setup +- **[Command Reference](../../reference/commands.md)** - All available commands + +--- + +## ✅ Validation Status + +**Overall Progress**: 80% complete (4/5 fully validated, 1/5 pending) + +**Key Achievements**: + +- ✅ CLI-first approach validated (works offline, no account required) +- ✅ 3+ integration case studies showing bugs fixed +- ✅ Enforcement blocking validated across all tested examples +- ✅ Documentation updated with actual command outputs and test results + +**Remaining Work**: + +- ⏳ Example 5 validation (2-3 hours estimated) +- ✅ Example 3 validated in production CI/CD (GitHub Actions workflow verified) + +--- + +## 💡 Tips + +1. **Start with Example 1** - It's the simplest and fully validated + +2. **Use the setup script** - Saves time creating test cases + +3. **Check validation status** - Examples 1, 2, and 4 are fully tested and working + +4. **Read the testing guide** - It has actual command outputs and expected results + +5. **Adapt to your workflow** - These examples are templates you can customize + +--- + +**Questions?** Check the [Brownfield FAQ](../../guides/brownfield-faq.md) or open an issue on GitHub. diff --git a/_site_test/examples/integration-showcases/integration-showcases-quick-reference.md b/_site_test/examples/integration-showcases/integration-showcases-quick-reference.md new file mode 100644 index 0000000..33c8e9f --- /dev/null +++ b/_site_test/examples/integration-showcases/integration-showcases-quick-reference.md @@ -0,0 +1,225 @@ +# Integration Showcases - Quick Reference + +> **Quick command reference** for testing all 5 integration examples + +--- + +## Setup (One-Time) + +### Step 1: Verify Python Version + +```bash +# Check Python version (requires 3.11+) +python3 --version +# Should show Python 3.11.x or higher +``` + +### Step 2: Install SpecFact + +```bash +# Install via pip (required for interactive AI assistant) +pip install specfact-cli + +# Verify installation +specfact --version +``` + +### Step 3: Create Test Cases + +```bash +# Run setup script +./docs/examples/integration-showcases/setup-integration-tests.sh + +# Or manually +mkdir -p /tmp/specfact-integration-tests +cd /tmp/specfact-integration-tests +``` + +### Step 4: Initialize IDE Integration (For Interactive Mode) + +```bash +# Navigate to test directory +cd /tmp/specfact-integration-tests/example1_vscode + +# Initialize SpecFact for your IDE (one-time per project) +specfact init + +# Or specify IDE explicitly: +# specfact init --ide cursor +# specfact init --ide vscode +``` + +**⚠️ Important**: `specfact init` copies templates to the directory where you run it (e.g., `/tmp/specfact-integration-tests/example1_vscode/.cursor/commands/`). For slash commands to work correctly: + +- **Open the demo repo in your IDE** as the workspace root (e.g., `/tmp/specfact-integration-tests/example1_vscode`) +- Interactive mode automatically uses your IDE workspace - no `--repo .` parameter needed +- **OR** if you need to analyze a different repository: `/specfact.01-import legacy-api --repo /path/to/other/repo` + +--- + +## Example 1: VS Code - Async Bug + +**⚠️ Prerequisite**: Open `/tmp/specfact-integration-tests/example1_vscode` as your IDE workspace. + +```bash +cd /tmp/specfact-integration-tests/example1_vscode + +# Step 1: Import code to create plan +# Recommended: Use interactive AI assistant (slash command in IDE) +# /specfact.01-import legacy-api --repo . +# (Interactive mode automatically uses IDE workspace - --repo . optional) +# The AI will prompt for a plan name - suggest: "Payment Processing" + +# Alternative: CLI-only mode (bundle name as positional argument) +specfact --no-banner import from-code payment-processing --repo . --output-format yaml + +# Step 2: Run enforcement +specfact --no-banner enforce stage --preset balanced + +# Expected: Contract violation about blocking I/O +``` + +**Capture**: Full output, exit code (`echo $?`) + +--- + +## Example 2: Cursor - Regression Prevention + +```bash +cd /tmp/specfact-integration-tests/example2_cursor + +# Step 1: Import code (bundle name as positional argument) +specfact --no-banner import from-code data-pipeline --repo . --output-format yaml + +# Step 2: Test original (should pass) +specfact --no-banner enforce stage --preset balanced + +# Step 3: Create broken version (remove None check) +# Edit src/pipeline.py to remove None check, then: +specfact --no-banner plan compare src/pipeline.py src/pipeline_broken.py --fail-on HIGH + +# Expected: Contract violation for missing None check +``` + +**Capture**: Output from both commands + +--- + +## Example 3: GitHub Actions - Type Error + +```bash +cd /tmp/specfact-integration-tests/example3_github_actions + +# Step 1: Import code (bundle name as positional argument) +specfact --no-banner import from-code user-api --repo . --output-format yaml + +# Step 2: Run enforcement +specfact --no-banner enforce stage --preset balanced + +# Expected: Type mismatch violation (int vs dict) +``` + +**Capture**: Full output, exit code + +--- + +## Example 4: Pre-commit - Breaking Change + +```bash +cd /tmp/specfact-integration-tests/example4_precommit + +# Step 1: Initial commit (bundle name as positional argument) +specfact --no-banner import from-code order-processor --repo . --output-format yaml +git add . +git commit -m "Initial code" + +# Step 2: Modify function (add user_id parameter) +# Edit src/legacy.py to add user_id parameter, then: +git add src/legacy.py +git commit -m "Breaking change test" + +# Expected: Pre-commit hook blocks commit, shows breaking change +``` + +**Capture**: Pre-commit hook output, git commit result + +--- + +## Example 5: Agentic - CrossHair Edge Case + +```bash +cd /tmp/specfact-integration-tests/example5_agentic + +# Option 1: CrossHair exploration (if available) +specfact --no-banner contract-test-exploration src/validator.py + +# Option 2: Contract enforcement (fallback) +specfact --no-banner enforce stage --preset balanced + +# Expected: Division by zero edge case detected +``` + +**Capture**: Output from exploration or enforcement + +--- + +## Output Template + +For each example, provide: + +```markdown +# Example X: [Name] + +## Command Executed + +```bash +[exact command] +``` + +## Full Output + +```bash +[complete stdout and stderr] +``` + +## Exit Code + +```bash +[exit code from echo $?] +``` + +## Files Created + +- [list of files] + +## Issues Found + +- [any problems or unexpected behavior] + +## Expected vs Actual + +- [comparison] + +```text +[comparison details] +``` + +--- + +## Quick Test All + +```bash +# Run all examples in sequence (bundle name as positional argument) +for dir in example1_vscode example2_cursor example3_github_actions example4_precommit example5_agentic; do + echo "Testing $dir..." + cd /tmp/specfact-integration-tests/$dir + bundle_name=$(echo "$dir" | sed 's/example[0-9]_//') + specfact --no-banner import from-code "$bundle_name" --repo . --output-format yaml 2>&1 + specfact --no-banner enforce stage --preset balanced 2>&1 + echo "---" +done +``` + +--- + +**Ready?** Start with Example 1 and work through each one! diff --git a/_site_test/examples/integration-showcases/integration-showcases-testing-guide.md b/_site_test/examples/integration-showcases/integration-showcases-testing-guide.md new file mode 100644 index 0000000..bb076c7 --- /dev/null +++ b/_site_test/examples/integration-showcases/integration-showcases-testing-guide.md @@ -0,0 +1,1692 @@ +# Integration Showcases Testing Guide + +> **Purpose**: Step-by-step guide to test and validate all 5 integration examples from `integration-showcases.md` + +This guide walks you through testing each example to ensure they work as documented and produce the expected outputs. + +--- + +## Prerequisites + +Before starting, ensure you have: + +1. **Python 3.11+ installed**: + + ```bash + # Check your Python version + python3 --version + # Should show Python 3.11.x or higher + ``` + + **Note**: SpecFact CLI requires Python 3.11 or higher. If you have an older version, upgrade Python first. + +2. **Semgrep installed** (optional, for async pattern detection in Example 1): + + ```bash + # Install Semgrep via pip (recommended) + pip install semgrep + + # Verify installation + semgrep --version + ``` + + **Note**: + + - Semgrep is optional but recommended for async pattern detection in Example 1 + - The setup script (`setup-integration-tests.sh`) will create the Semgrep config file automatically + - If Semgrep is not installed, async detection will be skipped but other checks will still run + - Semgrep is available via `pip install semgrep` and works well with Python projects + - The setup script will check if Semgrep is installed and provide installation instructions if missing + +3. **SpecFact CLI installed via pip** (required for interactive AI assistant): + + ```bash + # Install via pip (not just uvx - needed for IDE integration) + pip install specfact-cli + + # Verify installation (first time - banner shows) + specfact --version + ``` + + **Note**: For interactive AI assistant usage (slash commands), SpecFact must be installed via pip so the `specfact` command is available in your environment. `uvx` alone won't work for IDE integration. + +4. **One-time IDE setup** (for interactive AI assistant): + + ```bash + # Navigate to your test directory + cd /tmp/specfact-integration-tests/example1_vscode + + # Initialize SpecFact for your IDE (auto-detects IDE type) + # First time - banner shows, subsequent uses add --no-banner + specfact init + + # Or specify IDE explicitly: + # specfact init --ide cursor + # specfact init --ide vscode + ``` + + **⚠️ Important**: `specfact init` copies templates to the directory where you run the command (e.g., `/tmp/specfact-integration-tests/example1_vscode/.cursor/commands/`). However, for slash commands to work correctly with `--repo .`, you must: + + - **Open the demo repo directory as your IDE workspace** (e.g., `/tmp/specfact-integration-tests/example1_vscode`) + - This ensures `--repo .` operates on the correct repository + - **Note**: Interactive mode automatically uses your IDE workspace. If you need to analyze a different repository, specify: `/specfact.01-import legacy-api --repo /path/to/other/repo` + +5. **Test directory created**: + + ```bash + mkdir -p /tmp/specfact-integration-tests + cd /tmp/specfact-integration-tests + ``` + + **Note**: The setup script (`setup-integration-tests.sh`) automatically initializes git repositories in each example directory, so you don't need to run `git init` manually. + +--- + +## Test Setup + +### Create Test Files + +We'll create test files for each example. Run these commands: + +```bash +# Create directory structure +mkdir -p example1_vscode example2_cursor example3_github_actions example4_precommit example5_agentic +``` + +--- + +## Example 1: VS Code Integration - Async Bug Detection + +### Example 1 - Step 1: Create Test Files + +```bash +cd /tmp/specfact-integration-tests/example1_vscode +``` + +**Note**: The setup script already initializes a git repository in this directory, so `git init` is not needed. + +Create `src/views.py`: + +```python +# src/views.py - Legacy Django view with async bug +def process_payment(request): + user = get_user(request.user_id) + payment = create_payment(user.id, request.amount) + send_notification(user.email, payment.id) # ⚠️ Blocking call + return {"status": "success"} +``` + +### Example 1 - Step 2: Create SpecFact Plan + +**Option A: Interactive AI Assistant (Recommended)** ✅ + +**Prerequisites** (one-time setup): + +1. Ensure Python 3.11+ is installed: + + ```bash + python3 --version # Should show 3.11.x or higher + ``` + +2. Install SpecFact via pip: + + ```bash + pip install specfact-cli + ``` + +3. Initialize IDE integration: + + ```bash + cd /tmp/specfact-integration-tests/example1_vscode + specfact init + ``` + +4. **Open the demo repo in your IDE** (Cursor, VS Code, etc.): + + - Open `/tmp/specfact-integration-tests/example1_vscode` as your workspace + - This ensures `--repo .` operates on the correct repository + +5. Open `views.py` in your IDE and use the slash command: + + ```text + /specfact.01-import legacy-api --repo . + ``` + + **Interactive Flow**: + + 1. **Plan Name Prompt**: The AI assistant will prompt: "What name would you like to use for this plan? (e.g., 'API Client v2', 'User Authentication', 'Payment Processing')" + 2. **Provide Plan Name**: Reply with a meaningful name (e.g., "Payment Processing" or "django-example") + - **Suggested plan name for Example 1**: `Payment Processing` or `Legacy Payment View` + 3. **CLI Execution**: The AI will: + - Sanitize the name (lowercase, remove spaces/special chars) + - Run `specfact import from-code --repo --confidence 0.5` + - Capture CLI output and create a project bundle + 4. **CLI Output Summary**: The AI will present a summary showing: + - Bundle name used + - Mode detected (CI/CD or Copilot) + - Features/stories found (may be 0 for minimal test cases) + - Project bundle location: `.specfact/projects//` (modular structure) + - Analysis report location: `.specfact/projects//reports/brownfield/analysis-.md` (bundle-specific, Phase 8.5) + 5. **Next Steps**: The AI will offer options: + - **LLM Enrichment** (optional in CI/CD mode, required in Copilot mode): Add semantic understanding to detect features/stories that AST analysis missed + - Reply: "Please enrich" or "apply enrichment" + - The AI will read the CLI artifacts and code, create an enrichment report, and apply it via CLI + - **Rerun with different confidence**: Try a lower confidence threshold (e.g., 0.3) to catch more features + - Reply: "rerun with confidence 0.3" + + **Note**: For minimal test cases, the CLI may report "0 features" and "0 stories" - this is expected. Use LLM enrichment to add semantic understanding and detect features that AST analysis missed. + + **Enrichment Workflow** (when you choose "Please enrich"): + + 1. **AI Reads Artifacts**: The AI will read: + - The CLI-generated project bundle (`.specfact/projects//` - modular structure) + - The analysis report (`.specfact/projects//reports/brownfield/analysis-.md`) + - Your source code files (e.g., `views.py`) + 2. **Enrichment Report Creation**: The AI will: + - Draft an enrichment markdown file: `-.enrichment.md` (saved to `.specfact/projects//reports/enrichment/`, Phase 8.5) + - Include missing features, stories, confidence adjustments, and business context + - **CRITICAL**: Follow the exact enrichment report format (see [Dual-Stack Enrichment Guide](../../guides/dual-stack-enrichment.md) for format requirements): + - Features must use numbered list: `1. **Feature Title** (Key: FEATURE-XXX)` + - Each feature must have a `Stories:` section with numbered stories + - Stories must have `- Acceptance:` criteria + - Stories must be indented under the feature + 3. **Apply Enrichment**: The AI will run: + + ```bash + specfact import from-code --repo --enrichment .specfact/projects//reports/enrichment/-.enrichment.md --confidence 0.5 + ``` + + 4. **Enriched Project Bundle**: The CLI will update: + - **Project bundle**: `.specfact/projects//` (updated with enrichment) + - **New analysis report**: `report-.md` + 5. **Enrichment Results**: The AI will present: + - Number of features added + - Number of confidence scores adjusted + - Stories included per feature + - Business context added + - Plan validation status + + **Example Enrichment Results**: + - ✅ 1 feature added: `FEATURE-PAYMENTVIEW` (Payment Processing) + - ✅ 4 stories included: Async Payment Processing, Payment Status API, Cancel Payment, Create Payment + - ✅ Business context: Prioritize payment reliability, migrate blocking notifications to async + - ✅ Confidence: 0.88 (adjusted from default) + + **Note**: In interactive mode, `--repo .` is not required - it automatically uses your IDE workspace. If you need to analyze a different repository than your workspace, you can specify: `/specfact.01-import legacy-api --repo /path/to/other/repo` + +### Option B: CLI-only (For Integration Testing) + +```bash +uvx specfact-cli@latest --no-banner import from-code --repo . --output-format yaml +``` + +**Note**: CLI-only mode uses AST-based analysis and may show "0 features" for minimal test cases. This is expected and the plan bundle is still created for manual contract addition. + +**Banner Usage**: + +- **First-time setup**: Omit `--no-banner` to see the banner (verification, `specfact init`, `specfact --version`) +- **Repeated runs**: Use `--no-banner` **before** the command to suppress banner output +- **Important**: `--no-banner` is a global parameter and must come **before** the subcommand, not after + - ✅ Correct: `specfact --no-banner enforce stage --preset balanced` + - ✅ Correct: `uvx specfact-cli@latest --no-banner import from-code --repo . --output-format yaml` + - ❌ Wrong: `specfact enforce stage --preset balanced --no-banner` + - ❌ Wrong: `uvx specfact-cli@latest import from-code --repo . --output-format yaml --no-banner` + +**Note**: The `import from-code` command analyzes the entire repository/directory, not individual files. It will automatically detect and analyze all Python files in the current directory. + +**Important**: These examples are designed for **interactive AI assistant usage** (slash commands in Cursor, VS Code, etc.), not CLI-only execution. + +**CLI vs Interactive Mode**: + +- **CLI-only** (`uvx specfact-cli@latest import from-code` or `specfact import from-code`): Uses AST-based analyzer (CI/CD mode) + - May show "0 features" for minimal test cases + - Limited to AST pattern matching + - Works but may not detect all features in simple examples + - ✅ Works with `uvx` or pip installation + +- **Interactive AI Assistant** (slash commands in IDE): Uses AI-first semantic understanding + - ✅ **Creates valid plan bundles with features and stories** + - Uses AI to understand code semantics + - Works best for these integration showcase examples + - ⚠️ **Requires**: `pip install specfact-cli` + `specfact init` (one-time setup) + +**How to Use These Examples**: + +1. **Recommended**: Use with AI assistant (Cursor, VS Code CoPilot, etc.) + - Install SpecFact: `pip install specfact-cli` + - Navigate to demo repo: `cd /tmp/specfact-integration-tests/example1_vscode` + - Initialize IDE: `specfact init` (copies templates to `.cursor/commands/` in this directory) + - **⚠️ Important**: Open the demo repo directory as your IDE workspace (e.g., `/tmp/specfact-integration-tests/example1_vscode`) + - Interactive mode automatically uses your IDE workspace - no `--repo .` needed + - Open the test file in your IDE + - Use slash command: `/specfact.01-import legacy-api --repo .` + - Or let the AI prompt you for bundle name - provide a meaningful name (e.g., "legacy-api", "payment-service") + - The command will automatically analyze your IDE workspace + - If initial import shows "0 features", reply "Please enrich" to add semantic understanding + - AI will create an enriched plan bundle with detected features and stories + +2. **Alternative**: CLI-only (for integration testing) + - Works with `uvx specfact-cli@latest` or `pip install specfact-cli` + - May show 0 features, but plan bundle is still created + - Can manually add contracts for enforcement testing + - Useful for testing pre-commit hooks, CI/CD workflows + +**Expected Output**: + +- **Interactive mode**: + - AI creates workflow TODOs to track steps + - CLI runs automatically after plan name is provided + - May show "0 features" and "0 stories" for minimal test cases (expected) + - AI presents CLI output summary with mode, features/stories found, and artifact locations + - AI offers next steps: LLM enrichment or rerun with different confidence + - **Project bundle**: `.specfact/projects//` (modular structure) + - **Analysis report**: `.specfact/projects//reports/brownfield/analysis-.md` (bundle-specific, Phase 8.5) + - **After enrichment** (if requested): + - Enrichment report: `.specfact/projects//reports/enrichment/-.enrichment.md` (bundle-specific, Phase 8.5) + - Project bundle updated: `.specfact/projects//` (enriched) + - New analysis report: `.specfact/projects//reports/brownfield/analysis-.md` (bundle-specific, Phase 8.5) + - Features and stories added (e.g., 1 feature with 4 stories) + - Business context and confidence adjustments included +- **CLI-only mode**: Plan bundle created (may show 0 features for minimal cases) + +### Example 1 - Step 3: Review Plan and Add Missing Stories/Contracts + +**Important**: After enrichment, the plan bundle may have features but missing stories or contracts. Use `plan review` to identify gaps and add them via CLI commands. + +**⚠️ Do NOT manually edit `.specfact` artifacts**. All plan management should be done via CLI commands. + +#### Step 3.1: Run Plan Review to Identify Missing Items + +Run plan review to identify missing stories, contracts, and other gaps: + +```bash +cd /tmp/specfact-integration-tests/example1_vscode + +# Run plan review with auto-enrichment to identify gaps (bundle name as positional argument) +specfact --no-banner plan review django-example \ + --auto-enrich \ + --no-interactive \ + --list-findings \ + --findings-format json +``` + +**What to Look For**: + +- ✅ Review findings show missing stories, contracts, or acceptance criteria +- ✅ Critical findings (status: "Missing") that need to be addressed +- ✅ Partial findings (status: "Partial") that can be refined later + +#### Step 3.2: Add Missing Stories via CLI + +If stories are missing, add them using `plan add-story`: + +```bash +# Add the async payment processing story (bundle name via --bundle option) +specfact --no-banner plan add-story \ + --bundle django-example \ + --feature FEATURE-PAYMENTVIEW \ + --key STORY-PAYMENT-ASYNC \ + --title "Async Payment Processing" \ + --acceptance "process_payment does not call blocking notification functions directly; notifications dispatched via async-safe mechanism (task queue or async I/O); end-to-end payment succeeds and returns status: success" \ + --story-points 8 \ + --value-points 10 + +# Add other stories as needed (Payment Status API, Cancel Payment, Create Payment) +specfact --no-banner plan add-story \ + --bundle django-example \ + --feature FEATURE-PAYMENTVIEW \ + --key STORY-PAYMENT-STATUS \ + --title "Payment Status API" \ + --acceptance "get_payment_status returns correct status for existing payment; returns 404-equivalent for missing payment IDs; status values are one of: pending, success, cancelled" \ + --story-points 3 \ + --value-points 5 +``` + +**Note**: In interactive AI assistant mode (slash commands), the AI will automatically add missing stories based on the review findings. You can also use the interactive mode to guide the process. + +#### Step 3.3: Verify Plan Bundle Completeness + +After adding stories, verify the plan bundle is complete: + +```bash +# Re-run plan review to verify all critical items are resolved +specfact --no-banner plan review django-example \ + --no-interactive \ + --list-findings \ + --findings-format json +``` + +**What to Look For**: + +- ✅ No critical "Missing" findings remaining +- ✅ Stories are present in the plan bundle +- ✅ Acceptance criteria are complete and testable + +**Note**: Contracts are **automatically extracted** during `import from-code` by the AST analyzer, but only if function signatures have type hints. For the async bug detection example, detecting "blocking I/O in async context" requires additional analysis (Semgrep async patterns, not just AST contracts). + +#### Step 3.4: Set Up Enforcement Configuration + +```bash +specfact --no-banner enforce stage --preset balanced +``` + +**What to Look For**: + +- ✅ Enforcement mode configured +- ✅ Configuration saved to `.specfact/gates/config/enforcement.yaml` + +#### Step 3.5: Run Code Analysis for Async Violations + +For detecting async violations (like blocking I/O), use the validation suite which includes Semgrep async pattern analysis: + +**Prerequisites**: The setup script (`setup-integration-tests.sh`) already creates the proper project structure and Semgrep config. If you're setting up manually: + +```bash +# Create proper project structure (if not already done) +cd /tmp/specfact-integration-tests/example1_vscode +mkdir -p src tests tools/semgrep + +# The setup script automatically creates tools/semgrep/async.yml +# If running manually, ensure Semgrep config exists at: tools/semgrep/async.yml +``` + +**Note**: The setup script automatically: + +- Creates `tools/semgrep/` directory +- Copies or creates Semgrep async config (`tools/semgrep/async.yml`) +- Checks if Semgrep is installed and provides installation instructions if missing + +**Run Validation**: + +```bash +specfact --no-banner repro --repo . --budget 60 +``` + +**What to Look For**: + +- ✅ Semgrep async pattern analysis runs (if `tools/semgrep/async.yml` exists and Semgrep is installed) +- ✅ Semgrep appears in the summary table with status (PASSED/FAILED/SKIPPED) +- ✅ Detects blocking calls in async context (if violations exist) +- ✅ Reports violations with severity levels +- ⚠️ If Semgrep is not installed or config doesn't exist, this check will be skipped +- 💡 Use `--verbose` flag to see detailed Semgrep output: `specfact --no-banner repro --repo . --budget 60 --verbose` + +**Expected Output Format** (summary table): + +```bash +Check Summary +┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━┓ +┃ Check ┃ Tool ┃ Status ┃ +┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━┩ +│ Linting (ruff) │ ruff │ ✗ FAILED │ +│ Async patterns (semgrep) │ semgrep │ ✓ PASSED │ +│ Type checking (basedpyright) │ basedpyright │ ⊘ SKIPPED │ +│ Contract exploration (CrossHair)│ crosshair │ ✓ PASSED │ +└─────────────────────────────────┴──────────────┴───────────┘ +``` + +**With `--verbose` flag**, you'll see detailed Semgrep output: + +```bash +Async patterns (semgrep) Error: +┌─────────────┐ +│ Scan Status │ +└─────────────┘ + Scanning 46 files tracked by git with 13 Code rules: + Scanning 1 file with 13 python rules. + +┌──────────────┐ +│ Scan Summary │ +└──────────────┘ +✅ Scan completed successfully. + • Findings: 0 (0 blocking) + • Rules run: 13 + • Targets scanned: 1 +``` + +**Note**: + +- Semgrep output is shown in the summary table by default +- Detailed Semgrep output (scan status, findings) is only shown with `--verbose` flag +- If Semgrep is not installed or config doesn't exist, the check will be skipped +- The enforcement workflow still works via `plan compare`, which validates acceptance criteria in the plan bundle +- Use `--fix` flag to apply Semgrep auto-fixes: `specfact --no-banner repro --repo . --budget 60 --fix` + +#### Alternative: Use Plan Compare for Contract Validation + +You can also use `plan compare` to detect deviations between code and plan contracts: + +```bash +specfact --no-banner plan compare --code-vs-plan +``` + +This compares the current code state against the plan bundle contracts and reports any violations. + +### Example 1 - Step 4: Test Enforcement + +Now let's test that enforcement actually works by comparing plans and detecting violations: + +```bash +# Test plan comparison with enforcement (bundle directory paths) +cd /tmp/specfact-integration-tests/example1_vscode +specfact --no-banner plan compare \ + --manual .specfact/projects/django-example \ + --auto .specfact/projects/django-example-auto +``` + +**Expected Output**: + +```bash +============================================================ +Comparison Results +============================================================ + +Total Deviations: 1 + +Deviation Summary: + 🔴 HIGH: 1 + 🟡 MEDIUM: 0 + 🔵 LOW: 0 + +🚫 [HIGH] missing_feature: BLOCK +❌ Enforcement BLOCKED: 1 deviation(s) violate quality gates +Fix the blocking deviations or adjust enforcement config +``` + +**What This Shows**: + +- ✅ Enforcement is working: HIGH severity deviations are blocked +- ✅ Plan comparison detects differences between enriched and original plans +- ✅ Enforcement rules are applied correctly (HIGH → BLOCK) + +**Note**: This test demonstrates that enforcement blocks violations. For the actual async blocking detection, you would use Semgrep async pattern analysis (requires a more complete project structure with `src/` and `tests/` directories). + +### Example 1 - Step 5: Verify Results + +**What We've Accomplished**: + +1. ✅ Created plan bundle from code (`import from-code`) +2. ✅ Enriched plan with semantic understanding (added feature and stories) +3. ✅ Reviewed plan and added missing stories via CLI +4. ✅ Configured enforcement (balanced preset) +5. ✅ Tested enforcement (plan compare detected and blocked violations) + +**Plan Bundle Status**: + +- Features: 1 (`FEATURE-PAYMENTVIEW`) +- Stories: 4 (including `STORY-PAYMENT-ASYNC` with acceptance criteria requiring non-blocking notifications) +- Enforcement: Configured and working + +**Validation Status**: + +- ✅ **Workflow Validated**: End-to-end workflow (import → enrich → review → enforce) works correctly +- ✅ **Enforcement Validated**: Enforcement blocks HIGH severity violations via `plan compare` +- ✅ **Async Detection**: Semgrep integration works (Semgrep available via `pip install semgrep`) + - Semgrep runs async pattern analysis when `tools/semgrep/async.yml` exists + - Semgrep appears in validation summary table with status (PASSED/FAILED/SKIPPED) + - Detailed Semgrep output shown with `--verbose` flag + - `--fix` flag works: adds `--autofix` to Semgrep command for automatic fixes + - Async detection check passes in validation suite + - Proper project structure (`src/` directory) required for Semgrep to scan files + +**Test Results**: + +- Plan bundle: ✅ 1 feature, 4 stories (including `STORY-PAYMENT-ASYNC`) +- Enforcement: ✅ Blocks HIGH severity violations +- Async detection: ✅ Semgrep runs successfully (installed via `pip install semgrep`) + +**Note**: The demo is fully validated. Semgrep is available via `pip install semgrep` and integrates seamlessly with SpecFact CLI. The acceptance criteria in `STORY-PAYMENT-ASYNC` explicitly requires non-blocking notifications, and enforcement will block violations when comparing code against the plan. + +--- + +## Example 2: Cursor Integration - Regression Prevention + +### Example 2 - Step 1: Create Test Files + +```bash +cd /tmp/specfact-integration-tests/example2_cursor +``` + +**Note**: The setup script already initializes a git repository in this directory, so `git init` is not needed. + +Create `src/pipeline.py`: + +```python +# src/pipeline.py - Legacy data processing +def process_data(data: list[dict]) -> dict: + if not data: + return {"status": "empty", "count": 0} + + # Critical: handles None values in data + filtered = [d for d in data if d is not None and d.get("value") is not None] + + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } +``` + +### Example 2 - Step 2: Create Plan with Contract + +**Recommended**: Use interactive AI assistant (slash command in IDE): + +```text +/specfact.01-import legacy-api --repo . +``` + +**Interactive Flow**: + +- The AI assistant will prompt for bundle name if not provided +- **Suggested plan name for Example 2**: `Data Processing` or `Legacy Data Pipeline` +- Reply with the plan name (e.g., "Data Processing or Legacy Data Pipeline") +- The AI will: + 1. Run CLI import (may show 0 features initially - expected for AST-only analysis) + 2. Review artifacts and detect `DataProcessor` class + 3. Generate enrichment report + 4. Apply enrichment via CLI + 5. Add stories via CLI commands if needed + +**Expected Output Format**: + +```text +## Import complete + +### Plan bundles +- Original plan: data-processing-or-legacy-data-pipeline..bundle.yaml +- Enriched plan: data-processing-or-legacy-data-pipeline..enriched..bundle.yaml + +### CLI analysis results +- Features identified: 0 (AST analysis missed the DataProcessor class) +- Stories extracted: 0 +- Confidence threshold: 0.5 + +### LLM enrichment insights +Missing feature discovered: +- FEATURE-DATAPROCESSOR: Data Processing with Legacy Data Support + - Confidence: 0.85 + - Outcomes: + - Process legacy data with None value handling + - Transform and validate data structures + - Filter data by key criteria + +Stories added (4 total): +1. STORY-001: Process Data with None Handling (Story Points: 5 | Value Points: 8) +2. STORY-002: Validate Data Structure (Story Points: 2 | Value Points: 5) +3. STORY-003: Transform Data Format (Story Points: 3 | Value Points: 6) +4. STORY-004: Filter Data by Key (Story Points: 2 | Value Points: 5) + +### Final plan summary +- Features: 1 +- Stories: 4 +- Themes: Core +- Stage: draft +``` + +**Note**: In interactive mode, the command automatically uses your IDE workspace - no `--repo .` parameter needed. + +**Alternative**: CLI-only mode: + +```bash +uvx specfact-cli@latest --no-banner import from-code --repo . --output-format yaml +``` + +**Note**: Interactive mode creates valid plan bundles with features. CLI-only may show 0 features for minimal test cases. Use `--no-banner` before the command to suppress banner output: `specfact --no-banner `. + +### Example 2 - Step 3: Review Plan and Improve Quality + +**Important**: After enrichment, review the plan to identify gaps and improve quality. The `plan review` command can auto-enrich the plan to fix common issues: + +#### Option A: Interactive AI Assistant (Recommended) + +Use the slash command in your IDE: + +```text +/specfact.03-review legacy-api +``` + +**Interactive Flow**: + +- The AI assistant will review the enriched plan bundle +- It will run with `--auto-enrich` to fix common quality issues +- The AI will: + 1. Analyze the plan for missing items (target users, acceptance criteria, etc.) + 2. Create batch update files to address findings + 3. Apply updates via CLI commands + 4. Re-run review to verify improvements + 5. Present a summary of improvements made + +**Expected Output Format**: + +```text +## Review complete + +### Summary +Project Bundle: .specfact/projects/data-processing-or-legacy-data-pipeline/ + +Updates Applied: +- Idea section: Added target users and value hypothesis +- Feature acceptance criteria: Added 3 testable criteria +- Story acceptance criteria: Enhanced all 4 stories with specific, testable Given/When/Then criteria + +### Coverage summary +| Category | Status | Notes | +|----------|--------|-------| +| Functional Scope & Behavior | Clear | Resolved (was Missing) - Added target users | +| Domain & Data Model | Partial | Minor gap (data model constraints) - not critical | +| Interaction & UX Flow | Clear | Resolved (was Partial) - Added error handling | +| Edge Cases & Failure Handling | Clear | Resolved (was Partial) - Added edge case criteria | +| Feature/Story Completeness | Clear | Resolved (was Missing) - Added feature acceptance criteria | + +### Improvements made +1. Target users: Added "Data engineers", "Developers working with legacy data", "Backend developers" +2. Value hypothesis: Added business value statement +3. Feature acceptance criteria: Added 3 testable criteria covering: + - Successful method execution + - None value handling + - Error handling for invalid inputs +4. Story acceptance criteria: Enhanced all 4 stories with: + - Specific method signatures (e.g., `process_data(data: list[dict])`) + - Expected return values (e.g., `dict with 'status' key`) + - Edge cases (empty lists, None values, invalid inputs) + - Error handling scenarios + +### Next steps +- Plan is ready for promotion to `review` stage +- All critical ambiguities resolved +- All acceptance criteria are testable and specific +``` + +#### Option B: CLI-only Mode + +```bash +cd /tmp/specfact-integration-tests/example2_cursor + +# Review plan with auto-enrichment (bundle name as positional argument) +specfact --no-banner plan review data-processing-or-legacy-data-pipeline \ + --auto-enrich \ + --no-interactive \ + --list-findings \ + --findings-format json +``` + +**What to Look For**: + +- ✅ All critical findings resolved (Status: Clear) +- ✅ Feature acceptance criteria added (3 testable criteria) +- ✅ Story acceptance criteria enhanced (specific, testable Given/When/Then format) +- ✅ Target users and value hypothesis added +- ⚠️ Minor partial findings (e.g., data model constraints) are acceptable and not blocking + +**Note**: The `plan review` command with `--auto-enrich` will automatically fix common quality issues via CLI commands, so you don't need to manually edit plan bundles. + +### Example 2 - Step 4: Configure Enforcement + +After plan review is complete and all critical issues are resolved, configure enforcement: + +```bash +cd /tmp/specfact-integration-tests/example2_cursor +specfact --no-banner enforce stage --preset balanced +``` + +**Expected Output**: + +```text +Setting enforcement mode: balanced + Enforcement Mode: + BALANCED +┏━━━━━━━━━━┳━━━━━━━━┓ +┃ Severity ┃ Action ┃ +┡━━━━━━━━━━╇━━━━━━━━┩ +│ HIGH │ BLOCK │ +│ MEDIUM │ WARN │ +│ LOW │ LOG │ +└──────────┴────────┘ + +✓ Enforcement mode set to balanced +Configuration saved to: .specfact/gates/config/enforcement.yaml +``` + +**What to Look For**: + +- ✅ Enforcement mode configured (BALANCED preset) +- ✅ Configuration saved to `.specfact/gates/config/enforcement.yaml` +- ✅ Severity-to-action mapping displayed (HIGH → BLOCK, MEDIUM → WARN, LOW → LOG) + +**Note**: The plan review in Step 3 should have resolved all critical ambiguities and enhanced acceptance criteria. The plan is now ready for enforcement testing. + +### Example 2 - Step 5: Test Plan Comparison + +Test that plan comparison works correctly by comparing the enriched plan against the original plan: + +```bash +cd /tmp/specfact-integration-tests/example2_cursor +specfact --no-banner plan compare \ + --manual .specfact/projects/data-processing-or-legacy-data-pipeline \ + --auto .specfact/projects/data-processing-or-legacy-data-pipeline-auto +``` + +**Expected Output**: + +```text +ℹ️ Writing comparison report to: +.specfact/projects//reports/comparison/report-.md + +============================================================ +SpecFact CLI - Plan Comparison +============================================================ + +ℹ️ Loading manual plan: +ℹ️ Loading auto plan: +ℹ️ Comparing plans... + +============================================================ +Comparison Results +============================================================ + +Manual Plan: +Auto Plan: +Total Deviations: 1 + +Deviation Summary: + 🔴 HIGH: 1 + 🟡 MEDIUM: 0 + 🔵 LOW: 0 + + Deviations by Type and Severity +┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ +┃ Severity ┃ Type ┃ Description ┃ Location ┃ +┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩ +│ 🔴 HIGH │ Missing Feature │ Feature │ features[FEATURE-DATA… │ +│ │ │ 'FEATURE-DATAPROCESSO… │ │ +│ │ │ (Data Processing with │ │ +│ │ │ Legacy Data Support) │ │ +│ │ │ in ma... │ │ +└──────────┴─────────────────┴────────────────────────┴────────────────────────┘ + +============================================================ +Enforcement Rules +============================================================ + +Using enforcement config: .specfact/gates/config/enforcement.yaml + +🚫 [HIGH] missing_feature: BLOCK +❌ Enforcement BLOCKED: 1 deviation(s) violate quality gates +Fix the blocking deviations or adjust enforcement config +❌ Comparison failed: 1 +``` + +**What to Look For**: + +- ✅ Plan comparison runs successfully +- ✅ Deviations detected (enriched plan has features that original plan doesn't) +- ✅ HIGH severity deviation triggers BLOCK action +- ✅ Enforcement blocks the comparison (exit code: 1) +- ✅ Comparison report generated at `.specfact/projects//reports/comparison/report-.md` + +**Note**: This demonstrates that plan comparison works and enforcement blocks HIGH severity violations. The deviation is expected because the enriched plan has additional features/stories that the original AST-derived plan doesn't have. + +### Example 2 - Step 6: Test Breaking Change (Regression Detection) + +**Concept**: This step demonstrates how SpecFact detects when code changes violate contracts. The enriched plan has acceptance criteria requiring None value handling. If code is modified to remove the None check, plan comparison should detect this as a violation. + +**Note**: The actual regression detection would require: + +1. Creating a new plan from the modified (broken) code +2. Comparing the new plan against the enriched plan +3. Detecting that the new plan violates the acceptance criteria + +For demonstration purposes, Step 5 already shows that plan comparison works and enforcement blocks HIGH severity violations. The workflow is: + +1. **Original code** → Import → Create plan → Enrich → Review (creates enriched plan with contracts) +2. **Code changes** (e.g., removing None check) → Import → Create new plan +3. **Compare plans** → Detects violations → Enforcement blocks if HIGH severity + +**To fully demonstrate regression detection**, you would: + +```bash +# 1. Create broken version (removes None check) +cat > src/pipeline_broken.py << 'EOF' +# src/pipeline_broken.py - Broken version without None check +class DataProcessor: + def process_data(self, data: list[dict]) -> dict: + if not data: + return {"status": "empty", "count": 0} + # ⚠️ None check removed + filtered = [d for d in data if d.get("value") is not None] + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } +EOF + +# 2. Temporarily replace original with broken version +mv src/pipeline.py src/pipeline_original.py +mv src/pipeline_broken.py src/pipeline.py + +# 3. Import broken code to create new plan +specfact --no-banner import from-code pipeline-broken --repo . --output-format yaml + +# 4. Compare new plan (from broken code) against enriched plan +specfact --no-banner plan compare \ + --manual .specfact/projects/data-processing-or-legacy-data-pipeline \ + --auto .specfact/projects/pipeline-broken + +# 5. Restore original code +mv src/pipeline.py src/pipeline_broken.py +mv src/pipeline_original.py src/pipeline.py +``` + +**Expected Result**: The comparison should detect that the broken code plan violates the acceptance criteria requiring None value handling, resulting in a HIGH severity deviation that gets blocked by enforcement. + +**What This Demonstrates**: + +- ✅ **Regression Prevention**: SpecFact detects when refactoring removes critical edge case handling +- ✅ **Contract Enforcement**: The None check requirement is enforced via acceptance criteria in the plan +- ✅ **Breaking Change Detection**: `plan compare` identifies when code changes violate plan contracts +- ✅ **Enforcement Blocking**: HIGH severity violations are automatically blocked + +### Example 2 - Step 7: Verify Results + +**What We've Accomplished**: + +1. ✅ Created plan bundle from code (`import from-code`) +2. ✅ Enriched plan with semantic understanding (added FEATURE-DATAPROCESSOR and 4 stories) +3. ✅ Reviewed plan and improved quality (added target users, value hypothesis, feature acceptance criteria, enhanced story acceptance criteria with Given/When/Then format) +4. ✅ Configured enforcement (balanced preset with HIGH → BLOCK, MEDIUM → WARN, LOW → LOG) +5. ✅ Tested plan comparison (detects deviations and blocks HIGH severity violations) +6. ✅ Demonstrated regression detection workflow (plan comparison works, enforcement blocks violations) + +**Plan Bundle Status**: + +- Features: 1 (`FEATURE-DATAPROCESSOR`) +- Stories: 4 (including STORY-001: Process Data with None Handling) +- Enforcement: Configured and working (BALANCED preset) + +**Actual Test Results**: + +- ✅ Enforcement configuration: Successfully configured with BALANCED preset +- ✅ Plan comparison: Successfully detects deviations (1 HIGH severity deviation found) +- ✅ Enforcement blocking: HIGH severity violations are blocked (exit code: 1) +- ✅ Comparison report: Generated at `.specfact/projects//reports/comparison/report-.md` + +**What This Demonstrates**: + +- ✅ **Regression Prevention**: SpecFact detects when refactoring removes critical edge case handling +- ✅ **Contract Enforcement**: The None check requirement is enforced via acceptance criteria in the plan +- ✅ **Breaking Change Detection**: `plan compare` identifies when code changes violate plan contracts +- ✅ **Enforcement Blocking**: HIGH severity violations are automatically blocked by enforcement rules + +**Validation Status**: Example 2 workflow is validated. Plan comparison works correctly and enforcement blocks HIGH severity violations as expected. + +--- + +## Example 3: GitHub Actions Integration - Type Error Detection + +### Example 3 - Step 1: Create Test Files + +```bash +cd /tmp/specfact-integration-tests/example3_github_actions +``` + +**Note**: The setup script already initializes a git repository in this directory, so `git init` is not needed. + +Create `src/api.py`: + +```python +# src/api.py - New endpoint with type mismatch +def get_user_stats(user_id: str) -> dict: + # Simulate: calculate_stats returns int, not dict + stats = 42 # Returns int, not dict + return stats # ⚠️ Type mismatch: int vs dict +``` + +### Example 3 - Step 2: Create Plan with Type Contract + +**Recommended**: Use interactive AI assistant (slash command in IDE): + +```text +/specfact.01-import legacy-api --repo . +``` + +**Interactive Flow**: + +- The AI assistant will prompt for bundle name if not provided +- **Suggested plan name for Example 3**: `User Stats API` or `API Endpoints` +- Reply with the plan name +- The AI will create and enrich the plan bundle with detected features and stories + +**Note**: In interactive mode, the command automatically uses your IDE workspace - no `--repo .` parameter needed. + +**Alternative**: CLI-only mode: + +```bash +specfact --no-banner import from-code --repo . --output-format yaml +``` + +**Note**: Interactive mode creates valid plan bundles with features. CLI-only may show 0 features for minimal test cases. Use `--no-banner` before the command to suppress banner output: `specfact --no-banner `. + +### Example 3 - Step 3: Add Type Contract + +**Note**: Use CLI commands to interact with bundles. Do not edit `.specfact` files directly. Use `plan update-feature` or `plan update-story` commands to add contracts. + +### Example 3 - Step 4: Configure Enforcement + +```bash +cd /tmp/specfact-integration-tests/example3_github_actions +specfact --no-banner enforce stage --preset balanced +``` + +**What to Look For**: + +- ✅ Enforcement mode configured +- ✅ Configuration saved to `.specfact/gates/config/enforcement.yaml` + +### Example 3 - Step 5: Run Validation Checks + +```bash +specfact --no-banner repro --repo . --budget 90 +``` + +**Expected Output Format**: + +```text +Running validation suite... +Repository: . +Time budget: 90s + +⠙ Running validation checks... + +Validation Results + + Check Summary +┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓ +┃ Check ┃ Tool ┃ Status ┃ Duration ┃ +┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩ +│ Linting (ruff) │ ruff │ ✗ FAILED │ 0.03s │ +│ Type checking (basedpyright) │ basedpyright │ ✗ FAILED │ 1.12s │ +│ Contract exploration (CrossHair) │ crosshair │ ✗ FAILED │ 0.58s │ +└──────────────────────────────────┴──────────────┴──────────┴──────────┘ + +Summary: + Total checks: 3 + Passed: 0 + Failed: 3 + Total duration: 1.73s + +Report written to: .specfact/projects//reports/enforcement/report-.yaml + +✗ Some validations failed +``` + +**What to Look For**: + +- ✅ Validation suite runs successfully +- ✅ Check summary table shows status of each check +- ✅ Type checking detects type mismatches (if basedpyright is available) +- ✅ Report generated at `.specfact/projects//reports/enforcement/report-.yaml` (bundle-specific, Phase 8.5) +- ✅ Exit code 1 if violations found (blocks PR merge in GitHub Actions) + +**Note**: The `repro` command runs validation checks conditionally: + +- **Always runs**: + - Linting (ruff) - code style and common Python issues + - Type checking (basedpyright) - type annotations and type safety + +- **Conditionally runs** (only if present): + - Contract exploration (CrossHair) - only if `[tool.crosshair]` config exists in `pyproject.toml` (use `specfact repro setup` to generate) and `src/` directory exists (symbolic execution to find counterexamples, not runtime contract validation) + - Semgrep async patterns - only if `tools/semgrep/async.yml` exists (requires semgrep installed) + - Property tests (pytest) - only if `tests/contracts/` directory exists + - Smoke tests (pytest) - only if `tests/smoke/` directory exists + +**CrossHair Setup**: Before running `repro` for the first time, set up CrossHair configuration: + +```bash +specfact repro setup +``` +This automatically generates `[tool.crosshair]` configuration in `pyproject.toml` to enable contract exploration. + +**Important**: `repro` does **not** perform runtime contract validation (checking `@icontract` decorators at runtime). It runs static analysis (linting, type checking) and symbolic execution (CrossHair) for contract exploration. Type mismatches will be detected by the type checking tool (basedpyright) if available. The enforcement configuration determines whether failures block the workflow. + +### Example 3 - Step 6: Verify Results + +**What We've Accomplished**: + +1. ✅ Created plan bundle from code (`import from-code`) +2. ✅ Enriched plan with semantic understanding (if using interactive mode) +3. ✅ Configured enforcement (balanced preset) +4. ✅ Ran validation suite (`specfact repro`) +5. ✅ Validation checks executed (linting, type checking, contract exploration) + +**Expected Test Results**: + +- Enforcement: ✅ Configured with BALANCED preset +- Validation: ✅ Runs comprehensive checks via `repro` command +- Type checking: ✅ Detects type mismatches (if basedpyright is available) +- Exit code: ✅ Returns 1 if violations found (blocks PR in GitHub Actions) + +**What This Demonstrates**: + +- ✅ **CI/CD Integration**: SpecFact works seamlessly in GitHub Actions +- ✅ **Automated Validation**: `repro` command runs all validation checks +- ✅ **Type Safety**: Type checking detects mismatches before merge +- ✅ **PR Blocking**: Workflow fails (exit code 1) when violations are found + +**Validation Status**: Example 3 is **fully validated** in production CI/CD. The GitHub Actions workflow runs `specfact repro` in the specfact-cli repository and successfully: + +- ✅ Runs linting (ruff) checks +- ✅ Runs async pattern detection (Semgrep) +- ✅ Runs type checking (basedpyright) - detects type errors +- ✅ Runs contract exploration (CrossHair) - conditionally +- ✅ Blocks PRs when validation fails (exit code 1) + +**Production Validation**: The workflow is actively running in [PR #28](https://github.com/nold-ai/specfact-cli/pull/28) and successfully validates code changes. Type checking errors are detected and reported, demonstrating that the CI/CD integration works as expected. + +--- + +## Example 4: Pre-commit Hook - Breaking Change Detection + +### Example 4 - Step 1: Create Test Files + +```bash +cd /tmp/specfact-integration-tests/example4_precommit +``` + +**Note**: The setup script already initializes a git repository in this directory, so `git init` is not needed. + +Create `src/legacy.py`: + +```python +# src/legacy.py - Original function +def process_order(order_id: str) -> dict: + return {"order_id": order_id, "status": "processed"} +``` + +Create `src/caller.py`: + +```python +# src/caller.py - Uses legacy function +from legacy import process_order + +result = process_order(order_id="123") +``` + +### Example 4 - Step 2: Create Initial Plan + +**Recommended**: Use interactive AI assistant (slash command in IDE): + +```text +/specfact.01-import legacy-api --repo . +``` + +**Interactive Flow**: + +- The AI assistant will prompt for bundle name if not provided +- **Suggested plan name for Example 4**: `Order Processing` or `Legacy Order System` +- Reply with the plan name +- The AI will create and enrich the plan bundle with detected features and stories + +**Note**: In interactive mode, the command automatically uses your IDE workspace - no `--repo .` parameter needed. + +**Alternative**: CLI-only mode: + +```bash +specfact --no-banner import from-code --repo . --output-format yaml +``` + +**Important**: After creating the initial plan, we need to make it the default plan so `plan compare --code-vs-plan` can find it. Use `plan select` to set it as the active plan: + +```bash +# Find the created plan bundle +# Use bundle name directly (no need to find file) +BUNDLE_NAME="example4_github_actions" +PLAN_NAME=$(basename "$PLAN_FILE") + +# Set it as the active plan (this makes it the default for plan compare) +specfact --no-banner plan select "$BUNDLE_NAME" --no-interactive + +# Verify it's set as active +specfact --no-banner plan select --current +``` + +**Note**: `plan compare --code-vs-plan` uses the active plan (set via `plan select`) or falls back to the default bundle if no active plan is set. Using `plan select` is the recommended approach as it's cleaner and doesn't require file copying. + +Then commit: + +```bash +git add . +git commit -m "Initial code" +``` + +**Note**: Interactive mode creates valid plan bundles with features. CLI-only may show 0 features for minimal test cases. + +### Example 4 - Step 3: Modify Function (Breaking Change) + +Edit `src/legacy.py` to add a required parameter (breaking change): + +```python +# src/legacy.py - Modified function signature +class OrderProcessor: + """Processes orders.""" + + def process_order(self, order_id: str, user_id: str) -> dict: # ⚠️ Added required user_id + """Process an order with user ID. + + Processes an order and returns its status. + Note: user_id is now required (breaking change). + """ + return {"order_id": order_id, "user_id": user_id, "status": "processed"} + + def get_order(self, order_id: str) -> dict: + """Get order details.""" + return {"id": order_id, "items": []} + + def update_order(self, order_id: str, data: dict) -> dict: + """Update an order.""" + return {"id": order_id, "updated": True, **data} +``` + +**Note**: The caller (`src/caller.py`) still uses the old signature without `user_id`, which will cause a breaking change. + +### Example 4 - Step 3.5: Configure Enforcement (Before Pre-commit Hook) + +Before setting up the pre-commit hook, configure enforcement: + +```bash +cd /tmp/specfact-integration-tests/example4_precommit +specfact --no-banner enforce stage --preset balanced +``` + +**What to Look For**: + +- ✅ Enforcement mode configured (BALANCED preset) +- ✅ Configuration saved to `.specfact/gates/config/enforcement.yaml` +- ✅ Severity-to-action mapping: HIGH → BLOCK, MEDIUM → WARN, LOW → LOG + +**Note**: The pre-commit hook uses this enforcement configuration to determine whether to block commits. + +### Example 4 - Step 4: Set Up Pre-commit Hook + +Create `.git/hooks/pre-commit`: + +```bash +#!/bin/sh +# First, import current code to create a new plan for comparison +# Use default name "auto-derived" so plan compare --code-vs-plan can find it +specfact --no-banner import from-code --repo . --output-format yaml > /dev/null 2>&1 + +# Then compare: uses active plan (set via plan select) as manual, latest code-derived plan as auto +specfact --no-banner plan compare --code-vs-plan +``` + +**What This Does**: + +- Imports current code to create a new plan (auto-derived from modified code) + - **Important**: Uses default name "auto-derived" (or omit `--name`) so `plan compare --code-vs-plan` can find it + - `plan compare --code-vs-plan` looks for plans named `auto-derived.*.bundle.*` +- Compares the new plan (auto) against the active plan (manual/baseline - set via `plan select` in Step 2) +- Uses enforcement configuration to determine if deviations should block the commit +- Blocks commit if HIGH severity deviations are found (based on enforcement preset) + +**Note**: The `--code-vs-plan` flag automatically uses: + +- **Manual plan**: The active plan (set via `plan select`) or `main.bundle.yaml` as fallback +- **Auto plan**: The latest `auto-derived` project bundle (from `import from-code auto-derived` or default bundle name) + +Make it executable: + +```bash +chmod +x .git/hooks/pre-commit +``` + +### Example 4 - Step 5: Test Pre-commit Hook + +```bash +git add src/legacy.py +git commit -m "Breaking change test" +``` + +**What to Look For**: + +- ✅ Pre-commit hook runs +- ✅ Breaking change detected +- ✅ Commit blocked +- ✅ Error message about signature change + +**Expected Output Format**: + +```bash +============================================================ +Code vs Plan Drift Detection +============================================================ + +Comparing intended design (manual plan) vs actual implementation (code-derived plan) + +ℹ️ Using default manual plan: .specfact/projects/django-example/ +ℹ️ Using latest code-derived plan: .specfact/projects/auto-derived/ + +============================================================ +Comparison Results +============================================================ + +Total Deviations: 3 + +Deviation Summary: + 🔴 HIGH: 1 + 🟡 MEDIUM: 0 + 🔵 LOW: 2 + + Deviations by Type and Severity +┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ +┃ Severity ┃ Type ┃ Description ┃ Location ┃ +┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩ +│ 🔴 HIGH │ Missing Feature │ Feature 'FEATURE-*' │ features[FEATURE-*] │ +│ │ │ in manual plan but not │ │ +│ │ │ implemented in code │ │ +└──────────┴─────────────────┴────────────────────────┴────────────────────────┘ + +============================================================ +Enforcement Rules +============================================================ + +🚫 [HIGH] missing_feature: BLOCK +❌ Enforcement BLOCKED: 1 deviation(s) violate quality gates +Fix the blocking deviations or adjust enforcement config +❌ Comparison failed: 1 +``` + +**What This Shows**: + +- ✅ Plan comparison successfully finds both plans (active plan as manual, latest auto-derived as auto) +- ✅ Detects deviations (missing features, mismatches) +- ✅ Enforcement blocks the commit (HIGH → BLOCK based on balanced preset) +- ✅ Pre-commit hook exits with code 1, blocking the commit + +**Note**: The comparison may show deviations like "Missing Feature" when comparing an enriched plan (with AI-added features) against an AST-only plan (which may have 0 features). This is expected behavior - the enriched plan represents the intended design, while the AST-only plan represents what's actually in the code. For breaking change detection, you would compare two code-derived plans (before and after code changes). + +### Example 4 - Step 6: Verify Results + +**What We've Accomplished**: + +1. ✅ Created initial plan bundle from original code (`import from-code`) +2. ✅ Committed the original plan (baseline) +3. ✅ Modified code to introduce breaking change (added required `user_id` parameter) +4. ✅ Configured enforcement (balanced preset with HIGH → BLOCK) +5. ✅ Set up pre-commit hook (`plan compare --code-vs-plan`) +6. ✅ Tested pre-commit hook (commit blocked due to HIGH severity deviation) + +**Plan Bundle Status**: + +- Original plan: Created from initial code (before breaking change) +- New plan: Auto-derived from modified code (with breaking change) +- Comparison: Detects signature change as HIGH severity deviation +- Enforcement: Blocks commit when HIGH severity deviations found + +**Validation Status**: + +- ✅ **Pre-commit Hook**: Successfully blocks commits with breaking changes +- ✅ **Enforcement**: HIGH severity deviations trigger BLOCK action +- ✅ **Plan Comparison**: Detects signature changes and other breaking changes +- ✅ **Workflow**: Complete end-to-end validation (plan → modify → compare → block) + +**What This Demonstrates**: + +- ✅ **Breaking Change Detection**: SpecFact detects when function signatures change +- ✅ **Backward Compatibility**: Pre-commit hook prevents breaking changes from being committed +- ✅ **Local Validation**: No CI delay - issues caught before commit +- ✅ **Enforcement Integration**: Uses enforcement configuration to determine blocking behavior + +--- + +## Example 5: Agentic Workflow - CrossHair Edge Case Discovery + +### Example 5 - Step 1: Create Test Files + +```bash +cd /tmp/specfact-integration-tests/example5_agentic +``` + +**Note**: The setup script already initializes a git repository in this directory, so `git init` is not needed. + +Create `src/validator.py`: + +```python +# src/validator.py - AI-generated validation with edge case +def validate_and_calculate(data: dict) -> float: + value = data.get("value", 0) + divisor = data.get("divisor", 1) + return value / divisor # ⚠️ Edge case: divisor could be 0 +``` + +### Example 5 - Step 2: Run CrossHair Exploration + +```bash +specfact --no-banner contract-test-exploration src/validator.py +``` + +**Note**: If using `uvx`, the command would be: + +```bash +uvx specfact-cli@latest --no-banner contract-test-exploration src/validator.py +``` + +**What to Look For**: + +- ✅ CrossHair runs (if available) +- ✅ Division by zero detected +- ✅ Counterexample found +- ✅ Edge case identified + +**Expected Output Format** (if CrossHair is configured): + +```bash +🔍 CrossHair Exploration: Found counterexample + File: src/validator.py:3 + Function: validate_and_calculate + Issue: Division by zero when divisor=0 + Counterexample: {"value": 10, "divisor": 0} + Severity: HIGH + Fix: Add divisor != 0 check +``` + +**Note**: CrossHair requires additional setup. If not available, we can test with contract enforcement instead. + +### Example 5 - Step 3: Alternative Test (Contract Enforcement) + +If CrossHair is not available, test with contract enforcement: + +```bash +specfact --no-banner enforce stage --preset balanced +``` + +### Example 5 - Step 4: Provide Output + +Please provide: + +1. Output from `contract-test-exploration` (or `enforce stage`) +2. Any CrossHair errors or warnings +3. Whether edge case was detected + +--- + +## Testing Checklist + +For each example, please provide: + +- [ ] **Command executed**: Exact command you ran +- [ ] **Full output**: Complete stdout and stderr +- [ ] **Exit code**: `echo $?` after command +- [ ] **Files created**: List of test files +- [ ] **Project bundle**: Location of `.specfact/projects//` if created +- [ ] **Issues found**: Any problems or unexpected behavior +- [ ] **Expected vs Actual**: Compare expected output with actual + +--- + +## Quick Test Script + +You can also run this script to set up all test cases at once: + +```bash +#!/bin/bash +# setup_all_tests.sh + +BASE_DIR="/tmp/specfact-integration-tests" +mkdir -p "$BASE_DIR" + +# Example 1 +mkdir -p "$BASE_DIR/example1_vscode" +cd "$BASE_DIR/example1_vscode" +cat > views.py << 'EOF' +def process_payment(request): + user = get_user(request.user_id) + payment = create_payment(user.id, request.amount) + send_notification(user.email, payment.id) + return {"status": "success"} +EOF + +# Example 2 +mkdir -p "$BASE_DIR/example2_cursor" +cd "$BASE_DIR/example2_cursor" +cat > src/pipeline.py << 'EOF' +def process_data(data: list[dict]) -> dict: + if not data: + return {"status": "empty", "count": 0} + filtered = [d for d in data if d is not None and d.get("value") is not None] + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } +EOF + +# Example 3 +mkdir -p "$BASE_DIR/example3_github_actions" +cd "$BASE_DIR/example3_github_actions" +cat > src/api.py << 'EOF' +def get_user_stats(user_id: str) -> dict: + stats = 42 + return stats +EOF + +# Example 4 +mkdir -p "$BASE_DIR/example4_precommit" +cd "$BASE_DIR/example4_precommit" +cat > src/legacy.py << 'EOF' +def process_order(order_id: str) -> dict: + return {"order_id": order_id, "status": "processed"} +EOF +cat > caller.py << 'EOF' +from legacy import process_order +result = process_order(order_id="123") +EOF + +# Example 5 +mkdir -p "$BASE_DIR/example5_agentic" +cd "$BASE_DIR/example5_agentic" +cat > src/validator.py << 'EOF' +def validate_and_calculate(data: dict) -> float: + value = data.get("value", 0) + divisor = data.get("divisor", 1) + return value / divisor +EOF + +echo "✅ All test cases created in $BASE_DIR" +``` + +--- + +## Next Steps + +1. **Run each example** following the steps above +2. **Capture output** for each test case +3. **Report results** so we can update the documentation with actual outputs +4. **Identify issues** if any commands don't work as expected + +--- + +## Questions to Answer + +For each example, please answer: + +1. Did the command execute successfully? +2. Was the expected violation/issue detected? +3. Did the output match the expected format? +4. Were there any errors or warnings? +5. What would you change in the documentation based on your testing? + +--- + +## Cleanup After Testing + +After completing all examples, you can clean up the test directories: + +### Option 1: Remove All Test Directories + +```bash +# Remove all test directories +rm -rf /tmp/specfact-integration-tests +``` + +### Option 2: Keep Test Directories for Reference + +If you want to keep the test directories for reference or future testing: + +```bash +# Just remove temporary files (keep structure) +find /tmp/specfact-integration-tests -name "*.pyc" -delete +find /tmp/specfact-integration-tests -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null +find /tmp/specfact-integration-tests -name ".ruff_cache" -type d -exec rm -rf {} + 2>/dev/null +``` + +### Option 3: Archive Test Results + +If you want to save the test results before cleanup: + +```bash +# Create archive of test results +cd /tmp +tar -czf specfact-integration-tests-$(date +%Y%m%d).tar.gz specfact-integration-tests/ + +# Then remove original +rm -rf specfact-integration-tests +``` + +**Note**: The `.specfact` directories contain plan bundles, enforcement configs, and reports that may be useful for reference. Consider archiving them if you want to keep the test results. + +--- + +## Validation Status Summary + +### Example 1: VS Code Integration - ✅ **FULLY VALIDATED** + +**Status**: Fully validated - workflow works, async detection works with Semgrep (available via `pip install semgrep`) + +**What's Validated**: + +- ✅ Plan bundle creation (`import from-code`) +- ✅ Plan enrichment (LLM adds features and stories) +- ✅ Plan review (identifies missing items) +- ✅ Story addition via CLI (`plan add-story`) +- ✅ Enforcement configuration (`enforce stage`) +- ✅ Enforcement blocking (`plan compare` blocks HIGH severity violations) + +**Async Detection Setup** (for full async pattern analysis): + +- ✅ Semgrep available via `pip install semgrep` +- ✅ Proper project structure (`src/` directory) - created by setup script +- ✅ Semgrep config at `tools/semgrep/async.yml` - copied by setup script + +**Test Results**: + +- Plan bundle: ✅ 1 feature, 4 stories (including `STORY-PAYMENT-ASYNC`) +- Enforcement: ✅ Blocks HIGH severity violations +- Async detection: ✅ Semgrep runs successfully (installed via `pip install semgrep`) + +**Conclusion**: Example 1 is **fully validated**. Semgrep is available via `pip install semgrep` and integrates seamlessly with SpecFact CLI. The enforcement workflow works end-to-end, and async blocking detection runs successfully when Semgrep is installed. The acceptance criteria in the plan bundle explicitly requires non-blocking notifications, and enforcement will block violations when comparing code against the plan. + +### Example 2: Cursor Integration - ✅ **FULLY VALIDATED** + +**Status**: Fully validated - workflow works, plan comparison detects deviations, enforcement blocks HIGH severity violations + +**What's Validated**: + +- ✅ Plan bundle creation (`import from-code`) +- ✅ Plan enrichment (LLM adds FEATURE-DATAPROCESSOR and 4 stories) +- ✅ Plan review (auto-enrichment adds target users, value hypothesis, feature acceptance criteria, enhanced story acceptance criteria) +- ✅ Enforcement configuration (`enforce stage` with BALANCED preset) +- ✅ Plan comparison (`plan compare` detects deviations) +- ✅ Enforcement blocking (`plan compare` blocks HIGH severity violations with exit code 1) + +**Test Results**: + +- Plan bundle: ✅ 1 feature (`FEATURE-DATAPROCESSOR`), 4 stories (including STORY-001: Process Data with None Handling) +- Enforcement: ✅ Configured with BALANCED preset (HIGH → BLOCK, MEDIUM → WARN, LOW → LOG) +- Plan comparison: ✅ Detects deviations and blocks HIGH severity violations +- Comparison reports: ✅ Generated at `.specfact/projects//reports/comparison/report-.md` + +**Conclusion**: Example 2 is **fully validated**. The regression prevention workflow works end-to-end. Plan comparison successfully detects deviations between enriched and original plans, and enforcement blocks HIGH severity violations as expected. The workflow demonstrates how SpecFact prevents regressions by detecting when code changes violate plan contracts. + +### Example 4: Pre-commit Hook Integration - ✅ **FULLY VALIDATED** + +**Status**: Fully validated - workflow works, pre-commit hook successfully blocks commits with breaking changes + +**What's Validated**: + +- ✅ Plan bundle creation (`import from-code`) +- ✅ Plan selection (`plan select` sets active plan) +- ✅ Enforcement configuration (`enforce stage` with BALANCED preset) +- ✅ Pre-commit hook setup (imports code, then compares) +- ✅ Plan comparison (`plan compare --code-vs-plan` finds both plans correctly) +- ✅ Enforcement blocking (blocks HIGH severity violations with exit code 1) + +**Test Results**: + +- Plan creation: ✅ `import from-code ` creates project bundle at `.specfact/projects//` (modular structure) +- Plan selection: ✅ `plan select` sets active plan correctly +- Plan comparison: ✅ `plan compare --code-vs-plan` finds: + - Manual plan: Active plan (set via `plan select`) + - Auto plan: Latest `auto-derived` project bundle (`.specfact/projects/auto-derived/`) +- Deviation detection: ✅ Detects deviations (1 HIGH, 2 LOW in test case) +- Enforcement: ✅ Blocks commit when HIGH severity deviations found +- Pre-commit hook: ✅ Exits with code 1, blocking the commit + +**Key Findings**: + +- ✅ `import from-code` should use bundle name "auto-derived" so `plan compare --code-vs-plan` can find it +- ✅ `plan select` is the recommended way to set the baseline plan (cleaner than copying to `main.bundle.yaml`) +- ✅ Pre-commit hook workflow: `import from-code` → `plan compare --code-vs-plan` works correctly +- ✅ Enforcement configuration is respected (HIGH → BLOCK based on preset) + +**Conclusion**: Example 4 is **fully validated**. The pre-commit hook integration works end-to-end. The hook successfully imports current code, compares it against the active plan, and blocks commits when HIGH severity deviations are detected. The workflow demonstrates how SpecFact prevents breaking changes from being committed locally, before they reach CI/CD. + +### Example 3: GitHub Actions Integration - ✅ **FULLY VALIDATED** + +**Status**: Fully validated in production CI/CD - workflow runs `specfact repro` in GitHub Actions and successfully blocks PRs when validation fails + +**What's Validated**: + +- ✅ GitHub Actions workflow configuration (uses `pip install specfact-cli`, includes `specfact repro`) +- ✅ `specfact repro` command execution in CI/CD environment +- ✅ Validation checks execution (linting, type checking, Semgrep, CrossHair) +- ✅ Type checking error detection (basedpyright detects type mismatches) +- ✅ PR blocking when validation fails (exit code 1 blocks merge) + +**Production Validation**: + +- ✅ Workflow actively running in [specfact-cli PR #28](https://github.com/nold-ai/specfact-cli/pull/28) +- ✅ Type checking errors detected and reported in CI/CD +- ✅ Validation suite completes successfully (linting, Semgrep pass, type checking detects issues) +- ✅ Workflow demonstrates CI/CD integration working as expected + +**Test Results** (from production CI/CD): + +- Linting (ruff): ✅ PASSED +- Async patterns (Semgrep): ✅ PASSED +- Type checking (basedpyright): ✗ FAILED (detects type errors correctly) +- Contract exploration (CrossHair): ⊘ SKIPPED (signature analysis limitation, non-blocking) + +**Conclusion**: Example 3 is **fully validated** in production CI/CD. The GitHub Actions workflow successfully runs `specfact repro` and blocks PRs when validation fails. The workflow demonstrates how SpecFact integrates into CI/CD pipelines to prevent bad code from merging. + +### Example 5: Agentic Workflows - ⏳ **PENDING VALIDATION** + +Example 5 follows a similar workflow and should be validated using the same approach: + +1. Create test files +2. Create plan bundle (`import from-code`) +3. Enrich plan (if needed) +4. Review plan and add missing items +5. Configure enforcement +6. Test enforcement + +--- + +**Ready to start?** Begin with Example 1 and work through each one systematically. Share the outputs as you complete each test! diff --git a/_site_test/examples/integration-showcases/integration-showcases.md b/_site_test/examples/integration-showcases/integration-showcases.md new file mode 100644 index 0000000..072289a --- /dev/null +++ b/_site_test/examples/integration-showcases/integration-showcases.md @@ -0,0 +1,564 @@ +# Integration Showcases: Bugs Fixed via CLI Integrations + +> **Core USP**: SpecFact CLI works seamlessly with VS Code, Cursor, GitHub Actions, and any agentic workflow. This document showcases real examples of bugs that were caught and fixed through different integration points. + +--- + +## Overview + +SpecFact CLI works with your existing tools—no new platform to learn. These examples show real bugs that were caught through different integrations. + +### What You Need + +- **Python 3.11+** installed +- **SpecFact CLI** installed (via `pip install specfact-cli` or `uvx specfact-cli@latest`) +- **Your favorite IDE** (VS Code, Cursor, etc.) or CI/CD system + +### Integration Points Covered + +- ✅ **VS Code** - Catch bugs before you commit +- ✅ **Cursor** - Validate AI suggestions automatically +- ✅ **GitHub Actions** - Block bad code from merging +- ✅ **Pre-commit Hooks** - Check code locally before pushing +- ✅ **AI Assistants** - Find edge cases AI might miss + +--- + +## Example 1: VS Code Integration - Caught Async Bug Before Commit + +### The Problem + +A developer was refactoring a legacy Django view to use async/await. The code looked correct but had a subtle async bug that would cause race conditions in production. + +**Original Code**: + +```python +# views.py - Legacy Django view being modernized +def process_payment(request): + user = get_user(request.user_id) + payment = create_payment(user.id, request.amount) + send_notification(user.email, payment.id) # ⚠️ Blocking call in async context + return JsonResponse({"status": "success"}) +``` + +### The Integration + +**Setup** (one-time, takes 2 minutes): + +1. Install SpecFact CLI: `pip install specfact-cli` or use `uvx specfact-cli@latest` +2. Add a pre-commit hook to check code before commits: + +```bash +# .git/hooks/pre-commit +#!/bin/sh +specfact --no-banner enforce stage --preset balanced +``` + +**What This Does**: Runs SpecFact validation automatically before every commit. If it finds issues, the commit is blocked. + +### What SpecFact Caught + +```bash +🚫 Contract Violation: Blocking I/O in async context + File: views.py:45 + Function: process_payment + Issue: send_notification() is a blocking call + Severity: HIGH + Fix: Use async version or move to background task +``` + +### The Fix + +```python +# Fixed code +async def process_payment(request): + user = await get_user_async(request.user_id) + payment = await create_payment_async(user.id, request.amount) + await send_notification_async(user.email, payment.id) # ✅ Async call + return JsonResponse({"status": "success"}) +``` + +### Result + +- ✅ **Bug caught**: Before commit (local validation) +- ✅ **Time saved**: Prevented production race condition +- ✅ **Integration**: VS Code + pre-commit hook +- ✅ **No platform required**: Pure CLI integration + +--- + +## Example 2: Cursor Integration - Prevented Regression During Refactoring + +### The Problem + +A developer was using Cursor AI to refactor a legacy data pipeline. The AI assistant suggested changes that looked correct but would have broken a critical edge case. + +**Original Code**: + +```python +# pipeline.py - Legacy data processing +def process_data(data: list[dict]) -> dict: + if not data: + return {"status": "empty", "count": 0} + + # Critical: handles None values in data + filtered = [d for d in data if d is not None and d.get("value") is not None] + + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } +``` + +### The Integration + +**Setup** (one-time): + +1. Install SpecFact CLI: `pip install specfact-cli` +2. Initialize SpecFact in your project: `specfact init` +3. Use the slash command in Cursor: `/specfact.03-review legacy-api` + +**What This Does**: When Cursor suggests code changes, SpecFact checks if they break existing contracts or introduce regressions. + +### What SpecFact Caught + +The AI suggested removing the `None` check, which would have broken the edge case: + +```bash +🚫 Contract Violation: Missing None check + File: pipeline.py:12 + Function: process_data + Issue: Suggested code removes None check, breaking edge case + Severity: HIGH + Contract: Must handle None values in input data + Fix: Keep None check or add explicit contract +``` + +### The Fix + +```python +# AI suggestion rejected, kept original with contract +@icontract.require(lambda data: isinstance(data, list)) +@icontract.ensure(lambda result: result["count"] >= 0) +def process_data(data: list[dict]) -> dict: + if not data: + return {"status": "empty", "count": 0} + + # Contract enforces None handling + filtered = [d for d in data if d is not None and d.get("value") is not None] + + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } +``` + +### Result + +- ✅ **Regression prevented**: Edge case preserved +- ✅ **AI validation**: Cursor suggestions validated before acceptance +- ✅ **Integration**: Cursor + SpecFact CLI +- ✅ **Contract enforcement**: Runtime guarantees maintained + +--- + +## Example 3: GitHub Actions Integration - Blocked Merge with Type Error + +### The Problem + +A developer submitted a PR that added a new feature but introduced a type mismatch that would cause runtime errors. + +**PR Code**: + +```python +# api.py - New endpoint added +def get_user_stats(user_id: str) -> dict: + user = User.objects.get(id=user_id) + stats = calculate_stats(user) # Returns int, not dict + return stats # ⚠️ Type mismatch: int vs dict +``` + +### The Integration + +**Setup** (add to your GitHub repository): + +Create `.github/workflows/specfact-enforce.yml`: + +```yaml +name: SpecFact Validation + +on: + pull_request: + branches: [main] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + cache: "pip" + - name: Install SpecFact CLI + run: pip install specfact-cli + - name: Configure Enforcement + run: specfact --no-banner enforce stage --preset balanced + - name: Run SpecFact Validation + run: specfact --no-banner repro --repo . --budget 90 +``` + +**What This Does**: + +1. **Configure Enforcement**: Sets enforcement mode to `balanced` (blocks HIGH severity violations, warns on MEDIUM) +2. **Run Validation**: Executes `specfact repro` which runs validation checks: + + **Always runs**: + - Linting (ruff) - checks code style and common Python issues + - Type checking (basedpyright) - validates type annotations and type safety + + **Conditionally runs** (only if present): + - Contract exploration (CrossHair) - if `src/` directory exists (symbolic execution to find counterexamples) + - Async patterns (semgrep) - if `tools/semgrep/async.yml` exists (requires semgrep installed) + - Property tests (pytest) - if `tests/contracts/` directory exists + - Smoke tests (pytest) - if `tests/smoke/` directory exists + + **Note**: `repro` does not perform runtime contract validation (checking `@icontract` decorators at runtime). It runs static analysis tools (linting, type checking) and symbolic execution (CrossHair) for contract exploration. + +**Expected Output**: + +```text +Running validation suite... +Repository: . +Time budget: 90s + +⠙ Running validation checks... + +Validation Results + + Check Summary +┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓ +┃ Check ┃ Tool ┃ Status ┃ Duration ┃ +┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩ +│ Linting (ruff) │ ruff │ ✗ FAILED │ 0.03s │ +│ Type checking (basedpyright) │ basedpyright │ ✗ FAILED │ 1.12s │ +│ Contract exploration (CrossHair) │ crosshair │ ✗ FAILED │ 0.58s │ +└──────────────────────────────────┴──────────────┴──────────┴──────────┘ + +Summary: + Total checks: 3 + Passed: 0 + Failed: 3 + Total duration: 1.73s + +Report written to: .specfact/projects//reports/enforcement/report-.yaml + +✗ Some validations failed +``` + +If SpecFact finds violations that trigger enforcement rules, the workflow fails (exit code 1) and the PR is blocked from merging. + +### What SpecFact Caught + +```bash +🚫 Contract Violation: Return type mismatch + File: api.py:45 + Function: get_user_stats + Issue: Function returns int, but contract requires dict + Severity: HIGH + Contract: @ensure(lambda result: isinstance(result, dict)) + Fix: Return dict with stats, not raw int +``` + +### The Fix + +```python +# Fixed code +@icontract.ensure(lambda result: isinstance(result, dict)) +def get_user_stats(user_id: str) -> dict: + user = User.objects.get(id=user_id) + stats_value = calculate_stats(user) + return {"stats": stats_value} # ✅ Returns dict +``` + +### Result + +- ✅ **Merge blocked**: PR failed CI check +- ✅ **Type safety**: Runtime type error prevented +- ✅ **Integration**: GitHub Actions + SpecFact CLI +- ✅ **Automated**: No manual review needed + +--- + +## Example 4: Pre-commit Hook - Caught Undocumented Breaking Change + +### The Problem + +A developer modified a legacy function's signature without updating callers, breaking backward compatibility. + +**Modified Code**: + +```python +# legacy.py - Function signature changed +def process_order(order_id: str, user_id: str) -> dict: # ⚠️ Added required user_id + # ... implementation +``` + +**Caller Code** (not updated): + +```python +# caller.py - Still using old signature +result = process_order(order_id="123") # ⚠️ Missing user_id +``` + +### The Integration + +**Setup** (one-time): + +1. Configure enforcement: `specfact --no-banner enforce stage --preset balanced` +2. Add pre-commit hook: + +```bash +# .git/hooks/pre-commit +#!/bin/sh +# Import current code to create a new plan for comparison +# Use bundle name "auto-derived" so plan compare --code-vs-plan can find it +specfact --no-banner import from-code auto-derived --repo . --output-format yaml > /dev/null 2>&1 + +# Compare: uses active plan (set via plan select) as manual, latest auto-derived plan as auto +specfact --no-banner plan compare --code-vs-plan +``` + +**What This Does**: Before you commit, SpecFact imports your current code to create a new plan, then compares it against the baseline plan. If it detects breaking changes with HIGH severity, the commit is blocked (based on enforcement configuration). + +### What SpecFact Caught + +```bash +🚫 Contract Violation: Breaking change detected + File: legacy.py:12 + Function: process_order + Issue: Signature changed from (order_id) to (order_id, user_id) + Severity: HIGH + Impact: 3 callers will break + Fix: Make user_id optional or update all callers +``` + +### The Fix + +```python +# Fixed: Made user_id optional to maintain backward compatibility +def process_order(order_id: str, user_id: str | None = None) -> dict: + if user_id is None: + # Legacy behavior + user_id = get_default_user_id() + # ... implementation +``` + +### Result + +- ✅ **Breaking change caught**: Before commit +- ✅ **Backward compatibility**: Maintained +- ✅ **Integration**: Pre-commit hook + SpecFact CLI +- ✅ **Local validation**: No CI delay + +--- + +## Example 5: Agentic Workflow - CrossHair Found Edge Case + +### The Problem + +A developer was using an AI coding assistant to add input validation. The code looked correct but had an edge case that would cause division by zero. + +**AI-Generated Code**: + +```python +# validator.py - AI-generated validation +def validate_and_calculate(data: dict) -> float: + value = data.get("value", 0) + divisor = data.get("divisor", 1) + return value / divisor # ⚠️ Edge case: divisor could be 0 +``` + +### The Integration + +**Setup** (when using AI assistants): + +1. Install SpecFact CLI: `pip install specfact-cli` +2. Use the slash command in your AI assistant: `/specfact-contract-test-exploration` + +**What This Does**: Uses mathematical proof (not guessing) to find edge cases that AI might miss, like division by zero or None handling issues. + +### What SpecFact Caught + +**CrossHair Symbolic Execution** discovered the edge case: + +```bash +🔍 CrossHair Exploration: Found counterexample + File: validator.py:5 + Function: validate_and_calculate + Issue: Division by zero when divisor=0 + Counterexample: {"value": 10, "divisor": 0} + Severity: HIGH + Fix: Add divisor != 0 check +``` + +### The Fix + +```python +# Fixed with contract +@icontract.require(lambda data: data.get("divisor", 1) != 0) +def validate_and_calculate(data: dict) -> float: + value = data.get("value", 0) + divisor = data.get("divisor", 1) + return value / divisor # ✅ Contract ensures divisor != 0 +``` + +### Result + +- ✅ **Edge case found**: Mathematical proof, not LLM guess +- ✅ **Symbolic execution**: CrossHair discovered counterexample +- ✅ **Integration**: Agentic workflow + SpecFact CLI +- ✅ **Formal verification**: Deterministic, not probabilistic + +--- + +## Integration Patterns + +### Pattern 1: Pre-commit Validation + +**Best For**: Catching issues before they enter the repository + +**Setup**: + +```bash +# .git/hooks/pre-commit +#!/bin/sh +specfact --no-banner enforce stage --preset balanced +``` + +**Benefits**: + +- ✅ Fast feedback (runs locally) +- ✅ Prevents bad commits +- ✅ Works with any IDE or editor + +### Pattern 2: CI/CD Integration + +**Best For**: Automated validation in pull requests + +**Setup** (GitHub Actions example): + +```yaml +- name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + cache: "pip" +- name: Install SpecFact CLI + run: pip install specfact-cli +- name: Configure Enforcement + run: specfact --no-banner enforce stage --preset balanced +- name: Run SpecFact Validation + run: specfact --no-banner repro --repo . --budget 90 +``` + +**Benefits**: + +- ✅ Blocks merges automatically +- ✅ Same checks for everyone on the team +- ✅ No manual code review needed for these issues + +### Pattern 3: IDE Integration + +**Best For**: Real-time validation while coding + +**Setup** (VS Code example): + +```json +// .vscode/tasks.json +{ + "label": "SpecFact Validate", + "type": "shell", + "command": "specfact --no-banner enforce stage --preset balanced" +} +``` + +**Benefits**: + +- ✅ Immediate feedback as you code +- ✅ Works with any editor (VS Code, Cursor, etc.) +- ✅ No special extension needed + +### Pattern 4: AI Assistant Integration + +**Best For**: Validating AI-generated code suggestions + +**Setup**: + +1. Install SpecFact: `pip install specfact-cli` +2. Initialize: `specfact init` (creates slash commands for your IDE) +3. Use slash commands like `/specfact.03-review legacy-api` in Cursor or GitHub Copilot + +**Benefits**: + +- ✅ Catches bugs in AI suggestions +- ✅ Prevents AI from making mistakes +- ✅ Uses formal proof, not guessing + +--- + +## Key Takeaways + +### ✅ What Makes These Integrations Work + +1. **CLI-First Design**: Works with any tool, no platform lock-in +2. **Standard Exit Codes**: Integrates with any CI/CD system +3. **Fast Execution**: < 10 seconds for most validations +4. **Formal Guarantees**: Runtime contracts + symbolic execution +5. **Zero Configuration**: Works out of the box + +### ✅ Bugs Caught That Other Tools Missed + +- **Async bugs**: Blocking calls in async context +- **Type mismatches**: Runtime type errors +- **Breaking changes**: Backward compatibility issues +- **Edge cases**: Division by zero, None handling +- **Contract violations**: Missing preconditions/postconditions + +### ✅ Integration Benefits + +- **VS Code**: Pre-commit validation, no extension needed +- **Cursor**: AI suggestion validation +- **GitHub Actions**: Automated merge blocking +- **Pre-commit**: Local validation before commits +- **Agentic Workflows**: Formal verification of AI code + +--- + +## Next Steps + +1. **Try an Integration**: Pick your IDE/CI and add SpecFact validation +2. **Share Your Example**: Document bugs you catch via integrations +3. **Contribute**: Add integration examples to this document + +--- + +## Related Documentation + +- **[Getting Started](../../getting-started/README.md)** - Installation and setup +- **[IDE Integration](../../guides/ide-integration.md)** - Set up integrations +- **[Use Cases](../../guides/use-cases.md)** - More real-world scenarios +- **[Dogfooding Example](../dogfooding-specfact-cli.md)** - SpecFact analyzing itself + +--- + +**Remember**: SpecFact CLI's core USP is **seamless integration** into your existing workflow. These examples show how different integrations caught real bugs that other tools missed. Start with one integration, then expand as you see value. diff --git a/_site_test/examples/integration-showcases/setup-integration-tests.sh b/_site_test/examples/integration-showcases/setup-integration-tests.sh new file mode 100755 index 0000000..02d5d57 --- /dev/null +++ b/_site_test/examples/integration-showcases/setup-integration-tests.sh @@ -0,0 +1,363 @@ +#!/bin/bash +# setup-integration-tests.sh +# Quick setup script for integration showcase testing +# +# Usage: +# From specfact-cli repo root: +# ./docs/examples/integration-showcases/setup-integration-tests.sh +# +# Or from this directory: +# ./setup-integration-tests.sh +# +# Prerequisites: +# - Python 3.11+ (required by specfact-cli) +# - pip install specfact-cli (for interactive AI assistant mode) +# - pip install semgrep (optional, for async pattern detection in Example 1) +# - specfact init (one-time IDE setup) +# +# This script creates test cases in /tmp/specfact-integration-tests/ for +# validating the integration showcase examples. +# +# Project Structure Created: +# - All examples use src/ directory for source code (required for specfact repro) +# - tests/ directory created for test files +# - tools/semgrep/ directory created for Example 1 (Semgrep async config copied if available) + +set -e + +BASE_DIR="/tmp/specfact-integration-tests" +echo "📁 Creating test directory: $BASE_DIR" +mkdir -p "$BASE_DIR" +cd "$BASE_DIR" + +# Example 1: VS Code Integration +echo "📝 Setting up Example 1: VS Code Integration" +mkdir -p example1_vscode/src example1_vscode/tests example1_vscode/tools/semgrep +cd example1_vscode +git init > /dev/null 2>&1 || true + +# Copy Semgrep config if available from specfact-cli repo +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)" +if [ -f "$REPO_ROOT/src/specfact_cli/resources/semgrep/async.yml" ]; then + cp "$REPO_ROOT/src/specfact_cli/resources/semgrep/async.yml" tools/semgrep/ 2>/dev/null || true + echo "✅ Copied Semgrep async config" +elif [ -f "$REPO_ROOT/tools/semgrep/async.yml" ]; then + cp "$REPO_ROOT/tools/semgrep/async.yml" tools/semgrep/ 2>/dev/null || true + echo "✅ Copied Semgrep async config" +else + echo "⚠️ Semgrep config not found - creating minimal config" + # Create minimal Semgrep config for async detection + cat > tools/semgrep/async.yml << 'SEMGREP_EOF' +rules: + - id: blocking-io-in-async + pattern: | + def $FUNC(...): + ... + $CALL(...) + message: Blocking I/O call in potentially async context + languages: [python] + severity: ERROR +SEMGREP_EOF + echo "✅ Created minimal Semgrep async config" +fi + +# Check if semgrep is installed, offer to install if not +if ! command -v semgrep &> /dev/null; then + echo "⚠️ Semgrep not found in PATH" + echo " To enable async pattern detection, install Semgrep:" + echo " pip install semgrep" + echo " (This is optional - async detection will be skipped if Semgrep is not installed)" +else + echo "✅ Semgrep found: $(semgrep --version | head -1)" +fi + +cat > src/views.py << 'EOF' +# views.py - Legacy Django view with async bug +"""Payment processing views for legacy Django application.""" + +from typing import Dict, Any + +class PaymentView: + """Legacy Django view being modernized to async. + + This view handles payment processing operations including + creating payments, checking status, and cancelling payments. + """ + + def process_payment(self, request): + """Process payment with blocking I/O call. + + This method processes a payment request and sends a notification. + The send_notification call is blocking and should be async. + """ + user = get_user(request.user_id) + payment = create_payment(user.id, request.amount) + send_notification(user.email, payment.id) # ⚠️ Blocking call in async context + return {"status": "success"} + + def get_payment_status(self, payment_id: str) -> dict: + """Get payment status by ID. + + Returns the current status of a payment. + """ + return {"id": payment_id, "status": "pending"} + + def cancel_payment(self, payment_id: str) -> dict: + """Cancel a payment. + + Cancels an existing payment and returns the updated status. + """ + return {"id": payment_id, "status": "cancelled"} + + def create_payment(self, user_id: str, amount: float) -> dict: + """Create a new payment. + + Creates a new payment record for the specified user and amount. + """ + return {"id": "123", "user_id": user_id, "amount": amount} +EOF +echo "✅ Example 1 setup complete (src/views.py created)" +cd .. + +# Example 2: Cursor Integration +echo "📝 Setting up Example 2: Cursor Integration" +mkdir -p example2_cursor/src example2_cursor/tests +cd example2_cursor +git init > /dev/null 2>&1 || true +cat > src/pipeline.py << 'EOF' +# pipeline.py - Legacy data processing +class DataProcessor: + """Processes data with None value handling. + + This processor handles data transformation and validation, + with special attention to None value handling for legacy data. + """ + + def process_data(self, data: list[dict]) -> dict: + """Process data with critical None handling. + + Processes a list of data dictionaries, filtering out None values + and calculating totals. Critical for handling legacy data formats. + """ + if not data: + return {"status": "empty", "count": 0} + + # Critical: handles None values in data + filtered = [d for d in data if d is not None and d.get("value") is not None] + + if len(filtered) == 0: + return {"status": "no_valid_data", "count": 0} + + return { + "status": "success", + "count": len(filtered), + "total": sum(d["value"] for d in filtered) + } + + def validate_data(self, data: list[dict]) -> bool: + """Validate data structure. + + Checks if data is a non-empty list of dictionaries. + """ + return isinstance(data, list) and len(data) > 0 + + def transform_data(self, data: list[dict]) -> list[dict]: + """Transform data format. + + Transforms data by adding a processed flag to each item. + """ + return [{"processed": True, **item} for item in data if item] + + def filter_data(self, data: list[dict], key: str) -> list[dict]: + """Filter data by key. + + Returns only items that contain the specified key. + """ + return [item for item in data if key in item] +EOF +echo "✅ Example 2 setup complete (src/pipeline.py created)" +cd .. + +# Example 3: GitHub Actions Integration +echo "📝 Setting up Example 3: GitHub Actions Integration" +mkdir -p example3_github_actions/src example3_github_actions/tests +cd example3_github_actions +git init > /dev/null 2>&1 || true +cat > src/api.py << 'EOF' +# api.py - New endpoint with type mismatch +class UserAPI: + """User API endpoints. + + Provides REST API endpoints for user management operations + including profile retrieval, statistics, and updates. + """ + + def get_user_stats(self, user_id: str) -> dict: + """Get user statistics. + + Returns user statistics as a dictionary. Note: This method + has a type mismatch bug - returns int instead of dict. + """ + # Simulate: calculate_stats returns int, not dict + stats = 42 # Returns int, not dict + return stats # ⚠️ Type mismatch: int vs dict + + def get_user_profile(self, user_id: str) -> dict: + """Get user profile information. + + Retrieves the complete user profile for the given user ID. + """ + return {"id": user_id, "name": "John Doe"} + + def update_user(self, user_id: str, data: dict) -> dict: + """Update user information. + + Updates user information with the provided data. + """ + return {"id": user_id, "updated": True, **data} + + def create_user(self, user_data: dict) -> dict: + """Create a new user. + + Creates a new user with the provided data. + """ + return {"id": "new-123", **user_data} +EOF +echo "✅ Example 3 setup complete (src/api.py created)" +cd .. + +# Example 4: Pre-commit Hook +echo "📝 Setting up Example 4: Pre-commit Hook" +mkdir -p example4_precommit/src example4_precommit/tests +cd example4_precommit +git init > /dev/null 2>&1 || true +cat > src/legacy.py << 'EOF' +# legacy.py - Original function +class OrderProcessor: + """Processes orders. + + Handles order processing operations including order creation, + status retrieval, and order updates. + """ + + def process_order(self, order_id: str) -> dict: + """Process an order. + + Processes an order and returns its status. + """ + return {"order_id": order_id, "status": "processed"} + + def get_order(self, order_id: str) -> dict: + """Get order details. + + Retrieves order information by order ID. + """ + return {"id": order_id, "items": []} + + def update_order(self, order_id: str, data: dict) -> dict: + """Update an order. + + Updates order information with the provided data. + """ + return {"id": order_id, "updated": True, **data} +EOF +cat > src/caller.py << 'EOF' +# caller.py - Uses legacy function +from legacy import OrderProcessor + +processor = OrderProcessor() +result = processor.process_order(order_id="123") +EOF +# Create pre-commit hook (enforcement must be configured separately) +mkdir -p .git/hooks +cat > .git/hooks/pre-commit << 'EOF' +#!/bin/sh +specfact --no-banner plan compare --code-vs-plan +EOF +chmod +x .git/hooks/pre-commit +echo "⚠️ Pre-commit hook created. Remember to run 'specfact enforce stage --preset balanced' before testing." +echo "✅ Example 4 setup complete (src/legacy.py, src/caller.py, pre-commit hook created)" +cd .. + +# Example 5: Agentic Workflow +echo "📝 Setting up Example 5: Agentic Workflow" +mkdir -p example5_agentic/src example5_agentic/tests +cd example5_agentic +git init > /dev/null 2>&1 || true +cat > src/validator.py << 'EOF' +# validator.py - AI-generated validation with edge case +class DataValidator: + """Validates and calculates data. + + Provides validation and calculation utilities for data processing, + with support for various data types and formats. + """ + + def validate_and_calculate(self, data: dict) -> float: + """Validate data and perform calculation. + + Validates input data and performs division calculation. + Note: This method has an edge case bug - divisor could be 0. + """ + value = data.get("value", 0) + divisor = data.get("divisor", 1) + return value / divisor # ⚠️ Edge case: divisor could be 0 + + def validate_input(self, data: dict) -> bool: + """Validate input data structure. + + Checks if data is a valid dictionary with required fields. + """ + return isinstance(data, dict) and "value" in data + + def calculate_total(self, values: list[float]) -> float: + """Calculate total from list of values. + + Sums all values in the provided list. + """ + return sum(values) if values else 0.0 + + def check_data_quality(self, data: dict) -> bool: + """Check data quality. + + Performs quality checks on the provided data dictionary. + """ + return isinstance(data, dict) and len(data) > 0 +EOF +echo "✅ Example 5 setup complete (src/validator.py created)" +cd .. + +echo "" +echo "✅ All test cases created in $BASE_DIR" +echo "" +echo "📋 Test directories:" +echo " 1. example1_vscode - VS Code async bug detection" +echo " 2. example2_cursor - Cursor regression prevention" +echo " 3. example3_github_actions - GitHub Actions type error" +echo " 4. example4_precommit - Pre-commit breaking change" +echo " 5. example5_agentic - Agentic workflow edge case" +echo "" +echo "⚠️ IMPORTANT: For Interactive AI Assistant Usage" +echo "" +echo " Before using slash commands in your IDE, you need to:" +echo " 1. Install SpecFact via pip: pip install specfact-cli" +echo " 2. Initialize IDE integration (one-time per project):" +echo " cd $BASE_DIR/example1_vscode" +echo " specfact init" +echo "" +echo " This sets up prompt templates so slash commands work." +echo "" +echo "🚀 Next steps:" +echo " 1. Follow the testing guide: integration-showcases-testing-guide.md (in this directory)" +echo " 2. Install SpecFact: pip install specfact-cli" +echo " 3. Initialize IDE: cd $BASE_DIR/example1_vscode && specfact init" +echo " 4. Open test file in IDE and use slash command: /specfact.01-import legacy-api --repo ." +echo " (Interactive mode automatically uses IDE workspace - --repo . optional)" +echo "" +echo "📚 Documentation:" +echo " - Testing Guide: docs/examples/integration-showcases/integration-showcases-testing-guide.md" +echo " - Quick Reference: docs/examples/integration-showcases/integration-showcases-quick-reference.md" +echo " - Showcases: docs/examples/integration-showcases/integration-showcases.md" +echo "" + diff --git a/_site_test/feed/index.xml b/_site_test/feed/index.xml new file mode 100644 index 0000000..0f51227 --- /dev/null +++ b/_site_test/feed/index.xml @@ -0,0 +1 @@ +Jekyll2026-01-05T02:07:30+01:00https://nold-ai.github.io/specfact-cli/feed/SpecFact CLI DocumentationComplete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. \ No newline at end of file diff --git a/_site_test/getting-started/README.md b/_site_test/getting-started/README.md new file mode 100644 index 0000000..7377db6 --- /dev/null +++ b/_site_test/getting-started/README.md @@ -0,0 +1,54 @@ +# Getting Started with SpecFact CLI + +Welcome to SpecFact CLI! This guide will help you get started in under 60 seconds. + +## Installation + +Choose your preferred installation method: + +- **[Installation Guide](installation.md)** - All installation options (uvx, pip, Docker, GitHub Actions) +- **[Enhanced Analysis Dependencies](../installation/enhanced-analysis-dependencies.md)** - Optional dependencies for graph-based analysis (pyan3, syft, bearer, graphviz) + +## Quick Start + +### Your First Command + +**For Legacy Code Modernization** (Recommended): + +```bash +# CLI-only mode (works with uvx, no installation needed) +uvx specfact-cli@latest import from-code my-project --repo . + +# Interactive AI Assistant mode (requires pip install + specfact init) +# See First Steps guide for IDE integration setup +``` + +**For New Projects**: + +```bash +# CLI-only mode (bundle name as positional argument) +uvx specfact-cli@latest plan init my-project --interactive + +# Interactive AI Assistant mode (recommended for better results) +# Requires: pip install specfact-cli && specfact init +``` + +**Note**: Interactive AI Assistant mode provides better feature detection and semantic understanding, but requires `pip install specfact-cli` and IDE setup. CLI-only mode works immediately with `uvx` but may show 0 features for simple test cases. + +### Modernizing Legacy Code? + +**New to brownfield modernization?** See our **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** for a complete walkthrough of modernizing legacy Python code with SpecFact CLI. + +## Next Steps + +- 📖 **[Installation Guide](installation.md)** - Install SpecFact CLI +- 📖 **[First Steps](first-steps.md)** - Step-by-step first commands +- 📖 **[Tutorial: Using SpecFact with OpenSpec or Spec-Kit](tutorial-openspec-speckit.md)** ⭐ **NEW** - Complete beginner-friendly tutorial +- 📖 **[Use Cases](../guides/use-cases.md)** - See real-world examples +- 📖 **[Command Reference](../reference/commands.md)** - Learn all available commands + +## Need Help? + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_test/getting-started/first-steps/index.html b/_site_test/getting-started/first-steps/index.html new file mode 100644 index 0000000..a1f32a1 --- /dev/null +++ b/_site_test/getting-started/first-steps/index.html @@ -0,0 +1,609 @@ + + + + + + + +Your First Steps with SpecFact CLI | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Your First Steps with SpecFact CLI

+ +

This guide walks you through your first commands with SpecFact CLI, with step-by-step explanations.

+ +

Before You Start

+ +
    +
  • Install SpecFact CLI (if not already installed)
    • +
  • Python 3.11+ required: Check with python3 --version
    • +
  • Choose your scenario below
    • +
+ +

Installation Options:

+ +
    +
  • Quick start (CLI-only): uvx specfact-cli@latest --help (no installation needed)
    • +
  • Better results (Interactive): pip install specfact-cli + specfact init (recommended for legacy code)
    • +
+ +
+ +

Scenario 1: Modernizing Legacy Code ⭐ PRIMARY

+ +

Goal: Reverse engineer existing code into documented specs

+ +

Time: < 5 minutes

+ +

Step 1: Analyze Your Legacy Codebase

+ +

Option A: CLI-only Mode (Quick start, works with uvx):

+ +
uvx specfact-cli@latest import from-code my-project --repo .
+
+ +

Option B: Interactive AI Assistant Mode (Recommended for better results):

+ +
# Step 1: Install SpecFact CLI
+pip install specfact-cli
+
+# Step 2: Navigate to your project
+cd /path/to/your/project
+
+# Step 3: Initialize IDE integration (one-time)
+specfact init
+
+# Step 4: Use slash command in IDE chat
+/specfact.01-import legacy-api --repo .
+# Or let the AI assistant prompt you for bundle name
+
+ +

What happens:

+ +
    +
  • Auto-detects project context: Language, framework, existing specs, and configuration
    • +
  • Analyzes all Python files in your repository
    • +
  • Extracts features, user stories, and business logic from code
    • +
  • Generates dependency graphs
    • +
  • Creates plan bundle with extracted specs
    • +
  • Suggests next steps: Provides actionable commands based on your project state
    • +
+ +

💡 Tip: Use --help or -h for standard help, or --help-advanced (alias: -ha) to see all options including advanced configuration.

+ +

Example output (Interactive mode - better results):

+ +
✅ Analyzed 47 Python files
+✅ Extracted 23 features
+✅ Generated 112 user stories
+⏱️  Completed in 8.2 seconds
+
+ +

Example output (CLI-only mode - may show 0 features for simple cases):

+ +
✅ Analyzed 3 Python files
+✅ Extracted 0 features  # ⚠️ AST-based analysis may miss features in simple code
+✅ Generated 0 user stories
+⏱️  Completed in 2.1 seconds
+
+ +

Note: CLI-only mode uses AST-based analysis which may show 0 features for simple test cases. Interactive AI Assistant mode provides better semantic understanding and feature detection.

+ +

Step 2: Review Extracted Specs

+ +
# Review the extracted bundle using CLI commands
+specfact plan review my-project
+
+# Or get structured findings for analysis
+specfact plan review my-project --list-findings --findings-format json
+
+ +

Review the auto-generated plan to understand what SpecFact discovered about your codebase.

+ +

Note: Use CLI commands to interact with bundles. The bundle structure is managed by SpecFact CLI - use commands like plan review, plan add-feature, plan update-feature to work with bundles, not direct file editing.

+ +

💡 Tip: If you plan to sync with Spec-Kit later, the import command will suggest generating a bootstrap constitution. You can also run it manually:

+ +
specfact sdd constitution bootstrap --repo .
+
+ +

Step 3: Find and Fix Gaps

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Analyze and validate your codebase
+specfact repro --verbose
+
+ +

What happens:

+ +
    +
  • repro setup configures CrossHair for contract exploration (one-time setup)
    • +
  • repro runs the full validation suite (linting, type checking, contracts, tests)
    • +
  • Identifies gaps and issues in your codebase
    • +
  • Generates enforcement reports that downstream tools (like generate fix-prompt) can use
    • +
+ +

Step 4: Use AI to Fix Gaps (New in 0.17+)

+ +
# Generate AI-ready prompt to fix a specific gap
+specfact generate fix-prompt GAP-001 --bundle my-project
+
+# Generate AI-ready prompt to add tests
+specfact generate test-prompt src/auth/login.py
+
+ +

What happens:

+ +
    +
  • Creates structured prompt file in .specfact/prompts/
    • +
  • Copy prompt to your AI IDE (Cursor, Copilot, Claude)
    • +
  • AI generates the fix
    • +
  • Validate with SpecFact enforcement
    • +
+ +

Step 5: Enforce Contracts

+ +
# Start in shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# Validate the codebase
+specfact enforce sdd --bundle my-project
+
+ +

See Brownfield Engineer Guide for complete workflow.

+ +
+ +

Scenario 2: Starting a New Project (Alternative)

+ +

Goal: Create a plan before writing code

+ +

Time: 5-10 minutes

+ +

Step 1: Initialize a Plan

+ +
specfact plan init my-project --interactive
+
+ +

What happens:

+ +
    +
  • Creates .specfact/ directory structure
    • +
  • Prompts you for project title and description
    • +
  • Creates modular project bundle at .specfact/projects/my-project/
    • +
+ +

Example output:

+ +
📋 Initializing new development plan...
+
+Enter project title: My Awesome Project
+Enter project description: A project to demonstrate SpecFact CLI
+
+✅ Plan initialized successfully!
+📁 Project bundle: .specfact/projects/my-project/
+
+ +

Step 2: Add Your First Feature

+ +
specfact plan add-feature \
+  --bundle my-project \
+  --key FEATURE-001 \
+  --title "User Authentication" \
+  --outcomes "Users can login securely"
+
+ +

What happens:

+ +
    +
  • Adds a new feature to your project bundle
    • +
  • Creates a feature with key FEATURE-001
    • +
  • Sets the title and outcomes
    • +
+ +

Step 3: Add Stories to the Feature

+ +
specfact plan add-story \
+  --bundle my-project \
+  --feature FEATURE-001 \
+  --title "As a user, I can login with email and password" \
+  --acceptance "Login form validates input" \
+  --acceptance "User is redirected after successful login"
+
+ +

What happens:

+ +
    +
  • Adds a user story to the feature
    • +
  • Defines acceptance criteria
    • +
  • Links the story to the feature
    • +
+ +

Step 4: Validate the Plan

+ +
specfact repro
+
+ +

What happens:

+ +
    +
  • Validates the plan bundle structure
    • +
  • Checks for required fields
    • +
  • Reports any issues
    • +
+ +

Expected output:

+ +
✅ Plan validation passed
+📊 Features: 1
+📊 Stories: 1
+
+ +

Next Steps

+ + + +
+ +

Scenario 3: Migrating from Spec-Kit (Secondary)

+ +

Goal: Add automated enforcement to Spec-Kit project

+ +

Time: 15-30 minutes

+ +

Step 1: Preview Migration

+ +
specfact import from-bridge \
+  --repo ./my-speckit-project \
+  --adapter speckit \
+  --dry-run
+
+ +

What happens:

+ +
    +
  • Analyzes your Spec-Kit project structure
    • +
  • Detects Spec-Kit artifacts (specs, plans, tasks, constitution)
    • +
  • Shows what will be imported
    • +
  • Does not modify anything (dry-run mode)
    • +
+ +

Example output:

+ +
🔍 Analyzing Spec-Kit project...
+✅ Found .specify/ directory (modern format)
+✅ Found specs/001-user-authentication/spec.md
+✅ Found specs/001-user-authentication/plan.md
+✅ Found specs/001-user-authentication/tasks.md
+✅ Found .specify/memory/constitution.md
+
+📊 Migration Preview:
+  - Will create: .specfact/projects/<bundle-name>/ (modular project bundle)
+  - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected)
+  - Will convert: Spec-Kit features → SpecFact Feature models
+  - Will convert: Spec-Kit user stories → SpecFact Story models
+  
+🚀 Ready to migrate (use --write to execute)
+
+ +

Step 2: Execute Migration

+ +
specfact import from-bridge \
+  --repo ./my-speckit-project \
+  --adapter speckit \
+  --write
+
+ +

What happens:

+ +
    +
  • Imports Spec-Kit artifacts into SpecFact format using bridge architecture
    • +
  • Creates .specfact/ directory structure
    • +
  • Converts Spec-Kit features and stories to SpecFact models
    • +
  • Creates modular project bundle at .specfact/projects/<bundle-name>/
    • +
  • Preserves all information
    • +
+ +

Step 3: Review Generated Bundle

+ +
# Review the imported bundle
+specfact plan review <bundle-name>
+
+# Check bundle status
+specfact plan select
+
+ +

What was created:

+ +
    +
  • Modular project bundle at .specfact/projects/<bundle-name>/ with multiple aspect files
    • +
  • .specfact/protocols/workflow.protocol.yaml - FSM definition (if protocol detected)
    • +
  • .specfact/gates/config.yaml - Quality gates configuration
    • +
+ +

Note: Use CLI commands (plan review, plan add-feature, etc.) to interact with bundles. Do not edit .specfact files directly.

+ +

Step 4: Set Up Bidirectional Sync (Optional)

+ +

Keep Spec-Kit and SpecFact synchronized:

+ +
# Generate constitution if missing (auto-suggested during sync)
+specfact sdd constitution bootstrap --repo .
+
+# One-time bidirectional sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Continuous watch mode
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+ +

What happens:

+ +
    +
  • Constitution bootstrap: Auto-generates constitution from repository analysis (if missing or minimal)
    • +
  • Syncs changes between Spec-Kit and SpecFact
    • +
  • Bidirectional: changes in either direction are synced
    • +
  • Watch mode: continuously monitors for changes
    • +
  • Auto-generates all Spec-Kit fields: When syncing from SpecFact to Spec-Kit, all required fields (frontmatter, INVSEST, Constitution Check, Phases, Technology Stack, Story mappings) are automatically generated - ready for /speckit.analyze without manual editing
    • +
+ +

Step 5: Enable Enforcement

+ +
# Start in shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# After stabilization, enable warnings
+specfact enforce stage --preset balanced
+
+# For production, enable strict mode
+specfact enforce stage --preset strict
+
+ +

What happens:

+ +
    +
  • Configures enforcement rules
    • +
  • Sets severity levels (HIGH, MEDIUM, LOW)
    • +
  • Defines actions (BLOCK, WARN, LOG)
    • +
+ +

Next Steps for Scenario 3 (Secondary)

+ + + +
+ +

Common Questions

+ +

What if I make a mistake?

+ +

All commands support --dry-run or --shadow-only flags to preview changes without modifying files.

+ +

Can I undo changes?

+ +

Yes! SpecFact CLI creates backups and you can use Git to revert changes:

+ +
git status
+git diff
+git restore .specfact/
+
+ +

How do I learn more?

+ + + +
+ +

Happy building! 🚀

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/getting-started/installation/index.html b/_site_test/getting-started/installation/index.html new file mode 100644 index 0000000..90d829b --- /dev/null +++ b/_site_test/getting-started/installation/index.html @@ -0,0 +1,710 @@ + + + + + + + +Getting Started with SpecFact CLI | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Getting Started with SpecFact CLI

+ +

This guide will help you get started with SpecFact CLI in under 60 seconds.

+ +
+

Primary Use Case: SpecFact CLI is designed for brownfield code modernization - reverse-engineering existing codebases into documented specs with runtime contract enforcement. See First Steps for brownfield workflows.

+
+ +

Installation

+ +

Option 1: uvx (CLI-only Mode)

+ +

No installation required - run directly:

+ +
uvx specfact-cli@latest --help
+
+ +

Best for: Quick testing, CI/CD, one-off commands

+ +

Limitations: CLI-only mode uses AST-based analysis which may show 0 features for simple test cases. For better results, use interactive AI Assistant mode (Option 2).

+ +

Option 2: pip (Interactive AI Assistant Mode)

+ +

Required for: IDE integration, slash commands, enhanced feature detection

+ +
# System-wide
+pip install specfact-cli
+
+# User install
+pip install --user specfact-cli
+
+# Virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
+pip install specfact-cli
+
+ +

Optional: For enhanced graph-based dependency analysis, see Enhanced Analysis Dependencies.

+ +

After installation: Set up IDE integration for interactive mode:

+ +
# Navigate to your project
+cd /path/to/your/project
+
+# Initialize IDE integration (one-time per project)
+specfact init
+
+# Or specify IDE explicitly
+specfact init --ide cursor
+specfact init --ide vscode
+
+# Install required packages for contract enhancement
+specfact init --install-deps
+
+# Initialize for specific IDE and install dependencies
+specfact init --ide cursor --install-deps
+
+ +

Note: Interactive mode requires Python 3.11+ and automatically uses your IDE workspace (no --repo . needed in slash commands).

+ +

Option 3: Container

+ +
# Docker
+docker run --rm -v $(pwd):/workspace ghcr.io/nold-ai/specfact-cli:latest --help
+
+# Podman
+podman run --rm -v $(pwd):/workspace ghcr.io/nold-ai/specfact-cli:latest --help
+
+ +

Option 4: GitHub Action

+ +

Create .github/workflows/specfact.yml:

+ +
name: SpecFact CLI Validation
+
+on:
+  pull_request:
+    branches: [main, dev]
+  push:
+    branches: [main, dev]
+  workflow_dispatch:
+    inputs:
+      budget:
+        description: "Time budget in seconds"
+        required: false
+        default: "90"
+        type: string
+      mode:
+        description: "Enforcement mode (block, warn, log)"
+        required: false
+        default: "block"
+        type: choice
+        options:
+          - block
+          - warn
+          - log
+
+jobs:
+  specfact-validation:
+    name: Contract Validation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      checks: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install SpecFact CLI
+        run: pip install specfact-cli
+
+      - name: Set up CrossHair Configuration
+        run: specfact repro setup
+
+      - name: Run Contract Validation
+        run: specfact repro --verbose --budget 90
+
+      - name: Generate PR Comment
+        if: github.event_name == 'pull_request'
+        run: python -m specfact_cli.utils.github_annotations
+        env:
+          SPECFACT_REPORT_PATH: .specfact/projects/<bundle-name>/reports/enforcement/report-*.yaml
+
+ +

First Steps

+ +

Operational Modes

+ +

SpecFact CLI supports two operational modes:

+ +
    +
  • CLI-only Mode (uvx): Fast, AST-based analysis for automation +
      +
    • Works immediately with uvx specfact-cli@latest
      • +
    • No installation required
      • +
    • May show 0 features for simple test cases (AST limitations)
      • +
    • Best for: CI/CD, quick testing, one-off commands
      • +
    +
    • +
  • Interactive AI Assistant Mode (pip + specfact init): Enhanced semantic understanding +
      +
    • Requires pip install specfact-cli and specfact init
      • +
    • Better feature detection and semantic understanding
      • +
    • IDE integration with slash commands
      • +
    • Automatically uses IDE workspace (no --repo . needed)
      • +
    • Best for: Development, legacy code analysis, complex projects
      • +
    +
    • +
+ +

Mode Selection:

+ +
# CLI-only mode (uvx - no installation)
+uvx specfact-cli@latest import from-code my-project --repo .
+
+# Interactive mode (pip + specfact init - recommended)
+# After: pip install specfact-cli && specfact init
+# Then use slash commands in IDE: /specfact.01-import legacy-api --repo .
+
+ +

Note: Mode is auto-detected based on whether specfact command is available and IDE integration is set up.

+ +

For Greenfield Projects

+ +

Start a new contract-driven project:

+ +
specfact plan init --interactive
+
+ +

This will guide you through creating:

+ +
    +
  • Initial project idea and narrative
    • +
  • Product themes and releases
    • +
  • First features and stories
    • +
  • Protocol state machine
    • +
+ +

With IDE Integration (Interactive AI Assistant Mode):

+ +
# Step 1: Install SpecFact CLI
+pip install specfact-cli
+
+# Step 2: Navigate to your project
+cd /path/to/your/project
+
+# Step 3: Initialize IDE integration (one-time per project)
+specfact init
+# Or specify IDE: specfact init --ide cursor
+
+# Step 4: Use slash command in IDE chat
+/specfact.02-plan init legacy-api
+# Or use other plan operations: /specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth"
+
+ +

Important:

+ +
    +
  • Interactive mode automatically uses your IDE workspace
    • +
  • Slash commands use numbered format: /specfact.01-import, /specfact.02-plan, etc.
    • +
  • Commands are numbered for natural workflow progression (01-import → 02-plan → 03-review → 04-sdd → 05-enforce → 06-sync)
    • +
  • No --repo . parameter needed in interactive mode (uses workspace automatically)
    • +
  • The AI assistant will prompt you for bundle names and other inputs if not provided
    • +
+ +

See IDE Integration Guide for detailed setup instructions.

+ +

For Spec-Kit Migration

+ +

Convert an existing GitHub Spec-Kit project:

+ +
# Preview what will be migrated
+specfact import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run
+
+# Execute migration (one-time import)
+specfact import from-bridge \
+  --adapter speckit \
+  --repo ./my-speckit-project \
+  --write
+
+# Ongoing bidirectional sync (after migration)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Bidirectional Sync:

+ +

Keep Spec-Kit and SpecFact artifacts synchronized:

+ +
# One-time sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Continuous watch mode
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Note: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in AdapterRegistry and accessed via specfact sync bridge --adapter <adapter-name>, making the architecture extensible for future tool integrations.

+ +

For Brownfield Projects

+ +

Analyze existing code to generate specifications.

+ +

With IDE Integration (Interactive AI Assistant Mode - Recommended):

+ +
# Step 1: Install SpecFact CLI
+pip install specfact-cli
+
+# Step 2: Navigate to your project
+cd /path/to/your/project
+
+# Step 3: Initialize IDE integration (one-time per project)
+specfact init
+# Or specify IDE: specfact init --ide cursor
+
+# Step 4: Use slash command in IDE chat
+/specfact.01-import legacy-api
+# Or let the AI assistant prompt you for bundle name and other options
+
+ +

Important for IDE Integration:

+ +
    +
  • Interactive mode automatically uses your IDE workspace (no --repo . needed in interactive mode)
    • +
  • Slash commands use numbered format: /specfact.01-import, /specfact.02-plan, etc. (numbered for workflow ordering)
    • +
  • Commands follow natural progression: 01-import → 02-plan → 03-review → 04-sdd → 05-enforce → 06-sync
    • +
  • The AI assistant will prompt you for bundle names and confidence thresholds if not provided
    • +
  • Better feature detection than CLI-only mode (semantic understanding vs AST-only)
    • +
  • Do NOT use --mode copilot with IDE slash commands - IDE integration automatically provides enhanced prompts
    • +
+ +

CLI-Only Mode (Alternative - for CI/CD or when IDE integration is not available):

+ +
# Analyze repository (CI/CD mode - fast)
+specfact import from-code my-project \
+  --repo ./my-project \
+  --shadow-only \
+  --report analysis.md
+
+# Analyze with CoPilot mode (enhanced prompts - CLI only, not for IDE)
+specfact --mode copilot import from-code my-project \
+  --repo ./my-project \
+  --confidence 0.7 \
+  --report analysis.md
+
+# Review generated plan
+cat analysis.md
+
+ +

Note: --mode copilot is for CLI usage only. When using IDE integration, use slash commands (e.g., /specfact.01-import) instead - IDE integration automatically provides enhanced prompts without needing the --mode copilot flag.

+ +

See IDE Integration Guide for detailed setup instructions.

+ +

Sync Changes:

+ +

Keep plan artifacts updated as code changes:

+ +
# One-time sync
+specfact sync repository --repo . --target .specfact
+
+# Continuous watch mode
+specfact sync repository --repo . --watch
+
+ +

Next Steps

+ +
    +
  1. Explore Commands: See Command Reference
    2. +
  2. Learn Use Cases: Read Use Cases
    3. +
  3. Understand Architecture: Check Architecture
    4. +
  4. Set Up IDE Integration: See IDE Integration Guide
    5. +
+ +

Quick Tips

+ +
    +
  • Python 3.11+ required: SpecFact CLI requires Python 3.11 or higher
    • +
  • Start in shadow mode: Use --shadow-only to observe without blocking
    • +
  • Use dry-run: Always preview with --dry-run before writing changes
    • +
  • Check reports: Generate reports with --report <filename> for review
    • +
  • Progressive enforcement: Start with minimal, move to balanced, then strict
    • +
  • CLI-only vs Interactive: Use uvx for quick testing, pip install + specfact init for better results
    • +
  • IDE integration: Use specfact init to set up slash commands in IDE (requires pip install)
    • +
  • Slash commands: Use numbered format /specfact.01-import, /specfact.02-plan, etc. (numbered for workflow ordering)
    • +
  • Global flags: Place --no-banner before the command: specfact --no-banner <command>
    • +
  • Bridge adapter sync: Use sync bridge --adapter <adapter-name> for external tool integration (Spec-Kit, OpenSpec, GitHub, etc.)
    • +
  • Repository sync: Use sync repository for code change tracking
    • +
  • Semgrep (optional): Install pip install semgrep for async pattern detection in specfact repro
    • +
+ +
+ +

Supported Project Management Tools

+ +

SpecFact CLI automatically detects and works with the following Python project management tools. No configuration needed - it detects your project’s environment manager automatically!

+ +

Automatic Detection

+ +

When you run SpecFact CLI commands on a repository, it automatically:

+ +
    +
  1. Detects the environment manager by checking for configuration files
    2. +
  2. Detects source directories (src/, lib/, or package name from pyproject.toml)
    3. +
  3. Builds appropriate commands using the detected environment manager
    4. +
  4. Checks tool availability and skips with clear messages if tools are missing
    5. +
+ +

Supported Tools

+ +

1. hatch - Modern Python project manager

+ +
    +
  • Detection: [tool.hatch] section in pyproject.toml
    • +
  • Command prefix: hatch run
    • +
  • Example: hatch run pytest tests/
    • +
  • Use case: Modern Python projects using hatch for build and dependency management
    • +
+ +

2. poetry - Dependency management and packaging

+ +
    +
  • Detection: [tool.poetry] section in pyproject.toml or poetry.lock file
    • +
  • Command prefix: poetry run
    • +
  • Example: poetry run pytest tests/
    • +
  • Use case: Projects using Poetry for dependency management
    • +
+ +

3. uv - Fast Python package installer and resolver

+ +
    +
  • Detection: [tool.uv] section in pyproject.toml, uv.lock, or uv.toml file
    • +
  • Command prefix: uv run
    • +
  • Example: uv run pytest tests/
    • +
  • Use case: Projects using uv for fast package management
    • +
+ +

4. pip - Standard Python package installer

+ +
    +
  • Detection: requirements.txt or setup.py file
    • +
  • Command prefix: Direct tool invocation (no prefix)
    • +
  • Example: pytest tests/
    • +
  • Use case: Traditional Python projects using pip and virtual environments
    • +
+ +

Detection Priority

+ +

SpecFact CLI checks in this order:

+ +
    +
  1. pyproject.toml for tool sections ([tool.hatch], [tool.poetry], [tool.uv])
    2. +
  2. Lock files (poetry.lock, uv.lock, uv.toml)
    3. +
  3. Fallback to requirements.txt or setup.py for pip-based projects
    4. +
+ +

Source Directory Detection

+ +

SpecFact CLI automatically detects source directories:

+ +
    +
  • Standard layouts: src/, lib/
    • +
  • Package name: Extracted from pyproject.toml (e.g., my-package → my_package/)
    • +
  • Root-level: Falls back to root directory if no standard layout found
    • +
+ +

Example: Working with Different Projects

+ +
# Hatch project
+cd /path/to/hatch-project
+specfact repro --repo .  # Automatically uses "hatch run" for tools
+
+# Poetry project
+cd /path/to/poetry-project
+specfact repro --repo .  # Automatically uses "poetry run" for tools
+
+# UV project
+cd /path/to/uv-project
+specfact repro --repo .  # Automatically uses "uv run" for tools
+
+# Pip project
+cd /path/to/pip-project
+specfact repro --repo .  # Uses direct tool invocation
+
+ +

External Repository Support

+ +

SpecFact CLI works seamlessly on external repositories without requiring:

+ +
    +
  • ❌ SpecFact CLI adoption
    • +
  • ❌ Specific project structures
    • +
  • ❌ Manual configuration
    • +
  • ❌ Tool installation in global environment
    • +
+ +

All commands automatically adapt to the target repository’s environment and structure.

+ +

This makes SpecFact CLI ideal for:

+ +
    +
  • OSS validation workflows - Validate external open-source projects
    • +
  • Multi-project environments - Work with different project structures
    • +
  • CI/CD pipelines - Validate any Python project without setup
    • +
+ +

Common Commands

+ +
# Check version
+specfact --version
+
+# Get help
+specfact --help
+specfact <command> --help
+
+# Initialize plan (bundle name as positional argument)
+specfact plan init my-project --interactive
+
+# Add feature
+specfact plan add-feature --key FEATURE-001 --title "My Feature"
+
+# Validate everything
+specfact repro
+
+# Set enforcement level
+specfact enforce stage --preset balanced
+
+ +

Getting Help

+ + + +

Development Setup

+ +

For contributors:

+ +
# Clone repository
+git clone https://github.com/nold-ai/specfact-cli.git
+cd specfact-cli
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+hatch run contract-test-full
+
+# Format code
+hatch run format
+
+# Run linters
+hatch run lint
+
+ +

See CONTRIBUTING.md for detailed contribution guidelines.

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/getting-started/tutorial-openspec-speckit.md b/_site_test/getting-started/tutorial-openspec-speckit.md new file mode 100644 index 0000000..65c1dc9 --- /dev/null +++ b/_site_test/getting-started/tutorial-openspec-speckit.md @@ -0,0 +1,686 @@ +# Tutorial: Using SpecFact with OpenSpec or Spec-Kit + +> **Complete step-by-step guide for new users** +> Learn how to use SpecFact CLI with OpenSpec or Spec-Kit for brownfield code modernization + +**Time**: 15-30 minutes | **Prerequisites**: Python 3.11+, basic command-line knowledge + +**Note**: This tutorial assumes you're using `specfact` command directly. + +--- + +## 🎯 What You'll Learn + +By the end of this tutorial, you'll know how to: + +- ✅ Install and set up SpecFact CLI +- ✅ Use SpecFact with OpenSpec for change tracking and DevOps integration +- ✅ Use SpecFact with Spec-Kit for greenfield + brownfield workflows +- ✅ Sync between tools using bridge adapters +- ✅ Export change proposals to GitHub Issues +- ✅ Track implementation progress automatically + +--- + +## 📋 Prerequisites + +Before starting, ensure you have: + +- **Python 3.11+** installed (`python3 --version`) +- **Git** installed (`git --version`) +- **Command-line access** (Terminal, PowerShell, or WSL) +- **A GitHub account** (for DevOps integration examples) + +**Optional but recommended:** + +- **OpenSpec CLI** installed (`npm install -g @fission-ai/openspec@latest`) - for OpenSpec workflows +- **VS Code or Cursor** - for IDE integration + +--- + +## 🚀 Quick Start: Choose Your Path + +### Path A: Using SpecFact with OpenSpec + +**Best for**: Teams using OpenSpec for specification management and change tracking + +**Use case**: You have OpenSpec change proposals and want to: + +- Export them to GitHub Issues +- Track implementation progress +- Sync OpenSpec specs with code analysis + +👉 **[Jump to OpenSpec Tutorial](#path-a-using-specfact-with-openspec)** + +### Path B: Using SpecFact with Spec-Kit + +**Best for**: Teams using GitHub Spec-Kit for interactive specification authoring + +**Use case**: You have Spec-Kit specs and want to: + +- Add runtime contract enforcement +- Enable team collaboration with shared plans +- Sync Spec-Kit artifacts with SpecFact bundles + +👉 **[Jump to Spec-Kit Tutorial](#path-b-using-specfact-with-spec-kit)** + +--- + +## Path A: Using SpecFact with OpenSpec + +### Step 1: Install SpecFact CLI + +**Option 1: Quick Start (CLI-only)** + +```bash +# No installation needed - works immediately +uvx specfact-cli@latest --help +``` + +**Option 2: Full Installation (Recommended)** + +```bash +# Install SpecFact CLI +pip install specfact-cli + +# Verify installation +specfact --version +``` + +**Expected output**: `specfact-cli, version 0.22.0` + +### Step 2: Set Up Your Project + +**If you already have an OpenSpec project:** + +```bash +# Navigate to your OpenSpec project +cd /path/to/your-openspec-project + +# Verify OpenSpec structure exists +ls openspec/ +# Should show: specs/, changes/, project.md, AGENTS.md +``` + +**If you don't have OpenSpec yet:** + +```bash +# Install OpenSpec CLI +npm install -g @fission-ai/openspec@latest + +# Initialize OpenSpec in your project +cd /path/to/your-project +openspec init + +# This creates openspec/ directory structure +``` + +### Step 3: Analyze Your Legacy Code with SpecFact + +**First, extract specs from your existing code:** + +```bash +# Analyze legacy codebase +cd /path/to/your-openspec-project +specfact import from-code legacy-api --repo . + +# Expected output: +# 🔍 Analyzing codebase... +# ✅ Analyzed X Python files +# ✅ Extracted Y features +# ✅ Generated Z user stories +# ⏱️ Completed in X seconds +# 📁 Project bundle: .specfact/projects/legacy-api/ +# ✅ Import complete! +``` + +**What this does:** + +- Analyzes your Python codebase +- Extracts features and user stories automatically +- Creates a SpecFact project bundle (`.specfact/projects/legacy-api/`) + +**Note**: If using `hatch run specfact`, run from the specfact-cli directory: +```bash +cd /path/to/specfact-cli +hatch run specfact import from-code legacy-api --repo /path/to/your-openspec-project +``` + +### Step 4: Create an OpenSpec Change Proposal + +**Create a change proposal in OpenSpec:** + +```bash +# Create change proposal directory +mkdir -p openspec/changes/modernize-api + +# Create proposal.md +cat > openspec/changes/modernize-api/proposal.md << 'EOF' +# Change: Modernize Legacy API + +## Why +Legacy API needs modernization for better performance and maintainability. + +## What Changes +- Refactor API endpoints +- Add contract validation +- Update database schema + +## Impact +- Affected specs: api, database +- Affected code: src/api/, src/db/ +EOF + +# Create tasks.md +cat > openspec/changes/modernize-api/tasks.md << 'EOF' +## Implementation Tasks + +- [ ] Refactor API endpoints +- [ ] Add contract validation +- [ ] Update database schema +- [ ] Add tests +EOF +``` + +### Step 5: Export OpenSpec Proposal to GitHub Issues + +**Export your change proposal to GitHub Issues:** + +```bash +# Export OpenSpec change proposal to GitHub Issues +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo + +# Expected output: +# ✅ Found change proposal: modernize-api +# ✅ Created GitHub Issue #123: Modernize Legacy API +# ✅ Updated proposal.md with issue tracking +``` + +**What this does:** + +- Reads your OpenSpec change proposal +- Creates a GitHub Issue from the proposal +- Updates the proposal with issue tracking information +- Enables progress tracking + +### Step 6: Track Implementation Progress + +**As you implement changes, track progress automatically:** + +```bash +# Make commits with change ID in commit message +cd /path/to/source-code-repo +git commit -m "feat: modernize-api - refactor endpoints [change:modernize-api]" + +# Track progress (detects commits and adds comments to GitHub Issue) +cd /path/to/openspec-repo +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --track-code-changes \ + --repo . \ + --code-repo /path/to/source-code-repo + +# Expected output: +# ✅ Detected commit: feat: modernize-api - refactor endpoints +# ✅ Added progress comment to Issue #123 +``` + +**Note**: Use `--track-code-changes` flag to enable automatic code change detection. The `--code-repo` option specifies where the source code repository is located (if different from the OpenSpec repo). + +### Step 7: Sync OpenSpec Change Proposals to SpecFact + +**Import OpenSpec change proposals into SpecFact:** + +```bash +# Sync OpenSpec change proposals to SpecFact (read-only) +cd /path/to/openspec-repo +specfact sync bridge --adapter openspec --mode read-only \ + --bundle legacy-api \ + --repo . + +# Expected output: +# ✅ Syncing OpenSpec artifacts (read-only) +# ✅ Found 1 change proposal: modernize-api +# ✅ Synced to SpecFact bundle: legacy-api +# ✅ Change tracking updated +``` + +**What this does:** + +- Reads OpenSpec change proposals from `openspec/changes/` +- Syncs them to SpecFact change tracking +- Enables alignment reports (planned feature) + +**Note**: Currently, OpenSpec adapter sync may show an error about `discover_features` method. This is a known limitation in v0.22.0. The adapter successfully loads change proposals, but alignment report generation may fail. This will be fixed in a future release. + +### Step 8: Add Runtime Contract Enforcement + +**Add contracts to prevent regressions:** + +```bash +# Configure enforcement (global setting, no --bundle or --repo needed) +cd /path/to/your-project +specfact enforce stage --preset balanced + +# Expected output: +# Setting enforcement mode: balanced +# Enforcement Mode: BALANCED +# ┏━━━━━━━━━━┳━━━━━━━━┓ +# ┃ Severity ┃ Action ┃ +# ┡━━━━━━━━╇━━━━━━━━┩ +# │ HIGH │ BLOCK │ +# │ MEDIUM │ WARN │ +# │ LOW │ LOG │ +# ✅ Quality gates configured +``` + +**What this does:** + +- Configures quality gates (global setting for the repository) +- Enables contract enforcement +- Prepares CI/CD integration + +**Note**: `enforce stage` is a global setting and doesn't take `--bundle` or `--repo` options. It configures enforcement for the current repository. + +### Step 9: Archive Completed Change + +**When implementation is complete, archive the change:** + +```bash +# Archive completed change in OpenSpec +openspec archive modernize-api --yes + +# Expected output: +# ✅ Change archived successfully +# ✅ Specs updated in openspec/specs/ +``` + +--- + +## Path B: Using SpecFact with Spec-Kit + +### Step 1: Install SpecFact CLI + +**Option 1: Quick Start (CLI-only)** + +```bash +# No installation needed +uvx specfact-cli@latest --help +``` + +**Option 2: Full Installation (Recommended)** + +```bash +# Install SpecFact CLI +pip install specfact-cli + +# Verify installation +specfact --version +``` + +### Step 2: Set Up Your Spec-Kit Project + +**If you already have a Spec-Kit project:** + +```bash +# Navigate to your Spec-Kit project +cd /path/to/your-speckit-project + +# Verify Spec-Kit structure exists +ls specs/ +# Should show: [###-feature-name]/ directories with spec.md, plan.md, tasks.md +``` + +**If you don't have Spec-Kit yet:** + +```bash +# Spec-Kit is integrated into GitHub Copilot +# Use slash commands in Copilot chat: +# /speckit.specify --feature "User Authentication" +# /speckit.plan --feature "User Authentication" +# /speckit.tasks --feature "User Authentication" +``` + +### Step 3: Preview Spec-Kit Import + +**See what will be imported (safe - no changes):** + +```bash +# Preview import +specfact import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run + +# Expected output: +# 🔍 Analyzing Spec-Kit project via bridge adapter... +# ✅ Found .specify/ directory (modern format) +# ✅ Found specs/001-user-authentication/spec.md +# ✅ Found specs/001-user-authentication/plan.md +# ✅ Found specs/001-user-authentication/tasks.md +# ✅ Found .specify/memory/constitution.md +# +# 📊 Migration Preview: +# - Will create: .specfact/projects// (modular project bundle) +# - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected) +# - Will create: .specfact/gates/config.yaml +# - Will convert: Spec-Kit features → SpecFact Feature models +# - Will convert: Spec-Kit user stories → SpecFact Story models +# +# 🚀 Ready to migrate (use --write to execute) +``` + +### Step 4: Import Spec-Kit Project + +**Import your Spec-Kit project to SpecFact:** + +```bash +# Execute import +specfact import from-bridge \ + --adapter speckit \ + --repo ./my-speckit-project \ + --write + +# Expected output: +# ✅ Parsed Spec-Kit artifacts +# ✅ Generated SpecFact bundle: .specfact/projects// +# ✅ Created quality gates config +# ✅ Preserved Spec-Kit artifacts (original files untouched) +``` + +**What this does:** + +- Parses Spec-Kit artifacts (spec.md, plan.md, tasks.md, constitution.md) +- Generates SpecFact project bundle +- Creates quality gates configuration +- Preserves your original Spec-Kit files + +### Step 5: Review Generated Bundle + +**Review what was created:** + +```bash +# Review plan bundle (bundle name is positional argument, not --bundle) +# IMPORTANT: Must be in the project directory where .specfact/ exists +cd /path/to/your-speckit-project +specfact plan review + +# Note: Bundle name is typically "main" for Spec-Kit imports +# Check actual bundle name: ls .specfact/projects/ + +# Expected output: +# ✅ Features: 5 +# ✅ Stories: 23 +# ✅ Plan bundle reviewed successfully +``` + +**Note**: +- `plan review` takes the bundle name as a positional argument (not `--bundle`) +- It uses the current directory to find `.specfact/projects/` (no `--repo` option) +- You must be in the project directory where the bundle was created + +### Step 6: Enable Bidirectional Sync + +**Keep Spec-Kit and SpecFact in sync:** + +```bash +# One-time sync (bundle name is typically "main" for Spec-Kit imports) +cd /path/to/my-speckit-project +specfact sync bridge --adapter speckit --bundle main --repo . --bidirectional + +# Continuous watch mode (recommended for team collaboration) +specfact sync bridge --adapter speckit --bundle main --repo . --bidirectional --watch --interval 5 + +# Expected output: +# ✅ Detected speckit repository +# ✅ Constitution found and validated +# ✅ Detected SpecFact structure +# ✅ No conflicts detected +# Sync Summary (Bidirectional): +# - speckit → SpecFact: Updated 0, Added 0 features +# - SpecFact → speckit: No features to convert +``` + +**What this does:** + +- **Spec-Kit → SpecFact**: New specs automatically imported +- **SpecFact → Spec-Kit**: Changes synced back to Spec-Kit format +- **Team collaboration**: Multiple developers can work together + +**Note**: Replace `main` with your actual bundle name if different. Check with `ls .specfact/projects/` after import. + +### Step 7: Continue Using Spec-Kit Interactively + +**Keep using Spec-Kit slash commands - sync happens automatically:** + +```bash +# In GitHub Copilot chat: +/speckit.specify --feature "Payment Processing" +/speckit.plan --feature "Payment Processing" +/speckit.tasks --feature "Payment Processing" + +# SpecFact automatically syncs (if watch mode enabled) +# → Detects changes in specs/[###-feature-name]/ +# → Imports new spec.md, plan.md, tasks.md +# → Updates .specfact/projects// aspect files +``` + +### Step 8: Add Runtime Contract Enforcement + +**Add contracts to prevent regressions:** + +```bash +# Configure enforcement (global setting, no --bundle or --repo needed) +cd /path/to/my-speckit-project +specfact enforce stage --preset balanced + +# Expected output: +# Setting enforcement mode: balanced +# Enforcement Mode: BALANCED +# ┏━━━━━━━━━━┳━━━━━━━━┓ +# ┃ Severity ┃ Action ┃ +# ┡━━━━━━━━━━╇━━━━━━━━┩ +# │ HIGH │ BLOCK │ +# │ MEDIUM │ WARN │ +# │ LOW │ LOG │ +# ✅ Quality gates configured +``` + +**Note**: `enforce stage` is a global setting and doesn't take `--bundle` or `--repo` options. + +### Step 9: Detect Code vs Plan Drift + +**Compare intended design vs actual implementation:** + +```bash +# Compare code vs plan (use --bundle to specify bundle name) +# IMPORTANT: Must be in the project directory where .specfact/ exists +cd /path/to/my-speckit-project +specfact plan compare --code-vs-plan --bundle + +# Note: Bundle name is typically "main" for Spec-Kit imports +# Check actual bundle name: ls .specfact/projects/ + +# Expected output: +# ✅ Comparing intended design vs actual implementation +# ✅ Found 3 deviations +# ✅ Auto-derived plans from code analysis +``` + +**What this does:** + +- Compares Spec-Kit plans (what you planned) vs code (what's implemented) +- Identifies deviations automatically +- Helps catch drift between design and code + +**Note**: +- `plan compare` takes `--bundle` as an option (not positional) +- It uses the current directory to find bundles (no `--repo` option) +- You must be in the project directory where the bundle was created + +--- + +## 🎓 Key Concepts + +### Bridge Adapters + +**What are bridge adapters?** + +Bridge adapters are plugin-based connectors that sync between SpecFact and external tools (OpenSpec, Spec-Kit, GitHub Issues, etc.). + +**Available adapters:** + +- `openspec` - OpenSpec integration (read-only sync, v0.22.0+) +- `speckit` - Spec-Kit integration (bidirectional sync) +- `github` - GitHub Issues integration (export-only) + +**How to use:** + +```bash +# View available adapters (shown in help text) +specfact sync bridge --help + +# Use an adapter +specfact sync bridge --adapter --mode --bundle --repo . +``` + +**Note**: Adapters are listed in the help text. There's no `--list-adapters` option, but adapters are shown when you use `--help` or when an adapter is not found (error message shows available adapters). + +### Sync Modes + +**Available sync modes:** + +- `read-only` - Import from external tool (no modifications) +- `export-only` - Export to external tool (no imports) +- `bidirectional` - Two-way sync (read and write) +- `unidirectional` - One-way sync (Spec-Kit → SpecFact only) + +**Which mode to use:** + +- **OpenSpec**: Use `read-only` (v0.22.0+) or `export-only` (GitHub Issues) +- **Spec-Kit**: Use `bidirectional` for team collaboration +- **GitHub Issues**: Use `export-only` for DevOps integration + +--- + +## 🐛 Troubleshooting + +### Issue: "Adapter not found" + +**Solution:** + +```bash +# View available adapters in help text +specfact sync bridge --help + +# Or check error message when adapter is not found (shows available adapters) +# Should show: openspec, speckit, github, generic-markdown +``` + +### Issue: "No change proposals found" + +**Solution:** + +```bash +# Verify OpenSpec structure +ls openspec/changes/ +# Should show change proposal directories + +# Check proposal.md exists +cat openspec/changes//proposal.md +``` + +### Issue: "Spec-Kit artifacts not found" + +**Solution:** + +```bash +# Verify Spec-Kit structure +ls specs/ +# Should show: [###-feature-name]/ directories + +# Check spec.md exists +cat specs/001-user-authentication/spec.md +``` + +### Issue: "GitHub Issues export failed" + +**Solution:** + +```bash +# Verify GitHub token +export GITHUB_TOKEN=your-token + +# Or use GitHub CLI +gh auth login + +# Verify repository access +gh repo view your-org/your-repo +``` + +--- + +## 📚 Next Steps + +### For OpenSpec Users + +1. **[OpenSpec Journey Guide](../guides/openspec-journey.md)** - Complete integration guide +2. **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** - GitHub Issues and backlog tracking +3. **[Commands Reference](../reference/commands.md#sync-bridge)** - Complete `sync bridge` documentation + +### For Spec-Kit Users + +1. **[Spec-Kit Journey Guide](../guides/speckit-journey.md)** - Complete integration guide +2. **[Spec-Kit Comparison](../guides/speckit-comparison.md)** - Understand when to use each tool +3. **[Commands Reference](../reference/commands.md#sync-bridge)** - Complete `sync bridge` documentation + +### General Resources + +1. **[Getting Started Guide](README.md)** - Installation and first commands +2. **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** - Complete brownfield modernization workflow +3. **[Use Cases](../guides/use-cases.md)** - Real-world scenarios + +--- + +## 💡 Tips & Best Practices + +### For OpenSpec Integration + +- ✅ **Separate repositories**: Keep OpenSpec specs in a separate repo from code +- ✅ **Change proposals**: Use OpenSpec for structured change proposals +- ✅ **DevOps export**: Export proposals to GitHub Issues for team visibility +- ✅ **Progress tracking**: Use `--track-code-changes` to auto-track implementation + +### For Spec-Kit Integration + +- ✅ **Bidirectional sync**: Use `--bidirectional --watch` for team collaboration +- ✅ **Interactive authoring**: Keep using Spec-Kit slash commands +- ✅ **Contract enforcement**: Add SpecFact contracts to critical paths +- ✅ **Drift detection**: Regularly run `plan compare` to catch deviations + +### General Tips + +- ✅ **Start small**: Begin with one feature or change proposal +- ✅ **Use watch mode**: Enable `--watch` for automatic synchronization +- ✅ **Review before sync**: Use `--dry-run` to preview changes +- ✅ **Version control**: Commit SpecFact bundles to version control + +--- + +## 🆘 Need Help? + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) +- 📖 [Full Documentation](../README.md) + +--- + +**Happy building!** 🚀 + +--- + +Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold) + +**Trademarks**: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See [TRADEMARKS.md](../../TRADEMARKS.md) for more information. diff --git a/_site_test/guides/README.md b/_site_test/guides/README.md new file mode 100644 index 0000000..00aa0ce --- /dev/null +++ b/_site_test/guides/README.md @@ -0,0 +1,65 @@ +# Guides + +Practical guides for using SpecFact CLI effectively. + +## Available Guides + +### Primary Use Case: Brownfield Modernization ⭐ + +- **[Brownfield Engineer Guide](brownfield-engineer.md)** ⭐ **PRIMARY** - Complete guide for modernizing legacy code +- **[The Brownfield Journey](brownfield-journey.md)** ⭐ **PRIMARY** - Step-by-step modernization workflow +- **[Brownfield ROI](brownfield-roi.md)** ⭐ - Calculate time and cost savings +- **[Brownfield FAQ](brownfield-faq.md)** ⭐ - Common questions about brownfield modernization + +### Secondary Use Case: Spec-Kit & OpenSpec Integration + +- **[Spec-Kit Journey](speckit-journey.md)** - Adding enforcement to Spec-Kit projects +- **[Spec-Kit Comparison](speckit-comparison.md)** - Understand when to use each tool +- **[OpenSpec Journey](openspec-journey.md)** 🆕 ⭐ **START HERE** - Complete integration guide with visual workflows: DevOps export (✅), bridge adapter (⏳), brownfield modernization +- **[Use Cases](use-cases.md)** - Real-world scenarios (brownfield primary, Spec-Kit secondary) + +### General Guides + +- **[Workflows](workflows.md)** - Common daily workflows +- **[IDE Integration](ide-integration.md)** - Set up slash commands in your IDE +- **[CoPilot Mode](copilot-mode.md)** - Using `--mode copilot` on CLI commands +- **[DevOps Adapter Integration](devops-adapter-integration.md)** - Integrate with GitHub Issues, Azure DevOps, Linear, Jira for backlog tracking +- **[Specmatic Integration](specmatic-integration.md)** - API contract testing with Specmatic (validate specs, generate tests, mock servers) +- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions +- **[Competitive Analysis](competitive-analysis.md)** - How SpecFact compares to other tools +- **[Operational Modes](../reference/modes.md)** - CI/CD vs CoPilot modes (reference) + +## Quick Start + +### Modernizing Legacy Code? ⭐ PRIMARY + +1. **[Integration Showcases](../examples/integration-showcases/)** ⭐ **START HERE** - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations +2. **[Brownfield Engineer Guide](brownfield-engineer.md)** ⭐ - Complete modernization guide +3. **[The Brownfield Journey](brownfield-journey.md)** ⭐ - Step-by-step workflow +4. **[Use Cases - Brownfield](use-cases.md#use-case-1-brownfield-code-modernization-primary)** ⭐ - Real-world examples + +### For IDE Users + +1. **[IDE Integration](ide-integration.md)** - Set up slash commands in your IDE +2. **[Use Cases](use-cases.md)** - See real-world examples + +### For CLI Users + +1. **[CoPilot Mode](copilot-mode.md)** - Using `--mode copilot` for enhanced prompts +2. **[Operational Modes](../reference/modes.md)** - Understanding CI/CD vs CoPilot modes +3. **[DevOps Adapter Integration](devops-adapter-integration.md)** - GitHub Issues and backlog tracking +4. **[Specmatic Integration](specmatic-integration.md)** - API contract testing workflow + +### For Spec-Kit & OpenSpec Users (Secondary) + +1. **[Tutorial: Using SpecFact with OpenSpec or Spec-Kit](../getting-started/tutorial-openspec-speckit.md)** ⭐ **START HERE** - Complete beginner-friendly step-by-step tutorial +2. **[Spec-Kit Journey](speckit-journey.md)** - Add enforcement to Spec-Kit projects +3. **[OpenSpec Journey](openspec-journey.md)** 🆕 ⭐ - Complete OpenSpec integration guide with DevOps export and visual workflows +4. **[DevOps Adapter Integration](devops-adapter-integration.md)** 🆕 - Export change proposals to GitHub Issues +5. **[Use Cases - Spec-Kit Migration](use-cases.md#use-case-2-github-spec-kit-migration-secondary)** - Step-by-step migration + +## Need Help? + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_test/guides/adapter-development.md b/_site_test/guides/adapter-development.md new file mode 100644 index 0000000..cf9a229 --- /dev/null +++ b/_site_test/guides/adapter-development.md @@ -0,0 +1,562 @@ +# Adapter Development Guide + +This guide explains how to create new bridge adapters for SpecFact CLI using the adapter registry pattern. + +## Overview + +SpecFact CLI uses a plugin-based adapter architecture that allows external tools (GitHub, Spec-Kit, Linear, Jira, etc.) to integrate seamlessly. All adapters implement the `BridgeAdapter` interface and are registered in the `AdapterRegistry` for automatic discovery and usage. + +## Architecture + +### Adapter Registry Pattern + +The adapter registry provides a centralized way to: + +- **Register adapters**: Auto-discover and register adapters at import time +- **Get adapters**: Retrieve adapters by name (e.g., `"speckit"`, `"github"`, `"openspec"`) +- **List adapters**: Enumerate all registered adapters +- **Check registration**: Verify if an adapter is registered + +### BridgeAdapter Interface + +All adapters must implement the `BridgeAdapter` abstract base class, which defines the following methods: + +```python +class BridgeAdapter(ABC): + @abstractmethod + def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool: + """Detect if this adapter applies to the repository.""" + + @abstractmethod + def get_capabilities(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> ToolCapabilities: + """Get tool capabilities for detected repository.""" + + @abstractmethod + def import_artifact(self, artifact_key: str, artifact_path: Path | dict[str, Any], project_bundle: Any, bridge_config: BridgeConfig | None = None) -> None: + """Import artifact from tool format to SpecFact.""" + + @abstractmethod + def export_artifact(self, artifact_key: str, artifact_data: Any, bridge_config: BridgeConfig | None = None) -> Path | dict[str, Any]: + """Export artifact from SpecFact to tool format.""" + + @abstractmethod + def generate_bridge_config(self, repo_path: Path) -> BridgeConfig: + """Generate bridge configuration for this adapter.""" + + @abstractmethod + def load_change_tracking(self, bundle_dir: Path, bridge_config: BridgeConfig | None = None) -> ChangeTracking | None: + """Load change tracking (adapter-specific storage location).""" + + @abstractmethod + def save_change_tracking(self, bundle_dir: Path, change_tracking: ChangeTracking, bridge_config: BridgeConfig | None = None) -> None: + """Save change tracking (adapter-specific storage location).""" + + @abstractmethod + def load_change_proposal(self, change_id: str, bridge_config: BridgeConfig | None = None) -> ChangeProposal | None: + """Load change proposal from adapter-specific location.""" + + @abstractmethod + def save_change_proposal(self, change_proposal: ChangeProposal, bridge_config: BridgeConfig | None = None) -> None: + """Save change proposal to adapter-specific location.""" +``` + +## Step-by-Step Guide + +### Step 1: Create Adapter Module + +Create a new file `src/specfact_cli/adapters/.py`: + +```python +""" + bridge adapter for . + +This adapter implements the BridgeAdapter interface to sync artifacts +with SpecFact plan bundles and protocols. +""" + +from __future__ import annotations + +from pathlib import Path +from typing import Any + +from beartype import beartype +from icontract import ensure, require + +from specfact_cli.adapters.base import BridgeAdapter +from specfact_cli.models.bridge import BridgeConfig +from specfact_cli.models.capabilities import ToolCapabilities +from specfact_cli.models.change import ChangeProposal, ChangeTracking + + +class MyAdapter(BridgeAdapter): + """ + bridge adapter implementing BridgeAdapter interface. + + This adapter provides sync between artifacts + and SpecFact plan bundles/protocols. + """ + + @beartype + @ensure(lambda result: result is None, "Must return None") + def __init__(self) -> None: + """Initialize adapter.""" + pass + + # Implement all abstract methods... +``` + +### Step 2: Implement Required Methods + +#### 2.1 Implement `detect()` + +Detect if the repository uses your tool: + +```python +@beartype +@require(lambda repo_path: repo_path.exists(), "Repository path must exist") +@require(lambda repo_path: repo_path.is_dir(), "Repository path must be a directory") +@ensure(lambda result: isinstance(result, bool), "Must return bool") +def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool: + """ + Detect if this is a repository. + + Args: + repo_path: Path to repository root + bridge_config: Optional bridge configuration (for cross-repo detection) + + Returns: + True if structure detected, False otherwise + """ + # Check for cross-repo support + base_path = repo_path + if bridge_config and bridge_config.external_base_path: + base_path = bridge_config.external_base_path + + # Check for tool-specific structure + # Example: Check for .tool/ directory or tool-specific files + tool_dir = base_path / ".tool" + config_file = base_path / "tool.config" + + return (tool_dir.exists() and tool_dir.is_dir()) or config_file.exists() +``` + +#### 2.2 Implement `get_capabilities()` + +Return tool capabilities: + +```python +@beartype +@require(lambda repo_path: repo_path.exists(), "Repository path must exist") +@require(lambda repo_path: repo_path.is_dir(), "Repository path must be a directory") +@ensure(lambda result: isinstance(result, ToolCapabilities), "Must return ToolCapabilities") +def get_capabilities(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> ToolCapabilities: + """ + Get adapter capabilities. + + Args: + repo_path: Path to repository root + bridge_config: Optional bridge configuration (for cross-repo detection) + + Returns: + ToolCapabilities instance for adapter + """ + from specfact_cli.models.capabilities import ToolCapabilities + + base_path = repo_path + if bridge_config and bridge_config.external_base_path: + base_path = bridge_config.external_base_path + + # Determine tool-specific capabilities + return ToolCapabilities( + tool="", + layout="", + specs_dir="", + supported_sync_modes=["", ""], # e.g., ["bidirectional", "unidirectional"] + has_custom_hooks=False, # Set to True if tool has custom hooks/constitution + ) +``` + +#### 2.3 Implement `generate_bridge_config()` + +Generate bridge configuration: + +```python +@beartype +@require(lambda repo_path: repo_path.exists(), "Repository path must exist") +@require(lambda repo_path: repo_path.is_dir(), "Repository path must be a directory") +@ensure(lambda result: isinstance(result, BridgeConfig), "Must return BridgeConfig") +def generate_bridge_config(self, repo_path: Path) -> BridgeConfig: + """ + Generate bridge configuration for adapter. + + Args: + repo_path: Path to repository root + + Returns: + BridgeConfig instance for adapter + """ + from specfact_cli.models.bridge import AdapterType, ArtifactMapping, BridgeConfig + + # Auto-detect layout and create appropriate config + # Use existing preset methods if available, or create custom config + return BridgeConfig( + adapter=AdapterType., + artifacts={ + "specification": ArtifactMapping( + path_pattern="", + format="", + ), + # Add other artifact mappings... + }, + ) +``` + +#### 2.4 Implement `import_artifact()` + +Import artifacts from tool format: + +```python +@beartype +@require( + lambda artifact_key: isinstance(artifact_key, str) and len(artifact_key) > 0, "Artifact key must be non-empty" +) +@ensure(lambda result: result is None, "Must return None") +def import_artifact( + self, + artifact_key: str, + artifact_path: Path | dict[str, Any], + project_bundle: Any, # ProjectBundle - avoid circular import + bridge_config: BridgeConfig | None = None, +) -> None: + """ + Import artifact from format to SpecFact. + + Args: + artifact_key: Artifact key (e.g., "specification", "plan", "tasks") + artifact_path: Path to artifact file or dict for API-based artifacts + project_bundle: Project bundle to update + bridge_config: Bridge configuration (may contain adapter-specific settings) + """ + # Parse tool-specific format and update project_bundle + # Store tool-specific paths in source_tracking.source_metadata + pass +``` + +#### 2.5 Implement `export_artifact()` + +Export artifacts to tool format: + +```python +@beartype +@require( + lambda artifact_key: isinstance(artifact_key, str) and len(artifact_key) > 0, "Artifact key must be non-empty" +) +@ensure(lambda result: isinstance(result, (Path, dict)), "Must return Path or dict") +def export_artifact( + self, + artifact_key: str, + artifact_data: Any, # Feature, ChangeProposal, etc. - avoid circular import + bridge_config: BridgeConfig | None = None, +) -> Path | dict[str, Any]: + """ + Export artifact from SpecFact to format. + + Args: + artifact_key: Artifact key (e.g., "specification", "plan", "tasks") + artifact_data: Data to export (Feature, Plan, etc.) + bridge_config: Bridge configuration (may contain adapter-specific settings) + + Returns: + Path to exported file or dict with API response data + """ + # Convert SpecFact models to tool-specific format + # Write to file or send via API + # Return Path for file-based exports, dict for API-based exports + pass +``` + +#### 2.6 Implement Change Tracking Methods + +For adapters that support change tracking: + +```python +@beartype +@require(lambda bundle_dir: isinstance(bundle_dir, Path), "Bundle directory must be Path") +@require(lambda bundle_dir: bundle_dir.exists(), "Bundle directory must exist") +@ensure(lambda result: result is None or isinstance(result, ChangeTracking), "Must return ChangeTracking or None") +def load_change_tracking( + self, bundle_dir: Path, bridge_config: BridgeConfig | None = None +) -> ChangeTracking | None: + """Load change tracking from tool-specific location.""" + # Return None if tool doesn't support change tracking + return None + +@beartype +@require(lambda bundle_dir: isinstance(bundle_dir, Path), "Bundle directory must be Path") +@require(lambda bundle_dir: bundle_dir.exists(), "Bundle directory must exist") +@ensure(lambda result: result is None, "Must return None") +def save_change_tracking( + self, bundle_dir: Path, change_tracking: ChangeTracking, bridge_config: BridgeConfig | None = None +) -> None: + """Save change tracking to tool-specific location.""" + # Raise NotImplementedError if tool doesn't support change tracking + raise NotImplementedError("Change tracking not supported by this adapter") +``` + +#### 2.7 Implement Change Proposal Methods + +For adapters that support change proposals: + +```python +@beartype +@require(lambda change_id: isinstance(change_id, str) and len(change_id) > 0, "Change ID must be non-empty") +@ensure(lambda result: result is None or isinstance(result, ChangeProposal), "Must return ChangeProposal or None") +def load_change_proposal( + self, change_id: str, bridge_config: BridgeConfig | None = None +) -> ChangeProposal | None: + """Load change proposal from tool-specific location.""" + # Return None if tool doesn't support change proposals + return None + +@beartype +@require(lambda change_proposal: isinstance(change_proposal, ChangeProposal), "Must provide ChangeProposal") +@ensure(lambda result: result is None, "Must return None") +def save_change_proposal( + self, change_proposal: ChangeProposal, bridge_config: BridgeConfig | None = None +) -> None: + """Save change proposal to tool-specific location.""" + # Raise NotImplementedError if tool doesn't support change proposals + raise NotImplementedError("Change proposals not supported by this adapter") +``` + +### Step 3: Register Adapter + +Register your adapter in `src/specfact_cli/adapters/__init__.py`: + +```python +from specfact_cli.adapters.my_adapter import MyAdapter +from specfact_cli.adapters.registry import AdapterRegistry + +# Auto-register adapter +AdapterRegistry.register("my-adapter", MyAdapter) + +__all__ = [..., "MyAdapter"] +``` + +**Important**: Use the actual CLI tool name as the registry key (e.g., `"speckit"`, `"github"`, not `"spec-kit"` or `"git-hub"`). + +### Step 4: Add Contract Decorators + +All methods must have contract decorators: + +- `@beartype`: Runtime type checking +- `@require`: Preconditions (input validation) +- `@ensure`: Postconditions (output validation) + +Example: + +```python +@beartype +@require(lambda repo_path: repo_path.exists(), "Repository path must exist") +@require(lambda repo_path: repo_path.is_dir(), "Repository path must be a directory") +@ensure(lambda result: isinstance(result, bool), "Must return bool") +def detect(self, repo_path: Path, bridge_config: BridgeConfig | None = None) -> bool: + # Implementation... +``` + +### Step 5: Add Tests + +Create comprehensive tests in `tests/unit/adapters/test_my_adapter.py`: + +```python +"""Unit tests for MyAdapter.""" + +import pytest +from pathlib import Path + +from specfact_cli.adapters.my_adapter import MyAdapter +from specfact_cli.adapters.registry import AdapterRegistry +from specfact_cli.models.bridge import BridgeConfig + + +class TestMyAdapter: + """Test MyAdapter class.""" + + def test_detect(self, tmp_path: Path): + """Test detect() method.""" + adapter = MyAdapter() + # Create tool-specific structure + (tmp_path / ".tool").mkdir() + + assert adapter.detect(tmp_path) is True + + def test_get_capabilities(self, tmp_path: Path): + """Test get_capabilities() method.""" + adapter = MyAdapter() + capabilities = adapter.get_capabilities(tmp_path) + + assert capabilities.tool == "my-adapter" + assert "bidirectional" in capabilities.supported_sync_modes + + def test_adapter_registry_registration(self): + """Test adapter is registered in registry.""" + assert AdapterRegistry.is_registered("my-adapter") + adapter_class = AdapterRegistry.get_adapter("my-adapter") + assert adapter_class == MyAdapter +``` + +### Step 6: Update Documentation + +1. **Update `docs/reference/architecture.md`**: Add your adapter to the adapters section +2. **Update `README.md`**: Add your adapter to the supported tools list +3. **Update `CHANGELOG.md`**: Document the new adapter addition + +## Examples + +### SpecKitAdapter (Bidirectional Sync) + +The `SpecKitAdapter` is a complete example of a bidirectional sync adapter: + +- **Location**: `src/specfact_cli/adapters/speckit.py` +- **Registry key**: `"speckit"` +- **Features**: Bidirectional sync, classic/modern layout support, constitution management +- **Public helpers**: `discover_features()`, `detect_changes()`, `detect_conflicts()`, `export_bundle()` + +### GitHubAdapter (Export-Only) + +The `GitHubAdapter` is an example of an export-only adapter: + +- **Location**: `src/specfact_cli/adapters/github.py` +- **Registry key**: `"github"` +- **Features**: Export-only (OpenSpec → GitHub Issues), progress tracking, content sanitization + +### OpenSpecAdapter (Bidirectional Sync) + +The `OpenSpecAdapter` is an example of a bidirectional sync adapter with change tracking: + +- **Location**: `src/specfact_cli/adapters/openspec.py` +- **Registry key**: `"openspec"` +- **Features**: Bidirectional sync, change tracking, change proposals + +## Best Practices + +### 1. Use Adapter Registry Pattern + +**✅ DO:** + +```python +# In commands/sync.py +adapter = AdapterRegistry.get_adapter(adapter_name) +if adapter: + adapter_instance = adapter() + if adapter_instance.detect(repo_path, bridge_config): + # Use adapter... +``` + +**❌ DON'T:** + +```python +# Hard-coded adapter checks +if adapter_name == "speckit": + adapter = SpecKitAdapter() +elif adapter_name == "github": + adapter = GitHubAdapter() +``` + +### 2. Support Cross-Repo Detection + +Always check `bridge_config.external_base_path` for cross-repository support: + +```python +base_path = repo_path +if bridge_config and bridge_config.external_base_path: + base_path = bridge_config.external_base_path + +# Use base_path for all file operations +tool_dir = base_path / ".tool" +``` + +### 3. Store Source Metadata + +When importing artifacts, store tool-specific paths in `source_tracking.source_metadata`: + +```python +if hasattr(project_bundle, "source_tracking") and project_bundle.source_tracking: + project_bundle.source_tracking.source_metadata = { + "tool": "my-adapter", + "original_path": str(artifact_path), + "tool_version": "1.0.0", + } +``` + +### 4. Handle Missing Artifacts Gracefully + +Return appropriate error messages when artifacts are not found: + +```python +if not artifact_path.exists(): + raise FileNotFoundError( + f"Artifact '{artifact_key}' not found at {artifact_path}. " + f"Expected location: {expected_path}" + ) +``` + +### 5. Use Contract Decorators + +Always add contract decorators for runtime validation: + +```python +@beartype +@require(lambda artifact_key: len(artifact_key) > 0, "Artifact key must be non-empty") +@ensure(lambda result: result is not None, "Must return non-None value") +def import_artifact(self, artifact_key: str, ...) -> None: + # Implementation... +``` + +## Testing + +### Unit Tests + +Create comprehensive unit tests covering: + +- Detection logic (same-repo and cross-repo) +- Capabilities retrieval +- Artifact import/export for all supported artifact types +- Error handling +- Adapter registry registration + +### Integration Tests + +Create integration tests covering: + +- Full sync workflows +- Bidirectional sync (if supported) +- Cross-repo scenarios +- Error recovery + +## Troubleshooting + +### Adapter Not Detected + +- Check `detect()` method logic +- Verify tool-specific structure exists +- Check `bridge_config.external_base_path` for cross-repo scenarios + +### Import/Export Failures + +- Verify artifact paths are resolved correctly +- Check `bridge_config.external_base_path` for cross-repo scenarios +- Ensure artifact format matches tool expectations + +### Registry Registration Issues + +- Verify adapter is imported in `adapters/__init__.py` +- Check registry key matches actual tool name +- Ensure `AdapterRegistry.register()` is called at module import time + +## Related Documentation + +- **[Architecture Documentation](../reference/architecture.md)**: Adapter architecture overview +- **[Architecture Documentation](../reference/architecture.md)**: Adapter architecture and BridgeConfig/ToolCapabilities models +- **[SpecKitAdapter Example](../../src/specfact_cli/adapters/speckit.py)**: Complete bidirectional sync example +- **[GitHubAdapter Example](../../src/specfact_cli/adapters/github.py)**: Export-only adapter example diff --git a/_site_test/guides/agile-scrum-workflows/index.html b/_site_test/guides/agile-scrum-workflows/index.html new file mode 100644 index 0000000..dcbd2c6 --- /dev/null +++ b/_site_test/guides/agile-scrum-workflows/index.html @@ -0,0 +1,1049 @@ + + + + + + + +Agile/Scrum Workflows with SpecFact CLI | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Agile/Scrum Workflows with SpecFact CLI

+ +

This guide explains how to use SpecFact CLI for agile/scrum workflows, including backlog management, sprint planning, dependency tracking, and Definition of Ready (DoR) validation.

+ +

Overview

+ +

SpecFact CLI supports real-world agile/scrum practices through:

+ +
    +
  • Definition of Ready (DoR): Automatic validation of story readiness for sprint planning
    • +
  • Dependency Management: Track story-to-story and feature-to-feature dependencies
    • +
  • Prioritization: Priority levels, ranking, and business value scoring
    • +
  • Sprint Planning: Target sprint/release assignment and story point tracking
    • +
  • Business Value Focus: User-focused value statements and measurable outcomes
    • +
  • Conflict Resolution: Persona-aware three-way merge with automatic conflict resolution based on section ownership
    • +
+ +

Persona-Based Workflows

+ +

SpecFact uses persona-based workflows where different roles work on different aspects:

+ +
    +
  • Product Owner: Owns requirements, user stories, business value, prioritization, sprint planning
    • +
  • Architect: Owns technical constraints, protocols, contracts, architectural decisions, non-functional requirements, risk assessment, deployment architecture
    • +
  • Developer: Owns implementation tasks, technical design, code mappings, test scenarios, Definition of Done
    • +
+ +

Exporting Persona Artifacts

+ +

Export persona-specific Markdown files for editing:

+ +
# Export Product Owner view
+specfact project export --bundle my-project --persona product-owner
+
+# Export Developer view
+specfact project export --bundle my-project --persona developer
+
+# Export Architect view
+specfact project export --bundle my-project --persona architect
+
+# Export to custom location
+specfact project export --bundle my-project --persona product-owner --output docs/backlog.md
+
+ +

The exported Markdown includes persona-specific content:

+ +

Product Owner Export:

+ +
    +
  • Definition of Ready Checklist: Visual indicators for each DoR criterion
    • +
  • Prioritization Data: Priority, rank, business value scores
    • +
  • Dependencies: Clear dependency chains (depends on, blocks)
    • +
  • Business Value: User-focused value statements and metrics
    • +
  • Sprint Planning: Target dates, sprints, and releases
    • +
+ +

Developer Export:

+ +
    +
  • Acceptance Criteria: Feature and story acceptance criteria
    • +
  • User Stories: Detailed story context with tasks, contracts, scenarios
    • +
  • Implementation Tasks: Granular tasks with file paths
    • +
  • Code Mappings: Source and test function mappings
    • +
  • Sprint Context: Story points, priority, dependencies, target sprint/release
    • +
  • Definition of Done: Completion criteria checklist
    • +
+ +

Architect Export:

+ +
    +
  • Technical Constraints: Feature-level technical constraints
    • +
  • Architectural Decisions: Technology choices, patterns, integration approaches
    • +
  • Non-Functional Requirements: Performance, scalability, availability, security, reliability targets
    • +
  • Protocols & State Machines: Complete protocol definitions with states and transitions
    • +
  • Contracts: OpenAPI/AsyncAPI contract details
    • +
  • Risk Assessment: Technical risks and mitigation strategies
    • +
  • Deployment Architecture: Infrastructure and deployment patterns
    • +
+ +

Importing Persona Edits

+ +

After editing the Markdown file, import changes back:

+ +
# Import Product Owner edits
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md
+
+# Import Developer edits
+specfact project import --bundle my-project --persona developer --source docs/developer.md
+
+# Import Architect edits
+specfact project import --bundle my-project --persona architect --source docs/architect.md
+
+# Dry-run to validate without applying
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md --dry-run
+
+ +

The import process validates:

+ +
    +
  • Template Structure: Required sections present
    • +
  • DoR Completeness: All DoR criteria met
    • +
  • Dependency Integrity: No circular dependencies, all references exist
    • +
  • Priority Consistency: Valid priority formats (P0-P3, MoSCoW)
    • +
  • Date Formats: ISO 8601 date validation
    • +
  • Story Point Ranges: Valid Fibonacci-like values
    • +
+ +

Section Locking

+ +

SpecFact supports section-level locking to prevent concurrent edits and ensure data integrity when multiple personas work on the same project bundle.

+ +

Lock Workflow

+ +

Step 1: Lock Section Before Editing

+ +

Lock the sections you plan to edit to prevent conflicts:

+ +
# Product Owner locks idea section
+specfact project lock --bundle my-project --section idea --persona product-owner
+
+# Architect locks protocols section
+specfact project lock --bundle my-project --section protocols --persona architect
+
+ +

Step 2: Export and Edit

+ +

Export your persona view, make edits, then import back:

+ +
# Export
+specfact project export --bundle my-project --persona product-owner
+
+# Edit the exported Markdown file
+# ... make your changes ...
+
+# Import (will be blocked if section is locked by another persona)
+specfact project import --bundle my-project --persona product-owner --input product-owner.md
+
+ +

Step 3: Unlock After Completing Edits

+ +

Unlock the section when you’re done:

+ +
# Unlock section
+specfact project unlock --bundle my-project --section idea
+
+ +

Lock Enforcement

+ +

The project import command automatically checks locks before saving:

+ +
    +
  • Allowed: Import succeeds if you own the locked section
    • +
  • Blocked: Import fails if section is locked by another persona
    • +
  • Blocked: Import fails if section is locked and you don’t own it
    • +
+ +

Example: Lock Enforcement in Action

+ +
# Product Owner locks idea section
+specfact project lock --bundle my-project --section idea --persona product-owner
+
+# Product Owner imports (succeeds - owns the section)
+specfact project import --bundle my-project --persona product-owner --input backlog.md
+# ✓ Import successful
+
+# Architect tries to import (fails - section is locked)
+specfact project import --bundle my-project --persona architect --input architect.md
+# ✗ Error: Cannot import: Section(s) are locked
+#   - Section 'idea' is locked by 'product-owner' (locked at 2025-12-12T10:00:00Z)
+
+ +

Real-World Workflow Example

+ +

Scenario: Product Owner and Architect working in parallel

+ +
# Morning: Product Owner locks idea and business sections
+specfact project lock --bundle my-project --section idea --persona product-owner
+specfact project lock --bundle my-project --section business --persona product-owner
+
+# Product Owner exports and edits
+specfact project export --bundle my-project --persona product-owner
+# Edit docs/project-plans/my-project/product-owner.md
+
+# Product Owner imports (succeeds)
+specfact project import --bundle my-project --persona product-owner \
+  --input docs/project-plans/my-project/product-owner.md
+
+# Product Owner unlocks after completing edits
+specfact project unlock --bundle my-project --section idea
+specfact project unlock --bundle my-project --section business
+
+# Afternoon: Architect locks protocols section
+specfact project lock --bundle my-project --section protocols --persona architect
+
+# Architect exports and edits
+specfact project export --bundle my-project --persona architect
+# Edit docs/project-plans/my-project/architect.md
+
+# Architect imports (succeeds)
+specfact project import --bundle my-project --persona architect \
+  --input docs/project-plans/my-project/architect.md
+
+# Architect unlocks
+specfact project unlock --bundle my-project --section protocols
+
+ +

Checking Locks

+ +

List all current locks:

+ +
# List all locks
+specfact project locks --bundle my-project
+
+ +

Output:

+ +
Section Locks
+┌─────────────────────┬──────────────────┬─────────────────────────┬──────────────────┐
+│ Section             │ Owner            │ Locked At               │ Locked By        │
+├─────────────────────┼──────────────────┼─────────────────────────┼──────────────────┤
+│ idea                │ product-owner    │ 2025-12-12T10:00:00Z    │ user@hostname    │
+│ protocols           │ architect        │ 2025-12-12T14:00:00Z    │ user@hostname    │
+└─────────────────────┴──────────────────┴─────────────────────────┴──────────────────┘
+
+ +

Lock Best Practices

+ +
    +
  1. Lock Before Editing: Always lock sections before exporting and editing
    2. +
  2. Unlock Promptly: Unlock sections immediately after completing edits
    3. +
  3. Check Locks First: Use project locks to see what’s locked before starting work
    4. +
  4. Coordinate with Team: Communicate lock usage to avoid blocking teammates
    5. +
  5. Use Granular Locks: Lock only the sections you need, not entire bundles
    6. +
+ +

Troubleshooting Locks

+ +

Issue: Import fails with “Section(s) are locked”

+ +

Solution: Check who locked the section and coordinate:

+ +
# Check locks
+specfact project locks --bundle my-project
+
+# Contact the lock owner or wait for them to unlock
+# Or ask them to unlock: specfact project unlock --section <section>
+
+ +

Issue: Can’t lock section - “already locked”

+ +

Solution: Someone else has locked it. Check locks and coordinate:

+ +
# See who locked it
+specfact project locks --bundle my-project
+
+# Wait for unlock or coordinate with lock owner
+
+ +

Issue: Locked section but forgot to unlock

+ +

Solution: Unlock manually:

+ +
# Unlock the section
+specfact project unlock --bundle my-project --section <section>
+
+ +

Conflict Resolution

+ +

When multiple personas work on the same project bundle in parallel, conflicts can occur when merging changes. SpecFact provides persona-aware conflict resolution that automatically resolves conflicts based on section ownership.

+ +

How Persona-Based Conflict Resolution Works

+ +

SpecFact uses a three-way merge algorithm that:

+ +
    +
  1. Detects conflicts: Compares base (common ancestor), ours (current branch), and theirs (incoming branch) versions
    2. +
  2. Checks ownership: Determines which persona owns each conflicting section based on bundle manifest
    3. +
  3. Auto-resolves: Automatically resolves conflicts when ownership is clear: +
      +
    • If only one persona owns the section → that persona’s version wins
      • +
    • If both personas own it and they’re the same → current branch wins
      • +
    • If both personas own it and they’re different → requires manual resolution
      • +
    +
    4. +
  4. Interactive resolution: Prompts for manual resolution when ownership is ambiguous
    5. +
+ +

Merge Workflow

+ +

Step 1: Export and Edit

+ +

Each persona exports their view, edits it, and imports back:

+ +
# Product Owner exports and edits
+specfact project export --bundle my-project --persona product-owner
+# Edit docs/project-plans/my-project/product-owner.md
+specfact project import --bundle my-project --persona product-owner --source docs/project-plans/my-project/product-owner.md
+
+# Architect exports and edits (in parallel)
+specfact project export --bundle my-project --persona architect
+# Edit docs/project-plans/my-project/architect.md
+specfact project import --bundle my-project --persona architect --source docs/project-plans/my-project/architect.md
+
+ +

Step 2: Merge Changes

+ +

When merging branches, use project merge with persona information:

+ +
# Merge with automatic persona-based resolution
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours po-branch \
+  --theirs arch-branch \
+  --persona-ours product-owner \
+  --persona-theirs architect
+
+ +

Step 3: Resolve Remaining Conflicts

+ +

If conflicts remain after automatic resolution, resolve them interactively:

+ +
# The merge command will prompt for each unresolved conflict:
+# Choose resolution: [ours/theirs/base/manual]
+
+ +

Or resolve individual conflicts manually:

+ +
# Resolve a specific conflict
+specfact project resolve-conflict \
+  --bundle my-project \
+  --path features.FEATURE-001.title \
+  --resolution ours
+
+ +

Example: Resolving a Conflict

+ +

Scenario: Product Owner and Architect both modified the same feature title.

+ +

Base version (common ancestor):

+ +
features:
+  FEATURE-001:
+    title: "User Authentication"
+
+ +

Product Owner’s version (ours):

+ +
features:
+  FEATURE-001:
+    title: "Secure User Authentication"
+
+ +

Architect’s version (theirs):

+ +
features:
+  FEATURE-001:
+    title: "OAuth2 User Authentication"
+
+ +

Automatic Resolution:

+ +
    +
  1. SpecFact checks ownership: features.FEATURE-001 is owned by product-owner (based on manifest)
    2. +
  2. Since Product Owner owns this section, their version wins automatically
    3. +
  3. Result: "Secure User Authentication" is kept
    4. +
+ +

Manual Resolution (if both personas own it):

+ +

If both personas own the section, SpecFact prompts:

+ +
Resolving conflict: features.FEATURE-001.title
+Base: User Authentication
+Ours (product-owner): Secure User Authentication
+Theirs (architect): OAuth2 User Authentication
+
+Choose resolution [ours/theirs/base/manual]: manual
+Enter manual value: OAuth2 Secure User Authentication
+
+ +

Conflict Resolution Strategies

+ +

You can specify a merge strategy to override automatic resolution:

+ +
    +
  • auto (default): Persona-based automatic resolution
    • +
  • ours: Always prefer our version
    • +
  • theirs: Always prefer their version
    • +
  • base: Always prefer base version
    • +
  • manual: Require manual resolution for all conflicts
    • +
+ +
# Use manual strategy for full control
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours po-branch \
+  --theirs arch-branch \
+  --persona-ours product-owner \
+  --persona-theirs architect \
+  --strategy manual
+
+ +

CI/CD Integration

+ +

For automated workflows, use --no-interactive:

+ +
# Non-interactive merge (fails if conflicts require manual resolution)
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours HEAD \
+  --theirs origin/feature \
+  --persona-ours product-owner \
+  --persona-theirs architect \
+  --no-interactive
+
+ +

Note: In non-interactive mode, the merge will fail if there are conflicts that require manual resolution. Use this in CI/CD pipelines only when you’re confident conflicts will be auto-resolved.

+ +

Best Practices

+ +
    +
  1. Set Clear Ownership: Ensure persona ownership is clearly defined in bundle manifest
    2. +
  2. Merge Frequently: Merge branches frequently to reduce conflict scope
    3. +
  3. Review Auto-Resolutions: Review automatically resolved conflicts before committing
    4. +
  4. Use Manual Strategy for Complex Conflicts: When in doubt, use --strategy manual for full control
    5. +
  5. Document Resolution Decisions: Add comments explaining why certain resolutions were chosen
    6. +
+ +

Troubleshooting Conflicts

+ +

Issue: Merge fails with “unresolved conflicts”

+ +

Solution: Use interactive mode to resolve conflicts:

+ +
# Run merge in interactive mode
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours po-branch \
+  --theirs arch-branch \
+  --persona-ours product-owner \
+  --persona-theirs architect
+# Follow prompts to resolve each conflict
+
+ +

Issue: Auto-resolution chose wrong version

+ +

Solution: Check persona ownership in manifest, or use manual strategy:

+ +
# Check ownership
+specfact project export --bundle my-project --list-personas
+
+# Use manual strategy
+specfact project merge --strategy manual ...
+
+ +

Issue: Conflict path not found

+ +

Solution: Use correct conflict path format:

+ +
    +
  • idea.title - Idea title
    • +
  • business.value_proposition - Business value proposition
    • +
  • features.FEATURE-001.title - Feature title
    • +
  • features.FEATURE-001.stories.STORY-001.description - Story description
    • +
+ +

Definition of Ready (DoR)

+ +

DoR Checklist

+ +

Each story must meet these criteria before sprint planning:

+ +
    +
  • Story Points: Complexity estimated (1, 2, 3, 5, 8, 13, 21…)
    • +
  • Value Points: Business value estimated (1, 2, 3, 5, 8, 13, 21…)
    • +
  • Priority: Priority level set (P0-P3 or MoSCoW)
    • +
  • Dependencies: Dependencies identified and validated
    • +
  • Business Value: Clear business value description present
    • +
  • Target Date: Target completion date set (optional but recommended)
    • +
  • Target Sprint: Target sprint assigned (optional but recommended)
    • +
+ +

Example: Story with Complete DoR

+ +
**Story 1**: User can login with email
+
+**Definition of Ready**:
+- [x] Story Points: 5 (Complexity)
+- [x] Value Points: 8 (Business Value)
+- [x] Priority: P1
+- [x] Dependencies: 1 identified
+- [x] Business Value: ✓
+- [x] Target Date: 2025-01-15
+- [x] Target Sprint: Sprint 2025-01
+
+**Story Details**:
+- **Story Points**: 5 (Complexity)
+- **Value Points**: 8 (Business Value)
+- **Priority**: P1
+- **Rank**: 1
+- **Target Date**: 2025-01-15
+- **Target Sprint**: Sprint 2025-01
+- **Target Release**: v2.1.0
+
+**Business Value**:
+Enables users to securely access their accounts, reducing support tickets by 30% and improving user satisfaction.
+
+**Business Metrics**:
+- Reduce support tickets by 30%
+- Increase user login success rate to 99.5%
+- Reduce password reset requests by 25%
+
+**Dependencies**:
+**Depends On**:
+- STORY-000: User registration system
+
+**Acceptance Criteria** (User-Focused):
+- [ ] As a user, I can enter my email and password to log in
+- [ ] As a user, I receive clear error messages if login fails
+- [ ] As a user, I am redirected to my dashboard after successful login
+
+ +

Dependency Management

+ +

Story Dependencies

+ +

Track dependencies between stories:

+ +
**Dependencies**:
+**Depends On**:
+- STORY-001: User registration system
+- STORY-002: Email verification
+
+**Blocks**:
+- STORY-010: Password reset flow
+
+ +

Feature Dependencies

+ +

Track dependencies between features:

+ +
### FEATURE-001: User Authentication
+
+#### Dependencies
+
+**Depends On Features**:
+- FEATURE-000: User Management Infrastructure
+
+**Blocks Features**:
+- FEATURE-002: User Profile Management
+
+ +

Validation Rules

+ +

The import process validates:

+ +
    +
  1. Reference Existence: All referenced stories/features exist
    2. +
  2. No Circular Dependencies: Prevents A → B → A cycles
    3. +
  3. Format Validation: Dependency keys match expected format (STORY-001, FEATURE-001)
    4. +
+ +

Example: Circular Dependency Error

+ +
$ specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+Error: Agile/Scrum validation failed:
+  - Story STORY-001: Circular dependency detected with 'STORY-002'
+  - Feature FEATURE-001: Circular dependency detected with 'FEATURE-002'
+
+ +

Prioritization

+ +

Priority Levels

+ +

Use one of these priority formats:

+ +
    +
  • P0-P3: P0=Critical, P1=High, P2=Medium, P3=Low
    • +
  • MoSCoW: Must, Should, Could, Won’t
    • +
  • Descriptive: Critical, High, Medium, Low
    • +
+ +

Ranking

+ +

Use backlog rank (1 = highest priority):

+ +
**Priority**: P1 | **Rank**: 1
+
+ +

Business Value Scoring

+ +

Score features 0-100 for business value:

+ +
**Business Value Score**: 75/100
+
+ +

Example: Prioritized Feature

+ +
### FEATURE-001: User Authentication
+
+**Priority**: P1 | **Rank**: 1  
+**Business Value Score**: 75/100  
+**Target Release**: v2.1.0  
+**Estimated Story Points**: 13
+
+#### Business Value
+
+Enables secure user access, reducing support overhead and improving user experience.
+
+**Target Users**: end-user, admin
+
+**Success Metrics**:
+- Reduce support tickets by 30%
+- Increase user login success rate to 99.5%
+- Reduce password reset requests by 25%
+
+ +

Sprint Planning

+ +

Story Point Estimation

+ +

Use Fibonacci-like values: 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 100

+ +
- **Story Points**: 5 (Complexity)
+- **Value Points**: 8 (Business Value)
+
+ +

Target Sprint Assignment

+ +

Assign stories to specific sprints:

+ +
- **Target Sprint**: Sprint 2025-01
+- **Target Release**: v2.1.0
+- **Target Date**: 2025-01-15
+
+ +

Feature-Level Totals

+ +

Feature story point totals are automatically calculated:

+ +
**Estimated Story Points**: 13
+
+ +

This is the sum of all story points for stories in this feature.

+ +

Business Value Focus

+ +

User-Focused Value Statements

+ +

Write stories with clear user value:

+ +
**Business Value**:
+As a user, I want to securely log in to my account so that I can access my personalized dashboard and manage my data.
+
+**Business Metrics**:
+- Reduce support tickets by 30%
+- Increase user login success rate to 99.5%
+- Reduce password reset requests by 25%
+
+ +

Acceptance Criteria Format

+ +

Use “As a [user], I want [capability] so that [outcome]” format:

+ +
**Acceptance Criteria** (User-Focused):
+- [ ] As a user, I can enter my email and password to log in
+- [ ] As a user, I receive clear error messages if login fails
+- [ ] As a user, I am redirected to my dashboard after successful login
+
+ +

Template Customization

+ +

Override Default Templates

+ +

Create project-specific templates in .specfact/templates/persona/:

+ +
.specfact/
+└── templates/
+    └── persona/
+        └── product-owner.md.j2  # Project-specific template
+
+ +

The project-specific template overrides the default template in resources/templates/persona/.

+ +

Template Structure

+ +

Templates use Jinja2 syntax with these variables:

+ +
    +
  • bundle_name: Project bundle name
    • +
  • features: Dictionary of features (key -> feature dict)
    • +
  • idea: Idea section data
    • +
  • business: Business section data
    • +
  • locks: Section locks information
    • +
+ +

Example: Custom Template Section

+ +
{% if features %}
+## Features & User Stories
+
+{% for feature_key, feature in features.items() %}
+### {{ feature.key }}: {{ feature.title }}
+
+**Priority**: {{ feature.priority | default('Not Set') }}
+**Business Value**: {{ feature.business_value_score | default('Not Set') }}/100
+
+{% if feature.stories %}
+#### User Stories
+
+{% for story in feature.stories %}
+**Story {{ loop.index }}**: {{ story.title }}
+
+**DoR Status**: {{ '✓ Complete' if story.definition_of_ready.values() | all else '✗ Incomplete' }}
+
+{% endfor %}
+{% endif %}
+
+{% endfor %}
+{% endif %}
+
+ +

Validation Examples

+ +

DoR Validation

+ +
$ specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+Error: Agile/Scrum validation failed:
+  - Story STORY-001 (Feature FEATURE-001): Missing story points (required for DoR)
+  - Story STORY-001 (Feature FEATURE-001): Missing value points (required for DoR)
+  - Story STORY-001 (Feature FEATURE-001): Missing priority (required for DoR)
+  - Story STORY-001 (Feature FEATURE-001): Missing business value description (required for DoR)
+
+ +

Dependency Validation

+ +
$ specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+Error: Agile/Scrum validation failed:
+  - Story STORY-001: Dependency 'STORY-999' does not exist
+  - Story STORY-001: Circular dependency detected with 'STORY-002'
+  - Feature FEATURE-001: Dependency 'FEATURE-999' does not exist
+
+ +

Priority Validation

+ +
$ specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+Error: Agile/Scrum validation failed:
+  - Story STORY-001: Invalid priority 'P5' (must be P0-P3, MoSCoW, or Critical/High/Medium/Low)
+  - Feature FEATURE-001: Invalid priority 'Invalid' (must be P0-P3, MoSCoW, or Critical/High/Medium/Low)
+
+ +

Date Format Validation

+ +
$ specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+Error: Agile/Scrum validation failed:
+  - Story STORY-001: Invalid date format '2025/01/15' (expected ISO 8601: YYYY-MM-DD)
+  - Story STORY-001: Warning - target date '2024-01-15' is in the past (may need updating)
+
+ +

Best Practices

+ +

1. Complete DoR Before Sprint Planning

+ +

Ensure all stories meet DoR criteria before assigning to sprints:

+ +
# Validate DoR completeness
+specfact project import --bundle my-project --persona product-owner --source backlog.md --dry-run
+
+ +

2. Track Dependencies Early

+ +

Identify dependencies during story creation to avoid blockers:

+ +
**Dependencies**:
+**Depends On**:
+- STORY-001: User registration (must complete first)
+
+ +

3. Use Consistent Priority Formats

+ +

Choose one priority format per project and use consistently:

+ +
    +
  • Option 1: P0-P3 (recommended for technical teams)
    • +
  • Option 2: MoSCoW (recommended for business-focused teams)
    • +
  • Option 3: Descriptive (Critical/High/Medium/Low)
    • +
+ +

4. Set Business Value for All Stories

+ +

Every story should have a clear business value statement:

+ +
**Business Value**:
+Enables users to securely access their accounts, reducing support tickets by 30%.
+
+ +

5. Use Story Points for Capacity Planning

+ +

Track story points to estimate sprint capacity:

+ +
**Estimated Story Points**: 21  # Sum of all stories in feature
+
+ +

Troubleshooting

+ +

Validation Errors

+ +

If import fails with validation errors:

+ +
    +
  1. Check DoR Completeness: Ensure all required fields are present
    2. +
  2. Verify Dependencies: Check that all referenced stories/features exist
    3. +
  3. Validate Formats: Ensure priority, dates, and story points use correct formats
    4. +
  4. Review Business Value: Ensure business value descriptions are present and meaningful
    5. +
+ +

Template Issues

+ +

If template rendering fails:

+ +
    +
  1. Check Template Syntax: Verify Jinja2 syntax is correct
    2. +
  2. Verify Variables: Ensure template variables match exported data structure
    3. +
  3. Test Template: Use --dry-run to test template without importing
    4. +
+ + + + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/guides/brownfield-faq.md b/_site_test/guides/brownfield-faq.md new file mode 100644 index 0000000..40e2d53 --- /dev/null +++ b/_site_test/guides/brownfield-faq.md @@ -0,0 +1,369 @@ +# Brownfield Modernization FAQ + +> **Frequently asked questions about using SpecFact CLI for legacy code modernization** + +--- + +## General Questions + +### What is brownfield modernization? + +**Brownfield modernization** refers to improving, refactoring, or migrating existing (legacy) codebases, as opposed to greenfield development (starting from scratch). + +SpecFact CLI is designed specifically for brownfield projects where you need to: + +- Understand undocumented legacy code +- Modernize without breaking existing behavior +- Extract specs from existing code (code2spec) +- Enforce contracts during refactoring + +--- + +## Code Analysis + +### Can SpecFact analyze code with no docstrings? + +**Yes.** SpecFact's code2spec analyzes: + +- Function signatures and type hints +- Code patterns and control flow +- Existing validation logic +- Module dependencies +- Commit history and code structure + +No docstrings needed. SpecFact infers behavior from code patterns. + +### What if the legacy code has no type hints? + +**SpecFact infers types** from usage patterns and generates specs. You can add type hints incrementally as part of modernization. + +**Example:** + +```python +# Legacy code (no type hints) +def process_order(user_id, amount): + # SpecFact infers: user_id: int, amount: float + ... + +# SpecFact generates: +# - Precondition: user_id > 0, amount > 0 +# - Postcondition: returns Order object +``` + +### Can SpecFact handle obfuscated or minified code? + +**Limited.** SpecFact works best with: + +- Source code (not compiled bytecode) +- Readable variable names +- Standard Python patterns + +For heavily obfuscated code, consider: + +1. Deobfuscation first (if possible) +2. Manual documentation of critical paths +3. Adding contracts incrementally to deobfuscated sections + +### What about code with no tests? + +**SpecFact doesn't require tests.** In fact, code2spec is designed for codebases with: + +- No tests +- No documentation +- No type hints + +SpecFact extracts specs from code structure and patterns, not from tests. + +--- + +## Contract Enforcement + +### Will contracts slow down my code? + +**Minimal impact.** Contract checks are fast (microseconds per call). For high-performance code: + +- **Development/Testing:** Keep contracts enabled (catch violations) +- **Production:** Optionally disable contracts (performance-critical paths only) + +**Best practice:** Keep contracts in tests, disable only in production hot paths if needed. + +### Can I add contracts incrementally? + +**Yes.** Recommended approach: + +1. **Week 1:** Add contracts to 3-5 critical functions +2. **Week 2:** Expand to 10-15 functions +3. **Week 3:** Add contracts to all public APIs +4. **Week 4+:** Add contracts to internal functions as needed + +Start with shadow mode (observe only), then enable enforcement incrementally. + +### What if a contract is too strict? + +**Contracts are configurable.** You can: + +- **Relax contracts:** Adjust preconditions/postconditions to match actual behavior +- **Shadow mode:** Observe violations without blocking +- **Warn mode:** Log violations but don't raise exceptions +- **Block mode:** Raise exceptions on violations (default) + +Start in shadow mode, then tighten as you understand the code better. + +--- + +## Edge Case Discovery + +### How does CrossHair discover edge cases? + +**CrossHair uses symbolic execution** to explore all possible code paths mathematically. It: + +1. Represents inputs symbolically (not concrete values) +2. Explores all feasible execution paths +3. Finds inputs that violate contracts +4. Generates concrete test cases for violations + +**Example:** + +```python +@icontract.require(lambda numbers: len(numbers) > 0) +@icontract.ensure(lambda numbers, result: min(numbers) > result) +def remove_smallest(numbers: List[int]) -> int: + smallest = min(numbers) + numbers.remove(smallest) + return smallest + +# CrossHair finds: [3, 3, 5] violates postcondition +# (duplicates cause min(numbers) == result after removal) +``` + +### Can CrossHair find all edge cases? + +**No tool can find all edge cases**, but CrossHair is more thorough than: + +- Manual testing (limited by human imagination) +- Random testing (limited by coverage) +- LLM suggestions (probabilistic, not exhaustive) + +CrossHair provides **mathematical guarantees** for explored paths, but complex code may have paths that are computationally infeasible to explore. + +### How long does CrossHair take? + +**Typically 10-60 seconds per function**, depending on: + +- Function complexity +- Number of code paths +- Contract complexity + +For large codebases, run CrossHair on critical functions first, then expand. + +--- + +## Modernization Workflow + +### How do I start modernizing safely? + +**Recommended workflow:** + +1. **Extract specs** (`specfact import from-code`) +2. **Add contracts** to 3-5 critical functions +3. **Run CrossHair** to discover edge cases +4. **Refactor incrementally** (one function at a time) +5. **Verify contracts** still pass after refactoring +6. **Expand contracts** to more functions + +Start in shadow mode, then enable enforcement as you gain confidence. + +### What if I break a contract during refactoring? + +**That's the point!** Contracts catch regressions immediately: + +```python +# Refactored code violates contract +process_payment(user_id=-1, amount=-50, currency="XYZ") + +# Contract violation caught: +# ❌ ContractViolation: Payment amount must be positive (got -50) +# → Fix the bug before it reaches production! +``` + +Contracts are your **safety net** - they prevent breaking changes from being deployed. + +### Can I use SpecFact with existing test suites? + +**Yes.** SpecFact complements existing tests: + +- **Tests:** Verify specific scenarios +- **Contracts:** Enforce behavior at API boundaries +- **CrossHair:** Discover edge cases tests miss + +Use all three together for comprehensive coverage. + +### What's the learning curve for contract-first development? + +**Minimal.** SpecFact is designed for incremental adoption: + +**Week 1 (2-4 hours):** + +- Run `import from-code` to extract specs (10 seconds) +- Review extracted plan bundle +- Add contracts to 3-5 critical functions + +**Week 2 (4-6 hours):** + +- Expand contracts to 10-15 functions +- Run CrossHair on critical paths +- Set up pre-commit hook + +**Week 3+ (ongoing):** + +- Add contracts incrementally as you refactor +- Use shadow mode to observe violations +- Enable enforcement when confident + +**No upfront training required.** Start with shadow mode (observe only), then enable enforcement incrementally as you understand the code better. + +**Resources:** + +- [Brownfield Engineer Guide](brownfield-engineer.md) - Complete walkthrough +- [Integration Showcases](../examples/integration-showcases/) - Real examples +- [Getting Started](../getting-started/README.md) - Quick start guide + +--- + +## Integration + +### Does SpecFact work with GitHub Spec-Kit? + +**Yes.** SpecFact complements Spec-Kit: + +- **Spec-Kit:** Interactive spec authoring (greenfield) +- **SpecFact:** Automated enforcement + brownfield support + +**Use both together:** + +1. Use Spec-Kit for initial spec generation (fast, LLM-powered) +2. Use SpecFact to add runtime contracts to critical paths (safety net) +3. Spec-Kit generates docs, SpecFact prevents regressions + +See [Spec-Kit Comparison Guide](speckit-comparison.md) for details. + +### Can I use SpecFact in CI/CD? + +**Yes.** SpecFact integrates with: + +- **GitHub Actions:** PR annotations, contract validation +- **GitLab CI:** Pipeline integration +- **Jenkins:** Plugin support (planned) +- **Local CI:** Run `specfact enforce` in your pipeline + +Contracts can block merges if violations are detected (configurable). + +### Does SpecFact work with VS Code, Cursor, or other IDEs? + +**Yes.** SpecFact's CLI-first design means it works with **any IDE or editor**: + +- **VS Code:** Pre-commit hooks, tasks, or extensions +- **Cursor:** AI assistant integration with contract validation +- **Any editor:** Pure CLI, no IDE lock-in required +- **Agentic workflows:** Works with any AI coding assistant + +**Example VS Code integration:** + +```bash +# .git/hooks/pre-commit +#!/bin/sh +uvx specfact-cli@latest enforce stage --preset balanced +``` + +**Example Cursor integration:** + +```bash +# Validate AI suggestions before accepting +cursor-agent --validate-with "uvx specfact-cli@latest enforce stage" +``` + +See [Integration Showcases](../examples/integration-showcases/) for real examples of bugs caught via different integrations. + +### Do I need to learn a new platform? + +**No.** SpecFact is **CLI-first**—it integrates into your existing workflow: + +- ✅ Works with your current IDE (VS Code, Cursor, etc.) +- ✅ Works with your current CI/CD (GitHub Actions, GitLab, etc.) +- ✅ Works with your current tools (no new platform to learn) +- ✅ Works offline (no cloud account required) +- ✅ Zero vendor lock-in (OSS forever) + +**No platform migration needed.** Just add SpecFact CLI to your existing workflow. + +--- + +## Performance + +### How fast is code2spec extraction? + +**Typical timing**: + +- **Small codebases** (10-50 files): ~10 seconds to 1-2 minutes +- **Medium codebases** (50-100 files): ~1-2 minutes +- **Large codebases** (100+ files): **2-3 minutes** for AST + Semgrep analysis +- **Large codebases with contracts** (100+ files): **15-30+ minutes** with contract extraction, graph analysis, and parallel processing (8 workers) + +The import process performs AST analysis, Semgrep pattern detection, and (when enabled) extracts OpenAPI contracts, relationships, and graph dependencies in parallel, which can take significant time for large repositories. + +### Does SpecFact require internet? + +**No.** SpecFact works 100% offline: + +- No cloud services required +- No API keys needed +- No telemetry (opt-in only) +- Fully local execution + +Perfect for air-gapped environments or sensitive codebases. + +--- + +## Limitations + +### What are SpecFact's limitations? + +**Known limitations:** + +1. **Python-only** (JavaScript/TypeScript support planned Q1 2026) +2. **Source code required** (not compiled bytecode) +3. **Readable code preferred** (obfuscated code may have lower accuracy) +4. **Complex contracts** may slow CrossHair (timeout configurable) + +**What SpecFact does well:** + +- ✅ Extracts specs from undocumented code +- ✅ Enforces contracts at runtime +- ✅ Discovers edge cases with symbolic execution +- ✅ Prevents regressions during modernization + +--- + +## Support + +### Where can I get help? + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) - Ask questions +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) - Report bugs +- 📧 [hello@noldai.com](mailto:hello@noldai.com) - Direct support + +### Can I contribute? + +**Yes!** SpecFact is open source. See [CONTRIBUTING.md](https://github.com/nold-ai/specfact-cli/blob/main/CONTRIBUTING.md) for guidelines. + +--- + +## Next Steps + +1. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete modernization workflow +2. **[ROI Calculator](brownfield-roi.md)** - Calculate your savings +3. **[Examples](../examples/)** - Real-world brownfield examples + +--- + +**Still have questions?** [Open a discussion](https://github.com/nold-ai/specfact-cli/discussions) or [email us](mailto:hello@noldai.com). diff --git a/_site_test/guides/brownfield-roi.md b/_site_test/guides/brownfield-roi.md new file mode 100644 index 0000000..0fabb32 --- /dev/null +++ b/_site_test/guides/brownfield-roi.md @@ -0,0 +1,224 @@ +# Brownfield Modernization ROI with SpecFact + +> **Calculate your time and cost savings when modernizing legacy Python code** + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow (VS Code, Cursor, GitHub Actions, pre-commit hooks). No platform to learn, no vendor lock-in. + +--- + +## ROI Calculator + +Use this calculator to estimate your savings when using SpecFact CLI for brownfield modernization. + +### Input Your Project Size + +**Number of Python files in legacy codebase:** `[____]` +**Average lines of code per file:** `[____]` +**Hourly rate:** `$[____]` per hour + +--- + +## Manual Approach (Baseline) + +### Time Investment + +| Task | Time (Hours) | Cost | +|------|-------------|------| +| **Documentation** | | | +| - Manually document legacy code | `[files] × 1.5-2.5 hours` | `$[____]` | +| - Write API documentation | `[endpoints] × 2-4 hours` | `$[____]` | +| - Create architecture diagrams | `8-16 hours` | `$[____]` | +| **Testing** | | | +| - Write tests for undocumented code | `[files] × 2-3 hours` | `$[____]` | +| - Manual edge case discovery | `20-40 hours` | `$[____]` | +| **Modernization** | | | +| - Debug regressions during refactor | `40-80 hours` | `$[____]` | +| - Fix production bugs from modernization | `20-60 hours` | `$[____]` | +| **TOTAL** | **`[____]` hours** | **`$[____]`** | + +### Example: 50-File Legacy App + +| Task | Time (Hours) | Cost (@$150/hr) | +|------|-------------|-----------------| +| Manually document 50-file legacy app | 80-120 hours | $12,000-$18,000 | +| Write tests for undocumented code | 100-150 hours | $15,000-$22,500 | +| Debug regression during refactor | 40-80 hours | $6,000-$12,000 | +| **TOTAL** | **220-350 hours** | **$33,000-$52,500** | + +--- + +## SpecFact Automated Approach + +### Time Investment (Automated) + +| Task | Time (Hours) | Cost | +|------|-------------|------| +| **Documentation** | | | +| - Run code2spec extraction | `0.17 hours (10 min)` | `$[____]` | +| - Review and refine extracted specs | `8-16 hours` | `$[____]` | +| **Contract Enforcement** | | | +| - Add contracts to critical paths | `16-24 hours` | `$[____]` | +| - CrossHair edge case discovery | `2-4 hours` | `$[____]` | +| **Modernization** | | | +| - Refactor with contract safety net | `[baseline] × 0.5-0.7` | `$[____]` | +| - Fix regressions (prevented by contracts) | `0-10 hours` | `$[____]` | +| **TOTAL** | **`[____]` hours** | **`$[____]`** | + +### Example: 50-File Legacy App (Automated Results) + +| Task | Time (Hours) | Cost (@$150/hr) | +|------|-------------|-----------------| +| Run code2spec extraction | 0.17 hours (10 min) | $25 | +| Review and refine extracted specs | 8-16 hours | $1,200-$2,400 | +| Add contracts to critical paths | 16-24 hours | $2,400-$3,600 | +| CrossHair edge case discovery | 2-4 hours | $300-$600 | +| **TOTAL** | **26-44 hours** | **$3,925-$6,625** | + +--- + +## ROI Calculation + +### Time Savings + +**Manual approach:** `[____]` hours +**SpecFact approach:** `[____]` hours +**Time saved:** `[____]` hours (**`[____]%`** reduction) + +### Cost Savings + +**Manual approach:** `$[____]` +**SpecFact approach:** `$[____]` +**Cost avoided:** `$[____]` (**`[____]%`** reduction) + +### Example: 50-File Legacy App (Results) + +**Time saved:** 194-306 hours (**87%** reduction) +**Cost avoided:** $26,075-$45,875 (**87%** reduction) + +--- + +## Industry Benchmarks + +### IBM GenAI Modernization Study + +- **70% cost reduction** via automated code discovery +- **50% faster** feature delivery +- **95% reduction** in manual effort + +### SpecFact Alignment + +SpecFact's code2spec provides similar automation: + +- **87% time saved** on documentation (vs. manual) +- **100% detection rate** for contract violations (vs. manual review) +- **6-12 edge cases** discovered automatically (vs. 0-2 manually) + +--- + +## Additional Benefits (Not Quantified) + +### Quality Improvements + +- ✅ **Zero production bugs** from modernization (contracts prevent regressions) +- ✅ **100% API documentation** coverage (extracted automatically) +- ✅ **Hidden edge cases** discovered before production (CrossHair) + +### Team Productivity + +- ✅ **60% faster** developer onboarding (documented codebase) +- ✅ **50% reduction** in code review time (contracts catch issues) +- ✅ **Zero debugging time** for contract violations (caught at runtime) + +### Risk Reduction + +- ✅ **Formal guarantees** vs. probabilistic LLM suggestions +- ✅ **Mathematical verification** vs. manual code review +- ✅ **Safety net** during modernization (contracts enforce behavior) + +--- + +## Real-World Case Studies + +### Case Study 1: Data Pipeline Modernization + +**Challenge:** + +- 5-year-old Python data pipeline (12K LOC) +- No documentation, original developers left +- Needed modernization from Python 2.7 → 3.12 +- Fear of breaking critical ETL jobs + +**Solution:** + +1. Ran `specfact import from-code` → 47 features extracted in 12 seconds +2. Added contracts to 23 critical data transformation functions +3. CrossHair discovered 6 edge cases in legacy validation logic +4. Enforced contracts during migration, blocked 11 regressions +5. Integrated with GitHub Actions CI/CD to prevent bad code from merging + +**Results:** + +- ✅ 87% faster documentation (8 hours vs. 60 hours manual) +- ✅ 11 production bugs prevented during migration +- ✅ Zero downtime migration completed in 3 weeks vs. estimated 8 weeks +- ✅ New team members productive in days vs. weeks + +**ROI:** $42,000 saved, 5-week acceleration + +### Case Study 2: Integration Success Stories + +**See real examples of bugs fixed via integrations:** + +- **[Integration Showcases](../examples/integration-showcases/)** - 5 complete examples: + - VS Code + Pre-commit: Async bug caught before commit + - Cursor Integration: Regression prevented during refactoring + - GitHub Actions: Type mismatch blocked from merging + - Pre-commit Hook: Breaking change detected locally + - Agentic Workflows: Edge cases discovered with symbolic execution + +**Key Finding**: 3 of 5 examples fully validated, showing real bugs fixed through CLI integrations. + +--- + +## When ROI Is Highest + +SpecFact provides maximum ROI for: + +- ✅ **Large codebases** (50+ files) - More time saved on documentation +- ✅ **Undocumented code** - Manual documentation is most expensive +- ✅ **High-risk systems** - Contract enforcement prevents costly production bugs +- ✅ **Complex business logic** - CrossHair discovers edge cases manual testing misses +- ✅ **Team modernization** - Faster onboarding = immediate productivity gains + +--- + +## Try It Yourself + +Calculate your ROI: + +1. **Run code2spec** on your legacy codebase: + + ```bash + specfact import from-code --bundle legacy-api --repo ./your-legacy-app + ``` + +2. **Time the extraction** (typically < 10 seconds) + +3. **Compare to manual documentation time** (typically 1.5-2.5 hours per file) + +4. **Calculate your savings:** + - Time saved = (files × 1.5 hours) - 0.17 hours + - Cost saved = Time saved × hourly rate + +--- + +## Next Steps + +1. **[Integration Showcases](../examples/integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations +2. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete modernization workflow +3. **[Brownfield Journey](brownfield-journey.md)** - Step-by-step modernization guide +4. **[Examples](../examples/)** - Real-world brownfield examples + +--- + +**Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) | [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_test/guides/command-chains/index.html b/_site_test/guides/command-chains/index.html new file mode 100644 index 0000000..f0b7750 --- /dev/null +++ b/_site_test/guides/command-chains/index.html @@ -0,0 +1,922 @@ + + + + + + + +Command Chains Reference | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Command Chains Reference

+ +
+

Complete guide to SpecFact CLI command chains and workflows

+
+ +
+ +

Overview

+ +

Command chains are sequences of SpecFact CLI commands that work together to achieve specific goals. Each chain represents a complete workflow from start to finish, with decision points and expected outcomes documented.

+ +

Why use command chains? Instead of learning individual commands in isolation, command chains show you how to combine commands to solve real-world problems. They provide context, decision points, and links to detailed guides.

+ +

This document covers all 9 identified command chains:

+ +
    +
  • 6 Mature Chains: Well-established workflows with comprehensive documentation
    • +
  • 3 Emerging Chains: AI-assisted workflows that integrate with IDE slash commands
    • +
+ +
+ +

When to Use Which Chain?

+ +

Use this decision tree to find the right chain for your use case:

+ +
Start: What do you want to accomplish?
+
+├─ Modernize existing legacy code?
+│  └─ → Brownfield Modernization Chain
+│
+├─ Plan a new feature from scratch?
+│  └─ → Greenfield Planning Chain
+│
+├─ Integrate with Spec-Kit, OpenSpec, or other tools?
+│  └─ → External Tool Integration Chain
+│
+├─ Develop or validate API contracts?
+│  └─ → API Contract Development Chain
+│
+├─ Promote a plan through stages to release?
+│  └─ → Plan Promotion & Release Chain
+│
+├─ Compare code against specifications?
+│  └─ → Code-to-Plan Comparison Chain
+│
+├─ Use AI to enhance code with contracts?
+│  └─ → AI-Assisted Code Enhancement Chain (Emerging)
+│
+├─ Generate tests from specifications?
+│  └─ → Test Generation from Specifications Chain (Emerging)
+│
+└─ Fix gaps discovered during analysis?
+   └─ → Gap Discovery & Fixing Chain (Emerging)
+
+ +
+ +

1. Brownfield Modernization Chain

+ +

Goal: Modernize legacy code safely by extracting specifications, creating plans, and enforcing contracts.

+ +

When to use: You have existing code that needs modernization, refactoring, or migration.

+ +

Command Sequence:

+ +
# Step 1: Extract specifications from legacy code
+specfact import from-code --bundle legacy-api --repo .
+
+# Step 2: Review the extracted plan
+specfact plan review --bundle legacy-api
+
+# Step 3: Update features based on review findings
+specfact plan update-feature --bundle legacy-api --feature <feature-id>
+
+# Step 4: Enforce SDD (Spec-Driven Development) compliance
+specfact enforce sdd --bundle legacy-api
+
+# Step 5: Run full validation suite
+specfact repro --verbose
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Legacy Codebase] -->|import from-code| B[Extract Specifications]
+    B --> C[Plan Review]
+    C -->|Issues Found| D[Update Features]
+    C -->|No Issues| E[Enforce SDD]
+    D --> E
+    E --> F[Run Validation]
+    F -->|Pass| G[Modernized Code]
+    F -->|Fail| D
+
+ +

Decision Points:

+ +
    +
  • After import from-code: Review the extracted plan. If features are incomplete or incorrect, use plan update-feature to refine them.
    • +
  • After plan review: If ambiguities are found, resolve them before proceeding to enforcement.
    • +
  • After enforce sdd: If compliance fails, update the plan and re-run enforcement.
    • +
  • After repro: If validation fails, fix issues and re-run the chain from the appropriate step.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Complete specification extracted from legacy code
    • +
  • Plan bundle with features, stories, and acceptance criteria
    • +
  • SDD-compliant codebase
    • +
  • Validated contracts and tests
    • +
+ +

Related Guides:

+ + + +
+ +

2. Greenfield Planning Chain

+ +

Goal: Plan new features from scratch using Spec-Driven Development principles.

+ +

When to use: You’re starting a new feature or project and want to plan it properly before coding.

+ +

Command Sequence:

+ +
# Step 1: Initialize a new plan bundle
+specfact plan init --bundle new-feature --interactive
+
+# Step 2: Add features to the plan
+specfact plan add-feature --bundle new-feature --name "User Authentication"
+
+# Step 3: Add user stories to features
+specfact plan add-story --bundle new-feature --feature <feature-id> --story "As a user, I want to log in"
+
+# Step 4: Review the plan for completeness
+specfact plan review --bundle new-feature
+
+# Step 5: Harden the plan (finalize before implementation)
+specfact plan harden --bundle new-feature
+
+# Step 6: Generate contracts from the plan
+specfact generate contracts --bundle new-feature
+
+# Step 7: Enforce SDD compliance
+specfact enforce sdd --bundle new-feature
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[New Feature Idea] -->|plan init| B[Initialize Plan]
+    B -->|plan add-feature| C[Add Features]
+    C -->|plan add-story| D[Add User Stories]
+    D -->|plan review| E[Review Plan]
+    E -->|Issues| D
+    E -->|Complete| F[plan harden]
+    F -->|generate contracts| G[Generate Contracts]
+    G -->|enforce sdd| H[SDD-Compliant Plan]
+
+ +

Decision Points:

+ +
    +
  • After plan init: Choose interactive mode to get guided prompts, or use flags for automation.
    • +
  • After plan add-feature: Add multiple features before adding stories, or add stories immediately.
    • +
  • After plan review: If ambiguities are found, add more details or stories before hardening.
    • +
  • After plan harden: Once hardened, the plan is locked. Generate contracts before enforcement.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Complete plan bundle with features and stories
    • +
  • Generated contracts ready for implementation
    • +
  • SDD-compliant plan ready for development
    • +
+ +

Related Guides:

+ + + +
+ +

3. External Tool Integration Chain

+ +

Goal: Integrate SpecFact with external tools like Spec-Kit, OpenSpec, Linear, or Jira.

+ +

When to use: You want to sync specifications between SpecFact and other tools, or import from external sources.

+ +

Command Sequence:

+ +
# Step 1: Import from external tool via bridge adapter
+specfact import from-bridge --repo . --adapter speckit --write
+
+# Step 2: Review the imported plan
+specfact plan review --bundle <bundle-name>
+
+# Step 3: Set up bidirectional sync (optional)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --bidirectional --watch
+
+# Step 4: Enforce SDD compliance
+specfact enforce sdd --bundle <bundle-name>
+
+ +

Workflow Diagram:

+ +
graph LR
+    A[External Tool] -->|import from-bridge| B[SpecFact Plan]
+    B -->|plan review| C[Review Import]
+    C -->|sync bridge| D[Bidirectional Sync]
+    D -->|enforce sdd| E[SDD-Compliant]
+    E -.->|watch mode| D
+
+ +

Decision Points:

+ +
    +
  • After import from-bridge: Review the imported plan. If it needs refinement, use plan update-feature.
    • +
  • Bidirectional sync: Use --watch mode for continuous synchronization, or run sync manually as needed.
    • +
  • Adapter selection: Choose the appropriate adapter (speckit, openspec, github, linear, jira).
    • +
+ +

Expected Outcomes:

+ +
    +
  • Specifications imported from external tool
    • +
  • Bidirectional synchronization (if enabled)
    • +
  • SDD-compliant integrated workflow
    • +
+ +

Related Guides:

+ + + +
+ +

4. API Contract Development Chain

+ +

Goal: Develop, validate, and test API contracts using SpecFact and Specmatic integration.

+ +

When to use: You’re developing REST APIs and want to ensure contract compliance and backward compatibility.

+ +

Command Sequence:

+ +
# Step 1: Validate API specification
+specfact spec validate --spec openapi.yaml
+
+# Step 2: Check backward compatibility
+specfact spec backward-compat --spec openapi.yaml --previous-spec openapi-v1.yaml
+
+# Step 3: Generate tests from specification
+specfact spec generate-tests --spec openapi.yaml --output tests/
+
+# Step 4: Generate mock server (optional)
+specfact spec mock --spec openapi.yaml --port 8080
+
+# Step 5: Verify contracts at runtime
+specfact contract verify --bundle api-bundle
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[API Specification] -->|spec validate| B[Validate Spec]
+    B -->|spec backward-compat| C[Check Compatibility]
+    C -->|spec generate-tests| D[Generate Tests]
+    C -->|spec mock| E[Mock Server]
+    D -->|contract verify| F[Verified Contracts]
+    E --> F
+
+ +

Decision Points:

+ +
    +
  • After spec validate: If validation fails, fix the specification before proceeding.
    • +
  • Backward compatibility: Check compatibility before releasing new API versions.
    • +
  • Mock server: Use mock server for testing clients before implementation is complete.
    • +
  • Contract verification: Run verification in CI/CD to catch contract violations early.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Validated API specification
    • +
  • Backward compatibility verified
    • +
  • Generated tests from specification
    • +
  • Runtime contract verification
    • +
+ +

Related Guides:

+ + + +
+ +

5. Plan Promotion & Release Chain

+ +

Goal: Promote a plan through stages (draft → review → approved → released) and manage versions.

+ +

When to use: You have a completed plan and want to promote it through your organization’s approval process.

+ +

Command Sequence:

+ +
# Step 1: Review the plan before promotion
+specfact plan review --bundle <bundle-name>
+
+# Step 2: Enforce SDD compliance
+specfact enforce sdd --bundle <bundle-name>
+
+# Step 3: Promote the plan to next stage
+specfact plan promote --bundle <bundle-name> --stage <next-stage>
+
+# Step 4: Bump version when releasing
+specfact project version bump --bundle <bundle-name> --type <major|minor|patch>
+
+ +

Workflow Diagram:

+ +
graph LR
+    A[Draft Plan] -->|plan review| B[Review]
+    B -->|enforce sdd| C[SDD Compliant]
+    C -->|plan promote| D[Next Stage]
+    D -->|version bump| E[Released]
+
+ +

Decision Points:

+ +
    +
  • After plan review: If issues are found, fix them before promotion.
    • +
  • SDD enforcement: Ensure compliance before promoting to production stages.
    • +
  • Version bumping: Choose appropriate version type (major/minor/patch) based on changes.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Plan promoted through approval stages
    • +
  • Version bumped appropriately
    • +
  • Release-ready plan bundle
    • +
+ +

Related Guides:

+ + + +
+ +

6. Code-to-Plan Comparison Chain

+ +

Goal: Detect and resolve drift between code and specifications.

+ +

When to use: You want to ensure your code matches your specifications, or detect when code has diverged.

+ +

Command Sequence:

+ +
# Step 1: Import current code state
+specfact import from-code --bundle current-state --repo .
+
+# Step 2: Compare code against plan
+specfact plan compare --bundle <plan-bundle> --code-vs-plan
+
+# Step 3: Detect drift
+specfact drift detect --bundle <bundle-name>
+
+# Step 4: Sync repository (if drift found)
+specfact sync repository --bundle <bundle-name> --direction <code-to-plan|plan-to-code>
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Code Repository] -->|import from-code| B[Current State]
+    B -->|plan compare| C[Compare]
+    C -->|drift detect| D[Drift Found?]
+    D -->|Yes| E[sync repository]
+    D -->|No| F[In Sync]
+    E --> F
+
+ +

Decision Points:

+ +
    +
  • After plan compare: Review the comparison results to understand differences.
    • +
  • Drift detection: If drift is detected, decide whether to sync code-to-plan or plan-to-code.
    • +
  • Sync direction: Choose code-to-plan to update plan from code, or plan-to-code to update code from plan.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Code and plan synchronized
    • +
  • Drift detected and resolved
    • +
  • Consistent state between code and specifications
    • +
+ +

Related Guides:

+ + + +
+ +

7. AI-Assisted Code Enhancement Chain (Emerging)

+ +

Goal: Use AI IDE integration to enhance code with contracts and validate them.

+ +

When to use: You want to add contracts to existing code using AI assistance in your IDE.

+ +

Command Sequence:

+ +
# Step 1: Generate contract prompt for AI IDE
+specfact generate contracts-prompt --bundle <bundle-name> --feature <feature-id>
+
+# Step 2: [In AI IDE] Use slash command to apply contracts
+# /specfact-cli/contracts-apply <prompt-file>
+
+# Step 3: Check contract coverage
+specfact contract coverage --bundle <bundle-name>
+
+# Step 4: Run validation
+specfact repro --verbose
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Code Without Contracts] -->|generate contracts-prompt| B[AI Prompt]
+    B -->|AI IDE| C[Apply Contracts]
+    C -->|contract coverage| D[Check Coverage]
+    D -->|repro| E[Validated Code]
+
+ +

Decision Points:

+ +
    +
  • After generating prompt: Review the prompt in your AI IDE before applying.
    • +
  • Contract coverage: Ensure coverage meets your requirements before validation.
    • +
  • Validation: If validation fails, review and fix contracts, then re-run.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Contracts added to code via AI assistance
    • +
  • Contract coverage verified
    • +
  • Validated enhanced code
    • +
+ +

Related Guides:

+ + + +
+ +

8. Test Generation from Specifications Chain (Emerging)

+ +

Goal: Generate tests from specifications using AI assistance.

+ +

When to use: You have specifications and want to generate comprehensive tests automatically.

+ +

Command Sequence:

+ +
# Step 1: Generate test prompt for AI IDE
+specfact generate test-prompt --bundle <bundle-name> --feature <feature-id>
+
+# Step 2: [In AI IDE] Use slash command to generate tests
+# /specfact-cli/test-generate <prompt-file>
+
+# Step 3: Generate tests from specification
+specfact spec generate-tests --spec <spec-file> --output tests/
+
+# Step 4: Run tests
+pytest tests/
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Specification] -->|generate test-prompt| B[AI Prompt]
+    B -->|AI IDE| C[Generate Tests]
+    A -->|spec generate-tests| D[Spec-Based Tests]
+    C --> E[Test Suite]
+    D --> E
+    E -->|pytest| F[Test Results]
+
+ +

Decision Points:

+ +
    +
  • Test generation method: Use AI IDE for custom tests, or spec generate-tests for specification-based tests.
    • +
  • Test coverage: Review generated tests to ensure they cover all scenarios.
    • +
  • Test execution: Run tests in CI/CD for continuous validation.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Comprehensive test suite generated
    • +
  • Tests validated and passing
    • +
  • Specification coverage verified
    • +
+ +

Related Guides:

+ + + +
+ +

9. Gap Discovery & Fixing Chain (Emerging)

+ +

Goal: Discover gaps in specifications and fix them using AI assistance.

+ +

When to use: You want to find missing contracts or specifications and add them systematically.

+ +

Command Sequence:

+ +
# Step 1: Run validation with verbose output
+specfact repro --verbose
+
+# Step 2: Generate fix prompt for discovered gaps
+specfact generate fix-prompt --bundle <bundle-name> --gap <gap-id>
+
+# Step 3: [In AI IDE] Use slash command to apply fixes
+# /specfact-cli/fix-apply <prompt-file>
+
+# Step 4: Enforce SDD compliance
+specfact enforce sdd --bundle <bundle-name>
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Codebase] -->|repro --verbose| B[Discover Gaps]
+    B -->|generate fix-prompt| C[AI Fix Prompt]
+    C -->|AI IDE| D[Apply Fixes]
+    D -->|enforce sdd| E[SDD Compliant]
+    E -->|repro| B
+
+ +

Decision Points:

+ +
    +
  • After repro --verbose: Review discovered gaps and prioritize fixes.
    • +
  • Fix application: Review AI-suggested fixes before applying.
    • +
  • SDD enforcement: Ensure compliance after fixes are applied.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Gaps discovered and documented
    • +
  • Fixes applied via AI assistance
    • +
  • SDD-compliant codebase
    • +
+ +

Related Guides:

+ + + +
+ +

10. SDD Constitution Management Chain

+ +

Goal: Manage Spec-Driven Development (SDD) constitutions for Spec-Kit compatibility.

+ +

When to use: You’re working with Spec-Kit format and need to bootstrap, enrich, or validate constitutions.

+ +

Command Sequence:

+ +
# Step 1: Bootstrap constitution from repository
+specfact sdd constitution bootstrap --repo .
+
+# Step 2: Enrich constitution with repository context
+specfact sdd constitution enrich --repo .
+
+# Step 3: Validate constitution completeness
+specfact sdd constitution validate
+
+# Step 4: List SDD manifests
+specfact sdd list
+
+ +

Workflow Diagram:

+ +
graph TD
+    A[Repository] -->|sdd constitution bootstrap| B[Bootstrap Constitution]
+    B -->|sdd constitution enrich| C[Enrich Constitution]
+    C -->|sdd constitution validate| D[Validate Constitution]
+    D -->|sdd list| E[SDD Manifests]
+    D -->|Issues Found| C
+
+ +

Decision Points:

+ +
    +
  • Bootstrap vs Enrich: Use bootstrap for new constitutions, enrich for existing ones.
    • +
  • Validation: Run validation after bootstrap/enrich to ensure completeness.
    • +
  • Spec-Kit Compatibility: These commands are for Spec-Kit format only. SpecFact uses modular project bundles internally.
    • +
+ +

Expected Outcomes:

+ +
    +
  • Complete SDD constitution for Spec-Kit compatibility
    • +
  • Validated constitution ready for use
    • +
  • List of SDD manifests in repository
    • +
+ +

Related Guides:

+ + + +
+ +

Orphaned Commands Integration

+ +

The following commands are now integrated into documented workflows:

+ +

plan update-idea

+ +

Integrated into: Greenfield Planning Chain

+ +

When to use: Update feature ideas during planning phase.

+ +

Workflow: Use as part of plan update-feature workflow in Greenfield Planning.

+ +
+ +

project export/import/lock/unlock

+ +

Integrated into: Team Collaboration Workflow and Plan Promotion & Release Chain

+ +

When to use: Team collaboration with persona-based workflows.

+ +

Workflow: See Team Collaboration Workflow for complete workflow.

+ +
+ +

migrate * Commands

+ +

Integrated into: Migration Guide

+ +

When to use: Migrating between versions or from other tools.

+ +

Workflow: See Migration Guide for decision tree and workflows.

+ +
+ +

sdd list

+ +

Integrated into: SDD Constitution Management Chain

+ +

When to use: List SDD manifests in repository.

+ +

Workflow: Use after constitution management to verify manifests.

+ +
+ +

contract verify

+ +

Integrated into: API Contract Development Chain

+ +

When to use: Verify contracts at runtime.

+ +

Workflow: Use as final step in API Contract Development Chain.

+ +
+ +

See Also

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/guides/contract-testing-workflow.md b/_site_test/guides/contract-testing-workflow.md new file mode 100644 index 0000000..471d29a --- /dev/null +++ b/_site_test/guides/contract-testing-workflow.md @@ -0,0 +1,269 @@ +# Contract Testing Workflow - Simple Guide for Developers + +## Quick Start: Verify Your Contract + +The easiest way to verify your OpenAPI contract works is with a single command: + +```bash +# Verify a specific contract +specfact contract verify --bundle my-api --feature FEATURE-001 + +# Verify all contracts in a bundle +specfact contract verify --bundle my-api +``` + +**What this does:** + +1. ✅ Validates your contract schema +2. ✅ Generates examples from the contract +3. ✅ Starts a mock server +4. ✅ Tests connectivity + +**That's it!** Your contract is verified and ready to use. The mock server keeps running so you can test your client code. + +## What You Can Do Without a Real API + +### ✅ Contract Verification (No API Needed) + +Use `contract verify` to ensure your contract is correct: + +```bash +specfact contract verify --bundle my-api --feature FEATURE-001 +``` + +**Output:** + +``` +``` + +Step 1: Validating contracts... +✓ FEATURE-001: Valid (13 endpoints) + +Step 2: Generating examples... +✓ FEATURE-001: Examples generated + +Step 3: Starting mock server for FEATURE-001... +✓ Mock server started at + +Step 4: Testing connectivity... +✓ Health check passed: UP + +✓ Contract verification complete! + +Summary: + • Contracts validated: 1 + • Examples generated: 1 + • Mock server: + +``` + +### ✅ Mock Server for Development + +Start a mock server that generates responses from your contract: + +```bash +# Start mock server with examples +specfact contract serve --bundle my-api --feature FEATURE-001 --examples + +# Or use the verify command (starts mock server automatically) +specfact contract verify --bundle my-api --feature FEATURE-001 +``` + +**Use cases:** + +- Frontend development without backend +- Client library testing +- Integration testing (test your client against the contract) + +### ✅ Contract Validation + +Validate that your contract schema is correct: + +```bash +# Validate a specific contract +specfact contract validate --bundle my-api --feature FEATURE-001 + +# Check coverage across all contracts +specfact contract coverage --bundle my-api +``` + +## Complete Workflow Examples + +### Example 1: New Contract Development + +```bash +# 1. Create a new contract +specfact contract init --bundle my-api --feature FEATURE-001 + +# 2. Edit the contract file +# Edit: .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml + +# 3. Verify everything works +specfact contract verify --bundle my-api --feature FEATURE-001 + +# 4. Test your client code against the mock server +curl http://localhost:9000/api/endpoint +``` + +### Example 2: CI/CD Pipeline + +```bash +# Validate contracts without starting mock server +specfact contract verify --bundle my-api --skip-mock --no-interactive + +# Or just validate +specfact contract validate --bundle my-api --no-interactive +``` + +### Example 3: Multiple Contracts + +```bash +# Verify all contracts in a bundle +specfact contract verify --bundle my-api + +# Check coverage +specfact contract coverage --bundle my-api +``` + +## What Requires a Real API + +### ❌ Contract Testing Against Real Implementation + +The `specmatic test` command requires a **real API implementation**: + +```bash +# This REQUIRES a running API +specmatic test \ + --spec .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml \ + --host http://localhost:8000 +``` + +**When to use:** + +- After implementing your API +- To verify your implementation matches the contract +- In integration tests + +**Workflow:** + +```bash +# 1. Generate test files +specfact contract test --bundle my-api --feature FEATURE-001 + +# 2. Start your real API +python -m uvicorn main:app --port 8000 + +# 3. Run contract tests +specmatic test \ + --spec .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml \ + --host http://localhost:8000 +``` + +## Command Reference + +### `contract verify` - All-in-One Verification + +The simplest way to verify your contract: + +```bash +specfact contract verify [OPTIONS] + +Options: + --bundle TEXT Project bundle name + --feature TEXT Feature key (optional - verifies all if not specified) + --port INTEGER Port for mock server (default: 9000) + --skip-mock Skip mock server (only validate) + --no-interactive Non-interactive mode (CI/CD) +``` + +**What it does:** + +1. Validates contract schema +2. Generates examples +3. Starts mock server (unless `--skip-mock`) +4. Tests connectivity + +### `contract validate` - Schema Validation + +```bash +specfact contract validate --bundle my-api --feature FEATURE-001 +``` + +Validates the OpenAPI schema structure. + +### `contract serve` - Mock Server + +```bash +specfact contract serve --bundle my-api --feature FEATURE-001 --examples +``` + +Starts a mock server that generates responses from your contract. + +### `contract coverage` - Coverage Report + +```bash +specfact contract coverage --bundle my-api +``` + +Shows contract coverage metrics across all features. + +### `contract test` - Generate Tests + +```bash +specfact contract test --bundle my-api --feature FEATURE-001 +``` + +Generates test files that can be run against a real API. + +## Key Insights + +| Task | Requires Real API? | Command | +|------|-------------------|---------| +| **Contract Verification** | ❌ No | `contract verify` | +| **Schema Validation** | ❌ No | `contract validate` | +| **Mock Server** | ❌ No | `contract serve` | +| **Example Generation** | ❌ No | `contract verify` (automatic) | +| **Contract Testing** | ✅ Yes | `specmatic test` (after `contract test`) | + +## Troubleshooting + +### Mock Server Won't Start + +```bash +# Check if Specmatic is installed +npx specmatic --version + +# Install if needed +npm install -g @specmatic/specmatic +``` + +### Contract Validation Fails + +```bash +# Check contract file syntax +cat .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml + +# Validate manually +specfact contract validate --bundle my-api --feature FEATURE-001 +``` + +### Examples Not Generated + +Examples are generated automatically from your OpenAPI schema. If generation fails: + +- Check that your schema has proper request/response definitions +- Ensure data types are properly defined +- Run `contract verify` to see detailed error messages + +## Best Practices + +1. **Start with `contract verify`** - It does everything you need +2. **Use mock servers for development** - No need to wait for backend +3. **Validate in CI/CD** - Use `--skip-mock --no-interactive` for fast validation +4. **Test against real API** - Use `specmatic test` after implementation + +## Next Steps + +- Read the [API Reference](../reference/commands.md) for detailed command options +- Check [Architecture Documentation](../reference/architecture.md) for bundle management +- See [Agile/Scrum Workflows](../guides/agile-scrum-workflows.md) for team collaboration diff --git a/_site_test/guides/devops-adapter-integration.md b/_site_test/guides/devops-adapter-integration.md new file mode 100644 index 0000000..387d6e2 --- /dev/null +++ b/_site_test/guides/devops-adapter-integration.md @@ -0,0 +1,605 @@ +# DevOps Adapter Integration Guide + +This guide explains how to integrate SpecFact CLI with DevOps backlog tools (GitHub Issues, Azure DevOps, Linear, Jira) to sync OpenSpec change proposals and track implementation progress through automated comment annotations. + +## Overview + +SpecFact CLI supports exporting OpenSpec change proposals to DevOps tools and tracking implementation progress: + +- **Issue Creation**: Export OpenSpec change proposals as GitHub Issues (or other DevOps backlog items) +- **Progress Tracking**: Automatically detect code changes and add progress comments to issues +- **Content Sanitization**: Protect internal information when syncing to public repositories +- **Separate Repository Support**: Handle cases where OpenSpec proposals and source code are in different repositories + +## Supported Adapters + +Currently supported DevOps adapters: + +- **GitHub Issues** (`--adapter github`) - Full support for issue creation and progress comments +- **Azure DevOps** (`--adapter ado`) - Planned +- **Linear** (`--adapter linear`) - Planned +- **Jira** (`--adapter jira`) - Planned + +This guide focuses on GitHub Issues integration. Other adapters will follow similar patterns. + +--- + +## Quick Start + +### 1. Create Change Proposal + +Create an OpenSpec change proposal in your OpenSpec repository: + +```bash +# Structure: openspec/changes//proposal.md +mkdir -p openspec/changes/add-feature-x +cat > openspec/changes/add-feature-x/proposal.md << 'EOF' +# Add Feature X + +## Summary + +Add new feature X to improve user experience. + +## Status + +- status: proposed + +## Implementation Plan + +1. Design API endpoints +2. Implement backend logic +3. Add frontend components +4. Write tests +EOF +``` + +### 2. Export to GitHub Issues + +Export the change proposal to create a GitHub issue: + +```bash +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo +``` + +### 3. Track Code Changes + +As you implement the feature, track progress automatically: + +```bash +# Make commits with change ID in commit message +git commit -m "feat: implement add-feature-x - initial API design" + +# Track progress (detects commits and adds comments) +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --track-code-changes \ + --repo /path/to/openspec-repo \ + --code-repo /path/to/source-code-repo # If different from OpenSpec repo +``` + +--- + +## GitHub Issues Integration + +### Prerequisites + +**For Issue Creation:** + +- OpenSpec change proposals in `openspec/changes//proposal.md` +- GitHub token (via `GITHUB_TOKEN` env var, `gh auth token`, or `--github-token`) +- Repository access permissions (read for proposals, write for issues) + +**For Code Change Tracking:** + +- Issues must already exist (created via previous sync) +- Git repository with commits mentioning the change proposal ID in commit messages +- If OpenSpec and source code are in separate repositories, use `--code-repo` parameter + +### Authentication + +SpecFact CLI supports multiple authentication methods: + +**Option 1: GitHub CLI (Recommended)** + +```bash +# Uses gh auth token automatically +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --use-gh-cli +``` + +**Option 2: Environment Variable** + +```bash +export GITHUB_TOKEN=ghp_your_token_here +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo +``` + +**Option 3: Command Line Flag** + +```bash +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --github-token ghp_your_token_here +``` + +### Basic Usage + +#### Create Issues from Change Proposals + +```bash +# Export all active proposals to GitHub Issues +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo +``` + +#### Track Code Changes + +```bash +# Detect code changes and add progress comments +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --track-code-changes \ + --repo /path/to/openspec-repo +``` + +#### Sync Specific Proposals + +```bash +# Export only specific change proposals +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --change-ids add-feature-x,update-api \ + --repo /path/to/openspec-repo +``` + +--- + +## Separate OpenSpec and Source Code Repositories + +When your OpenSpec change proposals are in a different repository than your source code: + +### Architecture + +- **OpenSpec Repository** (`--repo`): Contains change proposals in `openspec/changes/` directory +- **Source Code Repository** (`--code-repo`): Contains actual implementation commits + +### Example Setup + +```bash +# OpenSpec proposals in specfact-cli-internal +# Source code in specfact-cli + +# Step 1: Create issue from proposal +specfact sync bridge --adapter github --mode export-only \ + --repo-owner nold-ai \ + --repo-name specfact-cli-internal \ + --repo /path/to/specfact-cli-internal + +# Step 2: Track code changes from source code repo +specfact sync bridge --adapter github --mode export-only \ + --repo-owner nold-ai \ + --repo-name specfact-cli-internal \ + --track-code-changes \ + --repo /path/to/specfact-cli-internal \ + --code-repo /path/to/specfact-cli +``` + +### Why Use `--code-repo`? + +- **OpenSpec repository** (`--repo`): Contains change proposals and tracks issue metadata +- **Source code repository** (`--code-repo`): Contains actual implementation commits that reference the change proposal ID + +If both are in the same repository, you can omit `--code-repo` and it will use `--repo` for both purposes. + +--- + +## Content Sanitization + +When exporting to public repositories, use content sanitization to protect internal information: + +### What Gets Sanitized + +**Removed:** + +- Competitive analysis sections +- Market positioning statements +- Implementation details (file-by-file changes) +- Effort estimates and timelines +- Technical architecture details +- Internal strategy sections + +**Preserved:** + +- High-level feature descriptions +- User-facing value propositions +- Acceptance criteria +- External documentation links +- Use cases and examples + +### Usage + +```bash +# Public repository: sanitize content +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name public-repo \ + --sanitize \ + --target-repo your-org/public-repo \ + --repo /path/to/openspec-repo + +# Internal repository: use full content +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name internal-repo \ + --no-sanitize \ + --target-repo your-org/internal-repo \ + --repo /path/to/openspec-repo +``` + +### Auto-Detection + +SpecFact CLI automatically detects when to sanitize: + +- **Different repos** (code repo ≠ planning repo): Sanitization recommended (default: yes) +- **Same repo** (code repo = planning repo): Sanitization optional (default: no) + +You can override with `--sanitize` or `--no-sanitize` flags. + +--- + +## Code Change Tracking + +### How It Works + +When `--track-code-changes` is enabled: + +1. **Repository Selection**: Uses `--code-repo` if provided, otherwise uses `--repo` +2. **Git Commit Detection**: Searches git log for commits mentioning the change proposal ID +3. **File Change Tracking**: Extracts files modified in detected commits +4. **Progress Comment Generation**: Formats comment with commit details and file changes +5. **Duplicate Prevention**: Checks against existing comments to avoid duplicates +6. **Source Tracking Update**: Updates `proposal.md` with progress metadata + +### Commit Message Format + +Include the change proposal ID in your commit messages: + +```bash +# Good: Change ID clearly mentioned +git commit -m "feat: implement add-feature-x - initial API design" +git commit -m "fix: add-feature-x - resolve authentication issue" +git commit -m "docs: add-feature-x - update API documentation" + +# Also works: Change ID anywhere in message +git commit -m "Implement new feature + +- Add API endpoints +- Update database schema +- Related to add-feature-x" +``` + +### Progress Comment Format + +Progress comments include: + +- **Commit details**: Hash, message, author, date +- **Files changed**: Up to 10 files listed, then "and X more file(s)" +- **Detection timestamp**: When the change was detected + +**Example Comment:** + +``` +📊 **Code Change Detected** + +**Commit**: `364c8cfb` - feat: implement add-feature-x - initial API design +**Author**: @username +**Date**: 2025-12-30 +**Files Changed**: +- src/api/endpoints.py +- src/models/feature.py +- tests/test_feature.py +- and 2 more file(s) + +*Detected at: 2025-12-30T10:00:00Z* +``` + +### Progress Comment Sanitization + +When `--sanitize` is enabled, progress comments are sanitized: + +- **Commit messages**: Internal keywords removed, long messages truncated +- **File paths**: Replaced with file type counts (e.g., "3 py file(s)") +- **Author emails**: Removed, only username shown +- **Timestamps**: Date only (no time component) + +--- + +## Integration Workflow + +### Initial Setup (One-Time) + +1. **Create Change Proposal**: + + ```bash + mkdir -p openspec/changes/add-feature-x + # Edit openspec/changes/add-feature-x/proposal.md + ``` + +2. **Export to GitHub**: + + ```bash + specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo + ``` + +3. **Verify Issue Created**: + + ```bash + gh issue list --repo your-org/your-repo + ``` + +### Development Workflow (Ongoing) + +1. **Make Commits** with change ID in commit message: + + ```bash + git commit -m "feat: implement add-feature-x - initial API design" + ``` + +2. **Track Progress**: + + ```bash + specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --track-code-changes \ + --repo /path/to/openspec-repo \ + --code-repo /path/to/source-code-repo + ``` + +3. **Verify Comments Added**: + + ```bash + gh issue view --repo your-org/your-repo --json comments + ``` + +### Manual Progress Updates + +Add manual progress comments without code change detection: + +```bash +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --add-progress-comment \ + --repo /path/to/openspec-repo +``` + +--- + +## Advanced Features + +### Update Existing Issues + +Update issue bodies when proposal content changes: + +```bash +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --update-existing \ + --repo /path/to/openspec-repo +``` + +**Note**: Uses content hash to detect changes. Default: `False` for safety. + +### Proposal Filtering + +Proposals are filtered based on target repository type: + +**Public Repositories** (with `--sanitize`): + +- Only syncs proposals with status `"applied"` (archived/completed changes) +- Filters out `"proposed"`, `"in-progress"`, `"deprecated"`, or `"discarded"` + +**Internal Repositories** (with `--no-sanitize`): + +- Syncs all active proposals regardless of status + +### Duplicate Prevention + +Progress comments are deduplicated using SHA-256 hash: + +- First run: Comment added +- Second run: Comment skipped (duplicate detected) +- New commits: New comment added + +--- + +## Verification + +### Check Issue Creation + +```bash +# List issues +gh issue list --repo your-org/your-repo + +# View specific issue +gh issue view --repo your-org/your-repo +``` + +### Check Progress Comments + +```bash +# View latest comment +gh issue view --repo your-org/your-repo --json comments --jq '.comments[-1].body' + +# View all comments +gh issue view --repo your-org/your-repo --json comments +``` + +### Check Source Tracking + +Verify `openspec/changes//proposal.md` was updated: + +```markdown +## Source Tracking + +- **GitHub Issue**: #123 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + +``` + +--- + +## Troubleshooting + +### No Commits Detected + +**Problem**: Code changes not detected even though commits exist. + +**Solutions**: + +- Ensure commit messages include the change proposal ID (e.g., "add-feature-x") +- Verify `--code-repo` points to the correct source code repository +- Check that `last_code_change_detected` timestamp isn't in the future (reset if needed) + +### Wrong Repository + +**Problem**: Commits detected from wrong repository. + +**Solutions**: + +- Verify `--code-repo` parameter points to source code repository +- Check that OpenSpec repository (`--repo`) is correct +- Ensure both repositories are valid Git repositories + +### No Comments Added + +**Problem**: Progress comments not added to issues. + +**Solutions**: + +- Verify issues exist (create them first without `--track-code-changes`) +- Check GitHub token has write permissions +- Verify change proposal ID matches commit messages +- Check for duplicate comments (may be skipped) + +### Sanitization Issues + +**Problem**: Too much or too little content sanitized. + +**Solutions**: + +- Use `--sanitize` for public repos, `--no-sanitize` for internal repos +- Check auto-detection logic (different repos → sanitize, same repo → no sanitization) +- Review proposal content to ensure sensitive information is properly marked + +### Authentication Errors + +**Problem**: GitHub authentication fails. + +**Solutions**: + +- Verify GitHub token is valid: `gh auth status` +- Check token permissions (read/write access) +- Try using `--use-gh-cli` flag +- Verify `GITHUB_TOKEN` environment variable is set correctly + +--- + +## Best Practices + +### Commit Messages + +- Always include change proposal ID in commit messages +- Use descriptive commit messages that explain what was changed +- Follow conventional commit format: `type: change-id - description` + +### Repository Organization + +- Keep OpenSpec proposals in a dedicated repository for better organization +- Use `--code-repo` when OpenSpec and source code are separate +- Document repository structure in your team's documentation + +### Content Sanitization + +- Always sanitize when exporting to public repositories +- Review sanitized content before syncing to ensure nothing sensitive leaks +- Use `--no-sanitize` only for internal repositories + +### Progress Tracking + +- Run `--track-code-changes` regularly (e.g., after each commit or daily) +- Use manual progress comments for non-code updates (meetings, decisions, etc.) +- Verify comments are added correctly after each sync + +### Issue Management + +- Create issues first, then track code changes +- Use `--update-existing` sparingly (only when proposal content changes significantly) +- Monitor issue comments to ensure progress tracking is working + +--- + +## See Also + +### Related Guides + +- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations + +- [Command Chains Reference](command-chains.md) - Complete workflows including [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain) +- [Common Tasks Index](common-tasks.md) - Quick reference for DevOps integration tasks +- [OpenSpec Journey](openspec-journey.md) - OpenSpec integration with DevOps export +- [Agile/Scrum Workflows](agile-scrum-workflows.md) - Persona-based backlog management + +### Related Commands + +- [Command Reference - Sync Bridge](../reference/commands.md#sync-bridge) - Complete `sync bridge` command documentation +- [Command Reference - DevOps Adapters](../reference/commands.md#sync-bridge) - Adapter configuration + +### Related Examples + +- [DevOps Integration Examples](../examples/) - Real-world integration examples + +### Architecture & Troubleshooting + +- [Architecture](../reference/architecture.md) - System architecture and design +- [Troubleshooting](troubleshooting.md) - Common issues and solutions + +--- + +## Future Adapters + +Additional DevOps adapters are planned: + +- **Azure DevOps** (`--adapter ado`) - Work items and progress tracking +- **Linear** (`--adapter linear`) - Issues and progress updates +- **Jira** (`--adapter jira`) - Issues, epics, and sprint tracking + +These will follow similar patterns to GitHub Issues integration. Check the [Commands Reference](../reference/commands.md) for the latest adapter support. + +--- + +**Need Help?** + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_test/guides/dual-stack-enrichment.md b/_site_test/guides/dual-stack-enrichment.md new file mode 100644 index 0000000..be52231 --- /dev/null +++ b/_site_test/guides/dual-stack-enrichment.md @@ -0,0 +1,344 @@ +# Dual-Stack Enrichment Pattern + +**Status**: ✅ **AVAILABLE** (v0.13.0+) +**Last Updated**: 2025-12-23 +**Version**: v0.20.4 (enrichment parser improvements: story merging, format validation) + +--- + +## Overview + +The **Dual-Stack Enrichment Pattern** is SpecFact's approach to combining CLI automation with AI IDE (LLM) capabilities. It ensures that all artifacts are CLI-generated and validated, while allowing LLMs to add semantic understanding and enhancements. + +## Core Principle + +**ALWAYS use the SpecFact CLI as the primary tool**. LLM enrichment is a **secondary layer** that enhances CLI output with semantic understanding, but **never replaces CLI artifact creation**. + +## CLI vs LLM Capabilities + +### CLI-Only Operations (CI/CD Mode - No LLM Required) + +The CLI can perform these operations **without LLM**: + +- ✅ Tool execution (ruff, pylint, basedpyright, mypy, semgrep, specmatic) +- ✅ Bundle management (create, load, save, validate structure) +- ✅ Metadata management (timestamps, hashes, telemetry) +- ✅ Planning operations (init, add-feature, add-story, update-idea, update-feature) +- ✅ AST/Semgrep-based analysis (code structure, patterns, relationships) +- ✅ Specmatic validation (OpenAPI/AsyncAPI contract validation) +- ✅ Format validation (YAML/JSON schema compliance) +- ✅ Source tracking and drift detection + +**CRITICAL LIMITATIONS**: + +- ❌ **CANNOT generate code** - No LLM available in CLI-only mode +- ❌ **CANNOT do reasoning** - No semantic understanding without LLM + +### LLM-Required Operations (AI IDE Mode - Via Slash Prompts) + +These operations **require LLM** and are only available via AI IDE slash prompts: + +- ✅ Code generation (requires LLM reasoning) +- ✅ Code enhancement (contracts, refactoring, improvements) +- ✅ Semantic understanding (business logic, context, priorities) +- ✅ Plan enrichment (missing features, confidence adjustments, business context) +- ✅ Code reasoning (why decisions were made, trade-offs, constraints) + +**Access**: Only available via AI IDE slash prompts (Cursor, CoPilot, etc.) +**Pattern**: Slash prompt → LLM generates → CLI validates → Apply if valid + +## Three-Phase Workflow + +When working with AI IDE slash prompts, follow this three-phase workflow: + +### Phase 1: CLI Grounding (REQUIRED) + +```bash +# Execute CLI to get structured output +specfact [options] --no-interactive +``` + +**Capture**: + +- CLI-generated artifacts (plan bundles, reports) +- Metadata (timestamps, confidence scores) +- Telemetry (execution time, file counts) + +### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only) + +**Purpose**: Add semantic understanding to CLI output + +**What to do**: + +- Read CLI-generated artifacts (use file reading tools for display only) +- Research codebase for additional context +- Identify missing features/stories +- Suggest confidence adjustments +- Extract business context +- **CRITICAL**: Generate enrichment report in the exact format specified below (see "Enrichment Report Format" section) + +**What NOT to do**: + +- ❌ Create YAML/JSON artifacts directly +- ❌ Modify CLI artifacts directly (use CLI commands to update) +- ❌ Bypass CLI validation +- ❌ Write to `.specfact/` folder directly (always use CLI) +- ❌ Use direct file manipulation tools for writing (use CLI commands) +- ❌ Deviate from the enrichment report format (will cause parsing failures) + +**Output**: Generate enrichment report (Markdown) saved to `.specfact/projects//reports/enrichment/` (bundle-specific, Phase 8.5) + +**Enrichment Report Format** (REQUIRED for successful parsing): + +The enrichment parser expects a specific Markdown format. Follow this structure exactly: + +```markdown +# [Bundle Name] Enrichment Report + +**Date**: YYYY-MM-DDTHH:MM:SS +**Bundle**: + +--- + +## Missing Features + +1. **Feature Title** (Key: FEATURE-XXX) + - Confidence: 0.85 + - Outcomes: outcome1, outcome2, outcome3 + - Stories: + 1. Story title here + - Acceptance: criterion1, criterion2, criterion3 + 2. Another story title + - Acceptance: criterion1, criterion2 + +2. **Another Feature** (Key: FEATURE-YYY) + - Confidence: 0.80 + - Outcomes: outcome1, outcome2 + - Stories: + 1. Story title + - Acceptance: criterion1, criterion2, criterion3 + +## Confidence Adjustments + +- FEATURE-EXISTING-KEY: 0.90 (reason: improved understanding after code review) + +## Business Context + +- Priority: High priority feature for core functionality +- Constraint: Must support both REST and GraphQL APIs +- Risk: Potential performance issues with large datasets +``` + +**Format Requirements**: + +1. **Section Header**: Must use `## Missing Features` (case-insensitive, but prefer this exact format) +2. **Feature Format**: + - Numbered list: `1. **Feature Title** (Key: FEATURE-XXX)` + - **Bold title** is required (use `**Title**`) + - **Key in parentheses**: `(Key: FEATURE-XXX)` - must be uppercase, alphanumeric with hyphens/underscores + - Fields on separate lines with `-` prefix: + - `- Confidence: 0.85` (float between 0.0-1.0) + - `- Outcomes: comma-separated or line-separated list` + - `- Stories:` (required - each feature must have at least one story) +3. **Stories Format**: + - Numbered list under `Stories:` section: `1. Story title` + - **Indentation**: Stories must be indented (2-4 spaces) under the feature + - **Acceptance Criteria**: `- Acceptance: criterion1, criterion2, criterion3` + - Can be comma-separated on one line + - Or multi-line (each criterion on new line) + - Must start with `- Acceptance:` +4. **Optional Sections**: + - `## Confidence Adjustments`: List existing features with confidence updates + - `## Business Context`: Priorities, constraints, risks (bullet points) +5. **File Naming**: `-.enrichment.md` (e.g., `djangogoat-2025-12-23T23-50-00.enrichment.md`) + +**Example** (working format): + +```markdown +## Missing Features + +1. **User Authentication** (Key: FEATURE-USER-AUTHENTICATION) + - Confidence: 0.85 + - Outcomes: User registration, login, profile management + - Stories: + 1. User can sign up for new account + - Acceptance: sign_up view processes POST requests, creates User automatically, user is logged in after signup, redirects to profile page + 2. User can log in with credentials + - Acceptance: log_in view authenticates username/password, on success user is logged in and redirected, on failure error message is displayed +``` + +**Common Mistakes to Avoid**: + +- ❌ Missing `(Key: FEATURE-XXX)` - parser needs this to identify features +- ❌ Missing `Stories:` section - every feature must have at least one story +- ❌ Stories not indented - parser expects indented numbered lists +- ❌ Missing `- Acceptance:` prefix - acceptance criteria won't be parsed +- ❌ Using bullet points (`-`) instead of numbers (`1.`) for stories +- ❌ Feature title not in bold (`**Title**`) - parser may not extract title correctly + +**Important Notes**: + +- **Stories are merged**: When updating existing features (not creating new ones), stories from the enrichment report are merged into the existing feature. New stories are added, existing stories are preserved. +- **Feature titles updated**: If a feature exists but has an empty title, the enrichment report will update it. +- **Validation**: The enrichment parser validates the format and will fail with clear error messages if the format is incorrect. + +### Phase 3: CLI Artifact Creation (REQUIRED) + +```bash +# Use enrichment to update plan via CLI +specfact import from-code [] --repo --enrichment --no-interactive +``` + +**Result**: Final artifacts are CLI-generated with validated enrichments + +**What happens during enrichment application**: + +- Missing features are added with their stories and acceptance criteria +- Existing features are updated (confidence, outcomes, title if empty) +- Stories are merged into existing features (new stories added, existing preserved) +- Business context is applied to the plan bundle +- All changes are validated and saved via CLI + +## Standard Validation Loop Pattern (For LLM-Generated Code) + +When generating or enhancing code via LLM, **ALWAYS** follow this pattern: + +```text +1. CLI Prompt Generation (Required) + ↓ + CLI generates structured prompt → saved to .specfact/prompts/ + (e.g., `generate contracts-prompt`, future: `generate code-prompt`) + +2. LLM Execution (Required - AI IDE Only) + ↓ + LLM reads prompt → generates enhanced code → writes to TEMPORARY file + (NEVER writes directly to original artifacts) + Pattern: `enhanced_.py` or `generated_.py` + +3. CLI Validation Loop (Required, up to N retries) + ↓ + CLI validates temp file with all relevant tools: + - Syntax validation (py_compile) + - File size check (must be >= original) + - AST structure comparison (preserve functions/classes) + - Contract imports verification + - Code quality checks (ruff, pylint, basedpyright, mypy) + - Test execution (contract-test, pytest) + ↓ + If validation fails: + - CLI provides detailed error feedback + - LLM fixes issues in temp file + - Re-validate (max 3 attempts) + ↓ + If validation succeeds: + - CLI applies changes to original file + - CLI removes temporary file + - CLI updates metadata/telemetry +``` + +**This pattern must be used for**: + +- ✅ Contract enhancement (`generate contracts-prompt` / `contracts-apply`) - Already implemented +- ⏳ Code generation (future: `generate code-prompt` / `code-apply`) - Needs implementation +- ⏳ Plan enrichment (future: `plan enrich-prompt` / `enrich-apply`) - Needs implementation +- ⏳ Any LLM-enhanced artifact modification - Needs implementation + +## Example: Contract Enhancement Workflow + +This is a real example of the validation loop pattern in action: + +### Step 1: Generate Prompt + +```bash +specfact generate contracts-prompt src/auth/login.py --apply beartype,icontract --bundle legacy-api +``` + +**Result**: Prompt saved to `.specfact/projects/legacy-api/prompts/enhance-login-beartype-icontract.md` + +### Step 2: LLM Enhances Code + +1. AI IDE reads the prompt file +2. AI IDE reads the original file (`src/auth/login.py`) +3. AI IDE generates enhanced code with contracts +4. AI IDE writes to temporary file: `enhanced_login.py` +5. **DO NOT modify original file directly** + +### Step 3: Validate and Apply + +```bash +specfact generate contracts-apply enhanced_login.py --original src/auth/login.py +``` + +**Validation includes**: + +- Syntax validation +- File size check +- AST structure comparison +- Contract imports verification +- Code quality checks +- Test execution + +**If validation fails**: + +- Review error messages +- Fix issues in `enhanced_login.py` +- Re-run validation (up to 3 attempts) + +**If validation succeeds**: + +- CLI applies changes to `src/auth/login.py` +- CLI removes `enhanced_login.py` +- CLI updates metadata/telemetry + +## Why This Pattern? + +### Benefits + +- ✅ **Format Consistency**: All artifacts match CLI schema versions +- ✅ **Traceability**: CLI metadata tracks who/what/when +- ✅ **Validation**: CLI ensures schema compliance +- ✅ **Reliability**: Works in both Copilot and CI/CD +- ✅ **No Format Drift**: CLI-generated artifacts always match current schema + +### What Happens If You Don't Follow + +- ❌ Artifacts may not match CLI schema versions +- ❌ Missing metadata and telemetry +- ❌ Format inconsistencies +- ❌ Validation failures +- ❌ Works only in Copilot mode, fails in CI/CD +- ❌ Code generation attempts in CLI-only mode will fail (no LLM available) + +## Rules + +1. **Execute CLI First**: Always run CLI commands before any analysis +2. **Use CLI for Writes**: All write operations must go through CLI +3. **Read for Display Only**: Use file reading tools for display/analysis only +4. **Never Modify .specfact/**: Do not create/modify files in `.specfact/` directly +5. **Never Bypass Validation**: CLI ensures schema compliance and metadata +6. **Code Generation Requires LLM**: Code generation is only possible via AI IDE slash prompts, not CLI-only +7. **Use Validation Loop**: All LLM-generated code must follow the validation loop pattern + +## Available CLI Commands + +- `specfact plan init ` - Initialize project bundle +- `specfact plan select ` - Set active plan (used as default for other commands) +- `specfact import from-code [] --repo ` - Import from codebase (uses active plan if bundle not specified) +- `specfact plan review []` - Review plan (uses active plan if bundle not specified) +- `specfact plan harden []` - Create SDD manifest (uses active plan if bundle not specified) +- `specfact enforce sdd []` - Validate SDD (uses active plan if bundle not specified) +- `specfact generate contracts-prompt --apply ` - Generate contract enhancement prompt +- `specfact generate contracts-apply --original ` - Validate and apply enhanced code +- `specfact sync bridge --adapter --repo ` - Sync with external tools +- See [Command Reference](../reference/commands.md) for full list + +**Note**: Most commands now support active plan fallback. If `--bundle` is not specified, commands automatically use the active plan set via `plan select`. This improves workflow efficiency in AI IDE environments. + +--- + +## Related Documentation + +- **[Architecture Documentation](../reference/architecture.md)** - Enforcement rules and quality gates +- **[Operational Modes](../reference/modes.md)** - CI/CD vs Copilot modes +- **[IDE Integration](ide-integration.md)** - Setting up slash commands +- **[Command Reference](../reference/commands.md)** - Complete command reference diff --git a/_site_test/guides/ide-integration/index.html b/_site_test/guides/ide-integration/index.html new file mode 100644 index 0000000..fa1f3dd --- /dev/null +++ b/_site_test/guides/ide-integration/index.html @@ -0,0 +1,571 @@ + + + + + + + +IDE Integration with SpecFact CLI | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

IDE Integration with SpecFact CLI

+ +

Status: ✅ AVAILABLE (v0.4.2+)
+Last Updated: 2025-11-09

+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

+ +

Terminal Output: The CLI automatically detects embedded terminals (Cursor, VS Code) and CI/CD environments, adapting output formatting automatically. Progress indicators work in all environments - see Troubleshooting for details.

+ +
+ +

Overview

+ +

SpecFact CLI supports IDE integration through prompt templates that work with various AI-assisted IDEs. These templates are copied to IDE-specific locations and automatically registered by the IDE as slash commands.

+ +

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via IDE integrations

+ +

Supported IDEs:

+ +
    +
  • ✅ Cursor - .cursor/commands/
    • +
  • ✅ VS Code / GitHub Copilot - .github/prompts/ + .vscode/settings.json
    • +
  • ✅ Claude Code - .claude/commands/
    • +
  • ✅ Gemini CLI - .gemini/commands/
    • +
  • ✅ Qwen Code - .qwen/commands/
    • +
  • ✅ opencode - .opencode/command/
    • +
  • ✅ Windsurf - .windsurf/workflows/
    • +
  • ✅ Kilo Code - .kilocode/workflows/
    • +
  • ✅ Auggie - .augment/commands/
    • +
  • ✅ Roo Code - .roo/commands/
    • +
  • ✅ CodeBuddy - .codebuddy/commands/
    • +
  • ✅ Amp - .agents/commands/
    • +
  • ✅ Amazon Q Developer - .amazonq/prompts/
    • +
+ +
+ +

Quick Start

+ +

Step 1: Initialize IDE Integration

+ +

Run the specfact init command in your repository:

+ +
# Auto-detect IDE
+specfact init
+
+# Or specify IDE explicitly
+specfact init --ide cursor
+specfact init --ide vscode
+specfact init --ide copilot
+
+# Install required packages for contract enhancement
+specfact init --install-deps
+
+# Initialize for specific IDE and install dependencies
+specfact init --ide cursor --install-deps
+
+ +

What it does:

+ +
    +
  1. Detects your IDE (or uses --ide flag)
    2. +
  2. Copies prompt templates from resources/prompts/ to IDE-specific location
    3. +
  3. Creates/updates VS Code settings if needed
    4. +
  4. Makes slash commands available in your IDE
    5. +
  5. Optionally installs required packages for contract enhancement (if --install-deps is provided): +
      +
    • beartype>=0.22.4 - Runtime type checking
      • +
    • icontract>=2.7.1 - Design-by-contract decorators
      • +
    • crosshair-tool>=0.0.97 - Contract exploration
      • +
    • pytest>=8.4.2 - Testing framework
      • +
    +
    6. +
+ +

Step 2: Use Slash Commands in Your IDE

+ +

Once initialized, you can use slash commands directly in your IDE’s AI chat:

+ +

In Cursor / VS Code / Copilot:

+ +
# Core workflow commands (numbered for natural progression)
+/specfact.01-import legacy-api --repo .
+/specfact.02-plan init legacy-api
+/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth"
+/specfact.03-review legacy-api
+/specfact.04-sdd legacy-api
+/specfact.05-enforce legacy-api
+/specfact.06-sync --adapter speckit --repo . --bidirectional
+/specfact.07-contracts legacy-api --apply all-contracts  # Analyze, generate prompts, apply contracts sequentially
+
+# Advanced commands
+/specfact.compare --bundle legacy-api
+/specfact.validate --repo .
+
+ +

The IDE automatically recognizes these commands and provides enhanced prompts.

+ +
+ +

How It Works

+ +

Prompt Templates

+ +

Slash commands are markdown prompt templates (not executable CLI commands). They:

+ +
    +
  1. Live in your repository - Templates are stored in resources/prompts/ (packaged with SpecFact CLI)
    2. +
  2. Get copied to IDE locations - specfact init copies them to IDE-specific directories
    3. +
  3. Registered automatically - The IDE reads these files and makes them available as slash commands
    4. +
  4. Provide enhanced prompts - Templates include detailed instructions for the AI assistant
    5. +
+ +

Template Format

+ +

Each template follows this structure:

+ +
---
+description: Command description for IDE display
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+
+ +

Goal

+ +

Detailed instructions for the AI assistant…

+ +

Execution Steps

+ +
    +
  1. +

    Parse arguments…

    +
    2. +
  2. +

    Execute command…

    +
    3. +
  3. +

    Generate output…

    +
    4. +
+ +

+### IDE Registration
+
+**How IDEs discover slash commands:**
+
+- **VS Code / Copilot**: Reads `.github/prompts/*.prompt.md` files listed in `.vscode/settings.json` under `chat.promptFilesRecommendations`
+- **Cursor**: Automatically discovers `.cursor/commands/*.md` files
+- **Other IDEs**: Follow their respective discovery mechanisms
+
+---
+
+## Available Slash Commands
+
+**Complete Reference**: [Prompts README](/specfact-cli/prompts/README.md) - Full slash commands reference with examples
+
+**Workflow Guide**: [AI IDE Workflow Guide](/specfact-cli/ai-ide-workflow/) - Complete workflow from setup to validation
+
+## Available Slash Commands
+
+**Core Workflow Commands** (numbered for workflow ordering):
+
+| Command | Description | CLI Equivalent |
+|---------|-------------|----------------|
+| `/specfact.01-import` | Import codebase into plan bundle | `specfact import from-code <bundle-name>` |
+| `/specfact.02-plan` | Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) | `specfact plan <operation> <bundle-name>` |
+| `/specfact.03-review` | Review plan and promote through stages | `specfact plan review <bundle-name>`, `specfact plan promote <bundle-name>` |
+| `/specfact.04-sdd` | Create SDD manifest from plan | `specfact plan harden <bundle-name>` |
+| `/specfact.05-enforce` | Validate SDD and contracts | `specfact enforce sdd <bundle-name>` |
+| `/specfact.06-sync` | Sync with external tools or repository | `specfact sync bridge --adapter <adapter>` |
+| `/specfact.07-contracts` | Contract enhancement workflow: analyze → generate prompts → apply sequentially | `specfact analyze contracts`, `specfact generate contracts-prompt`, `specfact generate contracts-apply` |
+
+**Advanced Commands** (no numbering):
+
+| Command | Description | CLI Equivalent |
+|---------|-------------|----------------|
+| `/specfact.compare` | Compare manual vs auto plans | `specfact plan compare` |
+| `/specfact.validate` | Run validation suite | `specfact repro` |
+| `/specfact.generate-contracts-prompt` | Generate AI IDE prompt for adding contracts | `specfact generate contracts-prompt <file> --apply <contracts>` |
+
+---
+
+## Examples
+
+### Example 1: Initialize for Cursor
+
+```bash
+# Run init in your repository
+cd /path/to/my-project
+specfact init --ide cursor
+
+# Output:
+# ✓ Initialization Complete
+# Copied 5 template(s) to .cursor/commands/
+#
+# You can now use SpecFact slash commands in Cursor!
+# Example: /specfact.01-import legacy-api --repo .
+
+ +

Now in Cursor:

+ +
    +
  1. Open Cursor AI chat
    2. +
  2. Type /specfact.01-import legacy-api --repo .
    3. +
  3. Cursor recognizes the command and provides enhanced prompts
    4. +
+ +

Example 2: Initialize for VS Code / Copilot

+ +
# Run init in your repository
+specfact init --ide vscode
+
+# Output:
+# ✓ Initialization Complete
+# Copied 5 template(s) to .github/prompts/
+# Updated VS Code settings: .vscode/settings.json
+
+
+ +

VS Code settings.json:

+ +
{
+  "chat": {
+    "promptFilesRecommendations": [
+      ".github/prompts/specfact.01-import.prompt.md",
+      ".github/prompts/specfact.02-plan.prompt.md",
+      ".github/prompts/specfact.03-review.prompt.md",
+      ".github/prompts/specfact.04-sdd.prompt.md",
+      ".github/prompts/specfact.05-enforce.prompt.md",
+      ".github/prompts/specfact.06-sync.prompt.md",
+      ".github/prompts/specfact.07-contracts.prompt.md",
+      ".github/prompts/specfact.compare.prompt.md",
+      ".github/prompts/specfact.validate.prompt.md"
+    ]
+  }
+}
+
+ +

Example 3: Update Templates

+ +

If you update SpecFact CLI, run init again to update templates:

+ +
# Re-run init to update templates (use --force to overwrite)
+specfact init --ide cursor --force
+
+ +
+ +

Advanced Usage

+ +

Custom Template Locations

+ +

By default, templates are copied from SpecFact CLI’s package resources. To use custom templates:

+ +
    +
  1. Create your own templates in a custom location
    2. +
  2. Modify specfact init to use custom path (future feature)
    3. +
+ +

IDE-Specific Customization

+ +

Different IDEs may require different template formats:

+ +
    +
  • Markdown (Cursor, Claude, etc.): Direct .md files
    • +
  • TOML (Gemini, Qwen): Converted to TOML format automatically
    • +
  • VS Code: .prompt.md files with settings.json integration
    • +
+ +

The specfact init command handles all conversions automatically.

+ +
+ +

Troubleshooting

+ +

Slash Commands Not Showing in IDE

+ +

Issue: Commands don’t appear in IDE autocomplete

+ +

Solutions:

+ +
    +
  1. +

    Verify files exist:

    + + 
    ls .cursor/commands/specfact-*.md  # For Cursor
+ls .github/prompts/specfact-*.prompt.md  # For VS Code
+
+
    +
    2. +
  2. +

    Re-run init:

    + + 
    specfact init --ide cursor --force
+
    +
    3. +
  3. +

    Restart IDE: Some IDEs require restart to discover new commands

    +
    4. +
+ +

VS Code Settings Not Updated

+ +

Issue: VS Code settings.json not created or updated

+ +

Solutions:

+ +
    +
  1. +

    Check permissions:

    + + 
    ls -la .vscode/settings.json
+
+
    +
    2. +
  2. +

    Manually verify settings.json:

    + + 
    {
+  "chat": {
+    "promptFilesRecommendations": [...]
+  }
+}
+
+
    +
    3. +
  3. +

    Re-run init:

    + + 
    specfact init --ide vscode --force
+
    +
    4. +
+ +
+ + + + + +
+ +

Next Steps

+ +
    +
  • ⭐ Integration Showcases - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations
    • +
  • ✅ Initialize IDE integration with specfact init
    • +
  • ✅ Use slash commands in your IDE
    • +
  • 📖 Read CoPilot Mode Guide for CLI usage
    • +
  • 📖 Read Command Reference for all commands
    • +
+ +
+ +

Trademarks: All product names, logos, and brands mentioned in this guide are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See TRADEMARKS.md for more information.

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/guides/integrations-overview.md b/_site_test/guides/integrations-overview.md new file mode 100644 index 0000000..79f74cd --- /dev/null +++ b/_site_test/guides/integrations-overview.md @@ -0,0 +1,263 @@ +# Integrations Overview + +> **Comprehensive guide to all SpecFact CLI integrations** +> Understand when to use each integration and how they work together + +--- + +## Overview + +SpecFact CLI integrates with multiple tools and platforms to provide a complete spec-driven development ecosystem. This guide provides an overview of all available integrations, when to use each, and how they complement each other. + +--- + +## Integration Categories + +SpecFact CLI integrations fall into four main categories: + +1. **Specification Tools** - Tools for creating and managing specifications +2. **Testing & Validation** - Tools for contract testing and validation +3. **DevOps & Backlog** - Tools for syncing change proposals and tracking progress +4. **IDE & Development** - Tools for AI-assisted development workflows + +--- + +## Specification Tools + +### Spec-Kit Integration + +**Purpose**: Interactive specification authoring for new features + +**What it provides**: + +- ✅ Interactive slash commands (`/speckit.specify`, `/speckit.plan`) with AI assistance +- ✅ Rapid prototyping workflow: spec → plan → tasks → code +- ✅ Constitution and planning for new features +- ✅ IDE integration with CoPilot chat + +**When to use**: + +- Creating new features from scratch (greenfield development) +- Interactive specification authoring with AI assistance +- Learning and exploration of state machines and contracts +- Single-developer projects and rapid prototyping + +**Key difference**: Spec-Kit focuses on **new feature authoring**, while SpecFact CLI focuses on **brownfield code modernization**. + +**See also**: [Spec-Kit Journey Guide](./speckit-journey.md) + +--- + +### OpenSpec Integration + +**Purpose**: Specification anchoring and change tracking + +**What it provides**: + +- ✅ Source-of-truth specifications (`openspec/specs/`) documenting what IS built +- ✅ Change tracking with delta specs (ADDED/MODIFIED/REMOVED) +- ✅ Structured change proposals (`openspec/changes/`) with rationale and tasks +- ✅ Cross-repository support (specs can live separately from code) +- ✅ Spec-driven development workflow: proposal → delta specs → implementation → archive + +**When to use**: + +- Managing specifications as source of truth +- Tracking changes with structured proposals +- Cross-repository workflows (specs in different repos than code) +- Team collaboration on specifications and change proposals + +**Key difference**: OpenSpec manages **what should be built** (proposals) and **what is built** (specs), while SpecFact CLI adds **brownfield analysis** and **runtime enforcement**. + +**See also**: [OpenSpec Journey Guide](./openspec-journey.md) + +--- + +## Testing & Validation + +### Specmatic Integration + +**Purpose**: API contract testing and validation + +**What it provides**: + +- ✅ OpenAPI/AsyncAPI specification validation +- ✅ Backward compatibility checking between spec versions +- ✅ Mock server generation from specifications +- ✅ Test suite generation from specs +- ✅ Service-level contract testing (complements SpecFact's code-level contracts) + +**When to use**: + +- Validating API specifications (OpenAPI/AsyncAPI) +- Checking backward compatibility when updating API versions +- Running mock servers for frontend/client development +- Generating contract tests from specifications +- Service-level contract validation (complements code-level contracts) + +**Key difference**: Specmatic provides **API-level contract testing**, while SpecFact CLI provides **code-level contract enforcement** (icontract, beartype, CrossHair). + +**See also**: [Specmatic Integration Guide](./specmatic-integration.md) + +--- + +## DevOps & Backlog + +### DevOps Adapter Integration + +**Purpose**: Sync change proposals to DevOps backlog tools and track progress + +**What it provides**: + +- ✅ Export OpenSpec change proposals to GitHub Issues (or other DevOps tools) +- ✅ Automatic progress tracking via code change detection +- ✅ Content sanitization for public repositories +- ✅ Separate repository support (OpenSpec proposals and code in different repos) +- ✅ Automated comment annotations on issues + +**Supported adapters**: + +- **GitHub Issues** (`--adapter github`) - ✅ Full support +- **Azure DevOps** (`--adapter ado`) - Planned +- **Linear** (`--adapter linear`) - Planned +- **Jira** (`--adapter jira`) - Planned + +**When to use**: + +- Syncing OpenSpec change proposals to GitHub Issues +- Tracking implementation progress automatically +- Managing change proposals in DevOps backlog tools +- Coordinating between OpenSpec repositories and code repositories + +**Key difference**: DevOps adapters provide **backlog integration and progress tracking**, while OpenSpec provides **specification management**. + +**See also**: [DevOps Adapter Integration Guide](./devops-adapter-integration.md) + +--- + +## IDE & Development + +### AI IDE Integration + +**Purpose**: AI-assisted development workflows with slash commands + +**What it provides**: + +- ✅ Setup process (`init --ide cursor`) for IDE integration +- ✅ Slash commands for common workflows +- ✅ Prompt generation → AI IDE → validation loop +- ✅ Integration with command chains +- ✅ AI-assisted specification and planning + +**When to use**: + +- AI-assisted development workflows +- Using slash commands for common tasks +- Integrating SpecFact CLI with Cursor, VS Code + Copilot +- Streamlining development workflows with AI assistance + +**Key difference**: AI IDE integration provides **interactive AI assistance**, while command chains provide **automated workflows**. + +**See also**: [AI IDE Workflow Guide](./ai-ide-workflow.md), [IDE Integration Guide](./ide-integration.md) + +--- + +## Integration Decision Tree + +Use this decision tree to determine which integrations to use: + +```text +Start: What do you need? + +├─ Need to work with existing code? +│ └─ ✅ Use SpecFact CLI `import from-code` (brownfield analysis) +│ +├─ Need to create new features interactively? +│ └─ ✅ Use Spec-Kit integration (greenfield development) +│ +├─ Need to manage specifications as source of truth? +│ └─ ✅ Use OpenSpec integration (specification anchoring) +│ +├─ Need API contract testing? +│ └─ ✅ Use Specmatic integration (API-level contracts) +│ +├─ Need to sync change proposals to backlog? +│ └─ ✅ Use DevOps adapter integration (GitHub Issues, etc.) +│ +└─ Need AI-assisted development? + └─ ✅ Use AI IDE integration (slash commands, AI workflows) +``` + +--- + +## Integration Combinations + +### Common Workflows + +#### 1. Brownfield Modernization with OpenSpec + +- Use SpecFact CLI `import from-code` to analyze existing code +- Export to OpenSpec for specification anchoring +- Use OpenSpec change proposals for tracking improvements +- Sync proposals to GitHub Issues via DevOps adapter + +#### 2. Greenfield Development with Spec-Kit + +- Use Spec-Kit for interactive specification authoring +- Add SpecFact CLI enforcement for runtime contracts +- Use Specmatic for API contract testing +- Integrate with AI IDE for streamlined workflows + +#### 3. Full Stack Development + +- Use Spec-Kit/OpenSpec for specification management +- Use SpecFact CLI for code-level contract enforcement +- Use Specmatic for API-level contract testing +- Use DevOps adapter for backlog integration +- Use AI IDE integration for development workflows + +--- + +## Quick Reference + +| Integration | Primary Use Case | Key Command | Documentation | +|------------|------------------|-------------|---------------| +| **Spec-Kit** | Interactive spec authoring for new features | `/speckit.specify` | [Spec-Kit Journey](./speckit-journey.md) | +| **OpenSpec** | Specification anchoring and change tracking | `openspec validate` | [OpenSpec Journey](./openspec-journey.md) | +| **Specmatic** | API contract testing and validation | `spec validate` | [Specmatic Integration](./specmatic-integration.md) | +| **DevOps Adapter** | Sync proposals to backlog tools | `sync bridge --adapter github` | [DevOps Integration](./devops-adapter-integration.md) | +| **AI IDE** | AI-assisted development workflows | `init --ide cursor` | [AI IDE Workflow](./ai-ide-workflow.md) | + +--- + +## Getting Started + +1. **Choose your primary integration** based on your use case: + - Working with existing code? → Start with SpecFact CLI brownfield analysis + - Creating new features? → Start with Spec-Kit integration + - Managing specifications? → Start with OpenSpec integration + +2. **Add complementary integrations** as needed: + - Need API testing? → Add Specmatic + - Need backlog sync? → Add DevOps adapter + - Want AI assistance? → Add AI IDE integration + +3. **Follow the detailed guides** for each integration you choose + +--- + +## See Also + +- [Command Chains Guide](./command-chains.md) - Complete workflows using integrations +- [Common Tasks Guide](./common-tasks.md) - Quick reference for common integration tasks +- [Team Collaboration Workflow](./team-collaboration-workflow.md) - Using integrations in teams +- [Migration Guide](./migration-guide.md) - Migrating between integrations + +--- + +## Related Workflows + +- [Brownfield Modernization Chain](./command-chains.md#brownfield-modernization-chain) - Using SpecFact CLI with existing code +- [API Contract Development Chain](./command-chains.md#api-contract-development-chain) - Using Specmatic for API testing +- [Spec-Driven Development Chain](./command-chains.md#spec-driven-development-chain) - Using OpenSpec for spec management +- [AI IDE Workflow Chain](./command-chains.md#ai-ide-workflow-chain) - Using AI IDE integration diff --git a/_site_test/guides/migration-0.16-to-0.19.md b/_site_test/guides/migration-0.16-to-0.19.md new file mode 100644 index 0000000..646196e --- /dev/null +++ b/_site_test/guides/migration-0.16-to-0.19.md @@ -0,0 +1,174 @@ +# Migration Guide: v0.16.x to v0.20.0 LTS + +This guide helps you upgrade from SpecFact CLI v0.16.x to v0.20.0 LTS (Long-Term Stable). + +## Overview + +v0.17.0 - v0.20.0 are part of the **0.x stabilization track** leading to v0.20.0 LTS. + +### Key Changes + +| Version | Changes | +|---------|---------| +| **0.17.0** | Deprecated `implement` command, added bridge commands, version management | +| **0.18.0** | Updated documentation positioning, AI IDE bridge workflow | +| **0.19.0** | Full test coverage for Phase 7, migration guide | +| **0.20.0 LTS** | Long-Term Stable release - production-ready analysis and enforcement | + +--- + +## Breaking Changes + +### `implement` Command Deprecated + +The `implement tasks` command was deprecated in v0.17.0 and removed in v0.22.0. The `generate tasks` command was also removed in v0.22.0. + +**Before (v0.16.x):** + +```bash +specfact implement tasks .specfact/projects/my-bundle/tasks.yaml +``` + +**After (v0.17.0+):** + +Use the new bridge commands instead: + +```bash +# Set up CrossHair for contract exploration (one-time setup, only available since v0.20.1) +specfact repro setup + +# Analyze and validate your codebase +specfact repro --verbose + +# Generate AI-ready prompt to fix a gap +specfact generate fix-prompt GAP-001 --bundle my-bundle + +# Generate AI-ready prompt to add tests +specfact generate test-prompt src/auth/login.py --bundle my-bundle +``` + +### `run idea-to-ship` Removed + +The `run idea-to-ship` command has been removed in v0.17.0. + +**Rationale:** Code generation features are being redesigned for v1.0 with AI-assisted workflows. + +--- + +## New Features + +### Bridge Commands (v0.17.0) + +New commands that generate AI-ready prompts for your IDE: + +```bash +# Generate fix prompt for a gap +specfact generate fix-prompt GAP-001 + +# Generate test prompt for a file +specfact generate test-prompt src/module.py --type unit +``` + +### Version Management (v0.17.0) + +New commands for managing bundle versions: + +```bash +# Check for recommended version bump +specfact project version check --bundle my-bundle + +# Bump version (major/minor/patch) +specfact project version bump --bundle my-bundle --type minor + +# Set explicit version +specfact project version set --bundle my-bundle --version 2.0.0 +``` + +### CI Version Check (v0.17.0) + +GitHub Actions template now includes version check with configurable modes: + +- `info` - Informational only +- `warn` (default) - Log warnings, continue CI +- `block` - Fail CI if version bump not followed + +--- + +## Upgrade Steps + +### Step 1: Update SpecFact CLI + +```bash +pip install -U specfact-cli +# or +uvx specfact-cli@latest --version +``` + +### Step 2: Verify Version + +```bash +specfact --version +# Should show: SpecFact CLI version 0.19.0 +``` + +### Step 3: Update Workflows + +If you were using `implement tasks` or `run idea-to-ship`, migrate to bridge commands: + +**Old workflow:** + +```bash +# REMOVED in v0.22.0 - Use Spec-Kit, OpenSpec, or other SDD tools instead +# specfact generate tasks --bundle my-bundle +# specfact implement tasks .specfact/projects/my-bundle/tasks.yaml +``` + +**New workflow:** + +```bash +# 1. Analyze and validate your codebase +specfact repro --verbose + +# 2. Generate AI prompts for each gap +specfact generate fix-prompt GAP-001 --bundle my-bundle + +# 3. Copy prompt to AI IDE, get fix, apply + +# 4. Validate +specfact enforce sdd --bundle my-bundle +``` + +### Step 4: Update CI/CD (Optional) + +Add version check to your GitHub Actions: + +```yaml +- name: Version Check + run: specfact project version check --bundle ${{ env.BUNDLE_NAME }} + env: + SPECFACT_VERSION_CHECK_MODE: warn # or 'info' or 'block' +``` + +--- + +## FAQ + +### Q: Why was `implement` deprecated? + +**A:** The `implement` command attempted to generate code directly, but this approach doesn't align with the Ultimate Vision for v1.0. In v1.0, AI copilots will consume structured data from SpecFact and generate code, with SpecFact validating the results. The bridge commands provide a transitional workflow. + +### Q: Can I still use v0.16.x? + +**A:** Yes, v0.16.x will continue to work. However, we recommend upgrading to v0.20.0 LTS for the latest fixes, features, and long-term stability. v0.20.0 is the Long-Term Stable (LTS) release and will receive bug fixes and security updates until v1.0 GA. + +### Q: When will v1.0 be released? + +**A:** See the [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) for the v1.0 roadmap. + +--- + +## Support + +- 💬 **Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 **Found a bug?** [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 **Need help?** [hello@noldai.com](mailto:hello@noldai.com) diff --git a/_site_test/guides/migration-cli-reorganization.md b/_site_test/guides/migration-cli-reorganization.md new file mode 100644 index 0000000..20c3a2a --- /dev/null +++ b/_site_test/guides/migration-cli-reorganization.md @@ -0,0 +1,293 @@ +# CLI Reorganization Migration Guide + +**Date**: 2025-11-27 +**Version**: 0.9.3+ + +This guide helps you migrate from the old command structure to the new reorganized structure, including parameter standardization, slash command changes, and bundle parameter integration. + +--- + +## Overview of Changes + +The CLI reorganization includes: + +1. **Parameter Standardization** - Consistent parameter names across all commands +2. **Parameter Grouping** - Logical organization (Target → Output → Behavior → Advanced) +3. **Slash Command Reorganization** - Reduced from 13 to 8 commands with numbered workflow ordering +4. **Bundle Parameter Integration** - All commands now use `--bundle` parameter + +--- + +## Parameter Name Changes + +### Standard Parameter Names + +| Old Name | New Name | Commands Affected | +|----------|----------|-------------------| +| `--base-path` | `--repo` | `generate contracts` | +| `--output` | `--out` | `bridge constitution bootstrap` | +| `--format` | `--output-format` | `enforce sdd`, `plan compare` | +| `--non-interactive` | `--no-interactive` | All commands | +| `--name` (bundle name) | `--bundle` | All commands | + +### Deprecation Policy + +- **Transition Period**: 3 months from implementation date (2025-11-27) +- **Deprecation Warnings**: Commands using deprecated names will show warnings +- **Removal**: Deprecated names will be removed after transition period +- **Documentation**: All examples and docs updated immediately + +### Examples + +**Before**: + +```bash +specfact import from-code --bundle legacy-api --repo . +specfact plan compare --bundle legacy-api --output-format json --out report.json +specfact enforce sdd legacy-api --no-interactive +``` + +**After**: + +```bash +specfact import from-code --bundle legacy-api --repo . +specfact plan compare --bundle legacy-api --output-format json --out report.json +specfact enforce sdd legacy-api --no-interactive +``` + +--- + +## Slash Command Changes + +### Old Slash Commands (13 total) → New Slash Commands (8 total) + +| Old Command | New Command | Notes | +|-------------|-------------|-------| +| `/specfact-import-from-code` | `/specfact.01-import` | Numbered for workflow ordering | +| `/specfact-plan-init` | `/specfact.02-plan` | Unified plan management | +| `/specfact-plan-add-feature` | `/specfact.02-plan` | Merged into plan command | +| `/specfact-plan-add-story` | `/specfact.02-plan` | Merged into plan command | +| `/specfact-plan-update-idea` | `/specfact.02-plan` | Merged into plan command | +| `/specfact-plan-update-feature` | `/specfact.02-plan` | Merged into plan command | +| `/specfact-plan-review` | `/specfact.03-review` | Numbered for workflow ordering | +| `/specfact-plan-promote` | `/specfact.03-review` | Merged into review command | +| `/specfact-plan-compare` | `/specfact.compare` | Advanced command (no numbering) | +| `/specfact-enforce` | `/specfact.05-enforce` | Numbered for workflow ordering | +| `/specfact-sync` | `/specfact.06-sync` | Numbered for workflow ordering | +| `/specfact-repro` | `/specfact.validate` | Advanced command (no numbering) | +| `/specfact-plan-select` | *(CLI-only)* | Removed (use CLI directly) | + +### Workflow Ordering + +The new numbered commands follow natural workflow progression: + +1. **Import** (`/specfact.01-import`) - Start by importing existing code +2. **Plan** (`/specfact.02-plan`) - Manage your plan bundle +3. **Review** (`/specfact.03-review`) - Review and promote your plan +4. **SDD** (`/specfact.04-sdd`) - Create SDD manifest +5. **Enforce** (`/specfact.05-enforce`) - Validate SDD and contracts +6. **Sync** (`/specfact.06-sync`) - Sync with external tools + +**Advanced Commands** (no numbering): + +- `/specfact.compare` - Compare plans +- `/specfact.validate` - Validation suite + +### Ordered Workflow Examples + +**Before**: + +```bash +/specfact-import-from-code --repo . --confidence 0.7 +/specfact-plan-init my-project +/specfact-plan-add-feature --key FEATURE-001 --title "User Auth" +/specfact-plan-review my-project +``` + +**After**: + +```bash +/specfact.01-import legacy-api --repo . --confidence 0.7 +/specfact.02-plan init legacy-api +/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth" +/specfact.03-review legacy-api +``` + +--- + +## Bundle Parameter Addition + +### All Commands Now Require `--bundle` + +**Before** (positional argument): + +```bash +specfact import from-code --bundle legacy-api --repo . +specfact plan init --bundle legacy-api +specfact plan review --bundle legacy-api +``` + +**After** (named parameter): + +```bash +specfact import from-code --bundle legacy-api --repo . +specfact plan init --bundle legacy-api +specfact plan review --bundle legacy-api +``` + +### Path Resolution Changes + +- **Old**: Used positional argument or `--name` for bundle identification +- **New**: Uses `--bundle` parameter for bundle name +- **Path**: Bundle path is resolved from bundle name: `.specfact/projects//` + +### Migration Steps + +1. **Update all scripts** to use `--bundle` instead of positional arguments +2. **Update CI/CD pipelines** to use new parameter format +3. **Update IDE slash commands** to use new numbered format +4. **Test workflows** to ensure bundle resolution works correctly + +--- + +## Command Path Changes + +### Constitution Commands + +**Current Command**: + +```bash +specfact sdd constitution bootstrap +specfact sdd constitution enrich +specfact sdd constitution validate +``` + +**Note**: The old `specfact constitution` command has been removed. All constitution functionality is now available under `specfact sdd constitution`. + +--- + +## Why the Change? + +The constitution commands are **Spec-Kit adapter commands** - they're only needed when syncing with Spec-Kit or working in Spec-Kit format. They are now under the `sdd` (Spec-Driven Development) command group, as constitution management is part of the SDD workflow. + +**Benefits**: + +- Clearer command organization (adapters grouped together) +- Better aligns with bridge architecture +- Makes it obvious these are for external tool integration + +--- + +## Command Changes + +The old `specfact constitution` command has been removed. Use `specfact sdd constitution` instead: + +```bash +$ specfact constitution bootstrap --repo . +⚠ Breaking Change: The 'specfact constitution' command has been removed. +Please use 'specfact sdd constitution' instead. +Example: 'specfact constitution bootstrap' → 'specfact sdd constitution bootstrap' + +[bold cyan]Generating bootstrap constitution for:[/bold cyan] . +... +``` + +--- + +## Updated Workflows + +### Brownfield Import Workflow + +```bash +specfact import from-code --bundle legacy-api --repo . +specfact sdd constitution bootstrap --repo . +specfact sync bridge --adapter speckit +``` + +### Constitution Management Workflow + +```bash +specfact sdd constitution bootstrap --repo . +specfact sdd constitution validate +specfact sdd constitution enrich --repo . +``` + +--- + +## CI/CD Updates + +Update your CI/CD pipelines to use the new command paths: + +**GitHub Actions Example**: + +```yaml +- name: Validate Constitution + run: specfact sdd constitution validate +``` + +**GitLab CI Example**: + +```yaml +validate_constitution: + script: + - specfact sdd constitution validate +``` + +--- + +## Script Updates + +Update any scripts that use the old commands: + +**Bash Script Example**: + +```bash +#!/bin/bash +# Old +# specfact constitution bootstrap --repo . + +# New +specfact sdd constitution bootstrap --repo . +``` + +**Python Script Example**: + +```python +# Old +# subprocess.run(["specfact", "constitution", "bootstrap", "--repo", "."]) + +# New +subprocess.run(["specfact", "bridge", "constitution", "bootstrap", "--repo", "."]) +``` + +--- + +## IDE Integration + +If you're using IDE slash commands, update your prompts: + +**Old**: + +```bash +/specfact-constitution-bootstrap --repo . +``` + +**New**: + +```bash +/specfact.bridge.constitution.bootstrap --repo . +``` + +--- + +## Questions? + +If you encounter any issues during migration: + +1. Check the [Command Reference](../reference/commands.md) for updated examples +2. Review the [Troubleshooting Guide](./troubleshooting.md) +3. Open an issue on GitHub + +--- + +**Last Updated**: 2025-01-27 diff --git a/_site_test/guides/openspec-journey.md b/_site_test/guides/openspec-journey.md new file mode 100644 index 0000000..e0d5027 --- /dev/null +++ b/_site_test/guides/openspec-journey.md @@ -0,0 +1,512 @@ +# The Journey: OpenSpec + SpecFact Integration + +> **OpenSpec and SpecFact are complementary, not competitive.** +> **Primary Use Case**: OpenSpec for specification anchoring and change tracking +> **Secondary Use Case**: SpecFact adds brownfield analysis, runtime enforcement, and DevOps integration + +--- + +## 🎯 Why Integrate? + +### **What OpenSpec Does Great** + +OpenSpec is **excellent** for: + +- ✅ **Specification Anchoring** - Source-of-truth specifications (`openspec/specs/`) that document what IS built +- ✅ **Change Tracking** - Delta specs (ADDED/MODIFIED/REMOVED) that document what SHOULD change +- ✅ **Change Proposals** - Structured proposals (`openspec/changes/`) with rationale, impact, and tasks +- ✅ **Cross-Repository Support** - Specifications can live in separate repositories from code +- ✅ **Spec-Driven Development** - Clear workflow: proposal → delta specs → implementation → archive +- ✅ **Team Collaboration** - Shared specifications and change proposals for coordination + +**Note**: OpenSpec excels at **managing specifications and change proposals** - it provides the "what" and "why" for changes, but doesn't analyze existing code or enforce contracts. + +### **What OpenSpec Is Designed For (vs. SpecFact CLI)** + +OpenSpec **is designed primarily for**: + +- ✅ **Specification Management** - Source-of-truth specs (`openspec/specs/`) and change proposals (`openspec/changes/`) +- ✅ **Change Tracking** - Delta specs (ADDED/MODIFIED/REMOVED) that document proposed changes +- ✅ **Cross-Repository Workflows** - Specifications can be in different repos than code +- ✅ **Spec-Driven Development** - Clear proposal → implementation → archive workflow + +OpenSpec **is not designed primarily for** (but SpecFact CLI provides): + +- ⚠️ **Brownfield Analysis** - **Not designed for reverse-engineering from existing code** + - OpenSpec focuses on documenting what SHOULD be built (proposals) and what IS built (specs) + - **This is where SpecFact CLI complements OpenSpec** 🎯 +- ⚠️ **Runtime Contract Enforcement** - Not designed for preventing regressions with executable contracts +- ⚠️ **Code2Spec Extraction** - Not designed for automatically extracting specs from legacy code +- ⚠️ **DevOps Integration** - Not designed for syncing change proposals to GitHub Issues, ADO, Linear, Jira +- ⚠️ **Automated Validation** - Not designed for CI/CD gates or automated contract validation +- ⚠️ **Symbolic Execution** - Not designed for discovering edge cases with CrossHair + +### **When to Integrate** + +| Need | OpenSpec Solution | SpecFact Solution | +|------|------------------|-------------------| +| **Work with existing code** ⭐ **PRIMARY** | ⚠️ **Not designed for** - Focuses on spec authoring | ✅ **`import from-code`** ⭐ - Reverse-engineer existing code to plans (PRIMARY use case) | +| **Sync change proposals to DevOps** | ⚠️ **Not designed for** - Manual process | ✅ **`sync bridge --adapter github`** ✅ - Export proposals to GitHub Issues (IMPLEMENTED) | +| **Track code changes** | ⚠️ **Not designed for** - Manual tracking | ✅ **`--track-code-changes`** ✅ - Auto-detect commits and add progress comments (IMPLEMENTED) | +| **Runtime enforcement** | Manual validation | ✅ **Contract enforcement** - Prevent regressions with executable contracts | +| **Code vs spec alignment** | Manual comparison | ✅ **Alignment reports** ⏳ - Compare SpecFact features vs OpenSpec specs (PLANNED) | +| **Brownfield modernization** | Manual spec authoring | ✅ **Brownfield analysis** ⭐ - Extract specs from legacy code automatically | + +--- + +## 🌱 The Integration Vision + +### **Complete Brownfield Modernization Stack** + +When modernizing legacy code, you can use **both tools together** for maximum value: + +```mermaid +graph TB + subgraph "OpenSpec: Specification Management" + OS1[openspec/specs/
Source-of-Truth Specs] + OS2[openspec/changes/
Change Proposals] + OS3[Delta Specs
ADDED/MODIFIED/REMOVED] + end + + subgraph "SpecFact: Code Analysis & Enforcement" + SF1[import from-code
Extract specs from code] + SF2[Runtime Contracts
Prevent regressions] + SF3[Bridge Adapters
Sync to DevOps] + end + + subgraph "DevOps Integration" + GH[GitHub Issues] + ADO[Azure DevOps] + LIN[Linear] + end + + OS2 -->|Export| SF3 + SF3 -->|Create Issues| GH + SF3 -->|Create Issues| ADO + SF3 -->|Create Issues| LIN + + SF1 -->|Compare| OS1 + OS1 -->|Validate| SF2 + + style OS1 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style OS2 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style OS3 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style SF1 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF2 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF3 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style GH fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff + style ADO fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff + style LIN fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff +``` + +**The Power of Integration:** + +1. **OpenSpec** manages specifications and change proposals (the "what" and "why") +2. **SpecFact** analyzes existing code and enforces contracts (the "how" and "safety") +3. **Bridge Adapters** sync change proposals to DevOps tools (the "tracking") +4. **Together** they form a complete brownfield modernization solution + +--- + +## 🚀 The Integration Journey + +### **Stage 1: DevOps Export** ✅ **IMPLEMENTED** + +**Time**: < 5 minutes + +**What's Available Now:** + +Export OpenSpec change proposals to GitHub Issues and track implementation progress: + +```bash +# Step 1: Create change proposal in OpenSpec +mkdir -p openspec/changes/add-feature-x +cat > openspec/changes/add-feature-x/proposal.md << 'EOF' +# Change: Add Feature X + +## Why +Add new feature X to improve user experience. + +## What Changes +- Add API endpoints +- Update database schema +- Add frontend components + +## Impact +- Affected specs: api, frontend +- Affected code: src/api/, src/frontend/ +EOF + +# Step 2: Export to GitHub Issues +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo +``` + +**What You Get:** + +- ✅ **Issue Creation** - OpenSpec change proposals become GitHub Issues automatically +- ✅ **Progress Tracking** - Code changes detected and progress comments added automatically +- ✅ **Content Sanitization** - Protect internal information when syncing to public repos +- ✅ **Separate Repository Support** - OpenSpec proposals and source code can be in different repos + +**Visual Flow:** + +```mermaid +sequenceDiagram + participant Dev as Developer + participant OS as OpenSpec + participant SF as SpecFact CLI + participant GH as GitHub Issues + + Dev->>OS: Create change proposal
openspec/changes/add-feature-x/ + Dev->>SF: specfact sync bridge --adapter github + SF->>OS: Read proposal.md + SF->>GH: Create issue from proposal + GH-->>SF: Issue #123 created + SF->>OS: Update proposal.md
with issue tracking + + Note over Dev,GH: Implementation Phase + + Dev->>Dev: Make commits with change ID + Dev->>SF: specfact sync bridge --track-code-changes + SF->>SF: Detect commits mentioning
change ID + SF->>GH: Add progress comment
to issue #123 + GH-->>Dev: Progress visible in issue + + rect rgb(59, 130, 246) + Note over OS: OpenSpec
Specification Management + end + + rect rgb(249, 115, 22) + Note over SF: SpecFact CLI
Code Analysis & Enforcement + end + + rect rgb(100, 116, 139) + Note over GH: DevOps
Backlog Tracking + end +``` + +**Key Insight**: OpenSpec proposals become actionable DevOps backlog items automatically! + +--- + +### **Stage 2: OpenSpec Bridge Adapter** ✅ **IMPLEMENTED** + +**Time**: Available now (v0.22.0+) + +**What's Available:** + +Read-only sync from OpenSpec to SpecFact for change proposal tracking: + +```bash +# Sync OpenSpec change proposals to SpecFact +specfact sync bridge --adapter openspec --mode read-only \ + --bundle my-project \ + --repo /path/to/openspec-repo + +# The adapter reads OpenSpec change proposals from openspec/changes/ +# and syncs them to SpecFact change tracking +``` + +**What You Get:** + +- ✅ **Change Proposal Import** - OpenSpec change proposals synced to SpecFact bundles +- ✅ **Change Tracking** - Track OpenSpec proposals in SpecFact format +- ✅ **Read-Only Sync** - Import from OpenSpec without modifying OpenSpec files +- ⏳ **Alignment Reports** - Compare OpenSpec specs vs code-derived features (planned) +- ⏳ **Gap Detection** - Identify OpenSpec specs not found in code (planned) +- ⏳ **Coverage Calculation** - Measure how well code matches specifications (planned) + +**Visual Flow:** + +```mermaid +graph LR + subgraph "OpenSpec Repository" + OS1[openspec/specs/
Source-of-Truth] + OS2[openspec/changes/
Proposals] + end + + subgraph "SpecFact Analysis" + SF1[import from-code
Extract features] + SF2[Alignment Report
Compare specs vs code] + end + + OS1 -->|Import| SF2 + SF1 -->|Compare| SF2 + SF2 -->|Gap Report| Dev[Developer] + + style OS1 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style OS2 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style SF1 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF2 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style Dev fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff +``` + +**Key Insight**: Validate that your code matches OpenSpec specifications automatically! + +--- + +### **Stage 3: Bidirectional Sync** ⏳ **PLANNED** + +**Time**: Future enhancement + +**What's Coming:** + +Full bidirectional sync between OpenSpec and SpecFact: + +```bash +# Bidirectional sync (future) +specfact sync bridge --adapter openspec --bidirectional \ + --bundle my-project \ + --repo /path/to/openspec-repo \ + --watch +``` + +**What You'll Get:** + +- ⏳ **Spec Sync** - OpenSpec specs ↔ SpecFact features +- ⏳ **Change Sync** - OpenSpec proposals ↔ SpecFact change tracking +- ⏳ **Conflict Resolution** - Automatic conflict resolution with priority rules +- ⏳ **Watch Mode** - Real-time sync as files change + +**Visual Flow:** + +```mermaid +graph TB + subgraph "OpenSpec" + OS1[Specs] + OS2[Change Proposals] + end + + subgraph "SpecFact" + SF1[Features] + SF2[Change Tracking] + end + + OS1 <-->|Bidirectional| SF1 + OS2 <-->|Bidirectional| SF2 + + style OS1 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style OS2 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style SF1 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF2 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff +``` + +**Key Insight**: Keep OpenSpec and SpecFact in perfect sync automatically! + +--- + +## 📋 Complete Workflow Example + +### **Brownfield Modernization with OpenSpec + SpecFact** + +Here's how to use both tools together for legacy code modernization: + +```bash +# Step 1: Analyze legacy code with SpecFact +specfact import from-code --bundle legacy-api --repo ./legacy-app +# → Extracts features from existing code +# → Creates SpecFact bundle: .specfact/projects/legacy-api/ + +# Step 2: Create OpenSpec change proposal +mkdir -p openspec/changes/modernize-api +cat > openspec/changes/modernize-api/proposal.md << 'EOF' +# Change: Modernize Legacy API + +## Why +Legacy API needs modernization for better performance and maintainability. + +## What Changes +- Refactor API endpoints +- Add contract validation +- Update database schema + +## Impact +- Affected specs: api, database +- Affected code: src/api/, src/db/ +EOF + +# Step 3: Export proposal to GitHub Issues ✅ IMPLEMENTED +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo + +# Step 4: Implement changes +git commit -m "feat: modernize-api - refactor endpoints" + +# Step 5: Track progress ✅ IMPLEMENTED +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --track-code-changes \ + --repo /path/to/openspec-repo \ + --code-repo /path/to/source-code-repo + +# Step 6: Sync OpenSpec change proposals ✅ AVAILABLE +specfact sync bridge --adapter openspec --mode read-only \ + --bundle legacy-api \ + --repo /path/to/openspec-repo +# → Generates alignment report +# → Shows gaps between OpenSpec specs and code + +# Step 7: Add runtime contracts +specfact enforce stage --preset balanced + +# Step 8: Archive completed change +openspec archive modernize-api +``` + +**Complete Flow:** + +```mermaid +graph TB + Start[Start: Legacy Code] --> SF1[SpecFact: Extract Features] + SF1 --> OS1[OpenSpec: Create Proposal] + OS1 --> SF2[SpecFact: Export to GitHub] + SF2 --> GH[GitHub: Issue Created] + GH --> Dev[Developer: Implement] + Dev --> SF3[SpecFact: Track Progress] + SF3 --> GH2[GitHub: Progress Comments] + GH2 --> SF4[SpecFact: Validate Alignment] + SF4 --> SF5[SpecFact: Add Contracts] + SF5 --> OS2[OpenSpec: Archive Change] + OS2 --> End[End: Modernized Code] + + style Start fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff + style End fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff + style SF1 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF2 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF3 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF4 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style SF5 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff + style OS1 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style OS2 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff + style GH fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff + style GH2 fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff + style Dev fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff +``` + +--- + +## 🎯 Implementation Status + +### ✅ **Implemented Features** + +| Feature | Status | Description | +|---------|--------|-------------| +| **DevOps Export** | ✅ **Available** | Export OpenSpec change proposals to GitHub Issues | +| **Code Change Tracking** | ✅ **Available** | Detect commits and add progress comments automatically | +| **Content Sanitization** | ✅ **Available** | Protect internal information for public repos | +| **Separate Repository Support** | ✅ **Available** | OpenSpec proposals and source code in different repos | +| **Progress Comments** | ✅ **Available** | Automated progress comments with commit details | + +### ⏳ **Planned Features** + +| Feature | Status | Description | +|---------|--------|-------------| +| **OpenSpec Bridge Adapter** | ✅ **Available** | Read-only sync from OpenSpec to SpecFact (v0.22.0+) | +| **Alignment Reports** | ⏳ **Planned** | Compare OpenSpec specs vs code-derived features | +| **Specification Import** | ⏳ **Planned** | Import OpenSpec specs into SpecFact bundles | +| **Bidirectional Sync** | ⏳ **Future** | Full bidirectional sync between OpenSpec and SpecFact | +| **Watch Mode** | ⏳ **Future** | Real-time sync as files change | + +--- + +## 💡 Key Insights + +### **The "Aha!" Moment** + +**OpenSpec** = The "what" and "why" (specifications and change proposals) +**SpecFact** = The "how" and "safety" (code analysis and contract enforcement) +**Together** = Complete brownfield modernization solution + +### **Why This Integration Matters** + +1. **OpenSpec** provides structured change proposals and source-of-truth specifications +2. **SpecFact** extracts features from legacy code and enforces contracts +3. **Bridge Adapters** sync proposals to DevOps tools for team visibility +4. **Alignment Reports** (planned) validate that code matches specifications + +### **The Power of Separation** + +- **OpenSpec Repository**: Specifications and change proposals (the "plan") +- **Source Code Repository**: Actual implementation (the "code") +- **SpecFact**: Bridges the gap between plan and code + +This separation enables: + +- ✅ **Cross-Repository Workflows** - Specs in one repo, code in another +- ✅ **Team Collaboration** - Product owners manage specs, developers implement code +- ✅ **Clear Separation of Concerns** - Specifications separate from implementation + +--- + +## See Also + +### Related Guides + +- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations + +- [Command Chains Reference](command-chains.md) - Complete workflows including [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain) +- [Common Tasks Index](common-tasks.md) - Quick reference for OpenSpec integration tasks +- [DevOps Adapter Integration](devops-adapter-integration.md) - GitHub Issues and backlog tracking +- [Team Collaboration Workflow](team-collaboration-workflow.md) - Team collaboration patterns + +### Related Commands + +- [Command Reference - Import Commands](../reference/commands.md#import---import-from-external-formats) - `import from-bridge` reference +- [Command Reference - Sync Commands](../reference/commands.md#sync-bridge) - `sync bridge` reference +- [Command Reference - DevOps Adapters](../reference/commands.md#sync-bridge) - Adapter configuration + +### Related Examples + +- [OpenSpec Integration Examples](../examples/) - Real-world integration examples + +### Getting Started + +- [Getting Started](../getting-started/README.md) - Quick setup guide +- [Architecture](../reference/architecture.md) - System architecture and design + +--- + +## 📚 Next Steps + +### **Try It Now** ✅ + +1. **[DevOps Adapter Integration Guide](devops-adapter-integration.md)** - Export OpenSpec proposals to GitHub Issues +2. **[Commands Reference](../reference/commands.md#sync-bridge)** - Complete `sync bridge` documentation +3. **[OpenSpec Documentation](https://github.com/nold-ai/openspec)** - Learn OpenSpec basics + +### **Available Now** ✅ + +1. **OpenSpec Bridge Adapter** - Read-only sync for change proposal tracking (v0.22.0+) + +### **Coming Soon** ⏳ + +1. **Alignment Reports** - Compare OpenSpec specs vs code-derived features +2. **Bidirectional Sync** - Keep OpenSpec and SpecFact in sync +3. **Watch Mode** - Real-time synchronization + +--- + +## 🔗 Related Documentation + +- **[DevOps Adapter Integration](devops-adapter-integration.md)** - GitHub Issues and backlog tracking +- **[Spec-Kit Journey](speckit-journey.md)** - Similar guide for Spec-Kit integration +- **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete brownfield modernization workflow +- **[Commands Reference](../reference/commands.md)** - Complete command documentation + +--- + +**Need Help?** + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) + +--- + +**Remember**: OpenSpec manages specifications, SpecFact analyzes code. Together they form a complete brownfield modernization solution! 🚀 diff --git a/_site_test/guides/speckit-comparison.md b/_site_test/guides/speckit-comparison.md new file mode 100644 index 0000000..d80214e --- /dev/null +++ b/_site_test/guides/speckit-comparison.md @@ -0,0 +1,361 @@ +# How SpecFact Compares to GitHub Spec-Kit + +> **Complementary positioning: When to use Spec-Kit, SpecFact, or both together** + +--- + +## TL;DR: Complementary, Not Competitive + +**Spec-Kit excels at:** Documentation, greenfield specs, multi-language support +**SpecFact excels at:** Runtime enforcement, edge case discovery, high-risk brownfield + +**Use both together:** + +1. Use Spec-Kit for initial spec generation (fast, LLM-powered) +2. Use SpecFact to add runtime contracts to critical paths (safety net) +3. Spec-Kit generates docs, SpecFact prevents regressions + +--- + +## Quick Comparison + +| Capability | GitHub Spec-Kit | SpecFact CLI | When to Choose | +|-----------|----------------|--------------|----------------| +| **Code2spec (brownfield analysis)** | ✅ LLM-generated markdown specs | ✅ AST + contracts extraction | SpecFact for executable contracts | +| **Runtime enforcement** | ❌ No | ✅ icontract + beartype | **SpecFact only** | +| **Symbolic execution** | ❌ No | ✅ CrossHair SMT solver | **SpecFact only** | +| **Edge case discovery** | ⚠️ LLM suggests (probabilistic) | ✅ Mathematical proof (deterministic) | SpecFact for formal guarantees | +| **Regression prevention** | ⚠️ Code review (human) | ✅ Contract violation (automated) | SpecFact for automated safety net | +| **Multi-language** | ✅ 10+ languages | ⚠️ Python (Q1: +JS/TS) | Spec-Kit for multi-language | +| **GitHub integration** | ✅ Native slash commands | ✅ GitHub Actions + CLI | Spec-Kit for native integration | +| **Learning curve** | ✅ Low (markdown + slash commands) | ⚠️ Medium (decorators + contracts) | Spec-Kit for ease of use | +| **High-risk brownfield** | ⚠️ Good documentation | ✅ Formal verification | **SpecFact for high-risk** | +| **Free tier** | ✅ Open-source | ✅ Apache 2.0 | Both free | + +--- + +## Detailed Comparison + +### Code Analysis (Brownfield) + +**GitHub Spec-Kit:** + +- Uses LLM (Copilot) to generate markdown specs from code +- Fast, but probabilistic (may miss details) +- Output: Markdown documentation + +**SpecFact CLI:** + +- Uses AST analysis + LLM hybrid for precise extraction +- Generates executable contracts, not just documentation +- Output: YAML plans + Python contract decorators + +**Winner:** SpecFact for executable contracts, Spec-Kit for quick documentation + +### Runtime Enforcement + +**GitHub Spec-Kit:** + +- ❌ No runtime validation +- Specs are documentation only +- Human review catches violations (if reviewer notices) + +**SpecFact CLI:** + +- ✅ Runtime contract enforcement (icontract + beartype) +- Contracts catch violations automatically +- Prevents regressions during modernization + +**Winner:** SpecFact (core differentiation) + +### Edge Case Discovery + +**GitHub Spec-Kit:** + +- ⚠️ LLM suggests edge cases based on training data +- Probabilistic (may miss edge cases) +- Depends on LLM having seen similar patterns + +**SpecFact CLI:** + +- ✅ CrossHair symbolic execution +- Mathematical proof of edge cases +- Explores all feasible code paths + +**Winner:** SpecFact (formal guarantees) + +### Regression Prevention + +**GitHub Spec-Kit:** + +- ⚠️ Code review catches violations (if reviewer notices) +- Spec-code divergence possible (documentation drift) +- No automated enforcement + +**SpecFact CLI:** + +- ✅ Contract violations block execution automatically +- Impossible to diverge (contract = executable truth) +- Automated safety net during modernization + +**Winner:** SpecFact (automated enforcement) + +### Multi-Language Support + +**GitHub Spec-Kit:** + +- ✅ 10+ languages (Python, JS, TS, Go, Ruby, etc.) +- Native support for multiple ecosystems + +**SpecFact CLI:** + +- ⚠️ Python only (Q1 2026: +JavaScript/TypeScript) +- Focused on Python brownfield market + +**Winner:** Spec-Kit (broader language support) + +### GitHub Integration + +**GitHub Spec-Kit:** + +- ✅ Native slash commands in GitHub +- Integrated with Copilot +- Seamless GitHub workflow + +**SpecFact CLI:** + +- ✅ GitHub Actions integration +- CLI tool (works with any Git host) +- Not GitHub-specific + +**Winner:** Spec-Kit for native GitHub integration, SpecFact for flexibility + +--- + +## When to Use Spec-Kit + +### Use Spec-Kit For + +- **Greenfield projects** - Starting from scratch with specs +- **Rapid prototyping** - Fast spec generation with LLM +- **Multi-language teams** - Support for 10+ languages +- **Documentation focus** - Want markdown specs, not runtime enforcement +- **GitHub-native workflows** - Already using Copilot, want native integration + +### Example Use Case (Spec-Kit) + +**Scenario:** Starting a new React + Node.js project + +**Why Spec-Kit:** + +- Multi-language support (React + Node.js) +- Fast spec generation with Copilot +- Native GitHub integration +- Documentation-focused workflow + +--- + +## When to Use SpecFact + +### Use SpecFact For + +- **High-risk brownfield modernization** - Finance, healthcare, government +- **Runtime enforcement needed** - Can't afford production bugs +- **Edge case discovery** - Need formal guarantees, not LLM suggestions +- **Contract-first culture** - Already using Design-by-Contract, TDD +- **Python-heavy codebases** - Data engineering, ML pipelines, DevOps + +### Example Use Case (SpecFact) + +**Scenario:** Modernizing legacy Python payment system + +**Why SpecFact:** + +- Runtime contract enforcement prevents regressions +- CrossHair discovers hidden edge cases +- Formal guarantees (not probabilistic) +- Safety net during modernization + +--- + +## When to Use Both Together + +### ✅ Best of Both Worlds + +**Workflow:** + +1. **Spec-Kit** generates initial specs (fast, LLM-powered) +2. **SpecFact** adds runtime contracts to critical paths (safety net) +3. **Spec-Kit** maintains documentation (living specs) +4. **SpecFact** prevents regressions (contract enforcement) + +### Example Use Case + +**Scenario:** Modernizing multi-language codebase (Python backend + React frontend) + +**Why Both:** + +- **Spec-Kit** for React frontend (multi-language support) +- **SpecFact** for Python backend (runtime enforcement) +- **Spec-Kit** for documentation (markdown specs) +- **SpecFact** for safety net (contract enforcement) + +**Integration:** + +```bash +# Step 1: Use Spec-Kit for initial spec generation +# (Interactive slash commands in GitHub) + +# Step 2: Import Spec-Kit artifacts into SpecFact (via bridge adapter) +specfact import from-bridge --adapter speckit --repo ./my-project + +# Step 3: Add runtime contracts to critical Python paths +# (SpecFact contract decorators) + +# Step 4: Keep both in sync (using adapter registry pattern) +specfact sync bridge --adapter speckit --bundle --repo . --bidirectional +``` + +**Note**: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. + +--- + +## Competitive Positioning + +### Spec-Kit's Strengths + +- ✅ **Multi-language support** - 10+ languages +- ✅ **Native GitHub integration** - Slash commands, Copilot +- ✅ **Fast spec generation** - LLM-powered, interactive +- ✅ **Low learning curve** - Markdown + slash commands +- ✅ **Greenfield focus** - Designed for new projects + +### SpecFact's Strengths + +- ✅ **Runtime enforcement** - Contracts prevent regressions +- ✅ **Symbolic execution** - CrossHair discovers edge cases +- ✅ **Formal guarantees** - Mathematical verification +- ✅ **Brownfield-first** - Designed for legacy code +- ✅ **High-risk focus** - Finance, healthcare, government + +### Where They Overlap + +- ⚠️ **Low-risk brownfield** - Internal tools, non-critical systems + - **Spec-Kit:** Fast documentation, good enough + - **SpecFact:** Slower setup, overkill for low-risk + - **Winner:** Spec-Kit (convenience > rigor for low-risk) + +- ⚠️ **Documentation + enforcement** - Teams want both + - **Spec-Kit:** Use for specs, add tests manually + - **SpecFact:** Use for contracts, generate markdown from contracts + - **Winner:** Depends on team philosophy (docs-first vs. contracts-first) + +--- + +## FAQ + +### Can I use Spec-Kit and SpecFact together? + +**Yes!** They're complementary: + +1. Use Spec-Kit for initial spec generation (fast, LLM-powered) +2. Use SpecFact to add runtime contracts to critical paths (safety net) +3. Keep both in sync with bidirectional sync + +### Which should I choose for brownfield projects? + +**Depends on risk level:** + +- **High-risk** (finance, healthcare, government): **SpecFact** (runtime enforcement) +- **Low-risk** (internal tools, non-critical): **Spec-Kit** (fast documentation) +- **Mixed** (multi-language, some high-risk): **Both** (Spec-Kit for docs, SpecFact for enforcement) + +### Does SpecFact replace Spec-Kit? + +**No.** They serve different purposes: + +- **Spec-Kit:** Documentation, greenfield, multi-language +- **SpecFact:** Runtime enforcement, brownfield, formal guarantees + +Use both together for best results. + +### Does SpecFact work with other specification tools? + +**Yes!** SpecFact CLI uses a plugin-based adapter architecture that supports multiple tools: + +- **Spec-Kit** - Bidirectional sync for interactive authoring +- **OpenSpec** - Read-only sync for change proposal tracking (v0.22.0+) +- **GitHub Issues** - Export change proposals to DevOps backlogs +- **Future**: Linear, Jira, Azure DevOps, and more + +All adapters are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. + +### Can I migrate from Spec-Kit to SpecFact? + +**Yes.** SpecFact can import Spec-Kit artifacts: + +```bash +specfact import from-bridge --adapter speckit --repo ./my-project +``` + +You can also keep using both tools with bidirectional sync via the adapter registry pattern. + +### Does SpecFact work with OpenSpec? + +**Yes!** SpecFact CLI integrates with OpenSpec via the OpenSpec adapter (v0.22.0+): + +```bash +# Read-only sync from OpenSpec to SpecFact +specfact sync bridge --adapter openspec --mode read-only \ + --bundle my-project \ + --repo /path/to/openspec-repo +``` + +OpenSpec focuses on specification anchoring and change tracking, while SpecFact adds brownfield analysis and runtime enforcement. **[Learn more →](openspec-journey.md)** + +--- + +## Decision Matrix + +### Choose Spec-Kit If + +- ✅ Starting greenfield project +- ✅ Need multi-language support +- ✅ Want fast LLM-powered spec generation +- ✅ Documentation-focused workflow +- ✅ Low-risk brownfield project + +### Choose SpecFact If + +- ✅ Modernizing high-risk legacy code +- ✅ Need runtime contract enforcement +- ✅ Want formal guarantees (not probabilistic) +- ✅ Python-heavy codebase +- ✅ Contract-first development culture + +### Choose Both If + +- ✅ Multi-language codebase (some high-risk) +- ✅ Want documentation + enforcement +- ✅ Team uses Spec-Kit, but needs safety net +- ✅ Gradual migration path desired + +--- + +## Next Steps + +1. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete modernization workflow +2. **[Spec-Kit Journey](speckit-journey.md)** - Migration from Spec-Kit +3. **[Examples](../examples/)** - Real-world examples + +--- + +## Support + +- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- 📧 [hello@noldai.com](mailto:hello@noldai.com) + +--- + +**Questions?** [Open a discussion](https://github.com/nold-ai/specfact-cli/discussions) or [email us](mailto:hello@noldai.com). diff --git a/_site_test/guides/speckit-journey/index.html b/_site_test/guides/speckit-journey/index.html new file mode 100644 index 0000000..c574b29 --- /dev/null +++ b/_site_test/guides/speckit-journey/index.html @@ -0,0 +1,826 @@ + + + + + + + +The Journey: From Spec-Kit to SpecFact | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

The Journey: From Spec-Kit to SpecFact

+ +
+

Spec-Kit and SpecFact are complementary, not competitive.
+Primary Use Case: SpecFact CLI for brownfield code modernization
+Secondary Use Case: Add SpecFact enforcement to Spec-Kit’s interactive authoring for new features

+
+ +
+ +

🎯 Why Level Up?

+ +

What Spec-Kit Does Great

+ +

Spec-Kit is excellent for:

+ +
    +
  • ✅ Interactive Specification - Slash commands (/speckit.specify, /speckit.plan) with AI assistance
    • +
  • ✅ Rapid Prototyping - Quick spec → plan → tasks → code workflow for NEW features
    • +
  • ✅ Learning & Exploration - Great for understanding state machines, contracts, requirements
    • +
  • ✅ IDE Integration - CoPilot chat makes it accessible to less technical developers
    • +
  • ✅ Constitution & Planning - Add constitution, plans, and feature breakdowns for new features
    • +
  • ✅ Single-Developer Projects - Perfect for personal projects and learning
    • +
+ +

Note: Spec-Kit excels at working with new features - you can add constitution, create plans, and break down features for things you’re building from scratch.

+ +

What Spec-Kit Is Designed For (vs. SpecFact CLI)

+ +

Spec-Kit is designed primarily for:

+ +
    +
  • ✅ Greenfield Development - Interactive authoring of new features via slash commands
    • +
  • ✅ Specification-First Workflow - Natural language → spec → plan → tasks → code
    • +
  • ✅ Interactive AI Assistance - CoPilot chat-based specification and planning
    • +
  • ✅ New Feature Planning - Add constitution, plans, and feature breakdowns for new features
    • +
+ +

Spec-Kit is not designed primarily for (but SpecFact CLI provides):

+ +
    +
  • ⚠️ Work with Existing Code - Not designed primarily for analyzing existing repositories or iterating on existing features +
      +
    • Spec-Kit allows you to add constitution, plans, and feature breakdowns for NEW features via interactive slash commands
      • +
    • Current design focuses on greenfield development and interactive authoring
      • +
    • This is the primary area where SpecFact CLI complements Spec-Kit 🎯
      • +
    +
    • +
  • ⚠️ Brownfield Analysis - Not designed primarily for reverse-engineering from existing code
    • +
  • ⚠️ Automated Enforcement - Not designed for CI/CD gates or automated contract validation
    • +
  • ⚠️ Team Collaboration - Not designed for shared plans or deviation detection between developers
    • +
  • ⚠️ Production Quality Gates - Not designed for proof bundles or budget-based enforcement
    • +
  • ⚠️ Multi-Repository Sync - Not designed for cross-repo consistency validation
    • +
  • ⚠️ Deterministic Execution - Designed for interactive AI interactions rather than scriptable automation
    • +
+ +

When to Level Up

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NeedSpec-Kit SolutionSpecFact Solution
Work with existing code ⭐ PRIMARY⚠️ Not designed for - Focuses on new feature authoring✅ import from-code ⭐ - Reverse-engineer existing code to plans (PRIMARY use case)
Iterate on existing features ⭐ PRIMARY⚠️ Not designed for - Focuses on new feature planning✅ Auto-derive plans ⭐ - Understand existing features from code (PRIMARY use case)
Brownfield projects ⭐ PRIMARY⚠️ Not designed for - Designed primarily for greenfield✅ Brownfield analysis ⭐ - Work with existing projects (PRIMARY use case)
Team collaborationManual sharing, no syncShared structured plans (automated bidirectional sync for team collaboration), automated deviation detection
CI/CD integrationManual validationAutomated gates, proof bundles
Production deploymentManual checklistAutomated quality gates
Code reviewManual reviewAutomated deviation detection
ComplianceManual auditProof bundles, reproducible checks
+ +
+ +

🌱 Brownfield Modernization with SpecFact + Spec-Kit

+ +

Best of Both Worlds for Legacy Code

+ +

When modernizing legacy code, you can use both tools together for maximum value:

+ +
    +
  1. Spec-Kit for initial spec generation (fast, LLM-powered)
    2. +
  2. SpecFact for runtime contract enforcement (safety net)
    3. +
  3. Spec-Kit maintains documentation (living specs)
    4. +
  4. SpecFact prevents regressions (contract enforcement)
    5. +
+ +

Workflow: Legacy Code → Modernized Code

+ +
# Step 1: Use SpecFact to extract specs from legacy code
+specfact import from-code --bundle customer-portal --repo ./legacy-app
+
+# Output: Auto-generated project bundle from existing code
+# ✅ Analyzed 47 Python files
+# ✅ Extracted 23 features
+# ✅ Generated 112 user stories
+# ⏱️  Completed in 8.2 seconds
+# 📁 Project bundle: .specfact/projects/customer-portal/
+
+# Step 2: (Optional) Use Spec-Kit to refine specs interactively
+# /speckit.specify --feature "Payment Processing"
+# /speckit.plan --feature "Payment Processing"
+
+# Step 3: Use SpecFact to add runtime contracts
+# Add @icontract decorators to critical paths
+
+# Step 4: Modernize safely with contract safety net
+# Refactor knowing contracts will catch regressions
+
+# Step 5: Keep both in sync
+specfact sync bridge --adapter speckit --bundle customer-portal --repo . --bidirectional --watch
+
+ +

Why This Works

+ +
    +
  • SpecFact code2spec extracts specs from undocumented legacy code automatically
    • +
  • Spec-Kit interactive authoring refines specs with LLM assistance
    • +
  • SpecFact runtime contracts prevent regressions during modernization
    • +
  • Spec-Kit documentation maintains living specs for team
    • +
+ +

Result: Fast spec generation + runtime safety net = confident modernization

+ +

See Also

+ + + +
+ +

🚀 The Onboarding Journey

+ +

Stage 1: Discovery (“What is SpecFact?”)

+ +

Time: < 5 minutes

+ +

Learn how SpecFact complements Spec-Kit:

+ +
# See it in action
+specfact --help
+
+# Read the docs
+cat docs/getting-started.md
+
+ +

What you’ll discover:

+ +
    +
  • ✅ SpecFact imports your Spec-Kit artifacts automatically
    • +
  • ✅ Automated enforcement (CI/CD gates, contract validation)
    • +
  • ✅ Shared plans (bidirectional sync for team collaboration)
    • +
  • ✅ Code vs plan drift detection (automated deviation detection)
    • +
  • ✅ Production readiness (quality gates, proof bundles)
    • +
+ +

Key insight: SpecFact preserves your Spec-Kit workflow - you can use both tools together!

+ +
+ +

Stage 2: First Import (“Try It Out”)

+ +

Time: < 60 seconds

+ +

Import your Spec-Kit project to see what SpecFact adds:

+ +
# 1. Preview what will be imported
+specfact import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run
+
+# 2. Execute import (one command) - bundle name will be auto-detected or you can specify with --bundle
+specfact import from-bridge --adapter speckit --repo ./my-speckit-project --write
+
+# 3. Review generated bundle using CLI commands
+specfact plan review --bundle <bundle-name>
+
+ +

What was created:

+ +
    +
  • Modular project bundle at .specfact/projects/<bundle-name>/ (multiple aspect files)
    • +
  • .specfact/protocols/workflow.protocol.yaml (from FSM if detected)
    • +
  • .specfact/gates/config.yaml (quality gates configuration)
    • +
+ +

Note: Use CLI commands to interact with bundles. Do not edit .specfact files directly.

+ +

What happens:

+ +
    +
  1. Parses Spec-Kit artifacts: specs/[###-feature-name]/spec.md, plan.md, tasks.md, .specify/memory/constitution.md
    2. +
  2. Generates SpecFact plans: Converts Spec-Kit features/stories → SpecFact models
    3. +
  3. Creates enforcement config: Quality gates, CI/CD integration
    4. +
  4. Preserves Spec-Kit artifacts: Your original files remain untouched
    5. +
+ +

Result: Your Spec-Kit specs become production-ready contracts with automated quality gates!

+ +
+ +

Stage 3: Adoption (“Use Both Together”)

+ +

Time: Ongoing (automatic)

+ +

Keep using Spec-Kit interactively, sync automatically with SpecFact:

+ +
# Enable bidirectional sync (bridge-based, adapter-agnostic)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Workflow:

+ +
# 1. Continue using Spec-Kit interactively (slash commands)
+/speckit.specify --feature "User Authentication"
+/speckit.plan --feature "User Authentication"
+/speckit.tasks --feature "User Authentication"
+
+# 2. SpecFact automatically syncs new artifacts (watch mode)
+# → Detects changes in specs/[###-feature-name]/
+# → Imports new spec.md, plan.md, tasks.md
+# → Updates .specfact/projects/<bundle-name>/ aspect files
+# → Enables shared plans for team collaboration
+
+# 3. Detect code vs plan drift automatically
+specfact plan compare --code-vs-plan
+# → Compares intended design (manual plan = what you planned) vs actual implementation (code-derived plan = what's in your code)
+# → Identifies deviations automatically (not just artifact consistency like Spec-Kit's /speckit.analyze)
+# → Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift"
+
+# 4. Enable automated enforcement
+specfact enforce stage --preset balanced
+
+# 5. CI/CD automatically validates (GitHub Action)
+# → Runs on every PR
+# → Blocks HIGH severity issues
+# → Generates proof bundles
+
+ +

What you get:

+ +
    +
  • ✅ Interactive authoring (Spec-Kit): Use slash commands for rapid prototyping
    • +
  • ✅ Automated enforcement (SpecFact): CI/CD gates catch issues automatically
    • +
  • ✅ Team collaboration (SpecFact): Shared plans, deviation detection
    • +
  • ✅ Production readiness (SpecFact): Quality gates, proof bundles
    • +
+ +

Best of both worlds: Spec-Kit for authoring, SpecFact for enforcement!

+ +
+ +

Stage 4: Migration (“Full SpecFact Workflow”)

+ +

Time: Progressive (1-4 weeks)

+ +

Optional: Migrate to full SpecFact workflow (or keep using both tools together)

+ +

Week 1: Import + Sync

+ +
# Import existing Spec-Kit project
+specfact import from-bridge --adapter speckit --repo . --write
+
+# Enable bidirectional sync (bridge-based, adapter-agnostic)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Result: Both tools working together seamlessly.

+ +

Week 2-3: Enable Enforcement (Shadow Mode)

+ +
# Start in shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# Set up CrossHair for contract exploration
+specfact repro setup
+
+# Review what would be blocked
+specfact repro --verbose
+
+# Apply auto-fixes for violations (if available)
+specfact repro --fix --verbose
+
+ +

Result: See what SpecFact would catch, no blocking yet. Auto-fixes can be applied for Semgrep violations.

+ +

Week 4: Enable Balanced Enforcement

+ +
# Enable balanced mode (block HIGH, warn MEDIUM)
+specfact enforce stage --preset balanced
+
+# Test with real PR
+git checkout -b test-enforcement
+# Make a change that violates contracts
+specfact repro  # Should block HIGH issues
+
+# Or apply auto-fixes first
+specfact repro --fix  # Apply Semgrep auto-fixes, then validate
+
+ +

Result: Automated enforcement catching critical issues. Auto-fixes can be applied before validation.

+ +

Week 5+: Full SpecFact Workflow (Optional)

+ +
# Enable strict enforcement
+specfact enforce stage --preset strict
+
+# Full automation (CI/CD, brownfield analysis, etc.)
+# (CrossHair setup already done in Week 3)
+specfact repro --budget 120 --verbose
+
+ +

Result: Complete SpecFact workflow - or keep using both tools together!

+ +
+ +

📋 Step-by-Step Migration

+ +

Step 1: Preview Migration

+ +
# See what will be imported (safe - no changes)
+specfact import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run
+
+ +

Expected Output:

+ +
🔍 Analyzing Spec-Kit project via bridge adapter...
+✅ Found .specify/ directory (modern format)
+✅ Found specs/001-user-authentication/spec.md
+✅ Found specs/001-user-authentication/plan.md
+✅ Found specs/001-user-authentication/tasks.md
+✅ Found .specify/memory/constitution.md
+
+**💡 Tip**: If constitution is missing or minimal, run `specfact sdd constitution bootstrap --repo .` to auto-generate from repository analysis.
+
+📊 Migration Preview:
+  - Will create: .specfact/projects/<bundle-name>/ (modular project bundle)
+  - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected)
+  - Will create: .specfact/gates/config.yaml
+  - Will convert: Spec-Kit features → SpecFact Feature models
+  - Will convert: Spec-Kit user stories → SpecFact Story models
+  
+🚀 Ready to migrate (use --write to execute)
+
+ +

Step 2: Execute Migration

+ +
# Execute migration (creates SpecFact artifacts)
+specfact import from-bridge \
+  --adapter speckit \
+  --repo ./my-speckit-project \
+  --write \
+  --report migration-report.md
+
+ +

What it does:

+ +
    +
  1. Parses Spec-Kit artifacts (via bridge adapter): +
      +
    • specs/[###-feature-name]/spec.md → Features, user stories, requirements
      • +
    • specs/[###-feature-name]/plan.md → Technical context, architecture
      • +
    • specs/[###-feature-name]/tasks.md → Tasks, story mappings
      • +
    • .specify/memory/constitution.md → Principles, constraints
      • +
    +
    2. +
  2. Generates SpecFact artifacts: +
      +
    • .specfact/projects/<bundle-name>/ - Modular project bundle (multiple aspect files)
      • +
    • .specfact/protocols/workflow.protocol.yaml - FSM protocol (if detected)
      • +
    • .specfact/gates/config.yaml - Quality gates configuration
      • +
    +
    3. +
  3. Preserves Spec-Kit artifacts: +
      +
    • Original files remain untouched
      • +
    • Bidirectional sync keeps both aligned
      • +
    +
    4. +
+ +

Step 3: Review Generated Artifacts

+ +
# Review plan bundle using CLI commands
+specfact plan review --bundle <bundle-name>
+
+# Review enforcement config using CLI commands
+specfact enforce show-config
+
+# Review migration report
+cat migration-report.md
+
+ +

Note: Use CLI commands to interact with bundles. Do not edit .specfact files directly.

+ +

What to check:

+ +
    +
  • ✅ Features/stories correctly mapped from Spec-Kit
    • +
  • ✅ Acceptance criteria preserved
    • +
  • ✅ Business context extracted from constitution
    • +
  • ✅ Enforcement config matches your needs
    • +
+ +

Step 4: Enable Shared Plans (Bidirectional Sync)

+ +

Shared structured plans enable team collaboration with automated bidirectional sync. Unlike Spec-Kit’s manual markdown sharing, SpecFact automatically keeps plans synchronized across team members.

+ +
# One-time sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Continuous watch mode (recommended for team collaboration)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+ +

What it syncs:

+ +
    +
  • Spec-Kit → SpecFact: New spec.md, plan.md, tasks.md → Updated .specfact/projects/<bundle-name>/ aspect files
    • +
  • SpecFact → Spec-Kit: Changes to .specfact/projects/<bundle-name>/ → Updated Spec-Kit markdown with all required fields auto-generated: +
      +
    • spec.md: Frontmatter, INVSEST criteria, Scenarios (Primary, Alternate, Exception, Recovery)
      • +
    • plan.md: Constitution Check, Phases, Technology Stack (from constraints)
      • +
    • tasks.md: Phase organization, Story mappings ([US1], [US2]), Parallel markers
      • +
    +
    • +
  • Team collaboration: Multiple developers can work on the same plan with automated synchronization
    • +
  • No manual editing required: All Spec-Kit fields are auto-generated - ready for /speckit.analyze without additional work
    • +
+ +

Step 5: Enable Enforcement

+ +
# Week 1-2: Shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# Week 3-4: Balanced mode (block HIGH, warn MEDIUM)
+specfact enforce stage --preset balanced
+
+# Week 5+: Strict mode (block MEDIUM+)
+specfact enforce stage --preset strict
+
+ +

Step 6: Validate

+ +
# Set up CrossHair for contract exploration (one-time setup)
+specfact repro setup
+
+# Run all checks
+specfact repro --verbose
+
+# Check CI/CD integration
+git push origin feat/specfact-migration
+# → GitHub Action runs automatically
+# → PR blocked if HIGH severity issues found
+
+ +
+ +

💡 Best Practices

+ +

1. Start in Shadow Mode

+ +
# Always start with shadow mode (no blocking)
+specfact enforce stage --preset minimal
+specfact repro
+
+ +

Why: See what SpecFact would catch before enabling blocking.

+ +

2. Use Shared Plans (Bidirectional Sync)

+ +
# Enable bidirectional sync for team collaboration
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
+
+ +

Why: Shared structured plans enable team collaboration with automated bidirectional sync. Unlike Spec-Kit’s manual markdown sharing, SpecFact automatically keeps plans synchronized across team members. Continue using Spec-Kit interactively, get SpecFact automation automatically.

+ +

3. Progressive Enforcement

+ +
# Week 1: Shadow (observe)
+specfact enforce stage --preset minimal
+
+# Week 2-3: Balanced (block HIGH)
+specfact enforce stage --preset balanced
+
+# Week 4+: Strict (block MEDIUM+)
+specfact enforce stage --preset strict
+
+ +

Why: Gradual adoption reduces disruption and builds team confidence.

+ +

4. Keep Spec-Kit Artifacts

+ +

Don’t delete Spec-Kit files - they’re still useful:

+ +
    +
  • ✅ Interactive authoring (slash commands)
    • +
  • ✅ Fallback if SpecFact has issues
    • +
  • ✅ Team members who prefer Spec-Kit workflow
    • +
+ +

Bidirectional sync keeps both aligned automatically.

+ +
+ +

❓ FAQ

+ +

Q: Do I need to stop using Spec-Kit?

+ +

A: No! SpecFact works alongside Spec-Kit. Use Spec-Kit for interactive authoring (new features), SpecFact for automated enforcement and existing code analysis.

+ +

Q: What happens to my Spec-Kit artifacts?

+ +

A: They’re preserved - SpecFact imports them but doesn’t modify them. Bidirectional sync keeps both aligned.

+ +

Q: Can I export back to Spec-Kit?

+ +

A: Yes! SpecFact can export back to Spec-Kit format. Your original files are never modified.

+ +

Q: What if I prefer Spec-Kit workflow?

+ +

A: Keep using Spec-Kit! Bidirectional sync automatically keeps SpecFact artifacts updated. Use SpecFact for CI/CD enforcement and brownfield analysis.

+ +

Q: Does SpecFact replace Spec-Kit?

+ +

A: No - they’re complementary. Spec-Kit excels at interactive authoring for new features, SpecFact adds automation, enforcement, and brownfield analysis capabilities.

+ +
+ +

See Also

+ + + + + + + + + + + + + +

Getting Started

+ + + +
+ +

Next Steps:

+ +
    +
  1. Try it: specfact import from-bridge --adapter speckit --repo . --dry-run
    2. +
  2. Import: specfact import from-bridge --adapter speckit --repo . --write
    3. +
  3. Sync: specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch
    4. +
  4. Enforce: specfact enforce stage --preset minimal (start shadow mode)
    5. +
+ +
+ +
+

Remember: Spec-Kit and SpecFact are complementary. Use Spec-Kit for interactive authoring, add SpecFact for automated enforcement. Best of both worlds! 🚀

+
+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/guides/specmatic-integration.md b/_site_test/guides/specmatic-integration.md new file mode 100644 index 0000000..009b4e3 --- /dev/null +++ b/_site_test/guides/specmatic-integration.md @@ -0,0 +1,646 @@ +# Specmatic Integration Guide + +> **API Contract Testing with Specmatic** +> Validate OpenAPI/AsyncAPI specifications, check backward compatibility, and run mock servers + +--- + +## Overview + +SpecFact CLI integrates with **Specmatic** to provide service-level contract testing for API specifications. This complements SpecFact's code-level contracts (icontract, beartype, CrossHair) by adding API contract validation. + +**What Specmatic adds:** + +- ✅ **OpenAPI/AsyncAPI validation** - Validate specification structure and examples +- ✅ **Backward compatibility checking** - Detect breaking changes between spec versions +- ✅ **Mock server generation** - Run development mock servers from specifications +- ✅ **Test suite generation** - Auto-generate contract tests from specs + +--- + +## Quick Reference: When to Use What + +| Command | Purpose | Output | When to Use | +|---------|---------|--------|-------------| +| `spec validate` | **Check if spec is valid** | Validation report (console) | Before committing spec changes, verify spec correctness | +| `spec generate-tests` | **Create tests to validate API** | Test files (on disk) | To test your API implementation matches the spec | +| `spec mock` | **Run mock server** | Running server | Test client code, frontend development | +| `spec backward-compat` | **Check breaking changes** | Compatibility report | When updating API versions | + +**Key Difference:** + +- `validate` = "Is my spec file correct?" (checks the specification itself) +- `generate-tests` = "Create tests to verify my API matches the spec" (creates executable tests) + +**Typical Workflow:** + +```bash +# 1. Validate spec is correct +specfact spec validate --bundle my-api + +# 2. Generate tests from spec +specfact spec generate-tests --bundle my-api --output tests/ + +# 3. Run tests against your API +specmatic test --spec ... --host http://localhost:8000 +``` + +--- + +## Installation + +**Important**: Specmatic is a **Java CLI tool**, not a Python package. It must be installed separately. + +### Install Specmatic + +Visit the [Specmatic download page](https://docs.specmatic.io/download.html) for detailed installation instructions. + +**Quick install options:** + +```bash +# Option 1: Direct installation (requires Java 17+) +# macOS/Linux +curl https://docs.specmatic.io/install-specmatic.sh | bash + +# Windows (PowerShell) +irm https://docs.specmatic.io/install-specmatic.ps1 | iex + +# Option 2: Via npm/npx (requires Java/JRE and Node.js) +# Run directly without installation +npx specmatic --version + +# Option 3: macOS (Homebrew) +brew install specmatic + +# Verify installation +specmatic --version +``` + +**Note**: SpecFact CLI automatically detects Specmatic whether it's installed directly or available via `npx`. If you have Java/JRE installed, you can use `npx specmatic` without a separate installation. + +### Verify Integration + +SpecFact CLI will automatically detect if Specmatic is available: + +```bash +# Check if Specmatic is detected +specfact spec validate --help + +# If Specmatic is not installed, you'll see: +# ✗ Specmatic not available: Specmatic CLI not found. Install from: https://docs.specmatic.io/ +``` + +--- + +## Commands + +### Validate Specification + +Validate an OpenAPI/AsyncAPI specification. Can validate a single file or all contracts in a project bundle: + +```bash +# Validate a single spec file +specfact spec validate api/openapi.yaml + +# With backward compatibility check +specfact spec validate api/openapi.yaml --previous api/openapi.v1.yaml + +# Validate all contracts in active bundle (interactive selection) +specfact spec validate + +# Validate all contracts in specific bundle +specfact spec validate --bundle legacy-api + +# Non-interactive: validate all contracts in active bundle +specfact spec validate --bundle legacy-api --no-interactive +``` + +**CLI-First Pattern**: The command uses the active plan (from `specfact plan select`) as default, or you can specify `--bundle`. Never requires direct `.specfact` paths - always use the CLI interface. + +**What it checks:** + +- Schema structure validation +- Example generation test +- Backward compatibility (if previous version provided) + +### Check Backward Compatibility + +Compare two specification versions: + +```bash +specfact spec backward-compat api/openapi.v1.yaml api/openapi.v2.yaml +``` + +**Output:** + +- ✓ Compatible - No breaking changes detected +- ✗ Breaking changes - Lists incompatible changes + +### Generate Test Suite + +Auto-generate contract tests from specification. Can generate for a single file or all contracts in a bundle: + +```bash +# Generate for a single spec file +specfact spec generate-tests api/openapi.yaml + +# Generate to custom location +specfact spec generate-tests api/openapi.yaml --output tests/specmatic/ + +# Generate tests for all contracts in active bundle +specfact spec generate-tests --bundle legacy-api + +# Generate tests for all contracts in specific bundle +specfact spec generate-tests --bundle legacy-api --output tests/contract/ +``` + +**CLI-First Pattern**: Uses active plan as default, or specify `--bundle`. Never requires direct `.specfact` paths. + +### What Can You Do With Generated Tests? + +The tests generated by `spec generate-tests` are **executable contract tests** that validate your API implementation against your OpenAPI/AsyncAPI specification. Here's a complete walkthrough: + +#### Understanding Generated Tests + +When you run `specfact spec generate-tests`, Specmatic creates test files that: + +- **Validate request format**: Check that requests match the spec (headers, body, query params) +- **Validate response format**: Verify responses match the spec (status codes, headers, body schema) +- **Test all endpoints**: Ensure all endpoints defined in the spec are implemented +- **Check data types**: Validate that data types and constraints are respected +- **Property-based testing**: Automatically generate diverse test data to find edge cases + +#### Step-by-Step: Using Generated Tests + +**Step 1: Generate Tests from Your Contract** + +```bash +# Generate tests for all contracts in your bundle +specfact spec generate-tests --bundle my-api --output tests/contract/ + +# Output: +# [1/5] Generating test suite from: .specfact/projects/my-api/contracts/api.openapi.yaml +# ✓ Test suite generated: tests/contract/ +# ... +# ✓ Generated tests for 5 contract(s) +``` + +**Step 2: Review Generated Test Files** + +The tests are generated in the output directory (default: `.specfact/specmatic-tests/`): + +```bash +# Check what was generated +ls -la tests/contract/ +# Output shows Specmatic test files (format depends on Specmatic version) +``` + +**Step 3: Start Your API Server** + +Before running tests, start your API implementation: + +```bash +# Example: Start FastAPI server +python -m uvicorn main:app --port 8000 + +# Or Flask +python app.py + +# Or any other API server +# Make sure it's running on the expected host/port +``` + +**Step 4: Run Tests Against Your API** + +Use Specmatic's test runner to execute the generated tests: + +```bash +# Run tests against your running API +specmatic test \ + --spec .specfact/projects/my-api/contracts/api.openapi.yaml \ + --host http://localhost:8000 + +# Output: +# ✓ GET /api/users - Request/Response match contract +# ✓ POST /api/users - Request/Response match contract +# ✗ GET /api/products - Response missing required field 'price' +# ... +``` + +**Step 5: Fix Issues and Re-run** + +If tests fail, fix your API implementation and re-run: + +```bash +# Fix the API code +# ... make changes ... + +# Restart API server +python -m uvicorn main:app --port 8000 + +# Re-run tests +specmatic test --spec ... --host http://localhost:8000 +``` + +#### Complete Example: Contract-Driven Development Workflow + +Here's a full workflow from contract to tested implementation: + +```bash +# 1. Import existing code and extract contracts +specfact import from-code --bundle user-api --repo . + +# 2. Validate contracts are correct +specfact spec validate --bundle user-api + +# Output: +# [1/3] Validating specification: contracts/user-api.openapi.yaml +# ✓ Specification is valid: user-api.openapi.yaml +# ... + +# 3. Generate tests from validated contracts +specfact spec generate-tests --bundle user-api --output tests/contract/ + +# Output: +# [1/3] Generating test suite from: contracts/user-api.openapi.yaml +# ✓ Test suite generated: tests/contract/ +# ✓ Generated tests for 3 contract(s) + +# 4. Start your API server +python -m uvicorn api.main:app --port 8000 & +sleep 3 # Wait for server to start + +# 5. Run contract tests +specmatic test \ + --spec .specfact/projects/user-api/contracts/user-api.openapi.yaml \ + --host http://localhost:8000 + +# Output: +# Running contract tests... +# ✓ GET /api/users - Passed +# ✓ POST /api/users - Passed +# ✓ GET /api/users/{id} - Passed +# All tests passed! ✓ +``` + +#### CI/CD Integration Example + +Add contract testing to your CI/CD pipeline: + +```yaml +# .github/workflows/contract-tests.yml +name: Contract Tests + +on: [push, pull_request] + +jobs: + contract-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Install Specmatic + run: | + curl https://docs.specmatic.io/install-specmatic.sh | bash + + - name: Install SpecFact CLI + run: pip install specfact-cli + + - name: Generate contract tests + run: | + specfact spec generate-tests \ + --bundle my-api \ + --output tests/contract/ \ + --no-interactive + + - name: Start API server + run: | + python -m uvicorn main:app --port 8000 & + sleep 5 + + - name: Run contract tests + run: | + specmatic test \ + --spec .specfact/projects/my-api/contracts/api.openapi.yaml \ + --host http://localhost:8000 +``` + +#### Testing Against Mock Servers + +You can also test your client code against Specmatic mock servers: + +```bash +# Terminal 1: Start mock server +specfact spec mock --bundle my-api --port 9000 + +# Terminal 2: Run your client code against mock +python client.py # Your client code that calls the API + +# The mock server: +# - Validates requests match the spec +# - Returns spec-compliant responses +# - Helps test client code without a real API +``` + +#### Benefits of Using Generated Tests + +1. **Automated Validation**: Catch contract violations automatically +2. **Early Detection**: Find issues before deployment +3. **Documentation**: Tests serve as executable examples +4. **Confidence**: Ensure API changes don't break contracts +5. **Integration Safety**: Prevent breaking changes between services +6. **Property-Based Testing**: Automatically test edge cases and boundary conditions + +#### Troubleshooting Test Execution + +**Tests fail with "Connection refused":** + +```bash +# Make sure your API server is running +curl http://localhost:8000/health # Test server is up + +# Check the host/port in your test command matches your server +specmatic test --spec ... --host http://localhost:8000 +``` + +**Tests fail with "Response doesn't match contract":** + +```bash +# Check what the actual response is +curl -v http://localhost:8000/api/users + +# Compare with your OpenAPI spec +# Fix your API implementation to match the spec +``` + +**Tests pass but you want to see details:** + +```bash +# Use verbose mode (if supported by Specmatic version) +specmatic test --spec ... --host ... --verbose +``` + +### Run Mock Server + +Start a mock server for development. Can use a single spec file or select from bundle contracts: + +```bash +# Auto-detect spec file from current directory +specfact spec mock + +# Specify spec file and port +specfact spec mock --spec api/openapi.yaml --port 9000 + +# Use examples mode (less strict) +specfact spec mock --spec api/openapi.yaml --examples + +# Select contract from active bundle (interactive) +specfact spec mock --bundle legacy-api + +# Use specific bundle (non-interactive, uses first contract) +specfact spec mock --bundle legacy-api --no-interactive +``` + +**CLI-First Pattern**: Uses active plan as default, or specify `--bundle`. Interactive selection when multiple contracts available. + +**Mock server features:** + +- Serves API endpoints based on specification +- Validates requests against spec +- Returns example responses +- Press Ctrl+C to stop + +--- + +## Integration with Other Commands + +Specmatic validation is automatically integrated into: + +### Import Command + +When importing code, SpecFact auto-detects and validates OpenAPI/AsyncAPI specs: + +```bash +# Import with bundle (uses active plan if --bundle not specified) +specfact import from-code --bundle legacy-api --repo . + +# Automatically validates: +# - Repo-level OpenAPI/AsyncAPI specs (openapi.yaml, asyncapi.yaml) +# - Bundle contract files referenced in features +# - Suggests starting mock server if API specs found +``` + +### Enforce Command + +SDD enforcement includes Specmatic validation for all contracts referenced in the bundle: + +```bash +# Enforce SDD (uses active plan if --bundle not specified) +specfact enforce sdd --bundle legacy-api + +# Automatically validates: +# - All contract files referenced in bundle features +# - Includes validation results in enforcement report +# - Reports deviations for invalid contracts +``` + +### Sync Command + +Repository sync validates specs before synchronization: + +```bash +# Sync bridge (uses active plan if --bundle not specified) +specfact sync bridge --bundle legacy-api --repo . + +# Automatically validates: +# - OpenAPI/AsyncAPI specs before sync operation +# - Prevents syncing invalid contracts +# - Reports validation errors before proceeding +``` + +--- + +## How It Works + +### Architecture + +```text +┌─────────────────────────────────────────────────────────┐ +│ SpecFact Complete Stack │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ Layer 1: Code-Level Contracts (Current) │ +│ ├─ icontract: Function preconditions/postconditions │ +│ ├─ beartype: Runtime type validation │ +│ └─ CrossHair: Symbolic execution & counterexamples │ +│ │ +│ Layer 2: Service-Level Contracts (Specmatic) │ +│ ├─ OpenAPI/AsyncAPI validation │ +│ ├─ Backward compatibility checking │ +│ ├─ Mock server for development │ +│ └─ Contract testing automation │ +│ │ +└─────────────────────────────────────────────────────────┘ +``` + +### Integration Pattern + +SpecFact calls Specmatic via subprocess: + +1. **Check availability** - Verifies Specmatic CLI is in PATH +2. **Execute command** - Runs Specmatic CLI with appropriate arguments +3. **Parse results** - Extracts validation results and errors +4. **Display output** - Shows results in SpecFact's rich console format + +--- + +## Examples + +### Example 1: Validate API Spec During Import + +```bash +# Project has openapi.yaml +specfact import from-code --bundle api-service --repo . + +# Output: +# ✓ Import complete! +# 🔍 Found 1 API specification file(s) +# Validating openapi.yaml with Specmatic... +# ✓ openapi.yaml is valid +# Validated 3 bundle contract(s), 0 failed. +# 💡 Tip: Run 'specfact spec mock --bundle api-service' to start a mock server for development +``` + +### Example 2: Check Breaking Changes + +```bash +# Compare API versions +specfact spec backward-compat api/v1/openapi.yaml api/v2/openapi.yaml + +# Output: +# ✗ Breaking changes detected +# Breaking Changes: +# - Removed endpoint /api/v1/users +# - Changed response schema for /api/v1/products +``` + +### Example 3: Development Workflow with Bundle + +```bash +# 1. Set active bundle +specfact plan select api-service + +# 2. Validate all contracts in bundle (interactive selection) +specfact spec validate +# Shows list of contracts, select by number or 'all' + +# 3. Start mock server from bundle (interactive selection) +specfact spec mock --bundle api-service --port 9000 + +# 4. In another terminal, test against mock +curl http://localhost:9000/api/users + +# 5. Generate tests for all contracts +specfact spec generate-tests --bundle api-service --output tests/ +``` + +### Example 4: CI/CD Workflow (Non-Interactive) + +```bash +# 1. Validate all contracts in bundle (non-interactive) +specfact spec validate --bundle api-service --no-interactive + +# 2. Generate tests for all contracts +specfact spec generate-tests --bundle api-service --output tests/ --no-interactive + +# 3. Run generated tests +pytest tests/specmatic/ +``` + +--- + +## Troubleshooting + +### Specmatic Not Found + +**Error:** + +```text +✗ Specmatic not available: Specmatic CLI not found. Install from: https://docs.specmatic.io/ +``` + +**Solution:** + +1. Install Specmatic from [https://docs.specmatic.io/](https://docs.specmatic.io/) +2. Ensure `specmatic` is in your PATH +3. Verify with: `specmatic --version` + +### Validation Failures + +**Error:** + +```text +✗ Specification validation failed +Errors: + - Schema validation failed: missing required field 'info' +``` + +**Solution:** + +1. Check your OpenAPI/AsyncAPI spec format +2. Validate with: `specmatic validate your-spec.yaml` +3. Review Specmatic documentation for spec requirements + +### Mock Server Won't Start + +**Error:** + +```text +✗ Failed to start mock server: Port 9000 already in use +``` + +**Solution:** + +1. Use a different port: `specfact spec mock --port 9001` +2. Stop the existing server on that port +3. Check for other processes: `lsof -i :9000` + +--- + +## Best Practices + +1. **Validate early** - Run `specfact spec validate` before committing spec changes +2. **Check compatibility** - Use `specfact spec backward-compat` when updating API versions +3. **Use mock servers** - Start mock servers during development to test integrations +4. **Generate tests** - Auto-generate tests for CI/CD pipelines +5. **Integrate in workflows** - Let SpecFact auto-validate specs during import/enforce/sync + +--- + +## See Also + +### Related Guides + +- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations +- [Command Chains Reference](command-chains.md) - Complete workflows including [API Contract Development Chain](command-chains.md#4-api-contract-development-chain) +- [Common Tasks Index](common-tasks.md) - Quick reference for API-related tasks +- [Contract Testing Workflow](contract-testing-workflow.md) - Contract testing patterns + +### Related Commands + +- [Command Reference - Spec Commands](../reference/commands.md#spec-commands) - Full command documentation +- [Command Reference - Contract Commands](../reference/commands.md#contract-commands) - Contract verification commands + +### Related Examples + +- [API Contract Development Examples](../examples/) - Real-world examples + +### External Documentation + +- **[Specmatic Official Docs](https://docs.specmatic.io/)** - Specmatic documentation +- **[OpenAPI Specification](https://swagger.io/specification/)** - OpenAPI spec format +- **[AsyncAPI Specification](https://www.asyncapi.com/)** - AsyncAPI spec format + +--- + +**Note**: Specmatic is an external tool and must be installed separately. SpecFact CLI provides integration but does not include Specmatic itself. diff --git a/_site_test/guides/workflows.md b/_site_test/guides/workflows.md new file mode 100644 index 0000000..8cc8c0d --- /dev/null +++ b/_site_test/guides/workflows.md @@ -0,0 +1,546 @@ +# Common Workflows + +Daily workflows for using SpecFact CLI effectively. + +> **Primary Workflow**: Brownfield code modernization +> **Secondary Workflow**: Spec-Kit bidirectional sync + +**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in. + +--- + +## Brownfield Code Modernization ⭐ PRIMARY + +Reverse engineer existing code and enforce contracts incrementally. + +**Integration**: Works with VS Code, Cursor, GitHub Actions, pre-commit hooks. See [Integration Showcases](../examples/integration-showcases/) for real examples. + +### Step 1: Analyze Legacy Code + +```bash +# Full repository analysis +specfact import from-code --bundle legacy-api --repo . + +# For large codebases, analyze specific modules: +specfact import from-code --bundle core-module --repo . --entry-point src/core +specfact import from-code --bundle api-module --repo . --entry-point src/api +``` + +### Step 2: Review Extracted Specs + +```bash +# Review bundle to understand extracted specs +specfact plan review --bundle legacy-api + +# Or get structured findings for analysis +specfact plan review --bundle legacy-api --list-findings --findings-format json +``` + +**Note**: Use CLI commands to interact with bundles. The bundle structure (`.specfact/projects//`) is managed by SpecFact CLI - use commands like `plan review`, `plan add-feature`, `plan update-feature` to modify bundles, not direct file editing. + +### Step 3: Add Contracts Incrementally + +```bash +# Start in shadow mode +specfact enforce stage --preset minimal +``` + +See [Brownfield Journey Guide](brownfield-journey.md) for complete workflow. + +### Partial Repository Coverage + +For large codebases or monorepos with multiple projects, use `--entry-point` to analyze specific subdirectories: + +```bash +# Analyze individual projects in a monorepo +specfact import from-code --bundle api-service --repo . --entry-point projects/api-service +specfact import from-code --bundle web-app --repo . --entry-point projects/web-app +specfact import from-code --bundle mobile-app --repo . --entry-point projects/mobile-app + +# Analyze specific modules for incremental modernization +specfact import from-code --bundle core-module --repo . --entry-point src/core +specfact import from-code --bundle integrations-module --repo . --entry-point src/integrations +``` + +**Benefits:** + +- **Faster analysis** - Focus on specific modules for quicker feedback +- **Incremental modernization** - Modernize one module at a time +- **Multi-bundle support** - Create separate project bundles for different projects/modules +- **Better organization** - Keep bundles organized by project boundaries + +**Note:** When using `--entry-point`, each analysis creates a separate project bundle. Use `specfact plan compare` to compare different bundles. + +--- + +## Bridge Adapter Sync (Secondary) + +Keep SpecFact synchronized with external tools (Spec-Kit, OpenSpec, GitHub Issues, etc.) via the plugin-based adapter registry. + +**Supported Adapters**: + +- **Spec-Kit** (`--adapter speckit`) - Bidirectional sync for interactive authoring +- **OpenSpec** (`--adapter openspec`) - Read-only sync for change proposal tracking (v0.22.0+) +- **GitHub Issues** (`--adapter github`) - Export change proposals to DevOps backlogs +- **Future**: Linear, Jira, Azure DevOps, and more + +**Note**: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters are registered in `AdapterRegistry` and accessed via `specfact sync bridge --adapter `, making the architecture extensible for future tool integrations. + +### Spec-Kit Bidirectional Sync + +Keep Spec-Kit and SpecFact synchronized automatically. + +#### One-Time Sync + +```bash +specfact sync bridge --adapter speckit --bundle --repo . --bidirectional +``` + +**What it does**: + +- Syncs Spec-Kit artifacts → SpecFact project bundles +- Syncs SpecFact project bundles → Spec-Kit artifacts +- Resolves conflicts automatically (SpecFact takes priority) + +**When to use**: + +- After migrating from Spec-Kit +- When you want to keep both tools in sync +- Before making changes in either tool + +#### Watch Mode (Continuous Sync) + +```bash +specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 +``` + +**What it does**: + +- Monitors file system for changes +- Automatically syncs when files are created/modified +- Runs continuously until interrupted (Ctrl+C) + +**When to use**: + +- During active development +- When multiple team members use both tools +- For real-time synchronization + +**Example**: + +```bash +# Terminal 1: Start watch mode +specfact sync bridge --adapter speckit --bundle my-project --repo . --bidirectional --watch --interval 5 + +# Terminal 2: Make changes in Spec-Kit +echo "# New Feature" >> specs/002-new-feature/spec.md + +# Watch mode automatically detects and syncs +# Output: "Detected 1 change(s), syncing..." +``` + +#### What Gets Synced + +- `specs/[###-feature-name]/spec.md` ↔ `.specfact/projects//features/FEATURE-*.yaml` +- `specs/[###-feature-name]/plan.md` ↔ `.specfact/projects//product.yaml` +- `specs/[###-feature-name]/tasks.md` ↔ `.specfact/projects//features/FEATURE-*.yaml` +- `.specify/memory/constitution.md` ↔ SpecFact business context (business.yaml) +- `specs/[###-feature-name]/contracts/*.yaml` ↔ `.specfact/protocols/*.yaml` + +**Note**: When syncing from SpecFact to Spec-Kit, all required Spec-Kit fields (frontmatter, INVSEST criteria, Constitution Check, Phases, Technology Stack, Story mappings) are automatically generated. No manual editing required - generated artifacts are ready for `/speckit.analyze`. + +### OpenSpec Read-Only Sync + +Sync OpenSpec change proposals to SpecFact (v0.22.0+): + +```bash +# Read-only sync from OpenSpec to SpecFact +specfact sync bridge --adapter openspec --mode read-only \ + --bundle my-project \ + --repo /path/to/openspec-repo +``` + +**What it does**: + +- Reads OpenSpec change proposals from `openspec/changes/` +- Syncs proposals to SpecFact change tracking +- Read-only mode (does not modify OpenSpec files) + +**When to use**: + +- When working with OpenSpec change proposals +- For tracking OpenSpec proposals in SpecFact format +- Before exporting proposals to DevOps tools + +See [OpenSpec Journey Guide](openspec-journey.md) for complete integration workflow. + +--- + +## Repository Sync Workflow + +Keep plan artifacts updated as code changes. + +### One-Time Repository Sync + +```bash +specfact sync repository --repo . --target .specfact +``` + +**What it does**: + +- Analyzes code changes +- Updates plan artifacts +- Detects deviations from manual plans + +**When to use**: + +- After making code changes +- Before comparing plans +- To update auto-derived plans + +### Repository Watch Mode (Continuous Sync) + +```bash +specfact sync repository --repo . --watch --interval 5 +``` + +**What it does**: + +- Monitors code files for changes +- Automatically updates plan artifacts +- Triggers sync when files are created/modified/deleted + +**When to use**: + +- During active development +- For real-time plan updates +- When code changes frequently + +**Example**: + +```bash +# Terminal 1: Start watch mode +specfact sync repository --repo . --watch --interval 5 + +# Terminal 2: Make code changes +echo "class NewService:" >> src/new_service.py + +# Watch mode automatically detects and syncs +# Output: "Detected 1 change(s), syncing..." +``` + +--- + +## Enforcement Workflow + +Progressive enforcement from observation to blocking. + +### Step 1: Shadow Mode (Observe Only) + +```bash +specfact enforce stage --preset minimal +``` + +**What it does**: + +- Sets enforcement to LOG only +- Observes violations without blocking +- Collects metrics and reports + +**When to use**: + +- Initial setup +- Understanding current state +- Baseline measurement + +### Step 2: Balanced Mode (Warn on Issues) + +```bash +specfact enforce stage --preset balanced +``` + +**What it does**: + +- BLOCKs HIGH severity violations +- WARNs on MEDIUM severity violations +- LOGs LOW severity violations + +**When to use**: + +- After stabilization period +- When ready for warnings +- Before production deployment + +### Step 3: Strict Mode (Block Everything) + +```bash +specfact enforce stage --preset strict +``` + +**What it does**: + +- BLOCKs all violations (HIGH, MEDIUM, LOW) +- Enforces all rules strictly +- Production-ready enforcement + +**When to use**: + +- Production environments +- After full validation +- When all issues are resolved + +### Running Validation + +```bash +# First-time setup: Configure CrossHair for contract exploration +specfact repro setup + +# Quick validation +specfact repro + +# Verbose validation with budget +specfact repro --verbose --budget 120 + +# Apply auto-fixes +specfact repro --fix --budget 120 +``` + +**What it does**: + +- `repro setup` configures CrossHair for contract exploration (one-time setup) +- `repro` validates contracts +- Checks types +- Detects async anti-patterns +- Validates state machines +- Applies auto-fixes (if available) + +--- + +## Plan Comparison Workflow + +Compare manual plans vs auto-derived plans to detect deviations. + +### Quick Comparison + +```bash +specfact plan compare --bundle legacy-api +``` + +**What it does**: + +- Compares two project bundles (manual vs auto-derived) +- Finds bundles in `.specfact/projects/` +- Compares and reports deviations + +**When to use**: + +- After code changes +- Before merging PRs +- Regular validation + +### Detailed Comparison + +```bash +specfact plan compare \ + --manual .specfact/projects/manual-plan \ + --auto .specfact/projects/auto-derived \ + --out comparison-report.md +``` + +**Note**: Commands accept bundle directory paths, not individual files. + +**What it does**: + +- Compares specific plans +- Generates detailed report +- Shows all deviations with severity + +**When to use**: + +- Investigating specific deviations +- Generating reports for review +- Deep analysis + +### Code vs Plan Comparison + +```bash +specfact plan compare --bundle legacy-api --code-vs-plan +``` + +**What it does**: + +- Compares current code state vs manual plan +- Auto-derives plan from code +- Compares in one command + +**When to use**: + +- Quick drift detection +- Before committing changes +- CI/CD validation + +--- + +## Daily Development Workflow + +Typical workflow for daily development. + +### Morning: Check Status + +```bash +# Validate everything +specfact repro --verbose + +# Compare plans +specfact plan compare --bundle legacy-api +``` + +**What it does**: + +- Validates current state +- Detects any deviations +- Reports issues + +### During Development: Watch Mode + +```bash +# Start watch mode for repository sync +specfact sync repository --repo . --watch --interval 5 +``` + +**What it does**: + +- Monitors code changes +- Updates plan artifacts automatically +- Keeps plans in sync + +### Before Committing: Validate + +```bash +# Run validation +specfact repro + +# Compare plans +specfact plan compare --bundle legacy-api +``` + +**What it does**: + +- Ensures no violations +- Detects deviations +- Validates contracts + +### After Committing: CI/CD + +```bash +# CI/CD pipeline runs +specfact repro --verbose --budget 120 +``` + +**What it does**: + +- Validates in CI/CD +- Blocks merges on violations +- Generates reports + +--- + +## Migration Workflow + +Complete workflow for migrating from Spec-Kit or OpenSpec. + +### Spec-Kit Migration + +#### Step 1: Preview + +```bash +specfact import from-bridge --adapter speckit --repo . --dry-run +``` + +**What it does**: + +- Analyzes Spec-Kit project using bridge adapter +- Shows what will be imported +- Does not modify anything + +#### Step 2: Execute + +```bash +specfact import from-bridge --adapter speckit --repo . --write +``` + +**What it does**: + +- Imports Spec-Kit artifacts using bridge adapter +- Creates modular project bundle structure +- Converts to SpecFact format (multiple aspect files) + +#### Step 3: Set Up Sync + +```bash +specfact sync bridge --adapter speckit --bundle --repo . --bidirectional --watch --interval 5 +``` + +**What it does**: + +- Enables bidirectional sync via Spec-Kit adapter +- Keeps both tools in sync +- Monitors for changes + +### OpenSpec Integration + +Sync with OpenSpec change proposals (v0.22.0+): + +```bash +# Read-only sync from OpenSpec to SpecFact +specfact sync bridge --adapter openspec --mode read-only \ + --bundle my-project \ + --repo /path/to/openspec-repo + +# Export OpenSpec change proposals to GitHub Issues +specfact sync bridge --adapter github --mode export-only \ + --repo-owner your-org \ + --repo-name your-repo \ + --repo /path/to/openspec-repo +``` + +**What it does**: + +- Reads OpenSpec change proposals using OpenSpec adapter +- Syncs proposals to SpecFact change tracking +- Exports proposals to DevOps tools via GitHub adapter + +See [OpenSpec Journey Guide](openspec-journey.md) for complete integration workflow. + +### Step 4: Enable Enforcement + +```bash +# Start in shadow mode +specfact enforce stage --preset minimal + +# After stabilization, enable warnings +specfact enforce stage --preset balanced + +# For production, enable strict mode +specfact enforce stage --preset strict +``` + +**What it does**: + +- Progressive enforcement +- Gradual rollout +- Production-ready + +--- + +## Related Documentation + +- **[Integration Showcases](../examples/integration-showcases/)** ⭐ - Real bugs fixed via VS Code, Cursor, GitHub Actions integrations +- [Use Cases](use-cases.md) - Detailed use case scenarios +- [Command Reference](../reference/commands.md) - All commands with examples +- [Troubleshooting](troubleshooting.md) - Common issues and solutions +- [IDE Integration](ide-integration.md) - Set up slash commands + +--- + +**Happy building!** 🚀 diff --git a/_site_test/index.html b/_site_test/index.html new file mode 100644 index 0000000..e33b05a --- /dev/null +++ b/_site_test/index.html @@ -0,0 +1,315 @@ + + + + + + + +SpecFact CLI Documentation | Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

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.

+ +
+ +

🚀 Quick Start

+ +

New to SpecFact CLI?

+ +

Primary Use Case: Modernizing legacy Python codebases

+ +
    +
  1. Installation - Get started in 60 seconds
    2. +
  2. First Steps - Run your first command
    3. +
  3. Modernizing Legacy Code ⭐ PRIMARY - Brownfield-first guide
    4. +
  4. The Brownfield Journey ⭐ - Complete modernization workflow
    5. +
+ +

Using GitHub Spec-Kit?

+ +

Secondary Use Case: Add automated enforcement to your Spec-Kit projects

+ + + +

📚 Documentation

+ +

Guides

+ + + +

Reference

+ + + +

Examples

+ + + +
+ +

🆘 Getting Help

+ +

Documentation

+ +

You’re here! Browse the guides above.

+ +

Community

+ + + +

Direct Support

+ + + +
+ +

🤝 Contributing

+ +

Found an error or want to improve the docs?

+ +
    +
  1. Fork the repository
    2. +
  2. Edit the markdown files in docs/
    3. +
  3. Submit a pull request
    4. +
+ +

See CONTRIBUTING.md for guidelines.

+ +
+ +

Happy building! 🚀

+ +
+ +

Copyright © 2025 Nold AI (Owner: Dominikus Nold)

+ +

Trademarks: All product names, logos, and brands mentioned in this documentation are the property of their respective owners. NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). See TRADEMARKS.md for more information.

+ +

License: See LICENSE.md for licensing information.

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/installation/enhanced-analysis-dependencies.md b/_site_test/installation/enhanced-analysis-dependencies.md new file mode 100644 index 0000000..5c01aaa --- /dev/null +++ b/_site_test/installation/enhanced-analysis-dependencies.md @@ -0,0 +1,130 @@ +# Enhanced Analysis Dependencies + +## Python Package Dependencies + +### Already in `pyproject.toml` + +✅ **NetworkX** (`networkx>=3.4.2`) - Already in main dependencies + +- Used for: Dependency graph building and analysis +- Status: ✅ Already configured + +✅ **Graphviz** (`graphviz>=0.20.1`) - Added to main dependencies and optional-dependencies + +- Used for: Architecture diagram generation +- **Important**: Requires system Graphviz to be installed: + - Debian/Ubuntu: `apt-get install graphviz` + - macOS: `brew install graphviz` + - The Python `graphviz` package is a wrapper that requires the system package + +### Quick Setup + +```bash +# Install Python dependencies +pip install -e ".[enhanced-analysis]" + +# Install system dependencies (required for graphviz) +# Debian/Ubuntu: +sudo apt-get install graphviz + +# macOS: +brew install graphviz +``` + +## Optional Python Packages + +These packages are available via pip and can be installed with: + +```bash +pip install -e ".[enhanced-analysis]" +# or +hatch install -e ".[enhanced-analysis]" +``` + +### 1. pyan3 - Python Call Graph Analysis + +**Purpose**: Extract function call graphs from Python code + +**Package**: `pyan3>=1.2.0` (in optional-dependencies.enhanced-analysis) + +**Usage**: The `graph_analyzer.py` module automatically detects if `pyan3` is available and gracefully falls back if not installed. + +**Status**: ✅ **Available** - Install via `pip install -e ".[enhanced-analysis]"` + +### 2. Syft - Software Bill of Materials (SBOM) + +**Purpose**: Generate comprehensive SBOM of all dependencies (direct and transitive) + +**Package**: `syft>=0.9.5` (in optional-dependencies.enhanced-analysis) + +**Usage**: Will be integrated in `sbom_generator.py` (pending implementation) + +**Status**: ✅ **Available** - Install via `pip install -e ".[enhanced-analysis]"` + +### 3. Bearer - Data Flow Analysis + +**Purpose**: Track sensitive data flow through codebase for security analysis + +**Package**: `bearer>=3.1.0` (in optional-dependencies.enhanced-analysis) + +**Note**: Bearer primarily supports Java, Ruby, JS/TS. For Python projects, we may need Python-specific alternatives. + +**Status**: ✅ **Available** - Install via `pip install -e ".[enhanced-analysis]"` + +## Summary + +### Required Python Packages (in pyproject.toml dependencies) + +- ✅ `networkx>=3.4.2` - Already configured +- ✅ `graphviz>=0.20.1` - Added to dependencies + +### Optional Python Packages (in optional-dependencies.enhanced-analysis) + +Install all with: `pip install -e ".[enhanced-analysis]"` + +- ✅ `pyan3>=1.2.0` - Python call graph analysis +- ✅ `syft>=0.9.5` - Software Bill of Materials (SBOM) generation +- ✅ `bearer>=3.1.0` - Data flow analysis for security +- ✅ `graphviz>=0.20.1` - Graph visualization (also in main dependencies) + +### System Dependencies (Required for graphviz) + +- ⏳ `graphviz` (system package) - `apt-get install graphviz` or `brew install graphviz` + - The Python `graphviz` package is a wrapper that requires the system package + +## Installation Guide + +### Quick Install (All Enhanced Analysis Tools) + +```bash +# Install Python dependencies +pip install -e ".[enhanced-analysis]" + +# Install system Graphviz (required for graphviz Python package) +# Debian/Ubuntu: +sudo apt-get install graphviz + +# macOS: +brew install graphviz +``` + +### Individual Package Installation + +```bash +# Install specific packages +pip install pyan3>=1.2.0 +pip install syft>=0.9.5 +pip install bearer>=3.1.0 +pip install graphviz>=0.20.1 +``` + +## Graceful Degradation + +All graph analysis features are designed to work gracefully when optional tools are missing: + +- **pyan3 missing**: Call graph extraction returns empty (no error) +- **graphviz missing**: Diagram generation skipped (no error) +- **syft missing**: SBOM generation skipped (no error) +- **bearer missing**: Data flow analysis skipped (no error) + +The import command will continue to work with whatever tools are available, providing enhanced analysis when tools are present. diff --git a/_site_test/migration-guide/index.html b/_site_test/migration-guide/index.html new file mode 100644 index 0000000..cf21e01 --- /dev/null +++ b/_site_test/migration-guide/index.html @@ -0,0 +1,452 @@ + + + + + + + +Migration Guide | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Migration Guide

+ +
+

Decision tree and workflow for migrating between SpecFact CLI versions and from other tools

+
+ +
+ +

Overview

+ +

This guide helps you decide when and how to migrate:

+ +
    +
  • Between SpecFact CLI versions - When upgrading to a new version
    • +
  • From other tools - When migrating from Spec-Kit, OpenSpec, or other SDD tools
    • +
  • Between project structures - When restructuring your project bundles
    • +
+ +
+ +

Migration Decision Tree

+ +
Start: What do you need to migrate?
+
+├─ Upgrading SpecFact CLI version?
+│  ├─ Minor version (0.19 → 0.20)?
+│  │  └─ → Usually automatic, check [Version-Specific Migration Guides](#version-specific-migrations)
+│  ├─ Major version (0.x → 1.0)?
+│  │  └─ → Check breaking changes, use [Version-Specific Migration Guides](#version-specific-migrations)
+│  └─ CLI reorganization (pre-0.16 → 0.16+)?
+│     └─ → See [CLI Reorganization Migration](/specfact-cli/guides/migration-cli-reorganization.md)
+│
+├─ Migrating from Spec-Kit?
+│  └─ → See [Spec-Kit Journey Guide](/specfact-cli/guides/speckit-journey/)
+│
+├─ Migrating from OpenSpec?
+│  └─ → See [OpenSpec Journey Guide](/specfact-cli/guides/openspec-journey.md)
+│
+└─ Restructuring project bundles?
+   └─ → See [Project Bundle Management](/specfact-cli/reference/commands/#project---project-bundle-management)
+
+ +
+ +

Version-Specific Migrations

+ +

Migration from 0.16 to 0.19+

+ +

Breaking Changes: CLI command reorganization

+ +

Migration Steps:

+ +
    +
  1. Review CLI Reorganization Migration Guide
    2. +
  2. Update scripts and CI/CD pipelines
    3. +
  3. Test commands in development environment
    4. +
  4. Update documentation references
    5. +
+ +

Related: Migration 0.16 to 0.19

+ +
+ +

Migration from Pre-0.16 to 0.16+

+ +

Breaking Changes: Major CLI reorganization

+ +

Migration Steps:

+ +
    +
  1. Review CLI Reorganization Migration Guide
    2. +
  2. Update all command references
    3. +
  3. Migrate plan bundles to new schema
    4. +
  4. Update CI/CD configurations
    5. +
+ +

Related: CLI Reorganization Migration

+ +
+ +

Tool Migration Workflows

+ +

Migrating from Spec-Kit

+ +

Workflow: Use External Tool Integration Chain

+ +
    +
  1. Import from Spec-Kit via bridge adapter
    2. +
  2. Review imported plan
    3. +
  3. Set up bidirectional sync (optional)
    4. +
  4. Enforce SDD compliance
    5. +
+ +

Detailed Guide: Spec-Kit Journey Guide

+ +

Command Chain: External Tool Integration Chain

+ +
+ +

Migrating from OpenSpec

+ +

Workflow: Use External Tool Integration Chain

+ +
    +
  1. Import from OpenSpec via bridge adapter
    2. +
  2. Review imported change proposals
    3. +
  3. Set up DevOps sync (optional)
    4. +
  4. Enforce SDD compliance
    5. +
+ +

Detailed Guide: OpenSpec Journey Guide

+ +

Command Chain: External Tool Integration Chain

+ +
+ +

Project Structure Migrations

+ +

Migrating Between Project Bundles

+ +

When to use: Restructuring projects, splitting/merging bundles

+ +

Commands:

+ +
# Export from old bundle
+specfact project export --bundle old-bundle --persona <persona>
+
+# Create new bundle
+specfact plan init --bundle new-bundle
+
+# Import to new bundle (manual editing may be required)
+specfact project import --bundle new-bundle --persona <persona> --source exported.md
+
+ +

Related: Project Bundle Management

+ +
+ +

Plan Schema Migrations

+ +

Upgrading Plan Bundles

+ +

When to use: When plan bundles are on an older schema version

+ +

Command:

+ +
# Upgrade all bundles
+specfact plan upgrade --all
+
+# Upgrade specific bundle
+specfact plan upgrade --bundle <bundle-name>
+
+ +

Benefits:

+ +
    +
  • Improved performance (44% faster plan select)
    • +
  • New features and metadata
    • +
  • Better compatibility
    • +
+ +

Related: Plan Upgrade

+ +
+ +

Migration Workflow Examples

+ +

Example 1: Upgrading SpecFact CLI

+ +
# 1. Check current version
+specfact --version
+
+# 2. Review migration guide for target version
+# See: guides/migration-*.md
+
+# 3. Upgrade SpecFact CLI
+pip install --upgrade specfact-cli
+
+# 4. Upgrade plan bundles
+specfact plan upgrade --all
+
+# 5. Test commands
+specfact plan select --last 5
+
+ +
+ +

Example 2: Migrating from Spec-Kit

+ +
# 1. Import from Spec-Kit
+specfact import from-bridge --repo . --adapter speckit --write
+
+# 2. Review imported plan
+specfact plan review --bundle <bundle-name>
+
+# 3. Set up bidirectional sync (optional)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --bidirectional --watch
+
+# 4. Enforce SDD compliance
+specfact enforce sdd --bundle <bundle-name>
+
+ +

Related: Spec-Kit Journey Guide

+ +
+ +

Troubleshooting Migrations

+ +

Common Issues

+ +

Issue: Plan bundles fail to upgrade

+ +

Solution:

+ +
# Check bundle schema version
+specfact plan select --bundle <bundle-name> --json | jq '.schema_version'
+
+# Manual upgrade if needed
+specfact plan upgrade --bundle <bundle-name> --force
+
+ +

Issue: Imported plans have missing data

+ +

Solution:

+ +
    +
  1. Review import logs
    2. +
  2. Use plan review to identify gaps
    3. +
  3. Use plan update-feature to fill missing data
    4. +
  4. Re-import if needed
    5. +
+ +

Related: Troubleshooting Guide

+ +
+ +

See Also

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/modes/index.html b/_site_test/modes/index.html new file mode 100644 index 0000000..67f5cab --- /dev/null +++ b/_site_test/modes/index.html @@ -0,0 +1,546 @@ + + + + + + + +Operational Modes | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Operational Modes

+ +

Reference documentation for SpecFact CLI’s operational modes: CI/CD and CoPilot.

+ +

Overview

+ +

SpecFact CLI supports two operational modes for different use cases:

+ +
    +
  • CI/CD Mode (default): Fast, deterministic execution for automated pipelines
    • +
  • CoPilot Mode: Enhanced prompts with context injection for interactive development
    • +
+ +

Mode Detection

+ +

Mode is automatically detected based on:

+ +
    +
  1. Explicit --mode flag (highest priority)
    2. +
  2. CoPilot API availability (environment/IDE detection)
    3. +
  3. IDE integration (VS Code/Cursor with CoPilot enabled)
    4. +
  4. Default to CI/CD mode (fallback)
    5. +
+ +

Testing Mode Detection

+ +

This reference shows how to test mode detection and command routing in practice.

+ +

Quick Test Commands

+ +

Note: The CLI must be run through hatch run or installed first. Use hatch run specfact or install with hatch build && pip install -e ..

+ +

1. Test Explicit Mode Flags

+ +
# Test CI/CD mode explicitly
+hatch run specfact --mode cicd hello
+
+# Test CoPilot mode explicitly
+hatch run specfact --mode copilot hello
+
+# Test invalid mode (should fail)
+hatch run specfact --mode invalid hello
+
+# Test short form -m flag
+hatch run specfact -m cicd hello
+
+ +

Quick Test Script

+ +

Run the automated test script:

+ +
# Python-based test (recommended)
+python3 test_mode_practical.py
+
+# Or using hatch
+hatch run python test_mode_practical.py
+
+ +

This script tests all detection scenarios automatically.

+ +

2. Test Environment Variable

+ +
# Set environment variable and test
+export SPECFACT_MODE=copilot
+specfact hello
+
+# Set to CI/CD mode
+export SPECFACT_MODE=cicd
+specfact hello
+
+# Unset to test default
+unset SPECFACT_MODE
+specfact hello  # Should default to CI/CD
+
+ +

3. Test Auto-Detection

+ +

Test CoPilot API Detection

+ +
# Simulate CoPilot API available
+export COPILOT_API_URL=https://api.copilot.com
+specfact hello  # Should detect CoPilot mode
+
+# Or with token
+export COPILOT_API_TOKEN=token123
+specfact hello  # Should detect CoPilot mode
+
+# Or with GitHub Copilot token
+export GITHUB_COPILOT_TOKEN=token123
+specfact hello  # Should detect CoPilot mode
+
+ +

Test IDE Detection

+ +
# Simulate VS Code environment
+export VSCODE_PID=12345
+export COPILOT_ENABLED=true
+specfact hello  # Should detect CoPilot mode
+
+# Simulate Cursor environment
+export CURSOR_PID=12345
+export CURSOR_COPILOT_ENABLED=true
+specfact hello  # Should detect CoPilot mode
+
+# Simulate VS Code via TERM_PROGRAM
+export TERM_PROGRAM=vscode
+export VSCODE_COPILOT_ENABLED=true
+specfact hello  # Should detect CoPilot mode
+
+ +

4. Test Priority Order

+ +
# Test that explicit flag overrides environment
+export SPECFACT_MODE=copilot
+specfact --mode cicd hello  # Should use CI/CD mode (flag wins)
+
+# Test that explicit flag overrides auto-detection
+export COPILOT_API_URL=https://api.copilot.com
+specfact --mode cicd hello  # Should use CI/CD mode (flag wins)
+
+ +

5. Test Default Behavior

+ +
# Clean environment - should default to CI/CD
+unset SPECFACT_MODE
+unset COPILOT_API_URL
+unset COPILOT_API_TOKEN
+unset GITHUB_COPILOT_TOKEN
+unset VSCODE_PID
+unset CURSOR_PID
+specfact hello  # Should default to CI/CD mode
+
+ +

Python Interactive Testing

+ +

You can also test the detection logic directly in Python using hatch:

+ +
# Test explicit mode
+hatch run python -c "from specfact_cli.modes import OperationalMode, detect_mode; mode = detect_mode(explicit_mode=OperationalMode.CICD); print(f'Explicit CI/CD: {mode}')"
+
+# Test environment variable
+SPECFACT_MODE=copilot hatch run python -c "from specfact_cli.modes import OperationalMode, detect_mode; import os; mode = detect_mode(explicit_mode=None); print(f'Environment Copilot: {mode}')"
+
+# Test default
+hatch run python -c "from specfact_cli.modes import OperationalMode, detect_mode; import os; os.environ.clear(); mode = detect_mode(explicit_mode=None); print(f'Default: {mode}')"
+
+ +

Or use the practical test script:

+ +
hatch run python test_mode_practical.py
+
+ +

Testing Command Routing (Phase 3.2+)

+ +

Current State (Phase 3.2)

+ +

Important: In Phase 3.2, mode detection and routing infrastructure is complete, but actual command execution is identical for both modes. The only difference is the log message. Actual mode-specific behavior will be implemented in Phase 4.

+ +

Test with Actual Commands

+ +

The import from-code command now uses mode-aware routing. You should see mode information in the output (but execution is the same for now):

+ +
# Test with CI/CD mode (bundle name as positional argument)
+hatch run specfact --mode cicd import from-code test-project --repo . --confidence 0.5 --shadow-only
+
+# Expected output:
+# Mode: CI/CD (direct execution)
+# Analyzing repository: .
+# ...
+
+ +
# Test with CoPilot mode (bundle name as positional argument)
+hatch run specfact --mode copilot import from-code test-project --repo . --confidence 0.5 --shadow-only
+
+# Expected output:
+# Mode: CoPilot (agent routing)
+# Analyzing repository: .
+# ...
+
+ +

Test Router Directly

+ +

You can also test the routing logic directly in Python:

+ +
# Test router with CI/CD mode
+hatch run python -c "
+from specfact_cli.modes import OperationalMode, get_router
+router = get_router()
+result = router.route('import from-code', OperationalMode.CICD, {})
+print(f'Mode: {result.mode}')
+print(f'Execution mode: {result.execution_mode}')
+"
+
+# Test router with CoPilot mode
+hatch run python -c "
+from specfact_cli.modes import OperationalMode, get_router
+router = get_router()
+result = router.route('import from-code', OperationalMode.COPILOT, {})
+print(f'Mode: {result.mode}')
+print(f'Execution mode: {result.execution_mode}')
+"
+
+ +

Real-World Scenarios

+ +

Scenario 1: CI/CD Pipeline

+ +
# In GitHub Actions or CI/CD
+# No environment variables set
+# Should auto-detect CI/CD mode (bundle name as positional argument)
+hatch run specfact import from-code my-project --repo . --confidence 0.7
+
+# Expected: Mode: CI/CD (direct execution)
+
+ +

Scenario 2: Developer with CoPilot

+ +
# Developer running in VS Code/Cursor with CoPilot enabled
+# IDE environment variables automatically set
+# Should auto-detect CoPilot mode (bundle name as positional argument)
+hatch run specfact import from-code my-project --repo . --confidence 0.7
+
+# Expected: Mode: CoPilot (agent routing)
+
+ +

Scenario 3: Force Mode Override

+ +
# Developer wants CI/CD mode even though CoPilot is available (bundle name as positional argument)
+hatch run specfact --mode cicd import from-code my-project --repo . --confidence 0.7
+
+# Expected: Mode: CI/CD (direct execution) - flag overrides auto-detection
+
+ +

Verification Script

+ +

Here’s a simple script to test all scenarios:

+ +
#!/bin/bash
+# test-mode-detection.sh
+
+echo "=== Testing Mode Detection ==="
+echo
+
+echo "1. Testing explicit CI/CD mode:"
+specfact --mode cicd hello
+echo
+
+echo "2. Testing explicit CoPilot mode:"
+specfact --mode copilot hello
+echo
+
+echo "3. Testing invalid mode (should fail):"
+specfact --mode invalid hello 2>&1 || echo "✓ Failed as expected"
+echo
+
+echo "4. Testing SPECFACT_MODE environment variable:"
+export SPECFACT_MODE=copilot
+specfact hello
+unset SPECFACT_MODE
+echo
+
+echo "5. Testing CoPilot API detection:"
+export COPILOT_API_URL=https://api.copilot.com
+specfact hello
+unset COPILOT_API_URL
+echo
+
+echo "6. Testing default (no overrides):"
+specfact hello
+echo
+
+echo "=== All Tests Complete ==="
+
+ +

Debugging Mode Detection

+ +

To see what mode is being detected, you can add debug output:

+ +
# In Python
+from specfact_cli.modes import detect_mode, OperationalMode
+import os
+
+mode = detect_mode(explicit_mode=None)
+print(f"Detected mode: {mode}")
+print(f"Environment variables:")
+print(f"  SPECFACT_MODE: {os.environ.get('SPECFACT_MODE', 'not set')}")
+print(f"  COPILOT_API_URL: {os.environ.get('COPILOT_API_URL', 'not set')}")
+print(f"  VSCODE_PID: {os.environ.get('VSCODE_PID', 'not set')}")
+print(f"  CURSOR_PID: {os.environ.get('CURSOR_PID', 'not set')}")
+
+ +

Expected Results

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ScenarioExpected ModeNotes
--mode cicdCICDExplicit flag (highest priority)
--mode copilotCOPILOTExplicit flag (highest priority)
SPECFACT_MODE=copilotCOPILOTEnvironment variable
COPILOT_API_URL setCOPILOTAuto-detection
VSCODE_PID + COPILOT_ENABLED=trueCOPILOTIDE detection
Clean environmentCICDDefault fallback
Invalid modeErrorValidation rejects invalid values
+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/project-plans/speckit-test/architect.md b/_site_test/project-plans/speckit-test/architect.md new file mode 100644 index 0000000..d8d385a --- /dev/null +++ b/_site_test/project-plans/speckit-test/architect.md @@ -0,0 +1,4132 @@ +# Project Plan: speckit-test - Architect View + +**Persona**: Architect +**Bundle**: `speckit-test` +**Created**: 2025-12-11T23:26:08.394471+00:00 +**Status**: active +**Last Updated**: 2025-12-11T23:26:08.394488+00:00 + +## Technical Constraints & Requirements *(mandatory)* + +### FEATURE-PERFORMANCEMETRIC: Performance Metric + +#### Technical Constraints - FEATURE-PERFORMANCEMETRIC + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ARTIFACTMAPPING: Artifact Mapping + +#### Technical Constraints - FEATURE-ARTIFACTMAPPING + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SDDMANIFEST: S D D Manifest + +#### Technical Constraints - FEATURE-SDDMANIFEST + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-TEMPLATEMAPPING: Template Mapping + +#### Technical Constraints - FEATURE-TEMPLATEMAPPING + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CLIARTIFACTMETADATA: C L I Artifact Metadata + +#### Technical Constraints - FEATURE-CLIARTIFACTMETADATA + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-MOCKSERVER: Mock Server + +#### Technical Constraints - FEATURE-MOCKSERVER + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-FEATURESPECIFICATIONTEMPLATE: Feature Specification Template + +#### Technical Constraints - FEATURE-FEATURESPECIFICATIONTEMPLATE + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-TASKLIST: Task List + +#### Technical Constraints - FEATURE-TASKLIST + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-DEVIATIONREPORT: Deviation Report + +#### Technical Constraints - FEATURE-DEVIATIONREPORT + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROGRESSIVEDISCLOSUREGROUP: Progressive Disclosure Group + +#### Technical Constraints - FEATURE-PROGRESSIVEDISCLOSUREGROUP + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-VALIDATIONREPORT: Validation Report + +#### Technical Constraints - FEATURE-VALIDATIONREPORT + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CHECKRESULT: Check Result + +#### Technical Constraints - FEATURE-CHECKRESULT + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-TELEMETRYSETTINGS: Telemetry Settings + +#### Technical Constraints - FEATURE-TELEMETRYSETTINGS + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENRICHMENTPARSER: Enrichment Parser + +#### Technical Constraints - FEATURE-ENRICHMENTPARSER + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-YAMLUTILS: Y A M L Utils + +#### Technical Constraints - FEATURE-YAMLUTILS + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-TEXTUTILS: Text Utils + +#### Technical Constraints - FEATURE-TEXTUTILS + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-STRUCTUREDFORMAT: Structured Format + +#### Technical Constraints - FEATURE-STRUCTUREDFORMAT + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-FILEHASHCACHE: File Hash Cache + +#### Technical Constraints - FEATURE-FILEHASHCACHE + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SOURCETRACKING: Source Tracking + +#### Technical Constraints - FEATURE-SOURCETRACKING + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-TELEMETRYMANAGER: Telemetry Manager + +#### Technical Constraints - FEATURE-TELEMETRYMANAGER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROJECTCONTEXT: Project Context + +#### Technical Constraints - FEATURE-PROJECTCONTEXT + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENFORCEMENTCONFIG: Enforcement Config + +#### Technical Constraints - FEATURE-ENFORCEMENTCONFIG + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTRACTEXTRACTIONTEMPLATE: Contract Extraction Template + +#### Technical Constraints - FEATURE-CONTRACTEXTRACTIONTEMPLATE + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SCHEMAVALIDATOR: Schema Validator + +#### Technical Constraints - FEATURE-SCHEMAVALIDATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-REPROCHECKER: Repro Checker + +#### Technical Constraints - FEATURE-REPROCHECKER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-RELATIONSHIPMAPPER: Relationship Mapper + +#### Technical Constraints - FEATURE-RELATIONSHIPMAPPER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-DRIFTDETECTOR: Drift Detector + +#### Technical Constraints - FEATURE-DRIFTDETECTOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-AMBIGUITYSCANNER: Ambiguity Scanner + +#### Technical Constraints - FEATURE-AMBIGUITYSCANNER + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CHANGEDETECTOR: Change Detector + +#### Technical Constraints - FEATURE-CHANGEDETECTOR + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-AGENTMODE: Agent Mode + +#### Technical Constraints - FEATURE-AGENTMODE + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PERFORMANCEMONITOR: Performance Monitor + +#### Technical Constraints - FEATURE-PERFORMANCEMONITOR + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-FSMVALIDATOR: F S M Validator + +#### Technical Constraints - FEATURE-FSMVALIDATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROMPTVALIDATOR: Prompt Validator + +#### Technical Constraints - FEATURE-PROMPTVALIDATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECVALIDATIONRESULT: Spec Validation Result + +#### Technical Constraints - FEATURE-SPECVALIDATIONRESULT + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-LOGGERSETUP: Logger Setup + +#### Technical Constraints - FEATURE-LOGGERSETUP + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-AGENTREGISTRY: Agent Registry + +#### Technical Constraints - FEATURE-AGENTREGISTRY + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-REPROREPORT: Repro Report + +#### Technical Constraints - FEATURE-REPROREPORT + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-GITOPERATIONS: Git Operations + +#### Technical Constraints - FEATURE-GITOPERATIONS + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PERFORMANCEREPORT: Performance Report + +#### Technical Constraints - FEATURE-PERFORMANCEREPORT + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANENRICHER: Plan Enricher + +#### Technical Constraints - FEATURE-PLANENRICHER + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGEWATCHEVENTHANDLER: Bridge Watch Event Handler + +#### Technical Constraints - FEATURE-BRIDGEWATCHEVENTHANDLER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTRACTDENSITYMETRICS: Contract Density Metrics + +#### Technical Constraints - FEATURE-CONTRACTDENSITYMETRICS + +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENRICHMENTREPORT: Enrichment Report + +#### Technical Constraints - FEATURE-ENRICHMENTREPORT + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-IMPLEMENTATIONPLANTEMPLATE: Implementation Plan Template + +#### Technical Constraints - FEATURE-IMPLEMENTATIONPLANTEMPLATE + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SOURCEARTIFACTSCANNER: Source Artifact Scanner + +#### Technical Constraints - FEATURE-SOURCEARTIFACTSCANNER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-REQUIREMENTEXTRACTOR: Requirement Extractor + +#### Technical Constraints - FEATURE-REQUIREMENTEXTRACTOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANCOMPARATOR: Plan Comparator + +#### Technical Constraints - FEATURE-PLANCOMPARATOR + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROTOCOLGENERATOR: Protocol Generator + +#### Technical Constraints - FEATURE-PROTOCOLGENERATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SYNCWATCHER: Sync Watcher + +#### Technical Constraints - FEATURE-SYNCWATCHER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENRICHMENTCONTEXT: Enrichment Context + +#### Technical Constraints - FEATURE-ENRICHMENTCONTEXT + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SYNCAGENT: Sync Agent + +#### Technical Constraints - FEATURE-SYNCAGENT + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGEWATCH: Bridge Watch + +#### Technical Constraints - FEATURE-BRIDGEWATCH + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGECONFIG: Bridge Config + +#### Technical Constraints - FEATURE-BRIDGECONFIG + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-REPORTGENERATOR: Report Generator + +#### Technical Constraints - FEATURE-REPORTGENERATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONSTITUTIONENRICHER: Constitution Enricher + +#### Technical Constraints - FEATURE-CONSTITUTIONENRICHER + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENHANCEDSYNCWATCHER: Enhanced Sync Watcher + +#### Technical Constraints - FEATURE-ENHANCEDSYNCWATCHER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTRACTGENERATOR: Contract Generator + +#### Technical Constraints - FEATURE-CONTRACTGENERATOR + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-WORKFLOWGENERATOR: Workflow Generator + +#### Technical Constraints - FEATURE-WORKFLOWGENERATOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-MESSAGEFLOWFORMATTER: Message Flow Formatter + +#### Technical Constraints - FEATURE-MESSAGEFLOWFORMATTER + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGESYNC: Bridge Sync + +#### Technical Constraints - FEATURE-BRIDGESYNC + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-REPOSITORYSYNC: Repository Sync + +#### Technical Constraints - FEATURE-REPOSITORYSYNC + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROGRESSIVEDISCLOSURECOMMAND: Progressive Disclosure Command + +#### Technical Constraints - FEATURE-PROGRESSIVEDISCLOSURECOMMAND + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANMIGRATOR: Plan Migrator + +#### Technical Constraints - FEATURE-PLANMIGRATOR + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-COMMANDROUTER: Command Router + +#### Technical Constraints - FEATURE-COMMANDROUTER + +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTROLFLOWANALYZER: Control Flow Analyzer + +#### Technical Constraints - FEATURE-CONTROLFLOWANALYZER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-GRAPHANALYZER: Graph Analyzer + +#### Technical Constraints - FEATURE-GRAPHANALYZER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SMARTCOVERAGEMANAGER: Smart Coverage Manager + +#### Technical Constraints - FEATURE-SMARTCOVERAGEMANAGER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CODEANALYZER: Code Analyzer + +#### Technical Constraints - FEATURE-CODEANALYZER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SYNCEVENTHANDLER: Sync Event Handler + +#### Technical Constraints - FEATURE-SYNCEVENTHANDLER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECKITCONVERTER: Spec Kit Converter + +#### Technical Constraints - FEATURE-SPECKITCONVERTER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR: Constitution Evidence Extractor + +#### Technical Constraints - FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTRACTEXTRACTOR: Contract Extractor + +#### Technical Constraints - FEATURE-CONTRACTEXTRACTOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PROJECTBUNDLE: Project Bundle + +#### Technical Constraints - FEATURE-PROJECTBUNDLE + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-OPENAPIEXTRACTOR: Open A P I Extractor + +#### Technical Constraints - FEATURE-OPENAPIEXTRACTOR + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must support asynchronous operations for improved performance +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECKITSCANNER: Spec Kit Scanner + +#### Technical Constraints - FEATURE-SPECKITSCANNER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ENHANCEDSYNCEVENTHANDLER: Enhanced Sync Event Handler + +#### Technical Constraints - FEATURE-ENHANCEDSYNCEVENTHANDLER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGEPROBE: Bridge Probe + +#### Technical Constraints - FEATURE-BRIDGEPROBE + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANAGENT: Plan Agent + +#### Technical Constraints - FEATURE-PLANAGENT + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-ANALYZEAGENT: Analyze Agent + +#### Technical Constraints - FEATURE-ANALYZEAGENT + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANBUNDLE: Plan Bundle + +#### Technical Constraints - FEATURE-PLANBUNDLE + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CODETOSPECSYNC: Code To Spec Sync + +#### Technical Constraints - FEATURE-CODETOSPECSYNC + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-BRIDGETEMPLATELOADER: Bridge Template Loader + +#### Technical Constraints - FEATURE-BRIDGETEMPLATELOADER + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECTOCODESYNC: Spec To Code Sync + +#### Technical Constraints - FEATURE-SPECTOCODESYNC + +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-PLANGENERATOR: Plan Generator + +#### Technical Constraints - FEATURE-PLANGENERATOR + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECKITSYNC: Spec Kit Sync + +#### Technical Constraints - FEATURE-SPECKITSYNC + +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-SPECFACTSTRUCTURE: Spec Fact Structure + +#### Technical Constraints - FEATURE-SPECFACTSTRUCTURE + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-OPENAPITESTCONVERTER: Open A P I Test Converter + +#### Technical Constraints - FEATURE-OPENAPITESTCONVERTER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support +### FEATURE-CONTRACTFIRSTTESTMANAGER: Contract First Test Manager + +#### Technical Constraints - FEATURE-CONTRACTFIRSTTESTMANAGER + +- The system must meet performance requirements (async operations, caching, optimization) +- The system must meet security requirements (authentication, authorization, encryption) +- The system must meet reliability requirements (error handling, retry logic, resilience) +- The system must meet maintainability requirements (documentation, type hints, testing) +- The system must use type hints for improved code maintainability and IDE support + +## Protocols & State Machines *(mandatory)* + +*[ACTION REQUIRED: Define protocols and state machines]* + +**Note**: Protocols should be defined in `.specfact/projects/speckit-test/protocols/*.protocol.yaml` files. + +## Contracts *(mandatory)* + +### FEATURE-PERFORMANCEREPORT + +**Info**: + +- **Title**: Performance Report +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Performance Report**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/performance-metric/to-dict`: + - `GET`: To Dict +- `/performance-report/add-metric`: + - `POST`: Add Metric +- `/performance-report/get-summary`: + - `GET`: Get Summary +- `/performance-report/print-summary`: + - `GET`: Print Summary +- `/performance-monitor/start`: + - `GET`: Start +- `/performance-monitor/stop`: + - `GET`: Stop +- `/performance-monitor/track`: + - `GET`: Track +- `/performance-monitor/get-report`: + - `GET`: Get Report +- `/performance-monitor/disable`: + - `GET`: Disable +- `/performance-monitor/enable`: + - `GET`: Enable +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String + +---### FEATURE-SPECKITSCANNER + +**Info**: + +- **Title**: Spec Kit Scanner +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec Kit Scanner**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/source-artifact-scanner/scan-repository`: + - `GET`: Scan Repository +- `/source-artifact-scanner/link-to-specs`: + - `GET`: Link To Specs +- `/source-artifact-scanner/extract-function-mappings`: + - `GET`: Extract Function Mappings +- `/source-artifact-scanner/extract-test-mappings`: + - `GET`: Extract Test Mappings +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +- `/ambiguity-scanner/scan`: + - `GET`: Scan +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop + +---### FEATURE-CODETOSPECSYNC + +**Info**: + +- **Title**: Code To Spec Sync +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Code To Spec Sync**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files + +---### FEATURE-SPECVALIDATIONRESULT + +**Info**: + +- **Title**: Spec Validation Result +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec Validation Result**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-ENRICHMENTPARSER + +**Info**: + +- **Title**: Enrichment Parser +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enrichment Parser**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/enrichment-context/add-relationships`: + - `POST`: Add Relationships +- `/enrichment-context/add-contract`: + - `POST`: Add Contract +- `/enrichment-context/add-bundle-metadata`: + - `POST`: Add Bundle Metadata +- `/enrichment-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/to-markdown`: + - `GET`: To Markdown +- `/enrichment-report/add-missing-feature`: + - `POST`: Add Missing Feature +- `/enrichment-report/adjust-confidence`: + - `GET`: Adjust Confidence +- `/enrichment-report/add-business-context`: + - `POST`: Add Business Context +- `/enrichment-parser/parse`: + - `GET`: Parse + +---### FEATURE-VALIDATIONREPORT + +**Info**: + +- **Title**: Validation Report +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Validation Report**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String + +---### FEATURE-ENRICHMENTCONTEXT + +**Info**: + +- **Title**: Enrichment Context +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enrichment Context**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/enrichment-report/add-missing-feature`: + - `POST`: Add Missing Feature +- `/enrichment-report/adjust-confidence`: + - `GET`: Adjust Confidence +- `/enrichment-report/add-business-context`: + - `POST`: Add Business Context +- `/enrichment-parser/parse`: + - `GET`: Parse +- `/project-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/add-relationships`: + - `POST`: Add Relationships +- `/enrichment-context/add-contract`: + - `POST`: Add Contract +- `/enrichment-context/add-bundle-metadata`: + - `POST`: Add Bundle Metadata +- `/enrichment-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/to-markdown`: + - `GET`: To Markdown + +---### FEATURE-PROTOCOLGENERATOR + +**Info**: + +- **Title**: Protocol Generator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Protocol Generator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String +- `/protocol-generator/generate`: + - `GET`: Generate +- `/protocol-generator/generate-from-template`: + - `GET`: Generate From Template +- `/protocol-generator/render-string`: + - `GET`: Render String +**Schemas**: + +- `Transition`: object +- `Protocol`: object + +---### FEATURE-REQUIREMENTEXTRACTOR + +**Info**: + +- **Title**: Requirement Extractor +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Requirement Extractor**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/requirement-extractor/extract-complete-requirement`: + - `GET`: Extract Complete Requirement +- `/requirement-extractor/extract-method-requirement`: + - `GET`: Extract Method Requirement +- `/requirement-extractor/extract-nfrs`: + - `GET`: Extract Nfrs +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/open-a-p-i-extractor/extract-openapi-from-verbose`: + - `GET`: Extract Openapi From Verbose +- `/open-a-p-i-extractor/extract-openapi-from-code`: + - `GET`: Extract Openapi From Code +- `/open-a-p-i-extractor/add-test-examples`: + - `POST`: Add Test Examples +- `/open-a-p-i-extractor/save-openapi-contract`: + - `GET`: Save Openapi Contract +- `/constitution-evidence-extractor/extract-article-vii-evidence`: + - `GET`: Extract Article Vii Evidence +- `/constitution-evidence-extractor/extract-article-viii-evidence`: + - `GET`: Extract Article Viii Evidence +- `/constitution-evidence-extractor/extract-article-ix-evidence`: + - `GET`: Extract Article Ix Evidence +- `/constitution-evidence-extractor/extract-all-evidence`: + - `GET`: Extract All Evidence +- `/constitution-evidence-extractor/generate-constitution-check-section`: + - `GET`: Generate Constitution Check Section + +---### FEATURE-PROJECTBUNDLE + +**Info**: + +- **Title**: Project Bundle +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Project Bundle**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/project-bundle/load-from-directory`: + - `GET`: Load From Directory +- `/project-bundle/save-to-directory`: + - `GET`: Save To Directory +- `/project-bundle/get-feature/{key}`: + - `GET`: Get Feature +- `/project-bundle/add-feature`: + - `POST`: Add Feature +- `/project-bundle/update-feature/{key}`: + - `PUT`: Update Feature +- `/project-bundle/compute-summary`: + - `PUT`: Compute Summary +**Schemas**: + +- `BundleVersions`: object +- `SchemaMetadata`: object +- `ProjectMetadata`: object +- `BundleChecksums`: object +- `SectionLock`: object +- `PersonaMapping`: object +- `FeatureIndex`: object +- `ProtocolIndex`: object +- `BundleManifest`: object +- `ProjectBundle`: object + +---### FEATURE-SPECFACTSTRUCTURE + +**Info**: + +- **Title**: Spec Fact Structure +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec Fact Structure**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop +- `/spec-fact-structure/plan-suffix`: + - `GET`: Plan Suffix +- `/spec-fact-structure/ensure-plan-filename`: + - `GET`: Ensure Plan Filename +- `/spec-fact-structure/strip-plan-suffix`: + - `GET`: Strip Plan Suffix +- `/spec-fact-structure/default-plan-filename`: + - `GET`: Default Plan Filename +- `/spec-fact-structure/ensure-structure`: + - `GET`: Ensure Structure +- `/spec-fact-structure/get-timestamped-report-path`: + - `GET`: Get Timestamped Report Path +- `/spec-fact-structure/get-brownfield-analysis-path`: + - `GET`: Get Brownfield Analysis Path +- `/spec-fact-structure/get-brownfield-plan-path`: + - `GET`: Get Brownfield Plan Path +- `/spec-fact-structure/get-comparison-report-path`: + - `GET`: Get Comparison Report Path +- `/spec-fact-structure/get-default-plan-path`: + - `GET`: Get Default Plan Path +- `/spec-fact-structure/get-active-bundle-name`: + - `GET`: Get Active Bundle Name +- `/spec-fact-structure/set-active-plan`: + - `GET`: Set Active Plan +- `/spec-fact-structure/list-plans`: + - `GET`: List Plans +- `/spec-fact-structure/update-plan-summary`: + - `PUT`: Update Plan Summary +- `/spec-fact-structure/get-enforcement-config-path`: + - `GET`: Get Enforcement Config Path +- `/spec-fact-structure/get-sdd-path`: + - `GET`: Get Sdd Path +- `/spec-fact-structure/sanitize-plan-name/{name}`: + - `GET`: Sanitize Plan Name +- `/spec-fact-structure/get-timestamped-brownfield-report/{name}`: + - `GET`: Get Timestamped Brownfield Report +- `/spec-fact-structure/get-enrichment-report-path`: + - `GET`: Get Enrichment Report Path +- `/spec-fact-structure/get-plan-bundle-from-enrichment`: + - `GET`: Get Plan Bundle From Enrichment +- `/spec-fact-structure/get-enriched-plan-path`: + - `GET`: Get Enriched Plan Path +- `/spec-fact-structure/get-latest-brownfield-report`: + - `GET`: Get Latest Brownfield Report +- `/spec-fact-structure/create-gitignore`: + - `POST`: Create Gitignore +- `/spec-fact-structure/create-readme`: + - `POST`: Create Readme +- `/spec-fact-structure/scaffold-project`: + - `GET`: Scaffold Project +- `/spec-fact-structure/project-dir`: + - `GET`: Project Dir +- `/spec-fact-structure/ensure-project-structure`: + - `GET`: Ensure Project Structure +- `/spec-fact-structure/detect-bundle-format`: + - `GET`: Detect Bundle Format +- `/spec-fact-structure/get-bundle-reports-dir`: + - `GET`: Get Bundle Reports Dir +- `/spec-fact-structure/get-bundle-brownfield-report-path`: + - `GET`: Get Bundle Brownfield Report Path +- `/spec-fact-structure/get-bundle-comparison-report-path`: + - `GET`: Get Bundle Comparison Report Path +- `/spec-fact-structure/get-bundle-enrichment-report-path`: + - `GET`: Get Bundle Enrichment Report Path +- `/spec-fact-structure/get-bundle-enforcement-report-path`: + - `GET`: Get Bundle Enforcement Report Path +- `/spec-fact-structure/get-bundle-sdd-path`: + - `GET`: Get Bundle Sdd Path +- `/spec-fact-structure/get-bundle-tasks-path`: + - `GET`: Get Bundle Tasks Path +- `/spec-fact-structure/get-bundle-logs-dir`: + - `GET`: Get Bundle Logs Dir +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +- `/structured-format/from-string`: + - `GET`: From String +- `/structured-format/from-path`: + - `GET`: From Path + +---### FEATURE-SYNCEVENTHANDLER + +**Info**: + +- **Title**: Sync Event Handler +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Sync Event Handler**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-PERFORMANCEMONITOR + +**Info**: + +- **Title**: Performance Monitor +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Performance Monitor**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/performance-metric/to-dict`: + - `GET`: To Dict +- `/performance-report/add-metric`: + - `POST`: Add Metric +- `/performance-report/get-summary`: + - `GET`: Get Summary +- `/performance-report/print-summary`: + - `GET`: Print Summary +- `/performance-monitor/start`: + - `GET`: Start +- `/performance-monitor/stop`: + - `GET`: Stop +- `/performance-monitor/track`: + - `GET`: Track +- `/performance-monitor/get-report`: + - `GET`: Get Report +- `/performance-monitor/disable`: + - `GET`: Disable +- `/performance-monitor/enable`: + - `GET`: Enable + +---### FEATURE-SPECKITSYNC + +**Info**: + +- **Title**: Spec Kit Sync +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec Kit Sync**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-SYNCWATCHER + +**Info**: + +- **Title**: Sync Watcher +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Sync Watcher**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/file-hash-cache/load`: + - `GET`: Load +- `/file-hash-cache/save`: + - `GET`: Save +- `/file-hash-cache/get-hash`: + - `GET`: Get Hash +- `/file-hash-cache/set-hash`: + - `GET`: Set Hash +- `/file-hash-cache/get-dependencies`: + - `GET`: Get Dependencies +- `/file-hash-cache/set-dependencies`: + - `GET`: Set Dependencies +- `/file-hash-cache/has-changed`: + - `GET`: Has Changed +- `/enhanced-sync-event-handler/on-modified`: + - `GET`: On Modified +- `/enhanced-sync-event-handler/on-created`: + - `POST`: On Created +- `/enhanced-sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/enhanced-sync-watcher/start`: + - `GET`: Start +- `/enhanced-sync-watcher/stop`: + - `GET`: Stop +- `/enhanced-sync-watcher/watch`: + - `GET`: Watch +- `/sync-event-handler/on-modified`: + - `GET`: On Modified +- `/sync-event-handler/on-created`: + - `POST`: On Created +- `/sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/sync-watcher/start`: + - `GET`: Start +- `/sync-watcher/stop`: + - `GET`: Stop +- `/sync-watcher/watch`: + - `GET`: Watch +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-BRIDGEPROBE + +**Info**: + +- **Title**: Bridge Probe +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Probe**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-ANALYZEAGENT + +**Info**: + +- **Title**: Analyze Agent +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Analyze Agent**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/analyze-agent/execute`: + - `GET`: Execute +- `/analyze-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/analyze-codebase`: + - `GET`: Analyze Codebase +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/graph-analyzer/extract-call-graph`: + - `GET`: Extract Call Graph +- `/graph-analyzer/build-dependency-graph`: + - `GET`: Build Dependency Graph +- `/graph-analyzer/get-graph-summary`: + - `GET`: Get Graph Summary +- `/control-flow-analyzer/extract-scenarios-from-method`: + - `GET`: Extract Scenarios From Method + +---### FEATURE-PLANBUNDLE + +**Info**: + +- **Title**: Plan Bundle +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Bundle**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-CONTRACTEXTRACTIONTEMPLATE + +**Info**: + +- **Title**: Contract Extraction Template +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Contract Extraction Template**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator + +---### FEATURE-BRIDGEWATCH + +**Info**: + +- **Title**: Bridge Watch +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Watch**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/file-hash-cache/load`: + - `GET`: Load +- `/file-hash-cache/save`: + - `GET`: Save +- `/file-hash-cache/get-hash`: + - `GET`: Get Hash +- `/file-hash-cache/set-hash`: + - `GET`: Set Hash +- `/file-hash-cache/get-dependencies`: + - `GET`: Get Dependencies +- `/file-hash-cache/set-dependencies`: + - `GET`: Set Dependencies +- `/file-hash-cache/has-changed`: + - `GET`: Has Changed +- `/enhanced-sync-event-handler/on-modified`: + - `GET`: On Modified +- `/enhanced-sync-event-handler/on-created`: + - `POST`: On Created +- `/enhanced-sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/enhanced-sync-watcher/start`: + - `GET`: Start +- `/enhanced-sync-watcher/stop`: + - `GET`: Stop +- `/enhanced-sync-watcher/watch`: + - `GET`: Watch +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +- `/sync-event-handler/on-modified`: + - `GET`: On Modified +- `/sync-event-handler/on-created`: + - `POST`: On Created +- `/sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/sync-watcher/start`: + - `GET`: Start +- `/sync-watcher/stop`: + - `GET`: Stop +- `/sync-watcher/watch`: + - `GET`: Watch +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-PROGRESSIVEDISCLOSURECOMMAND + +**Info**: + +- **Title**: Progressive Disclosure Command +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Progressive Disclosure Command**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/progressive-disclosure-group/get-params`: + - `GET`: Get Params +- `/progressive-disclosure-command/format-help`: + - `GET`: Format Help +- `/progressive-disclosure-command/get-params`: + - `GET`: Get Params + +---### FEATURE-AGENTMODE + +**Info**: + +- **Title**: Agent Mode +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Agent Mode**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/analyze-agent/execute`: + - `GET`: Execute +- `/analyze-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/analyze-codebase`: + - `GET`: Analyze Codebase + +---### FEATURE-PLANENRICHER + +**Info**: + +- **Title**: Plan Enricher +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Enricher**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/constitution-enricher/analyze-repository`: + - `GET`: Analyze Repository +- `/constitution-enricher/suggest-principles`: + - `GET`: Suggest Principles +- `/constitution-enricher/enrich-template`: + - `GET`: Enrich Template +- `/constitution-enricher/bootstrap`: + - `GET`: Bootstrap +- `/constitution-enricher/validate`: + - `GET`: Validate +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-BRIDGETEMPLATELOADER + +**Info**: + +- **Title**: Bridge Template Loader +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Template Loader**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-CONSTITUTIONENRICHER + +**Info**: + +- **Title**: Constitution Enricher +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Constitution Enricher**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/constitution-enricher/analyze-repository`: + - `GET`: Analyze Repository +- `/constitution-enricher/suggest-principles`: + - `GET`: Suggest Principles +- `/constitution-enricher/enrich-template`: + - `GET`: Enrich Template +- `/constitution-enricher/bootstrap`: + - `GET`: Bootstrap +- `/constitution-enricher/validate`: + - `GET`: Validate +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/constitution-evidence-extractor/extract-article-vii-evidence`: + - `GET`: Extract Article Vii Evidence +- `/constitution-evidence-extractor/extract-article-viii-evidence`: + - `GET`: Extract Article Viii Evidence +- `/constitution-evidence-extractor/extract-article-ix-evidence`: + - `GET`: Extract Article Ix Evidence +- `/constitution-evidence-extractor/extract-all-evidence`: + - `GET`: Extract All Evidence +- `/constitution-evidence-extractor/generate-constitution-check-section`: + - `GET`: Generate Constitution Check Section + +---### FEATURE-SOURCETRACKING + +**Info**: + +- **Title**: Source Tracking +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Source Tracking**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/source-tracking/compute-hash`: + - `PUT`: Compute Hash +- `/source-tracking/has-changed`: + - `GET`: Has Changed +- `/source-tracking/update-hash`: + - `PUT`: Update Hash +- `/source-tracking/update-sync-timestamp`: + - `PUT`: Update Sync Timestamp +- `/source-artifact-scanner/scan-repository`: + - `GET`: Scan Repository +- `/source-artifact-scanner/link-to-specs`: + - `GET`: Link To Specs +- `/source-artifact-scanner/extract-function-mappings`: + - `GET`: Extract Function Mappings +- `/source-artifact-scanner/extract-test-mappings`: + - `GET`: Extract Test Mappings +**Schemas**: + +- `SourceTracking`: object + +---### FEATURE-CONTRACTDENSITYMETRICS + +**Info**: + +- **Title**: Contract Density Metrics +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Contract Density Metrics**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator + +---### FEATURE-AMBIGUITYSCANNER + +**Info**: + +- **Title**: Ambiguity Scanner +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Ambiguity Scanner**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/source-artifact-scanner/scan-repository`: + - `GET`: Scan Repository +- `/source-artifact-scanner/link-to-specs`: + - `GET`: Link To Specs +- `/source-artifact-scanner/extract-function-mappings`: + - `GET`: Extract Function Mappings +- `/source-artifact-scanner/extract-test-mappings`: + - `GET`: Extract Test Mappings +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/ambiguity-scanner/scan`: + - `GET`: Scan + +---### FEATURE-ENHANCEDSYNCEVENTHANDLER + +**Info**: + +- **Title**: Enhanced Sync Event Handler +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enhanced Sync Event Handler**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/file-hash-cache/load`: + - `GET`: Load +- `/file-hash-cache/save`: + - `GET`: Save +- `/file-hash-cache/get-hash`: + - `GET`: Get Hash +- `/file-hash-cache/set-hash`: + - `GET`: Set Hash +- `/file-hash-cache/get-dependencies`: + - `GET`: Get Dependencies +- `/file-hash-cache/set-dependencies`: + - `GET`: Set Dependencies +- `/file-hash-cache/has-changed`: + - `GET`: Has Changed +- `/enhanced-sync-event-handler/on-modified`: + - `GET`: On Modified +- `/enhanced-sync-event-handler/on-created`: + - `POST`: On Created +- `/enhanced-sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/enhanced-sync-watcher/start`: + - `GET`: Start +- `/enhanced-sync-watcher/stop`: + - `GET`: Stop +- `/enhanced-sync-watcher/watch`: + - `GET`: Watch +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-CHANGEDETECTOR + +**Info**: + +- **Title**: Change Detector +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Change Detector**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/drift-detector/scan`: + - `GET`: Scan +- `/change-detector/detect-changes`: + - `GET`: Detect Changes + +---### FEATURE-CONTROLFLOWANALYZER + +**Info**: + +- **Title**: Control Flow Analyzer +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Control Flow Analyzer**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/graph-analyzer/extract-call-graph`: + - `GET`: Extract Call Graph +- `/graph-analyzer/build-dependency-graph`: + - `GET`: Build Dependency Graph +- `/graph-analyzer/get-graph-summary`: + - `GET`: Get Graph Summary +- `/control-flow-analyzer/extract-scenarios-from-method`: + - `GET`: Extract Scenarios From Method + +---### FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR + +**Info**: + +- **Title**: Constitution Evidence Extractor +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Constitution Evidence Extractor**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/requirement-extractor/extract-complete-requirement`: + - `GET`: Extract Complete Requirement +- `/requirement-extractor/extract-method-requirement`: + - `GET`: Extract Method Requirement +- `/requirement-extractor/extract-nfrs`: + - `GET`: Extract Nfrs +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/open-a-p-i-extractor/extract-openapi-from-verbose`: + - `GET`: Extract Openapi From Verbose +- `/open-a-p-i-extractor/extract-openapi-from-code`: + - `GET`: Extract Openapi From Code +- `/open-a-p-i-extractor/add-test-examples`: + - `POST`: Add Test Examples +- `/open-a-p-i-extractor/save-openapi-contract`: + - `GET`: Save Openapi Contract +- `/constitution-evidence-extractor/extract-article-vii-evidence`: + - `GET`: Extract Article Vii Evidence +- `/constitution-evidence-extractor/extract-article-viii-evidence`: + - `GET`: Extract Article Viii Evidence +- `/constitution-evidence-extractor/extract-article-ix-evidence`: + - `GET`: Extract Article Ix Evidence +- `/constitution-evidence-extractor/extract-all-evidence`: + - `GET`: Extract All Evidence +- `/constitution-evidence-extractor/generate-constitution-check-section`: + - `GET`: Generate Constitution Check Section +- `/constitution-enricher/analyze-repository`: + - `GET`: Analyze Repository +- `/constitution-enricher/suggest-principles`: + - `GET`: Suggest Principles +- `/constitution-enricher/enrich-template`: + - `GET`: Enrich Template +- `/constitution-enricher/bootstrap`: + - `GET`: Bootstrap +- `/constitution-enricher/validate`: + - `GET`: Validate + +---### FEATURE-TEMPLATEMAPPING + +**Info**: + +- **Title**: Template Mapping +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Template Mapping**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict + +---### FEATURE-PLANMIGRATOR + +**Info**: + +- **Title**: Plan Migrator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Migrator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-TASKLIST + +**Info**: + +- **Title**: Task List +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Task List**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/task-list/get-tasks-by-phase`: + - `GET`: Get Tasks By Phase +- `/task-list/get-task`: + - `GET`: Get Task +- `/task-list/get-dependencies`: + - `GET`: Get Dependencies +**Schemas**: + +- `Task`: object +- `TaskList`: object + +---### FEATURE-OPENAPITESTCONVERTER + +**Info**: + +- **Title**: Open A P I Test Converter +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Open A P I Test Converter**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/open-a-p-i-extractor/extract-openapi-from-verbose`: + - `GET`: Extract Openapi From Verbose +- `/open-a-p-i-extractor/extract-openapi-from-code`: + - `GET`: Extract Openapi From Code +- `/open-a-p-i-extractor/add-test-examples`: + - `POST`: Add Test Examples +- `/open-a-p-i-extractor/save-openapi-contract`: + - `GET`: Save Openapi Contract +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit + +---### FEATURE-ENFORCEMENTCONFIG + +**Info**: + +- **Title**: Enforcement Config +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enforcement Config**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/enforcement-config/from-preset`: + - `GET`: From Preset +- `/enforcement-config/should-block-deviation`: + - `GET`: Should Block Deviation +- `/enforcement-config/get-action`: + - `GET`: Get Action +- `/enforcement-config/to-summary-dict`: + - `GET`: To Summary Dict +**Schemas**: + +- `EnforcementConfig`: object + +---### FEATURE-GRAPHANALYZER + +**Info**: + +- **Title**: Graph Analyzer +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Graph Analyzer**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/graph-analyzer/extract-call-graph`: + - `GET`: Extract Call Graph +- `/graph-analyzer/build-dependency-graph`: + - `GET`: Build Dependency Graph +- `/graph-analyzer/get-graph-summary`: + - `GET`: Get Graph Summary +- `/control-flow-analyzer/extract-scenarios-from-method`: + - `GET`: Extract Scenarios From Method + +---### FEATURE-PROJECTCONTEXT + +**Info**: + +- **Title**: Project Context +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Project Context**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/enrichment-context/add-relationships`: + - `POST`: Add Relationships +- `/enrichment-context/add-contract`: + - `POST`: Add Contract +- `/enrichment-context/add-bundle-metadata`: + - `POST`: Add Bundle Metadata +- `/enrichment-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/to-markdown`: + - `GET`: To Markdown +- `/project-bundle/load-from-directory`: + - `GET`: Load From Directory +- `/project-bundle/save-to-directory`: + - `GET`: Save To Directory +- `/project-bundle/get-feature/{key}`: + - `GET`: Get Feature +- `/project-bundle/add-feature`: + - `POST`: Add Feature +- `/project-bundle/update-feature/{key}`: + - `PUT`: Update Feature +- `/project-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/project-context/to-dict`: + - `GET`: To Dict +**Schemas**: + +- `BundleVersions`: object +- `SchemaMetadata`: object +- `ProjectMetadata`: object +- `BundleChecksums`: object +- `SectionLock`: object +- `PersonaMapping`: object +- `FeatureIndex`: object +- `ProtocolIndex`: object +- `BundleManifest`: object +- `ProjectBundle`: object + +---### FEATURE-PLANCOMPARATOR + +**Info**: + +- **Title**: Plan Comparator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Comparator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-CONTRACTEXTRACTOR + +**Info**: + +- **Title**: Contract Extractor +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Contract Extractor**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/requirement-extractor/extract-complete-requirement`: + - `GET`: Extract Complete Requirement +- `/requirement-extractor/extract-method-requirement`: + - `GET`: Extract Method Requirement +- `/requirement-extractor/extract-nfrs`: + - `GET`: Extract Nfrs +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/open-a-p-i-extractor/extract-openapi-from-verbose`: + - `GET`: Extract Openapi From Verbose +- `/open-a-p-i-extractor/extract-openapi-from-code`: + - `GET`: Extract Openapi From Code +- `/open-a-p-i-extractor/add-test-examples`: + - `POST`: Add Test Examples +- `/open-a-p-i-extractor/save-openapi-contract`: + - `GET`: Save Openapi Contract +- `/constitution-evidence-extractor/extract-article-vii-evidence`: + - `GET`: Extract Article Vii Evidence +- `/constitution-evidence-extractor/extract-article-viii-evidence`: + - `GET`: Extract Article Viii Evidence +- `/constitution-evidence-extractor/extract-article-ix-evidence`: + - `GET`: Extract Article Ix Evidence +- `/constitution-evidence-extractor/extract-all-evidence`: + - `GET`: Extract All Evidence +- `/constitution-evidence-extractor/generate-constitution-check-section`: + - `GET`: Generate Constitution Check Section + +---### FEATURE-ENRICHMENTREPORT + +**Info**: + +- **Title**: Enrichment Report +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enrichment Report**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String +- `/enrichment-report/add-missing-feature`: + - `POST`: Add Missing Feature +- `/enrichment-report/adjust-confidence`: + - `GET`: Adjust Confidence +- `/enrichment-report/add-business-context`: + - `POST`: Add Business Context +- `/enrichment-parser/parse`: + - `GET`: Parse +- `/enrichment-context/add-relationships`: + - `POST`: Add Relationships +- `/enrichment-context/add-contract`: + - `POST`: Add Contract +- `/enrichment-context/add-bundle-metadata`: + - `POST`: Add Bundle Metadata +- `/enrichment-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/to-markdown`: + - `GET`: To Markdown + +---### FEATURE-COMMANDROUTER + +**Info**: + +- **Title**: Command Router +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Command Router**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/command-router/route`: + - `GET`: Route +- `/command-router/route-with-auto-detect`: + - `GET`: Route With Auto Detect +- `/command-router/should-use-agent`: + - `GET`: Should Use Agent +- `/command-router/should-use-direct`: + - `GET`: Should Use Direct + +---### FEATURE-BRIDGESYNC + +**Info**: + +- **Title**: Bridge Sync +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Sync**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-PLANAGENT + +**Info**: + +- **Title**: Plan Agent +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Agent**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/analyze-agent/execute`: + - `GET`: Execute +- `/analyze-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/analyze-codebase`: + - `GET`: Analyze Codebase +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-TEXTUTILS + +**Info**: + +- **Title**: Text Utils +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Text Utils**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/y-a-m-l-utils/load`: + - `GET`: Load +- `/y-a-m-l-utils/load-string`: + - `GET`: Load String +- `/y-a-m-l-utils/dump`: + - `GET`: Dump +- `/y-a-m-l-utils/dump-string`: + - `GET`: Dump String +- `/y-a-m-l-utils/merge-yaml`: + - `GET`: Merge Yaml +- `/project-context/to-dict`: + - `GET`: To Dict +- `/text-utils/shorten-text`: + - `GET`: Shorten Text +- `/text-utils/clean-code`: + - `GET`: Clean Code +- `/enrichment-context/add-relationships`: + - `POST`: Add Relationships +- `/enrichment-context/add-contract`: + - `POST`: Add Contract +- `/enrichment-context/add-bundle-metadata`: + - `POST`: Add Bundle Metadata +- `/enrichment-context/to-dict`: + - `GET`: To Dict +- `/enrichment-context/to-markdown`: + - `GET`: To Markdown + +---### FEATURE-PROMPTVALIDATOR + +**Info**: + +- **Title**: Prompt Validator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Prompt Validator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/c-l-i-artifact-metadata/to-dict`: + - `GET`: To Dict +- `/c-l-i-artifact-metadata/from-dict`: + - `GET`: From Dict +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict + +---### FEATURE-SYNCAGENT + +**Info**: + +- **Title**: Sync Agent +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Sync Agent**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/analyze-agent/execute`: + - `GET`: Execute +- `/analyze-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/analyze-codebase`: + - `GET`: Analyze Codebase +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-SCHEMAVALIDATOR + +**Info**: + +- **Title**: Schema Validator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Schema Validator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/schema-validator/validate-json-schema`: + - `GET`: Validate Json Schema +- `/c-l-i-artifact-metadata/to-dict`: + - `GET`: To Dict +- `/c-l-i-artifact-metadata/from-dict`: + - `GET`: From Dict +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict + +---### FEATURE-CHECKRESULT + +**Info**: + +- **Title**: Check Result +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Check Result**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/check-result/to-dict`: + - `GET`: To Dict +- `/repro-report/add-check`: + - `POST`: Add Check +- `/repro-report/get-exit-code`: + - `GET`: Get Exit Code +- `/repro-report/to-dict`: + - `GET`: To Dict +- `/repro-checker/run-check/{name}`: + - `GET`: Run Check +- `/repro-checker/run-all-checks`: + - `GET`: Run All Checks + +---### FEATURE-CONTRACTFIRSTTESTMANAGER + +**Info**: + +- **Title**: Contract First Test Manager +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Contract First Test Manager**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/c-l-i-artifact-metadata/to-dict`: + - `GET`: To Dict +- `/c-l-i-artifact-metadata/from-dict`: + - `GET`: From Dict + +---### FEATURE-OPENAPIEXTRACTOR + +**Info**: + +- **Title**: Open A P I Extractor +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Open A P I Extractor**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/requirement-extractor/extract-complete-requirement`: + - `GET`: Extract Complete Requirement +- `/requirement-extractor/extract-method-requirement`: + - `GET`: Extract Method Requirement +- `/requirement-extractor/extract-nfrs`: + - `GET`: Extract Nfrs +- `/open-a-p-i-extractor/extract-openapi-from-verbose`: + - `GET`: Extract Openapi From Verbose +- `/open-a-p-i-extractor/extract-openapi-from-code`: + - `GET`: Extract Openapi From Code +- `/open-a-p-i-extractor/add-test-examples`: + - `POST`: Add Test Examples +- `/open-a-p-i-extractor/save-openapi-contract`: + - `GET`: Save Openapi Contract +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/constitution-evidence-extractor/extract-article-vii-evidence`: + - `GET`: Extract Article Vii Evidence +- `/constitution-evidence-extractor/extract-article-viii-evidence`: + - `GET`: Extract Article Viii Evidence +- `/constitution-evidence-extractor/extract-article-ix-evidence`: + - `GET`: Extract Article Ix Evidence +- `/constitution-evidence-extractor/extract-all-evidence`: + - `GET`: Extract All Evidence +- `/constitution-evidence-extractor/generate-constitution-check-section`: + - `GET`: Generate Constitution Check Section + +---### FEATURE-REPROCHECKER + +**Info**: + +- **Title**: Repro Checker +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Repro Checker**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/check-result/to-dict`: + - `GET`: To Dict +- `/repro-report/add-check`: + - `POST`: Add Check +- `/repro-report/get-exit-code`: + - `GET`: Get Exit Code +- `/repro-report/to-dict`: + - `GET`: To Dict +- `/repro-checker/run-check/{name}`: + - `GET`: Run Check +- `/repro-checker/run-all-checks`: + - `GET`: Run All Checks + +---### FEATURE-SPECKITCONVERTER + +**Info**: + +- **Title**: Spec Kit Converter +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec Kit Converter**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict + +---### FEATURE-TELEMETRYSETTINGS + +**Info**: + +- **Title**: Telemetry Settings +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Telemetry Settings**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/telemetry-settings/from-env`: + - `GET`: From Env +- `/telemetry-manager/enabled`: + - `GET`: Enabled +- `/telemetry-manager/last-event`: + - `GET`: Last Event +- `/telemetry-manager/track-command`: + - `GET`: Track Command + +---### FEATURE-IMPLEMENTATIONPLANTEMPLATE + +**Info**: + +- **Title**: Implementation Plan Template +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Implementation Plan Template**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +- `/plan-comparator/compare`: + - `GET`: Compare +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-MESSAGEFLOWFORMATTER + +**Info**: + +- **Title**: Message Flow Formatter +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Message Flow Formatter**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/control-flow-analyzer/extract-scenarios-from-method`: + - `GET`: Extract Scenarios From Method + +---### FEATURE-SOURCEARTIFACTSCANNER + +**Info**: + +- **Title**: Source Artifact Scanner +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Source Artifact Scanner**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/source-tracking/compute-hash`: + - `PUT`: Compute Hash +- `/source-tracking/has-changed`: + - `GET`: Has Changed +- `/source-tracking/update-hash`: + - `PUT`: Update Hash +- `/source-tracking/update-sync-timestamp`: + - `PUT`: Update Sync Timestamp +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/source-artifact-scanner/scan-repository`: + - `GET`: Scan Repository +- `/source-artifact-scanner/link-to-specs`: + - `GET`: Link To Specs +- `/source-artifact-scanner/extract-function-mappings`: + - `GET`: Extract Function Mappings +- `/source-artifact-scanner/extract-test-mappings`: + - `GET`: Extract Test Mappings +- `/ambiguity-scanner/scan`: + - `GET`: Scan +**Schemas**: + +- `SourceTracking`: object + +---### FEATURE-BRIDGEWATCHEVENTHANDLER + +**Info**: + +- **Title**: Bridge Watch Event Handler +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Watch Event Handler**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/file-hash-cache/load`: + - `GET`: Load +- `/file-hash-cache/save`: + - `GET`: Save +- `/file-hash-cache/get-hash`: + - `GET`: Get Hash +- `/file-hash-cache/set-hash`: + - `GET`: Set Hash +- `/file-hash-cache/get-dependencies`: + - `GET`: Get Dependencies +- `/file-hash-cache/set-dependencies`: + - `GET`: Set Dependencies +- `/file-hash-cache/has-changed`: + - `GET`: Has Changed +- `/enhanced-sync-event-handler/on-modified`: + - `GET`: On Modified +- `/enhanced-sync-event-handler/on-created`: + - `POST`: On Created +- `/enhanced-sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/enhanced-sync-watcher/start`: + - `GET`: Start +- `/enhanced-sync-watcher/stop`: + - `GET`: Stop +- `/enhanced-sync-watcher/watch`: + - `GET`: Watch +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/sync-event-handler/on-modified`: + - `GET`: On Modified +- `/sync-event-handler/on-created`: + - `POST`: On Created +- `/sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/sync-watcher/start`: + - `GET`: Start +- `/sync-watcher/stop`: + - `GET`: Stop +- `/sync-watcher/watch`: + - `GET`: Watch +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-TELEMETRYMANAGER + +**Info**: + +- **Title**: Telemetry Manager +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Telemetry Manager**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/telemetry-settings/from-env`: + - `GET`: From Env +- `/telemetry-manager/enabled`: + - `GET`: Enabled +- `/telemetry-manager/last-event`: + - `GET`: Last Event +- `/telemetry-manager/track-command`: + - `GET`: Track Command + +---### FEATURE-WORKFLOWGENERATOR + +**Info**: + +- **Title**: Workflow Generator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Workflow Generator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/protocol-generator/generate`: + - `GET`: Generate +- `/protocol-generator/generate-from-template`: + - `GET`: Generate From Template +- `/protocol-generator/render-string`: + - `GET`: Render String +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String + +---### FEATURE-REPROREPORT + +**Info**: + +- **Title**: Repro Report +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Repro Report**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/check-result/to-dict`: + - `GET`: To Dict +- `/repro-report/add-check`: + - `POST`: Add Check +- `/repro-report/get-exit-code`: + - `GET`: Get Exit Code +- `/repro-report/to-dict`: + - `GET`: To Dict +- `/repro-checker/run-check/{name}`: + - `GET`: Run Check +- `/repro-checker/run-all-checks`: + - `GET`: Run All Checks +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String + +---### FEATURE-BRIDGECONFIG + +**Info**: + +- **Title**: Bridge Config +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Bridge Config**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/artifact-mapping/resolve-path`: + - `GET`: Resolve Path +- `/template-mapping/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/load-from-file`: + - `GET`: Load From File +- `/bridge-config/save-to-file`: + - `GET`: Save To File +- `/bridge-config/resolve-path`: + - `GET`: Resolve Path +- `/bridge-config/get-command`: + - `GET`: Get Command +- `/bridge-config/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-config/preset-speckit-classic`: + - `GET`: Preset Speckit Classic +- `/bridge-config/preset-speckit-modern`: + - `GET`: Preset Speckit Modern +- `/bridge-config/preset-generic-markdown`: + - `GET`: Preset Generic Markdown +- `/bridge-probe/detect`: + - `GET`: Detect +- `/bridge-probe/auto-generate-bridge`: + - `GET`: Auto Generate Bridge +- `/bridge-probe/validate-bridge`: + - `GET`: Validate Bridge +- `/bridge-probe/save-bridge-config`: + - `GET`: Save Bridge Config +- `/bridge-watch/start`: + - `GET`: Start +- `/bridge-watch/stop`: + - `GET`: Stop +- `/bridge-watch/watch`: + - `GET`: Watch +**Schemas**: + +- `ArtifactMapping`: object +- `CommandMapping`: object +- `TemplateMapping`: object +- `BridgeConfig`: object + +---### FEATURE-STRUCTUREDFORMAT + +**Info**: + +- **Title**: Structured Format +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Structured Format**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/structured-format/from-string`: + - `GET`: From String +- `/structured-format/from-path`: + - `GET`: From Path + +---### FEATURE-FEATURESPECIFICATIONTEMPLATE + +**Info**: + +- **Title**: Feature Specification Template +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Feature Specification Template**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/bridge-template-loader/resolve-template-path`: + - `GET`: Resolve Template Path +- `/bridge-template-loader/load-template`: + - `GET`: Load Template +- `/bridge-template-loader/render-template`: + - `GET`: Render Template +- `/bridge-template-loader/list-available-templates`: + - `GET`: List Available Templates +- `/bridge-template-loader/template-exists`: + - `GET`: Template Exists +- `/bridge-template-loader/create-template-context`: + - `POST`: Create Template Context +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict + +---### FEATURE-AGENTREGISTRY + +**Info**: + +- **Title**: Agent Registry +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Agent Registry**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/agent-registry/register/{name}`: + - `GET`: Register +- `/agent-registry/{name}`: + - `GET`: Get +- `/agent-registry/get-agent-for-command`: + - `GET`: Get Agent For Command +- `/agent-registry/list-agents`: + - `GET`: List Agents +- `/analyze-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/analyze-agent/execute`: + - `GET`: Execute +- `/analyze-agent/inject-context`: + - `GET`: Inject Context +- `/analyze-agent/analyze-codebase`: + - `GET`: Analyze Codebase + +---### FEATURE-REPORTGENERATOR + +**Info**: + +- **Title**: Report Generator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Report Generator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String +- `/protocol-generator/generate`: + - `GET`: Generate +- `/protocol-generator/generate-from-template`: + - `GET`: Generate From Template +- `/protocol-generator/render-string`: + - `GET`: Render String + +---### FEATURE-DEVIATIONREPORT + +**Info**: + +- **Title**: Deviation Report +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Deviation Report**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/deviation-report/total-deviations`: + - `GET`: Total Deviations +- `/deviation-report/high-count`: + - `GET`: High Count +- `/deviation-report/medium-count`: + - `GET`: Medium Count +- `/deviation-report/low-count`: + - `GET`: Low Count +- `/validation-report/total-deviations`: + - `GET`: Total Deviations +- `/validation-report/add-deviation`: + - `POST`: Add Deviation +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String +**Schemas**: + +- `Deviation`: object +- `DeviationReport`: object +- `ValidationReport`: object + +---### FEATURE-REPOSITORYSYNC + +**Info**: + +- **Title**: Repository Sync +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Repository Sync**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-YAMLUTILS + +**Info**: + +- **Title**: Y A M L Utils +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Y A M L Utils**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/text-utils/shorten-text`: + - `GET`: Shorten Text +- `/text-utils/clean-code`: + - `GET`: Clean Code +- `/y-a-m-l-utils/load`: + - `GET`: Load +- `/y-a-m-l-utils/load-string`: + - `GET`: Load String +- `/y-a-m-l-utils/dump`: + - `GET`: Dump +- `/y-a-m-l-utils/dump-string`: + - `GET`: Dump String +- `/y-a-m-l-utils/merge-yaml`: + - `GET`: Merge Yaml + +---### FEATURE-ENHANCEDSYNCWATCHER + +**Info**: + +- **Title**: Enhanced Sync Watcher +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Enhanced Sync Watcher**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/file-hash-cache/load`: + - `GET`: Load +- `/file-hash-cache/save`: + - `GET`: Save +- `/file-hash-cache/get-hash`: + - `GET`: Get Hash +- `/file-hash-cache/set-hash`: + - `GET`: Set Hash +- `/file-hash-cache/get-dependencies`: + - `GET`: Get Dependencies +- `/file-hash-cache/set-dependencies`: + - `GET`: Set Dependencies +- `/file-hash-cache/has-changed`: + - `GET`: Has Changed +- `/enhanced-sync-event-handler/on-modified`: + - `GET`: On Modified +- `/enhanced-sync-event-handler/on-created`: + - `POST`: On Created +- `/enhanced-sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/enhanced-sync-watcher/start`: + - `GET`: Start +- `/enhanced-sync-watcher/stop`: + - `GET`: Stop +- `/enhanced-sync-watcher/watch`: + - `GET`: Watch +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/sync-event-handler/on-modified`: + - `GET`: On Modified +- `/sync-event-handler/on-created`: + - `POST`: On Created +- `/sync-event-handler/on-deleted`: + - `DELETE`: On Deleted +- `/sync-watcher/start`: + - `GET`: Start +- `/sync-watcher/stop`: + - `GET`: Stop +- `/sync-watcher/watch`: + - `GET`: Watch +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts + +---### FEATURE-PLANGENERATOR + +**Info**: + +- **Title**: Plan Generator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Plan Generator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/plan-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/plan-agent/execute`: + - `GET`: Execute +- `/plan-agent/inject-context`: + - `GET`: Inject Context +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/plan-migrator/load-and-migrate`: + - `GET`: Load And Migrate +- `/plan-migrator/check-migration-needed`: + - `GET`: Check Migration Needed +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/plan-bundle/compute-summary`: + - `PUT`: Compute Summary +- `/plan-bundle/update-summary`: + - `PUT`: Update Summary +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String +- `/plan-comparator/compare`: + - `GET`: Compare +- `/protocol-generator/generate`: + - `GET`: Generate +- `/protocol-generator/generate-from-template`: + - `GET`: Generate From Template +- `/protocol-generator/render-string`: + - `GET`: Render String +- `/plan-enricher/enrich-plan`: + - `GET`: Enrich Plan +**Schemas**: + +- `Story`: object +- `Feature`: object +- `Release`: object +- `Product`: object +- `Business`: object +- `Idea`: object +- `PlanSummary`: object +- `Metadata`: object +- `Clarification`: object +- `ClarificationSession`: object +- `Clarifications`: object +- `PlanBundle`: object + +---### FEATURE-PERFORMANCEMETRIC + +**Info**: + +- **Title**: Performance Metric +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Performance Metric**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/performance-metric/to-dict`: + - `GET`: To Dict +- `/performance-report/add-metric`: + - `POST`: Add Metric +- `/performance-report/get-summary`: + - `GET`: Get Summary +- `/performance-report/print-summary`: + - `GET`: Print Summary +- `/performance-monitor/start`: + - `GET`: Start +- `/performance-monitor/stop`: + - `GET`: Stop +- `/performance-monitor/track`: + - `GET`: Track +- `/performance-monitor/get-report`: + - `GET`: Get Report +- `/performance-monitor/disable`: + - `GET`: Disable +- `/performance-monitor/enable`: + - `GET`: Enable + +---### FEATURE-CONTRACTGENERATOR + +**Info**: + +- **Title**: Contract Generator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Contract Generator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-generator/generate-contracts`: + - `GET`: Generate Contracts +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/workflow-generator/generate-github-action`: + - `GET`: Generate Github Action +- `/workflow-generator/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/plan-generator/generate`: + - `GET`: Generate +- `/plan-generator/generate-from-template`: + - `GET`: Generate From Template +- `/plan-generator/render-string`: + - `GET`: Render String +- `/protocol-generator/generate`: + - `GET`: Generate +- `/protocol-generator/generate-from-template`: + - `GET`: Generate From Template +- `/protocol-generator/render-string`: + - `GET`: Render String +- `/contract-extractor/extract-function-contracts`: + - `GET`: Extract Function Contracts +- `/contract-extractor/generate-json-schema`: + - `GET`: Generate Json Schema +- `/contract-extractor/generate-icontract-decorator`: + - `GET`: Generate Icontract Decorator +- `/report-generator/generate-validation-report`: + - `GET`: Generate Validation Report +- `/report-generator/generate-deviation-report`: + - `GET`: Generate Deviation Report +- `/report-generator/render-markdown-string`: + - `GET`: Render Markdown String + +---### FEATURE-LOGGERSETUP + +**Info**: + +- **Title**: Logger Setup +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Logger Setup**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/message-flow-formatter/format`: + - `GET`: Format +- `/logger-setup/shutdown-listeners`: + - `GET`: Shutdown Listeners +- `/logger-setup/create-agent-flow-logger`: + - `POST`: Create Agent Flow Logger +- `/logger-setup/create-logger/{name}`: + - `POST`: Create Logger +- `/logger-setup/flush-all-loggers`: + - `GET`: Flush All Loggers +- `/logger-setup/flush-logger/{name}`: + - `GET`: Flush Logger +- `/logger-setup/write-test-summary`: + - `GET`: Write Test Summary +- `/logger-setup/get-logger/{name}`: + - `GET`: Get Logger +- `/logger-setup/trace`: + - `GET`: Trace +- `/logger-setup/redact-secrets`: + - `GET`: Redact Secrets + +---### FEATURE-SPECTOCODESYNC + +**Info**: + +- **Title**: Spec To Code Sync +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Spec To Code Sync**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/bridge-sync/resolve-artifact-path`: + - `GET`: Resolve Artifact Path +- `/bridge-sync/import-artifact`: + - `GET`: Import Artifact +- `/bridge-sync/export-artifact`: + - `GET`: Export Artifact +- `/bridge-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-converter/convert-protocol`: + - `GET`: Convert Protocol +- `/spec-kit-converter/convert-plan`: + - `GET`: Convert Plan +- `/spec-kit-converter/generate-semgrep-rules`: + - `GET`: Generate Semgrep Rules +- `/spec-kit-converter/generate-github-action`: + - `GET`: Generate Github Action +- `/spec-kit-converter/convert-to-speckit`: + - `GET`: Convert To Speckit +- `/spec-to-tests-sync/sync`: + - `GET`: Sync +- `/repository-sync/sync-repository-changes`: + - `GET`: Sync Repository Changes +- `/repository-sync/detect-code-changes`: + - `GET`: Detect Code Changes +- `/repository-sync/update-plan-artifacts`: + - `PUT`: Update Plan Artifacts +- `/repository-sync/track-deviations`: + - `GET`: Track Deviations +- `/sync-agent/generate-prompt`: + - `GET`: Generate Prompt +- `/sync-agent/execute`: + - `GET`: Execute +- `/sync-agent/inject-context`: + - `GET`: Inject Context +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/feature-specification-template/to-dict`: + - `GET`: To Dict +- `/implementation-plan-template/to-dict`: + - `GET`: To Dict +- `/contract-extraction-template/to-dict`: + - `GET`: To Dict +- `/spec-kit-scanner/is-speckit-repo`: + - `GET`: Is Speckit Repo +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/spec-kit-sync/sync-bidirectional`: + - `GET`: Sync Bidirectional +- `/spec-kit-sync/detect-speckit-changes`: + - `GET`: Detect Speckit Changes +- `/spec-kit-sync/detect-specfact-changes`: + - `GET`: Detect Specfact Changes +- `/spec-kit-sync/merge-changes`: + - `GET`: Merge Changes +- `/spec-kit-sync/detect-conflicts`: + - `GET`: Detect Conflicts +- `/spec-kit-sync/resolve-conflicts`: + - `GET`: Resolve Conflicts +- `/spec-kit-sync/apply-resolved-conflicts`: + - `GET`: Apply Resolved Conflicts +- `/spec-kit-scanner/has-constitution`: + - `GET`: Has Constitution +- `/spec-kit-scanner/scan-structure`: + - `GET`: Scan Structure +- `/spec-kit-scanner/discover-features`: + - `GET`: Discover Features +- `/spec-kit-scanner/parse-spec-markdown`: + - `GET`: Parse Spec Markdown +- `/spec-kit-scanner/parse-plan-markdown`: + - `GET`: Parse Plan Markdown +- `/spec-kit-scanner/parse-tasks-markdown`: + - `GET`: Parse Tasks Markdown +- `/spec-kit-scanner/parse-memory-files`: + - `GET`: Parse Memory Files +- `/spec-validation-result/to-dict`: + - `GET`: To Dict +- `/spec-validation-result/to-json`: + - `GET`: To Json +- `/mock-server/is-running`: + - `GET`: Is Running +- `/mock-server/stop`: + - `GET`: Stop + +---### FEATURE-CODEANALYZER + +**Info**: + +- **Title**: Code Analyzer +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Code Analyzer**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/code-to-spec-sync/sync`: + - `GET`: Sync +- `/spec-to-code-sync/prepare-llm-context`: + - `GET`: Prepare Llm Context +- `/spec-to-code-sync/generate-llm-prompt`: + - `GET`: Generate Llm Prompt +- `/graph-analyzer/extract-call-graph`: + - `GET`: Extract Call Graph +- `/graph-analyzer/build-dependency-graph`: + - `GET`: Build Dependency Graph +- `/graph-analyzer/get-graph-summary`: + - `GET`: Get Graph Summary +- `/code-analyzer/analyze`: + - `GET`: Analyze +- `/code-analyzer/get-plugin-status`: + - `GET`: Get Plugin Status +- `/control-flow-analyzer/extract-scenarios-from-method`: + - `GET`: Extract Scenarios From Method + +---### FEATURE-PROGRESSIVEDISCLOSUREGROUP + +**Info**: + +- **Title**: Progressive Disclosure Group +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Progressive Disclosure Group**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/progressive-disclosure-group/get-params`: + - `GET`: Get Params +- `/progressive-disclosure-command/format-help`: + - `GET`: Format Help +- `/progressive-disclosure-command/get-params`: + - `GET`: Get Params + +---### FEATURE-DRIFTDETECTOR + +**Info**: + +- **Title**: Drift Detector +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Drift Detector**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/drift-detector/scan`: + - `GET`: Scan +- `/change-detector/detect-changes`: + - `GET`: Detect Changes + +---### FEATURE-FSMVALIDATOR + +**Info**: + +- **Title**: F S M Validator +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for F S M Validator**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/contract-density-metrics/to-dict`: + - `GET`: To Dict +- `/c-l-i-artifact-metadata/to-dict`: + - `GET`: To Dict +- `/c-l-i-artifact-metadata/from-dict`: + - `GET`: From Dict + +---### FEATURE-RELATIONSHIPMAPPER + +**Info**: + +- **Title**: Relationship Mapper +- **Version**: 1.0.0 +- **Description**: API contract extracted from code for Relationship Mapper**OpenAPI Version**: 3.0.3**Endpoints**: + +- `/relationship-mapper/analyze-file`: + - `GET`: Analyze File +- `/relationship-mapper/analyze-files`: + - `GET`: Analyze Files +- `/relationship-mapper/get-relationship-graph`: + - `GET`: Get Relationship Graph + +--- +## Ownership & Locks + +No sections currently locked + +## Validation Checklist + +- [ ] All features have technical constraints defined +- [ ] Protocols/state machines are documented +- [ ] Contracts are defined and validated +- [ ] Architecture decisions are documented +- [ ] Non-functional requirements are specified +- [ ] Risk assessment is complete +- [ ] Deployment architecture is documented + +## Notes + +*Use this section for architectural decisions, trade-offs, or technical clarifications.* diff --git a/_site_test/project-plans/speckit-test/developer.md b/_site_test/project-plans/speckit-test/developer.md new file mode 100644 index 0000000..c9d51a4 --- /dev/null +++ b/_site_test/project-plans/speckit-test/developer.md @@ -0,0 +1,203 @@ +# Project Plan: speckit-test - Developer View + +**Persona**: Developer +**Bundle**: `speckit-test` +**Created**: 2025-12-11T23:36:34.742100+00:00 +**Status**: active +**Last Updated**: 2025-12-11T23:36:34.742122+00:00 + +## Acceptance Criteria & Implementation Details *(mandatory)*### FEATURE-TEXTUTILS: Text Utils + +#### Acceptance Criteria - FEATURE-TEXTUTILS- [ ] The system text utils must provide text utils functionality### FEATURE-MOCKSERVER: Mock Server + +#### Acceptance Criteria - FEATURE-MOCKSERVER- [ ] The system mock server must provide mock server functionality### FEATURE-SDDMANIFEST: S D D Manifest + +#### Acceptance Criteria - FEATURE-SDDMANIFEST- [ ] The system sddmanifest must provide sddmanifest functionality### FEATURE-FEATURESPECIFICATIONTEMPLATE: Feature Specification Template + +#### Acceptance Criteria - FEATURE-FEATURESPECIFICATIONTEMPLATE- [ ] The system feature specification template must provide feature specification template functionality### FEATURE-VALIDATIONREPORT: Validation Report + +#### Acceptance Criteria - FEATURE-VALIDATIONREPORT- [ ] The system validation report must provide validation report functionality### FEATURE-CLIARTIFACTMETADATA: C L I Artifact Metadata + +#### Acceptance Criteria - FEATURE-CLIARTIFACTMETADATA- [ ] The system cliartifact metadata must provide cliartifact metadata functionality### FEATURE-TEMPLATEMAPPING: Template Mapping + +#### Acceptance Criteria - FEATURE-TEMPLATEMAPPING- [ ] The system template mapping must provide template mapping functionality### FEATURE-PERFORMANCEMETRIC: Performance Metric + +#### Acceptance Criteria - FEATURE-PERFORMANCEMETRIC- [ ] The system performance metric must provide performance metric functionality### FEATURE-DEVIATIONREPORT: Deviation Report + +#### Acceptance Criteria - FEATURE-DEVIATIONREPORT- [ ] The system deviation report must provide deviation report functionality### FEATURE-ARTIFACTMAPPING: Artifact Mapping + +#### Acceptance Criteria - FEATURE-ARTIFACTMAPPING- [ ] The system artifact mapping must provide artifact mapping functionality### FEATURE-TELEMETRYSETTINGS: Telemetry Settings + +#### Acceptance Criteria - FEATURE-TELEMETRYSETTINGS- [ ] The system telemetry settings must provide telemetry settings functionality### FEATURE-TASKLIST: Task List + +#### Acceptance Criteria - FEATURE-TASKLIST- [ ] The system task list must provide task list functionality### FEATURE-CHECKRESULT: Check Result + +#### Acceptance Criteria - FEATURE-CHECKRESULT- [ ] The system check result must validate CheckResult### FEATURE-ENRICHMENTPARSER: Enrichment Parser + +#### Acceptance Criteria - FEATURE-ENRICHMENTPARSER- [ ] The system enrichment parser must provide enrichment parser functionality### FEATURE-SOURCETRACKING: Source Tracking + +#### Acceptance Criteria - FEATURE-SOURCETRACKING- [ ] The system source tracking must provide source tracking functionality### FEATURE-YAMLUTILS: Y A M L Utils + +#### Acceptance Criteria - FEATURE-YAMLUTILS- [ ] The system yamlutils must provide yamlutils functionality### FEATURE-STRUCTUREDFORMAT: Structured Format + +#### Acceptance Criteria - FEATURE-STRUCTUREDFORMAT- [ ] The system structured format must provide structured format functionality### FEATURE-PROGRESSIVEDISCLOSUREGROUP: Progressive Disclosure Group + +#### Acceptance Criteria - FEATURE-PROGRESSIVEDISCLOSUREGROUP- [ ] The system progressive disclosure group must provide progressive disclosure group functionality### FEATURE-CONTRACTEXTRACTIONTEMPLATE: Contract Extraction Template + +#### Acceptance Criteria - FEATURE-CONTRACTEXTRACTIONTEMPLATE- [ ] The system contract extraction template must provide contract extraction template functionality### FEATURE-TELEMETRYMANAGER: Telemetry Manager + +#### Acceptance Criteria - FEATURE-TELEMETRYMANAGER- [ ] The system telemetry manager must telemetrymanager TelemetryManager### FEATURE-ENFORCEMENTCONFIG: Enforcement Config + +#### Acceptance Criteria - FEATURE-ENFORCEMENTCONFIG- [ ] The system enforcement config must provide enforcement config functionality### FEATURE-REPROCHECKER: Repro Checker + +#### Acceptance Criteria - FEATURE-REPROCHECKER- [ ] The system repro checker must validate ReproChecker### FEATURE-FILEHASHCACHE: File Hash Cache + +#### Acceptance Criteria - FEATURE-FILEHASHCACHE- [ ] The system file hash cache must provide file hash cache functionality### FEATURE-DRIFTDETECTOR: Drift Detector + +#### Acceptance Criteria - FEATURE-DRIFTDETECTOR- [ ] The system drift detector must provide drift detector functionality### FEATURE-AMBIGUITYSCANNER: Ambiguity Scanner + +#### Acceptance Criteria - FEATURE-AMBIGUITYSCANNER- [ ] Scanner for identifying ambiguities in plan bundles### FEATURE-RELATIONSHIPMAPPER: Relationship Mapper + +#### Acceptance Criteria - FEATURE-RELATIONSHIPMAPPER- [ ] The system relationship mapper must provide relationship mapper functionality### FEATURE-PROJECTCONTEXT: Project Context + +#### Acceptance Criteria - FEATURE-PROJECTCONTEXT- [ ] The system project context must provide project context functionality### FEATURE-SCHEMAVALIDATOR: Schema Validator + +#### Acceptance Criteria - FEATURE-SCHEMAVALIDATOR- [ ] The system schema validator must provide schema validator functionality### FEATURE-CHANGEDETECTOR: Change Detector + +#### Acceptance Criteria - FEATURE-CHANGEDETECTOR- [ ] The system change detector must provide change detector functionality### FEATURE-PERFORMANCEMONITOR: Performance Monitor + +#### Acceptance Criteria - FEATURE-PERFORMANCEMONITOR- [ ] The system performance monitor must provide performance monitor functionality### FEATURE-AGENTMODE: Agent Mode + +#### Acceptance Criteria - FEATURE-AGENTMODE- [ ] The system agent mode must provide agent mode functionality### FEATURE-BRIDGEWATCHEVENTHANDLER: Bridge Watch Event Handler + +#### Acceptance Criteria - FEATURE-BRIDGEWATCHEVENTHANDLER- [ ] The system bridge watch event handler must bridgewatcheventhandler BridgeWatchEventHandler### FEATURE-GITOPERATIONS: Git Operations + +#### Acceptance Criteria - FEATURE-GITOPERATIONS- [ ] The system git operations must provide git operations functionality### FEATURE-SPECVALIDATIONRESULT: Spec Validation Result + +#### Acceptance Criteria - FEATURE-SPECVALIDATIONRESULT- [ ] The system spec validation result must provide spec validation result functionality### FEATURE-LOGGERSETUP: Logger Setup + +#### Acceptance Criteria - FEATURE-LOGGERSETUP- [ ] The system logger setup must provide logger setup functionality### FEATURE-PROMPTVALIDATOR: Prompt Validator + +#### Acceptance Criteria - FEATURE-PROMPTVALIDATOR- [ ] The system prompt validator must validates prompt templates### FEATURE-PERFORMANCEREPORT: Performance Report + +#### Acceptance Criteria - FEATURE-PERFORMANCEREPORT- [ ] The system performance report must provide performance report functionality### FEATURE-CONTRACTDENSITYMETRICS: Contract Density Metrics + +#### Acceptance Criteria - FEATURE-CONTRACTDENSITYMETRICS- [ ] The system contract density metrics must provide contract density metrics functionality### FEATURE-PLANENRICHER: Plan Enricher + +#### Acceptance Criteria - FEATURE-PLANENRICHER- [ ] The system plan enricher must provide plan enricher functionality### FEATURE-FSMVALIDATOR: F S M Validator + +#### Acceptance Criteria - FEATURE-FSMVALIDATOR- [ ] The system fsmvalidator must provide fsmvalidator functionality### FEATURE-IMPLEMENTATIONPLANTEMPLATE: Implementation Plan Template + +#### Acceptance Criteria - FEATURE-IMPLEMENTATIONPLANTEMPLATE- [ ] The system implementation plan template must provide implementation plan template functionality### FEATURE-REQUIREMENTEXTRACTOR: Requirement Extractor + +#### Acceptance Criteria - FEATURE-REQUIREMENTEXTRACTOR- [ ] The system requirement extractor must extracts complete requirements from code semantics### FEATURE-ENRICHMENTREPORT: Enrichment Report + +#### Acceptance Criteria - FEATURE-ENRICHMENTREPORT- [ ] The system enrichment report must provide enrichment report functionality### FEATURE-AGENTREGISTRY: Agent Registry + +#### Acceptance Criteria - FEATURE-AGENTREGISTRY- [ ] The system agent registry must provide agent registry functionality### FEATURE-REPROREPORT: Repro Report + +#### Acceptance Criteria - FEATURE-REPROREPORT- [ ] The system repro report must provide repro report functionality### FEATURE-PLANCOMPARATOR: Plan Comparator + +#### Acceptance Criteria - FEATURE-PLANCOMPARATOR- [ ] The system plan comparator must provide plan comparator functionality### FEATURE-PROTOCOLGENERATOR: Protocol Generator + +#### Acceptance Criteria - FEATURE-PROTOCOLGENERATOR- [ ] The system protocol generator must provide protocol generator functionality### FEATURE-ENRICHMENTCONTEXT: Enrichment Context + +#### Acceptance Criteria - FEATURE-ENRICHMENTCONTEXT- [ ] The system enrichment context must provide enrichment context functionality### FEATURE-SOURCEARTIFACTSCANNER: Source Artifact Scanner + +#### Acceptance Criteria - FEATURE-SOURCEARTIFACTSCANNER- [ ] Scanner for discovering and linking source artifacts to specifications### FEATURE-CONTRACTGENERATOR: Contract Generator + +#### Acceptance Criteria - FEATURE-CONTRACTGENERATOR- [ ] The system contract generator must generates contract stubs from sdd how sections### FEATURE-BRIDGECONFIG: Bridge Config + +#### Acceptance Criteria - FEATURE-BRIDGECONFIG- [ ] The system bridge config must provide bridge config functionality### FEATURE-SYNCAGENT: Sync Agent + +#### Acceptance Criteria - FEATURE-SYNCAGENT- [ ] The system sync agent must provide sync agent functionality### FEATURE-BRIDGEWATCH: Bridge Watch + +#### Acceptance Criteria - FEATURE-BRIDGEWATCH- [ ] The system bridge watch must provide bridge watch functionality### FEATURE-CONSTITUTIONENRICHER: Constitution Enricher + +#### Acceptance Criteria - FEATURE-CONSTITUTIONENRICHER- [ ] The system constitution enricher must provide constitution enricher functionality### FEATURE-ENHANCEDSYNCWATCHER: Enhanced Sync Watcher + +#### Acceptance Criteria - FEATURE-ENHANCEDSYNCWATCHER- [ ] The system enhanced sync watcher must provide enhanced sync watcher functionality### FEATURE-REPORTGENERATOR: Report Generator + +#### Acceptance Criteria - FEATURE-REPORTGENERATOR- [ ] The system report generator must provide report generator functionality### FEATURE-SYNCWATCHER: Sync Watcher + +#### Acceptance Criteria - FEATURE-SYNCWATCHER- [ ] The system sync watcher must provide sync watcher functionality### FEATURE-PROGRESSIVEDISCLOSURECOMMAND: Progressive Disclosure Command + +#### Acceptance Criteria - FEATURE-PROGRESSIVEDISCLOSURECOMMAND- [ ] The system progressive disclosure command must provide progressive disclosure command functionality### FEATURE-WORKFLOWGENERATOR: Workflow Generator + +#### Acceptance Criteria - FEATURE-WORKFLOWGENERATOR- [ ] The system workflow generator must provide workflow generator functionality### FEATURE-REPOSITORYSYNC: Repository Sync + +#### Acceptance Criteria - FEATURE-REPOSITORYSYNC- [ ] The system repository sync must provide repository sync functionality### FEATURE-PLANMIGRATOR: Plan Migrator + +#### Acceptance Criteria - FEATURE-PLANMIGRATOR- [ ] The system plan migrator must provide plan migrator functionality### FEATURE-CONTRACTEXTRACTOR: Contract Extractor + +#### Acceptance Criteria - FEATURE-CONTRACTEXTRACTOR- [ ] The system contract extractor must extracts api contracts from function signatures, type hints, and validation logic### FEATURE-BRIDGESYNC: Bridge Sync + +#### Acceptance Criteria - FEATURE-BRIDGESYNC- [ ] The system bridge sync must provide bridge sync functionality### FEATURE-CONTROLFLOWANALYZER: Control Flow Analyzer + +#### Acceptance Criteria - FEATURE-CONTROLFLOWANALYZER- [ ] The system control flow analyzer must analyzes ast to extract control flow patterns and generate scenarios### FEATURE-SYNCEVENTHANDLER: Sync Event Handler + +#### Acceptance Criteria - FEATURE-SYNCEVENTHANDLER- [ ] The system sync event handler must synceventhandler SyncEventHandler### FEATURE-COMMANDROUTER: Command Router + +#### Acceptance Criteria - FEATURE-COMMANDROUTER- [ ] The system command router must provide command router functionality### FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR: Constitution Evidence Extractor + +#### Acceptance Criteria - FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR- [ ] The system constitution evidence extractor must extracts evidence-based constitution checklist from code patterns### FEATURE-SPECKITCONVERTER: Spec Kit Converter + +#### Acceptance Criteria - FEATURE-SPECKITCONVERTER- [ ] The system spec kit converter must provide spec kit converter functionality### FEATURE-SPECKITSCANNER: Spec Kit Scanner + +#### Acceptance Criteria - FEATURE-SPECKITSCANNER- [ ] Scanner for Spec-Kit repositories### FEATURE-MESSAGEFLOWFORMATTER: Message Flow Formatter + +#### Acceptance Criteria - FEATURE-MESSAGEFLOWFORMATTER- [ ] The system message flow formatter must provide message flow formatter functionality### FEATURE-SMARTCOVERAGEMANAGER: Smart Coverage Manager + +#### Acceptance Criteria - FEATURE-SMARTCOVERAGEMANAGER- [ ] The system smart coverage manager must smartcoveragemanager SmartCoverageManager### FEATURE-CODEANALYZER: Code Analyzer + +#### Acceptance Criteria - FEATURE-CODEANALYZER- [ ] The system code analyzer must analyzes python code to auto-derive plan bundles### FEATURE-PROJECTBUNDLE: Project Bundle + +#### Acceptance Criteria - FEATURE-PROJECTBUNDLE- [ ] The system project bundle must provide project bundle functionality### FEATURE-BRIDGEPROBE: Bridge Probe + +#### Acceptance Criteria - FEATURE-BRIDGEPROBE- [ ] The system bridge probe must provide bridge probe functionality### FEATURE-GRAPHANALYZER: Graph Analyzer + +#### Acceptance Criteria - FEATURE-GRAPHANALYZER- [ ] The system graph analyzer must provide graph analyzer functionality### FEATURE-PLANAGENT: Plan Agent + +#### Acceptance Criteria - FEATURE-PLANAGENT- [ ] The system plan agent must provide plan agent functionality### FEATURE-OPENAPIEXTRACTOR: Open A P I Extractor + +#### Acceptance Criteria - FEATURE-OPENAPIEXTRACTOR- [ ] The system open apiextractor must provide open apiextractor functionality### FEATURE-PLANBUNDLE: Plan Bundle + +#### Acceptance Criteria - FEATURE-PLANBUNDLE- [ ] The system plan bundle must provide plan bundle functionality### FEATURE-ENHANCEDSYNCEVENTHANDLER: Enhanced Sync Event Handler + +#### Acceptance Criteria - FEATURE-ENHANCEDSYNCEVENTHANDLER- [ ] The system enhanced sync event handler must enhancedsynceventhandler EnhancedSyncEventHandler### FEATURE-ANALYZEAGENT: Analyze Agent + +#### Acceptance Criteria - FEATURE-ANALYZEAGENT- [ ] The system analyze agent must provide analyze agent functionality### FEATURE-BRIDGETEMPLATELOADER: Bridge Template Loader + +#### Acceptance Criteria - FEATURE-BRIDGETEMPLATELOADER- [ ] The system bridge template loader must provide bridge template loader functionality### FEATURE-SPECTOCODESYNC: Spec To Code Sync + +#### Acceptance Criteria - FEATURE-SPECTOCODESYNC- [ ] The system spec to code sync must provide spec to code sync functionality### FEATURE-CODETOSPECSYNC: Code To Spec Sync + +#### Acceptance Criteria - FEATURE-CODETOSPECSYNC- [ ] The system code to spec sync must provide code to spec sync functionality### FEATURE-PLANGENERATOR: Plan Generator + +#### Acceptance Criteria - FEATURE-PLANGENERATOR- [ ] The system plan generator must provide plan generator functionality### FEATURE-SPECKITSYNC: Spec Kit Sync + +#### Acceptance Criteria - FEATURE-SPECKITSYNC- [ ] The system spec kit sync must provide spec kit sync functionality### FEATURE-SPECFACTSTRUCTURE: Spec Fact Structure + +#### Acceptance Criteria - FEATURE-SPECFACTSTRUCTURE- [ ] Manages the canonical### FEATURE-OPENAPITESTCONVERTER: Open A P I Test Converter + +#### Acceptance Criteria - FEATURE-OPENAPITESTCONVERTER- [ ] The system open apitest converter must provide open apitest converter functionality### FEATURE-CONTRACTFIRSTTESTMANAGER: Contract First Test Manager + +#### Acceptance Criteria - FEATURE-CONTRACTFIRSTTESTMANAGER- [ ] The system contract first test manager must contractfirsttestmanager ContractFirstTestManager## Ownership & Locks + +No sections currently locked + +## Validation Checklist + +- [ ] All features have acceptance criteria defined +- [ ] Acceptance criteria are testable +- [ ] Implementation tasks are documented +- [ ] API contracts are defined +- [ ] Test scenarios are documented +- [ ] Code mappings are complete +- [ ] Edge cases are considered +- [ ] Testing strategy is defined +- [ ] Definition of Done criteria are met + +## Notes + +*Use this section for implementation questions, technical notes, or development clarifications.* diff --git a/_site_test/project-plans/speckit-test/product-owner.md b/_site_test/project-plans/speckit-test/product-owner.md new file mode 100644 index 0000000..63d8373 --- /dev/null +++ b/_site_test/project-plans/speckit-test/product-owner.md @@ -0,0 +1,11214 @@ +# Project Plan: speckit-test - Product Owner View + +**Persona**: Product Owner +**Bundle**: `speckit-test` +**Created**: 2025-12-11T22:36:03.710567+00:00 +**Status**: active +**Last Updated**: 2025-12-11T22:36:03.710581+00:00 + +## Idea & Business Context *(mandatory)* + +### Problem Statement + +*[ACTION REQUIRED: Define the problem this project solves]* + +### Solution Vision + +*[ACTION REQUIRED: Describe the envisioned solution]* + +### Success Metrics + +- *[ACTION REQUIRED: Define measurable success metrics]* + +## Features & User Stories *(mandatory)* + +### FEATURE-PROGRESSIVEDISCLOSUREGROUP: Progressive Disclosure Group + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can view Progressive Disclosure Group data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Override get_params to include hidden options when advanced help is requested. +- [ ] Error handling: Invalid format produces clear validation errors +- [ ] Empty states: Missing format fields use sensible defaults +- [ ] Validation: Required fields validated before format conversion + +--- + +#### Feature Outcomes + +- Custom Typer group that shows hidden options when advanced help is requested. +- Provides CRUD operations: READ params +### FEATURE-MOCKSERVER: Mock Server + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Mock Server features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Check if mock server is running. +- [ ] Stop the mock server. + +--- + +#### Feature Outcomes + +- Mock server instance. +### FEATURE-SDDMANIFEST: S D D Manifest + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 4 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can validate S D D Manifest data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate SDD manifest structure (custom validation beyond Pydantic). + +--- +**Story 2**: As a user, I can update S D D Manifest records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Update the updated_at timestamp. + +--- + +#### Feature Outcomes + +- SDD manifest with WHY/WHAT/HOW, hashes, and coverage thresholds. +- Defines data models: $MODEL +- Provides CRUD operations: UPDATE timestamp +### FEATURE-ARTIFACTMAPPING: Artifact Mapping + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Artifact Mapping features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Resolve dynamic path pattern with context variables. + +--- + +#### Feature Outcomes + +- Maps SpecFact logical concepts to physical tool paths. +- Defines data models: $MODEL +### FEATURE-TEXTUTILS: Text Utils + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Text Utils features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Shorten text to a maximum length, appending '...' if truncated. +- [ ] Extract code from markdown triple-backtick fences. If multiple fenced + +--- + +#### Feature Outcomes + +- A utility class for text manipulation. +### FEATURE-PERFORMANCEMETRIC: Performance Metric + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Performance Metric features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. +- [ ] Error handling: Invalid input produces clear validation errors +- [ ] Empty states: Missing data uses sensible defaults +- [ ] Validation: Required fields validated before processing + +--- + +#### Feature Outcomes + +- Performance metric for a single operation. +### FEATURE-VALIDATIONREPORT: Validation Report + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 4 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Validation Report features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Total number of deviations. + +--- +**Story 2**: As a user, I can create new Validation Report records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add a deviation and update counts. + +--- + +#### Feature Outcomes + +- Validation report model (for backward compatibility). +- Defines data models: $MODEL +- Provides CRUD operations: CREATE deviation +### FEATURE-DEVIATIONREPORT: Deviation Report + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Deviation Report features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Total number of deviations. +- [ ] Number of high severity deviations. +- [ ] Number of medium severity deviations. +- [ ] Number of low severity deviations. + +--- + +#### Feature Outcomes + +- Deviation report model. +- Defines data models: $MODEL +### FEATURE-FEATURESPECIFICATIONTEMPLATE: Feature Specification Template + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Feature Specification Template features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. + +--- + +#### Feature Outcomes + +- Template for feature specifications (brownfield enhancement). +### FEATURE-YAMLUTILS: Y A M L Utils + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Y A M L Utils + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize YAML utilities. + +--- +**Story 2**: As a user, I can use Y A M L Utils features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Load YAML from file. +- [ ] Load YAML from string. +- [ ] Dump data to YAML file. +- [ ] Dump data to YAML string. +- [ ] Deep merge two YAML dictionaries. + +--- + +#### Feature Outcomes + +- Helper class for YAML operations. +### FEATURE-TASKLIST: Task List + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can view Task List data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get task IDs for a specific phase. +- [ ] Get task by ID. +- [ ] Get all dependencies for a task (recursive). + +--- + +#### Feature Outcomes + +- Complete task breakdown for a project bundle. +- Defines data models: $MODEL +- Provides CRUD operations: READ tasks_by_phase, READ task, READ dependencies +### FEATURE-SOURCETRACKING: Source Tracking + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can process data using Source Tracking + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Compute SHA256 hash for change detection. + +--- +**Story 2**: As a user, I can update Source Tracking records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Check if file changed since last sync. +- [ ] Update stored hash for a file. +- [ ] Update last_synced timestamp to current time. + +--- + +#### Feature Outcomes + +- Links specs to actual code/tests with hash-based change detection. +- Defines data models: $MODEL +- Provides CRUD operations: UPDATE hash, UPDATE sync_timestamp +### FEATURE-TELEMETRYSETTINGS: Telemetry Settings + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 8 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Telemetry Settings features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Build telemetry settings from environment variables, config file, and opt-in file. + +--- + +#### Feature Outcomes + +- User-configurable telemetry settings. +### FEATURE-TEMPLATEMAPPING: Template Mapping + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Template Mapping features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Resolve template path for a schema key. +- [ ] Error handling: Invalid data produces clear validation errors +- [ ] Empty states: Missing fields use sensible defaults +- [ ] Validation: Required fields validated before processing + +--- + +#### Feature Outcomes + +- Maps SpecFact schemas to tool prompt templates. +- Defines data models: $MODEL +### FEATURE-CLIARTIFACTMETADATA: C L I Artifact Metadata + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use C L I Artifact Metadata features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. +- [ ] Create from dictionary. +- [ ] Error handling: Invalid input produces clear error messages +- [ ] Empty states: Missing data uses sensible defaults +- [ ] Validation: Required fields validated before processing + +--- + +#### Feature Outcomes + +- Metadata for CLI-generated artifacts. +### FEATURE-ENRICHMENTPARSER: Enrichment Parser + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can analyze data with Enrichment Parser + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Parse Markdown enrichment report. + +--- + +#### Feature Outcomes + +- Parser for Markdown enrichment reports. +### FEATURE-CHECKRESULT: Check Result + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Check Result features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert result to dictionary with structured findings. + +--- + +#### Feature Outcomes + +- Result of a single validation check. +### FEATURE-STRUCTUREDFORMAT: Structured Format + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Structured Format features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert string to StructuredFormat (defaults to YAML). +- [ ] Infer format from file path suffix. +- [ ] Error handling: Invalid data produces clear error messages +- [ ] Empty states: Missing fields use sensible defaults +- [ ] Validation: Required fields validated before processing + +--- + +#### Feature Outcomes + +- Supported structured data formats. +### FEATURE-FILEHASHCACHE: File Hash Cache + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use File Hash Cache features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Load hash cache from disk. +- [ ] Save hash cache to disk. + +--- +**Story 2**: As a user, I can view File Hash Cache data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get cached hash for a file. +- [ ] Get dependencies for a file. + +--- +**Story 3**: As a user, I can update File Hash Cache records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Set hash for a file. +- [ ] Set dependencies for a file. +- [ ] Check if file has changed based on hash. + +--- + +#### Feature Outcomes + +- Cache for file hashes to detect actual changes. +- Provides CRUD operations: READ hash, READ dependencies +### FEATURE-CONTRACTEXTRACTIONTEMPLATE: Contract Extraction Template + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Contract Extraction Template features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. + +--- + +#### Feature Outcomes + +- Template for contract extraction (from legacy code). +### FEATURE-PROJECTCONTEXT: Project Context + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Project Context features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert context to dictionary. + +--- + +#### Feature Outcomes + +- Detected project context information. +### FEATURE-SCHEMAVALIDATOR: Schema Validator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Schema Validator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize schema validator. + +--- +**Story 2**: As a developer, I can validate Schema Validator data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate data against JSON schema. + +--- + +#### Feature Outcomes + +- Schema validator for plan bundles and protocols. +### FEATURE-AMBIGUITYSCANNER: Ambiguity Scanner + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Ambiguity Scanner + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize ambiguity scanner. + +--- +**Story 2**: As a user, I can use Ambiguity Scanner features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Scan plan bundle for ambiguities. + +--- + +#### Feature Outcomes + +- Scanner for identifying ambiguities in plan bundles. +### FEATURE-REPROCHECKER: Repro Checker + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 13 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Repro Checker + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize reproducibility checker. + +--- +**Story 2**: As a developer, I can validate Repro Checker data + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Run a single validation check. +- [ ] Run all validation checks. + +--- + +#### Feature Outcomes + +- Runs validation checks with time budgets and result aggregation. +### FEATURE-ENFORCEMENTCONFIG: Enforcement Config + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can update Enforcement Config records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Create an enforcement config from a preset. + +--- +**Story 2**: As a user, I can use Enforcement Config features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Determine if a deviation should block execution. +- [ ] Convert config to a summary dictionary for display. + +--- +**Story 3**: As a user, I can view Enforcement Config data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get the action for a given severity level. + +--- + +#### Feature Outcomes + +- Configuration for contract enforcement and quality gates. +- Defines data models: $MODEL +- Provides CRUD operations: READ action +### FEATURE-DRIFTDETECTOR: Drift Detector + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Drift Detector + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize drift detector. + +--- +**Story 2**: As a user, I can use Drift Detector features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Comprehensive drift analysis. + +--- + +#### Feature Outcomes + +- Detector for drift between code and specifications. +### FEATURE-TELEMETRYMANAGER: Telemetry Manager + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Telemetry Manager + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) + +--- +**Story 2**: As a user, I can use Telemetry Manager features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Return True if telemetry is active. +- [ ] Expose the last emitted telemetry event (used for tests). +- [ ] Context manager to record anonymized telemetry for a CLI command. + +--- + +#### Feature Outcomes + +- Privacy-first telemetry helper. +### FEATURE-AGENTMODE: Agent Mode + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can generate outputs from Agent Mode + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate enhanced prompt for CoPilot. + +--- +**Story 2**: As a user, I can use Agent Mode features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Execute command with agent mode routing. +- [ ] Inject context information for CoPilot. + +--- + +#### Feature Outcomes + +- Base class for agent modes. +### FEATURE-CHANGEDETECTOR: Change Detector + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Change Detector + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize change detector. + +--- +**Story 2**: As a user, I can update Change Detector records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Detect changes using hash-based comparison. + +--- + +#### Feature Outcomes + +- Detector for changes in code, specs, and tests. +### FEATURE-PERFORMANCEMONITOR: Performance Monitor + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Performance Monitor + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize performance monitor. + +--- +**Story 2**: As a user, I can use Performance Monitor features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Start performance monitoring. +- [ ] Stop performance monitoring. +- [ ] Track an operation's performance. +- [ ] Disable performance monitoring. +- [ ] Enable performance monitoring. + +--- +**Story 3**: As a user, I can view Performance Monitor data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get performance report. + +--- + +#### Feature Outcomes + +- Performance monitor for tracking command execution. +- Provides CRUD operations: READ report +### FEATURE-PROMPTVALIDATOR: Prompt Validator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Prompt Validator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize validator with prompt path. + +--- +**Story 2**: As a developer, I can validate Prompt Validator data + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate prompt structure (required sections). +- [ ] Validate CLI command alignment. +- [ ] Validate wait state rules (optional - only warnings). +- [ ] Validate dual-stack enrichment workflow (if applicable). +- [ ] Validate consistency with other prompts. +- [ ] Run all validations. + +--- + +#### Feature Outcomes + +- Validates prompt templates. +### FEATURE-RELATIONSHIPMAPPER: Relationship Mapper + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Relationship Mapper + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize relationship mapper. + +--- +**Story 2**: As a user, I can analyze data with Relationship Mapper + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Analyze a single file for relationships. +- [ ] Analyze multiple files for relationships (parallelized). + +--- +**Story 3**: As a user, I can view Relationship Mapper data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get relationship graph representation. + +--- + +#### Feature Outcomes + +- Maps relationships, dependencies, and interfaces in a codebase. +- Provides CRUD operations: READ relationship_graph +### FEATURE-FSMVALIDATOR: F S M Validator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure F S M Validator + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize FSM validator. + +--- +**Story 2**: As a developer, I can validate F S M Validator data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate the FSM protocol. +- [ ] Check if transition is valid. + +--- +**Story 3**: As a user, I can view F S M Validator data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get all states reachable from given state. +- [ ] Get all transitions from given state. + +--- + +#### Feature Outcomes + +- FSM validator for protocol validation. +- Provides CRUD operations: READ reachable_states, READ transitions_from +### FEATURE-GITOPERATIONS: Git Operations + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 16 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Git Operations + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize Git operations. + +--- +**Story 2**: As a user, I can use Git Operations features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize a new Git repository. +- [ ] Commit staged changes. +- [ ] Push commits to remote repository. +- [ ] Check if the working directory is clean. + +--- +**Story 3**: As a user, I can create new Git Operations records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Create a new branch. +- [ ] Add files to the staging area. + +--- +**Story 4**: As a developer, I can validate Git Operations data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Checkout an existing branch. + +--- +**Story 5**: As a user, I can view Git Operations data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get the name of the current branch. +- [ ] List all branches. +- [ ] Get list of changed files. + +--- + +#### Feature Outcomes + +- Helper class for Git operations. +- Provides CRUD operations: CREATE branch, READ current_branch, READ changed_files +### FEATURE-LOGGERSETUP: Logger Setup + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can view Logger Setup data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Shuts down all active queue listeners. +- [ ] Get a logger by name + +--- +**Story 2**: As a user, I can create new Logger Setup records + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Creates a dedicated logger for inter-agent message flow. +- [ ] Creates a new logger or returns an existing one with the specified configuration. + +--- +**Story 3**: As a user, I can use Logger Setup features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Flush all active loggers to ensure their output is written +- [ ] Flush a specific logger by name +- [ ] Write test summary in a format that log_analyzer.py can understand +- [ ] Log a message at TRACE level (5) +- [ ] Recursively mask sensitive values (API keys, tokens, passwords, secrets) in dicts/lists/strings. + +--- + +#### Feature Outcomes + +- Utility class for standardized logging setup across all agents +- Provides CRUD operations: CREATE agent_flow_logger, CREATE logger, READ logger +### FEATURE-SPECVALIDATIONRESULT: Spec Validation Result + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Spec Validation Result features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. +- [ ] Convert to JSON string. + +--- + +#### Feature Outcomes + +- Result of Specmatic validation. +### FEATURE-BRIDGEWATCHEVENTHANDLER: Bridge Watch Event Handler + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Bridge Watch Event Handler + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize bridge watch event handler. + +--- + +#### Feature Outcomes + +- Event handler for bridge-based watch mode. +### FEATURE-REPROREPORT: Repro Report + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can create new Repro Report records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add a check result to the report. + +--- +**Story 2**: As a user, I can view Repro Report data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get exit code for the repro command. + +--- +**Story 3**: As a user, I can use Repro Report features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert report to dictionary with structured findings. + +--- + +#### Feature Outcomes + +- Aggregated report of all validation checks. +- Provides CRUD operations: CREATE check, READ exit_code +### FEATURE-PERFORMANCEREPORT: Performance Report + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 6 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can create new Performance Report records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add a performance metric. + +--- +**Story 2**: As a user, I can view Performance Report data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get summary of performance report. + +--- +**Story 3**: As a user, I can use Performance Report features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Print performance summary to console. + +--- + +#### Feature Outcomes + +- Performance report for a command execution. +- Provides CRUD operations: CREATE metric, READ summary +### FEATURE-CONTRACTDENSITYMETRICS: Contract Density Metrics + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 4 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Contract Density Metrics + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize contract density metrics. + +--- +**Story 2**: As a user, I can use Contract Density Metrics features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert metrics to dictionary. + +--- + +#### Feature Outcomes + +- Contract density metrics for a plan bundle. +### FEATURE-AGENTREGISTRY: Agent Registry + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Agent Registry + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize agent registry with default agents. + +--- +**Story 2**: As a user, I can use Agent Registry features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Register an agent instance. + +--- +**Story 3**: As a user, I can view Agent Registry data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get an agent instance by name. +- [ ] Get agent instance for a command. +- [ ] List all registered agent names. + +--- + +#### Feature Outcomes + +- Registry for agent mode instances. +- Provides CRUD operations: READ agent_for_command +### FEATURE-PLANENRICHER: Plan Enricher + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 8 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Plan Enricher features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Enrich plan bundle by enhancing vague acceptance criteria, incomplete requirements, and generic tasks. + +--- + +#### Feature Outcomes + +- Enricher for automatically enhancing plan bundles. +### FEATURE-IMPLEMENTATIONPLANTEMPLATE: Implementation Plan Template + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 2 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Implementation Plan Template features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert to dictionary. + +--- + +#### Feature Outcomes + +- Template for implementation plans (modernization roadmap). +### FEATURE-SYNCAGENT: Sync Agent + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can generate outputs from Sync Agent + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate enhanced prompt for sync operation. + +--- +**Story 2**: As a user, I can use Sync Agent features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Execute sync command with enhanced prompts. +- [ ] Inject context information specific to sync operations. + +--- + +#### Feature Outcomes + +- Bidirectional sync agent with conflict resolution. +### FEATURE-ENRICHMENTCONTEXT: Enrichment Context + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Enrichment Context + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize empty enrichment context. + +--- +**Story 2**: As a user, I can create new Enrichment Context records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add relationship data to context. +- [ ] Add contract for a feature. +- [ ] Add bundle metadata to context. + +--- +**Story 3**: As a user, I can use Enrichment Context features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert context to dictionary for LLM consumption. +- [ ] Convert context to Markdown format for LLM prompt. + +--- + +#### Feature Outcomes + +- Context for LLM enrichment workflow. +### FEATURE-SOURCEARTIFACTSCANNER: Source Artifact Scanner + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Source Artifact Scanner + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize scanner with repository path. + +--- +**Story 2**: As a user, I can use Source Artifact Scanner features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Discover existing files and their current state. +- [ ] Map code files → feature specs using AST analysis (parallelized). + +--- +**Story 3**: As a user, I can analyze data with Source Artifact Scanner + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract function names from code. +- [ ] Extract test function names from test file. + +--- + +#### Feature Outcomes + +- Scanner for discovering and linking source artifacts to specifications. +### FEATURE-ENRICHMENTREPORT: Enrichment Report + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 6 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Enrichment Report + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize empty enrichment report. + +--- +**Story 2**: As a user, I can create new Enrichment Report records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add a missing feature discovered by LLM. +- [ ] Add business context items. + +--- +**Story 3**: As a user, I can use Enrichment Report features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Adjust confidence score for a feature. + +--- + +#### Feature Outcomes + +- Parsed enrichment report from LLM. +### FEATURE-REQUIREMENTEXTRACTOR: Requirement Extractor + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Requirement Extractor + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize requirement extractor. + +--- +**Story 2**: As a user, I can analyze data with Requirement Extractor + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract complete requirement statement from class. +- [ ] Extract complete requirement statement from method. +- [ ] Extract Non-Functional Requirements from code patterns. + +--- + +#### Feature Outcomes + +- Extracts complete requirements from code semantics. +### FEATURE-BRIDGEWATCH: Bridge Watch + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Bridge Watch + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize bridge watch mode. + +--- +**Story 2**: As a user, I can use Bridge Watch features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Start watching for file system changes. +- [ ] Stop watching for file system changes. +- [ ] Continuously watch and sync changes. + +--- + +#### Feature Outcomes + +- Bridge-based watch mode for continuous sync operations. +### FEATURE-CONTRACTGENERATOR: Contract Generator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Contract Generator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize contract generator. + +--- +**Story 2**: As a user, I can generate outputs from Contract Generator + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate contract stubs from SDD HOW sections. + +--- + +#### Feature Outcomes + +- Generates contract stubs from SDD HOW sections. +### FEATURE-PLANCOMPARATOR: Plan Comparator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 5 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can compare Plan Comparator data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Compare two plan bundles and generate deviation report. + +--- + +#### Feature Outcomes + +- Compares two plan bundles to detect deviations. +### FEATURE-PROTOCOLGENERATOR: Protocol Generator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Protocol Generator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize protocol generator. + +--- +**Story 2**: As a user, I can generate outputs from Protocol Generator + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate protocol YAML file from model. +- [ ] Generate file from custom template. + +--- +**Story 3**: As a user, I can use Protocol Generator features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Render protocol to YAML string without writing to file. + +--- + +#### Feature Outcomes + +- Generator for protocol YAML files. +### FEATURE-REPORTGENERATOR: Report Generator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Report Generator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize report generator. + +--- +**Story 2**: As a user, I can generate outputs from Report Generator + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate validation report file. +- [ ] Generate deviation report file. + +--- +**Story 3**: As a user, I can use Report Generator features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Render report to markdown string without writing to file. + +--- + +#### Feature Outcomes + +- Generator for validation and deviation reports. +### FEATURE-BRIDGECONFIG: Bridge Config + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Bridge Config features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Load bridge configuration from YAML file. +- [ ] Save bridge configuration to YAML file. +- [ ] Resolve dynamic path pattern with context variables. +- [ ] Resolve template path for a schema key. + +--- +**Story 2**: As a user, I can view Bridge Config data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get command mapping by key. + +--- +**Story 3**: As a user, I can update Bridge Config records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Create Spec-Kit classic layout bridge preset. +- [ ] Create Spec-Kit modern layout bridge preset. +- [ ] Create generic markdown bridge preset. + +--- + +#### Feature Outcomes + +- Bridge configuration (translation layer between SpecFact and external tools). +- Defines data models: $MODEL +- Provides CRUD operations: READ command +### FEATURE-SYNCWATCHER: Sync Watcher + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Sync Watcher + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize sync watcher. + +--- +**Story 2**: As a user, I can use Sync Watcher features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Start watching for file system changes. +- [ ] Stop watching for file system changes. +- [ ] Continuously watch and sync changes. + +--- + +#### Feature Outcomes + +- Watch mode for continuous sync operations. +### FEATURE-CONSTITUTIONENRICHER: Constitution Enricher + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can analyze data with Constitution Enricher + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Analyze repository and extract constitution metadata. + +--- +**Story 2**: As a user, I can use Constitution Enricher features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Suggest principles based on repository analysis. +- [ ] Fill constitution template with suggestions. +- [ ] Generate bootstrap constitution from repository analysis. + +--- +**Story 3**: As a developer, I can validate Constitution Enricher data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate constitution completeness. + +--- + +#### Feature Outcomes + +- Enricher for automatically generating and enriching project constitutions. +### FEATURE-BRIDGESYNC: Bridge Sync + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Bridge Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize bridge sync. + +--- +**Story 2**: As a user, I can use Bridge Sync features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Resolve artifact path using bridge configuration. +- [ ] Import artifact from tool format to SpecFact project bundle. +- [ ] Export artifact from SpecFact project bundle to tool format. +- [ ] Perform bidirectional sync for all artifacts. + +--- + +#### Feature Outcomes + +- Adapter-agnostic bidirectional sync using bridge configuration. +### FEATURE-REPOSITORYSYNC: Repository Sync + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Repository Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize repository sync. + +--- +**Story 2**: As a user, I can update Repository Sync records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Sync code changes to SpecFact artifacts. +- [ ] Detect code changes in repository. +- [ ] Update plan artifacts based on code changes. + +--- +**Story 3**: As a user, I can use Repository Sync features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Track deviations from manual plans. + +--- + +#### Feature Outcomes + +- Sync code changes to SpecFact artifacts. +- Provides CRUD operations: UPDATE plan_artifacts +### FEATURE-WORKFLOWGENERATOR: Workflow Generator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Workflow Generator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize workflow generator. + +--- +**Story 2**: As a user, I can generate outputs from Workflow Generator + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate GitHub Action workflow for SpecFact validation. +- [ ] Generate Semgrep async rules for the repository. + +--- + +#### Feature Outcomes + +- Generator for GitHub Actions workflows and Semgrep rules. +### FEATURE-ENHANCEDSYNCWATCHER: Enhanced Sync Watcher + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Enhanced Sync Watcher + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize enhanced sync watcher. + +--- +**Story 2**: As a user, I can use Enhanced Sync Watcher features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Start watching for file system changes. +- [ ] Stop watching for file system changes. +- [ ] Continuously watch and sync changes. + +--- + +#### Feature Outcomes + +- Enhanced watch mode with hash-based change detection, dependency tracking, and LZ4 cache. +### FEATURE-MESSAGEFLOWFORMATTER: Message Flow Formatter + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Message Flow Formatter + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize the formatter with the agent name + +--- +**Story 2**: As a user, I can use Message Flow Formatter features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Format the log record according to message flow patterns + +--- + +#### Feature Outcomes + +- Custom formatter that recognizes message flow patterns and formats them accordingly +### FEATURE-PROGRESSIVEDISCLOSURECOMMAND: Progressive Disclosure Command + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Progressive Disclosure Command features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Override format_help to conditionally show advanced options in docstring. + +--- +**Story 2**: As a user, I can view Progressive Disclosure Command data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Override get_params to include hidden options when advanced help is requested. + +--- + +#### Feature Outcomes + +- Custom Typer command that shows hidden options when advanced help is requested. +- Provides CRUD operations: READ params +### FEATURE-COMMANDROUTER: Command Router + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Command Router features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Route a command based on operational mode. +- [ ] Check if command should use agent routing. +- [ ] Check if command should use direct execution. + +--- +**Story 2**: As a user, I can analyze data with Command Router + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Route a command with automatic mode detection. + +--- + +#### Feature Outcomes + +- Routes commands based on operational mode. +### FEATURE-CONTROLFLOWANALYZER: Control Flow Analyzer + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Control Flow Analyzer + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize control flow analyzer. + +--- +**Story 2**: As a user, I can analyze data with Control Flow Analyzer + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract scenarios from a method's control flow. + +--- + +#### Feature Outcomes + +- Analyzes AST to extract control flow patterns and generate scenarios. +### FEATURE-SPECKITCONVERTER: Spec Kit Converter + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Spec Kit Converter + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize Spec-Kit converter. + +--- +**Story 2**: As a user, I can process data using Spec Kit Converter + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert Spec-Kit features to SpecFact protocol. +- [ ] Convert Spec-Kit markdown artifacts to SpecFact plan bundle. +- [ ] Convert SpecFact plan bundle to Spec-Kit markdown artifacts. + +--- +**Story 3**: As a user, I can generate outputs from Spec Kit Converter + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate Semgrep async rules for the repository. +- [ ] Generate GitHub Action workflow for SpecFact validation. + +--- + +#### Feature Outcomes + +- Converter from Spec-Kit format to SpecFact format. +### FEATURE-CODEANALYZER: Code Analyzer + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 21 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Code Analyzer + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize code analyzer. + +--- +**Story 2**: As a user, I can analyze data with Code Analyzer + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Analyze repository and generate plan bundle. + +--- +**Story 3**: As a user, I can view Code Analyzer data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get status of all analysis plugins. + +--- + +#### Feature Outcomes + +- Analyzes Python code to auto-derive plan bundles. +- Provides CRUD operations: READ plugin_status +### FEATURE-CONTRACTEXTRACTOR: Contract Extractor + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 12 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Contract Extractor + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize contract extractor. + +--- +**Story 2**: As a user, I can analyze data with Contract Extractor + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract contracts from a function signature. + +--- +**Story 3**: As a user, I can generate outputs from Contract Extractor + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate JSON Schema from contracts. +- [ ] Generate icontract decorator code from contracts. + +--- + +#### Feature Outcomes + +- Extracts API contracts from function signatures, type hints, and validation logic. +### FEATURE-PLANMIGRATOR: Plan Migrator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Plan Migrator features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Load plan bundle and migrate if needed. + +--- +**Story 2**: As a developer, I can validate Plan Migrator data + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Check if plan bundle needs migration. + +--- + +#### Feature Outcomes + +- Plan bundle migrator for upgrading schema versions. +### FEATURE-SMARTCOVERAGEMANAGER: Smart Coverage Manager + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 11 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Smart Coverage Manager + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) + +--- +**Story 2**: As a developer, I can validate Smart Coverage Manager data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Check if a full test run is needed. + +--- +**Story 3**: As a user, I can view Smart Coverage Manager data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get current coverage status. +- [ ] Get recent test log files. + +--- +**Story 4**: As a user, I can use Smart Coverage Manager features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Show recent test log files and their status. +- [ ] Show the latest test log content. +- [ ] Run tests with smart change detection and specified level. +- [ ] Run tests by specified level: unit, folder, integration, e2e, or full. +- [ ] Force a test run regardless of file changes. + +--- + +#### Feature Outcomes + +- Provides Smart Coverage Manager functionality +### FEATURE-CONSTITUTIONEVIDENCEEXTRACTOR: Constitution Evidence Extractor + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 18 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Constitution Evidence Extractor + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize constitution evidence extractor. + +--- +**Story 2**: As a user, I can analyze data with Constitution Evidence Extractor + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract Article VII (Simplicity) evidence from project structure. +- [ ] Extract Article VIII (Anti-Abstraction) evidence from framework usage. +- [ ] Extract Article IX (Integration-First) evidence from contract patterns. +- [ ] Extract evidence for all constitution articles. + +--- +**Story 3**: As a developer, I can validate Constitution Evidence Extractor data + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate constitution check section markdown from evidence. + +--- + +#### Feature Outcomes + +- Extracts evidence-based constitution checklist from code patterns. +### FEATURE-SYNCEVENTHANDLER: Sync Event Handler + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 8 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Sync Event Handler + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize event handler. + +--- +**Story 2**: As a user, I can use Sync Event Handler features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file modification events. + +--- +**Story 3**: As a user, I can create new Sync Event Handler records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file creation events. + +--- +**Story 4**: As a user, I can delete Sync Event Handler records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file deletion events. + +--- + +#### Feature Outcomes + +- Event handler for file system changes during sync operations. +### FEATURE-GRAPHANALYZER: Graph Analyzer + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 17 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Graph Analyzer + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize graph analyzer. + +--- +**Story 2**: As a user, I can analyze data with Graph Analyzer + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract call graph using pyan. + +--- +**Story 3**: As a user, I can generate outputs from Graph Analyzer + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Build comprehensive dependency graph using NetworkX. + +--- +**Story 4**: As a user, I can view Graph Analyzer data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get summary of dependency graph. + +--- + +#### Feature Outcomes + +- Graph-based dependency and call graph analysis. +- Provides CRUD operations: READ graph_summary +### FEATURE-PROJECTBUNDLE: Project Bundle + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 19 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Project Bundle features + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Load project bundle from directory structure. +- [ ] Save project bundle to directory structure. + +--- +**Story 2**: As a user, I can view Project Bundle data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get feature by key (lazy load if needed). + +--- +**Story 3**: As a user, I can create new Project Bundle records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add feature (save to file, update registry). + +--- +**Story 4**: As a user, I can update Project Bundle records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Update feature (save to file, update registry). + +--- +**Story 5**: As a user, I can process data using Project Bundle + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Compute summary from all aspects (for compatibility). + +--- + +#### Feature Outcomes + +- Modular project bundle (replaces monolithic PlanBundle). +- Defines data models: $MODEL +- Provides CRUD operations: READ feature, CREATE feature, UPDATE feature +### FEATURE-ANALYZEAGENT: Analyze Agent + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 18 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can generate outputs from Analyze Agent + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate enhanced prompt for brownfield analysis. + +--- +**Story 2**: As a user, I can use Analyze Agent features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Execute brownfield analysis with enhanced prompts. +- [ ] Inject context information specific to analysis operations. + +--- +**Story 3**: As a user, I can analyze data with Analyze Agent + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Analyze codebase using AI-first approach with semantic understanding. + +--- + +#### Feature Outcomes + +- AI-first brownfield analysis agent with semantic understanding. +### FEATURE-ENHANCEDSYNCEVENTHANDLER: Enhanced Sync Event Handler + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 8 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Enhanced Sync Event Handler + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize enhanced event handler. + +--- +**Story 2**: As a user, I can use Enhanced Sync Event Handler features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file modification events. + +--- +**Story 3**: As a user, I can create new Enhanced Sync Event Handler records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file creation events. + +--- +**Story 4**: As a user, I can delete Enhanced Sync Event Handler records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Handle file deletion events. + +--- + +#### Feature Outcomes + +- Enhanced event handler with hash-based change detection and dependency tracking. +### FEATURE-PLANBUNDLE: Plan Bundle + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can process data using Plan Bundle + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Compute summary metadata for fast access without full parsing. + +--- +**Story 2**: As a user, I can update Plan Bundle records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Update the summary metadata in this plan bundle. + +--- + +#### Feature Outcomes + +- Complete plan bundle model. +- Defines data models: $MODEL +- Provides CRUD operations: UPDATE summary +### FEATURE-PLANAGENT: Plan Agent + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can generate outputs from Plan Agent + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate enhanced prompt for plan management. + +--- +**Story 2**: As a user, I can use Plan Agent features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Execute plan command with enhanced prompts. +- [ ] Inject context information specific to plan operations. + +--- + +#### Feature Outcomes + +- Plan management agent with business logic understanding. +### FEATURE-OPENAPIEXTRACTOR: Open A P I Extractor + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 17 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Open A P I Extractor + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize extractor with repository path. + +--- +**Story 2**: As a user, I can analyze data with Open A P I Extractor + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Convert verbose acceptance criteria to OpenAPI contract. +- [ ] Extract OpenAPI contract from existing code using AST. + +--- +**Story 3**: As a user, I can create new Open A P I Extractor records + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Add test examples to OpenAPI specification. + +--- +**Story 4**: As a user, I can use Open A P I Extractor features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Save OpenAPI contract to file. + +--- + +#### Feature Outcomes + +- Extractor for generating OpenAPI contracts from features. +- Provides CRUD operations: CREATE test_examples +### FEATURE-SPECKITSCANNER: Spec Kit Scanner + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Spec Kit Scanner + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize Spec-Kit scanner. + +--- +**Story 2**: As a user, I can use Spec Kit Scanner features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Check if repository is a Spec-Kit project. +- [ ] Check if constitution.md exists and is not empty. +- [ ] Scan Spec-Kit directory structure. +- [ ] Discover all features from specs directory. + +--- +**Story 3**: As a user, I can analyze data with Spec Kit Scanner + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Parse a Spec-Kit spec.md file to extract features, stories, requirements, and success criteria. +- [ ] Parse a Spec-Kit plan.md file to extract technical context and architecture. +- [ ] Parse a Spec-Kit tasks.md file to extract tasks with IDs, story mappings, and dependencies. +- [ ] Parse Spec-Kit memory files (constitution.md, etc.). + +--- + +#### Feature Outcomes + +- Scanner for Spec-Kit repositories. +### FEATURE-CODETOSPECSYNC: Code To Spec Sync + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 7 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Code To Spec Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize code-to-spec sync. + +--- +**Story 2**: As a user, I can use Code To Spec Sync features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Sync code changes to specifications using AST analysis. + +--- + +#### Feature Outcomes + +- Sync code changes to specifications using AST analysis. +### FEATURE-BRIDGETEMPLATELOADER: Bridge Template Loader + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 14 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Bridge Template Loader + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize bridge template loader. + +--- +**Story 2**: As a user, I can use Bridge Template Loader features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Resolve template path for a schema key using bridge configuration. +- [ ] Load template for a schema key using bridge configuration. +- [ ] Render template for a schema key with provided context. +- [ ] Check if template exists for a schema key. + +--- +**Story 3**: As a user, I can view Bridge Template Loader data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] List all available templates from bridge configuration. + +--- +**Story 4**: As a user, I can create new Bridge Template Loader records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Create template context with common variables. + +--- + +#### Feature Outcomes + +- Template loader that uses bridge configuration for dynamic template resolution. +- Provides CRUD operations: CREATE template_context +### FEATURE-PLANGENERATOR: Plan Generator + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Plan Generator + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize plan generator. + +--- +**Story 2**: As a user, I can generate outputs from Plan Generator + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate plan bundle YAML file from model. +- [ ] Generate file from custom template. + +--- +**Story 3**: As a user, I can use Plan Generator features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Render plan bundle to YAML string without writing to file. + +--- + +#### Feature Outcomes + +- Generator for plan bundle YAML files. +### FEATURE-SPECTOCODESYNC: Spec To Code Sync + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 15 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Spec To Code Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize spec-to-code sync. + +--- +**Story 2**: As a user, I can use Spec To Code Sync features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Prepare context for LLM code generation. + +--- +**Story 3**: As a user, I can generate outputs from Spec To Code Sync + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Generate LLM prompt for code generation. + +--- + +#### Feature Outcomes + +- Sync specification changes to code by preparing LLM prompts. +### FEATURE-BRIDGEPROBE: Bridge Probe + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 16 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Bridge Probe + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize bridge probe. + +--- +**Story 2**: As a user, I can analyze data with Bridge Probe + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Detect tool capabilities and configuration. + +--- +**Story 3**: As a user, I can generate outputs from Bridge Probe + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Auto-generate bridge configuration based on detected capabilities. + +--- +**Story 4**: As a developer, I can validate Bridge Probe data + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Validate bridge configuration and check if paths exist. + +--- +**Story 5**: As a user, I can use Bridge Probe features + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Save bridge configuration to `.specfact/config/bridge.yaml`. + +--- + +#### Feature Outcomes + +- Probe for detecting tool configurations and generating bridge configs. +### FEATURE-SPECFACTSTRUCTURE: Spec Fact Structure + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 41 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a user, I can use Spec Fact Structure features + +**Definition of Ready**: + +- [x] Story Points: 13 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 13 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Return canonical plan suffix for format (defaults to YAML). +- [ ] Ensure a plan filename includes the correct suffix. +- [ ] Remove known plan suffix from filename. +- [ ] Compute default plan filename for requested format. +- [ ] Ensure the .specfact directory structure exists. +- [ ] Sanitize plan name for filesystem persistence. +- [ ] Create complete .specfact directory structure. +- [ ] Get path to project bundle directory. +- [ ] Ensure project bundle directory structure exists. + +--- +**Story 2**: As a user, I can view Spec Fact Structure data + +**Definition of Ready**: + +- [x] Story Points: 13 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 13 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get a timestamped report path. +- [ ] Get path for brownfield analysis report. +- [ ] Get path for auto-derived brownfield plan. +- [ ] Get path for comparison report. +- [ ] Get path to active plan bundle (from config or fallback to main.bundle.yaml). +- [ ] Get active bundle name from config. +- [ ] List all available project bundles with metadata. +- [ ] Get path to enforcement configuration file. +- [ ] Get path to SDD manifest file. +- [ ] Get timestamped path for brownfield analysis report (YAML bundle). +- [ ] Get enrichment report path based on plan bundle path. +- [ ] Get original plan bundle path from enrichment report path. +- [ ] Get enriched plan bundle path based on original plan bundle path. +- [ ] Get the latest brownfield report from the plans directory. +- [ ] Get bundle-specific reports directory. +- [ ] Get bundle-specific brownfield report path. +- [ ] Get bundle-specific comparison report path. +- [ ] Get bundle-specific enrichment report path. +- [ ] Get bundle-specific enforcement report path. +- [ ] Get bundle-specific SDD manifest path. +- [ ] Get bundle-specific tasks file path. +- [ ] Get bundle-specific logs directory. + +--- +**Story 3**: As a user, I can update Spec Fact Structure records + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Set the active project bundle in the plans config. +- [ ] Update summary metadata for an existing plan bundle. + +--- +**Story 4**: As a user, I can create new Spec Fact Structure records + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Create .gitignore for .specfact directory. +- [ ] Create README for .specfact directory. + +--- +**Story 5**: As a user, I can analyze data with Spec Fact Structure + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Detect if bundle is monolithic or modular. + +--- + +#### Feature Outcomes + +- Manages the canonical .specfact/ directory structure. +### FEATURE-SPECKITSYNC: Spec Kit Sync + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 14 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Spec Kit Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize Spec-Kit sync. + +--- +**Story 2**: As a user, I can use Spec Kit Sync features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Sync changes between Spec-Kit and SpecFact artifacts bidirectionally. +- [ ] Resolve conflicts with merge strategy. +- [ ] Apply resolved conflicts to merged changes. + +--- +**Story 3**: As a user, I can update Spec Kit Sync records + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Detect changes in Spec-Kit artifacts. +- [ ] Detect changes in SpecFact artifacts. +- [ ] Merge changes from both sources. + +--- +**Story 4**: As a user, I can analyze data with Spec Kit Sync + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Detect conflicts between Spec-Kit and SpecFact changes. + +--- + +#### Feature Outcomes + +- Bidirectional sync between Spec-Kit and SpecFact. +### FEATURE-OPENAPITESTCONVERTER: Open A P I Test Converter + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 10 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Open A P I Test Converter + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Initialize converter with repository path. + +--- +**Story 2**: As a user, I can analyze data with Open A P I Test Converter + +**Definition of Ready**: + +- [x] Story Points: 8 +- [x] Value Points: 5 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 8 (Complexity) +- **Value Points**: 5 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Extract OpenAPI examples from test files using Semgrep. + +--- + +#### Feature Outcomes + +- Converts test patterns to OpenAPI examples using Semgrep. +### FEATURE-CONTRACTFIRSTTESTMANAGER: Contract First Test Manager + +**Priority**: *[Not Set]* | **Rank**: *[Not Set]* +**Business Value Score**: *[Not Set]*/100 +**Target Release**: *[Not Set]* +**Estimated Story Points**: 9 + +#### Business Value + +*[ACTION REQUIRED: Define business value proposition]* + +**Target Users**: *[ACTION REQUIRED: Define target users]* +**Success Metrics**: + +- *[ACTION REQUIRED: Define measurable success metrics]* + +#### Dependencies + +- No feature dependencies + +#### User Stories + +**Story 1**: As a developer, I can configure Contract First Test Manager + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) + +--- +**Story 2**: As a user, I can use Contract First Test Manager features + +**Definition of Ready**: + +- [x] Story Points: 5 +- [x] Value Points: 3 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 5 (Complexity) +- **Value Points**: 3 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Run contract-first tests with the 3-layer quality model. + +--- +**Story 3**: As a user, I can view Contract First Test Manager data + +**Definition of Ready**: + +- [x] Story Points: 2 +- [x] Value Points: 8 +- [ ] Priority: None +- [ ] Dependencies: 0 identified +- [ ] Business Value: ✗ Missing +- [ ] Target Date: None +- [ ] Target Sprint: None + +**Story Details**: + +- **Story Points**: 2 (Complexity) +- **Value Points**: 8 (Business Value) +- **Priority**: None +- **Rank**: None +- **Target Date**: None +- **Target Sprint**: None +- **Target Release**: None + +**Business Value**: + +None + +**Business Metrics**: + +- *[ACTION REQUIRED: Define measurable business outcomes]* + +**Dependencies**: + +- No story dependencies + +**Acceptance Criteria** (User-Focused): + +- [ ] Must verify contracts extracted in plan bundle works correctly (see contract examples) +- [ ] Must verify contracts included in speckit plan md works correctly (see contract examples) +- [ ] article ix checkbox checked when contracts exist works correctly (see contract examples) +- [ ] Get contract-first test status. + +--- + +#### Feature Outcomes + +- Contract-first test manager extending the smart coverage system. +- Provides CRUD operations: READ contract_status + +## Ownership & Locks + +*No sections currently locked* + +## Validation Checklist + +- [ ] All user stories have clear acceptance criteria +- [ ] Success metrics are measurable and defined +- [ ] Target users are identified +- [ ] Business constraints are documented +- [ ] Feature priorities are established + +## Notes + +*Use this section for additional context, questions, or clarifications needed.* diff --git a/_site_test/prompts/PROMPT_VALIDATION_CHECKLIST.md b/_site_test/prompts/PROMPT_VALIDATION_CHECKLIST.md new file mode 100644 index 0000000..b178741 --- /dev/null +++ b/_site_test/prompts/PROMPT_VALIDATION_CHECKLIST.md @@ -0,0 +1,495 @@ +# Prompt Validation Checklist + +This checklist helps ensure prompt templates are correct, aligned with CLI commands, and provide good UX. + +## Automated Validation + +Run the automated validator: + +```bash +# Validate all prompts +hatch run validate-prompts + +# Or directly +python tools/validate_prompts.py +``` + +The validator checks: + +- ✅ Required sections present +- ✅ CLI commands match actual CLI +- ✅ CLI enforcement rules present +- ✅ Wait state rules present +- ✅ Dual-stack workflow (if applicable) +- ✅ Consistency across prompts + +## Manual Review Checklist + +### 1. Structure & Formatting + +- [ ] **Frontmatter present**: YAML frontmatter with `description` field +- [ ] **Required sections present**: + - [ ] `# SpecFact [Command Name]` - Main title (H1) + - [ ] `## User Input` - Contains `$ARGUMENTS` placeholder in code block + - [ ] `## Purpose` - Clear description of what the command does + - [ ] `## Parameters` - Organized by groups (Target/Input, Output/Results, Behavior/Options, Advanced/Configuration) + - [ ] `## Workflow` - Step-by-step execution instructions + - [ ] `## CLI Enforcement` - Rules for using CLI commands + - [ ] `## Expected Output` - Success and error examples + - [ ] `## Common Patterns` - Usage examples + - [ ] `## Context` - Contains `{ARGS}` placeholder +- [ ] **Markdown formatting**: Proper headers, code blocks, lists +- [ ] **$ARGUMENTS placeholder**: Present in "User Input" section within code block +- [ ] **{ARGS} placeholder**: Present in "Context" section + +### 2. CLI Alignment + +- [ ] **CLI command matches**: The command in the prompt matches the actual CLI command +- [ ] **CLI enforcement rules present**: + - [ ] "ALWAYS execute CLI first" + - [ ] "ALWAYS use non-interactive mode for CI/CD" (explicitly requires `--no-interactive` flag to avoid timeouts in Copilot environments) + - [ ] "ALWAYS use tools for read/write" (explicitly requires using file reading tools like `read_file` for display purposes only, CLI commands for all write operations) + - [ ] "NEVER modify .specfact folder directly" (explicitly forbids creating, modifying, or deleting files in `.specfact/` folder directly) + - [ ] "NEVER create YAML/JSON directly" + - [ ] "NEVER bypass CLI validation" + - [ ] "Use CLI output as grounding" + - [ ] "NEVER manipulate internal code" (explicitly forbids direct Python code manipulation) + - [ ] "No internal knowledge required" (explicitly states that internal implementation details should not be needed) + - [ ] "NEVER read artifacts directly for updates" (explicitly forbids reading files directly for update operations, only for display purposes) +- [ ] **Available CLI commands documented**: Prompt lists available CLI commands for plan updates (e.g., `update-idea`, `update-feature`, `add-feature`, `add-story`) +- [ ] **FORBIDDEN examples present**: Prompt shows examples of what NOT to do (direct code manipulation) +- [ ] **CORRECT examples present**: Prompt shows examples of what TO do (using CLI commands) +- [ ] **Command examples**: Examples show actual CLI usage with correct flags +- [ ] **Flag documentation**: All flags are documented with defaults and descriptions +- [ ] **Filter options documented** (for `plan select`): `--current`, `--stages`, `--last`, `--no-interactive` flags are documented with use cases and examples +- [ ] **Positional vs option arguments**: Correctly distinguishes between positional arguments and `--option` flags (e.g., `specfact plan select 20` not `specfact plan select --plan 20`) +- [ ] **Boolean flags documented correctly**: Boolean flags use `--flag/--no-flag` syntax, not `--flag true/false` + - ❌ **WRONG**: `--draft true` or `--draft false` (Typer boolean flags don't accept values) + - ✅ **CORRECT**: `--draft` (sets True) or `--no-draft` (sets False) or omit (leaves unchanged) +- [ ] **Entry point flag documented** (for `import from-code`): `--entry-point` flag is documented with use cases (multi-project repos, partial analysis, incremental modernization) + +### 3. Wait States & User Input + +- [ ] **User Input section**: Contains `$ARGUMENTS` placeholder in code block with `text` language +- [ ] **User Input instruction**: Includes "You **MUST** consider the user input before proceeding (if not empty)" +- [ ] **Wait state rules** (if applicable for interactive workflows): + - [ ] "Never assume" + - [ ] "Never continue" + - [ ] "Be explicit" + - [ ] "Provide options" +- [ ] **Explicit wait markers**: `[WAIT FOR USER RESPONSE - DO NOT CONTINUE]` present where needed (for interactive workflows) +- [ ] **Missing argument handling**: Clear instructions for what to do when arguments are missing +- [ ] **User prompts**: Examples show how to ask for user input (if applicable) +- [ ] **No assumptions**: Prompt doesn't allow LLM to assume values and continue + +### 4. Flow Logic + +- [ ] **Dual-stack workflow** (if applicable): + - [ ] Phase 1: CLI Grounding documented + - [ ] Phase 2: LLM Enrichment documented + - [ ] **CRITICAL**: Stories are required for features in enrichment reports + - [ ] Story format example provided in prompt + - [ ] Explanation: Stories are required for promotion validation + - [ ] Phase 3: CLI Artifact Creation documented + - [ ] Enrichment report location specified (`.specfact/projects//reports/enrichment/`, bundle-specific, Phase 8.5) +- [ ] **Auto-enrichment workflow** (for `plan review`): + - [ ] `--auto-enrich` flag documented with when to use it + - [ ] LLM reasoning guidance for detecting when enrichment is needed + - [ ] Post-enrichment analysis steps documented + - [ ] **MANDATORY automatic refinement**: LLM must automatically refine generic criteria with code-specific details after auto-enrichment + - [ ] Two-phase enrichment strategy (automatic + LLM-enhanced refinement) + - [ ] Continuous improvement loop documented + - [ ] Examples of enrichment output and refinement process + - [ ] **Generic criteria detection**: Instructions to identify and replace generic patterns ("interact with the system", "works correctly") + - [ ] **Code-specific criteria generation**: Instructions to research codebase and create testable criteria with method names, parameters, return values +- [ ] **Feature deduplication** (for `sync`, `plan review`, `import from-code`): + - [ ] **Automated deduplication documented**: CLI automatically deduplicates features using normalized key matching + - [ ] **Deduplication scope explained**: + - [ ] Exact normalized key matches (e.g., `FEATURE-001` vs `001_FEATURE_NAME`) + - [ ] Prefix matches for Spec-Kit features (e.g., `FEATURE-IDEINTEGRATION` vs `041_IDE_INTEGRATION_SYSTEM`) + - [ ] Only matches when at least one key has numbered prefix (Spec-Kit origin) to avoid false positives + - [ ] **LLM semantic deduplication guidance**: Instructions for LLM to identify semantic/logical duplicates that automated deduplication might miss + - [ ] Review feature titles and descriptions for semantic similarity + - [ ] Identify features that represent the same functionality with different names + - [ ] Suggest consolidation when multiple features cover the same code/functionality + - [ ] Use `specfact plan update-feature` or `specfact plan add-feature` to consolidate + - [ ] **Deduplication output**: CLI shows "✓ Removed N duplicate features" - LLM should acknowledge this + - [ ] **Post-deduplication review**: LLM should review remaining features for semantic duplicates +- [ ] **Execution steps**: Clear, sequential steps +- [ ] **Error handling**: Instructions for handling errors +- [ ] **Validation**: CLI validation steps documented +- [ ] **Coverage validation** (for `plan promote`): Documentation of coverage status checks (critical vs important categories) +- [ ] **Copilot-friendly formatting** (if applicable): Instructions for formatting output as Markdown tables for better readability +- [ ] **Interactive workflows** (if applicable): Support for "details" requests and other interactive options (e.g., "20 details" for plan selection) + +### 5. Consistency + +- [ ] **Consistent terminology**: Uses same terms as other prompts +- [ ] **Consistent formatting**: Same markdown style as other prompts +- [ ] **Consistent structure**: Same section order as other prompts +- [ ] **Consistent examples**: Examples follow same pattern + +### 6. UX & Clarity + +- [ ] **Clear goal**: Goal section clearly explains what the command does +- [ ] **Clear constraints**: Operating constraints are explicit +- [ ] **Helpful examples**: Examples are realistic and helpful +- [ ] **Error messages**: Shows what happens if rules aren't followed +- [ ] **User-friendly**: Language is clear and not overly technical + +## Testing with Copilot + +### Step 1: Run Automated Validation + +```bash +hatch run validate-prompts +``` + +All prompts should pass with 0 errors. + +### Step 2: Manual Testing + +For each prompt, test the following scenarios: + +#### Scenario 1: Missing Required Arguments + +1. Invoke the slash command without required arguments +2. Verify the LLM: + - ✅ Asks for missing arguments + - ✅ Shows `[WAIT FOR USER RESPONSE - DO NOT CONTINUE]` + - ✅ Does NOT assume values and continue + - ✅ Provides helpful examples or defaults + +#### Scenario 2: All Arguments Provided + +1. Invoke the slash command with all required arguments +2. Verify the LLM: + - ✅ Executes the CLI command immediately + - ✅ Uses the provided arguments correctly + - ✅ Uses boolean flags correctly (`--draft` not `--draft true`) + - ✅ Uses `--entry-point` when user specifies partial analysis + - ✅ Does NOT create artifacts directly + - ✅ Parses CLI output correctly + +#### Scenario 3: Dual-Stack Workflow (for import-from-code) + +1. Invoke `/specfact.01-import legacy-api --repo .` without `--enrichment` +2. Verify the LLM: + - ✅ Executes Phase 1: CLI Grounding + - ✅ Reads CLI-generated artifacts + - ✅ Generates enrichment report (Phase 2) + - ✅ **CRITICAL**: Each missing feature includes at least one story + - ✅ Stories follow the format shown in prompt example + - ✅ Saves enrichment to `.specfact/projects//reports/enrichment/` with correct naming (bundle-specific, Phase 8.5) + - ✅ Executes Phase 3: CLI Artifact Creation with `--enrichment` flag + - ✅ Final artifacts are CLI-generated + - ✅ Enriched plan can be promoted (features have stories) + +#### Scenario 4: Plan Review Workflow (for plan-review) + +1. Invoke `/specfact.03-review legacy-api` with a plan bundle +2. Verify the LLM: + - ✅ Executes `specfact plan review` CLI command + - ✅ Parses CLI output for ambiguity findings + - ✅ Waits for user input when questions are asked + - ✅ Does NOT create clarifications directly in YAML + - ✅ Uses CLI to save updated plan bundle after each answer + - ✅ Follows interactive Q&A workflow correctly + +#### Scenario 4a: Plan Review with Auto-Enrichment (for plan-review) + +1. Invoke `/specfact.03-review legacy-api` with a plan bundle that has vague acceptance criteria or incomplete requirements +2. Verify the LLM: + - ✅ **Detects need for enrichment**: Recognizes vague patterns ("is implemented", "System MUST Helper class", generic tasks) + - ✅ **Suggests or uses `--auto-enrich`**: Either suggests using `--auto-enrich` flag or automatically uses it based on plan quality indicators + - ✅ **Executes enrichment**: Runs `specfact plan review --auto-enrich` + - ✅ **Parses enrichment results**: Captures enrichment summary (features updated, stories updated, acceptance criteria enhanced, etc.) + - ✅ **Analyzes enrichment quality**: Uses LLM reasoning to review what was enhanced + - ✅ **Identifies generic patterns**: Finds placeholder text like "interact with the system" that needs refinement + - ✅ **Proposes specific refinements**: Suggests domain-specific improvements using CLI commands + - ✅ **Executes refinements**: Uses `specfact plan update-feature --bundle ` to refine generic improvements + - ✅ **Re-runs review**: Executes `specfact plan review` again to verify improvements +3. Test with explicit enrichment request (e.g., "enrich the plan"): + - ✅ Uses `--auto-enrich` flag immediately + - ✅ Reviews enrichment results + - ✅ Suggests further improvements if needed + +#### Scenario 5: Plan Selection Workflow (for plan-select) + +1. Invoke `/specfact.02-plan select` (or use CLI: `specfact plan select`) +2. Verify the LLM: + - ✅ Executes `specfact plan select` CLI command + - ✅ Formats plan list as copilot-friendly Markdown table (not Rich table) + - ✅ Provides selection options (number, "number details", "q" to quit) + - ✅ Waits for user response with `[WAIT FOR USER RESPONSE - DO NOT CONTINUE]` +3. Request plan details (e.g., "20 details"): + - ✅ Loads plan bundle YAML file + - ✅ Extracts and displays detailed information (idea, themes, top features, business context) + - ✅ Asks if user wants to select the plan + - ✅ Waits for user confirmation +4. Select a plan (e.g., "20" or "y" after details): + - ✅ Uses **positional argument** syntax: `specfact plan select 20` (NOT `--plan 20`) + - ✅ Confirms selection with CLI output + - ✅ Does NOT create config.yaml directly +5. Test filter options: + - ✅ Uses `--current` flag to show only active plan: `specfact plan select --current` + - ✅ Uses `--stages` flag to filter by stages: `specfact plan select --stages draft,review` + - ✅ Uses `--last N` flag to show recent plans: `specfact plan select --last 5` +6. Test non-interactive mode (CI/CD): + - ✅ Uses `--no-interactive` flag with `--current`: `specfact plan select --no-interactive --current` + - ✅ Uses `--no-interactive` flag with `--last 1`: `specfact plan select --no-interactive --last 1` + - ✅ Handles error when multiple plans match filters in non-interactive mode + - ✅ Does NOT prompt for input when `--no-interactive` is used + +#### Scenario 6: Plan Promotion with Coverage Validation (for plan-promote) + +1. Invoke `/specfact-plan-promote` with a plan that has missing critical categories +2. Verify the LLM: + - ✅ Executes `specfact plan promote --stage review --validate` CLI command + - ✅ Parses CLI output showing coverage validation errors + - ✅ Shows which critical categories are Missing + - ✅ Suggests running `specfact plan review` to resolve ambiguities + - ✅ Does NOT attempt to bypass validation by creating artifacts directly + - ✅ Waits for user decision (use `--force` or run `plan review` first) +3. Invoke promotion with `--force` flag: + - ✅ Uses `--force` flag correctly: `specfact plan promote --stage review --force` + - ✅ Explains that `--force` bypasses validation (not recommended) + - ✅ Does NOT create plan bundle directly + +#### Scenario 7: Error Handling + +1. Invoke command with invalid arguments or paths +2. Verify the LLM: + - ✅ Shows CLI error messages + - ✅ Doesn't try to fix errors by creating artifacts + - ✅ Asks user for correct input + - ✅ Waits for user response + +### Step 3: Review Output + +After testing, review: + +- [ ] **CLI commands executed**: All commands use `specfact` CLI +- [ ] **Artifacts CLI-generated**: No YAML/JSON created directly by LLM +- [ ] **Wait states respected**: LLM waits for user input when needed +- [ ] **Enrichment workflow** (if applicable): Three-phase workflow followed correctly +- [ ] **Review workflow** (if applicable): Interactive Q&A workflow followed correctly, clarifications saved via CLI +- [ ] **Auto-enrichment workflow** (if applicable): + - [ ] LLM detects when enrichment is needed (vague criteria, incomplete requirements, generic tasks) + - [ ] Uses `--auto-enrich` flag appropriately + - [ ] Analyzes enrichment results with reasoning + - [ ] Proposes and executes specific refinements using CLI commands + - [ ] Iterates until plan quality meets standards +- [ ] **Selection workflow** (if applicable): Copilot-friendly table formatting, details option, correct CLI syntax (positional arguments), filter options (`--current`, `--stages`, `--last`), non-interactive mode (`--no-interactive`) +- [ ] **Promotion workflow** (if applicable): Coverage validation respected, suggestions to run `plan review` when categories are Missing +- [ ] **Error handling**: Errors handled gracefully without assumptions + +## Common Issues to Watch For + +### ❌ LLM Creates Artifacts Directly + +**Symptom**: LLM generates YAML/JSON instead of using CLI + +**Fix**: Strengthen CLI enforcement section, add more examples of what NOT to do + +### ❌ LLM Uses Interactive Mode in CI/CD + +**Symptom**: LLM uses interactive prompts that cause timeouts in Copilot environments + +**Fix**: + +- Add explicit requirement to use `--no-interactive` flag +- Document that interactive mode should only be used when user explicitly requests it +- Add examples showing non-interactive CLI command usage + +### ❌ LLM Modifies .specfact Folder Directly + +**Symptom**: LLM creates, modifies, or deletes files in `.specfact/` folder directly instead of using CLI commands + +**Fix**: + +- Add explicit prohibition against direct `.specfact/` folder modifications +- Emphasize that all operations must go through CLI commands +- Add examples showing correct CLI usage vs incorrect direct file manipulation + +### ❌ LLM Uses Direct File Manipulation Instead of Tools + +**Symptom**: LLM uses direct file write operations instead of CLI commands or file reading tools + +**Fix**: + +- Add explicit requirement to use file reading tools (e.g., `read_file`) for display purposes only +- Emphasize that all write operations must use CLI commands +- Add examples showing correct tool usage vs incorrect direct manipulation + +### ❌ LLM Assumes Values + +**Symptom**: LLM continues without waiting for user input + +**Fix**: Add more explicit wait state markers, show more examples of correct wait behavior + +### ❌ Wrong CLI Command + +**Symptom**: LLM uses incorrect command or flags + +**Fix**: Update command examples, verify CLI help text matches prompt + +### ❌ Wrong Argument Format (Positional vs Option) + +**Symptom**: LLM uses `--option` flag when command expects positional argument (e.g., `specfact plan select --plan 20` instead of `specfact plan select 20`) + +**Fix**: + +- Verify actual CLI command signature (use `specfact --help`) +- Update prompt to explicitly state positional vs option arguments +- Add examples showing correct syntax +- Add warning about common mistakes (e.g., "NOT `specfact plan select --plan 20` (this will fail)") + +### ❌ Wrong Boolean Flag Usage + +**Symptom**: LLM uses `--flag true` or `--flag false` when flag is boolean (e.g., `--draft true` instead of `--draft`) + +**Fix**: + +- Verify actual CLI command signature (use `specfact --help`) +- Update prompt to explicitly state boolean flag syntax: `--flag` sets True, `--no-flag` sets False, omit to leave unchanged +- Add examples showing correct syntax: `--draft` (not `--draft true`) +- Add warning about common mistakes: "NOT `--draft true` (this will fail - Typer boolean flags don't accept values)" +- Document when to use `--no-flag` vs omitting the flag entirely + +### ❌ Missing Enrichment Workflow + +**Symptom**: LLM doesn't follow three-phase workflow for import-from-code + +**Fix**: Strengthen dual-stack workflow section, add more explicit phase markers + +### ❌ Missing Coverage Validation + +**Symptom**: LLM promotes plans without checking coverage status, or doesn't suggest running `plan review` when categories are Missing + +**Fix**: + +- Update prompt to document coverage validation clearly +- Add examples showing validation errors +- Emphasize that `--force` should only be used when explicitly requested +- Document critical vs important categories + +### ❌ Missing Auto-Enrichment + +**Symptom**: LLM doesn't detect or use `--auto-enrich` flag when plan has vague acceptance criteria or incomplete requirements + +**Fix**: + +- Update prompt to document `--auto-enrich` flag and when to use it +- Add LLM reasoning guidance for detecting enrichment needs +- Document decision flow for when to suggest or use auto-enrichment +- Add examples of enrichment output and refinement process +- Emphasize two-phase approach: automatic enrichment + LLM-enhanced refinement + +## Validation Commands + +```bash +# Run automated validation +hatch run validate-prompts + +# Run unit tests for validation +hatch test tests/unit/prompts/test_prompt_validation.py -v + +# Check specific prompt +python tools/validate_prompts.py --prompt specfact.01-import +``` + +## Continuous Improvement + +After each prompt update: + +1. Run automated validation +2. Test with Copilot in real scenarios +3. Document any issues found +4. Update checklist based on learnings +5. Share findings with team + +## Available Prompts + +The following prompts are available for SpecFact CLI commands: + +### Core Workflow Commands (Numbered) + +- `specfact.01-import.md` - Import codebase into plan bundle (replaces `specfact-import-from-code.md`) +- `specfact.02-plan.md` - Plan management: init, add-feature, add-story, update-idea, update-feature, update-story (replaces multiple plan commands) +- `specfact.03-review.md` - Review plan and promote (replaces `specfact-plan-review.md`, `specfact-plan-promote.md`) +- `specfact.04-sdd.md` - Create SDD manifest (new, based on `plan harden`) +- `specfact.05-enforce.md` - SDD enforcement (replaces `specfact-enforce.md`) +- `specfact.06-sync.md` - Sync operations (replaces `specfact-sync.md`) +- `specfact.07-contracts.md` - Contract enhancement workflow: analyze → generate prompts → apply contracts sequentially (new, based on `analyze contracts`, `generate contracts-prompt`, `generate contracts-apply`) + +### Advanced Commands (No Numbering) + +- `specfact.compare.md` - Compare plans (replaces `specfact-plan-compare.md`) +- `specfact.validate.md` - Validation suite (replaces `specfact-repro.md`) + +### Constitution Management + +- Constitution commands are integrated into `specfact.06-sync.md` and `specfact.01-import.md` workflows +- Constitution bootstrap/enrich/validate commands are suggested automatically when constitution is missing or minimal + +--- + +**Last Updated**: 2025-01-XX +**Version**: 1.10 + +## Changelog + +### Version 1.11 (2025-12-06) + +- Added `specfact.07-contracts.md` to available prompts list +- New contract enhancement workflow prompt for sequential contract application +- Workflow: analyze contracts → generate prompts → apply contracts with careful review + +### Version 1.10 (2025-01-XX) + +- Added non-interactive mode enforcement requirements +- Added tool-based read/write instructions requirements +- Added prohibition against direct `.specfact/` folder modifications +- Added new common issues: LLM Uses Interactive Mode in CI/CD, LLM Modifies .specfact Folder Directly, LLM Uses Direct File Manipulation Instead of Tools +- Updated CLI enforcement rules checklist to include new requirements + +### Version 1.9 (2025-11-20) + +- Added filter options validation for `plan select` command (`--current`, `--stages`, `--last`) +- Added non-interactive mode validation for `plan select` command (`--no-interactive`) +- Updated Scenario 5 to include filter options and non-interactive mode testing +- Added filter options documentation requirements to CLI alignment checklist +- Updated selection workflow checklist to include filter options and non-interactive mode + +### Version 1.8 (2025-11-20) + +- Added feature deduplication validation checks +- Added automated deduplication documentation requirements (exact matches, prefix matches for Spec-Kit features) +- Added LLM semantic deduplication guidance (identifying semantic/logical duplicates) +- Added deduplication workflow to testing scenarios +- Added common issue: Missing Semantic Deduplication +- Updated Scenario 2 to verify deduplication acknowledgment and semantic review + +### Version 1.7 (2025-11-19) + +- Added boolean flag validation checks +- Added `--entry-point` flag documentation requirements +- Added common issue: Wrong Boolean Flag Usage +- Updated Scenario 2 to verify boolean flag usage +- Added checks for `--entry-point` usage in partial analysis scenarios + +### Version 1.6 (2025-11-18) + +- Added constitution management commands integration +- Updated sync prompt to include constitution bootstrap/enrich/validate commands +- Added constitution bootstrap suggestion workflow for brownfield projects +- Updated prerequisites section to document constitution command options + +### Version 1.5 (2025-11-18) + +- Added auto-enrichment workflow validation for `plan review` command +- Added Scenario 4a: Plan Review with Auto-Enrichment +- Added checks for enrichment detection, execution, and refinement +- Added common issue: Missing Auto-Enrichment +- Updated flow logic section to include auto-enrichment workflow documentation requirements diff --git a/_site_test/prompts/README.md b/_site_test/prompts/README.md new file mode 100644 index 0000000..9e09cab --- /dev/null +++ b/_site_test/prompts/README.md @@ -0,0 +1,260 @@ +# Prompt Templates and Slash Commands Reference + +This directory contains documentation and tools for validating slash command prompts, as well as a reference for all available slash commands. + +--- + +## Slash Commands Reference + +SpecFact CLI provides slash commands that work with AI-assisted IDEs (Cursor, VS Code + Copilot, Claude Code, etc.). These commands enable a seamless workflow: **SpecFact finds gaps → AI IDE fixes them → SpecFact validates**. + +### Quick Start + +1. **Initialize IDE integration**: + + ```bash + specfact init --ide cursor + ``` + +2. **Use slash commands in your IDE**: + + ```bash + /specfact.01-import legacy-api --repo . + /specfact.03-review legacy-api + /specfact.05-enforce legacy-api + ``` + +**Related**: [AI IDE Workflow Guide](../guides/ai-ide-workflow.md) - Complete workflow guide + +--- + +### Core Workflow Commands + +#### `/specfact.01-import` + +**Purpose**: Import from codebase (brownfield modernization) + +**Equivalent CLI**: `specfact import from-code` + +**Example**: + +```bash +/specfact.01-import legacy-api --repo . +``` + +**Workflow**: [Brownfield Modernization Chain](../guides/command-chains.md#1-brownfield-modernization-chain) + +--- + +#### `/specfact.02-plan` + +**Purpose**: Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) + +**Equivalent CLI**: `specfact plan init/add-feature/add-story/update-idea/update-feature/update-story` + +**Example**: + +```bash +/specfact.02-plan init legacy-api +/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth" +``` + +**Workflow**: [Greenfield Planning Chain](../guides/command-chains.md#2-greenfield-planning-chain) + +--- + +#### `/specfact.03-review` + +**Purpose**: Review plan and promote + +**Equivalent CLI**: `specfact plan review` + +**Example**: + +```bash +/specfact.03-review legacy-api +``` + +**Workflow**: [Brownfield Modernization Chain](../guides/command-chains.md#1-brownfield-modernization-chain), [Greenfield Planning Chain](../guides/command-chains.md#2-greenfield-planning-chain) + +--- + +#### `/specfact.04-sdd` + +**Purpose**: Create SDD manifest + +**Equivalent CLI**: `specfact enforce sdd` + +**Example**: + +```bash +/specfact.04-sdd legacy-api +``` + +**Workflow**: [Brownfield Modernization Chain](../guides/command-chains.md#1-brownfield-modernization-chain) + +--- + +#### `/specfact.05-enforce` + +**Purpose**: SDD enforcement + +**Equivalent CLI**: `specfact enforce sdd` + +**Example**: + +```bash +/specfact.05-enforce legacy-api +``` + +**Workflow**: [Brownfield Modernization Chain](../guides/command-chains.md#1-brownfield-modernization-chain), [Plan Promotion & Release Chain](../guides/command-chains.md#5-plan-promotion--release-chain) + +--- + +#### `/specfact.06-sync` + +**Purpose**: Sync operations + +**Equivalent CLI**: `specfact sync bridge` + +**Example**: + +```bash +/specfact.06-sync --adapter speckit --repo . --bidirectional +``` + +**Workflow**: [External Tool Integration Chain](../guides/command-chains.md#3-external-tool-integration-chain) + +--- + +#### `/specfact.07-contracts` + +**Purpose**: Contract management (analyze, generate prompts, apply contracts sequentially) + +**Equivalent CLI**: `specfact generate contracts-prompt` + +**Example**: + +```bash +/specfact.07-contracts legacy-api --apply all-contracts +``` + +**Workflow**: [AI-Assisted Code Enhancement Chain](../guides/command-chains.md#7-ai-assisted-code-enhancement-chain-emerging) + +--- + +### Advanced Commands + +#### `/specfact.compare` + +**Purpose**: Compare plans + +**Equivalent CLI**: `specfact plan compare` + +**Example**: + +```bash +/specfact.compare --bundle legacy-api +``` + +**Workflow**: [Code-to-Plan Comparison Chain](../guides/command-chains.md#6-code-to-plan-comparison-chain) + +--- + +#### `/specfact.validate` + +**Purpose**: Validation suite + +**Equivalent CLI**: `specfact repro` + +**Example**: + +```bash +/specfact.validate --repo . +``` + +**Workflow**: [Brownfield Modernization Chain](../guides/command-chains.md#1-brownfield-modernization-chain), [Gap Discovery & Fixing Chain](../guides/command-chains.md#9-gap-discovery--fixing-chain-emerging) + +--- + +## Prompt Validation System + +This directory contains documentation and tools for validating slash command prompts to ensure they are correct, aligned with CLI commands, and provide good UX. + +## Quick Start + +### Run Automated Validation + +```bash +# Validate all prompts +hatch run validate-prompts + +# Or directly +python tools/validate_prompts.py +``` + +### Run Tests + +```bash +# Run prompt validation tests +hatch test tests/unit/prompts/test_prompt_validation.py -v +``` + +## What Gets Validated + +The automated validator checks: + +1. **Structure**: Required sections present (CLI Enforcement, Wait States, Goal, Operating Constraints) +2. **CLI Alignment**: CLI commands match actual CLI, enforcement rules present +3. **Wait States**: Wait state rules and markers present +4. **Dual-Stack Workflow**: Three-phase workflow for applicable commands +5. **Consistency**: Consistent formatting and structure across prompts + +## Validation Results + +All 8 prompts currently pass validation: + +- ✅ `specfact.01-import` (20 checks) - Import from codebase +- ✅ `specfact.02-plan` (15 checks) - Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) +- ✅ `specfact.03-review` (15 checks) - Review plan and promote +- ✅ `specfact.04-sdd` (15 checks) - Create SDD manifest +- ✅ `specfact.05-enforce` (15 checks) - SDD enforcement +- ✅ `specfact.06-sync` (15 checks) - Sync operations +- ✅ `specfact.compare` (15 checks) - Compare plans +- ✅ `specfact.validate` (15 checks) - Validation suite + +## Manual Review + +See [PROMPT_VALIDATION_CHECKLIST.md](./PROMPT_VALIDATION_CHECKLIST.md) for: + +- Detailed manual review checklist +- Testing scenarios with Copilot +- Common issues and fixes +- Continuous improvement process + +## Files + +- **`tools/validate_prompts.py`**: Automated validation tool +- **`tests/unit/prompts/test_prompt_validation.py`**: Unit tests for validator +- **`PROMPT_VALIDATION_CHECKLIST.md`**: Manual review checklist +- **`resources/prompts/`**: Prompt template files + +## Integration + +The validation tool is integrated into the development workflow: + +- **Pre-commit**: Run `hatch run validate-prompts` before committing prompt changes +- **CI/CD**: Add validation step to CI pipeline +- **Development**: Run validation after updating any prompt + +## Next Steps + +1. **Test with Copilot**: Use the manual checklist to test each prompt in real scenarios +2. **Document Issues**: Document any issues found during testing +3. **Improve Prompts**: Update prompts based on testing feedback +4. **Expand Validation**: Add more checks as patterns emerge + +--- + +**Last Updated**: 2025-12-02 (v0.11.4 - Active Plan Fallback, SDD Hash Stability) +**Version**: 1.1 diff --git a/_site_test/quick-examples/index.html b/_site_test/quick-examples/index.html new file mode 100644 index 0000000..4b69a95 --- /dev/null +++ b/_site_test/quick-examples/index.html @@ -0,0 +1,547 @@ + + + + + + + +Quick Examples | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Quick Examples

+ +

Quick code snippets for common SpecFact CLI tasks.

+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow (VS Code, Cursor, GitHub Actions, pre-commit hooks). No platform to learn, no vendor lock-in.

+ +

Installation

+ +
# Zero-install (no setup required) - CLI-only mode
+uvx specfact-cli@latest --help
+
+# Install with pip - Interactive AI Assistant mode
+pip install specfact-cli
+
+# Install in virtual environment
+python -m venv .venv
+source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
+pip install specfact-cli
+
+
+ +

Your First Command

+ +
# Starting a new project?
+specfact plan init my-project --interactive
+
+# Have existing code?
+specfact import from-code my-project --repo .
+
+# Using GitHub Spec-Kit?
+specfact import from-bridge --adapter speckit --repo ./my-project --dry-run
+
+
+ +

Import from Spec-Kit (via Bridge)

+ +
# Preview migration
+specfact import from-bridge --adapter speckit --repo ./spec-kit-project --dry-run
+
+# Execute migration
+specfact import from-bridge --adapter speckit --repo ./spec-kit-project --write
+
+
+ +

Import from Code

+ +
# Basic import (bundle name as positional argument)
+specfact import from-code my-project --repo .
+
+# With confidence threshold
+specfact import from-code my-project --repo . --confidence 0.7
+
+# Shadow mode (observe only)
+specfact import from-code my-project --repo . --shadow-only
+
+# CoPilot mode (enhanced prompts)
+specfact --mode copilot import from-code my-project --repo . --confidence 0.7
+
+
+ +

Plan Management

+ +
# Initialize plan (bundle name as positional argument)
+specfact plan init my-project --interactive
+
+# Add feature (bundle name via --bundle option)
+specfact plan add-feature \
+  --bundle my-project \
+  --key FEATURE-001 \
+  --title "User Authentication" \
+  --outcomes "Users can login securely"
+
+# Add story (bundle name via --bundle option)
+specfact plan add-story \
+  --bundle my-project \
+  --feature FEATURE-001 \
+  --title "As a user, I can login with email and password" \
+  --acceptance "Login form validates input"
+
+# Create hard SDD manifest (required for promotion)
+specfact plan harden my-project
+
+# Review plan (checks SDD automatically, bundle name as positional argument)
+specfact plan review my-project --max-questions 5
+
+# Promote plan (requires SDD for review+ stages)
+specfact plan promote my-project --stage review
+
+
+ +

Plan Comparison

+ +
# Quick comparison (auto-detects plans)
+specfact plan compare --repo .
+
+# Explicit comparison (bundle directory paths)
+specfact plan compare \
+  --manual .specfact/projects/manual-plan \
+  --auto .specfact/projects/auto-derived
+
+# Code vs plan comparison
+specfact plan compare --code-vs-plan --repo .
+
+
+ +

Sync Operations

+ +
# One-time Spec-Kit sync (via bridge adapter)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Watch mode (continuous sync)
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+# Repository sync
+specfact sync repository --repo . --target .specfact
+
+# Repository watch mode
+specfact sync repository --repo . --watch --interval 5
+
+
+ +

SDD (Spec-Driven Development) Workflow

+ +
# Create hard SDD manifest from plan
+specfact plan harden
+
+# Validate SDD manifest against plan
+specfact enforce sdd
+
+# Validate SDD with custom output format
+specfact enforce sdd --output-format json --out validation-report.json
+
+# Review plan (automatically checks SDD)
+specfact plan review --max-questions 5
+
+# Promote plan (requires SDD for review+ stages)
+specfact plan promote --stage review
+
+# Force promotion despite SDD validation failures
+specfact plan promote --stage review --force
+
+ +

Enforcement

+ +
# Shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# Balanced mode (block HIGH, warn MEDIUM)
+specfact enforce stage --preset balanced
+
+# Strict mode (block everything)
+specfact enforce stage --preset strict
+
+# Enforce SDD validation
+specfact enforce sdd
+
+
+ +

Validation

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Quick validation
+specfact repro
+
+# Verbose validation
+specfact repro --verbose
+
+# With budget
+specfact repro --verbose --budget 120
+
+# Apply auto-fixes
+specfact repro --fix --budget 120
+
+
+ +

IDE Integration

+ +
# Initialize Cursor integration
+specfact init --ide cursor
+
+# Initialize VS Code integration
+specfact init --ide vscode
+
+# Force reinitialize
+specfact init --ide cursor --force
+
+
+ +

Operational Modes

+ +
# Auto-detect mode (default)
+specfact import from-code my-project --repo .
+
+# Force CI/CD mode
+specfact --mode cicd import from-code my-project --repo .
+
+# Force CoPilot mode
+specfact --mode copilot import from-code my-project --repo .
+
+# Set via environment variable
+export SPECFACT_MODE=copilot
+specfact import from-code my-project --repo .
+
+ +

Common Workflows

+ +

Daily Development

+ +
# Morning: Check status
+specfact repro --verbose
+specfact plan compare --repo .
+
+# During development: Watch mode
+specfact sync repository --repo . --watch --interval 5
+
+# Before committing: Validate
+specfact repro
+specfact plan compare --repo .
+
+
+ +

Brownfield Modernization (Hard-SDD Workflow)

+ +
# Step 1: Extract specs from legacy code
+specfact import from-code my-project --repo .
+
+# Step 2: Create hard SDD manifest
+specfact plan harden my-project
+
+# Step 3: Validate SDD before starting work
+specfact enforce sdd my-project
+
+# Step 4: Review plan (checks SDD automatically)
+specfact plan review my-project --max-questions 5
+
+# Step 5: Promote plan (requires SDD for review+ stages)
+specfact plan promote my-project --stage review
+
+# Step 6: Add contracts to critical paths
+# ... (add @icontract decorators to code)
+
+# Step 7: Re-validate SDD after adding contracts
+specfact enforce sdd my-project
+
+# Step 8: Continue modernization with SDD safety net
+
+ +

Migration from Spec-Kit

+ +
# Step 1: Preview
+specfact import from-bridge --adapter speckit --repo . --dry-run
+
+# Step 2: Execute
+specfact import from-bridge --adapter speckit --repo . --write
+
+# Step 3: Set up sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+# Step 4: Enable enforcement
+specfact enforce stage --preset minimal
+
+
+ +

Brownfield Analysis

+ +
# Step 1: Analyze code
+specfact import from-code my-project --repo . --confidence 0.7
+
+# Step 2: Review plan using CLI commands
+specfact plan review my-project
+
+# Step 3: Compare with manual plan
+specfact plan compare --repo .
+
+# Step 4: Set up watch mode
+specfact sync repository --repo . --watch --interval 5
+
+ +

Advanced Examples

+ +

Bundle Name

+ +
# Bundle name is a positional argument (not --name option)
+specfact import from-code my-project --repo .
+
+
+ +

Custom Report

+ +
specfact import from-code \
+  --repo . \
+  --report analysis-report.md
+
+specfact plan compare \
+  --repo . \
+  --out comparison-report.md
+
+
+ +

Feature Key Format

+ +
# Classname format (default for auto-derived)
+specfact import from-code my-project --repo . --key-format classname
+
+# Sequential format (for manual plans)
+specfact import from-code my-project --repo . --key-format sequential
+
+
+ +

Confidence Threshold

+ +
# Lower threshold (more features, lower confidence)
+specfact import from-code my-project --repo . --confidence 0.3
+
+# Higher threshold (fewer features, higher confidence)
+specfact import from-code my-project --repo . --confidence 0.8
+
+ +

Integration Examples

+ + + + + + + +
+ +

Happy building! 🚀

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/redirects/index.json b/_site_test/redirects/index.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/_site_test/redirects/index.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/_site_test/reference/commands/index.html b/_site_test/reference/commands/index.html new file mode 100644 index 0000000..916c51e --- /dev/null +++ b/_site_test/reference/commands/index.html @@ -0,0 +1,5157 @@ + + + + + + + +Command Reference | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Command Reference

+ +

Complete reference for all SpecFact CLI commands.

+ +

Commands by Workflow

+ +

Quick Navigation: Find commands organized by workflow and command chain.

+ +

👉 Command Chains Reference ⭐ NEW - Complete workflows with decision trees and visual diagrams

+ +

Workflow Matrix

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WorkflowPrimary CommandsChain Reference
Brownfield Modernizationimport from-code, plan review, plan update-feature, enforce sdd, reproBrownfield Chain
Greenfield Planningplan init, plan add-feature, plan add-story, plan review, plan harden, generate contracts, enforce sddGreenfield Chain
External Tool Integrationimport from-bridge, plan review, sync bridge, enforce sddIntegration Chain
API Contract Developmentspec validate, spec backward-compat, spec generate-tests, spec mock, contract verifyAPI Chain
Plan Promotion & Releaseplan review, enforce sdd, plan promote, project version bumpPromotion Chain
Code-to-Plan Comparisonimport from-code, plan compare, drift detect, sync repositoryComparison Chain
AI-Assisted Enhancementgenerate contracts-prompt, contracts-apply, contract coverage, reproAI Enhancement Chain
Test Generationgenerate test-prompt, spec generate-tests, pytestTest Generation Chain
Gap Discovery & Fixingrepro --verbose, generate fix-prompt, enforce sddGap Discovery Chain
+ +

Not sure which workflow to use? → Command Chains Decision Tree

+ +
+ +

Quick Reference

+ +

Most Common Commands

+ +
# PRIMARY: Import from existing code (brownfield modernization)
+specfact import from-code --bundle legacy-api --repo .
+
+# SECONDARY: Import from external tools (Spec-Kit, Linear, Jira, etc.)
+specfact import from-bridge --repo . --adapter speckit --write
+
+# Initialize plan (alternative: greenfield workflow)
+specfact plan init --bundle legacy-api --interactive
+
+# Compare plans
+specfact plan compare --bundle legacy-api
+
+# Sync with external tools (bidirectional) - Secondary use case
+specfact sync bridge --adapter speckit --bundle legacy-api --bidirectional --watch
+
+# Set up CrossHair for contract exploration (one-time setup)
+specfact repro setup
+
+# Validate everything
+specfact repro --verbose
+
+ +

Global Flags

+ +
    +
  • --input-format {yaml,json} - Override default structured input detection for CLI commands (defaults to YAML)
    • +
  • --output-format {yaml,json} - Control how plan bundles and reports are written (JSON is ideal for CI/copilot automations)
    • +
  • --interactive/--no-interactive - Force prompt behavior (overrides auto-detection from CI/CD vs Copilot environments)
    • +
+ +

Commands by Workflow

+ +

Import & Analysis:

+ +
    +
  • import from-code ⭐ PRIMARY - Analyze existing codebase (brownfield modernization)
    • +
  • import from-bridge - Import from external tools via bridge architecture (Spec-Kit, Linear, Jira, etc.)
    • +
+ +

Plan Management:

+ +
    +
  • plan init --bundle <bundle-name> - Initialize new project bundle
    • +
  • plan add-feature --bundle <bundle-name> - Add feature to bundle
    • +
  • plan add-story --bundle <bundle-name> - Add story to feature
    • +
  • plan update-feature --bundle <bundle-name> - Update existing feature metadata
    • +
  • plan review --bundle <bundle-name> - Review plan bundle to resolve ambiguities
    • +
  • plan select - Select active plan from available bundles
    • +
  • plan upgrade - Upgrade plan bundles to latest schema version
    • +
  • plan compare - Compare plans (detect drift)
    • +
+ +

Project Bundle Management:

+ +
    +
  • project init-personas - Initialize persona definitions for team collaboration + +
    • +
  • project export --bundle <bundle-name> --persona <persona> - Export persona-specific Markdown artifacts + +
    • +
  • project import --bundle <bundle-name> --persona <persona> --source <file> - Import persona edits from Markdown + +
    • +
  • project lock --bundle <bundle-name> --section <section> --persona <persona> - Lock section for editing + +
    • +
  • project unlock --bundle <bundle-name> --section <section> - Unlock section after editing + +
    • +
  • project locks --bundle <bundle-name> - List all locked sections + +
    • +
  • project version check --bundle <bundle-name> - Recommend version bump (major/minor/patch/none) + +
    • +
  • project version bump --bundle <bundle-name> --type <major|minor|patch> - Apply SemVer bump and record history + +
    • +
  • project version set --bundle <bundle-name> --version <semver> - Set explicit project version and record history + +
    • +
  • CI/CD Integration: The GitHub Action template includes a configurable version check step with three modes: +
      +
    • info: Informational only, logs recommendations without failing CI
      • +
    • warn (default): Logs warnings but continues CI execution
      • +
    • block: Fails CI if version bump recommendation is not followed +Configure via version_check_mode input in workflow_dispatch or set SPECFACT_VERSION_CHECK_MODE environment variable.
      • +
    +
    • +
+ +

Enforcement:

+ + + +

AI IDE Bridge (v0.17+):

+ +
    +
  • generate fix-prompt ⭐ NEW - Generate AI IDE prompt to fix gaps
    • +
  • generate test-prompt ⭐ NEW - Generate AI IDE prompt to create tests
    • +
  • generate tasks - ⚠️ REMOVED in v0.22.0 - Use Spec-Kit, OpenSpec, or other SDD tools instead
    • +
  • generate contracts - Generate contract stubs from SDD
    • +
  • generate contracts-prompt - Generate AI IDE prompt for adding contracts
    • +
+ +

Synchronization:

+ + + +

API Specification Management:

+ + + +

Constitution Management (Spec-Kit Compatibility):

+ +
    +
  • sdd constitution bootstrap - Generate bootstrap constitution from repository analysis (for Spec-Kit format)
    • +
  • sdd constitution enrich - Auto-enrich existing constitution with repository context (for Spec-Kit format)
    • +
  • sdd constitution validate - Validate constitution completeness (for Spec-Kit format)
    • +
+ +

Note: The sdd constitution commands are for Spec-Kit compatibility only. SpecFact itself uses modular project bundles (.specfact/projects/<bundle-name>/) and protocols (.specfact/protocols/*.protocol.yaml) for internal operations. Constitutions are only needed when syncing with Spec-Kit artifacts or working in Spec-Kit format.

+ +

⚠️ Breaking Change: The specfact bridge constitution command has been moved to specfact sdd constitution as part of the bridge adapter refactoring. Please update your scripts and workflows.

+ +

Migration & Utilities:

+ +
    +
  • migrate cleanup-legacy - Remove empty legacy directories
    • +
  • migrate to-contracts - Migrate bundles to contract-centric structure
    • +
  • migrate artifacts - Migrate artifacts between bundle versions
    • +
  • sdd list - List all SDD manifests in repository
    • +
+ +

Setup:

+ +
    +
  • init - Initialize IDE integration
    • +
+ +

⚠️ Deprecated (v0.17.0):

+ +
    +
  • implement tasks - Use generate fix-prompt / generate test-prompt instead
    • +
+ +
+ +

Global Options

+ +
specfact [OPTIONS] COMMAND [ARGS]...
+
+ +

Global Options:

+ +
    +
  • --version, -v - Show version and exit
    • +
  • --help, -h - Show help message and exit
    • +
  • --help-advanced, -ha - Show all options including advanced configuration (progressive disclosure)
    • +
  • --no-banner - Hide ASCII art banner (useful for CI/CD)
    • +
  • --verbose - Enable verbose output
    • +
  • --quiet - Suppress non-error output
    • +
  • --mode {cicd|copilot} - Operational mode (default: auto-detect)
    • +
+ +

Mode Selection:

+ +
    +
  • cicd - CI/CD automation mode (fast, deterministic)
    • +
  • copilot - CoPilot-enabled mode (interactive, enhanced prompts)
    • +
  • Auto-detection: Checks CoPilot API availability and IDE integration
    • +
+ +

Boolean Flags:

+ +

Boolean flags in SpecFact CLI work differently from value flags:

+ +
    +
  • ✅ CORRECT: --flag (sets True) or --no-flag (sets False) or omit (uses default)
    • +
  • ❌ WRONG: --flag true or --flag false (Typer boolean flags don’t accept values)
    • +
+ +

Examples:

+ +
    +
  • --draft sets draft status to True
    • +
  • --no-draft sets draft status to False (when supported)
    • +
  • Omitting the flag leaves the value unchanged (if optional) or uses the default
    • +
+ +

Note: Some boolean flags support --no-flag syntax (e.g., --draft/--no-draft), while others are simple presence flags (e.g., --shadow-only). Check command help with specfact <command> --help for specific flag behavior.

+ +

Banner Display:

+ +

The CLI displays an ASCII art banner by default for brand recognition and visual appeal. The banner shows:

+ +
    +
  • When executing any command (unless --no-banner is specified)
    • +
  • With help output (--help or -h)
    • +
  • With version output (--version or -v)
    • +
+ +

To suppress the banner (useful for CI/CD or automated scripts):

+ +
specfact --no-banner <command>
+
+ +

Examples:

+ +
# Auto-detect mode (default)
+specfact import from-code --bundle legacy-api --repo .
+
+# Force CI/CD mode
+specfact --mode cicd import from-code --bundle legacy-api --repo .
+
+# Force CoPilot mode
+specfact --mode copilot import from-code --bundle legacy-api --repo .
+
+ +

Commands

+ +

import - Import from External Formats

+ +

Convert external project formats to SpecFact format.

+ +

import from-bridge

+ +

Convert external tool projects (Spec-Kit, Linear, Jira, etc.) to SpecFact format using the bridge architecture.

+ +
specfact import from-bridge [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository with external tool artifacts (required)
    • +
  • --dry-run - Preview changes without writing files
    • +
  • --write - Write converted files to repository
    • +
  • --out-branch NAME - Git branch for migration (default: feat/specfact-migration)
    • +
  • --report PATH - Write migration report to file
    • +
  • --force - Overwrite existing files
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --adapter ADAPTER - Adapter type: speckit, generic-markdown (default: auto-detect)
    • +
+ +

Example:

+ +
# Import from Spec-Kit
+specfact import from-bridge \
+  --repo ./my-speckit-project \
+  --adapter speckit \
+  --write \
+  --out-branch feat/specfact-migration \
+  --report migration-report.md
+
+# Auto-detect adapter
+specfact import from-bridge \
+  --repo ./my-project \
+  --write
+
+ +

What it does:

+ +
    +
  • Uses bridge configuration to detect external tool structure
    • +
  • For Spec-Kit: Detects .specify/ directory with markdown artifacts in specs/ folders
    • +
  • Parses tool-specific artifacts (e.g., specs/[###-feature-name]/spec.md, plan.md, tasks.md, .specify/memory/constitution.md for Spec-Kit)
    • +
  • Converts tool features/stories to SpecFact Pydantic models with contracts
    • +
  • Generates .specfact/protocols/workflow.protocol.yaml (if FSM detected)
    • +
  • Creates modular project bundle at .specfact/projects/<bundle-name>/ with features and stories
    • +
  • Adds Semgrep async anti-pattern rules (if async patterns detected)
    • +
+ +
+ +

import from-code

+ +

Import plan bundle from existing codebase (one-way import) using AI-first approach (CoPilot mode) or AST-based fallback (CI/CD mode).

+ +
specfact import from-code [OPTIONS]
+
+ +

Options:

+ +
    +
  • BUNDLE_NAME - Project bundle name (positional argument, required)
    • +
  • --repo PATH - Path to repository to import (required)
    • +
  • --output-format {yaml,json} - Override global output format for this command only (defaults to global flag)
    • +
  • --shadow-only - Observe without blocking
    • +
  • --report PATH - Write import report (default: bundle-specific .specfact/projects/<bundle-name>/reports/brownfield/analysis-<timestamp>.md, Phase 8.5)
    • +
  • --enrich-for-speckit/--no-enrich-for-speckit - Automatically enrich plan for Spec-Kit compliance using PlanEnricher (enhances vague acceptance criteria, incomplete requirements, generic tasks, and adds edge case stories for features with only 1 story). Default: enabled (same enrichment logic as plan review --auto-enrich)
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --confidence FLOAT - Minimum confidence score (0.0-1.0, default: 0.5)
    • +
  • --key-format {classname|sequential} - Feature key format (default: classname)
    • +
  • --entry-point PATH - Subdirectory path for partial analysis (relative to repo root). Analyzes only files within this directory and subdirectories. Useful for: +
      +
    • Multi-project repositories (monorepos): Analyze one project at a time (e.g., --entry-point projects/api-service)
      • +
    • Large codebases: Focus on specific modules or subsystems for faster analysis
      • +
    • Incremental modernization: Modernize one part of the codebase at a time
      • +
    • Example: --entry-point src/core analyzes only src/core/ and its subdirectories
      • +
    +
    • +
  • --enrichment PATH - Path to Markdown enrichment report from LLM (applies missing features, confidence adjustments, business context). The enrichment report must follow a specific format (see Dual-Stack Enrichment Guide for format requirements). When applied: +
      +
    • Missing features are added with their stories and acceptance criteria
      • +
    • Existing features are updated (confidence, outcomes, title if empty)
      • +
    • Stories are merged into existing features (new stories added, existing preserved)
      • +
    • Business context is applied to the plan bundle
      • +
    +
    • +
+ +

Note: The bundle name (positional argument) will be automatically sanitized (lowercased, spaces/special chars removed) for filesystem persistence. The bundle is created at .specfact/projects/<bundle-name>/.

+ +

Mode Behavior:

+ +
    +
  • +

    CoPilot Mode (AI-first - Pragmatic): Uses AI IDE’s native LLM (Cursor, CoPilot, etc.) for semantic understanding. The AI IDE understands the codebase semantically, then calls the SpecFact CLI for structured analysis. No separate LLM API setup needed. Multi-language support, high-quality Spec-Kit artifacts.

    +
    • +
  • +

    CI/CD Mode (AST+Semgrep Hybrid): Uses Python AST + Semgrep pattern detection for fast, deterministic analysis. Framework-aware detection (API endpoints, models, CRUD, code quality). Works offline, no LLM required. Displays plugin status (AST Analysis, Semgrep Pattern Detection, Dependency Graph Analysis).

    +
    • +
+ +

Pragmatic Integration:

+ +
    +
  • ✅ No separate LLM setup - Uses AI IDE’s existing LLM
    • +
  • ✅ No additional API costs - Leverages existing IDE infrastructure
    • +
  • ✅ Simpler architecture - No langchain, API keys, or complex integration
    • +
  • ✅ Better developer experience - Native IDE integration via slash commands
    • +
+ +

Note: The command automatically detects mode based on CoPilot API availability. Use --mode to override.

+ +
    +
  • --mode {cicd|copilot} - Operational mode (default: auto-detect)
    • +
+ +

Examples:

+ +
# Full repository analysis
+specfact import from-code --bundle legacy-api \
+  --repo ./my-project \
+  --confidence 0.7 \
+  --shadow-only \
+  --report reports/analysis.md
+
+# Partial analysis (analyze only specific subdirectory)
+specfact import from-code --bundle core-module \
+  --repo ./my-project \
+  --entry-point src/core \
+  --confidence 0.7
+
+# Multi-project codebase (analyze one project at a time)
+specfact import from-code --bundle api-service \
+  --repo ./monorepo \
+  --entry-point projects/api-service
+
+ +

What it does:

+ +
    +
  • AST Analysis: Extracts classes, methods, imports, docstrings
    • +
  • Semgrep Pattern Detection: Detects API endpoints, database models, CRUD operations, auth patterns, framework usage, code quality issues
    • +
  • Dependency Graph: Builds module dependency graph (when pyan3 and networkx available)
    • +
  • Evidence-Based Confidence Scoring: Systematically combines AST + Semgrep evidence for accurate confidence scores: +
      +
    • Framework patterns (API, models, CRUD) increase confidence
      • +
    • Test patterns increase confidence
      • +
    • Anti-patterns and security issues decrease confidence
      • +
    +
    • +
  • Code Quality Assessment: Identifies anti-patterns and security vulnerabilities
    • +
  • Plugin Status: Displays which analysis tools are enabled and used
    • +
  • Optimized Bundle Size: 81% reduction (18MB → 3.4MB, 5.3x smaller) via test pattern extraction to OpenAPI contracts
    • +
  • Acceptance Criteria: Limited to 1-3 high-level items per story, detailed examples in contract files
    • +
  • Interruptible: Press Ctrl+C during analysis to cancel immediately (all parallel operations support graceful cancellation)
    • +
  • Contract Extraction: Automatically extracts API contracts from function signatures, type hints, and validation logic: +
      +
    • Function parameters → Request schema (JSON Schema format)
      • +
    • Return types → Response schema
      • +
    • Validation logic → Preconditions and postconditions
      • +
    • Error handling → Error contracts
      • +
    • Contracts stored in Story.contracts field for runtime enforcement
      • +
    • Contracts included in Spec-Kit plan.md for Article IX compliance
      • +
    +
    • +
  • Test Pattern Extraction: Extracts test patterns from existing test files: +
      +
    • Parses pytest and unittest test functions
      • +
    • Converts test assertions to Given/When/Then acceptance criteria format
      • +
    • Maps test scenarios to user story scenarios
      • +
    +
    • +
  • Control Flow Analysis: Extracts scenarios from code control flow: +
      +
    • Primary scenarios (happy path)
      • +
    • Alternate scenarios (conditional branches)
      • +
    • Exception scenarios (error handling)
      • +
    • Recovery scenarios (retry logic)
      • +
    +
    • +
  • Requirement Extraction: Extracts complete requirements from code semantics: +
      +
    • Subject + Modal + Action + Object + Outcome format
      • +
    • Non-functional requirements (NFRs) from code patterns
      • +
    • Performance, security, reliability, maintainability patterns
      • +
    +
    • +
  • Generates plan bundle with enhanced confidence scores
    • +
+ +

Partial Repository Coverage:

+ +

The --entry-point parameter enables partial analysis of large codebases:

+ +
    +
  • Multi-project codebases: Analyze individual projects within a monorepo separately
    • +
  • Focused analysis: Analyze specific modules or subdirectories for faster feedback
    • +
  • Incremental modernization: Modernize one module at a time, creating separate plan bundles per module
    • +
  • Performance: Faster analysis when you only need to understand a subset of the codebase
    • +
+ +

Note on Multi-Project Codebases:

+ +

When working with multiple projects in a single repository, external tool integration (via sync bridge) may create artifacts at nested folder levels. For now, it’s recommended to:

+ +
    +
  • Use --entry-point to analyze each project separately
    • +
  • Create separate project bundles for each project (.specfact/projects/<bundle-name>/)
    • +
  • Run specfact init from the repository root to ensure IDE integration works correctly (templates are copied to root-level .github/, .cursor/, etc. directories)
    • +
+ +
+ +

plan - Manage Development Plans

+ +

Create and manage contract-driven development plans.

+ +
+

Plan commands respect both .bundle.yaml and .bundle.json. Use --output-format {yaml,json} (or the global specfact --output-format) to control serialization.

+
+ +

plan init

+ +

Initialize a new plan bundle:

+ +
specfact plan init [OPTIONS]
+
+ +

Options:

+ +
    +
  • --interactive/--no-interactive - Interactive mode with prompts (default: --interactive) +
      +
    • Use --no-interactive for CI/CD automation to avoid interactive prompts
      • +
    +
    • +
  • Bundle name is provided as a positional argument (e.g., plan init my-project)
    • +
  • --scaffold/--no-scaffold - Create complete .specfact/ directory structure (default: --scaffold)
    • +
  • --output-format {yaml,json} - Override global output format for this command only (defaults to global flag)
    • +
+ +

Example:

+ +
# Interactive mode (recommended for manual plan creation)
+specfact plan init --bundle legacy-api --interactive
+
+# Non-interactive mode (CI/CD automation)
+specfact plan init --bundle legacy-api --no-interactive
+
+# Interactive mode with different bundle
+specfact plan init --bundle feature-auth --interactive
+
+ +

plan add-feature

+ +

Add a feature to the plan:

+ +
specfact plan add-feature [OPTIONS]
+
+ +

Options:

+ +
    +
  • --key TEXT - Feature key (FEATURE-XXX) (required)
    • +
  • --title TEXT - Feature title (required)
    • +
  • --outcomes TEXT - Success outcomes (multiple allowed)
    • +
  • --acceptance TEXT - Acceptance criteria (multiple allowed)
    • +
  • --bundle TEXT - Bundle name (default: active bundle or main)
    • +
+ +

Example:

+ +
specfact plan add-feature \
+  --bundle legacy-api \
+  --key FEATURE-001 \
+  --title "Spec-Kit Import" \
+  --outcomes "Zero manual conversion" \
+  --acceptance "Given Spec-Kit repo, When import, Then bundle created"
+
+ +

plan add-story

+ +

Add a story to a feature:

+ +
specfact plan add-story [OPTIONS]
+
+ +

Options:

+ +
    +
  • --feature TEXT - Parent feature key (required)
    • +
  • --key TEXT - Story key (e.g., STORY-001) (required)
    • +
  • --title TEXT - Story title (required)
    • +
  • --acceptance TEXT - Acceptance criteria (comma-separated)
    • +
  • --story-points INT - Story points (complexity: 0-100)
    • +
  • --value-points INT - Value points (business value: 0-100)
    • +
  • --draft - Mark story as draft
    • +
  • --bundle TEXT - Bundle name (default: active bundle or main)
    • +
+ +

Example:

+ +
specfact plan add-story \
+  --bundle legacy-api \
+  --feature FEATURE-001 \
+  --key STORY-001 \
+  --title "Parse Spec-Kit artifacts" \
+  --acceptance "Schema validation passes"
+
+ +

plan update-feature

+ +

Update an existing feature’s metadata in a plan bundle:

+ +
specfact plan update-feature [OPTIONS]
+
+ +

Options:

+ +
    +
  • --key TEXT - Feature key to update (e.g., FEATURE-001) (required unless --batch-updates is provided)
    • +
  • --title TEXT - Feature title
    • +
  • --outcomes TEXT - Expected outcomes (comma-separated)
    • +
  • --acceptance TEXT - Acceptance criteria (comma-separated)
    • +
  • --constraints TEXT - Constraints (comma-separated)
    • +
  • --confidence FLOAT - Confidence score (0.0-1.0)
    • +
  • --draft/--no-draft - Mark as draft (use --draft to set True, --no-draft to set False, omit to leave unchanged) +
      +
    • Note: Boolean flags don’t accept values - use --draft (not --draft true) or --no-draft (not --draft false)
      • +
    +
    • +
  • --batch-updates PATH - Path to JSON/YAML file with multiple feature updates (preferred for bulk updates via Copilot LLM enrichment) +
      +
    • File format: List of objects with key and update fields (title, outcomes, acceptance, constraints, confidence, draft)
      • +
    • +

      Example file (updates.json):

      + + 
      [
+  {
+    "key": "FEATURE-001",
+    "title": "Updated Feature 1",
+    "outcomes": ["Outcome 1", "Outcome 2"],
+    "acceptance": ["Acceptance 1", "Acceptance 2"],
+    "confidence": 0.9
+  },
+  {
+    "key": "FEATURE-002",
+    "title": "Updated Feature 2",
+    "acceptance": ["Acceptance 3"],
+    "confidence": 0.85
+  }
+]
+
      +
      • +
    +
    • +
  • --bundle TEXT - Bundle name (default: active bundle or main)
    • +
+ +

Example:

+ +
# Single feature update
+specfact plan update-feature \
+  --bundle legacy-api \
+  --key FEATURE-001 \
+  --title "Updated Feature Title" \
+  --outcomes "Outcome 1, Outcome 2"
+
+# Update acceptance criteria and confidence
+specfact plan update-feature \
+  --bundle legacy-api \
+  --key FEATURE-001 \
+  --acceptance "Criterion 1, Criterion 2" \
+  --confidence 0.9
+
+# Batch updates from file (preferred for multiple features)
+specfact plan update-feature \
+  --bundle legacy-api \
+  --batch-updates updates.json
+
+# Batch updates with YAML format
+specfact plan update-feature \
+  --bundle main \
+  --batch-updates updates.yaml
+
+ +

Batch Update File Format:

+ +

The --batch-updates file must contain a list of update objects. Each object must have a key field and can include any combination of update fields:

+ +
[
+  {
+    "key": "FEATURE-001",
+    "title": "Updated Feature 1",
+    "outcomes": ["Outcome 1", "Outcome 2"],
+    "acceptance": ["Acceptance 1", "Acceptance 2"],
+    "constraints": ["Constraint 1"],
+    "confidence": 0.9,
+    "draft": false
+  },
+  {
+    "key": "FEATURE-002",
+    "title": "Updated Feature 2",
+    "acceptance": ["Acceptance 3"],
+    "confidence": 0.85
+  }
+]
+
+ +

When to Use Batch Updates:

+ +
    +
  • Multiple features need refinement: After plan review identifies multiple features with missing information
    • +
  • Copilot LLM enrichment: When LLM generates comprehensive updates for multiple features at once
    • +
  • Bulk acceptance criteria updates: When enhancing multiple features with specific file paths, method names, or component references
    • +
  • CI/CD automation: When applying multiple updates programmatically from external tools
    • +
+ +

What it does:

+ +
    +
  • Updates existing feature metadata (title, outcomes, acceptance criteria, constraints, confidence, draft status)
    • +
  • Works in CI/CD, Copilot, and interactive modes
    • +
  • Validates plan bundle structure after update
    • +
  • Preserves existing feature data (only updates specified fields)
    • +
+ +

Use cases:

+ +
    +
  • After enrichment: Update features added via enrichment that need metadata completion
    • +
  • CI/CD automation: Update features programmatically in non-interactive environments
    • +
  • Copilot mode: Update features without needing internal code knowledge
    • +
+ +

plan update-story

+ +

Update an existing story’s metadata in a plan bundle:

+ +
specfact plan update-story [OPTIONS]
+
+ +

Options:

+ +
    +
  • --feature TEXT - Parent feature key (e.g., FEATURE-001) (required unless --batch-updates is provided)
    • +
  • --key TEXT - Story key to update (e.g., STORY-001) (required unless --batch-updates is provided)
    • +
  • --title TEXT - Story title
    • +
  • --acceptance TEXT - Acceptance criteria (comma-separated)
    • +
  • --story-points INT - Story points (complexity: 0-100)
    • +
  • --value-points INT - Value points (business value: 0-100)
    • +
  • --confidence FLOAT - Confidence score (0.0-1.0)
    • +
  • --draft/--no-draft - Mark as draft (use --draft to set True, --no-draft to set False, omit to leave unchanged) +
      +
    • Note: Boolean flags don’t accept values - use --draft (not --draft true) or --no-draft (not --draft false)
      • +
    +
    • +
  • --batch-updates PATH - Path to JSON/YAML file with multiple story updates (preferred for bulk updates via Copilot LLM enrichment) +
      +
    • File format: List of objects with feature, key and update fields (title, acceptance, story_points, value_points, confidence, draft)
      • +
    • +

      Example file (story_updates.json):

      + + 
      [
+  {
+    "feature": "FEATURE-001",
+    "key": "STORY-001",
+    "title": "Updated Story 1",
+    "acceptance": ["Given X, When Y, Then Z"],
+    "story_points": 5,
+    "value_points": 3,
+    "confidence": 0.9
+  },
+  {
+    "feature": "FEATURE-002",
+    "key": "STORY-002",
+    "acceptance": ["Given A, When B, Then C"],
+    "confidence": 0.85
+  }
+]
+
      +
      • +
    +
    • +
  • --bundle TEXT - Bundle name (default: active bundle or main)
    • +
+ +

Example:

+ +
# Single story update
+specfact plan update-story \
+  --feature FEATURE-001 \
+  --key STORY-001 \
+  --title "Updated Story Title" \
+  --acceptance "Given X, When Y, Then Z"
+
+# Update story points and confidence
+specfact plan update-story \
+  --feature FEATURE-001 \
+  --key STORY-001 \
+  --story-points 5 \
+  --confidence 0.9
+
+# Batch updates from file (preferred for multiple stories)
+specfact plan update-story \
+  --bundle main \
+  --batch-updates story_updates.json
+
+# Batch updates with YAML format
+specfact plan update-story \
+  --bundle main \
+  --batch-updates story_updates.yaml
+
+ +

Batch Update File Format:

+ +

The --batch-updates file must contain a list of update objects. Each object must have feature and key fields and can include any combination of update fields:

+ +
[
+  {
+    "feature": "FEATURE-001",
+    "key": "STORY-001",
+    "title": "Updated Story 1",
+    "acceptance": ["Given X, When Y, Then Z"],
+    "story_points": 5,
+    "value_points": 3,
+    "confidence": 0.9,
+    "draft": false
+  },
+  {
+    "feature": "FEATURE-002",
+    "key": "STORY-002",
+    "acceptance": ["Given A, When B, Then C"],
+    "confidence": 0.85
+  }
+]
+
+ +

When to Use Batch Updates:

+ +
    +
  • Multiple stories need refinement: After plan review identifies multiple stories with missing information
    • +
  • Copilot LLM enrichment: When LLM generates comprehensive updates for multiple stories at once
    • +
  • Bulk acceptance criteria updates: When enhancing multiple stories with specific file paths, method names, or component references
    • +
  • CI/CD automation: When applying multiple updates programmatically from external tools
    • +
+ +

What it does:

+ +
    +
  • Updates existing story metadata (title, acceptance criteria, story points, value points, confidence, draft status)
    • +
  • Works in CI/CD, Copilot, and interactive modes
    • +
  • Validates plan bundle structure after update
    • +
  • Preserves existing story data (only updates specified fields)
    • +
+ +

plan review

+ +

Review plan bundle to identify and resolve ambiguities:

+ +
specfact plan review [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle TEXT - Project bundle name (required, e.g., legacy-api)
    • +
  • --list-questions - Output questions in JSON format without asking (for Copilot mode)
    • +
  • --output-questions PATH - Save questions directly to file (JSON format). Use with --list-questions to save instead of stdout. Default: None
    • +
  • --list-findings - Output all findings in structured format (JSON/YAML) or as table (interactive mode). Preferred for bulk updates via Copilot LLM enrichment
    • +
  • --output-findings PATH - Save findings directly to file (JSON/YAML format). Use with --list-findings to save instead of stdout. Default: None
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --auto-enrich - Automatically enrich vague acceptance criteria, incomplete requirements, and generic tasks using LLM-enhanced pattern matching
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --max-questions INT - Maximum questions per session (default: 5, max: 10)
    • +
  • --category TEXT - Focus on specific taxonomy category (optional)
    • +
  • --findings-format {json,yaml,table} - Output format for --list-findings (default: json for non-interactive, table for interactive)
    • +
  • --answers PATH|JSON - JSON file path or JSON string with question_id -> answer mappings (for non-interactive mode)
    • +
+ +

Modes:

+ +
    +
  • Interactive Mode: Asks questions one at a time, integrates answers immediately
    • +
  • Copilot Mode: Three-phase workflow: +
      +
    1. Get findings: specfact plan review --list-findings --findings-format json (preferred for bulk updates)
      2. +
    2. LLM enrichment: Analyze findings and generate batch update files
      3. +
    3. Apply updates: specfact plan update-feature --batch-updates <file> or specfact plan update-story --batch-updates <file>
      4. +
    +
    • +
  • Alternative Copilot Mode: Question-based workflow: +
      +
    1. Get questions: specfact plan review --list-questions
      2. +
    2. Ask user: LLM presents questions and collects answers
      3. +
    3. Feed answers: specfact plan review --answers <file>
      4. +
    +
    • +
  • CI/CD Mode: Use --no-interactive with --answers for automation
    • +
+ +

Example:

+ +
# Interactive review
+specfact plan review --bundle legacy-api
+
+# Get all findings for bulk updates (preferred for Copilot mode)
+specfact plan review --bundle legacy-api --list-findings --findings-format json
+
+# Save findings directly to file (clean JSON, no CLI banner)
+specfact plan review --bundle legacy-api --list-findings --output-findings /tmp/findings.json
+
+# Get findings as table (interactive mode)
+specfact plan review --bundle legacy-api --list-findings --findings-format table
+
+# Get questions for question-based workflow
+specfact plan review --bundle legacy-api --list-questions --max-questions 5
+
+# Save questions directly to file (clean JSON, no CLI banner)
+specfact plan review --bundle legacy-api --list-questions --output-questions /tmp/questions.json
+
+# Feed answers back (question-based workflow)
+specfact plan review --bundle legacy-api --answers answers.json
+
+# CI/CD automation
+specfact plan review --bundle legacy-api --no-interactive --answers answers.json
+
+ +

Findings Output Format:

+ +

The --list-findings option outputs all ambiguities and findings in a structured format:

+ +
{
+  "findings": [
+    {
+      "category": "Feature/Story Completeness",
+      "status": "Missing",
+      "description": "Feature FEATURE-001 has no stories",
+      "impact": 0.9,
+      "uncertainty": 0.8,
+      "priority": 0.72,
+      "question": "What stories should be added to FEATURE-001?",
+      "related_sections": ["features[0]"]
+    }
+  ],
+  "coverage": {
+    "Functional Scope & Behavior": "Missing",
+    "Feature/Story Completeness": "Missing"
+  },
+  "total_findings": 5,
+  "priority_score": 0.65
+}
+
+ +

Bulk Update Workflow (Recommended for Copilot Mode):

+ +
    +
  1. List findings: specfact plan review --list-findings --output-findings /tmp/findings.json (recommended - clean JSON) or specfact plan review --list-findings --findings-format json > findings.json (includes CLI banner)
    2. +
  2. LLM analyzes findings: Generate batch update files based on findings
    3. +
  3. Apply feature updates: specfact plan update-feature --batch-updates feature_updates.json
    4. +
  4. Apply story updates: specfact plan update-story --batch-updates story_updates.json
    5. +
  5. Verify: Run specfact plan review again to confirm improvements
    6. +
+ +

What it does:

+ +
    +
  1. Analyzes plan bundle for ambiguities using structured taxonomy (10 categories)
    2. +
  2. Identifies missing information, unclear requirements, and unknowns
    3. +
  3. Asks targeted questions (max 5 per session) to resolve ambiguities
    4. +
  4. Integrates answers back into plan bundle incrementally
    5. +
  5. Validates plan bundle structure after each update
    6. +
  6. Reports coverage summary and promotion readiness
    7. +
+ +

Taxonomy Categories:

+ +
    +
  • Functional Scope & Behavior
    • +
  • Domain & Data Model
    • +
  • Interaction & UX Flow
    • +
  • Non-Functional Quality Attributes
    • +
  • Integration & External Dependencies
    • +
  • Edge Cases & Failure Handling
    • +
  • Constraints & Tradeoffs
    • +
  • Terminology & Consistency
    • +
  • Completion Signals
    • +
  • Feature/Story Completeness
    • +
+ +

Answers Format:

+ +

The --answers parameter accepts either a JSON file path or JSON string:

+ +
{
+  "Q001": "Answer for question 1",
+  "Q002": "Answer for question 2"
+}
+
+ +

Integration Points:

+ +

Answers are integrated into plan bundle sections based on category:

+ +
    +
  • Functional ambiguity → features[].acceptance[] or idea.narrative
    • +
  • Data model → features[].constraints[]
    • +
  • Non-functional → features[].constraints[] or idea.constraints[]
    • +
  • Edge cases → features[].acceptance[] or stories[].acceptance[]
    • +
+ +

SDD Integration:

+ +

When an SDD manifest (.specfact/projects/<bundle-name>/sdd.yaml, Phase 8.5) is present, plan review automatically:

+ +
    +
  • Validates SDD manifest against the plan bundle (hash match, coverage thresholds)
    • +
  • Displays contract density metrics: +
      +
    • Contracts per story (compared to threshold)
      • +
    • Invariants per feature (compared to threshold)
      • +
    • Architecture facets (compared to threshold)
      • +
    +
    • +
  • Reports coverage threshold warnings if metrics are below thresholds
    • +
  • Suggests running specfact enforce sdd for detailed validation report
    • +
+ +

Example Output with SDD:

+ +
✓ SDD manifest validated successfully
+
+Contract Density Metrics:
+  Contracts/story: 1.50 (threshold: 1.0)
+  Invariants/feature: 2.00 (threshold: 1.0)
+  Architecture facets: 3 (threshold: 3)
+
+Found 0 coverage threshold warning(s)
+
+ +

Output:

+ +
    +
  • Questions asked count
    • +
  • Sections touched (integration points)
    • +
  • Coverage summary (per category status)
    • +
  • Contract density metrics (if SDD present)
    • +
  • Next steps (promotion readiness)
    • +
+ +

plan harden

+ +

Create or update SDD manifest (hard spec) from plan bundle:

+ +
specfact plan harden [OPTIONS]
+
+ +

Options:

+ +
    +
  • Bundle name is provided as a positional argument (e.g., plan harden my-project)
    • +
  • --sdd PATH - Output SDD manifest path (default: bundle-specific .specfact/projects/<bundle-name>/sdd.<format>, Phase 8.5)
    • +
  • --output-format {yaml,json} - SDD manifest format (defaults to global --output-format)
    • +
  • --interactive/--no-interactive - Interactive mode with prompts (default: interactive)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
+ +

What it does:

+ +
    +
  1. Loads plan bundle and computes content hash
    2. +
  2. Extracts SDD sections from plan bundle: +
      +
    • WHY: Intent, constraints, target users, value hypothesis (from idea section)
      • +
    • WHAT: Capabilities, acceptance criteria, out-of-scope (from features section)
      • +
    • HOW: Architecture, invariants, contracts, module boundaries (from features and stories)
      • +
    +
    3. +
  3. Creates SDD manifest with: +
      +
    • Plan bundle linkage (hash and ID)
      • +
    • Coverage thresholds (contracts per story, invariants per feature, architecture facets)
      • +
    • Enforcement budgets (shadow, warn, block time limits)
      • +
    • Promotion status (from plan bundle stage)
      • +
    +
    4. +
  4. Saves plan bundle with updated hash (ensures hash persists for subsequent commands)
    5. +
  5. Saves SDD manifest to .specfact/projects/<bundle-name>/sdd.<format> (bundle-specific, Phase 8.5)
    6. +
+ +

Important Notes:

+ +
    +
  • SDD-Plan Linkage: SDD manifests are linked to specific plan bundles via hash
    • +
  • Multiple Plans: Each bundle has its own SDD manifest in .specfact/projects/<bundle-name>/sdd.yaml (Phase 8.5)
    • +
  • Hash Persistence: Plan bundle is automatically saved with updated hash to ensure consistency
    • +
+ +

Example:

+ +
# Interactive with active plan
+specfact plan harden --bundle legacy-api
+
+# Non-interactive with specific bundle
+specfact plan harden --bundle legacy-api --no-interactive
+
+# Custom SDD path for multiple bundles
+specfact plan harden --bundle feature-auth  # SDD saved to .specfact/projects/feature-auth/sdd.yaml
+
+ +

SDD Manifest Structure:

+ +

The generated SDD manifest includes:

+ +
    +
  • version: Schema version (1.0.0)
    • +
  • plan_bundle_id: First 16 characters of plan hash
    • +
  • plan_bundle_hash: Full plan bundle content hash
    • +
  • why: Intent, constraints, target users, value hypothesis
    • +
  • what: Capabilities, acceptance criteria, out-of-scope
    • +
  • how: Architecture description, invariants, contracts, module boundaries
    • +
  • coverage_thresholds: Minimum contracts/story, invariants/feature, architecture facets
    • +
  • enforcement_budget: Time budgets for shadow/warn/block enforcement levels
    • +
  • promotion_status: Current plan bundle stage
    • +
+ +

plan promote

+ +

Promote a plan bundle through development stages with quality gate validation:

+ +
specfact plan promote <bundle-name> [OPTIONS]
+
+ +

Arguments:

+ +
    +
  • <bundle-name> - Project bundle name (required, positional argument, e.g., legacy-api)
    • +
+ +

Options:

+ +
    +
  • --stage TEXT - Target stage (draft, review, approved, released) (required)
    • +
  • --validate/--no-validate - Run validation before promotion (default: true)
    • +
  • --force - Force promotion even if validation fails (default: false)
    • +
+ +

Stages:

+ +
    +
  • draft: Initial state - can be modified freely
    • +
  • review: Plan is ready for review - should be stable
    • +
  • approved: Plan approved for implementation
    • +
  • released: Plan released and should be immutable
    • +
+ +

Example:

+ +
# Promote to review stage
+specfact plan promote legacy-api --stage review
+
+# Promote to approved with validation
+specfact plan promote legacy-api --stage approved --validate
+
+# Force promotion (bypasses validation)
+specfact plan promote legacy-api --stage released --force
+
+ +

What it does:

+ +
    +
  1. Validates promotion rules: +
      +
    • Draft → Review: All features must have at least one story
      • +
    • Review → Approved: All features and stories must have acceptance criteria
      • +
    • Approved → Released: Implementation verification (future check)
      • +
    +
    2. +
  2. Checks coverage status (when --validate is enabled): +
      +
    • Critical categories (block promotion if Missing): +
        +
      • Functional Scope & Behavior
        • +
      • Feature/Story Completeness
        • +
      • Constraints & Tradeoffs
        • +
      +
      • +
    • Important categories (warn if Missing or Partial): +
        +
      • Domain & Data Model
        • +
      • Integration & External Dependencies
        • +
      • Non-Functional Quality Attributes
        • +
      +
      • +
    +
    3. +
  3. +

    Updates metadata: Sets stage, promoted_at timestamp, and promoted_by user

    +
    4. +
  4. Saves plan bundle with updated metadata
    5. +
+ +

Coverage Validation:

+ +

The promotion command now validates coverage status to ensure plans are complete before promotion:

+ +
    +
  • Blocks promotion if critical categories are Missing (unless --force)
    • +
  • Warns and prompts if important categories are Missing or Partial (unless --force)
    • +
  • Suggests running specfact plan review to resolve missing categories
    • +
+ +

Validation Errors:

+ +

If promotion fails due to validation:

+ +
❌ Cannot promote to review: 1 critical category(ies) are Missing
+Missing critical categories:
+  - Constraints & Tradeoffs
+
+Run 'specfact plan review' to resolve these ambiguities
+
+ +

Use --force to bypass (not recommended):

+ +
specfact plan promote legacy-api --stage review --force
+
+ +

Next Steps:

+ +

After successful promotion, the CLI suggests next actions:

+ +
    +
  • draft → review: Review plan bundle, add stories if missing
    • +
  • review → approved: Plan is ready for implementation
    • +
  • approved → released: Plan is released and should be immutable
    • +
+ +

plan select

+ +

Select active plan from available plan bundles:

+ +
specfact plan select [PLAN] [OPTIONS]
+
+ +

Arguments:

+ +
    +
  • PLAN - Plan name or number to select (optional, for interactive selection)
    • +
+ +

Options:

+ +
    +
  • PLAN - Plan name or number to select (optional, for interactive selection)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation). Disables interactive prompts. Requires exactly one plan to match filters.
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --current - Show only the currently active plan (auto-selects in non-interactive mode)
    • +
  • --stages STAGES - Filter by stages (comma-separated: draft,review,approved,released)
    • +
  • --last N - Show last N plans by modification time (most recent first)
    • +
  • --name NAME - Select plan by exact filename (non-interactive, e.g., main.bundle.yaml)
    • +
  • --id HASH - Select plan by content hash ID (non-interactive, from metadata.summary.content_hash)
    • +
+ +

Example:

+ +
# Interactive selection (displays numbered list)
+specfact plan select
+
+# Select by number
+specfact plan select 1
+
+# Select by name
+specfact plan select main.bundle.yaml
+
+# Show only active plan
+specfact plan select --current
+
+# Filter by stages
+specfact plan select --stages draft,review
+
+# Show last 5 plans
+specfact plan select --last 5
+
+# CI/CD: Get active plan without prompts (auto-selects)
+specfact plan select --no-interactive --current
+
+# CI/CD: Get most recent plan without prompts
+specfact plan select --no-interactive --last 1
+
+# CI/CD: Select by exact filename
+specfact plan select --name main.bundle.yaml
+
+# CI/CD: Select by content hash ID
+specfact plan select --id abc123def456
+
+ +

What it does:

+ +
    +
  • Lists all available plan bundles in .specfact/projects/ with metadata (features, stories, stage, modified date)
    • +
  • Displays numbered list with active plan indicator
    • +
  • Applies filters (current, stages, last N) before display/selection
    • +
  • Updates .specfact/config.yaml to set the active bundle (Phase 8.5: migrated from .specfact/plans/config.yaml)
    • +
  • The active plan becomes the default for all commands with --bundle option: +
      +
    • Plan management: plan compare, plan promote, plan add-feature, plan add-story, plan update-idea, plan update-feature, plan update-story, plan review
      • +
    • Analysis & generation: import from-code, generate contracts, analyze contracts
      • +
    • Synchronization: sync bridge, sync intelligent
      • +
    • Enforcement & migration: enforce sdd, migrate to-contracts, drift detect
      • +
    + +

    Use --bundle <name> to override the active plan for any command.

    +
    • +
+ +

Filter Options:

+ +
    +
  • --current: Filters to show only the currently active plan. In non-interactive mode, automatically selects the active plan without prompts.
    • +
  • --stages: Filters plans by stage (e.g., --stages draft,review shows only draft and review plans)
    • +
  • --last N: Shows the N most recently modified plans (sorted by modification time, most recent first)
    • +
  • --name NAME: Selects plan by exact filename (non-interactive). Useful for CI/CD when you know the exact plan name.
    • +
  • --id HASH: Selects plan by content hash ID from metadata.summary.content_hash (non-interactive). Supports full hash or first 8 characters.
    • +
  • --no-interactive: Disables interactive prompts. If multiple plans match filters, command will error. Use with --current, --last 1, --name, or --id for single plan selection in CI/CD.
    • +
+ +

Performance Notes:

+ +

The plan select command uses optimized metadata reading for fast performance, especially with large plan bundles:

+ +
    +
  • Plan bundles include summary metadata (features count, stories count, content hash) at the top of the file
    • +
  • For large files (>10MB), only the metadata section is read (first 50KB)
    • +
  • This provides 44% faster performance compared to full file parsing
    • +
  • Summary metadata is automatically added when creating or upgrading plan bundles
    • +
+ +

Note: Project bundles are stored in .specfact/projects/<bundle-name>/. All plan commands (compare, promote, add-feature, add-story) use the bundle name specified via --bundle option or positional arguments.

+ +

plan sync

+ +

Enable shared plans for team collaboration (convenience wrapper for sync bridge --adapter speckit --bidirectional):

+ +
specfact plan sync --shared [OPTIONS]
+
+ +

Options:

+ +
    +
  • --shared - Enable shared plans (bidirectional sync for team collaboration)
    • +
  • --watch - Watch mode for continuous sync (monitors file changes in real-time)
    • +
  • --interval INT - Watch interval in seconds (default: 5, minimum: 1)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
  • --bundle BUNDLE_NAME - Project bundle name for SpecFact → tool conversion (default: auto-detect)
    • +
  • --overwrite - Overwrite existing tool artifacts (delete all existing before sync)
    • +
+ +

Shared Plans for Team Collaboration:

+ +

The plan sync --shared command is a convenience wrapper around sync bridge --adapter speckit --bidirectional that emphasizes team collaboration. Shared structured plans enable multiple developers to work on the same plan with automated bidirectional sync. Unlike Spec-Kit’s manual markdown sharing, SpecFact automatically keeps plans synchronized across team members.

+ +

Example:

+ +
# One-time shared plans sync
+specfact plan sync --shared
+
+# Continuous watch mode (recommended for team collaboration)
+specfact plan sync --shared --watch --interval 5
+
+# Sync specific repository and bundle
+specfact plan sync --shared --repo ./project --bundle my-project
+
+# Equivalent direct command:
+specfact sync bridge --adapter speckit --repo . --bundle my-project --bidirectional --watch
+
+ +

What it syncs:

+ +
    +
  • Tool → SpecFact: New spec.md, plan.md, tasks.md → Updated .specfact/projects/<bundle-name>/bundle.yaml
    • +
  • SpecFact → Tool: Changes to .specfact/projects/<bundle-name>/bundle.yaml → Updated tool markdown (preserves structure)
    • +
  • Team collaboration: Multiple developers can work on the same plan with automated synchronization
    • +
+ +

Note: This is a convenience wrapper. The underlying command is sync bridge --adapter speckit --bidirectional. See sync bridge for full details.

+ +

plan upgrade

+ +

Upgrade plan bundles to the latest schema version:

+ +
specfact plan upgrade [OPTIONS]
+
+ +

Options:

+ +
    +
  • --plan PATH - Path to specific plan bundle to upgrade (default: active plan from specfact plan select)
    • +
  • --all - Upgrade all project bundles in .specfact/projects/
    • +
  • --dry-run - Show what would be upgraded without making changes
    • +
+ +

Example:

+ +
# Preview what would be upgraded (active plan)
+specfact plan upgrade --dry-run
+
+# Upgrade active plan (uses bundle selected via `specfact plan select`)
+specfact plan upgrade
+
+# Upgrade specific plan by path
+specfact plan upgrade --plan .specfact/projects/my-project/bundle.manifest.yaml
+
+# Upgrade all plans
+specfact plan upgrade --all
+
+# Preview all upgrades
+specfact plan upgrade --all --dry-run
+
+ +

What it does:

+ +
    +
  • Detects plan bundles with older schema versions or missing summary metadata
    • +
  • Migrates plan bundles from older versions to the current version (1.1)
    • +
  • Adds summary metadata (features count, stories count, content hash) for performance optimization
    • +
  • Preserves all existing plan data while adding new fields
    • +
  • Updates plan bundle version to current schema version
    • +
+ +

Schema Versions:

+ +
    +
  • Version 1.0: Initial schema (no summary metadata)
    • +
  • Version 1.1: Added summary metadata for fast access without full parsing
    • +
+ +

When to use:

+ +
    +
  • After upgrading SpecFact CLI to a version with new schema features
    • +
  • When you notice slow performance with plan select (indicates missing summary metadata)
    • +
  • Before running batch operations on multiple plan bundles
    • +
  • As part of repository maintenance to ensure all plans are up to date
    • +
+ +

Migration Details:

+ +

The upgrade process:

+ +
    +
  1. Detects schema version from plan bundle’s version field
    2. +
  2. Checks for missing summary metadata (backward compatibility)
    3. +
  3. Applies migrations in sequence (supports multi-step migrations)
    4. +
  4. Computes and adds summary metadata with content hash for integrity verification
    5. +
  5. Updates plan bundle file with new schema version
    6. +
+ +

Active Plan Detection:

+ +

When no --plan option is provided, the command automatically uses the active bundle set via specfact plan select. If no active bundle is set, it falls back to the first available bundle in .specfact/projects/ and provides a helpful tip to set it as active.

+ +

Backward Compatibility:

+ +
    +
  • Older bundles (schema 1.0) missing the product field are automatically upgraded with default empty product structure
    • +
  • Missing required fields are provided with sensible defaults during migration
    • +
  • Upgraded plan bundles are backward compatible. Older CLI versions can still read them, but won’t benefit from performance optimizations
    • +
+ +

plan compare

+ +

Compare manual and auto-derived plans to detect code vs plan drift:

+ +
specfact plan compare [OPTIONS]
+
+ +

Options:

+ +
    +
  • --manual PATH - Manual plan bundle directory (intended design - what you planned) (default: active bundle from .specfact/projects/<bundle-name>/ or main)
    • +
  • --auto PATH - Auto-derived plan bundle directory (actual implementation - what’s in your code from import from-code) (default: latest in .specfact/projects/)
    • +
  • --code-vs-plan - Convenience alias for --manual <active-plan> --auto <latest-auto-plan> (detects code vs plan drift)
    • +
  • --output-format TEXT - Output format (markdown, json, yaml) (default: markdown)
    • +
  • --out PATH - Output file (default: bundle-specific .specfact/projects/<bundle-name>/reports/comparison/report-*.md, Phase 8.5, or global .specfact/reports/comparison/ if no bundle context)
    • +
  • --mode {cicd|copilot} - Operational mode (default: auto-detect)
    • +
+ +

Code vs Plan Drift Detection:

+ +

The --code-vs-plan flag is a convenience alias that compares your intended design (manual plan) with actual implementation (code-derived plan from import from-code). Auto-derived plans come from code analysis, so this comparison IS “code vs plan drift” - detecting deviations between what you planned and what’s actually in your code.

+ +

Example:

+ +
# Detect code vs plan drift (convenience alias)
+specfact plan compare --code-vs-plan
+# → Compares intended design (manual plan) vs actual implementation (code-derived plan)
+# → Auto-derived plans come from `import from-code` (code analysis), so comparison IS "code vs plan drift"
+
+# Explicit comparison (bundle directory paths)
+specfact plan compare \
+  --manual .specfact/projects/main \
+  --auto .specfact/projects/my-project-auto \
+  --output-format markdown \
+  --out .specfact/projects/<bundle-name>/reports/comparison/deviation.md
+
+ +

Output includes:

+ +
    +
  • Missing features (in manual but not in auto - planned but not implemented)
    • +
  • Extra features (in auto but not in manual - implemented but not planned)
    • +
  • Mismatched stories
    • +
  • Confidence scores
    • +
  • Deviation severity
    • +
+ +

How it differs from Spec-Kit: Spec-Kit’s /speckit.analyze only checks artifact consistency between markdown files; SpecFact CLI detects actual code vs plan drift by comparing manual plans (intended design) with code-derived plans (actual implementation from code analysis).

+ +
+ +

project - Project Bundle Management

+ +

Manage project bundles with persona-based workflows for agile/scrum teams.

+ +

project export

+ +

Export persona-specific sections from project bundle to Markdown for editing.

+ +
specfact project export [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --persona PERSONA - Persona name: product-owner, developer, or architect (required)
    • +
  • --output PATH - Output file path (default: docs/project-plans/<bundle>/<persona>.md)
    • +
  • --output-dir PATH - Output directory (default: docs/project-plans/<bundle>)
    • +
  • --stdout - Output to stdout instead of file
    • +
  • --template TEMPLATE - Custom template name (default: uses persona-specific template)
    • +
  • --list-personas - List all available personas and exit
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Export Product Owner view
+specfact project export --bundle my-project --persona product-owner
+
+# Export Developer view
+specfact project export --bundle my-project --persona developer
+
+# Export Architect view
+specfact project export --bundle my-project --persona architect
+
+# Export to custom location
+specfact project export --bundle my-project --persona product-owner --output docs/backlog.md
+
+# Output to stdout (for piping/CI)
+specfact project export --bundle my-project --persona product-owner --stdout
+
+ +

What it exports:

+ +

Product Owner Export:

+ +
    +
  • Definition of Ready (DoR) checklist for each story
    • +
  • Prioritization data (priority, rank, business value scores)
    • +
  • Dependencies (story-to-story, feature-to-feature)
    • +
  • Business value descriptions and metrics
    • +
  • Sprint planning data (target dates, sprints, releases)
    • +
+ +

Developer Export:

+ +
    +
  • Acceptance criteria for features and stories
    • +
  • User stories with detailed context
    • +
  • Implementation tasks with file paths
    • +
  • API contracts and test scenarios
    • +
  • Code mappings (source and test functions)
    • +
  • Sprint context (story points, priority, dependencies)
    • +
  • Definition of Done checklist
    • +
+ +

Architect Export:

+ +
    +
  • Technical constraints per feature
    • +
  • Architectural decisions (technology choices, patterns)
    • +
  • Non-functional requirements (performance, scalability, security)
    • +
  • Protocols & state machines (complete definitions)
    • +
  • Contracts (OpenAPI/AsyncAPI details)
    • +
  • Risk assessment and mitigation strategies
    • +
  • Deployment architecture
    • +
+ +

See: Agile/Scrum Workflows Guide for detailed persona workflow documentation.

+ +

project import

+ +

Import persona edits from Markdown back into project bundle.

+ +
specfact project import [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --persona PERSONA - Persona name: product-owner, developer, or architect (required)
    • +
  • --source PATH - Source Markdown file (required)
    • +
  • --dry-run - Validate without applying changes
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Import Product Owner edits
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md
+
+# Import Developer edits
+specfact project import --bundle my-project --persona developer --source docs/developer.md
+
+# Import Architect edits
+specfact project import --bundle my-project --persona architect --source docs/architect.md
+
+# Dry-run to validate without applying
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md --dry-run
+
+ +

What it validates:

+ +
    +
  • Template Structure: Required sections present
    • +
  • DoR Completeness: All Definition of Ready criteria met
    • +
  • Dependency Integrity: No circular dependencies, all references exist
    • +
  • Priority Consistency: Valid priority formats (P0-P3, MoSCoW)
    • +
  • Date Formats: ISO 8601 date validation
    • +
  • Story Point Ranges: Valid Fibonacci-like values
    • +
+ +

See: Agile/Scrum Workflows Guide for detailed validation rules and examples.

+ +

project merge

+ +

Merge project bundles using three-way merge with persona-aware conflict resolution.

+ +
specfact project merge [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --base BRANCH_OR_COMMIT - Base branch/commit (common ancestor, required)
    • +
  • --ours BRANCH_OR_COMMIT - Our branch/commit (current branch, required)
    • +
  • --theirs BRANCH_OR_COMMIT - Their branch/commit (incoming branch, required)
    • +
  • --persona-ours PERSONA - Persona who made our changes (e.g., product-owner, required)
    • +
  • --persona-theirs PERSONA - Persona who made their changes (e.g., architect, required)
    • +
  • --output PATH - Output directory for merged bundle (default: current bundle directory)
    • +
  • --strategy STRATEGY - Merge strategy: auto (persona-based), ours, theirs, base, manual (default: auto)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Merge with automatic persona-based resolution
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours po-branch \
+  --theirs arch-branch \
+  --persona-ours product-owner \
+  --persona-theirs architect
+
+# Merge with manual strategy
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours feature-1 \
+  --theirs feature-2 \
+  --persona-ours developer \
+  --persona-theirs developer \
+  --strategy manual
+
+# Non-interactive merge (for CI/CD)
+specfact project merge \
+  --bundle my-project \
+  --base main \
+  --ours HEAD \
+  --theirs origin/feature \
+  --persona-ours product-owner \
+  --persona-theirs architect \
+  --no-interactive
+
+ +

How it works:

+ +
    +
  1. Loads three versions: Base (common ancestor), ours (current branch), and theirs (incoming branch)
    2. +
  2. Detects conflicts: Compares all three versions to find conflicting changes
    3. +
  3. Resolves automatically: Uses persona ownership rules to auto-resolve conflicts: +
      +
    • If only one persona owns the conflicting section → that persona’s version wins
      • +
    • If both personas own it and they’re the same → ours wins
      • +
    • If both personas own it and they’re different → requires manual resolution
      • +
    +
    4. +
  4. Interactive resolution: For unresolved conflicts, prompts you to choose: +
      +
    • ours - Keep our version
      • +
    • theirs - Keep their version
      • +
    • base - Keep base version
      • +
    • manual - Enter custom value
      • +
    +
    5. +
  5. Saves merged bundle: Writes the resolved bundle to the output directory
    6. +
+ +

Merge Strategies:

+ +
    +
  • auto (default): Persona-based automatic resolution
    • +
  • ours: Always prefer our version for conflicts
    • +
  • theirs: Always prefer their version for conflicts
    • +
  • base: Always prefer base version for conflicts
    • +
  • manual: Require manual resolution for all conflicts
    • +
+ +

See: Conflict Resolution Workflows for detailed workflow examples.

+ +

project resolve-conflict

+ +

Resolve a specific conflict in a project bundle after a merge operation.

+ +
specfact project resolve-conflict [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --path CONFLICT_PATH - Conflict path (e.g., features.FEATURE-001.title, required)
    • +
  • --resolution RESOLUTION - Resolution: ours, theirs, base, or manual value (required)
    • +
  • --persona PERSONA - Persona resolving the conflict (for ownership validation, optional)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Resolve conflict by keeping our version
+specfact project resolve-conflict \
+  --bundle my-project \
+  --path features.FEATURE-001.title \
+  --resolution ours
+
+# Resolve conflict by keeping their version
+specfact project resolve-conflict \
+  --bundle my-project \
+  --path idea.intent \
+  --resolution theirs \
+  --persona product-owner
+
+# Resolve conflict with manual value
+specfact project resolve-conflict \
+  --bundle my-project \
+  --path features.FEATURE-001.title \
+  --resolution "Custom Feature Title"
+
+ +

Conflict Path Format:

+ +
    +
  • idea.title - Idea title
    • +
  • idea.intent - Idea intent
    • +
  • business.value_proposition - Business value proposition
    • +
  • product.themes - Product themes (list)
    • +
  • features.FEATURE-001.title - Feature title
    • +
  • features.FEATURE-001.stories.STORY-001.description - Story description
    • +
+ +

Note: This command is a helper for resolving individual conflicts after a merge. For full merge operations, use project merge.

+ +

See: Conflict Resolution Workflows for detailed workflow examples.

+ +

project lock

+ +

Lock a section for a persona to prevent concurrent edits.

+ +
specfact project lock [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --section SECTION - Section pattern to lock (e.g., idea, features.*.stories, required)
    • +
  • --persona PERSONA - Persona name (e.g., product-owner, architect, required)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Lock idea section for product owner
+specfact project lock --bundle my-project --section idea --persona product-owner
+
+# Lock all feature stories for product owner
+specfact project lock --bundle my-project --section "features.*.stories" --persona product-owner
+
+# Lock protocols for architect
+specfact project lock --bundle my-project --section protocols --persona architect
+
+ +

How it works:

+ +
    +
  1. Validates ownership: Checks that the persona owns the section (based on manifest)
    2. +
  2. Checks existing locks: Fails if section is already locked
    3. +
  3. Creates lock: Adds lock to bundle manifest with timestamp and user info
    4. +
  4. Saves bundle: Updates bundle manifest with lock information
    5. +
+ +

Lock Enforcement: Once locked, only the locking persona (or unlock command) can modify the section. Import operations will be blocked if attempting to edit a locked section owned by a different persona.

+ +

See: Section Locking for detailed workflow examples.

+ +

project unlock

+ +

Unlock a section to allow edits by any persona that owns it.

+ +
specfact project unlock [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --section SECTION - Section pattern to unlock (e.g., idea, features.*.stories, required)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Unlock idea section
+specfact project unlock --bundle my-project --section idea
+
+# Unlock all feature stories
+specfact project unlock --bundle my-project --section "features.*.stories"
+
+ +

How it works:

+ +
    +
  1. Finds lock: Searches for matching lock in bundle manifest
    2. +
  2. Removes lock: Removes lock from manifest
    3. +
  3. Saves bundle: Updates bundle manifest
    4. +
+ +

Note: Unlock doesn’t require a persona parameter - anyone can unlock a section (coordination is expected at team level).

+ +

See: Section Locking for detailed workflow examples.

+ +

project locks

+ +

List all current section locks in a project bundle.

+ +
specfact project locks [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# List all locks
+specfact project locks --bundle my-project
+
+ +

Output Format:

+ +

Displays a table with:

+ +
    +
  • Section: Section pattern that’s locked
    • +
  • Owner: Persona who locked the section
    • +
  • Locked At: ISO 8601 timestamp when lock was created
    • +
  • Locked By: User@hostname who created the lock
    • +
+ +

Use Cases:

+ +
    +
  • Check what’s locked before starting work
    • +
  • Coordinate with team members about lock usage
    • +
  • Identify stale locks that need cleanup
    • +
+ +

See: Section Locking for detailed workflow examples.

+ +
+ +

project init-personas

+ +

Initialize personas in project bundle manifest for persona-based workflows.

+ +
specfact project init-personas [OPTIONS]
+
+ +

Purpose:

+ +

Adds default persona mappings to the bundle manifest if they are missing. Useful for migrating existing bundles to use persona workflows or setting up new bundles for team collaboration.

+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name. If not specified, attempts to auto-detect or prompt.
    • +
  • --persona PERSONA - Specific persona(s) to initialize (can be repeated). If not specified, initializes all default personas.
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Default Personas:

+ +

When no specific personas are specified, the following default personas are initialized:

+ +
    +
  • product-owner: Owns idea, features metadata, and stories acceptance criteria
    • +
  • architect: Owns contracts, protocols, and technical constraints
    • +
  • developer: Owns implementation details, file paths, and technical stories
    • +
+ +

Examples:

+ +
# Initialize all default personas
+specfact project init-personas --bundle legacy-api
+
+# Initialize specific personas only
+specfact project init-personas --bundle legacy-api --persona product-owner --persona architect
+
+# Non-interactive mode for CI/CD
+specfact project init-personas --bundle legacy-api --no-interactive
+
+ +

When to Use:

+ +
    +
  • After creating a new bundle with plan init
    • +
  • When migrating existing bundles to persona workflows
    • +
  • When adding new team members with specific roles
    • +
  • Before using project export/import persona commands
    • +
+ +
+ +

project version check

+ +

Check if a version bump is recommended based on bundle changes.

+ +
specfact project version check [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Output:

+ +

Returns a recommendation (major, minor, patch, or none) based on:

+ +
    +
  • major: Breaking changes detected (API contracts modified, features removed)
    • +
  • minor: New features added, stories added
    • +
  • patch: Bug fixes, documentation changes, story updates
    • +
  • none: No significant changes detected
    • +
+ +

Examples:

+ +
# Check version bump recommendation
+specfact project version check --bundle legacy-api
+
+ +

CI/CD Integration:

+ +

Configure behavior via SPECFACT_VERSION_CHECK_MODE environment variable:

+ +
    +
  • info: Informational only, logs recommendations
    • +
  • warn (default): Logs warnings but continues
    • +
  • block: Fails CI if recommendation is not followed
    • +
+ +
+ +

project version bump

+ +

Apply a SemVer version bump to the project bundle.

+ +
specfact project version bump [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --type TYPE - Bump type: major, minor, patch (required)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Bump minor version (e.g., 1.0.0 → 1.1.0)
+specfact project version bump --bundle legacy-api --type minor
+
+# Bump patch version (e.g., 1.1.0 → 1.1.1)
+specfact project version bump --bundle legacy-api --type patch
+
+ +

What it does:

+ +
    +
  1. Reads current version from bundle manifest
    2. +
  2. Applies SemVer bump based on type
    3. +
  3. Records version history with timestamp
    4. +
  4. Updates bundle hash
    5. +
+ +
+ +

project version set

+ +

Set an explicit version for the project bundle.

+ +
specfact project version set [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --version VERSION - SemVer version string (e.g., 2.0.0, 1.5.0-beta.1)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Set explicit version
+specfact project version set --bundle legacy-api --version 2.0.0
+
+# Set pre-release version
+specfact project version set --bundle legacy-api --version 1.5.0-beta.1
+
+ +

Use Cases:

+ +
    +
  • Initial version setup for new bundles
    • +
  • Aligning with external version requirements
    • +
  • Setting pre-release or build metadata versions
    • +
+ +
+ +

contract - OpenAPI Contract Management

+ +

Manage OpenAPI contracts for project bundles, including initialization, validation, mock server generation, and test generation.

+ +

contract init

+ +

Initialize OpenAPI contract for a feature.

+ +
specfact contract init [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --feature FEATURE_KEY - Feature key (e.g., FEATURE-001, required)
    • +
  • --title TITLE - API title (default: feature title)
    • +
  • --version VERSION - API version (default: 1.0.0)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Initialize contract for a feature
+specfact contract init --bundle legacy-api --feature FEATURE-001
+
+# Initialize with custom title and version
+specfact contract init --bundle legacy-api --feature FEATURE-001 --title "Authentication API" --version 1.0.0
+
+ +

What it does:

+ +
    +
  1. Creates OpenAPI 3.0.3 contract stub in contracts/FEATURE-001.openapi.yaml
    2. +
  2. Links contract to feature in bundle manifest
    3. +
  3. Updates contract index in manifest for fast lookup
    4. +
+ +

Note: Defaults to OpenAPI 3.0.3 for Specmatic compatibility. Validation accepts both 3.0.x and 3.1.x for forward compatibility.

+ +

contract validate

+ +

Validate OpenAPI contract schema.

+ +
specfact contract validate [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --feature FEATURE_KEY - Feature key (optional, validates all contracts if not specified)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Validate specific feature contract
+specfact contract validate --bundle legacy-api --feature FEATURE-001
+
+# Validate all contracts in bundle
+specfact contract validate --bundle legacy-api
+
+ +

What it does:

+ +
    +
  1. Loads OpenAPI contract(s) from bundle
    2. +
  2. Validates schema structure (supports both 3.0.x and 3.1.x)
    3. +
  3. Reports validation results with endpoint counts
    4. +
+ +

Note: For comprehensive validation including Specmatic, use specfact spec validate.

+ +

contract verify

+ +

Verify OpenAPI contract - validate, generate examples, and test mock server. This is a convenience command that combines multiple steps into one.

+ +
specfact contract verify [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --feature FEATURE_KEY - Feature key (optional, verifies all contracts if not specified)
    • +
  • --port PORT - Port number for mock server (default: 9000)
    • +
  • --skip-mock - Skip mock server startup (only validate contract)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Verify a specific contract (validates, generates examples, starts mock server)
+specfact contract verify --bundle legacy-api --feature FEATURE-001
+
+# Verify all contracts in a bundle
+specfact contract verify --bundle legacy-api
+
+# Verify without starting mock server (CI/CD)
+specfact contract verify --bundle legacy-api --feature FEATURE-001 --skip-mock --no-interactive
+
+ +

What it does:

+ +
    +
  1. Step 1: Validates contracts - Checks OpenAPI schema structure
    2. +
  2. Step 2: Generates examples - Creates example JSON files from contract schema
    3. +
  3. Step 3: Starts mock server - Launches Specmatic mock server (unless --skip-mock)
    4. +
  4. Step 4: Tests connectivity - Verifies mock server is responding
    5. +
+ +

Output:

+ +
Step 1: Validating contracts...
+✓ FEATURE-001: Valid (13 endpoints)
+
+Step 2: Generating examples...
+✓ FEATURE-001: Examples generated
+
+Step 3: Starting mock server for FEATURE-001...
+✓ Mock server started at http://localhost:9000
+
+Step 4: Testing connectivity...
+✓ Health check passed: UP
+
+✓ Contract verification complete!
+
+Summary:
+  • Contracts validated: 1
+  • Examples generated: 1
+  • Mock server: http://localhost:9000
+
+ +

When to use:

+ +
    +
  • Quick verification - One command to verify everything works
    • +
  • Development - Start mock server and verify contract is correct
    • +
  • CI/CD - Use --skip-mock --no-interactive for fast validation
    • +
  • Multiple contracts - Verify all contracts in a bundle at once
    • +
+ +

Note: This is the recommended command for most use cases. It combines validation, example generation, and mock server testing into a single, simple workflow.

+ +

contract serve

+ +

Start mock server for OpenAPI contract.

+ +
specfact contract serve [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --feature FEATURE_KEY - Feature key (optional, prompts for selection if multiple contracts)
    • +
  • --port PORT - Port number for mock server (default: 9000)
    • +
  • --strict/--examples - Use strict validation mode or examples mode (default: strict)
    • +
  • --no-interactive - Non-interactive mode (uses first contract if multiple available)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Start mock server for specific feature contract
+specfact contract serve --bundle legacy-api --feature FEATURE-001
+
+# Start mock server on custom port with examples mode
+specfact contract serve --bundle legacy-api --feature FEATURE-001 --port 8080 --examples
+
+ +

What it does:

+ +
    +
  1. Loads OpenAPI contract from bundle
    2. +
  2. Launches Specmatic mock server
    3. +
  3. Serves API endpoints based on contract
    4. +
  4. Validates requests against spec
    5. +
  5. Returns example responses
    6. +
+ +

Requirements: Specmatic must be installed (npm install -g @specmatic/specmatic)

+ +
+

Press Ctrl+C to stop the server

+
+ +

contract test

+ +

Generate contract tests from OpenAPI contract.

+ +
specfact contract test [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --feature FEATURE_KEY - Feature key (optional, generates tests for all contracts if not specified)
    • +
  • --output PATH - Output directory for generated tests (default: bundle-specific .specfact/projects/<bundle-name>/tests/contracts/)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Generate tests for specific feature contract
+specfact contract test --bundle legacy-api --feature FEATURE-001
+
+# Generate tests for all contracts in bundle
+specfact contract test --bundle legacy-api
+
+# Generate tests to custom output directory
+specfact contract test --bundle legacy-api --output tests/contracts/
+
+ +

What it does:

+ +
    +
  1. Loads OpenAPI contract(s) from bundle
    2. +
  2. Generates Specmatic test suite(s) using specmatic generate-tests
    3. +
  3. Saves tests to bundle-specific or custom output directory
    4. +
  4. Creates feature-specific test directories for organization
    5. +
+ +

Requirements: Specmatic must be installed (npm install -g @specmatic/specmatic)

+ +

Output Structure:

+ +
.specfact/projects/<bundle-name>/tests/contracts/
+├── feature-001/
+│   └── [Specmatic-generated test files]
+├── feature-002/
+│   └── [Specmatic-generated test files]
+└── ...
+
+ +

contract coverage

+ +

Calculate contract coverage for a project bundle.

+ +
specfact contract coverage [OPTIONS]
+
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name (required, or auto-detect)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# Get coverage report for bundle
+specfact contract coverage --bundle legacy-api
+
+ +

What it does:

+ +
    +
  1. Loads all features from bundle
    2. +
  2. Checks which features have contracts
    3. +
  3. Calculates coverage percentage (features with contracts / total features)
    4. +
  4. Counts total API endpoints across all contracts
    5. +
  5. Displays coverage table with status indicators
    6. +
+ +

Output:

+ +
    +
  • Coverage table showing feature, contract file, endpoint count, and status
    • +
  • Coverage summary with percentage and total endpoints
    • +
  • Warning if coverage is below 100%
    • +
+ +

See: Specmatic Integration Guide for detailed contract testing workflow.

+ +
+ +

enforce - Configure Quality Gates

+ +

Set contract enforcement policies.

+ +

enforce sdd

+ +

Validate SDD manifest against plan bundle and contracts:

+ +
specfact enforce sdd [OPTIONS]
+
+ +

Options:

+ +
    +
  • Bundle name is provided as a positional argument (e.g., plan harden my-project)
    • +
  • --sdd PATH - SDD manifest path (default: bundle-specific .specfact/projects/<bundle-name>/sdd.<format>, Phase 8.5)
    • +
  • --output-format {markdown,json,yaml} - Output format (default: markdown)
    • +
  • --out PATH - Output report path (optional)
    • +
+ +

What it validates:

+ +
    +
  1. Hash Match: Verifies SDD manifest is linked to the correct plan bundle
    2. +
  2. Coverage Thresholds: Validates contract density metrics: +
      +
    • Contracts per story (must meet threshold)
      • +
    • Invariants per feature (must meet threshold)
      • +
    • Architecture facets (must meet threshold)
      • +
    +
    3. +
  3. SDD Structure: Validates SDD manifest schema and completeness
    4. +
+ +

Contract Density Metrics:

+ +

The command calculates and validates:

+ +
    +
  • Contracts per story: Total contracts divided by total stories
    • +
  • Invariants per feature: Total invariants divided by total features
    • +
  • Architecture facets: Number of architecture-related constraints
    • +
+ +

Example:

+ +
# Validate SDD against active plan
+specfact enforce sdd
+
+# Validate with specific bundle and SDD (bundle name as positional argument)
+specfact enforce sdd main  # Uses .specfact/projects/main/sdd.yaml (Phase 8.5)
+
+# Generate JSON report
+specfact enforce sdd --output-format json --out validation-report.json
+
+ +

Output:

+ +
    +
  • Validation status (pass/fail)
    • +
  • Contract density metrics with threshold comparisons
    • +
  • Deviations report with severity levels (HIGH/MEDIUM/LOW)
    • +
  • Fix hints for each deviation
    • +
+ +

Deviations:

+ +

The command reports deviations when:

+ +
    +
  • Hash mismatch (SDD linked to different plan)
    • +
  • Contracts per story below threshold
    • +
  • Invariants per feature below threshold
    • +
  • Architecture facets below threshold
    • +
+ +

Integration:

+ +
    +
  • Automatically called by plan review when SDD is present
    • +
  • Required for plan promote to “review” or higher stages
    • +
  • Part of standard SDD enforcement workflow
    • +
+ +

enforce stage

+ +

Configure enforcement stage:

+ +
specfact enforce stage [OPTIONS]
+
+ +

Options:

+ +
    +
  • --preset TEXT - Enforcement preset (minimal, balanced, strict) (required)
    • +
  • --config PATH - Enforcement config file
    • +
+ +

Presets:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PresetHIGH SeverityMEDIUM SeverityLOW Severity
minimalLog onlyLog onlyLog only
balancedBlockWarnLog only
strictBlockBlockWarn
+ +

Example:

+ +
# Start with minimal
+specfact enforce stage --preset minimal
+
+# Move to balanced after stabilization
+specfact enforce stage --preset balanced
+
+# Strict for production
+specfact enforce stage --preset strict
+
+ +
+ +

drift - Detect Drift Between Code and Specifications

+ +

Detect misalignment between code and specifications.

+ +

drift detect

+ +

Detect drift between code and specifications.

+ +
specfact drift detect [BUNDLE] [OPTIONS]
+
+ +

Arguments:

+ +
    +
  • BUNDLE - Project bundle name (e.g., legacy-api). Default: active plan from specfact plan select
    • +
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository. Default: current directory (.)
    • +
  • --format {table,json,yaml} - Output format. Default: table
    • +
  • --out PATH - Output file path (for JSON/YAML format). Default: stdout
    • +
+ +

What it detects:

+ +
    +
  • Added code - Files with no spec (untracked implementation files)
    • +
  • Removed code - Deleted files but spec still exists
    • +
  • Modified code - Files with hash changed (implementation modified)
    • +
  • Orphaned specs - Specifications with no source tracking (no linked code)
    • +
  • Test coverage gaps - Stories missing test functions
    • +
  • Contract violations - Implementation doesn’t match contract (requires Specmatic)
    • +
+ +

Examples:

+ +
# Detect drift for active plan
+specfact drift detect
+
+# Detect drift for specific bundle
+specfact drift detect legacy-api --repo .
+
+# Output to JSON file
+specfact drift detect my-bundle --format json --out drift-report.json
+
+# Output to YAML file
+specfact drift detect my-bundle --format yaml --out drift-report.yaml
+
+ +

Output Formats:

+ +
    +
  • Table (default) - Rich formatted table with color-coded sections
    • +
  • JSON - Machine-readable JSON format for CI/CD integration
    • +
  • YAML - Human-readable YAML format
    • +
+ +

Integration:

+ +

The drift detection command integrates with:

+ +
    +
  • Source tracking (hash-based change detection)
    • +
  • Project bundles (feature and story tracking)
    • +
  • Specmatic (contract validation, if available)
    • +
+ +

See also:

+ +
    +
  • plan compare - Compare plans to detect code vs plan drift
    • +
  • sync intelligent - Continuous sync with drift detection
    • +
+ +
+ +

repro - Reproducibility Validation

+ +

Run full validation suite for reproducibility.

+ +
specfact repro [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: current directory)
    • +
  • --verbose - Show detailed output
    • +
  • --fix - Apply auto-fixes where available (Semgrep auto-fixes)
    • +
  • --fail-fast - Stop on first failure
    • +
  • --out PATH - Output report path (default: bundle-specific .specfact/projects/<bundle-name>/reports/enforcement/report-<timestamp>.yaml, Phase 8.5, or global .specfact/reports/enforcement/ if no bundle context)
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --budget INT - Time budget in seconds (default: 120)
    • +
+ +

Subcommands:

+ +
    +
  • repro setup - Set up CrossHair configuration for contract exploration +
      +
    • Automatically generates [tool.crosshair] configuration in pyproject.toml
      • +
    • Detects source directories and environment manager
      • +
    • Checks for crosshair-tool availability
      • +
    • Provides installation guidance if needed
      • +
    +
    • +
+ +

Example:

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Standard validation (current directory)
+specfact repro --verbose --budget 120
+
+# Validate external repository
+specfact repro --repo /path/to/external/repo --verbose
+
+# Apply auto-fixes for violations
+specfact repro --fix --budget 120
+
+# Stop on first failure
+specfact repro --fail-fast
+
+ +

What it runs:

+ +
    +
  1. Lint checks - ruff, semgrep async rules
    2. +
  2. Type checking - mypy/basedpyright
    3. +
  3. Contract exploration - CrossHair
    4. +
  4. Property tests - Hypothesis
    5. +
  5. Smoke tests - Event loop lag, orphaned tasks
    6. +
  6. Plan validation - Schema compliance
    7. +
+ +

External Repository Support:

+ +

The repro command automatically detects the target repository’s environment manager and adapts commands accordingly:

+ +
    +
  • Environment Detection: Automatically detects hatch, poetry, uv, or pip-based projects
    • +
  • Tool Availability: All tools are optional - missing tools are skipped with clear messages
    • +
  • Source Detection: Automatically detects source directories (src/, lib/, or package name from pyproject.toml)
    • +
  • Cross-Repository: Works on external repositories without requiring SpecFact CLI adoption
    • +
+ +

Supported Environment Managers:

+ +

SpecFact CLI automatically detects and works with the following project management tools:

+ +
    +
  • hatch - Detected from [tool.hatch] in pyproject.toml +
      +
    • Commands prefixed with: hatch run
      • +
    • Example: hatch run pytest tests/
      • +
    +
    • +
  • poetry - Detected from [tool.poetry] in pyproject.toml or poetry.lock +
      +
    • Commands prefixed with: poetry run
      • +
    • Example: poetry run pytest tests/
      • +
    +
    • +
  • uv - Detected from [tool.uv] in pyproject.toml, uv.lock, or uv.toml +
      +
    • Commands prefixed with: uv run
      • +
    • Example: uv run pytest tests/
      • +
    +
    • +
  • pip - Detected from requirements.txt or setup.py (uses direct tool invocation) +
      +
    • Commands use: Direct tool invocation (no prefix)
      • +
    • Example: pytest tests/
      • +
    +
    • +
+ +

Detection Priority:

+ +
    +
  1. Checks pyproject.toml for tool sections ([tool.hatch], [tool.poetry], [tool.uv])
    2. +
  2. Checks for lock files (poetry.lock, uv.lock, uv.toml)
    3. +
  3. Falls back to requirements.txt or setup.py for pip-based projects
    4. +
+ +

Source Directory Detection:

+ +
    +
  • Automatically detects: src/, lib/, or package name from pyproject.toml
    • +
  • Works with any project structure without manual configuration
    • +
+ +

Tool Requirements:

+ +

Tools are checked for availability and skipped if not found:

+ +
    +
  • ruff - Optional, for linting
    • +
  • semgrep - Optional, only runs if tools/semgrep/async.yml config exists
    • +
  • basedpyright - Optional, for type checking
    • +
  • crosshair - Optional, for contract exploration (requires [tool.crosshair] config in pyproject.toml - use specfact repro setup to generate)
    • +
  • pytest - Optional, only runs if tests/contracts/ or tests/smoke/ directories exist
    • +
+ +

Auto-fixes:

+ +

When using --fix, Semgrep will automatically apply fixes for violations that have fix: fields in the rules. For example, blocking-sleep-in-async rule will automatically replace time.sleep(...) with asyncio.sleep(...) in async functions.

+ +

Exit codes:

+ +
    +
  • 0 - All checks passed
    • +
  • 1 - Validation failed
    • +
  • 2 - Budget exceeded
    • +
+ +

Report Format:

+ +

Reports are written as YAML files to .specfact/projects/<bundle-name>/reports/enforcement/report-<timestamp>.yaml (bundle-specific, Phase 8.5). Each report includes:

+ +

Summary Statistics:

+ +
    +
  • total_duration - Total time taken (seconds)
    • +
  • total_checks - Number of checks executed
    • +
  • passed_checks, failed_checks, timeout_checks, skipped_checks - Status counts
    • +
  • budget_exceeded - Whether time budget was exceeded
    • +
+ +

Check Details:

+ +
    +
  • checks - List of check results with: +
      +
    • name - Human-readable check name
      • +
    • tool - Tool used (ruff, semgrep, basedpyright, crosshair, pytest)
      • +
    • status - Check status (passed, failed, timeout, skipped)
      • +
    • duration - Time taken (seconds)
      • +
    • exit_code - Tool exit code
      • +
    • timeout - Whether check timed out
      • +
    • output_length - Length of output (truncated in report)
      • +
    • error_length - Length of error output (truncated in report)
      • +
    +
    • +
+ +

Metadata (Context):

+ +
    +
  • timestamp - When the report was generated (ISO format)
    • +
  • repo_path - Repository path (absolute)
    • +
  • budget - Time budget used (seconds)
    • +
  • active_plan_path - Active plan bundle path (relative to repo, if exists)
    • +
  • enforcement_config_path - Enforcement config path (relative to repo, if exists)
    • +
  • enforcement_preset - Enforcement preset used (minimal, balanced, strict, if config exists)
    • +
  • fix_enabled - Whether --fix flag was used (true/false)
    • +
  • fail_fast - Whether --fail-fast flag was used (true/false)
    • +
+ +

Example Report:

+ +
total_duration: 89.09
+total_checks: 4
+passed_checks: 1
+failed_checks: 2
+timeout_checks: 1
+skipped_checks: 0
+budget_exceeded: false
+checks:
+  - name: Linting (ruff)
+    tool: ruff
+    status: failed
+    duration: 0.03
+    exit_code: 1
+    timeout: false
+    output_length: 39324
+    error_length: 0
+  - name: Async patterns (semgrep)
+    tool: semgrep
+    status: passed
+    duration: 0.21
+    exit_code: 0
+    timeout: false
+    output_length: 0
+    error_length: 164
+metadata:
+  timestamp: '2025-11-06T00:43:42.062620'
+  repo_path: /home/user/my-project
+  budget: 120
+  active_plan_path: .specfact/projects/main/
+  enforcement_config_path: .specfact/gates/config/enforcement.yaml
+  enforcement_preset: balanced
+  fix_enabled: false
+  fail_fast: false
+
+ +
+ +

generate - Generate Artifacts

+ +

Generate contract stubs and other artifacts from SDD manifests.

+ +

generate contracts

+ +

Generate contract stubs from SDD manifest:

+ +
specfact generate contracts [OPTIONS]
+
+ +

Options:

+ +
    +
  • Bundle name is provided as a positional argument (e.g., plan harden my-project)
    • +
  • --sdd PATH - SDD manifest path (default: bundle-specific .specfact/projects/<bundle-name>/sdd.<format>, Phase 8.5)
    • +
  • --out PATH - Output directory (default: .specfact/contracts/)
    • +
  • --output-format {yaml,json} - SDD manifest format (default: auto-detect)
    • +
+ +

What it generates:

+ +
    +
  1. Contract stubs with icontract decorators: +
      +
    • Preconditions (@require)
      • +
    • Postconditions (@ensure)
      • +
    • Invariants (@invariant)
      • +
    +
    2. +
  2. Type checking with beartype decorators
    3. +
  3. CrossHair harnesses for property-based testing
    4. +
  4. One file per feature/story in .specfact/contracts/
    5. +
+ +

Validation:

+ +
    +
  • Hash match: Verifies SDD manifest is linked to the correct plan bundle
    • +
  • Plan bundle hash: Must match SDD manifest’s plan_bundle_hash
    • +
  • Error handling: Reports hash mismatch with clear error message
    • +
+ +

Example:

+ +
# Generate contracts from active plan and SDD
+specfact generate contracts
+
+# Generate with specific bundle and SDD (bundle name as positional argument)
+specfact generate contracts --bundle main  # Uses .specfact/projects/main/sdd.yaml (Phase 8.5)
+
+# Custom output directory
+specfact generate contracts --out src/contracts/
+
+ +

Workflow:

+ +
    +
  1. Create SDD: specfact plan harden (creates SDD manifest and saves plan with hash)
    2. +
  2. Generate contracts: specfact generate contracts (validates hash match, generates stubs)
    3. +
  3. Implement contracts: Add contract logic to generated stubs
    4. +
  4. Enforce: specfact enforce sdd (validates contract density)
    5. +
+ +

Important Notes:

+ +
    +
  • Hash validation: Command validates that SDD manifest’s plan_bundle_hash matches the plan bundle’s current hash
    • +
  • Plan bundle must be saved: Ensure plan harden has saved the plan bundle with updated hash before running generate contracts
    • +
  • Contract density: After generation, run specfact enforce sdd to validate contract density metrics
    • +
+ +

Output Structure:

+ +
.specfact/contracts/
+├── feature_001_contracts.py
+├── feature_002_contracts.py
+└── ...
+
+ +

Each file includes:

+ +
    +
  • Contract decorators (@icontract, @beartype)
    • +
  • CrossHair harnesses for property testing
    • +
  • Backlink metadata to SDD IDs
    • +
  • Plan bundle story/feature references
    • +
+ +
+ +

generate contracts-prompt

+ +

Generate AI IDE prompts for adding contracts to existing code files:

+ +
specfact generate contracts-prompt [FILE] [OPTIONS]
+
+ +

Purpose:

+ +

Creates structured prompt files that you can use with your AI IDE (Cursor, CoPilot, etc.) to add beartype, icontract, or CrossHair contracts to existing Python code. The CLI generates the prompt, your AI IDE’s LLM applies the contracts.

+ +

Options:

+ +
    +
  • FILE - Path to file to enhance (optional if --bundle provided)
    • +
  • --bundle BUNDLE_NAME - Project bundle name. If provided, selects files from bundle. Default: active plan from specfact plan select
    • +
  • --apply CONTRACTS - Required. Contracts to apply: all-contracts, beartype, icontract, crosshair, or comma-separated list (e.g., beartype,icontract)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation). Disables interactive prompts.
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --output PATH - Output file path (currently unused, prompt saved to .specfact/prompts/)
    • +
+ +

Contract Types:

+ +
    +
  • all-contracts - Apply all available contract types (beartype, icontract, crosshair)
    • +
  • beartype - Type checking decorators (@beartype)
    • +
  • icontract - Pre/post condition decorators (@require, @ensure, @invariant)
    • +
  • crosshair - Property-based test functions
    • +
+ +

Examples:

+ +
# Apply all contract types to a specific file
+specfact generate contracts-prompt src/auth/login.py --apply all-contracts
+
+# Apply specific contract types
+specfact generate contracts-prompt src/auth/login.py --apply beartype,icontract
+
+# Apply to all files in a bundle (interactive selection)
+specfact generate contracts-prompt --bundle legacy-api --apply all-contracts
+
+# Apply to all files in a bundle (non-interactive)
+specfact generate contracts-prompt --bundle legacy-api --apply all-contracts --no-interactive
+
+ +

How It Works:

+ +
    +
  1. CLI generates prompt: Reads the file and creates a structured prompt
    2. +
  2. Prompt saved: Saved to .specfact/projects/<bundle-name>/prompts/enhance-<filename>-<contracts>.md (or .specfact/prompts/ if no bundle)
    3. +
  3. You copy prompt: Copy the prompt to your AI IDE (Cursor, CoPilot, etc.)
    4. +
  4. AI IDE enhances code: AI IDE reads the file and provides enhanced code (does NOT modify file directly)
    5. +
  5. AI IDE writes to temp file: Enhanced code written to enhanced_<filename>.py
    6. +
  6. Validate with CLI: AI IDE runs specfact generate contracts-apply enhanced_<filename>.py --original <original-file>
    7. +
  7. Iterative validation: If validation fails, AI IDE fixes issues and re-validates (up to 3 attempts)
    8. +
  8. Apply changes: If validation succeeds, CLI applies changes automatically
    9. +
  9. Verify and test: Run specfact analyze contracts --bundle <bundle> and your test suite
    10. +
+ +

Prompt File Location:

+ +
    +
  • With bundle: .specfact/projects/<bundle-name>/prompts/enhance-<filename>-<contracts>.md
    • +
  • Without bundle: .specfact/prompts/enhance-<filename>-<contracts>.md
    • +
+ +

Why This Approach:

+ +
    +
  • Uses your existing AI IDE infrastructure (no separate LLM API setup)
    • +
  • No additional API costs (leverages IDE’s native LLM)
    • +
  • You maintain control (review before committing)
    • +
  • Works with any AI IDE (Cursor, CoPilot, Claude, etc.)
    • +
  • Iterative validation ensures code quality before applying changes
    • +
+ +

Complete Workflow:

+ +
# 1. Generate prompt
+specfact generate contracts-prompt src/auth/login.py --apply all-contracts
+
+# 2. Open prompt file
+cat .specfact/projects/my-bundle/prompts/enhance-login-beartype-icontract-crosshair.md
+
+# 3. Copy prompt to your AI IDE (Cursor, CoPilot, etc.)
+
+# 4. AI IDE reads the file and provides enhanced code (does NOT modify file directly)
+
+# 5. AI IDE writes enhanced code to temporary file: enhanced_login.py
+
+# 6. AI IDE runs validation
+specfact generate contracts-apply enhanced_login.py --original src/auth/login.py
+
+# 7. If validation fails, AI IDE fixes issues and re-validates (up to 3 attempts)
+
+# 8. If validation succeeds, CLI applies changes automatically
+
+# 9. Verify contract coverage
+specfact analyze contracts --bundle my-bundle
+
+# 10. Run your test suite
+pytest
+
+# 11. Commit the enhanced code
+git add src/auth/login.py && git commit -m "feat: add contracts to login module"
+
+ +

Validation Steps (performed by contracts-apply):

+ +

The contracts-apply command performs rigorous validation before applying changes:

+ +
    +
  1. File size check: Enhanced file must not be smaller than original
    2. +
  2. Python syntax validation: Uses python -m py_compile
    3. +
  3. AST structure comparison: Ensures no functions or classes are accidentally removed
    4. +
  4. Contract imports verification: Checks for required imports (beartype, icontract)
    5. +
  5. Test execution: Runs specfact repro or pytest to ensure code functions correctly
    6. +
  6. Diff preview: Displays changes before applying
    7. +
+ +

Only if all validation steps pass are changes applied to the original file.

+ +

Error Messages:

+ +

If --apply is missing or invalid, the CLI shows helpful error messages with:

+ +
    +
  • Available contract types and descriptions
    • +
  • Usage examples
    • +
  • Link to full documentation
    • +
+ +
+ +

generate fix-prompt

+ +

Generate AI IDE prompt for fixing a specific gap identified by analysis:

+ +
specfact generate fix-prompt [GAP_ID] [OPTIONS]
+
+ +

Purpose:

+ +

Creates a structured prompt file for your AI IDE (Cursor, Copilot, etc.) to fix identified gaps in your codebase. This is the recommended workflow for v0.17+ and replaces direct code generation.

+ +

Arguments:

+ +
    +
  • GAP_ID - Gap ID to fix (e.g., GAP-001). If not provided, lists available gaps.
    • +
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name. Default: active plan from specfact plan select
    • +
  • --output PATH, -o PATH - Output file path. Default: .specfact/prompts/fix-<gap-id>.md
    • +
  • --top N - Show top N gaps when listing. Default: 5
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
+ +

Workflow:

+ +
    +
  1. Run analysis to identify gaps (via import from-code + repro)
    2. +
  2. Run specfact generate fix-prompt to list available gaps
    3. +
  3. Run specfact generate fix-prompt GAP-001 to generate fix prompt
    4. +
  4. Copy the prompt to your AI IDE (Cursor, Copilot, Claude, etc.)
    5. +
  5. AI IDE provides the fix
    6. +
  6. Validate with specfact enforce sdd --bundle <bundle>
    7. +
+ +

Examples:

+ +
# List available gaps
+specfact generate fix-prompt
+
+# Generate fix prompt for specific gap
+specfact generate fix-prompt GAP-001
+
+# List gaps for specific bundle
+specfact generate fix-prompt --bundle legacy-api
+
+# Save to specific file
+specfact generate fix-prompt GAP-001 --output fix.md
+
+# Show more gaps in listing
+specfact generate fix-prompt --top 10
+
+ +

Gap Report Location:

+ +

Gap reports are stored at .specfact/projects/<bundle-name>/reports/gaps.json. If no gap report exists, the command provides guidance on how to generate one.

+ +

Why This Approach:

+ +
    +
  • AI IDE native: Uses your existing AI infrastructure (no separate LLM API setup)
    • +
  • No additional costs: Leverages IDE’s native LLM
    • +
  • You maintain control: Review fixes before committing
    • +
  • Works with any AI IDE: Cursor, Copilot, Claude, Windsurf, etc.
    • +
+ +
+ +

generate test-prompt

+ +

Generate AI IDE prompt for creating tests for a file:

+ +
specfact generate test-prompt [FILE] [OPTIONS]
+
+ +

Purpose:

+ +

Creates a structured prompt file for your AI IDE to generate comprehensive tests for your code. This is the recommended workflow for v0.17+.

+ +

Arguments:

+ +
    +
  • FILE - File to generate tests for. If not provided with --bundle, shows files without tests.
    • +
+ +

Options:

+ +
    +
  • --bundle BUNDLE_NAME - Project bundle name. Default: active plan from specfact plan select
    • +
  • --output PATH, -o PATH - Output file path. Default: .specfact/prompts/test-<filename>.md
    • +
  • --type TYPE - Test type: unit, integration, or both. Default: unit
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
+ +

Workflow:

+ +
    +
  1. Run specfact generate test-prompt src/module.py to get a test prompt
    2. +
  2. Copy the prompt to your AI IDE
    3. +
  3. AI IDE generates tests
    4. +
  4. Save tests to appropriate location (e.g., tests/unit/test_module.py)
    5. +
  5. Run tests with pytest
    6. +
+ +

Examples:

+ +
# List files that may need tests
+specfact generate test-prompt --bundle legacy-api
+
+# Generate unit test prompt for specific file
+specfact generate test-prompt src/auth/login.py
+
+# Generate integration test prompt
+specfact generate test-prompt src/api.py --type integration
+
+# Generate both unit and integration test prompts
+specfact generate test-prompt src/core/engine.py --type both
+
+# Save to specific file
+specfact generate test-prompt src/utils.py --output tests-prompt.md
+
+ +

Test Coverage Analysis:

+ +

When run without a file argument, the command analyzes the repository for Python files without corresponding test files and displays them in a table.

+ +

Generated Prompt Content:

+ +

The generated prompt includes:

+ +
    +
  • File path and content
    • +
  • Test type requirements (unit/integration/both)
    • +
  • Testing framework guidance (pytest, fixtures, parametrize)
    • +
  • Coverage requirements based on test type
    • +
  • AAA pattern (Arrange-Act-Assert) guidelines
    • +
+ +
+ +

generate tasks - Removed

+ +
+

⚠️ REMOVED in v0.22.0: The specfact generate tasks command has been removed. Per SPECFACT_0x_TO_1x_BRIDGE_PLAN.md, SpecFact CLI does not create plan → feature → task (that’s the job for spec-kit, openspec, etc.). We complement those SDD tools to enforce tests and quality.

+
+ +

Previous functionality (removed):

+ +

Generate task breakdown from project bundle and SDD manifest:

+ +
specfact generate tasks [BUNDLE] [OPTIONS]
+
+ +

Purpose:

+ +

Creates a dependency-ordered task list organized by development phase, linking tasks to user stories with acceptance criteria, file paths, dependencies, and parallelization markers.

+ +

Arguments:

+ +
    +
  • BUNDLE - Project bundle name (e.g., legacy-api). Default: active plan from specfact plan select
    • +
+ +

Options:

+ +
    +
  • --sdd PATH - Path to SDD manifest. Default: auto-discover from bundle name
    • +
  • --output-format FORMAT - Output format: yaml, json, markdown. Default: yaml
    • +
  • --out PATH - Output file path. Default: .specfact/projects/<bundle-name>/tasks.yaml
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation)
    • +
+ +

Task Phases:

+ +

Tasks are organized into four phases:

+ +
    +
  1. Setup: Project structure, dependencies, configuration
    2. +
  2. Foundational: Core models, base classes, contracts
    3. +
  3. User Stories: Feature implementation tasks (linked to stories)
    4. +
  4. Polish: Tests, documentation, optimization
    5. +
+ +

Previous Examples (command removed):

+ +
# REMOVED in v0.22.0 - Do not use
+# specfact generate tasks
+# specfact generate tasks legacy-api
+# specfact generate tasks auth-module --output-format json
+# specfact generate tasks legacy-api --output-format markdown
+# specfact generate tasks legacy-api --out custom-tasks.yaml
+
+ +

Migration: Use Spec-Kit, OpenSpec, or other SDD tools to create tasks. SpecFact CLI focuses on enforcing tests and quality gates for existing code.

+ +

Output Structure (YAML):

+ +
version: "1.0"
+bundle: legacy-api
+phases:
+  - name: Setup
+    tasks:
+      - id: TASK-001
+        title: Initialize project structure
+        story_ref: null
+        dependencies: []
+        parallel: false
+        files: [pyproject.toml, src/__init__.py]
+  - name: User Stories
+    tasks:
+      - id: TASK-010
+        title: Implement user authentication
+        story_ref: STORY-001
+        acceptance_criteria:
+          - Users can log in with email/password
+        dependencies: [TASK-001, TASK-005]
+        parallel: true
+        files: [src/auth/login.py]
+
+ +

Note: An SDD manifest (from plan harden) is recommended but not required. Without an SDD, tasks are generated based on plan bundle features and stories only.

+ +
+ +

sync - Synchronize Changes

+ +

Bidirectional synchronization for consistent change management.

+ +

sync bridge

+ +

Sync changes between external tool artifacts (Spec-Kit, Linear, Jira, etc.) and SpecFact using the bridge architecture:

+ +
specfact sync bridge [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
  • --adapter ADAPTER - Adapter type: speckit, generic-markdown, openspec, github, ado, linear, jira, notion (default: auto-detect)
    • +
  • --bundle BUNDLE_NAME - Project bundle name for SpecFact → tool conversion (default: auto-detect)
    • +
  • --mode MODE - Sync mode: read-only (OpenSpec → SpecFact), export-only (OpenSpec → DevOps), import-annotation (DevOps → SpecFact). Default: bidirectional if --bidirectional, else unidirectional
    • +
  • --external-base-path PATH - Base path for external tool repository (for cross-repo integrations, e.g., OpenSpec in different repo)
    • +
  • --bidirectional - Enable bidirectional sync (default: one-way import)
    • +
  • --overwrite - Overwrite existing tool artifacts (delete all existing before sync)
    • +
  • --watch - Watch mode for continuous sync (monitors file changes in real-time)
    • +
  • --interval INT - Watch interval in seconds (default: 5, minimum: 1)
    • +
  • --ensure-compliance - Validate and auto-enrich plan bundle for tool compliance before sync
    • +
+ +

DevOps Backlog Tracking (export-only mode):

+ +

When using --mode export-only with DevOps adapters (GitHub, ADO, Linear, Jira), the command exports OpenSpec change proposals to DevOps backlog tools, creating GitHub issues and tracking implementation progress through automated comment annotations.

+ +

Quick Start:

+ +
    +
  1. Create change proposals in openspec/changes/<change-id>/proposal.md
    2. +
  2. +

    Export to GitHub to create issues:

    + + 
    specfact sync bridge --adapter github --mode export-only \
+  --repo-owner owner --repo-name repo \
+  --repo /path/to/openspec-repo
+
    +
    3. +
  3. +

    Track code changes by adding progress comments:

    + + 
    specfact sync bridge --adapter github --mode export-only \
+  --repo-owner owner --repo-name repo \
+  --track-code-changes \
+  --repo /path/to/openspec-repo \
+  --code-repo /path/to/source-code-repo  # If different from OpenSpec repo
+
    +
    4. +
+ +

Basic Options:

+ +
    +
  • --adapter github - GitHub Issues adapter (requires GitHub API token)
    • +
  • --repo-owner OWNER - GitHub repository owner (optional, can use bridge config)
    • +
  • --repo-name NAME - GitHub repository name (optional, can use bridge config)
    • +
  • --github-token TOKEN - GitHub API token (optional, uses GITHUB_TOKEN env var or gh CLI if not provided)
    • +
  • --use-gh-cli/--no-gh-cli - Use GitHub CLI (gh auth token) to get token automatically (default: True). Useful in enterprise environments where PAT creation is restricted
    • +
  • --sanitize/--no-sanitize - Sanitize proposal content for public issues (default: auto-detect based on repo setup) +
      +
    • Auto-detection: If code repo != planning repo → sanitize, if same repo → no sanitization
      • +
    • --sanitize: Force sanitization (removes competitive analysis, internal strategy, implementation details)
      • +
    • --no-sanitize: Skip sanitization (use full proposal content)
      • +
    +
    • +
  • --target-repo OWNER/REPO - Target repository for issue creation (format: owner/repo). Default: same as code repository
    • +
  • --interactive - Interactive mode for AI-assisted sanitization (requires slash command)
    • +
  • --change-ids ID1,ID2 - Comma-separated list of change proposal IDs to export (default: all active proposals)
    • +
+ +

Environment Variables:

+ +
    +
  • GITHUB_TOKEN - GitHub API token (used if --github-token not provided and --use-gh-cli is False)
    • +
+ +

Watch Mode Features:

+ +
    +
  • Hash-based change detection: Only processes files that actually changed (SHA256 hash verification)
    • +
  • Real-time monitoring: Automatically detects file changes in tool artifacts, SpecFact bundles, and repository code
    • +
  • Dependency tracking: Tracks file dependencies for incremental processing
    • +
  • Debouncing: Prevents rapid file change events (500ms debounce interval)
    • +
  • Change type detection: Automatically detects whether changes are in tool artifacts, SpecFact bundles, or code
    • +
  • LZ4 cache compression: Faster cache I/O when LZ4 is available (optional)
    • +
  • Graceful shutdown: Press Ctrl+C to stop watch mode cleanly
    • +
  • Resource efficient: Minimal CPU/memory usage
    • +
+ +

Examples:

+ +
# One-time bidirectional sync with Spec-Kit
+specfact sync bridge --adapter speckit --repo . --bundle my-project --bidirectional
+
+# Auto-detect adapter and bundle
+specfact sync bridge --repo . --bidirectional
+
+# Overwrite tool artifacts with SpecFact bundle
+specfact sync bridge --adapter speckit --repo . --bundle my-project --bidirectional --overwrite
+
+# Continuous watch mode
+specfact sync bridge --adapter speckit --repo . --bundle my-project --bidirectional --watch --interval 5
+
+# OpenSpec read-only sync (Phase 1 - import only)
+specfact sync bridge --adapter openspec --mode read-only --bundle my-project --repo .
+
+# OpenSpec cross-repository sync (OpenSpec in different repo)
+specfact sync bridge --adapter openspec --mode read-only --bundle my-project --repo . --external-base-path ../specfact-cli-internal
+
+ +

Export OpenSpec change proposals to GitHub issues (auto-detect sanitization)

+

specfact sync bridge –adapter github –mode export-only

+ +

Export with explicit repository and sanitization

+

specfact sync bridge –adapter github –mode export-only
+ –repo-owner owner –repo-name repo
+ –sanitize
+ –target-repo public-owner/public-repo

+ +

Export without sanitization (use full proposal content)

+

specfact sync bridge –adapter github –mode export-only
+ –no-sanitize

+ +

Export using GitHub CLI for token (enterprise-friendly)

+

specfact sync bridge –adapter github –mode export-only
+ –use-gh-cli

+ +

Export specific change proposals only

+

specfact sync bridge –adapter github –mode export-only
+ –repo-owner owner –repo-name repo
+ –change-ids add-feature-x,update-api
+ –repo /path/to/openspec-repo

+

+**What it syncs (Spec-Kit adapter):**
+
+- `specs/[###-feature-name]/spec.md`, `plan.md`, `tasks.md` ↔ `.specfact/projects/<bundle-name>/bundle.yaml`
+- `.specify/memory/constitution.md` ↔ SpecFact business context
+- `specs/[###-feature-name]/research.md`, `data-model.md`, `quickstart.md` ↔ SpecFact supporting artifacts
+- `specs/[###-feature-name]/contracts/*.yaml` ↔ SpecFact protocol definitions
+- Automatic conflict resolution with priority rules
+
+**Spec-Kit Field Auto-Generation:**
+
+When syncing from SpecFact to Spec-Kit (`--bidirectional`), the CLI automatically generates all required Spec-Kit fields:
+
+- **spec.md**: Frontmatter (Feature Branch, Created date, Status), INVSEST criteria, Scenarios (Primary, Alternate, Exception, Recovery)
+- **plan.md**: Constitution Check (Article VII, VIII, IX), Phases (Phase 0, 1, 2, -1), Technology Stack (from constraints), Constraints, Unknowns
+- **tasks.md**: Phase organization (Phase 1: Setup, Phase 2: Foundational, Phase 3+: User Stories), Story mappings ([US1], [US2]), Parallel markers [P]
+
+**All Spec-Kit fields are auto-generated** - no manual editing required unless you want to customize defaults. Generated artifacts are ready for `/speckit.analyze` without additional work.
+
+**Content Sanitization (export-only mode):**
+
+When exporting OpenSpec change proposals to public repositories, content sanitization removes internal/competitive information while preserving user-facing value:
+
+**What's Removed:**
+
+- Competitive analysis sections
+- Market positioning statements
+- Implementation details (file-by-file changes)
+- Effort estimates and timelines
+- Technical architecture details
+- Internal strategy sections
+
+**What's Preserved:**
+
+- High-level feature descriptions
+- User-facing value propositions
+- Acceptance criteria
+- External documentation links
+- Use cases and examples
+
+**When to Use Sanitization:**
+
+- **Different repos** (code repo ≠ planning repo): Sanitization recommended (default: yes)
+- **Same repo** (code repo = planning repo): Sanitization optional (default: no, user can override)
+- **Breaking changes**: Use sanitization to communicate changes early without exposing internal strategy
+- **OSS collaboration**: Use sanitization for public issues to keep contributors informed
+
+**Sanitization Auto-Detection:**
+
+- Automatically detects if code and planning are in different repositories
+- Defaults to sanitize when repos differ (protects internal information)
+- Defaults to no sanitization when repos are the same (user can choose full disclosure)
+- User can override with `--sanitize` or `--no-sanitize` flags
+
+**AI-Assisted Sanitization:**
+
+- Use slash command `/specfact.sync-backlog` for interactive, AI-assisted content rewriting
+- AI analyzes proposal content and suggests sanitized version
+- User can review and approve sanitized content before issue creation
+- Useful for complex proposals requiring nuanced content adaptation
+
+**Proposal Filtering (export-only mode):**
+
+When exporting OpenSpec change proposals to DevOps tools, proposals are filtered based on target repository type and status:
+
+**Public Repositories** (with `--sanitize`):
+
+- **Only syncs proposals with status `"applied"`** (archived/completed changes)
+- Filters out proposals with status `"proposed"`, `"in-progress"`, `"deprecated"`, or `"discarded"`
+- Applies regardless of whether proposals have existing source tracking entries
+- Prevents premature exposure of work-in-progress proposals to public repositories
+- Warning message displayed when proposals are filtered out
+
+**Internal Repositories** (with `--no-sanitize` or auto-detected as internal):
+
+- Syncs all active proposals regardless of status:
+  - `"proposed"` - New proposals not yet started
+  - `"in-progress"` - Proposals currently being worked on
+  - `"applied"` - Completed/archived proposals
+  - `"deprecated"` - Deprecated proposals
+  - `"discarded"` - Discarded proposals
+- If proposal has source tracking entry for target repo: syncs it (for updates)
+- If proposal doesn't have entry: syncs if status is active
+
+**Examples:**
+
+```bash
+# Public repo: only syncs "applied" proposals (archived changes)
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli \
+  --sanitize \
+  --target-repo nold-ai/specfact-cli
+
+# Internal repo: syncs all active proposals (proposed, in-progress, applied, etc.)
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --no-sanitize \
+  --target-repo nold-ai/specfact-cli-internal
+
+ +

Code Change Tracking and Progress Comments (export-only mode):

+ +

When using --mode export-only with DevOps adapters, you can track implementation progress by detecting code changes and adding progress comments to existing GitHub issues:

+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --track-code-changes/--no-track-code-changes - Detect code changes (git commits, file modifications) and add progress comments to existing issues (default: False)
    • +
  • --add-progress-comment/--no-add-progress-comment - Add manual progress comment to existing issues without code change detection (default: False)
    • +
  • --code-repo PATH - Path to source code repository for code change detection (default: same as --repo). Required when OpenSpec repository differs from source code repository. For example, if OpenSpec proposals are in specfact-cli-internal but source code is in specfact-cli, use --repo /path/to/specfact-cli-internal --code-repo /path/to/specfact-cli.
    • +
  • --update-existing/--no-update-existing - Update existing issue bodies when proposal content changes (default: False for safety). Uses content hash to detect changes.
    • +
+ +

Code Change Detection:

+ +

When --track-code-changes is enabled:

+ +
    +
  1. Git Commit Detection: Searches git log for commits mentioning the change proposal ID (e.g., add-code-change-tracking)
    2. +
  2. File Change Tracking: Extracts files modified in detected commits
    3. +
  3. Progress Comment Generation: Formats progress comment with: +
      +
    • Commit details (hash, message, author, date)
      • +
    • Files changed summary
      • +
    • Detection timestamp
      • +
    +
    4. +
  4. Duplicate Prevention: Calculates SHA-256 hash of comment text and checks against existing progress comments
    5. +
  5. Source Tracking Update: Stores progress comment in source_metadata.progress_comments and updates last_code_change_detected timestamp
    6. +
+ +

Progress Comment Sanitization:

+ +

When --sanitize is enabled (for public repositories), progress comments are automatically sanitized:

+ +
    +
  • Commit messages: Internal/confidential/competitive keywords removed, long messages truncated
    • +
  • File paths: Replaced with file type counts (e.g., “3 py file(s)” instead of full paths)
    • +
  • Author emails: Removed, only username shown
    • +
  • Timestamps: Date only (no time component)
    • +
+ +

Examples:

+ +
# Detect code changes and add progress comments (internal repo)
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --track-code-changes \
+  --repo .
+
+# Detect code changes with sanitization (public repo)
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli \
+  --track-code-changes \
+  --sanitize \
+  --repo .
+
+# Add manual progress comment (without code change detection)
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --add-progress-comment \
+  --repo .
+
+# Update existing issues AND add progress comments
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --update-existing \
+  --track-code-changes \
+  --repo .
+
+# Sync specific change proposal with code change tracking
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --track-code-changes \
+  --change-ids add-code-change-tracking \
+  --repo .
+
+# Separate OpenSpec and source code repositories
+# OpenSpec proposals in specfact-cli-internal, source code in specfact-cli
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --track-code-changes \
+  --change-ids add-code-change-tracking \
+  --repo /path/to/specfact-cli-internal \
+  --code-repo /path/to/specfact-cli
+
+ +

Prerequisites:

+ +

For Issue Creation:

+ +
    +
  • Change proposals must exist in openspec/changes/<change-id>/proposal.md directory (in the OpenSpec repository specified by --repo)
    • +
  • GitHub token (via GITHUB_TOKEN env var, gh auth token, or --github-token)
    • +
  • Repository access permissions (read for proposals, write for issues)
    • +
+ +

For Code Change Tracking:

+ +
    +
  • Issues must already exist (created via previous sync)
    • +
  • Git repository with commits mentioning the change proposal ID in commit messages: +
      +
    • If --code-repo is provided, commits must be in that repository
      • +
    • Otherwise, commits must be in the OpenSpec repository (--repo)
      • +
    +
    • +
  • Commit messages should include the change proposal ID (e.g., “feat: implement add-code-change-tracking”)
    • +
+ +

Separate OpenSpec and Source Code Repositories:

+ +

When your OpenSpec change proposals are in a different repository than your source code:

+ +
# Example: OpenSpec in specfact-cli-internal, source code in specfact-cli
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner nold-ai --repo-name specfact-cli-internal \
+  --track-code-changes \
+  --repo /path/to/specfact-cli-internal \
+  --code-repo /path/to/specfact-cli
+
+ +

Why use --code-repo?

+ +
    +
  • OpenSpec repository (--repo): Contains change proposals in openspec/changes/ directory
    • +
  • Source code repository (--code-repo): Contains actual implementation commits that reference the change proposal ID
    • +
+ +

If both are in the same repository, you can omit --code-repo and it will use --repo for both purposes.

+ +

Integration Workflow:

+ +
    +
  1. +

    Initial Setup (one-time):

    + + 
    # Create change proposal in openspec/changes/<change-id>/proposal.md
+# Export to GitHub to create issue
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner owner --repo-name repo \
+  --repo /path/to/openspec-repo
+
    +
    2. +
  2. +

    Development Workflow (ongoing):

    + + 
    # Make commits with change ID in commit message
+git commit -m "feat: implement add-code-change-tracking - initial implementation"
+   
+# Track progress automatically
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner owner --repo-name repo \
+  --track-code-changes \
+  --repo /path/to/openspec-repo \
+  --code-repo /path/to/source-code-repo
+
    +
    3. +
  3. +

    Manual Progress Updates (when needed):

    + + 
    # Add manual progress comment without code change detection
+specfact sync bridge --adapter github --mode export-only \
+  --repo-owner owner --repo-name repo \
+  --add-progress-comment \
+  --repo /path/to/openspec-repo
+
    +
    4. +
+ +

Verification:

+ +

After running the command, verify:

+ +
    +
  1. +

    GitHub Issue: Check that progress comment was added to the issue:

    + + 
    gh issue view <issue-number> --repo owner/repo --json comments --jq '.comments[-1].body'
+
    +
    2. +
  2. +

    Source Tracking: Verify openspec/changes/<change-id>/proposal.md was updated with:

    + + 
    ## Source Tracking
+   
+- **GitHub Issue**: #123
+- **Issue URL**: <https://github.com/owner/repo/issues/123>
+- **Last Synced Status**: proposed
+- **Sanitized**: false
+<!-- last_code_change_detected: 2025-12-30T10:00:00Z -->
+
    +
    3. +
  3. +

    Duplicate Prevention: Run the same command twice - second run should skip duplicate comment (no new comment added)

    +
    4. +
+ +

Troubleshooting:

+ +
    +
  • No commits detected: Ensure commit messages include the change proposal ID (e.g., “add-code-change-tracking”)
    • +
  • Wrong repository: Verify --code-repo points to the correct source code repository
    • +
  • No comments added: Check that issues exist (create them first without --track-code-changes)
    • +
  • Sanitization issues: Use --sanitize for public repos, --no-sanitize for internal repos
    • +
+ +

Constitution Evidence Extraction:

+ +

When generating Spec-Kit plan.md files, SpecFact automatically extracts evidence-based constitution alignment from your codebase:

+ +
    +
  • Article VII (Simplicity): Analyzes project structure, directory depth, file organization, and naming patterns to determine PASS/FAIL status with rationale
    • +
  • Article VIII (Anti-Abstraction): Detects framework usage, abstraction layers, and framework-specific patterns to assess anti-abstraction compliance
    • +
  • Article IX (Integration-First): Analyzes contract patterns (icontract decorators, OpenAPI definitions, type hints) to verify integration-first approach
    • +
+ +

Evidence-Based Status: Constitution check sections include PASS/FAIL status (not PENDING) with:

+ +
    +
  • Evidence citations from code patterns
    • +
  • Rationale explaining why each article passes or fails
    • +
  • Actionable recommendations for improvement (if FAIL)
    • +
+ +

This evidence extraction happens automatically during sync bridge --adapter speckit when generating Spec-Kit artifacts. No additional configuration required.

+ +

sync repository

+ +

Sync code changes to SpecFact artifacts:

+ +
specfact sync repository [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
  • --target PATH - Target directory for artifacts (default: .specfact)
    • +
  • --watch - Watch mode for continuous sync (monitors code changes in real-time)
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --interval INT - Watch interval in seconds (default: 5, minimum: 1)
    • +
  • --confidence FLOAT - Minimum confidence threshold for feature detection (default: 0.5, range: 0.0-1.0)
    • +
+ +

Watch Mode Features:

+ +
    +
  • Hash-based change detection: Only processes files that actually changed (SHA256 hash verification)
    • +
  • Real-time monitoring: Automatically detects code changes in repository
    • +
  • Automatic sync: Triggers sync when code changes are detected
    • +
  • Deviation tracking: Tracks deviations from manual plans as code changes
    • +
  • Dependency tracking: Tracks file dependencies for incremental processing
    • +
  • Debouncing: Prevents rapid file change events (500ms debounce interval)
    • +
  • LZ4 cache compression: Faster cache I/O when LZ4 is available (optional)
    • +
  • Graceful shutdown: Press Ctrl+C to stop watch mode cleanly
    • +
+ +

Example:

+ +
# One-time sync
+specfact sync repository --repo . --target .specfact
+
+# Continuous watch mode (monitors for code changes every 5 seconds)
+specfact sync repository --repo . --watch --interval 5
+
+# Watch mode with custom interval and confidence threshold
+specfact sync repository --repo . --watch --interval 2 --confidence 0.7
+
+ +

What it tracks:

+ +
    +
  • Code changes → Plan artifact updates
    • +
  • Deviations from manual plans
    • +
  • Feature/story extraction from code
    • +
+ +
+ +

spec - API Specification Management (Specmatic Integration)

+ +

Manage API specifications with Specmatic for OpenAPI/AsyncAPI validation, backward compatibility checking, and mock server functionality.

+ +

Note: Specmatic is a Java CLI tool that must be installed separately from https://docs.specmatic.io/. SpecFact CLI will check for Specmatic availability and provide helpful error messages if it’s not found.

+ +

spec validate

+ +

Validate OpenAPI/AsyncAPI specification using Specmatic. Can validate a single file or all contracts in a project bundle.

+ +
specfact spec validate [<spec-path>] [OPTIONS]
+
+ +

Arguments:

+ +
    +
  • <spec-path> - Path to OpenAPI/AsyncAPI specification file (optional if –bundle provided)
    • +
+ +

Options:

+ +
    +
  • --bundle NAME - Project bundle name (e.g., legacy-api). If provided, validates all contracts in bundle. Default: active plan from ‘specfact plan select’
    • +
  • --previous PATH - Path to previous version for backward compatibility check
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation). Disables interactive prompts.
    • +
+ +

Examples:

+ +
# Validate a single spec file
+specfact spec validate api/openapi.yaml
+
+# With backward compatibility check
+specfact spec validate api/openapi.yaml --previous api/openapi.v1.yaml
+
+# Validate all contracts in active bundle (interactive selection)
+specfact spec validate
+
+# Validate all contracts in specific bundle
+specfact spec validate --bundle legacy-api
+
+# Non-interactive: validate all contracts
+specfact spec validate --bundle legacy-api --no-interactive
+
+ +

CLI-First Pattern: Uses active plan (from specfact plan select) as default, or specify --bundle. Never requires direct .specfact paths - always use the CLI interface. When multiple contracts are available, shows interactive list for selection.

+ +

What it checks:

+ +
    +
  • Schema structure validation
    • +
  • Example generation test
    • +
  • Backward compatibility (if previous version provided)
    • +
+ +

Output:

+ +
    +
  • Validation results table with status for each check
    • +
  • ✓ PASS or ✗ FAIL for each validation step
    • +
  • Detailed errors if validation fails
    • +
  • Summary when validating multiple contracts
    • +
+ +

spec backward-compat

+ +

Check backward compatibility between two spec versions.

+ +
specfact spec backward-compat <old-spec> <new-spec>
+
+ +

Arguments:

+ +
    +
  • <old-spec> - Path to old specification version (required)
    • +
  • <new-spec> - Path to new specification version (required)
    • +
+ +

Example:

+ +
specfact spec backward-compat api/openapi.v1.yaml api/openapi.v2.yaml
+
+ +

Output:

+ +
    +
  • ✓ Compatible - No breaking changes detected
    • +
  • ✗ Breaking changes - Lists incompatible changes
    • +
+ +

spec generate-tests

+ +

Generate Specmatic test suite from specification. Can generate for a single file or all contracts in a bundle.

+ +
specfact spec generate-tests [<spec-path>] [OPTIONS]
+
+ +

Arguments:

+ +
    +
  • <spec-path> - Path to OpenAPI/AsyncAPI specification (optional if –bundle provided)
    • +
+ +

Options:

+ +
    +
  • --bundle NAME - Project bundle name (e.g., legacy-api). If provided, generates tests for all contracts in bundle. Default: active plan from ‘specfact plan select’
    • +
  • --out PATH - Output directory for generated tests (default: .specfact/specmatic-tests/)
    • +
+ +

Examples:

+ +
# Generate for a single spec file
+specfact spec generate-tests api/openapi.yaml
+
+# Generate to custom location
+specfact spec generate-tests api/openapi.yaml --out tests/specmatic/
+
+# Generate tests for all contracts in active bundle
+specfact spec generate-tests --bundle legacy-api
+
+# Generate tests for all contracts in specific bundle
+specfact spec generate-tests --bundle legacy-api --out tests/contract/
+
+ +

CLI-First Pattern: Uses active plan as default, or specify --bundle. Never requires direct .specfact paths.

+ +

Caching: +Test generation results are cached in .specfact/cache/specmatic-tests.json based on file content hashes. Unchanged contracts are automatically skipped on subsequent runs. Use --force to bypass cache.

+ +

Output:

+ +
    +
  • ✓ Test suite generated with path to output directory
    • +
  • Instructions to run the generated tests
    • +
  • Summary when generating tests for multiple contracts
    • +
+ +

What to Do With Generated Tests:

+ +

The generated tests are executable contract tests that validate your API implementation against the OpenAPI/AsyncAPI specification. Here’s how to use them:

+ +
    +
  1. +

    Generate tests (you just did this):

    + + 
    specfact spec generate-tests --bundle my-api --output tests/contract/
+
    +
    2. +
  2. +

    Start your API server:

    + + 
    python -m uvicorn main:app --port 8000
+
    +
    3. +
  3. +

    Run tests against your API:

    + + 
    specmatic test \
+  --spec .specfact/projects/my-api/contracts/api.openapi.yaml \
+  --host http://localhost:8000
+
    +
    4. +
  4. +

    Tests validate:

    +
      +
    • Request format matches spec (headers, body, query params)
      • +
    • Response format matches spec (status codes, headers, body schema)
      • +
    • All endpoints are implemented
      • +
    • Data types and constraints are respected
      • +
    +
    5. +
+ +

CI/CD Integration:

+ +
- name: Generate contract tests
+  run: specfact spec generate-tests --bundle my-api --output tests/contract/
+
+- name: Start API server
+  run: python -m uvicorn main:app --port 8000 &
+
+- name: Run contract tests
+  run: specmatic test --spec ... --host http://localhost:8000
+
+ +

See Specmatic Integration Guide for complete walkthrough.

+ +

spec mock

+ +

Launch Specmatic mock server from specification. Can use a single spec file or select from bundle contracts.

+ +
specfact spec mock [OPTIONS]
+
+ +

Options:

+ +
    +
  • --spec PATH - Path to OpenAPI/AsyncAPI specification (default: auto-detect from current directory)
    • +
  • --bundle NAME - Project bundle name (e.g., legacy-api). If provided, selects contract from bundle. Default: active plan from ‘specfact plan select’
    • +
  • --port INT - Port number for mock server (default: 9000)
    • +
  • --strict/--examples - Use strict validation mode or examples mode (default: strict)
    • +
  • --no-interactive - Non-interactive mode (for CI/CD automation). Uses first contract if multiple available.
    • +
+ +

Examples:

+ +
# Auto-detect spec file from current directory
+specfact spec mock
+
+# Specify spec file and port
+specfact spec mock --spec api/openapi.yaml --port 9000
+
+# Use examples mode (less strict)
+specfact spec mock --spec api/openapi.yaml --examples
+
+# Select contract from active bundle (interactive)
+specfact spec mock --bundle legacy-api
+
+# Use specific bundle (non-interactive, uses first contract)
+specfact spec mock --bundle legacy-api --no-interactive
+
+ +

CLI-First Pattern: Uses active plan as default, or specify --bundle. Interactive selection when multiple contracts available.

+ +

Features:

+ +
    +
  • Serves API endpoints based on specification
    • +
  • Validates requests against spec
    • +
  • Returns example responses
    • +
  • Press Ctrl+C to stop
    • +
+ +

Common locations for auto-detection:

+ +
    +
  • openapi.yaml, openapi.yml, openapi.json
    • +
  • asyncapi.yaml, asyncapi.yml, asyncapi.json
    • +
  • api/openapi.yaml
    • +
  • specs/openapi.yaml
    • +
+ +

Integration:

+ +

The spec commands are automatically integrated into:

+ +
    +
  • import from-code - Auto-validates OpenAPI/AsyncAPI specs after import
    • +
  • enforce sdd - Validates API specs during SDD enforcement
    • +
  • sync bridge and sync repository - Auto-validates specs after sync
    • +
+ +

See Specmatic Integration Guide for detailed documentation.

+ +
+ +
+ +

sdd constitution - Manage Project Constitutions (Spec-Kit Compatibility)

+ +

Note: Constitution management commands are part of the sdd (Spec-Driven Development) command group. The specfact bridge command group has been removed in v0.22.0 as part of the bridge adapter refactoring. Bridge adapters are now internal connectors accessed via specfact sync bridge --adapter <adapter-name>, not user-facing commands.

+ +

Manage project constitutions for Spec-Kit format compatibility. Auto-generate bootstrap templates from repository analysis.

+ +

Note: These commands are for Spec-Kit format compatibility only. SpecFact itself uses modular project bundles (.specfact/projects/<bundle-name>/) and protocols (.specfact/protocols/*.protocol.yaml) for internal operations. Constitutions are only needed when:

+ +
    +
  • +

    Syncing with Spec-Kit artifacts (specfact sync bridge --adapter speckit)

    +
    • +
  • +

    Working in Spec-Kit format (using /speckit.* commands)

    +
    • +
  • +

    Migrating from Spec-Kit to SpecFact format

    +
    • +
+ +

If you’re using SpecFact standalone (without Spec-Kit), you don’t need constitutions - use specfact plan commands instead.

+ +

⚠️ Breaking Change: The specfact bridge constitution command has been moved to specfact sdd constitution as part of the bridge adapter refactoring. Please update your scripts and workflows.

+ +
sdd constitution bootstrap
+ +

Generate bootstrap constitution from repository analysis:

+ +
specfact sdd constitution bootstrap [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Repository path (default: current directory)
    • +
  • --out PATH - Output path for constitution (default: .specify/memory/constitution.md)
    • +
  • --overwrite - Overwrite existing constitution if it exists
    • +
+ +

Example:

+ +
# Generate bootstrap constitution
+specfact sdd constitution bootstrap --repo .
+
+# Generate with custom output path
+specfact sdd constitution bootstrap --repo . --out custom-constitution.md
+
+# Overwrite existing constitution
+specfact sdd constitution bootstrap --repo . --overwrite
+
+ +

What it does:

+ +
    +
  • Analyzes repository context (README.md, pyproject.toml, .cursor/rules/, docs/rules/)
    • +
  • Extracts project metadata (name, description, technology stack)
    • +
  • Extracts development principles from rule files
    • +
  • Generates bootstrap constitution template with: +
      +
    • Project name and description
      • +
    • Core principles (extracted from repository)
      • +
    • Development workflow guidelines
      • +
    • Quality standards
      • +
    • Governance rules
      • +
    +
    • +
  • Creates constitution at .specify/memory/constitution.md (Spec-Kit convention)
    • +
+ +

When to use:

+ +
    +
  • Spec-Kit sync operations: Required before specfact sync bridge --adapter speckit (bidirectional sync)
    • +
  • Spec-Kit format projects: When working with Spec-Kit artifacts (using /speckit.* commands)
    • +
  • After brownfield import (if syncing to Spec-Kit): Run specfact import from-code → Suggested automatically if Spec-Kit sync is planned
    • +
  • Manual setup: Generate constitution for new Spec-Kit projects
    • +
+ +

Note: If you’re using SpecFact standalone (without Spec-Kit), you don’t need constitutions. Use specfact plan commands instead for plan management.

+ +

Integration:

+ +
    +
  • Auto-suggested during specfact import from-code (brownfield imports)
    • +
  • Auto-detected during specfact sync bridge --adapter speckit (if constitution is minimal)
    • +
+ +
+ +
sdd constitution enrich
+ +

Auto-enrich existing constitution with repository context (Spec-Kit format):

+ +
specfact sdd constitution enrich [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Repository path (default: current directory)
    • +
  • --constitution PATH - Path to constitution file (default: .specify/memory/constitution.md)
    • +
+ +

Example:

+ +
# Enrich existing constitution
+specfact sdd constitution enrich --repo .
+
+# Enrich specific constitution file
+specfact sdd constitution enrich --repo . --constitution custom-constitution.md
+
+ +

What it does:

+ +
    +
  • Analyzes repository context (same as bootstrap)
    • +
  • Fills remaining placeholders in existing constitution
    • +
  • Adds additional principles extracted from repository
    • +
  • Updates workflow and quality standards sections
    • +
+ +

When to use:

+ +
    +
  • Constitution has placeholders that need filling
    • +
  • Repository context has changed (new rules, updated README)
    • +
  • Manual constitution needs enrichment with repository details
    • +
+ +
+ +
sdd constitution validate
+ +

Validate constitution completeness (Spec-Kit format):

+ +
specfact sdd constitution validate [OPTIONS]
+
+ +

Options:

+ +
    +
  • --constitution PATH - Path to constitution file (default: .specify/memory/constitution.md)
    • +
+ +

Example:

+ +
# Validate default constitution
+specfact sdd constitution validate
+
+# Validate specific constitution file
+specfact sdd constitution validate --constitution custom-constitution.md
+
+ +

What it checks:

+ +
    +
  • Constitution exists and is not empty
    • +
  • No unresolved placeholders remain
    • +
  • Has “Core Principles” section
    • +
  • Has at least one numbered principle
    • +
  • Has “Governance” section
    • +
  • Has version and ratification date
    • +
+ +

Output:

+ +
    +
  • ✅ Valid: Constitution is complete and ready for use
    • +
  • ❌ Invalid: Lists specific issues found (placeholders, missing sections, etc.)
    • +
+ +

When to use:

+ +
    +
  • Before syncing with Spec-Kit (specfact sync bridge --adapter speckit requires valid constitution)
    • +
  • After manual edits to verify completeness
    • +
  • In CI/CD pipelines to ensure constitution quality
    • +
+ +
+ +
+ +
+ +

Note: The specfact constitution command has been moved to specfact sdd constitution. See the sdd constitution section above for complete documentation.

+ +

Migration: Replace specfact constitution <command> or specfact bridge constitution <command> with specfact sdd constitution <command>.

+ +

Example Migration:

+ +
    +
  • specfact constitution bootstrap → specfact sdd constitution bootstrap
    • +
  • specfact bridge constitution bootstrap → specfact sdd constitution bootstrap
    • +
  • specfact constitution enrich → specfact sdd constitution enrich
    • +
  • specfact bridge constitution enrich → specfact sdd constitution enrich
    • +
  • specfact constitution validate → specfact sdd constitution validate
    • +
  • specfact bridge constitution validate → specfact sdd constitution validate
    • +
+ +
+ +

migrate - Migration Helpers

+ +

Helper commands for migrating legacy artifacts and cleaning up deprecated structures.

+ +

migrate cleanup-legacy

+ +

Remove empty legacy top-level directories (Phase 8.5 cleanup).

+ +
specfact migrate cleanup-legacy [OPTIONS]
+
+ +

Purpose:

+ +

Removes legacy directories that are no longer created by newer SpecFact versions:

+ +
    +
  • .specfact/plans/ (deprecated: no monolithic bundles, active bundle config moved to config.yaml)
    • +
  • .specfact/contracts/ (now bundle-specific: .specfact/projects/<bundle-name>/contracts/)
    • +
  • .specfact/protocols/ (now bundle-specific: .specfact/projects/<bundle-name>/protocols/)
    • +
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
  • --dry-run - Show what would be removed without actually removing
    • +
  • --force - Remove directories even if they contain files (default: only removes empty directories)
    • +
+ +

Examples:

+ +
# Preview what would be removed
+specfact migrate cleanup-legacy --dry-run
+
+# Remove empty legacy directories
+specfact migrate cleanup-legacy
+
+# Force removal even if directories contain files
+specfact migrate cleanup-legacy --force
+
+ +

Safety:

+ +

By default, the command only removes empty directories. Use --force to remove directories containing files (use with caution).

+ +
+ +

migrate to-contracts

+ +

Migrate legacy bundles to contract-centric structure.

+ +
specfact migrate to-contracts [BUNDLE] [OPTIONS]
+
+ +

Purpose:

+ +

Converts legacy plan bundles to the new contract-centric structure, extracting OpenAPI contracts from verbose acceptance criteria and validating with Specmatic.

+ +

Arguments:

+ +
    +
  • BUNDLE - Project bundle name. Default: active plan from specfact plan select
    • +
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
  • --extract-openapi/--no-extract-openapi - Extract OpenAPI contracts from verbose acceptance criteria (default: enabled)
    • +
  • --validate-with-specmatic/--no-validate-with-specmatic - Validate generated contracts with Specmatic (default: enabled)
    • +
  • --dry-run - Preview changes without writing
    • +
  • --no-interactive - Non-interactive mode
    • +
+ +

Examples:

+ +
# Migrate bundle to contract-centric structure
+specfact migrate to-contracts legacy-api
+
+# Preview migration without writing
+specfact migrate to-contracts legacy-api --dry-run
+
+# Skip OpenAPI extraction
+specfact migrate to-contracts legacy-api --no-extract-openapi
+
+ +

What it does:

+ +
    +
  1. Scans acceptance criteria for API-related patterns
    2. +
  2. Extracts OpenAPI contract definitions
    3. +
  3. Creates contract files in bundle-specific location
    4. +
  4. Validates contracts with Specmatic (if available)
    5. +
  5. Updates bundle manifest with contract references
    6. +
+ +
+ +

migrate artifacts

+ +

Migrate artifacts between bundle versions or locations.

+ +
specfact migrate artifacts [BUNDLE] [OPTIONS]
+
+ +

Purpose:

+ +

Migrates artifacts (reports, contracts, SDDs) from legacy locations to the current bundle-specific structure.

+ +

Arguments:

+ +
    +
  • BUNDLE - Project bundle name. If not specified, migrates artifacts for all bundles found in .specfact/projects/
    • +
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
  • --dry-run - Show what would be migrated without actually migrating
    • +
  • --backup/--no-backup - Create backups of original files (default: enabled)
    • +
+ +

Examples:

+ +
# Migrate artifacts for specific bundle
+specfact migrate artifacts legacy-api
+
+# Migrate artifacts for all bundles
+specfact migrate artifacts
+
+# Preview migration
+specfact migrate artifacts legacy-api --dry-run
+
+# Skip backups (faster, but no rollback)
+specfact migrate artifacts legacy-api --no-backup
+
+ +

What it migrates:

+ +
    +
  • Reports from legacy locations to .specfact/projects/<bundle>/reports/
    • +
  • Contracts from root-level to bundle-specific locations
    • +
  • SDD manifests from legacy paths to bundle-specific paths
    • +
+ +
+ +

sdd - SDD Manifest Utilities

+ +

Utilities for working with SDD (Software Design Document) manifests.

+ +

sdd list

+ +

List all SDD manifests in the repository.

+ +
specfact sdd list [OPTIONS]
+
+ +

Purpose:

+ +

Shows all SDD manifests found in the repository, including:

+ +
    +
  • Bundle-specific locations (.specfact/projects/<bundle-name>/sdd.yaml, Phase 8.5)
    • +
  • Legacy multi-SDD layout (.specfact/sdd/*.yaml)
    • +
  • Legacy single-SDD layout (.specfact/sdd.yaml)
    • +
+ +

Options:

+ +
    +
  • --repo PATH - Path to repository (default: .)
    • +
+ +

Examples:

+ +
# List all SDD manifests
+specfact sdd list
+
+# List SDDs in specific repository
+specfact sdd list --repo /path/to/repo
+
+ +

Output:

+ +

Displays a table with:

+ +
    +
  • Path: Location of the SDD manifest
    • +
  • Bundle: Associated bundle name (if applicable)
    • +
  • Version: SDD schema version
    • +
  • Features: Number of features defined
    • +
+ +

Use Cases:

+ +
    +
  • Discover existing SDD manifests in a repository
    • +
  • Verify SDD locations after migration
    • +
  • Debug SDD-related issues
    • +
+ +
+ +

implement - Removed Task Execution

+ +
+

⚠️ REMOVED in v0.22.0: The implement command group has been removed. Per SPECFACT_0x_TO_1x_BRIDGE_PLAN.md, SpecFact CLI does not create plan → feature → task (that’s the job for spec-kit, openspec, etc.). We complement those SDD tools to enforce tests and quality. Use the AI IDE bridge commands (specfact generate fix-prompt, specfact generate test-prompt, etc.) instead.

+
+ +

implement tasks (Removed)

+ +

Direct task execution was removed in v0.22.0. Use AI IDE bridge workflows instead.

+ +
# DEPRECATED - Do not use for new projects
+specfact implement tasks [OPTIONS]
+
+ +

Migration Guide:

+ +

Replace implement tasks with the new AI IDE bridge workflow:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Old CommandNew Workflow
specfact implement tasks1. specfact generate fix-prompt GAP-ID
 2. Copy prompt to AI IDE
 3. AI IDE provides the implementation
 4. specfact enforce sdd to validate
+ +

Why Deprecated:

+ +
    +
  • AI IDE integration provides better context awareness
    • +
  • Human-in-the-loop validation before code changes
    • +
  • Works with any AI IDE (Cursor, Copilot, Claude, etc.)
    • +
  • More reliable and controllable than direct code generation
    • +
+ +

Recommended Replacements:

+ +
    +
  • Fix gaps: specfact generate fix-prompt
    • +
  • Add tests: specfact generate test-prompt
    • +
  • Add contracts: specfact generate contracts-prompt
    • +
+ +
+

⚠️ REMOVED in v0.22.0: The specfact generate tasks command has been removed. Per SPECFACT_0x_TO_1x_BRIDGE_PLAN.md, SpecFact CLI does not create plan → feature → task (that’s the job for spec-kit, openspec, etc.). We complement those SDD tools to enforce tests and quality.

+
+ +

See: Migration Guide (0.16 to 0.19) for detailed migration instructions.

+ +
+ +

init - Initialize IDE Integration

+ +

Set up SpecFact CLI for IDE integration by copying prompt templates to IDE-specific locations.

+ +
specfact init [OPTIONS]
+
+ +

Options:

+ +
    +
  • --repo PATH - Repository path (default: current directory)
    • +
  • --force - Overwrite existing files
    • +
  • --install-deps - Install required packages for contract enhancement (beartype, icontract, crosshair-tool, pytest) via pip
    • +
+ +

Advanced Options (hidden by default, use --help-advanced or -ha to view):

+ +
    +
  • --ide TEXT - IDE type (auto, cursor, vscode, copilot, claude, gemini, qwen, opencode, windsurf, kilocode, auggie, roo, codebuddy, amp, q) (default: auto)
    • +
+ +

Examples:

+ +
# Auto-detect IDE
+specfact init
+
+# Specify IDE explicitly
+specfact init --ide cursor
+specfact init --ide vscode
+specfact init --ide copilot
+
+# Force overwrite existing files
+specfact init --ide cursor --force
+
+# Install required packages for contract enhancement
+specfact init --install-deps
+
+# Initialize IDE integration and install dependencies
+specfact init --ide cursor --install-deps
+
+ +

What it does:

+ +
    +
  1. Detects your IDE (or uses --ide flag)
    2. +
  2. Copies prompt templates from resources/prompts/ to IDE-specific location at the repository root level
    3. +
  3. Creates/updates VS Code settings.json if needed (for VS Code/Copilot)
    4. +
  4. Makes slash commands available in your IDE
    5. +
  5. Optionally installs required packages for contract enhancement (if --install-deps is provided): +
      +
    • beartype>=0.22.4 - Runtime type checking
      • +
    • icontract>=2.7.1 - Design-by-contract decorators
      • +
    • crosshair-tool>=0.0.97 - Contract exploration
      • +
    • pytest>=8.4.2 - Testing framework
      • +
    +
    6. +
+ +

Important: Templates are always copied to the repository root level (where .github/, .cursor/, etc. directories must reside for IDE recognition). The --repo parameter specifies the repository root path. For multi-project codebases, run specfact init from the repository root to ensure IDE integration works correctly.

+ +

IDE-Specific Locations:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDEDirectoryFormat
Cursor.cursor/commands/Markdown
VS Code / Copilot.github/prompts/.prompt.md
Claude Code.claude/commands/Markdown
Gemini.gemini/commands/TOML
Qwen.qwen/commands/TOML
And more…See IDE Integration GuideMarkdown
+ +

See IDE Integration Guide for detailed setup instructions and all supported IDEs.

+ +
+ +

IDE Integration (Slash Commands)

+ +

Slash commands provide an intuitive interface for IDE integration (VS Code, Cursor, GitHub Copilot, etc.).

+ +

Available Slash Commands

+ +

Core Workflow Commands (numbered for workflow ordering):

+ +
    +
  1. /specfact.01-import [args] - Import codebase into plan bundle (replaces specfact-import-from-code)
    2. +
  2. /specfact.02-plan [args] - Plan management: init, add-feature, add-story, update-idea, update-feature, update-story (replaces specfact-plan-init, specfact-plan-add-feature, specfact-plan-add-story, specfact-plan-update-idea, specfact-plan-update-feature)
    3. +
  3. /specfact.03-review [args] - Review plan and promote (replaces specfact-plan-review, specfact-plan-promote)
    4. +
  4. /specfact.04-sdd [args] - Create SDD manifest (new, based on plan harden)
    5. +
  5. /specfact.05-enforce [args] - SDD enforcement (replaces specfact-enforce)
    6. +
  6. /specfact.06-sync [args] - Sync operations (replaces specfact-sync)
    7. +
  7. /specfact.07-contracts [args] - Contract enhancement workflow: analyze → generate prompts → apply contracts sequentially
    8. +
+ +

Advanced Commands (no numbering):

+ +
    +
  • /specfact.compare [args] - Compare plans (replaces specfact-plan-compare)
    • +
  • /specfact.validate [args] - Validation suite (replaces specfact-repro)
    • +
  • /specfact.generate-contracts-prompt [args] - Generate AI IDE prompt for adding contracts (see generate contracts-prompt)
    • +
+ +

Setup

+ +
# Initialize IDE integration (one-time setup)
+specfact init --ide cursor
+
+# Or auto-detect IDE
+specfact init
+
+# Initialize and install required packages for contract enhancement
+specfact init --install-deps
+
+# Initialize for specific IDE and install dependencies
+specfact init --ide cursor --install-deps
+
+ +

Usage

+ +

After initialization, use slash commands directly in your IDE’s AI chat:

+ +
# In IDE chat (Cursor, VS Code, Copilot, etc.)
+# Core workflow (numbered for natural progression)
+/specfact.01-import legacy-api --repo .
+/specfact.02-plan init legacy-api
+/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth"
+/specfact.03-review legacy-api
+/specfact.04-sdd legacy-api
+/specfact.05-enforce legacy-api
+/specfact.06-sync --repo . --adapter speckit
+/specfact.07-contracts legacy-api --apply all-contracts  # Analyze, generate prompts, apply contracts sequentially
+
+# Advanced commands
+/specfact.compare --bundle legacy-api
+/specfact.validate --repo .
+
+ +

How it works:

+ +

Slash commands are prompt templates (markdown files) that are copied to IDE-specific locations by specfact init. The IDE automatically discovers and registers them as slash commands.

+ +

See IDE Integration Guide for detailed setup instructions and supported IDEs.

+ +
+ +

Environment Variables

+ +
    +
  • SPECFACT_CONFIG - Path to config file (default: .specfact/config.yaml)
    • +
  • SPECFACT_VERBOSE - Enable verbose output (0/1)
    • +
  • SPECFACT_NO_COLOR - Disable colored output (0/1)
    • +
  • SPECFACT_MODE - Operational mode (cicd or copilot)
    • +
  • COPILOT_API_URL - CoPilot API endpoint (for CoPilot mode detection)
    • +
+ +
+ +

Configuration File

+ +

Create .specfact.yaml in project root:

+ +
version: "1.0"
+
+# Enforcement settings
+enforcement:
+  preset: balanced
+  custom_rules: []
+
+# Analysis settings
+analysis:
+  confidence_threshold: 0.7
+  include_tests: true
+  exclude_patterns:
+    - "**/__pycache__/**"
+    - "**/node_modules/**"
+
+# Import settings
+import:
+  default_branch: feat/specfact-migration
+  preserve_history: true
+
+# Repro settings
+repro:
+  budget: 120
+  parallel: true
+  fail_fast: false
+
+ +
+ +

Exit Codes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeMeaning
0Success
1Validation/enforcement failed
2Time budget exceeded
3Configuration error
4File not found
5Invalid arguments
+ +
+ +

Shell Completion

+ +

SpecFact CLI supports native shell completion for bash, zsh, and fish without requiring any extensions. Completion works automatically once installed.

+ +

Quick Install

+ +

Use Typer’s built-in completion commands:

+ +
# Auto-detect shell and install (recommended)
+specfact --install-completion
+
+# Explicitly specify shell
+specfact --install-completion bash   # or zsh, fish
+
+ +

Show Completion Script

+ +

To view the completion script without installing:

+ +
# Auto-detect shell
+specfact --show-completion
+
+# Explicitly specify shell
+specfact --show-completion bash
+
+ +

Manual Installation

+ +

You can also manually add completion to your shell config:

+ +

Bash

+ +
# Add to ~/.bashrc
+eval "$(_SPECFACT_COMPLETE=bash_source specfact)"
+
+ +

Zsh

+ +
# Add to ~/.zshrc
+eval "$(_SPECFACT_COMPLETE=zsh_source specfact)"
+
+ +

Fish

+ +
# Add to ~/.config/fish/config.fish
+eval (env _SPECFACT_COMPLETE=fish_source specfact)
+
+ +

PowerShell

+ +

PowerShell completion requires the click-pwsh extension:

+ +
pip install click-pwsh
+python -m click_pwsh install specfact
+
+ +

Ubuntu/Debian Notes

+ +

On Ubuntu and Debian systems, /bin/sh points to dash instead of bash. SpecFact CLI automatically normalizes shell detection to use bash for completion, so auto-detection works correctly even on these systems.

+ +

If you encounter “Shell sh not supported” errors, explicitly specify the shell:

+ +
specfact --install-completion bash
+
+ +
+ + + + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/reference/feature-keys.md b/_site_test/reference/feature-keys.md new file mode 100644 index 0000000..c97005c --- /dev/null +++ b/_site_test/reference/feature-keys.md @@ -0,0 +1,250 @@ +# Feature Key Normalization + +Reference documentation for feature key formats and normalization in SpecFact CLI. + +## Overview + +SpecFact CLI supports multiple feature key formats to accommodate different use cases and historical plans. The normalization system ensures consistent comparison and merging across different formats. + +## Supported Key Formats + +### 1. Classname Format (Default) + +**Format**: `FEATURE-CLASSNAME` + +**Example**: `FEATURE-CONTRACTFIRSTTESTMANAGER` + +**Use case**: Auto-derived plans from brownfield analysis + +**Generation**: + +```bash +specfact import from-code --key-format classname +``` + +### 2. Sequential Format + +**Format**: `FEATURE-001`, `FEATURE-002`, `FEATURE-003`, ... + +**Example**: `FEATURE-001` + +**Use case**: Manual plans and greenfield development + +**Generation**: + +```bash +specfact import from-code --key-format sequential +``` + +**Manual creation**: When creating plans interactively, use `FEATURE-001` format: + +```bash +specfact plan init +# Enter feature key: FEATURE-001 +``` + +### 3. Underscore Format (Legacy) + +**Format**: `000_FEATURE_NAME` or `001_FEATURE_NAME` + +**Example**: `000_CONTRACT_FIRST_TEST_MANAGER` + +**Use case**: Legacy plans or plans imported from other systems + +**Note**: This format is supported for comparison but not generated by the analyzer. + +## Normalization + +The normalization system automatically handles different formats when comparing plans: + +### How It Works + +1. **Normalize keys**: Remove prefixes (`FEATURE-`, `000_`) and underscores +2. **Compare**: Match features by normalized key +3. **Display**: Show original keys in reports + +### Example + +```python +from specfact_cli.utils.feature_keys import normalize_feature_key + +# These all normalize to the same key: +normalize_feature_key("000_CONTRACT_FIRST_TEST_MANAGER") +# → "CONTRACTFIRSTTESTMANAGER" + +normalize_feature_key("FEATURE-CONTRACTFIRSTTESTMANAGER") +# → "CONTRACTFIRSTTESTMANAGER" + +normalize_feature_key("FEATURE-001") +# → "001" +``` + +## Automatic Normalization + +### Plan Comparison + +The `plan compare` command automatically normalizes keys: + +```bash +specfact plan compare --manual main.bundle.yaml --auto auto-derived.yaml +``` + +**Behavior**: Features with different key formats but the same normalized key are matched correctly. + +### Plan Merging + +When merging plans (e.g., via `sync bridge --adapter speckit`), normalization ensures features are matched correctly: + +```bash +specfact sync bridge --adapter speckit --bundle --bidirectional +``` + +**Behavior**: Features are matched by normalized key, not exact key format. + +## Converting Key Formats + +### Using Python Utilities + +```python +from specfact_cli.utils.feature_keys import ( + convert_feature_keys, + to_sequential_key, + to_classname_key, +) + +# Convert to sequential format +features_seq = convert_feature_keys(features, target_format="sequential", start_index=1) + +# Convert to classname format +features_class = convert_feature_keys(features, target_format="classname") +``` + +### Command-Line (Future) + +A `plan normalize` command may be added in the future to convert existing plans: + +```bash +# (Future) Convert plan to sequential format +specfact plan normalize --from main.bundle.yaml --to main-sequential.yaml --output-format sequential +``` + +## Best Practices + +### 1. Choose a Consistent Format + +**Recommendation**: Use **sequential format** (`FEATURE-001`) for new plans: + +- ✅ Easy to reference in documentation +- ✅ Clear ordering +- ✅ Standard format for greenfield plans + +**Auto-derived plans**: Use **classname format** (`FEATURE-CLASSNAME`): + +- ✅ Directly maps to codebase classes +- ✅ Self-documenting +- ✅ Easy to trace back to source code + +### 2. Don't Worry About Format Differences + +**Key insight**: The normalization system handles format differences automatically: + +- ✅ Comparison works across formats +- ✅ Merging works across formats +- ✅ Reports show original keys + +**Action**: Choose the format that fits your workflow; the system handles the rest. + +### 3. Use Sequential for Manual Plans + +When creating plans manually or interactively: + +```bash +specfact plan init +# Enter feature key: FEATURE-001 # ← Use sequential format +# Enter feature title: User Authentication +``` + +**Why**: Sequential format is easier to reference and understand in documentation. + +### 4. Let Analyzer Use Classname Format + +When analyzing existing codebases: + +```bash +specfact import from-code --key-format classname # ← Default, explicit for clarity +``` + +**Why**: Classname format directly maps to codebase structure, making it easy to trace features back to classes. + +## Migration Guide + +### Converting Existing Plans + +If you have a plan with `000_FEATURE_NAME` format and want to convert: + +1. **Load the plan**: + + ```python + from specfact_cli.utils import load_yaml + from specfact_cli.utils.feature_keys import convert_feature_keys + + plan_data = load_yaml("main.bundle.yaml") + features = plan_data["features"] + ``` + +2. **Convert to sequential**: + + ```python + converted = convert_feature_keys(features, target_format="sequential", start_index=1) + plan_data["features"] = converted + ``` + +3. **Save the plan**: + + ```python + from specfact_cli.utils import dump_yaml + + dump_yaml(plan_data, "main-sequential.yaml") + ``` + +### Recommended Migration + +**For existing plans**: Keep the current format; normalization handles comparison automatically. + +**For new plans**: Use sequential format (`FEATURE-001`) for consistency. + +## Troubleshooting + +### Feature Not Matching Between Plans + +**Issue**: Features appear as "missing" even though they exist in both plans. + +**Solution**: Check if keys normalize to the same value: + +```python +from specfact_cli.utils.feature_keys import normalize_feature_key + +key1 = "000_CONTRACT_FIRST_TEST_MANAGER" +key2 = "FEATURE-CONTRACTFIRSTTESTMANAGER" + +print(normalize_feature_key(key1)) # Should match +print(normalize_feature_key(key2)) # Should match +``` + +### Key Format Not Recognized + +**Issue**: Key format doesn't match expected patterns. + +**Solution**: The normalization system is flexible and handles variations: + +- `FEATURE-XXX` → normalized +- `000_XXX` → normalized +- `XXX` → normalized (no prefix) + +**Note**: If normalization fails, check the key manually for special characters or unusual formats. + +## See Also + +- [Brownfield Analysis](../guides/use-cases.md#use-case-2-brownfield-code-hardening) - Explains why different formats exist +- [Plan Comparison](../reference/commands.md#plan-compare) - How comparison works with normalization +- [Plan Sync](../reference/commands.md#sync) - How sync handles different formats diff --git a/_site_test/reference/index.html b/_site_test/reference/index.html new file mode 100644 index 0000000..7a2f1a0 --- /dev/null +++ b/_site_test/reference/index.html @@ -0,0 +1,272 @@ + + + + + + + +Reference Documentation | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Reference Documentation

+ +

Complete technical reference for SpecFact CLI.

+ +

Available References

+ + + +

Quick Reference

+ +

Commands

+ +
    +
  • specfact import from-bridge --adapter speckit - Import from external tools via bridge adapter
    • +
  • specfact import from-code <bundle-name> - Reverse-engineer plans from code
    • +
  • specfact plan init <bundle-name> - Initialize new development plan
    • +
  • specfact plan compare - Compare manual vs auto plans
    • +
  • specfact enforce stage - Configure quality gates
    • +
  • specfact repro - Run full validation suite
    • +
  • specfact sync bridge --adapter <adapter> --bundle <bundle-name> - Sync with external tools via bridge adapter
    • +
  • specfact spec validate [--bundle <name>] - Validate OpenAPI/AsyncAPI specifications
    • +
  • specfact spec generate-tests [--bundle <name>] - Generate contract tests from specifications
    • +
  • specfact spec mock [--bundle <name>] - Launch mock server for development
    • +
  • specfact init - Initialize IDE integration
    • +
+ +

Modes

+ +
    +
  • CI/CD Mode - Fast, deterministic execution
    • +
  • CoPilot Mode - Enhanced prompts with context injection
    • +
+ +

IDE Integration

+ + + +

Technical Details

+ + + + + + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/reference/parameter-standard.md b/_site_test/reference/parameter-standard.md new file mode 100644 index 0000000..1462839 --- /dev/null +++ b/_site_test/reference/parameter-standard.md @@ -0,0 +1,246 @@ +# Parameter Standard + +**Date**: 2025-11-26 +**Status**: Active +**Purpose**: Standardize parameter names and grouping across all SpecFact CLI commands + +--- + +## 📋 Overview + +This document defines the standard parameter names, groupings, and conventions for all SpecFact CLI commands. All commands must follow these standards for consistency and improved user experience. + +--- + +## 🎯 Parameter Naming Conventions + +### Standard Parameter Names + +| Concept | Standard Name | Deprecated Names | Notes | +|---------|--------------|------------------|-------| +| Repository path | `--repo` | `--base-path` | Use `--repo` for repository root path | +| Output file path | `--out` | `--output` | Use `--out` for output file paths | +| Output format | `--output-format` | `--format` | Use `--output-format` for format specification | +| Interactive mode | `--interactive/--no-interactive` | `--non-interactive` | Use `--interactive/--no-interactive` for mode control | +| Project bundle | `--bundle` | `--name`, `--plan` (when used for bundle name) | Use `--bundle` for project bundle name | +| Plan bundle path | `--plan` | N/A | Use `--plan` for plan bundle file/directory path | +| SDD manifest path | `--sdd` | N/A | Use `--sdd` for SDD manifest file path | + +### Deprecation Policy + +- **Transition Period**: 3 months from implementation date +- **Deprecation Warnings**: Commands using deprecated names will show warnings +- **Removal**: Deprecated names will be removed after transition period +- **Documentation**: All examples and docs updated immediately + +--- + +## 📊 Parameter Grouping + +Parameters must be organized into logical groups in the following order: + +### Group 1: Target/Input (Required) + +**Purpose**: What to operate on + +**Parameters**: + +- `--bundle NAME` - Project bundle name (required for modular structure) +- `--repo PATH` - Repository path (default: ".") +- `--plan PATH` - Plan bundle path (default: active plan for bundle) +- `--sdd PATH` - SDD manifest path (default: bundle-specific .specfact/projects//sdd.yaml, Phase 8.5, with fallback to legacy .specfact/sdd/.yaml) +- `--constitution PATH` - Constitution path (default: .specify/memory/constitution.md) + +**Help Text Format**: + +```python +# Target/Input +--bundle NAME # Project bundle name (required) +--repo PATH # Repository path (default: ".") +--plan PATH # Plan bundle path (default: active plan for bundle) +``` + +### Group 2: Output/Results + +**Purpose**: Where to write results + +**Parameters**: + +- `--out PATH` - Output file path (default: auto-generated) +- `--report PATH` - Report file path (default: auto-generated) +- `--output-format FMT` - Output format: yaml, json, markdown (default: yaml) + +**Help Text Format**: + +```python +# Output/Results +--out PATH # Output file path (default: auto-generated) +--report PATH # Report file path (default: auto-generated) +--output-format FMT # Output format: yaml, json, markdown (default: yaml) +``` + +### Group 3: Behavior/Options + +**Purpose**: How to operate + +**Parameters**: + +- `--interactive/--no-interactive` - Interactive mode (default: auto-detect) +- `--force` - Overwrite existing files +- `--dry-run` - Preview without writing +- `--verbose` - Verbose output +- `--shadow-only` - Observe without enforcing + +**Help Text Format**: + +```python +# Behavior/Options +--interactive # Interactive mode (default: auto-detect) +--no-interactive # Non-interactive mode (for CI/CD) +--force # Overwrite existing files +--dry-run # Preview without writing +--verbose # Verbose output +``` + +### Group 4: Advanced/Configuration + +**Purpose**: Advanced settings and configuration + +**Parameters**: + +- `--confidence FLOAT` - Confidence threshold: 0.0-1.0 (default: 0.5) +- `--budget SECONDS` - Time budget in seconds (default: 120) +- `--preset PRESET` - Enforcement preset: minimal, balanced, strict (default: balanced) +- `--max-questions INT` - Maximum questions per session (default: 5) + +**Help Text Format**: + +```python +# Advanced/Configuration +--confidence FLOAT # Confidence threshold: 0.0-1.0 (default: 0.5) +--budget SECONDS # Time budget in seconds (default: 120) +--preset PRESET # Enforcement preset: minimal, balanced, strict (default: balanced) +``` + +--- + +## 🔄 Parameter Changes Required + +### Phase 1.2: Rename Inconsistent Parameters ✅ **COMPLETED** + +The following parameters have been renamed: + +1. **`--base-path` → `--repo`** ✅ + - **File**: `src/specfact_cli/commands/generate.py` + - **Command**: `generate contracts` + - **Status**: Completed - Parameter renamed and all references updated + +2. **`--output` → `--out`** ✅ + - **File**: `src/specfact_cli/commands/constitution.py` + - **Command**: `constitution bootstrap` + - **Status**: Completed - Parameter renamed and all references updated + +3. **`--format` → `--output-format`** ✅ + - **Files**: + - `src/specfact_cli/commands/plan.py` (plan compare command) + - `src/specfact_cli/commands/enforce.py` (enforce sdd command) + - **Status**: Completed - Parameters renamed and all references updated + +4. **`--non-interactive` → `--no-interactive`** ✅ + - **Files**: + - `src/specfact_cli/cli.py` (global flag) + - `src/specfact_cli/commands/plan.py` (multiple commands) + - `src/specfact_cli/commands/enforce.py` (enforce sdd command) + - `src/specfact_cli/commands/generate.py` (generate contracts command) + - **Status**: Completed - Global flag and all command flags updated, interaction logic fixed + +### Phase 1.3: Verify `--bundle` Parameter ✅ **COMPLETED** + +**Commands with `--bundle` Parameter**: + +| Command | Parameter Type | Status | Notes | +|---------|---------------|--------|-------| +| `plan init` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `plan review` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `plan promote` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `plan harden` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `enforce sdd` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `import from-code` | Required Argument | ✅ | `bundle: str = typer.Argument(...)` | +| `plan add-feature` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` with validation | +| `plan add-story` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` with validation | +| `plan update-idea` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` with validation | +| `plan update-feature` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` with validation | +| `plan update-story` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` with validation | +| `plan compare` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` - Added for consistency | +| `generate contracts` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` - Added, prioritizes bundle over plan/sdd | +| `sync bridge` | Optional Option | ✅ | `bundle: str \| None = typer.Option(...)` - Auto-detects if not provided | + +**Validation Improvements**: + +- ✅ Enhanced `_find_bundle_dir()` function with better error messages +- ✅ Lists available bundles when bundle not found +- ✅ Suggests similar bundle names +- ✅ Provides clear creation instructions +- ✅ All commands with optional `--bundle` have fallback logic to find default bundle +- ✅ Help text updated to indicate when `--bundle` is required vs optional + +--- + +## ✅ Validation Checklist + +Before marking a command as compliant: + +- [ ] All parameters use standard names (no deprecated names) +- [ ] Parameters grouped in correct order (Target → Output → Behavior → Advanced) +- [ ] Help text shows parameter groups with comments +- [ ] Defaults shown explicitly in help text +- [ ] Deprecation warnings added for old names (if applicable) +- [ ] Tests updated to use new parameter names +- [ ] Documentation updated with new parameter names + +--- + +## 📝 Examples + +### Before (Inconsistent) + +```python +@app.command("contracts") +def generate_contracts( + base_path: Path | None = typer.Option(None, "--base-path", help="Base directory"), + non_interactive: bool = typer.Option(False, "--non-interactive", help="Non-interactive mode"), +) -> None: + ... +``` + +### After (Standardized) + +```python +@app.command("contracts") +def generate_contracts( + # Target/Input + repo: Path | None = typer.Option(None, "--repo", help="Repository path (default: current directory)"), + + # Behavior/Options + no_interactive: bool = typer.Option(False, "--no-interactive", help="Non-interactive mode (for CI/CD automation)"), +) -> None: + ... +``` + +--- + +## 🔗 Related Documentation + +- **[CLI Reorganization Implementation Plan](../../specfact-cli-internal/docs/internal/implementation/CLI_REORGANIZATION_IMPLEMENTATION_PLAN.md)** - Full reorganization plan +- **[Command Reference](./commands.md)** - Complete command reference +- **[Project Bundle Refactoring Plan](../../specfact-cli-internal/docs/internal/implementation/PROJECT_BUNDLE_REFACTORING_PLAN.md)** - Bundle parameter requirements + +--- + +**Rulesets Applied**: + +- Clean Code Principles (consistent naming, logical grouping) +- Estimation Bias Prevention (evidence-based standards) +- Markdown Rules (proper formatting, comprehensive structure) + +**AI Model**: Claude Sonnet 4.5 (claude-sonnet-4-20250514) diff --git a/_site_test/reference/specmatic.md b/_site_test/reference/specmatic.md new file mode 100644 index 0000000..c264673 --- /dev/null +++ b/_site_test/reference/specmatic.md @@ -0,0 +1,371 @@ +# Specmatic API Reference + +> **API Reference for Specmatic Integration** +> Complete reference for Specmatic functions, classes, and integration points + +--- + +## Overview + +The Specmatic integration module (`specfact_cli.integrations.specmatic`) provides functions and classes for validating OpenAPI/AsyncAPI specifications, checking backward compatibility, generating test suites, and running mock servers using Specmatic. + +**Module**: `specfact_cli.integrations.specmatic` + +--- + +## Functions + +### `check_specmatic_available() -> tuple[bool, str | None]` + +Check if Specmatic CLI is available (either directly or via npx). + +**Returns**: + +- `tuple[bool, str | None]`: `(is_available, error_message)` + - `is_available`: `True` if Specmatic is available, `False` otherwise + - `error_message`: Error message if not available, `None` if available + +**Example**: + +```python +from specfact_cli.integrations.specmatic import check_specmatic_available + +is_available, error_msg = check_specmatic_available() +if is_available: + print("Specmatic is available") +else: + print(f"Specmatic not available: {error_msg}") +``` + +--- + +### `validate_spec_with_specmatic(spec_path: Path, previous_version: Path | None = None) -> SpecValidationResult` + +Validate OpenAPI/AsyncAPI specification using Specmatic. + +**Parameters**: + +- `spec_path` (Path): Path to OpenAPI/AsyncAPI specification file +- `previous_version` (Path | None, optional): Optional path to previous version for backward compatibility check + +**Returns**: + +- `SpecValidationResult`: Validation result with status and details + +**Raises**: + +- No exceptions (returns result with `is_valid=False` if validation fails) + +**Example**: + +```python +from pathlib import Path +from specfact_cli.integrations.specmatic import validate_spec_with_specmatic +import asyncio + +spec_path = Path("api/openapi.yaml") +result = asyncio.run(validate_spec_with_specmatic(spec_path)) + +if result.is_valid: + print("Specification is valid") +else: + print(f"Validation failed: {result.errors}") +``` + +**Validation Checks**: + +1. **Schema Validation**: Validates OpenAPI/AsyncAPI schema structure +2. **Example Generation**: Tests that examples can be generated from the spec +3. **Backward Compatibility** (if `previous_version` provided): Checks for breaking changes + +--- + +### `check_backward_compatibility(old_spec: Path, new_spec: Path) -> tuple[bool, list[str]]` + +Check backward compatibility between two spec versions. + +**Parameters**: + +- `old_spec` (Path): Path to old specification version +- `new_spec` (Path): Path to new specification version + +**Returns**: + +- `tuple[bool, list[str]]`: `(is_compatible, breaking_changes)` + - `is_compatible`: `True` if backward compatible, `False` otherwise + - `breaking_changes`: List of breaking change descriptions + +**Raises**: + +- No exceptions (returns `(False, [])` if check fails) + +**Example**: + +```python +from pathlib import Path +from specfact_cli.integrations.specmatic import check_backward_compatibility +import asyncio + +old_spec = Path("api/openapi.v1.yaml") +new_spec = Path("api/openapi.v2.yaml") + +is_compatible, breaking_changes = asyncio.run( + check_backward_compatibility(old_spec, new_spec) +) + +if is_compatible: + print("Specifications are backward compatible") +else: + print(f"Breaking changes: {breaking_changes}") +``` + +--- + +### `generate_specmatic_tests(spec_path: Path, output_dir: Path | None = None) -> Path` + +Generate Specmatic test suite from specification. + +**Parameters**: + +- `spec_path` (Path): Path to OpenAPI/AsyncAPI specification +- `output_dir` (Path | None, optional): Optional output directory (default: `.specfact/specmatic-tests/`) + +**Returns**: + +- `Path`: Path to generated test directory + +**Raises**: + +- `RuntimeError`: If Specmatic is not available or test generation fails + +**Example**: + +```python +from pathlib import Path +from specfact_cli.integrations.specmatic import generate_specmatic_tests +import asyncio + +spec_path = Path("api/openapi.yaml") +output_dir = Path("tests/specmatic") + +test_dir = asyncio.run(generate_specmatic_tests(spec_path, output_dir)) +print(f"Tests generated in: {test_dir}") +``` + +--- + +### `create_mock_server(spec_path: Path, port: int = 9000, strict_mode: bool = True) -> MockServer` + +Create Specmatic mock server from specification. + +**Parameters**: + +- `spec_path` (Path): Path to OpenAPI/AsyncAPI specification +- `port` (int, optional): Port number for mock server (default: 9000) +- `strict_mode` (bool, optional): Use strict validation mode (default: True) + +**Returns**: + +- `MockServer`: Mock server instance + +**Raises**: + +- `RuntimeError`: If Specmatic is not available or mock server fails to start + +**Example**: + +```python +from pathlib import Path +from specfact_cli.integrations.specmatic import create_mock_server +import asyncio + +spec_path = Path("api/openapi.yaml") +mock_server = asyncio.run(create_mock_server(spec_path, port=8080)) + +print(f"Mock server running at http://localhost:{mock_server.port}") +# ... use mock server ... +mock_server.stop() +``` + +--- + +## Classes + +### `SpecValidationResult` + +Result of Specmatic validation. + +**Attributes**: + +- `is_valid` (bool): Overall validation status +- `schema_valid` (bool): Schema validation status +- `examples_valid` (bool): Example generation validation status +- `backward_compatible` (bool | None): Backward compatibility status (None if not checked) +- `errors` (list[str]): List of error messages +- `warnings` (list[str]): List of warning messages +- `breaking_changes` (list[str]): List of breaking changes (if backward compatibility checked) + +**Methods**: + +- `to_dict() -> dict[str, Any]`: Convert to dictionary +- `to_json(indent: int = 2) -> str`: Convert to JSON string + +**Example**: + +```python +from specfact_cli.integrations.specmatic import SpecValidationResult + +result = SpecValidationResult( + is_valid=True, + schema_valid=True, + examples_valid=True, + backward_compatible=True, +) + +print(result.to_json()) +# { +# "is_valid": true, +# "schema_valid": true, +# "examples_valid": true, +# "backward_compatible": true, +# "errors": [], +# "warnings": [], +# "breaking_changes": [] +# } +``` + +--- + +### `MockServer` + +Mock server instance. + +**Attributes**: + +- `port` (int): Port number +- `process` (subprocess.Popen[str] | None): Process handle (None if not running) +- `spec_path` (Path | None): Path to specification file + +**Methods**: + +- `is_running() -> bool`: Check if mock server is running +- `stop() -> None`: Stop the mock server + +**Example**: + +```python +from specfact_cli.integrations.specmatic import MockServer + +mock_server = MockServer(port=9000, spec_path=Path("api/openapi.yaml")) + +if mock_server.is_running(): + print("Mock server is running") + mock_server.stop() +``` + +--- + +## Integration Points + +### Import Command Integration + +The `import from-code` command automatically validates bundle contracts with Specmatic after import. + +**Location**: `specfact_cli.commands.import_cmd._validate_bundle_contracts()` + +**Behavior**: + +- Validates all contracts referenced in bundle features +- Shows validation results in console output +- Suggests mock server if contracts are found + +**Example Output**: + +``` +🔍 Validating 3 contract(s) in bundle with Specmatic... +Validating contracts/FEATURE-001.openapi.yaml (from FEATURE-001)... + ✓ FEATURE-001.openapi.yaml is valid +💡 Tip: Run 'specfact spec mock' to start a mock server for development +``` + +--- + +### Enforce Command Integration + +The `enforce sdd` command validates bundle contracts and reports failures as deviations. + +**Location**: `specfact_cli.commands.enforce.enforce_sdd()` + +**Behavior**: + +- Validates contracts referenced in bundle features +- Reports validation failures as `CONTRACT_VIOLATION` deviations +- Includes validation results in enforcement report + +**Example Output**: + +``` +Validating API contracts with Specmatic... +Found 2 contract(s) referenced in bundle +Validating contracts/FEATURE-001.openapi.yaml (from FEATURE-001)... + ⚠ FEATURE-001.openapi.yaml has validation issues + - Schema validation failed: Invalid schema +``` + +--- + +### Sync Command Integration + +The `sync bridge` command validates contracts before sync operation. + +**Location**: `specfact_cli.commands.sync.sync_bridge()` + +**Behavior**: + +- Validates contracts in bundle before sync +- Checks backward compatibility (if previous versions stored) +- Continues with sync even if validation fails (with warning) + +**Example Output**: + +``` +🔍 Validating OpenAPI contracts before sync... +Validating 2 contract(s)... +Validating contracts/FEATURE-001.openapi.yaml... + ✓ FEATURE-001.openapi.yaml is valid +✓ All contracts validated successfully +``` + +--- + +## Error Handling + +All functions handle errors gracefully: + +- **Specmatic Not Available**: Functions return appropriate error states or raise `RuntimeError` with helpful messages +- **Validation Failures**: Return `SpecValidationResult` with `is_valid=False` and error details +- **Timeout Errors**: Caught and reported in validation results +- **Process Errors**: Mock server creation failures raise `RuntimeError` with details + +--- + +## Command Detection + +Specmatic is automatically detected via: + +1. **Direct Installation**: `specmatic` command in PATH +2. **NPM/NPX**: `npx specmatic` (requires Java/JRE and Node.js) + +The module caches the detection result to avoid repeated checks. + +--- + +## Related Documentation + +- **[Specmatic Integration Guide](../guides/specmatic-integration.md)** - User guide with examples +- **[Spec Commands Reference](./commands.md#spec-commands)** - CLI command reference +- **[Specmatic Documentation](https://docs.specmatic.io/)** - Official Specmatic documentation + +--- + +**Last Updated**: 2025-12-05 diff --git a/_site_test/reference/telemetry.md b/_site_test/reference/telemetry.md new file mode 100644 index 0000000..410a626 --- /dev/null +++ b/_site_test/reference/telemetry.md @@ -0,0 +1,512 @@ +# Privacy-First Telemetry (Optional) + +> **Opt-in analytics that highlight how SpecFact prevents brownfield regressions.** + +SpecFact CLI ships with an **enterprise-grade, privacy-first telemetry system** that is **disabled by default** and only activates when you explicitly opt in. When enabled, we collect high-level, anonymized metrics to quantify outcomes like "what percentage of prevented regressions came from contract violations vs. plan drift." These insights help us communicate the value of SpecFact to the broader brownfield community (e.g., "71% of bugs caught by early adopters were surfaced only after contracts were introduced"). + +**Key Features:** + +- ✅ **Disabled by default** - Privacy-first, requires explicit opt-in +- ✅ **Local storage** - Data stored in `~/.specfact/telemetry.log` (you own it) +- ✅ **OTLP HTTP** - Standard OpenTelemetry Protocol, works with any collector +- ✅ **Test-aware** - Automatically disabled in test environments +- ✅ **Configurable** - Service name, batch settings, timeouts all customizable +- ✅ **Enterprise-ready** - Graceful error handling, retry logic, production-grade reliability + +--- + +## How to Opt In + +### Option 1: Local-only (No endpoint or auth needed) ⭐ Simplest + +**No authentication required!** Telemetry works out-of-the-box with local storage only. + +**Quick start:** + +```bash +# Enable telemetry (local storage only) +echo "true" > ~/.specfact/telemetry.opt-in +``` + +That's it! Telemetry data will be stored in `~/.specfact/telemetry.log` (JSONL format). You can inspect, rotate, or delete this file anytime. + +**Note:** If you later create `~/.specfact/telemetry.yaml` with `enabled: true`, the config file takes precedence and the `.opt-in` file is no longer needed. + +**Benefits:** + +- ✅ No setup required - works immediately +- ✅ No authentication needed +- ✅ Your data stays local (privacy-first) +- ✅ You own the data file + +### Option 2: Remote export (Requires endpoint and auth) + +If you want to send telemetry to a remote collector (for dashboards, analytics, etc.), you'll need: + +1. **An OTLP collector endpoint** (self-hosted or cloud service like Grafana Cloud) +2. **Authentication credentials** (if your collector requires auth) + +**When you need auth:** + +- Using a **cloud service** (Grafana Cloud, Honeycomb, etc.) - you sign up and get API keys +- Using a **self-hosted collector with auth** - you configure your own auth +- Using a **company's existing observability stack** - your team provides credentials + +**When you DON'T need auth:** + +- Using a **self-hosted collector without auth** (local development) +- **Local-only mode** (no endpoint = no auth needed) + +### Recommended: Config file (persistent) + +For remote export (or local-only with persistent config), create `~/.specfact/telemetry.yaml` with your telemetry configuration. + +**Important:** If you have `enabled: true` in `telemetry.yaml`, you **do NOT need** the `.opt-in` file. The config file takes precedence. The `.opt-in` file is only used as a fallback if the config file doesn't exist or has `enabled: false`. + +**Quick start:** Copy the example template: + +```bash +# Copy the example template +cp resources/templates/telemetry.yaml.example ~/.specfact/telemetry.yaml + +# Or if installed via pip/uvx, find it in the package: +# On Linux/Mac: ~/.local/share/specfact-cli/resources/templates/telemetry.yaml.example +# Then edit ~/.specfact/telemetry.yaml with your settings +``` + +**Manual setup:** Create `~/.specfact/telemetry.yaml` with your telemetry configuration: + +```yaml +# Enable telemetry +enabled: true + +# OTLP endpoint (HTTPS recommended for corporate environments) +# Example for Grafana Cloud: +endpoint: "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp/v1/traces" + +# Authentication headers +# For Grafana Cloud, use Basic auth with your instance-id:api-key (base64 encoded) +headers: + Authorization: "Basic YOUR_BASE64_ENCODED_CREDENTIALS_HERE" + +# Optional: Advanced configuration +service_name: "specfact-cli" # Custom service name (default: "specfact-cli") +batch_size: 512 # Batch size (default: 512) +batch_timeout: 5 # Batch timeout in seconds (default: 5) +export_timeout: 10 # Export timeout in seconds (default: 10) +debug: false # Enable console output for debugging (default: false) +local_path: "~/.specfact/telemetry.log" # Local log file path (default: ~/.specfact/telemetry.log) +``` + +**Benefits:** + +- Persistent configuration (survives shell restarts) +- All settings in one place +- Easy to version control or share with team +- Environment variables can still override (for temporary changes) + +### Alternative: Environment variables (temporary) + +```bash +# Basic opt-in (local storage only) +export SPECFACT_TELEMETRY_OPT_IN=true + +# Optional: send events to your own OTLP collector +export SPECFACT_TELEMETRY_ENDPOINT="https://telemetry.yourcompany.com/v1/traces" +export SPECFACT_TELEMETRY_HEADERS="Authorization: Bearer xxxx" + +# Advanced configuration (optional) +export SPECFACT_TELEMETRY_SERVICE_NAME="my-specfact-instance" # Custom service name +export SPECFACT_TELEMETRY_BATCH_SIZE="1024" # Batch size (default: 512) +export SPECFACT_TELEMETRY_BATCH_TIMEOUT="10" # Batch timeout in seconds (default: 5) +export SPECFACT_TELEMETRY_EXPORT_TIMEOUT="30" # Export timeout in seconds (default: 10) +export SPECFACT_TELEMETRY_DEBUG="true" # Enable console output for debugging +``` + +**Note:** Environment variables override config file settings (useful for temporary testing). + +### Legacy: Simple opt-in file (backward compatibility) + +Create `~/.specfact/telemetry.opt-in` with: + +```text +true +``` + +Remove the file (or set it to `false`) to opt out again. + +**Note:** This method only enables telemetry with local storage. For OTLP export, use the config file or environment variables. + +**Precedence:** If you have both `telemetry.yaml` (with `enabled: true`) and `telemetry.opt-in`, the config file takes precedence. The `.opt-in` file is only checked if the config file doesn't exist or has `enabled: false`. + +### Local storage only (default) + +If no OTLP endpoint is provided, telemetry is persisted as JSON lines in `~/.specfact/telemetry.log`. You own this file—feel free to rotate, inspect, or delete it at any time. + +--- + +## Data We Collect (and Why) + +| Field | Description | Example | +| --- | --- | --- | +| `command` | CLI command identifier | `import.from_code` | +| `mode` | High-level command family | `repro` | +| `execution_mode` | How the command ran (agent vs. AST) | `agent` | +| `files_analyzed` | Count of Python files scanned (rounded) | `143` | +| `features_detected` | Number of features plan import discovered | `27` | +| `stories_detected` | Total stories extracted from code | `112` | +| `checks_total` | Number of validation checks executed | `6` | +| `checks_failed` / `violations_detected` | How many checks or contracts failed | `2` | +| `duration_ms` | Command duration (auto-calculated) | `4280` | +| `success` | Whether the CLI exited successfully | `true` | + +**We never collect:** + +- Repository names or paths +- File contents or snippets +- Usernames, emails, or hostnames + +--- + +## Why Opt In? (Win-Win-Win) + +Telemetry creates a **mutual benefit cycle**: you help us build better features, we prioritize what you need, and the community benefits from collective insights. + +### 🎯 For You (The User) + +**Shape the roadmap:** + +- Your usage patterns directly influence what we build next +- Features you use get prioritized and improved +- Pain points you experience get fixed faster + +**Validate your approach:** + +- Compare your metrics against community benchmarks +- See if your results align with other users +- Build confidence that you're using SpecFact effectively + +**Get better features:** + +- Data-driven prioritization means we build what matters +- Your usage helps us understand real-world needs +- You benefit from features built based on actual usage patterns + +**Prove value:** + +- Community metrics help justify adoption to your team +- "X% of users prevented Y violations" is more convincing than anecdotes +- Helps make the case for continued investment + +### 🚀 For SpecFact (The Project) + +**Understand real usage:** + +- See which commands are actually used most +- Identify pain points and unexpected use cases +- Discover patterns we wouldn't know otherwise + +**Prioritize effectively:** + +- Focus development on high-impact features +- Fix bugs that affect many users +- Avoid building features nobody uses + +**Prove the tool works:** + +- Aggregate metrics demonstrate real impact +- "Contracts caught 3.7x more bugs than tests" is more credible with data +- Helps attract more users and contributors + +**Build credibility:** + +- Public dashboards show transparency +- Data-backed claims are more trustworthy +- Helps the project grow and succeed + +### 🌍 For the Community + +**Collective proof:** + +- Aggregate metrics validate the contract-driven approach +- Helps others decide whether to adopt SpecFact +- Builds momentum for the methodology + +**Knowledge sharing:** + +- See what works for other teams +- Learn from community patterns +- Avoid common pitfalls + +**Open source contribution:** + +- Low-effort way to contribute to the project +- Helps SpecFact succeed, which benefits everyone +- Your anonymized data helps the entire community + +### Real-World Impact + +**Without telemetry:** + +- Roadmap based on assumptions +- Hard to prove impact +- Features may not match real needs + +**With telemetry:** + +- "71% of bugs caught by early adopters were contract violations" +- "Average user prevented 12 regressions per week" +- "Most-used command: `import.from_code` (67% of sessions)" +- Roadmap based on real usage data + +### The Privacy Trade-Off + +**What you share:** + +- Anonymized usage patterns (commands, metrics, durations) +- No personal data, repository names, or file contents + +**What you get:** + +- Better tool (features you need get prioritized) +- Validated approach (compare against community) +- Community insights (learn from others' patterns) + +**You're in control:** + +- Can opt-out anytime +- Data stays local by default +- Choose where to send data (if anywhere) + +--- + +## Routing Telemetry to Your Stack + +### Scenario 1: Local-only (No setup needed) + +If you just want to track your own usage locally, **no endpoint or authentication is required**: + +```bash +# Enable telemetry (local storage only) +echo "true" > ~/.specfact/telemetry.opt-in +``` + +Data will be stored in `~/.specfact/telemetry.log`. That's it! + +### Scenario 2: Self-hosted collector (No auth required) + +If you're running your own OTLP collector locally or on your network without authentication: + +```yaml +# ~/.specfact/telemetry.yaml +enabled: true +endpoint: "http://localhost:4318/v1/traces" # Your local collector +# No headers needed if collector doesn't require auth +``` + +### Scenario 3: Cloud service (Auth required) + +If you're using a cloud service like Grafana Cloud, you'll need to: + +1. **Sign up for the service** (e.g., ) +2. **Get your API credentials** from the service dashboard +3. **Configure SpecFact** with the endpoint and credentials + +**Example for Grafana Cloud:** + +1. Sign up at (free tier available) +2. Go to "Connections" → "OpenTelemetry" → "Send traces" +3. Copy your endpoint URL and API key +4. Configure SpecFact: + +```yaml +# ~/.specfact/telemetry.yaml +enabled: true +endpoint: "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp/v1/traces" +headers: + Authorization: "Basic YOUR_BASE64_ENCODED_CREDENTIALS_HERE" + +# Optional: Resource attributes (recommended for Grafana Cloud) +service_name: "specfact-cli" # Service name (default: "specfact-cli") +service_namespace: "cli" # Service namespace (default: "cli") +deployment_environment: "production" # Deployment environment (default: "production") +``` + +**Where to get credentials:** + +- **Grafana Cloud**: Dashboard → Connections → OpenTelemetry → API key +- **Honeycomb**: Settings → API Keys → Create new key +- **SigNoz Cloud**: Settings → API Keys +- **Your company's stack**: Ask your DevOps/Platform team + +### Scenario 4: Company observability stack (Team provides credentials) + +If your company already has an observability stack (Tempo, Jaeger, etc.): + +1. **Ask your team** for the OTLP endpoint URL +2. **Get authentication credentials** (API key, token, etc.) +3. **Configure SpecFact** with the provided endpoint and auth + +### Using Config File (Recommended for remote export) + +1. Deploy or reuse an OTLP collector that supports HTTPS (Tempo, Honeycomb, SigNoz, Grafana Cloud, etc.). +2. Copy the example template and customize it: + +```bash +# Copy the template +cp resources/templates/telemetry.yaml.example ~/.specfact/telemetry.yaml + +# Edit with your settings +nano ~/.specfact/telemetry.yaml +``` + +Or create `~/.specfact/telemetry.yaml` manually with your endpoint and authentication: + +```yaml +enabled: true +endpoint: "https://your-collector.com/v1/traces" +headers: + Authorization: "Bearer your-token-here" +``` + +### Using Environment Variables + +1. Deploy or reuse an OTLP collector that supports HTTPS. +2. Set `SPECFACT_TELEMETRY_ENDPOINT` to your collector URL. +3. (Optional) Provide HTTP headers via `SPECFACT_TELEMETRY_HEADERS` for tokens or custom auth. +4. Keep `SPECFACT_TELEMETRY_OPT_IN=true`. + +**Note:** Environment variables override config file settings. + +SpecFact will continue writing the local JSON log **and** stream spans to your collector using the OpenTelemetry data model. + +--- + +## Inspecting & Deleting Data + +```bash +# View the most recent events +tail -n 20 ~/.specfact/telemetry.log | jq + +# Delete everything (immediate opt-out) +rm ~/.specfact/telemetry.log +unset SPECFACT_TELEMETRY_OPT_IN +``` + +--- + +## Advanced Configuration + +### Service Name Customization + +Customize the service name in your telemetry data: + +```bash +export SPECFACT_TELEMETRY_SERVICE_NAME="my-project-specfact" +``` + +This is useful when routing multiple projects to the same collector and want to distinguish between them. + +### Batch Processing Tuning + +Optimize batch processing for your use case: + +```bash +# Larger batches for high-volume scenarios +export SPECFACT_TELEMETRY_BATCH_SIZE="2048" + +# Longer timeouts for slower networks +export SPECFACT_TELEMETRY_BATCH_TIMEOUT="15" +export SPECFACT_TELEMETRY_EXPORT_TIMEOUT="60" +``` + +**Defaults:** + +- `BATCH_SIZE`: 512 spans +- `BATCH_TIMEOUT`: 5 seconds +- `EXPORT_TIMEOUT`: 10 seconds + +### Test Environment Detection + +Telemetry is **automatically disabled** in test environments. No configuration needed - we detect: + +- `TEST_MODE=true` environment variable +- `PYTEST_CURRENT_TEST` (set by pytest) + +This ensures tests run cleanly without telemetry overhead. + +### Debug Mode + +Enable console output to see telemetry events in real-time: + +```bash +export SPECFACT_TELEMETRY_DEBUG=true +``` + +Useful for troubleshooting telemetry configuration or verifying data collection. + +## FAQ + +**Do I need authentication to use telemetry?** + +**No!** Authentication is only required if you want to send telemetry to a remote collector (cloud service or company stack). For local-only mode, just enable telemetry - no endpoint or auth needed: + +```bash +echo "true" > ~/.specfact/telemetry.opt-in +``` + +**Where do I get authentication credentials?** + +**It depends on your setup:** + +- **Local-only mode**: No credentials needed ✅ +- **Self-hosted collector (no auth)**: No credentials needed ✅ +- **Grafana Cloud**: Sign up at → Get API key from dashboard +- **Honeycomb**: Sign up at → Settings → API Keys +- **Company stack**: Ask your DevOps/Platform team for endpoint and credentials + +**Do I need to set up my own collector?** + +**No!** Telemetry works with **local storage only** by default. If you want dashboards or remote analytics, you can optionally route to your own OTLP collector (self-hosted or cloud service). + +**Does telemetry affect performance?** + +No. We buffer metrics in-memory and write to disk at the end of each command. When OTLP export is enabled, spans are batched and sent asynchronously. Telemetry operations are non-blocking and won't slow down your CLI commands. + +**Can enterprises keep data on-prem?** +Yes. Point `SPECFACT_TELEMETRY_ENDPOINT` to an internal collector. Nothing leaves your network unless you decide to forward it. All data is stored locally in `~/.specfact/telemetry.log` by default. + +**Can I prove contracts are preventing bugs?** +Absolutely. We surface `violations_detected` from commands like `specfact repro` so you can compare "bugs caught by contracts" vs. "bugs caught by legacy tests" over time, and we aggregate the ratios (anonymously) to showcase SpecFact's brownfield impact publicly. + +**What happens if the collector is unavailable?** +Telemetry gracefully degrades - events are still written to local storage (`~/.specfact/telemetry.log`), and export failures are logged but don't affect your CLI commands. You can retry exports later by processing the local log file. + +**Is telemetry enabled in CI/CD?** +Only if you explicitly opt in. We recommend enabling telemetry in CI/CD to track brownfield adoption metrics, but it's completely optional. Test environments automatically disable telemetry. + +**How do I verify telemetry is working?** + +1. Enable debug mode: `export SPECFACT_TELEMETRY_DEBUG=true` +2. Run a command: `specfact import from-code --repo .` +3. Check local log: `tail -f ~/.specfact/telemetry.log` +4. Verify events appear in your OTLP collector (if configured) + +**Do I need both `telemetry.yaml` and `telemetry.opt-in`?** + +**No!** If you have `enabled: true` in `telemetry.yaml`, you **don't need** the `.opt-in` file. The config file takes precedence. The `.opt-in` file is only used as a fallback for backward compatibility or if you're using the simple local-only method without a config file. + +**Precedence order:** + +1. Environment variables (highest priority) +2. Config file (`telemetry.yaml` with `enabled: true`) +3. Simple opt-in file (`telemetry.opt-in`) - only if config file doesn't enable it +4. Defaults (disabled) + +--- + +**Related docs:** + +- [`docs/guides/brownfield-faq.md`](../guides/brownfield-faq.md) – Brownfield workflows +- [`docs/guides/brownfield-roi.md`](../guides/brownfield-roi.md) – Quantifying the savings +- [`docs/examples/brownfield-django-modernization.md`](../examples/brownfield-django-modernization.md) – Example pipeline diff --git a/_site_test/robots/index.txt b/_site_test/robots/index.txt new file mode 100644 index 0000000..b004bd4 --- /dev/null +++ b/_site_test/robots/index.txt @@ -0,0 +1 @@ +Sitemap: https://nold-ai.github.io/specfact-cli/sitemap.xml diff --git a/_site_test/schema-versioning/index.html b/_site_test/schema-versioning/index.html new file mode 100644 index 0000000..e72facd --- /dev/null +++ b/_site_test/schema-versioning/index.html @@ -0,0 +1,417 @@ + + + + + + + +Schema Versioning | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Schema Versioning

+ +

This document describes bundle schema versions and backward compatibility in SpecFact CLI.

+ +

Overview

+ +

SpecFact CLI uses semantic versioning for bundle schemas to ensure backward compatibility while allowing new features. Bundle schemas are versioned independently from the CLI version.

+ +

Schema Versions

+ +

v1.0 (Original)

+ +

Introduced: v0.1.0
+Status: Stable, fully supported

+ +

Features:

+ +
    +
  • Project bundle structure (modular aspect files)
    • +
  • Feature and story definitions
    • +
  • Protocol FSM definitions
    • +
  • Contract definitions
    • +
  • Basic bundle metadata
    • +
+ +

Bundle Manifest:

+ +
schema_metadata:
+  schema_version: "1.0"
+  project_version: "0.1.0"
+
+ +

v1.1 (Change Tracking)

+ +

Introduced: v0.21.1
+Status: Stable, fully supported

+ +

New Features:

+ +
    +
  • Change tracking data models (ChangeTracking, ChangeProposal, FeatureDelta, ChangeArchive)
    • +
  • Optional change_tracking field in BundleManifest and ProjectBundle
    • +
  • Optional change_archive field in BundleManifest
    • +
  • Bridge adapter interface extensions for change tracking
    • +
+ +

Bundle Manifest:

+ +
schema_metadata:
+  schema_version: "1.1"
+  project_version: "0.1.0"
+change_tracking:  # Optional - only present in v1.1+
+  proposals:
+    add-user-feedback:
+      name: "add-user-feedback"
+      title: "Add User Feedback Feature"
+      # ... change proposal fields
+  feature_deltas:
+    add-user-feedback:
+      - feature_key: "FEATURE-001"
+        change_type: "added"
+        # ... feature delta fields
+change_archive: []  # Optional - only present in v1.1+
+
+ +

Backward Compatibility

+ +

Automatic Compatibility

+ +

v1.0 bundles work with v1.1 CLI:

+ +
    +
  • All change tracking fields are optional
    • +
  • v1.0 bundles load with change_tracking = None and change_archive = []
    • +
  • No migration required - bundles continue to work without modification
    • +
+ +

v1.1 bundles work with v1.0 CLI (if CLI supports it):

+ +
    +
  • Change tracking fields are ignored if CLI doesn’t support v1.1
    • +
  • Core bundle functionality (features, stories, protocols) remains accessible
    • +
+ +

Version Detection

+ +

The bundle loader automatically detects schema version:

+ +
from specfact_cli.models.project import ProjectBundle, _is_schema_v1_1
+
+bundle = ProjectBundle.load_from_directory(bundle_dir)
+
+# Check if bundle uses v1.1 schema
+if _is_schema_v1_1(bundle.manifest):
+    # Bundle supports change tracking
+    if bundle.change_tracking:
+        active_changes = bundle.get_active_changes()
+        # ... work with change tracking
+else:
+    # v1.0 bundle - change tracking not available
+    # All other functionality works normally
+
+ +

Loading Change Tracking

+ +

Change tracking is loaded via bridge adapters (if available):

+ +
# In ProjectBundle.load_from_directory()
+if _is_schema_v1_1(manifest):
+    try:
+        adapter = AdapterRegistry.get_adapter(bridge_config.adapter.value)
+        change_tracking = adapter.load_change_tracking(bundle_dir, bridge_config)
+    except (ImportError, AttributeError, FileNotFoundError):
+        # Adapter or change tracking not available - continue without it
+        change_tracking = None
+
+ +

Migration

+ +

No Migration Required

+ +

v1.0 → v1.1: No migration needed - bundles are automatically compatible.

+ +
    +
  • v1.0 bundles continue to work without modification
    • +
  • To enable change tracking, update schema_version to "1.1" in bundle.manifest.yaml
    • +
  • Change tracking will be loaded via adapters when available
    • +
+ +

Manual Schema Upgrade (Optional)

+ +

If you want to explicitly upgrade a bundle to v1.1:

+ +
    +
  1. Update bundle manifest:
    2. +
+ +
# .specfact/projects/<bundle-name>/bundle.manifest.yaml
+schema_metadata:
+  schema_version: "1.1"  # Changed from "1.0"
+  project_version: "0.1.0"
+
+ +
    +
  1. Change tracking will be loaded automatically:
    2. +
+ +
    +
  • If bridge adapter is configured, change tracking loads from adapter-specific storage
    • +
  • If no adapter, change_tracking remains None (still valid v1.1 bundle)
    • +
+ +
    +
  1. No data loss:
    2. +
+ +
    +
  • All existing features, stories, and protocols remain unchanged
    • +
  • Change tracking fields are optional - bundle remains valid without them
    • +
+ +

Version Support Matrix

+ + + + + + + + + + + + + + + + + + + + + +
CLI Versionv1.0 Supportv1.1 Support
v0.1.0 - v0.21.0✅ Full❌ Not available
v0.21.1+✅ Full✅ Full
+ +

Best Practices

+ +

For Bundle Authors

+ +
    +
  1. Use latest schema version: Set schema_version: "1.1" for new bundles
    2. +
  2. Keep change tracking optional: Don’t require change tracking for core functionality
    3. +
  3. Document schema version: Include schema version in bundle documentation
    4. +
+ +

For Adapter Developers

+ +
    +
  1. Support both versions: Check schema version before loading change tracking
    2. +
  2. Graceful degradation: Return None if change tracking not available
    3. +
  3. Cross-repository support: Use external_base_path for cross-repo configurations
    4. +
+ + + + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/sitemap/index.xml b/_site_test/sitemap/index.xml new file mode 100644 index 0000000..de46fe6 --- /dev/null +++ b/_site_test/sitemap/index.xml @@ -0,0 +1,93 @@ + + + +https://nold-ai.github.io/specfact-cli/examples/ + + +https://nold-ai.github.io/specfact-cli/reference/ + + +https://nold-ai.github.io/specfact-cli/guides/agile-scrum-workflows/ + + +https://nold-ai.github.io/specfact-cli/ai-ide-workflow/ + + +https://nold-ai.github.io/specfact-cli/architecture/ + + +https://nold-ai.github.io/specfact-cli/brownfield-engineer/ + + +https://nold-ai.github.io/specfact-cli/brownfield-journey/ + + +https://nold-ai.github.io/specfact-cli/guides/command-chains/ + + +https://nold-ai.github.io/specfact-cli/reference/commands/ + + +https://nold-ai.github.io/specfact-cli/common-tasks/ + + +https://nold-ai.github.io/specfact-cli/competitive-analysis/ + + +https://nold-ai.github.io/specfact-cli/copilot-mode/ + + +https://nold-ai.github.io/specfact-cli/directory-structure/ + + +https://nold-ai.github.io/specfact-cli/getting-started/first-steps/ + + +https://nold-ai.github.io/specfact-cli/guides/ide-integration/ + + +https://nold-ai.github.io/specfact-cli/ + + +https://nold-ai.github.io/specfact-cli/getting-started/installation/ + + +https://nold-ai.github.io/specfact-cli/migration-guide/ + + +https://nold-ai.github.io/specfact-cli/modes/ + + +https://nold-ai.github.io/specfact-cli/quick-examples/ + + +https://nold-ai.github.io/specfact-cli/schema-versioning/ + + +https://nold-ai.github.io/specfact-cli/guides/speckit-journey/ + + +https://nold-ai.github.io/specfact-cli/team-collaboration-workflow/ + + +https://nold-ai.github.io/specfact-cli/testing-terminal-output/ + + +https://nold-ai.github.io/specfact-cli/troubleshooting/ + + +https://nold-ai.github.io/specfact-cli/use-cases/ + + +https://nold-ai.github.io/specfact-cli/ux-features/ + + +https://nold-ai.github.io/specfact-cli/redirects/ + + +https://nold-ai.github.io/specfact-cli/sitemap/ + + +https://nold-ai.github.io/specfact-cli/robots/ + + diff --git a/_site_test/team-collaboration-workflow/index.html b/_site_test/team-collaboration-workflow/index.html new file mode 100644 index 0000000..abf58c8 --- /dev/null +++ b/_site_test/team-collaboration-workflow/index.html @@ -0,0 +1,404 @@ + + + + + + + +Team Collaboration Workflow | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Team Collaboration Workflow

+ +
+

Complete guide to using SpecFact CLI for team collaboration with persona-based workflows

+
+ +
+ +

Overview

+ +

SpecFact CLI supports team collaboration through persona-based workflows where different roles (Product Owner, Architect, Developer) work on different aspects of the project using Markdown files. This guide explains when and how to use the team collaboration commands.

+ +

Related: Agile/Scrum Workflows - Complete persona-based collaboration guide

+ +
+ +

When to Use Team Collaboration Commands

+ +

Use these commands when:

+ +
    +
  • Multiple team members need to work on the same project bundle
    • +
  • Different roles (Product Owner, Architect, Developer) need to edit different sections
    • +
  • Concurrent editing needs to be managed safely
    • +
  • Version control integration is needed for team workflows
    • +
+ +
+ +

Core Commands

+ +

project init-personas

+ +

Initialize persona definitions for a project bundle.

+ +

When to use: First-time setup for team collaboration.

+ +

Example:

+ +
specfact project init-personas --bundle my-project
+
+ +

Related: Agile/Scrum Workflows - Persona Setup

+ +
+ +

project export

+ +

Export persona-specific Markdown artifacts for editing.

+ +

When to use: When a team member needs to edit their role-specific sections.

+ +

Example:

+ +
# Export Product Owner view
+specfact project export --bundle my-project --persona product-owner
+
+# Export Developer view
+specfact project export --bundle my-project --persona developer
+
+# Export Architect view
+specfact project export --bundle my-project --persona architect
+
+ +

Workflow: Export → Edit in Markdown → Import back

+ +

Related: Agile/Scrum Workflows - Exporting Persona Artifacts

+ +
+ +

project import

+ +

Import persona edits from Markdown files back into the project bundle.

+ +

When to use: After editing exported Markdown files.

+ +

Example:

+ +
# Import Product Owner edits
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md
+
+# Dry-run to validate without applying
+specfact project import --bundle my-project --persona product-owner --source docs/backlog.md --dry-run
+
+ +

Workflow: Export → Edit → Import → Validate

+ +

Related: Agile/Scrum Workflows - Importing Persona Edits

+ +
+ +

project lock / project unlock

+ +

Lock sections to prevent concurrent edits.

+ +

When to use: When multiple team members might edit the same section simultaneously.

+ +

Example:

+ +
# Lock a section for editing
+specfact project lock --bundle my-project --section idea --persona product-owner
+
+# Edit and import
+specfact project export --bundle my-project --persona product-owner
+# ... edit exported file ...
+specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+# Unlock when done
+specfact project unlock --bundle my-project --section idea
+
+ +

Workflow: Lock → Export → Edit → Import → Unlock

+ +

Related: Agile/Scrum Workflows - Section Locking

+ +
+ +

project locks

+ +

List all locked sections.

+ +

When to use: Before starting work to see what’s locked.

+ +

Example:

+ +
specfact project locks --bundle my-project
+
+ +

Related: Agile/Scrum Workflows - Checking Locks

+ +
+ +

Complete Workflow Example

+ +

Scenario: Product Owner Updates Backlog

+ +
# 1. Check what's locked
+specfact project locks --bundle my-project
+
+# 2. Lock the section you need
+specfact project lock --bundle my-project --section idea --persona product-owner
+
+# 3. Export your view
+specfact project export --bundle my-project --persona product-owner --output backlog.md
+
+# 4. Edit backlog.md in your preferred editor
+
+# 5. Import changes back
+specfact project import --bundle my-project --persona product-owner --source backlog.md
+
+# 6. Unlock the section
+specfact project unlock --bundle my-project --section idea
+
+ +
+ +

Integration with Version Management

+ +

Team collaboration integrates with version management:

+ +
# After importing changes, check if version bump is needed
+specfact project version check --bundle my-project
+
+# If needed, bump version
+specfact project version bump --bundle my-project --type minor
+
+ +

Related: Project Version Management

+ +
+ +

Integration with Command Chains

+ +

Team collaboration commands are part of the Plan Promotion & Release Chain:

+ +
    +
  1. Export persona views
    2. +
  2. Edit in Markdown
    3. +
  3. Import back
    4. +
  4. Review plan
    5. +
  5. Enforce SDD
    6. +
  6. Promote plan
    7. +
  7. Bump version
    8. +
+ +

Related: Plan Promotion & Release Chain

+ +
+ +

See Also

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/technical/README.md b/_site_test/technical/README.md new file mode 100644 index 0000000..f924182 --- /dev/null +++ b/_site_test/technical/README.md @@ -0,0 +1,36 @@ +# Technical Deep Dives + +Technical documentation for contributors and developers working on SpecFact CLI. + +## Available Documentation + +- **[Code2Spec Analysis Logic](code2spec-analysis-logic.md)** - AI-first approach for code analysis +- **[Testing Procedures](testing.md)** - Comprehensive testing guide for contributors + +## Developer Tools + +### Maintenance Scripts + +For maintenance scripts and developer utilities, see the [Contributing Guide](../../CONTRIBUTING.md#developer-tools) section on Developer Tools. This includes: + +- **Cleanup Acceptance Criteria Script** - Removes duplicate replacement instruction text from acceptance criteria +- Other maintenance and development utilities in the `scripts/` directory + +## Overview + +This section contains deep technical documentation for: + +- Implementation details +- Testing procedures +- Architecture internals +- Development workflows + +## Related Documentation + +- [Architecture](../reference/architecture.md) - Technical design and principles +- [Commands](../reference/commands.md) - Complete command reference +- [Getting Started](../getting-started/README.md) - Installation and setup + +--- + +**Note**: This section is intended for contributors and developers. For user guides, see [Guides](../guides/README.md). diff --git a/_site_test/technical/code2spec-analysis-logic.md b/_site_test/technical/code2spec-analysis-logic.md new file mode 100644 index 0000000..51a6ebb --- /dev/null +++ b/_site_test/technical/code2spec-analysis-logic.md @@ -0,0 +1,756 @@ +# Code2Spec Analysis Logic: How It Works + +> **TL;DR**: SpecFact CLI uses **AI-first approach** via AI IDE integration (Cursor, CoPilot, etc.) for semantic understanding, with **AST-based fallback** for CI/CD mode. The AI IDE's native LLM understands the codebase semantically, then calls the SpecFact CLI for structured analysis. This avoids separate LLM API setup, langchain, or additional API keys while providing high-quality, semantic-aware analysis that works with all languages and generates Spec-Kit compatible artifacts. + +--- + +## Overview + +The `code2spec` command analyzes existing codebases and reverse-engineers them into plan bundles (features, stories, tasks). It uses **two approaches** depending on operational mode: + +### **Mode 1: AI-First (CoPilot Mode)** - Recommended + +Uses **AI IDE's native LLM** for semantic understanding via pragmatic integration: + +**Workflow**: + +1. **AI IDE's LLM** understands codebase semantically (via slash command prompt) +2. **AI calls SpecFact CLI** (`specfact import from-code `) for structured analysis +3. **AI enhances results** with semantic understanding (priorities, constraints, unknowns) +4. **CLI handles structured work** (file I/O, YAML generation, validation) + +**Benefits**: + +- ✅ **No separate LLM setup** - Uses AI IDE's existing LLM (Cursor, CoPilot, etc.) +- ✅ **No additional API costs** - Leverages existing IDE infrastructure +- ✅ **Simpler architecture** - No langchain, API keys, or complex integration +- ✅ **Multi-language support** - Works with Python, TypeScript, JavaScript, PowerShell, Go, Rust, etc. + +- ✅ **Semantic understanding** - AI understands business logic, not just structure +- ✅ **High-quality output** - Generates meaningful priorities, constraints, unknowns +- ✅ **Spec-Kit compatible** - Produces artifacts that pass `/speckit.analyze` validation +- ✅ **Bidirectional sync** - Preserves semantics during Spec-Kit ↔ SpecFact sync + +**Why this approach?** + +- ✅ **Pragmatic** - Uses existing IDE infrastructure, no extra setup +- ✅ **Cost-effective** - No additional API costs +- ✅ **Streamlined** - Native IDE integration, better developer experience +- ✅ **Maintainable** - Simpler architecture, less code to maintain + +### **Mode 2: AST+Semgrep Hybrid (CI/CD Mode)** - Enhanced Fallback + +Uses **Python's AST + Semgrep pattern matching** for comprehensive structural analysis when LLM is unavailable: + +1. **AST Parsing** - Python's built-in Abstract Syntax Tree for structural analysis +2. **Semgrep Pattern Detection** - Framework-aware pattern matching (API endpoints, models, CRUD, auth) +3. **Pattern Matching** - Heuristic-based method grouping enhanced with Semgrep findings +4. **Confidence Scoring** - Evidence-based quality metrics combining AST + Semgrep evidence +5. **Code Quality Assessment** - Anti-pattern detection and maturity scoring +6. **Deterministic Algorithms** - No randomness, 100% reproducible + +**Why AST+Semgrep hybrid?** + +- ✅ **Fast** - Analyzes thousands of lines in seconds (parallelized) +- ✅ **Deterministic** - Same code always produces same results +- ✅ **Offline** - No cloud services or API calls +- ✅ **Framework-Aware** - Detects FastAPI, Flask, SQLAlchemy, Pydantic patterns +- ✅ **Enhanced Detection** - API endpoints, database models, CRUD operations, auth patterns +- ✅ **Code Quality** - Identifies anti-patterns and code smells +- ✅ **Multi-language Ready** - Semgrep supports TypeScript, JavaScript, Go (patterns ready) +- ⚠️ **Python-Focused** - Currently optimized for Python (other languages pending) + +--- + +## Architecture + +```mermaid +flowchart TD + A["code2spec Command
specfact import from-code my-project --repo . --confidence 0.5"] --> B{Operational Mode} + + B -->|CoPilot Mode| C["AnalyzeAgent (AI-First)
• LLM semantic understanding
• Multi-language support
• Semantic extraction (priorities, constraints, unknowns)
• High-quality Spec-Kit artifacts"] + + B -->|CI/CD Mode| D["CodeAnalyzer (AST+Semgrep Hybrid)
• AST parsing (Python's built-in ast module)
• Semgrep pattern detection (API, models, CRUD, auth)
• Pattern matching (method name + Semgrep findings)
• Confidence scoring (AST + Semgrep evidence)
• Code quality assessment (anti-patterns)
• Story point calculation (Fibonacci sequence)"] + + C --> E["Features with Semantic Understanding
• Actual priorities from code context
• Actual constraints from code/docs
• Actual unknowns from code analysis
• Meaningful scenarios from acceptance criteria"] + + D --> F["Features from Structure + Patterns
• Framework-aware outcomes (API endpoints, models)
• CRUD operation detection
• Code quality constraints (anti-patterns)
• Enhanced confidence scores
• Python-focused (multi-language ready)"] + + style A fill:#2196F3,stroke:#1976D2,stroke-width:2px,color:#fff + style C fill:#4CAF50,stroke:#388E3C,stroke-width:2px,color:#fff + style D fill:#FF9800,stroke:#F57C00,stroke-width:2px,color:#fff + style E fill:#9C27B0,stroke:#7B1FA2,stroke-width:2px,color:#fff + style F fill:#FF5722,stroke:#E64A19,stroke-width:2px,color:#fff +``` + +--- + +## Step-by-Step Process + +### Step 1: File Discovery and Filtering + +```python +# Find all Python files +python_files = repo_path.rglob("*.py") + +# Skip certain directories +skip_patterns = [ + "__pycache__", ".git", "venv", ".venv", + "env", ".pytest_cache", "htmlcov", + "dist", "build", ".eggs" +] + +# Test files: Included by default for comprehensive analysis +# Use --exclude-tests flag to skip test files for faster processing (~30-50% speedup) +# Rationale: Test files are consumers of production code (one-way dependency), +# so skipping them doesn't affect production dependency graph +``` + +**Rationale**: Only analyze production code, not test files or dependencies. + +--- + +### Step 2: AST Parsing + Semgrep Pattern Detection + +For each Python file, we use **two complementary approaches**: + +#### 2.1 AST Parsing + +```python +content = file_path.read_text(encoding="utf-8") +tree = ast.parse(content) # Built-in Python AST parser +``` + +**What AST gives us:** + +- ✅ Class definitions (`ast.ClassDef`) +- ✅ Function/method definitions (`ast.FunctionDef`) +- ✅ Import statements (`ast.Import`, `ast.ImportFrom`) +- ✅ Docstrings (via `ast.get_docstring()`) +- ✅ Method signatures and bodies + +**Why AST?** + +- Built into Python (no dependencies) +- Preserves exact structure (not text parsing) +- Handles all Python syntax correctly +- Extracts metadata (docstrings, names, structure) + +#### 2.2 Semgrep Pattern Detection + +```python +# Run Semgrep for pattern detection (parallel-safe) +semgrep_findings = self._run_semgrep_patterns(file_path) +``` + +**What Semgrep gives us:** + +- ✅ **API Endpoints**: FastAPI, Flask, Express, Gin routes (method + path) +- ✅ **Database Models**: SQLAlchemy, Django, Pydantic, TortoiseORM, Peewee +- ✅ **CRUD Operations**: Function naming patterns (create_*, get_*, update_*, delete_*) +- ✅ **Authentication**: Auth decorators, permission checks +- ✅ **Framework Patterns**: Async/await, context managers, type hints +- ✅ **Code Quality**: Anti-patterns, code smells, security vulnerabilities + +**Why Semgrep?** + +- Framework-aware pattern detection +- Multi-language support (Python, TypeScript, JavaScript, Go) +- Fast pattern matching (parallel execution) +- Rule-based (no hardcoded logic) + +--- + +### Step 3: Feature Extraction from Classes (AST + Semgrep Enhanced) + +**Rule**: Each public class (not starting with `_`) becomes a potential feature. + +```python +def _extract_feature_from_class(node: ast.ClassDef, file_path: Path) -> Feature | None: + # Skip private classes + if node.name.startswith("_") or node.name.startswith("Test"): + return None + + # Generate feature key: FEATURE-CLASSNAME + feature_key = f"FEATURE-{node.name.upper()}" + + # Extract docstring as outcome + docstring = ast.get_docstring(node) + if docstring: + outcomes = [docstring.split("\n\n")[0].strip()] + else: + outcomes = [f"Provides {humanize_name(node.name)} functionality"] +``` + +**Example**: + +- `EnforcementConfig` class → `FEATURE-ENFORCEMENTCONFIG` feature +- Docstring "Configuration for contract enforcement" → Outcome +- Methods grouped into stories (see Step 4) + +--- + +### Step 4: Story Extraction from Methods + +**Key Insight**: Methods are grouped by **functionality patterns**, not individually. + +#### 4.1 Method Grouping (Pattern Matching) + +Methods are grouped using **keyword matching** on method names: + +```python +def _group_methods_by_functionality(methods: list[ast.FunctionDef]) -> dict[str, list]: + groups = defaultdict(list) + + for method in public_methods: + name_lower = method.name.lower() + + # CRUD Operations + if any(crud in name_lower for crud in ["create", "add", "insert", "new"]): + groups["Create Operations"].append(method) + elif any(read in name_lower for read in ["get", "read", "fetch", "find", "list"]): + groups["Read Operations"].append(method) + elif any(update in name_lower for update in ["update", "modify", "edit"]): + groups["Update Operations"].append(method) + elif any(delete in name_lower for delete in ["delete", "remove", "destroy"]): + groups["Delete Operations"].append(method) + + # Validation + elif any(val in name_lower for val in ["validate", "check", "verify"]): + groups["Validation"].append(method) + + # Processing + elif any(proc in name_lower for proc in ["process", "compute", "transform"]): + groups["Processing"].append(method) + + # Analysis + elif any(an in name_lower for an in ["analyze", "parse", "extract"]): + groups["Analysis"].append(method) + + # ... more patterns +``` + +**Pattern Groups**: + +| Group | Keywords | Example Methods | +|-------|----------|----------------| +| **Create Operations** | `create`, `add`, `insert`, `new` | `create_user()`, `add_item()` | +| **Read Operations** | `get`, `read`, `fetch`, `find`, `list` | `get_user()`, `list_items()` | +| **Update Operations** | `update`, `modify`, `edit`, `change` | `update_profile()`, `modify_settings()` | +| **Delete Operations** | `delete`, `remove`, `destroy` | `delete_user()`, `remove_item()` | +| **Validation** | `validate`, `check`, `verify` | `validate_input()`, `check_permissions()` | +| **Processing** | `process`, `compute`, `transform` | `process_data()`, `transform_json()` | +| **Analysis** | `analyze`, `parse`, `extract` | `analyze_code()`, `parse_config()` | +| **Generation** | `generate`, `build`, `make` | `generate_report()`, `build_config()` | +| **Comparison** | `compare`, `diff`, `match` | `compare_plans()`, `diff_files()` | +| **Configuration** | `setup`, `configure`, `initialize` | `setup_logger()`, `configure_db()` | + +**Why Pattern Matching?** + +- ✅ Fast - Simple string matching, no ML overhead +- ✅ Deterministic - Same patterns always grouped together +- ✅ Interpretable - You can see why methods are grouped +- ✅ Customizable - Easy to add new patterns + +--- + +#### 4.2 Story Creation from Method Groups + +Each method group becomes a **user story**: + +```python +def _create_story_from_method_group(group_name, methods, class_name, story_number): + # Generate story key: STORY-CLASSNAME-001 + story_key = f"STORY-{class_name.upper()}-{story_number:03d}" + + # Create user-centric title + title = f"As a user, I can {group_name.lower()} {class_name}" + + # Extract tasks (method names) + tasks = [f"{method.name}()" for method in methods] + + # Extract acceptance from docstrings (Phase 4: Simple text format) + acceptance = [] + for method in methods: + docstring = ast.get_docstring(method) + if docstring: + # Phase 4: Use simple text description (not verbose GWT) + # Examples are stored in OpenAPI contracts, not in feature YAML + first_line = docstring.split("\n")[0].strip() + # Convert to simple format: "Feature works correctly (see contract examples)" + method_name = method.name.replace("_", " ").title() + acceptance.append(f"{method_name} works correctly (see contract examples)") + + # Calculate story points and value points + story_points = _calculate_story_points(methods) + value_points = _calculate_value_points(methods, group_name) +``` + +**Example** (Phase 4 Format): + +```python +# EnforcementConfig class has methods: +# - validate_input() +# - check_permissions() +# - verify_config() + +# → Grouped into "Validation" story: +{ + "key": "STORY-ENFORCEMENTCONFIG-001", + "title": "As a developer, I can validate EnforcementConfig data", + "tasks": ["validate_input()", "check_permissions()", "verify_config()"], + "acceptance": [ + "Validate Input works correctly (see contract examples)", + "Check Permissions works correctly (see contract examples)", + "Verify Config works correctly (see contract examples)" + ], + "contract": "contracts/enforcement-config.openapi.yaml", # Examples stored here + "story_points": 5, + "value_points": 3 +} +``` + +**Phase 4 & 5 Changes (GWT Elimination + Test Pattern Extraction)**: + +- ❌ **BEFORE**: Verbose GWT format ("Given X, When Y, Then Z") - one per test function +- ✅ **AFTER Phase 4**: Simple text format ("Feature works correctly (see contract examples)") +- ✅ **AFTER Phase 5**: Limited to 1-3 high-level acceptance criteria per story, all detailed test patterns in OpenAPI contracts +- ✅ **Benefits**: 81% bundle size reduction (18MB → 3.4MB, 5.3x smaller), examples in OpenAPI contracts for Specmatic integration +- ✅ **Quality**: All test patterns preserved in contract files, no information loss + +--- + +### Step 3: Feature Enhancement with Semgrep + +After extracting features from AST, we enhance them with Semgrep findings: + +```python +def _enhance_feature_with_semgrep(feature, semgrep_findings, file_path, class_name): + """Enhance feature with Semgrep pattern detection results.""" + for finding in semgrep_findings: + # API endpoint detection → +0.1 confidence, add "API" theme + # Database model detection → +0.15 confidence, add "Database" theme + # CRUD operation detection → +0.1 confidence, add to outcomes + # Auth pattern detection → +0.1 confidence, add "Security" theme + # Anti-pattern detection → -0.05 confidence, add to constraints + # Security issues → -0.1 confidence, add to constraints +``` + +**Semgrep Enhancements**: + +- **API Endpoints**: Adds `"Exposes API endpoints: GET /users, POST /users"` to outcomes +- **Database Models**: Adds `"Defines data models: UserModel, ProductModel"` to outcomes +- **CRUD Operations**: Adds `"Provides CRUD operations: CREATE user, GET user"` to outcomes +- **Code Quality**: Adds constraints like `"Code quality: Bare except clause detected - antipattern"` +- **Confidence Adjustments**: Framework patterns increase confidence, anti-patterns decrease it + +--- + +### Step 5: Confidence Scoring (AST + Semgrep Evidence) + +**Goal**: Determine how confident we are that this is a real feature (not noise), combining AST and Semgrep evidence. + +```python +def _calculate_feature_confidence(node: ast.ClassDef, stories: list[Story]) -> float: + score = 0.3 # Base score (30%) + + # Has docstring (+20%) + if ast.get_docstring(node): + score += 0.2 + + # Has stories (+20%) + if stories: + score += 0.2 + + # Has multiple stories (+20%) + if len(stories) > 2: + score += 0.2 + + # Stories are well-documented (+10%) + documented_stories = sum(1 for s in stories if s.acceptance and len(s.acceptance) > 1) + if stories and documented_stories > len(stories) / 2: + score += 0.1 + + return min(score, 1.0) # Cap at 100% +``` + +**Confidence Factors**: + +| Factor | Weight | Rationale | +|--------|--------|-----------| +| **Base Score** | 30% | Every class starts with baseline | +| **Has Docstring** | +20% | Documented classes are more likely real features | +| **Has Stories** | +20% | Methods grouped into stories indicate functionality | +| **Multiple Stories** | +20% | More stories = more complete feature | +| **Well-Documented Stories** | +10% | Docstrings in methods indicate intentional design | + +**Example**: + +- `EnforcementConfig` with docstring + 3 well-documented stories → **0.9 confidence** (90%) +- `InternalHelper` with no docstring + 1 story → **0.5 confidence** (50%) + +**Filtering**: Features below `--confidence` threshold (default 0.5) are excluded. + +**Semgrep Confidence Enhancements** (Systematic Evidence-Based Scoring): + +| Semgrep Finding | Confidence Adjustment | Rationale | +|----------------|----------------------|-----------| +| **API Endpoint Detected** | +0.1 | Framework patterns indicate real features | +| **Database Model Detected** | +0.15 | Data models are core features | +| **CRUD Operations Detected** | +0.1 | Complete CRUD indicates well-defined feature | +| **Auth Pattern Detected** | +0.1 | Security features are important | +| **Framework Patterns Detected** | +0.05 | Framework usage indicates intentional design | +| **Test Patterns Detected** | +0.1 | Tests indicate validated feature | +| **Anti-Pattern Detected** | -0.05 | Code quality issues reduce maturity | +| **Security Issue Detected** | -0.1 | Security vulnerabilities are critical | + +**How It Works**: + +1. **Evidence Extraction**: Semgrep findings are categorized into evidence flags (API endpoints, models, CRUD, etc.) +2. **Confidence Calculation**: Base AST confidence (0.3-0.9) is adjusted with Semgrep evidence weights +3. **Systematic Scoring**: Each pattern type has a documented weight, ensuring consistent confidence across features +4. **Quality Assessment**: Anti-patterns and security issues reduce confidence, indicating lower code maturity + +**Example**: + +- `UserService` with API endpoints + CRUD operations → **Base 0.6 + 0.1 (API) + 0.1 (CRUD) = 0.8 confidence** +- `BadService` with anti-patterns → **Base 0.6 - 0.05 (anti-pattern) = 0.55 confidence** + +--- + +### Step 6: Story Points Calculation + +**Goal**: Estimate complexity using **Fibonacci sequence** (1, 2, 3, 5, 8, 13, 21...) + +```python +def _calculate_story_points(methods: list[ast.FunctionDef]) -> int: + method_count = len(methods) + + # Count total lines + total_lines = sum(len(ast.unparse(m).split("\n")) for m in methods) + avg_lines = total_lines / method_count if method_count > 0 else 0 + + # Heuristic: complexity based on count and size + if method_count <= 2 and avg_lines < 20: + base_points = 2 # Small + elif method_count <= 5 and avg_lines < 40: + base_points = 5 # Medium + elif method_count <= 8: + base_points = 8 # Large + else: + base_points = 13 # Extra Large + + # Return nearest Fibonacci number + return min(FIBONACCI, key=lambda x: abs(x - base_points)) +``` + +**Heuristic Table**: + +| Methods | Avg Lines | Base Points | Fibonacci Result | +|---------|-----------|-------------|------------------| +| 1-2 | < 20 | 2 | **2** | +| 3-5 | < 40 | 5 | **5** | +| 6-8 | Any | 8 | **8** | +| 9+ | Any | 13 | **13** | + +**Why Fibonacci?** + +- ✅ Industry standard (Scrum/Agile) +- ✅ Non-linear (reflects uncertainty) +- ✅ Widely understood by teams + +--- + +### Step 7: Value Points Calculation + +**Goal**: Estimate **business value** (not complexity, but importance). + +```python +def _calculate_value_points(methods: list[ast.FunctionDef], group_name: str) -> int: + # CRUD operations are high value + crud_groups = ["Create Operations", "Read Operations", "Update Operations", "Delete Operations"] + if group_name in crud_groups: + base_value = 8 # High business value + + # User-facing operations + elif group_name in ["Processing", "Analysis", "Generation", "Comparison"]: + base_value = 5 # Medium-high value + + # Developer/internal operations + elif group_name in ["Validation", "Configuration"]: + base_value = 3 # Medium value + + else: + base_value = 3 # Default + + # Adjust for public API exposure + public_count = sum(1 for m in methods if not m.name.startswith("_")) + if public_count >= 3: + base_value = min(base_value + 2, 13) + + return min(FIBONACCI, key=lambda x: abs(x - base_value)) +``` + +**Value Hierarchy**: + +| Group Type | Base Value | Rationale | +|------------|------------|-----------| +| **CRUD Operations** | 8 | Direct user value (create, read, update, delete) | +| **User-Facing** | 5 | Processing, analysis, generation - users see results | +| **Developer/Internal** | 3 | Validation, configuration - infrastructure | +| **Public API Bonus** | +2 | More public methods = higher exposure = more value | + +--- + +### Step 8: Theme Detection from Imports + +**Goal**: Identify what kind of application this is (API, CLI, Database, etc.). + +```python +def _extract_themes_from_imports(tree: ast.AST) -> None: + theme_keywords = { + "fastapi": "API", + "flask": "API", + "django": "Web", + "typer": "CLI", + "click": "CLI", + "pydantic": "Validation", + "redis": "Caching", + "postgres": "Database", + "mysql": "Database", + "asyncio": "Async", + "pytest": "Testing", + # ... more keywords + } + + # Scan all imports + for node in ast.walk(tree): + if isinstance(node, (ast.Import, ast.ImportFrom)): + # Match keywords in import names + for keyword, theme in theme_keywords.items(): + if keyword in import_name.lower(): + self.themes.add(theme) +``` + +**Example**: + +- `import typer` → Theme: **CLI** +- `import pydantic` → Theme: **Validation** +- `from fastapi import FastAPI` → Theme: **API** + +--- + +## Why AI-First? + +### ✅ Advantages of AI-First Approach + +| Aspect | AI-First (CoPilot Mode) | AST-Based (CI/CD Mode) | +|-------|------------------------|------------------------| +| **Language Support** | ✅ All languages | ❌ Python only | +| **Semantic Understanding** | ✅ Understands business logic | ❌ Structure only | +| **Priorities** | ✅ Actual from code context | ⚠️ Generic (hardcoded) | +| **Constraints** | ✅ Actual from code/docs | ⚠️ Generic (hardcoded) | +| **Unknowns** | ✅ Actual from code analysis | ⚠️ Generic (hardcoded) | +| **Scenarios** | ✅ Actual from acceptance criteria | ⚠️ Generic (hardcoded) | +| **Spec-Kit Compatibility** | ✅ High-quality artifacts | ⚠️ Low-quality artifacts | +| **Bidirectional Sync** | ✅ Semantic preservation | ⚠️ Structure-only | + +### When AST Fallback Is Used + +AST-based analysis is used in **CI/CD mode** when: + +- LLM is unavailable (no API access) +- Fast, deterministic analysis is required +- Offline analysis is needed +- Python-only codebase analysis is sufficient + +**Trade-offs**: + +- ✅ Fast and deterministic +- ✅ Works offline +- ❌ Python-only +- ❌ Generic content (hardcoded fallbacks) + +--- + +## Accuracy and Limitations + +### ✅ AI-First Approach (CoPilot Mode) + +**What It Does Well**: + +1. **Semantic Understanding**: Understands business logic and domain concepts +2. **Multi-language Support**: Works with Python, TypeScript, JavaScript, PowerShell, Go, Rust, etc. + +3. **Semantic Extraction**: Extracts actual priorities, constraints, unknowns from code context +4. **High-quality Artifacts**: Generates Spec-Kit compatible artifacts with semantic content +5. **Bidirectional Sync**: Preserves semantics during Spec-Kit ↔ SpecFact sync + +**Limitations**: + +1. **Requires LLM Access**: Needs CoPilot API or IDE integration +2. **Variable Response Time**: Depends on LLM API response time +3. **Token Costs**: May incur API costs for large codebases +4. **Non-deterministic**: May produce slightly different results on repeated runs + +### ⚠️ AST-Based Fallback (CI/CD Mode) + +**What It Does Well**: + +1. **Structural Analysis**: Classes, methods, imports are 100% accurate (AST parsing) +2. **Pattern Recognition**: CRUD, validation, processing patterns are well-defined +3. **Confidence Scoring**: Evidence-based (docstrings, stories, documentation) +4. **Deterministic**: Same code always produces same results +5. **Fast**: Analyzes thousands of lines in seconds +6. **Offline**: Works without API access + +**Limitations**: + +1. **Python-only**: Cannot analyze TypeScript, JavaScript, PowerShell, etc. + +2. **Generic Content**: Produces generic priorities, constraints, unknowns (hardcoded fallbacks) +3. **No Semantic Understanding**: Cannot understand business logic or domain concepts +4. **Method Name Dependency**: If methods don't follow naming conventions, grouping may be less accurate +5. **Docstring Dependency**: Features/stories without docstrings have lower confidence +6. **False Positives**: Internal helper classes might be detected as features + +--- + +## Real Example: EnforcementConfig + +Let's trace how `EnforcementConfig` class becomes a feature: + +```python +class EnforcementConfig: + """Configuration for contract enforcement and quality gates.""" + + def __init__(self, preset: EnforcementPreset): + ... + + def should_block_deviation(self, severity: str) -> bool: + ... + + def get_action(self, severity: str) -> EnforcementAction: + ... +``` + +**Step-by-Step Analysis**: + +1. **AST Parse** → Finds `EnforcementConfig` class with 3 methods +2. **Feature Extraction**: + - Key: `FEATURE-ENFORCEMENTCONFIG` + - Title: `Enforcement Config` (humanized) + - Outcome: `"Configuration for contract enforcement and quality gates."` +3. **Method Grouping**: + - `__init__()` → **Configuration** group + - `should_block_deviation()` → **Validation** group (has "check" pattern) + - `get_action()` → **Read Operations** group (has "get" pattern) +4. **Story Creation**: + - Story 1: "As a developer, I can configure EnforcementConfig" (Configuration group) + - Story 2: "As a developer, I can validate EnforcementConfig data" (Validation group) + - Story 3: "As a user, I can view EnforcementConfig data" (Read Operations group) +5. **Confidence**: 0.9 (has docstring + 3 stories + well-documented) +6. **Story Points**: 5 (3 methods, medium complexity) +7. **Value Points**: 3 (Configuration group = medium value) + +**Result**: + +```yaml +feature: + key: FEATURE-ENFORCEMENTCONFIG + title: Enforcement Config + confidence: 0.9 + stories: + - key: STORY-ENFORCEMENTCONFIG-001 + title: As a developer, I can configure EnforcementConfig + story_points: 2 + value_points: 3 + tasks: ["__init__()"] + - key: STORY-ENFORCEMENTCONFIG-002 + title: As a developer, I can validate EnforcementConfig data + story_points: 2 + value_points: 3 + tasks: ["should_block_deviation()"] + - key: STORY-ENFORCEMENTCONFIG-003 + title: As a user, I can view EnforcementConfig data + story_points: 2 + value_points: 5 + tasks: ["get_action()"] +``` + +--- + +## Validation and Quality Assurance + +### Built-in Validations + +1. **Plan Bundle Schema**: Generated plans are validated against JSON schema +2. **Confidence Threshold**: Low-confidence features are filtered +3. **AST Error Handling**: Invalid Python files are skipped gracefully +4. **File Filtering**: Test files and dependencies are excluded + +### How to Improve Accuracy + +1. **Add Docstrings**: Increases confidence scores +2. **Use Descriptive Names**: Follow naming conventions (CRUD patterns) +3. **Group Related Methods**: Co-locate related functionality in same class +4. **Adjust Confidence Threshold**: Use `--confidence 0.7` for stricter filtering + +--- + +## Performance + +### Benchmarks + +| Repository Size | Files | Time | Throughput | Notes | +|----------------|-------|------|------------|-------| +| **Small** (10 files) | 10 | ~10-30s | ~0.3-1 files/sec | AST + Semgrep analysis | +| **Medium** (50 files) | 50 | ~1-2 min | ~0.4-0.8 files/sec | AST + Semgrep analysis | +| **Large** (100+ files) | 100+ | 2-3 min | ~0.5-0.8 files/sec | AST + Semgrep analysis | +| **Large with Contracts** (100+ files) | 100+ | 15-30+ min | Varies | With contract extraction, graph analysis, and parallel processing (8 workers) | + +**SpecFact CLI on itself**: 19 files in ~30-60 seconds = **~0.3-0.6 files/second** (AST + Semgrep analysis) + +**Note**: + +- **Basic analysis** (AST + Semgrep): Takes **2-3 minutes** for large codebases (100+ files) even without contract extraction +- **With contract extraction** (default in `import from-code`): The process uses parallel workers to extract OpenAPI contracts, relationships, and graph dependencies. For large codebases, this can take **15-30+ minutes** even with 8 parallel workers + +### Bundle Size Optimization (2025-11-30) + +- ✅ **81% Reduction**: 18MB → 3.4MB (5.3x smaller) via test pattern extraction to OpenAPI contracts +- ✅ **Acceptance Criteria**: Limited to 1-3 high-level items per story (detailed examples in contract files) +- ✅ **Quality Preserved**: All test patterns preserved in contract files (no information loss) +- ✅ **Specmatic Integration**: Examples in OpenAPI format enable contract testing + +### Optimization Opportunities + +1. ✅ **Parallel Processing**: Contract extraction uses 8 parallel workers (implemented) +2. ✅ **Interruptible Operations**: All parallel operations support Ctrl+C for immediate cancellation (implemented) +3. **Caching**: Cache AST parsing results (future enhancement) +4. **Incremental Analysis**: Only analyze changed files (future enhancement) + +--- + +## Conclusion + +The `code2spec` analysis is **deterministic, fast, and transparent** because it uses: + +1. ✅ **Python AST** - Built-in, reliable parsing +2. ✅ **Pattern Matching** - Simple, interpretable heuristics +3. ✅ **Confidence Scoring** - Evidence-based quality metrics +4. ✅ **Fibonacci Estimation** - Industry-standard story/value points + +**No AI required** - just solid engineering principles and proven algorithms. + +--- + +## Further Reading + +- [Python AST Documentation](https://docs.python.org/3/library/ast.html) +- [Scrum Story Points](https://www.scrum.org/resources/blog/what-are-story-points) +- [Dogfooding Example](../examples/dogfooding-specfact-cli.md) - See it in action + +--- + +**Questions or improvements?** Open an issue or PR on GitHub! diff --git a/_site_test/technical/dual-stack-pattern.md b/_site_test/technical/dual-stack-pattern.md new file mode 100644 index 0000000..62af053 --- /dev/null +++ b/_site_test/technical/dual-stack-pattern.md @@ -0,0 +1,153 @@ +# Dual-Stack Enrichment Pattern - Technical Specification + +**Status**: ✅ **IMPLEMENTED** (v0.13.0+) +**Last Updated**: 2025-12-02 + +--- + +## Overview + +The Dual-Stack Enrichment Pattern is a technical architecture that enforces CLI-first principles while allowing LLM enrichment in AI IDE environments. It ensures all artifacts are CLI-generated and validated, preventing format drift and ensuring consistency. + +## Architecture + +### Stack 1: CLI (REQUIRED) + +**Purpose**: Generate and validate all artifacts + +**Capabilities**: + +- Tool execution (ruff, pylint, basedpyright, mypy, semgrep, specmatic) +- Bundle management (create, load, save, validate structure) +- Metadata management (timestamps, hashes, telemetry) +- Planning operations (init, add-feature, add-story, update-idea, update-feature) +- AST/Semgrep-based analysis (code structure, patterns, relationships) +- Specmatic validation (OpenAPI/AsyncAPI contract validation) +- Format validation (YAML/JSON schema compliance) +- Source tracking and drift detection + +**Limitations**: + +- ❌ Cannot generate code (no LLM available) +- ❌ Cannot do reasoning (no semantic understanding) + +### Stack 2: LLM (OPTIONAL, AI IDE Only) + +**Purpose**: Add semantic understanding and generate code + +**Capabilities**: + +- Code generation (requires LLM reasoning) +- Code enhancement (contracts, refactoring, improvements) +- Semantic understanding (business logic, context, priorities) +- Plan enrichment (missing features, confidence adjustments, business context) +- Code reasoning (why decisions were made, trade-offs, constraints) + +**Access**: Only via AI IDE slash prompts (Cursor, CoPilot, etc.) + +## Validation Loop Pattern + +### Implementation + +The validation loop pattern is implemented in: + +- `src/specfact_cli/commands/generate.py`: + - `generate_contracts_prompt()` - Generates structured prompts + - `apply_enhanced_contracts()` - Validates and applies enhanced code + +### Validation Steps + +1. **Syntax Validation**: `python -m py_compile` +2. **File Size Check**: Enhanced file must be >= original file size +3. **AST Structure Comparison**: Logical structure integrity check +4. **Contract Imports Verification**: Required imports present +5. **Code Quality Checks**: ruff, pylint, basedpyright, mypy (if available) +6. **Test Execution**: Run tests via specfact (contract-test) + +### Retry Mechanism + +- Maximum 3 attempts +- CLI provides detailed error feedback after each attempt +- LLM fixes issues in temporary file +- Re-validate until success or max attempts reached + +## CLI Metadata + +### Metadata Structure + +```python +@dataclass +class CLIArtifactMetadata: + cli_generated: bool = True + cli_version: str | None = None + generated_at: str | None = None + generated_by: str = "specfact-cli" +``` + +### Metadata Detection + +The `cli_first_validator.py` module provides: + +- `is_cli_generated()` - Check if artifact was CLI-generated +- `extract_cli_metadata()` - Extract CLI metadata from artifact +- `validate_artifact_format()` - Validate artifact format +- `detect_direct_manipulation()` - Detect files that may have been directly manipulated + +## Enforcement Rules + +### For Slash Commands + +1. Every slash command MUST execute the specfact CLI at least once +2. Artifacts are ALWAYS CLI-generated (never LLM-generated directly) +3. Enrichment is additive (LLM adds context, CLI validates and creates) +4. Code generation MUST follow validation loop pattern (temp file → validate → apply) + +### For CLI Commands + +1. All write operations go through CLI +2. Never modify `.specfact/` folder directly +3. Always use `--no-interactive` flag in CI/CD environments +4. Use file reading tools for display only, CLI commands for writes + +## Implementation Status + +### ✅ Implemented + +- Contract enhancement workflow (`generate contracts-prompt` / `contracts-apply`) +- Validation loop pattern with retry mechanism +- CLI metadata detection utilities +- Prompt templates with dual-stack workflow documentation + +### ⏳ Pending + +- Code generation workflow (`generate code-prompt` / `code-apply`) +- Plan enrichment workflow (`plan enrich-prompt` / `enrich-apply`) +- CLI metadata injection into all generated artifacts +- Enhanced validation logic for format consistency + +## Testing + +### Unit Tests + +- `tests/unit/validators/test_cli_first_validator.py` - CLI-first validation utilities +- 23 test cases covering metadata extraction, format validation, and detection + +### Integration Tests + +- Contract enhancement workflow tests in `tests/integration/test_generate_contracts.py` +- Validation loop pattern tests in `tests/integration/test_contracts_apply.py` + +## Related Code + +- `src/specfact_cli/validators/cli_first_validator.py` - Validation utilities +- `src/specfact_cli/commands/generate.py` - Contract enhancement commands +- `resources/prompts/shared/cli-enforcement.md` - CLI enforcement rules +- `resources/prompts/specfact.*.md` - Slash command prompts with dual-stack workflow + +--- + +## Related Documentation + +- **[Dual-Stack Enrichment Guide](../guides/dual-stack-enrichment.md)** - End-user guide +- **[Architecture Documentation](../reference/architecture.md)** - Enforcement rules and quality gates +- **[Operational Modes](../reference/modes.md)** - CI/CD vs Copilot modes diff --git a/_site_test/technical/testing.md b/_site_test/technical/testing.md new file mode 100644 index 0000000..ad13d91 --- /dev/null +++ b/_site_test/technical/testing.md @@ -0,0 +1,901 @@ +# Testing Guide + +This document provides comprehensive guidance on testing the SpecFact CLI, including examples of how to test the `.specfact/` directory structure. + +## Table of Contents + +- [Test Organization](#test-organization) +- [Running Tests](#running-tests) +- [Unit Tests](#unit-tests) +- [Integration Tests](#integration-tests) +- [End-to-End Tests](#end-to-end-tests) +- [Testing Operational Modes](#testing-operational-modes) +- [Testing Sync Operations](#testing-sync-operations) +- [Testing Directory Structure](#testing-directory-structure) +- [Test Fixtures](#test-fixtures) +- [Best Practices](#best-practices) + +## Test Organization + +Tests are organized into three layers: + +```bash +tests/ +├── unit/ # Unit tests for individual modules +│ ├── analyzers/ # Code analyzer tests +│ ├── comparators/ # Plan comparator tests +│ ├── generators/ # Generator tests +│ ├── models/ # Data model tests +│ ├── utils/ # Utility tests +│ └── validators/ # Validator tests +├── integration/ # Integration tests for CLI commands +│ ├── analyzers/ # Analyze command tests +│ ├── comparators/ # Plan compare command tests +│ └── test_directory_structure.py # Directory structure tests +└── e2e/ # End-to-end workflow tests + ├── test_complete_workflow.py + └── test_directory_structure_workflow.py +``` + +## Running Tests + +### All Tests + +```bash +# Run all tests with coverage +hatch test --cover -v + +# Run specific test file +hatch test --cover -v tests/integration/test_directory_structure.py + +# Run specific test class +hatch test --cover -v tests/integration/test_directory_structure.py::TestDirectoryStructure + +# Run specific test method +hatch test --cover -v tests/integration/test_directory_structure.py::TestDirectoryStructure::test_ensure_structure_creates_directories +``` + +### Contract Testing (Brownfield & Greenfield) + +```bash +# Run contract tests +hatch run contract-test + +# Run contract validation +hatch run contract-test-contracts + +# Run scenario tests +hatch run contract-test-scenarios +``` + +## Unit Tests + +Unit tests focus on individual modules and functions. + +### Example: Testing CodeAnalyzer + +```python +def test_code_analyzer_extracts_features(tmp_path): + """Test that CodeAnalyzer extracts features from classes.""" + # Create test file + code = ''' +class UserService: + """User management service.""" + + def create_user(self, name): + """Create new user.""" + pass +''' + repo_path = tmp_path / "src" + repo_path.mkdir() + (repo_path / "service.py").write_text(code) + + # Analyze + analyzer = CodeAnalyzer(repo_path, confidence_threshold=0.5) + plan = analyzer.analyze() + + # Verify + assert len(plan.features) > 0 + assert any("User" in f.title for f in plan.features) +``` + +### Example: Testing PlanComparator + +```python +def test_plan_comparator_detects_missing_feature(): + """Test that PlanComparator detects missing features.""" + # Create plans + feature = Feature( + key="FEATURE-001", + title="Auth", + outcomes=["Login works"], + acceptance=["Users can login"], + ) + + manual_plan = PlanBundle( + version="1.0", + idea=None, + business=None, + product=Product(themes=[], releases=[]), + features=[feature], + ) + + auto_plan = PlanBundle( + version="1.0", + idea=None, + business=None, + product=Product(themes=[], releases=[]), + features=[], # Missing feature + ) + + # Compare + comparator = PlanComparator() + report = comparator.compare(manual_plan, auto_plan) + + # Verify + assert report.total_deviations == 1 + assert report.high_count == 1 + assert "FEATURE-001" in report.deviations[0].description +``` + +## Integration Tests + +Integration tests verify CLI commands work correctly. + +### Example: Testing `import from-code` + +```python +def test_analyze_code2spec_basic_repository(): + """Test analyzing a basic Python repository.""" + runner = CliRunner() + + with tempfile.TemporaryDirectory() as tmpdir: + # Create sample code + src_dir = Path(tmpdir) / "src" + src_dir.mkdir() + + code = ''' +class PaymentProcessor: + """Process payments.""" + def process_payment(self, amount): + """Process a payment.""" + pass +''' + (src_dir / "payment.py").write_text(code) + + # Run command (bundle name as positional argument) + result = runner.invoke( + app, + [ + "import", + "from-code", + "test-project", + "--repo", + tmpdir, + ], + ) + + # Verify + assert result.exit_code == 0 + assert "Analysis complete" in result.stdout or "Project bundle written" in result.stdout + + # Verify output in .specfact/ (modular bundle structure) + bundle_dir = Path(tmpdir) / ".specfact" / "projects" / "test-project" + assert bundle_dir.exists() + assert (bundle_dir / "bundle.manifest.yaml").exists() +``` + +### Example: Testing `plan compare` + +```python +def test_plan_compare_with_smart_defaults(tmp_path): + """Test plan compare finds plans using smart defaults.""" + # Create manual plan + manual_plan = PlanBundle( + version="1.0", + idea=Idea(title="Test", narrative="Test"), + business=None, + product=Product(themes=[], releases=[]), + features=[], + ) + + # Create modular project bundle (new structure) + bundle_dir = tmp_path / ".specfact" / "projects" / "main" + bundle_dir.mkdir(parents=True) + # Save as modular bundle structure + from specfact_cli.utils.bundle_loader import save_project_bundle + from specfact_cli.utils.bundle_loader import _convert_plan_bundle_to_project_bundle + project_bundle = _convert_plan_bundle_to_project_bundle(manual_plan, "main") + save_project_bundle(project_bundle, bundle_dir, atomic=True) + + # Create auto-derived plan (also as modular bundle) + auto_bundle_dir = tmp_path / ".specfact" / "projects" / "auto-derived" + auto_bundle_dir.mkdir(parents=True) + auto_project_bundle = _convert_plan_bundle_to_project_bundle(manual_plan, "auto-derived") + save_project_bundle(auto_project_bundle, auto_bundle_dir, atomic=True) + + # Run compare with --repo only + runner = CliRunner() + result = runner.invoke( + app, + [ + "plan", + "compare", + "--repo", + str(tmp_path), + ], + ) + + assert result.exit_code == 0 + assert "No deviations found" in result.stdout +``` + +## End-to-End Tests + +E2E tests verify complete workflows from start to finish. + +### Example: Complete Greenfield Workflow + +```python +def test_greenfield_workflow_with_scaffold(tmp_path): + """ + Test complete greenfield workflow: + 1. Init project with scaffold + 2. Verify structure created + 3. Edit plan manually + 4. Validate plan + """ + runner = CliRunner() + + # Step 1: Initialize project with scaffold (bundle name as positional argument) + result = runner.invoke( + app, + [ + "plan", + "init", + "e2e-test-project", + "--repo", + str(tmp_path), + "--scaffold", + "--no-interactive", + ], + ) + + assert result.exit_code == 0 + assert "Scaffolded .specfact directory structure" in result.stdout + + # Step 2: Verify structure (modular bundle structure) + specfact_dir = tmp_path / ".specfact" + bundle_dir = specfact_dir / "projects" / "e2e-test-project" + assert (bundle_dir / "bundle.manifest.yaml").exists() + assert (specfact_dir / "protocols").exists() + assert (specfact_dir / "reports" / "brownfield").exists() + assert (specfact_dir / ".gitignore").exists() + + # Step 3: Load and verify plan (modular bundle) + from specfact_cli.utils.bundle_loader import load_project_bundle + project_bundle = load_project_bundle(bundle_dir, validate_hashes=False) + assert project_bundle.manifest.versions.schema == "1.0" + assert project_bundle.idea.title == "E2E Test Project" +``` + +### Example: Complete Brownfield Workflow + +```python +def test_brownfield_analysis_workflow(tmp_path): + """ + Test complete brownfield workflow: + 1. Analyze existing codebase + 2. Verify project bundle generated in .specfact/projects// + 3. Create manual plan in .specfact/projects// + 4. Compare plans + 5. Verify comparison report in .specfact/projects//reports/comparison/ (bundle-specific, Phase 8.5) + """ + runner = CliRunner() + + # Step 1: Create sample codebase + src_dir = tmp_path / "src" + src_dir.mkdir() + + (src_dir / "users.py").write_text(''' +class UserService: + """Manages user operations.""" + def create_user(self, name, email): + """Create a new user account.""" + pass + def get_user(self, user_id): + """Retrieve user by ID.""" + pass +''') + + # Step 2: Run brownfield analysis (bundle name as positional argument) + result = runner.invoke( + app, + ["import", "from-code", "brownfield-test", "--repo", str(tmp_path)], + ) + assert result.exit_code == 0 + + # Step 3: Verify project bundle (modular structure) + bundle_dir = tmp_path / ".specfact" / "projects" / "brownfield-test" + auto_reports = list(brownfield_dir.glob("auto-derived.*.yaml")) + assert len(auto_reports) > 0 + + # Step 4: Create manual plan + # ... (create and save manual plan) + + # Step 5: Run comparison + result = runner.invoke( + app, + ["plan", "compare", "--repo", str(tmp_path)], + ) + assert result.exit_code == 0 + + # Step 6: Verify comparison report + comparison_dir = tmp_path / ".specfact" / "reports" / "comparison" + comparison_reports = list(comparison_dir.glob("report-*.md")) + assert len(comparison_reports) > 0 +``` + +## Testing Operational Modes + +SpecFact CLI supports two operational modes that should be tested: + +### Testing CI/CD Mode + +```python +def test_analyze_cicd_mode(tmp_path): + """Test analyze command in CI/CD mode.""" + runner = CliRunner() + + # Create sample code + src_dir = tmp_path / "src" + src_dir.mkdir() + (src_dir / "service.py").write_text(''' +class UserService: + """User management service.""" + def create_user(self, name): + """Create new user.""" + pass +''') + + # Run in CI/CD mode + result = runner.invoke( + app, + [ + "--mode", + "cicd", + "analyze", + "code2spec", + "--repo", + str(tmp_path), + ], + ) + + assert result.exit_code == 0 + assert "Analysis complete" in result.stdout + + # Verify deterministic output + brownfield_dir = tmp_path / ".specfact" / "reports" / "brownfield" + reports = list(brownfield_dir.glob("auto-derived.*.yaml")) + assert len(reports) > 0 +``` + +### Testing CoPilot Mode + +```python +def test_analyze_copilot_mode(tmp_path): + """Test analyze command in CoPilot mode.""" + runner = CliRunner() + + # Create sample code + src_dir = tmp_path / "src" + src_dir.mkdir() + (src_dir / "service.py").write_text(''' +class UserService: + """User management service.""" + def create_user(self, name): + """Create new user.""" + pass +''') + + # Run in CoPilot mode + result = runner.invoke( + app, + [ + "--mode", + "copilot", + "analyze", + "code2spec", + "--repo", + str(tmp_path), + "--confidence", + "0.7", + ], + ) + + assert result.exit_code == 0 + assert "Analysis complete" in result.stdout + + # CoPilot mode may provide enhanced prompts + # (behavior depends on CoPilot availability) +``` + +### Testing Mode Auto-Detection + +```python +def test_mode_auto_detection(tmp_path): + """Test that mode is auto-detected correctly.""" + runner = CliRunner() + + # Without explicit mode, should auto-detect (bundle name as positional argument) + result = runner.invoke( + app, + ["import", "from-code", "test-project", "--repo", str(tmp_path)], + ) + + assert result.exit_code == 0 + # Default to CI/CD mode if CoPilot not available +``` + +## Testing Sync Operations + +Sync operations require thorough testing for bidirectional synchronization: + +### Testing Spec-Kit Sync + +```python +def test_sync_speckit_one_way(tmp_path): + """Test one-way Spec-Kit sync (import).""" + # Create Spec-Kit structure + spec_dir = tmp_path / "spec" + spec_dir.mkdir() + (spec_dir / "components.yaml").write_text(''' +states: + - INIT + - PLAN +transitions: + - from_state: INIT + on_event: start + to_state: PLAN +''') + + runner = CliRunner() + result = runner.invoke( + app, + [ + "sync", + "bridge", + "--adapter", + "speckit", + "--repo", + str(tmp_path), + "--bundle", + "main", + ], + ) + + assert result.exit_code == 0 + # Verify SpecFact artifacts created (modular bundle structure) + bundle_dir = tmp_path / ".specfact" / "projects" / "main" + assert bundle_dir.exists() + assert (bundle_dir / "bundle.manifest.yaml").exists() +``` + +### Testing Bidirectional Sync + +```python +def test_sync_speckit_bidirectional(tmp_path): + """Test bidirectional Spec-Kit sync.""" + # Create Spec-Kit structure + spec_dir = tmp_path / "spec" + spec_dir.mkdir() + (spec_dir / "components.yaml").write_text(''' +states: + - INIT + - PLAN +transitions: + - from_state: INIT + on_event: start + to_state: PLAN +''') + + # Create SpecFact project bundle (modular structure) + from specfact_cli.models.project import ProjectBundle + from specfact_cli.models.bundle import BundleManifest, BundleVersions + from specfact_cli.models.plan import PlanBundle, Idea, Product, Feature + from specfact_cli.utils.bundle_loader import save_project_bundle + + plan_bundle = PlanBundle( + version="1.0", + idea=Idea(title="Test", narrative="Test"), + product=Product(themes=[], releases=[]), + features=[Feature(key="FEATURE-001", title="Test Feature")], + ) + bundle_dir = tmp_path / ".specfact" / "projects" / "main" + bundle_dir.mkdir(parents=True) + from specfact_cli.utils.bundle_loader import _convert_plan_bundle_to_project_bundle + project_bundle = _convert_plan_bundle_to_project_bundle(plan_bundle, "main") + save_project_bundle(project_bundle, bundle_dir, atomic=True) + + runner = CliRunner() + result = runner.invoke( + app, + [ + "sync", + "bridge", + "--adapter", + "speckit", + "--repo", + str(tmp_path), + "--bundle", + "main", + "--bidirectional", + ], + ) + + assert result.exit_code == 0 + # Verify both directions synced +``` + +### Testing Repository Sync + +```python +def test_sync_repository(tmp_path): + """Test repository sync.""" + # Create sample code + src_dir = tmp_path / "src" + src_dir.mkdir() + (src_dir / "service.py").write_text(''' +class UserService: + """User management service.""" + def create_user(self, name): + """Create new user.""" + pass +''') + + runner = CliRunner() + result = runner.invoke( + app, + [ + "sync", + "repository", + "--repo", + str(tmp_path), + "--target", + ".specfact", + ], + ) + + assert result.exit_code == 0 + # Verify plan artifacts updated + brownfield_dir = tmp_path / ".specfact" / "reports" / "sync" + assert brownfield_dir.exists() +``` + +### Testing Watch Mode + +```python +import time +from unittest.mock import patch + +def test_sync_watch_mode(tmp_path): + """Test watch mode for continuous sync.""" + # Create sample code + src_dir = tmp_path / "src" + src_dir.mkdir() + (src_dir / "service.py").write_text(''' +class UserService: + """User management service.""" + def create_user(self, name): + """Create new user.""" + pass +''') + + runner = CliRunner() + + # Test watch mode with short interval + with patch('time.sleep') as mock_sleep: + result = runner.invoke( + app, + [ + "sync", + "repository", + "--repo", + str(tmp_path), + "--watch", + "--interval", + "1", + ], + input="\n", # Press Enter to stop after first iteration + ) + + # Watch mode should run at least once + assert mock_sleep.called +``` + +## Testing Directory Structure + +The `.specfact/` directory structure is a core feature that requires thorough testing. + +### Testing Directory Creation + +```python +def test_ensure_structure_creates_directories(tmp_path): + """Test that ensure_structure creates all required directories.""" + repo_path = tmp_path / "test_repo" + repo_path.mkdir() + + # Ensure structure + SpecFactStructure.ensure_structure(repo_path) + + # Verify all directories exist (modular bundle structure) + specfact_dir = repo_path / ".specfact" + assert specfact_dir.exists() + assert (specfact_dir / "projects").exists() # Modular bundles directory + assert (specfact_dir / "protocols").exists() + assert (specfact_dir / "reports" / "brownfield").exists() + assert (specfact_dir / "reports" / "comparison").exists() + assert (specfact_dir / "gates" / "results").exists() + assert (specfact_dir / "cache").exists() +``` + +### Testing Scaffold Functionality + +```python +def test_scaffold_project_creates_full_structure(tmp_path): + """Test that scaffold_project creates complete directory structure.""" + repo_path = tmp_path / "test_repo" + repo_path.mkdir() + + # Scaffold project + SpecFactStructure.scaffold_project(repo_path) + + # Verify directories (modular bundle structure) + specfact_dir = repo_path / ".specfact" + assert (specfact_dir / "projects").exists() # Modular bundles directory + assert (specfact_dir / "protocols").exists() + assert (specfact_dir / "reports" / "brownfield").exists() + assert (specfact_dir / "gates" / "config").exists() + + # Verify .gitignore + gitignore = specfact_dir / ".gitignore" + assert gitignore.exists() + + gitignore_content = gitignore.read_text() + assert "reports/" in gitignore_content + assert "gates/results/" in gitignore_content + assert "cache/" in gitignore_content + assert "!projects/" in gitignore_content # Projects directory should be versioned +``` + +### Testing Smart Defaults + +```python +def test_analyze_default_paths(tmp_path): + """Test that analyze uses .specfact/ paths by default.""" + # Create sample code + src_dir = tmp_path / "src" + src_dir.mkdir() + (src_dir / "test.py").write_text(''' +class TestService: + """Test service.""" + def test_method(self): + """Test method.""" + pass +''') + + runner = CliRunner() + result = runner.invoke( + app, + ["import", "from-code", "test-project", "--repo", str(tmp_path)], + ) + + assert result.exit_code == 0 + + # Verify files in .specfact/ + brownfield_dir = tmp_path / ".specfact" / "reports" / "brownfield" + assert brownfield_dir.exists() + reports = list(brownfield_dir.glob("auto-derived.*.yaml")) + assert len(reports) > 0 +``` + +## Test Fixtures + +Use pytest fixtures to reduce code duplication. + +### Common Fixtures + +```python +@pytest.fixture +def tmp_repo(tmp_path): + """Create a temporary repository with .specfact structure.""" + repo_path = tmp_path / "test_repo" + repo_path.mkdir() + SpecFactStructure.scaffold_project(repo_path) + return repo_path + +@pytest.fixture +def sample_plan(): + """Create a sample plan bundle.""" + return PlanBundle( + version="1.0", + idea=Idea(title="Test Project", narrative="Test"), + business=None, + product=Product(themes=["Testing"], releases=[]), + features=[], + ) + +@pytest.fixture +def sample_code(tmp_path): + """Create sample Python code for testing.""" + src_dir = tmp_path / "src" + src_dir.mkdir() + code = ''' +class SampleService: + """Sample service for testing.""" + def sample_method(self): + """Sample method.""" + pass +''' + (src_dir / "sample.py").write_text(code) + return tmp_path +``` + +### Using Fixtures + +```python +def test_with_fixtures(tmp_repo, sample_plan): + """Test using fixtures.""" + # Use pre-configured repository (modular bundle structure) + from specfact_cli.utils.bundle_loader import save_project_bundle, _convert_plan_bundle_to_project_bundle + bundle_dir = tmp_repo / ".specfact" / "projects" / "main" + bundle_dir.mkdir(parents=True) + project_bundle = _convert_plan_bundle_to_project_bundle(sample_plan, "main") + save_project_bundle(project_bundle, bundle_dir, atomic=True) + + assert bundle_dir.exists() + assert (bundle_dir / "bundle.manifest.yaml").exists() +``` + +## Best Practices + +### 1. Test Isolation + +Ensure tests don't depend on each other or external state: + +```python +def test_isolated(tmp_path): + """Each test gets its own tmp_path.""" + # Use tmp_path for all file operations + repo_path = tmp_path / "repo" + repo_path.mkdir() + # Test logic... +``` + +### 2. Clear Test Names + +Use descriptive test names that explain what is being tested: + +```python +def test_plan_compare_detects_missing_feature_in_auto_plan(): + """Good: Clear what is being tested.""" + pass + +def test_compare(): + """Bad: Unclear what is being tested.""" + pass +``` + +### 3. Arrange-Act-Assert Pattern + +Structure tests clearly: + +```python +def test_example(): + # Arrange: Setup test data + plan = create_test_plan() + + # Act: Execute the code being tested + result = process_plan(plan) + + # Assert: Verify results + assert result.success is True +``` + +### 4. Test Both Success and Failure Cases + +```python +def test_valid_plan_passes_validation(): + """Test success case.""" + plan = create_valid_plan() + report = validate_plan_bundle(plan) + assert report.passed is True + +def test_invalid_plan_fails_validation(): + """Test failure case.""" + plan = create_invalid_plan() + report = validate_plan_bundle(plan) + assert report.passed is False + assert len(report.deviations) > 0 +``` + +### 5. Use Assertions Effectively + +```python +def test_with_good_assertions(): + """Use specific assertions with helpful messages.""" + result = compute_value() + + # Good: Specific assertion + assert result == 42, f"Expected 42, got {result}" + + # Good: Multiple specific assertions + assert result > 0, "Result should be positive" + assert result < 100, "Result should be less than 100" +``` + +### 6. Mock External Dependencies + +```python +from unittest.mock import Mock, patch + +def test_with_mocking(): + """Mock external API calls.""" + with patch('module.external_api_call') as mock_api: + mock_api.return_value = {"status": "success"} + + result = function_that_calls_api() + + assert result.status == "success" + mock_api.assert_called_once() +``` + +## Running Specific Test Suites + +```bash +# Run only unit tests +hatch test --cover -v tests/unit/ + +# Run only integration tests +hatch test --cover -v tests/integration/ + +# Run only E2E tests +hatch test --cover -v tests/e2e/ + +# Run tests matching a pattern +hatch test --cover -v -k "directory_structure" + +# Run tests with verbose output +hatch test --cover -vv tests/ + +# Run tests and stop on first failure +hatch test --cover -v -x tests/ +``` + +## Coverage Goals + +- **Unit tests**: Target 90%+ coverage for individual modules +- **Integration tests**: Cover all CLI commands and major workflows +- **E2E tests**: Cover complete user journeys +- **Operational modes**: Test both CI/CD and CoPilot modes +- **Sync operations**: Test bidirectional sync, watch mode, and conflict resolution + +## Continuous Integration + +Tests run automatically on: + +- Every commit +- Pull requests +- Before releases + +CI configuration ensures: + +- All tests pass +- Coverage thresholds met +- No linter errors + +## Additional Resources + +- [pytest documentation](https://docs.pytest.org/) +- [Typer testing guide](https://typer.tiangolo.com/tutorial/testing/) +- [Python testing best practices](https://docs.python-guide.org/writing/tests/) diff --git a/_site_test/testing-terminal-output/index.html b/_site_test/testing-terminal-output/index.html new file mode 100644 index 0000000..54097ad --- /dev/null +++ b/_site_test/testing-terminal-output/index.html @@ -0,0 +1,417 @@ + + + + + + + +Testing Terminal Output Modes | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Testing Terminal Output Modes

+ +

This guide explains how to test SpecFact CLI’s terminal output auto-detection on Ubuntu/GNOME systems.

+ +

Quick Test Methods

+ +

Method 1: Use NO_COLOR (Easiest)

+ +

The NO_COLOR environment variable is the standard way to disable colors:

+ +
# Test in current terminal session
+NO_COLOR=1 specfact --help
+
+# Or export for the entire session
+export NO_COLOR=1
+specfact import from-code my-bundle
+unset NO_COLOR  # Re-enable colors
+
+ +

Method 2: Simulate CI/CD Environment

+ +

Simulate a CI/CD pipeline (BASIC mode):

+ +
# Set CI environment variable
+CI=true specfact --help
+
+# Or simulate GitHub Actions
+GITHUB_ACTIONS=true specfact import from-code my-bundle
+
+ +

Method 3: Use Dumb Terminal Type

+ +

Force a “dumb” terminal that doesn’t support colors:

+ +
# Start a terminal with dumb TERM
+TERM=dumb specfact --help
+
+# Or use vt100 (minimal terminal)
+TERM=vt100 specfact --help
+
+ +

Method 4: Redirect to Non-TTY

+ +

Redirect output to a file or pipe (non-interactive):

+ +
# Redirect to file (non-TTY)
+specfact --help > output.txt 2>&1
+cat output.txt
+
+# Pipe to another command (non-TTY)
+specfact --help | cat
+
+ +

Method 5: Use script Command

+ +

The script command can create a non-interactive session:

+ +
# Create a script session (records to typescript file)
+script -c "specfact --help" output.txt
+
+# Or use script with dumb terminal
+TERM=dumb script -c "specfact --help" output.txt
+
+ +

Testing in GNOME Terminal

+ +

Option A: Launch Terminal with NO_COLOR

+ +
# Launch gnome-terminal with NO_COLOR set
+gnome-terminal -- bash -c "export NO_COLOR=1; specfact --help; exec bash"
+
+ +

Option B: Create a Test Script

+ +

Create a test script test-no-color.sh:

+ +
#!/bin/bash
+export NO_COLOR=1
+specfact --help
+
+ +

Then run:

+ +
chmod +x test-no-color.sh
+./test-no-color.sh
+
+ +

Option C: Use Different Terminal Emulators

+ +

Install and test with different terminal emulators:

+ +
# Install alternative terminals
+sudo apt install xterm terminator
+
+# Test with xterm (can be configured for minimal support)
+xterm -e "NO_COLOR=1 specfact --help"
+
+# Test with terminator
+terminator -e "NO_COLOR=1 specfact --help"
+
+ +

Verifying Terminal Mode Detection

+ +

You can verify which mode is detected:

+ +
# Check detected terminal mode
+python3 -c "from specfact_cli.runtime import get_terminal_mode; print(get_terminal_mode())"
+
+# Check terminal capabilities
+python3 -c "
+from specfact_cli.utils.terminal import detect_terminal_capabilities
+caps = detect_terminal_capabilities()
+print(f'Color: {caps.supports_color}')
+print(f'Animations: {caps.supports_animations}')
+print(f'Interactive: {caps.is_interactive}')
+print(f'CI: {caps.is_ci}')
+"
+
+ +

Expected Behavior

+ +

GRAPHICAL Mode (Default in Full Terminal)

+ +
    +
  • ✅ Colors enabled
    • +
  • ✅ Animations enabled
    • +
  • ✅ Full progress bars
    • +
  • ✅ Rich formatting
    • +
+ +

BASIC Mode (NO_COLOR or CI/CD)

+ +
    +
  • ❌ No colors
    • +
  • ❌ No animations
    • +
  • ✅ Plain text progress updates
    • +
  • ✅ Readable output
    • +
+ +

MINIMAL Mode (TEST_MODE)

+ +
    +
  • ❌ No colors
    • +
  • ❌ No animations
    • +
  • ❌ Minimal output
    • +
  • ✅ Test-friendly
    • +
+ +

Complete Test Workflow

+ +
# 1. Test with colors (default)
+specfact --help
+
+# 2. Test without colors (NO_COLOR)
+NO_COLOR=1 specfact --help
+
+# 3. Test CI/CD mode
+CI=true specfact --help
+
+# 4. Test minimal mode
+TEST_MODE=true specfact --help
+
+# 5. Verify detection
+python3 -c "from specfact_cli.runtime import get_terminal_mode; print(get_terminal_mode())"
+
+ +

Troubleshooting

+ +

If terminal detection isn’t working as expected:

+ +
    +
  1. +

    Check environment variables:

    + + 
    echo "NO_COLOR: $NO_COLOR"
+echo "FORCE_COLOR: $FORCE_COLOR"
+echo "TERM: $TERM"
+echo "CI: $CI"
+
    +
    2. +
  2. +

    Verify TTY status:

    + + 
    python3 -c "import sys; print('Is TTY:', sys.stdout.isatty())"
+
    +
    3. +
  3. +

    Check terminal capabilities:

    + + 
    python3 -c "
+from specfact_cli.utils.terminal import detect_terminal_capabilities
+import json
+caps = detect_terminal_capabilities()
+print(json.dumps({
+    'supports_color': caps.supports_color,
+    'supports_animations': caps.supports_animations,
+    'is_interactive': caps.is_interactive,
+    'is_ci': caps.is_ci
+}, indent=2))
+"
+
    +
    4. +
+ + + +
    +
  • Troubleshooting - Terminal output issues and auto-detection
    • +
  • UX Features - User experience features including terminal output
    • +
+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/troubleshooting/index.html b/_site_test/troubleshooting/index.html new file mode 100644 index 0000000..2ac22df --- /dev/null +++ b/_site_test/troubleshooting/index.html @@ -0,0 +1,987 @@ + + + + + + + +Troubleshooting | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Troubleshooting

+ +

Common issues and solutions for SpecFact CLI.

+ +

Installation Issues

+ +

Command Not Found

+ +

Issue: specfact: command not found

+ +

Solutions:

+ +
    +
  1. +

    Check installation:

    + + 
    pip show specfact-cli
+
    +
    2. +
  2. +

    Reinstall:

    + + 
    pip install --upgrade specfact-cli
+
    +
    3. +
+ +

Plan Select Command is Slow

+ +

Symptom: specfact plan select takes a long time (5+ seconds) to list plans.

+ +

Cause: Plan bundles may be missing summary metadata (older schema version 1.0).

+ +

Solution:

+ +
# Upgrade all plan bundles to latest schema (adds summary metadata)
+specfact plan upgrade --all
+
+# Verify upgrade worked
+specfact plan select --last 5
+
+ +

Performance Improvement: After upgrade, plan select is 44% faster (3.6s vs 6.5s) and scales better with large plan bundles.

+ +
    +
  1. +

    Use uvx (no installation needed):

    + + 
    uvx specfact-cli@latest --help
+
    +
    2. +
+ +

Permission Denied

+ +

Issue: Permission denied when running commands

+ +

Solutions:

+ +
    +
  1. +

    Use user install:

    + + 
    pip install --user specfact-cli
+
    +
    2. +
  2. +

    Check PATH:

    + + 
    echo $PATH
+# Should include ~/.local/bin
+
    +
    3. +
  3. +

    Add to PATH:

    + + 
    export PATH="$HOME/.local/bin:$PATH"
+
    +
    4. +
+ +
+ +

Import Issues

+ +

Spec-Kit Not Detected

+ +

Issue: No Spec-Kit project found when running import from-bridge --adapter speckit

+ +

Solutions:

+ +
    +
  1. +

    Check directory structure:

    + + 
    ls -la .specify/
+ls -la specs/
+
    +
    2. +
  2. +

    Verify Spec-Kit format:

    + +
      +
    • Should have .specify/ directory
      • +
    • Should have specs/ directory with feature folders
      • +
    • Should have specs/[###-feature-name]/spec.md files
      • +
    +
    3. +
  3. +

    Use explicit path:

    + + 
    specfact import from-bridge --adapter speckit --repo /path/to/speckit-project
+
    +
    4. +
+ +

Code Analysis Fails (Brownfield) ⭐

+ +

Issue: Analysis failed or No features detected when analyzing legacy code

+ +

Solutions:

+ +
    +
  1. +

    Check repository path:

    + + 
    specfact import from-code --bundle legacy-api --repo . --verbose
+
    +
    2. +
  2. +

    Lower confidence threshold (for legacy code with less structure):

    + + 
    specfact import from-code --bundle legacy-api --repo . --confidence 0.3
+
    +
    3. +
  3. +

    Check file structure:

    + + 
    find . -name "*.py" -type f | head -10
+
    +
    4. +
  4. +

    Use CoPilot mode (recommended for brownfield - better semantic understanding):

    + + 
    specfact --mode copilot import from-code --bundle legacy-api --repo . --confidence 0.7
+
    +
    5. +
  5. +

    For legacy codebases, start with minimal confidence and review extracted features:

    + + 
    specfact import from-code --bundle legacy-api --repo . --confidence 0.2
+
    +
    6. +
+ +
+ +

Sync Issues

+ +

Watch Mode Not Starting

+ +

Issue: Watch mode exits immediately or doesn’t detect changes

+ +

Solutions:

+ +
    +
  1. +

    Check repository path:

    + + 
    specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --watch --interval 5 --verbose
+
    +
    2. +
  2. +

    Verify directory exists:

    + + 
    ls -la .specify/
+ls -la .specfact/
+
    +
    3. +
  3. +

    Check permissions:

    + + 
    ls -la .specfact/projects/
+
    +
    4. +
  4. +

    Try one-time sync first:

    + + 
    specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
    +
    5. +
+ +

Bidirectional Sync Conflicts

+ +

Issue: Conflicts during bidirectional sync

+ +

Solutions:

+ +
    +
  1. +

    Check conflict resolution:

    + +
      +
    • SpecFact takes priority by default
      • +
    • Manual resolution may be needed
      • +
    +
    2. +
  2. +

    Review changes:

    + + 
    git status
+git diff
+
    +
    3. +
  3. +

    Use one-way sync:

    + + 
    # Spec-Kit → SpecFact only
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo .
+
+# SpecFact → Spec-Kit only (manual)
+# Edit Spec-Kit files manually
+
    +
    4. +
+ +
+ +

Enforcement Issues

+ +

Enforcement Not Working

+ +

Issue: Violations not being blocked or warned

+ +

Solutions:

+ +
    +
  1. +

    Check enforcement configuration (use CLI commands):

    + + 
    specfact enforce show-config
+
    +
    2. +
  2. +

    Verify enforcement mode:

    + + 
    specfact enforce stage --preset balanced
+
    +
    3. +
  3. +

    Run validation:

    + + 
    specfact repro --verbose
+
    +
    4. +
  4. +

    Check severity levels:

    + +
      +
    • HIGH → BLOCK (in balanced/strict mode)
      • +
    • MEDIUM → WARN (in balanced/strict mode)
      • +
    • LOW → LOG (in all modes)
      • +
    +
    5. +
+ +

False Positives

+ +

Issue: Valid code being flagged as violations

+ +

Solutions:

+ +
    +
  1. +

    Review violation details:

    + + 
    specfact repro --verbose
+
    +
    2. +
  2. +

    Adjust confidence threshold:

    + + 
    specfact import from-code --bundle legacy-api --repo . --confidence 0.7
+
    +
    3. +
  3. +

    Check enforcement rules (use CLI commands):

    + + 
    specfact enforce show-config
+
    +
    4. +
  4. +

    Use minimal mode (observe only):

    + + 
    specfact enforce stage --preset minimal
+
    +
    5. +
+ +
+ +

Constitution Issues

+ +

Constitution Missing or Minimal

+ +

Issue: Constitution required or Constitution is minimal when running sync bridge --adapter speckit

+ +

Solutions:

+ +
    +
  1. +

    Auto-generate bootstrap constitution (recommended for brownfield):

    + + 
    specfact sdd constitution bootstrap --repo .
+
    + +

    This analyzes your repository (README.md, pyproject.toml, .cursor/rules/, docs/rules/) and generates a bootstrap constitution.

    +
    2. +
  2. +

    Enrich existing minimal constitution:

    + + 
    specfact sdd constitution enrich --repo .
+
    + +

    This fills placeholders in an existing constitution with repository context.

    +
    3. +
  3. +

    Validate constitution completeness:

    + + 
    specfact sdd constitution validate
+
    + +

    This checks if the constitution is complete and ready for use.

    +
    4. +
  4. +

    Manual creation (for greenfield):

    + +
      +
    • Run /speckit.constitution command in your AI assistant
      • +
    • Fill in the constitution template manually
      • +
    +
    5. +
+ +

When to use each option:

+ +
    +
  • Bootstrap (brownfield): Use when you want to extract principles from existing codebase
    • +
  • Enrich (existing constitution): Use when you have a minimal constitution with placeholders
    • +
  • Manual (greenfield): Use when starting a new project and want full control
    • +
+ +

Constitution Validation Fails

+ +

Issue: specfact sdd constitution validate reports issues

+ +

Solutions:

+ +
    +
  1. +

    Check for placeholders:

    + + 
    grep -r "\[.*\]" .specify/memory/constitution.md
+
    +
    2. +
  2. +

    Run enrichment:

    + + 
    specfact sdd constitution enrich --repo .
+
    +
    3. +
  3. +

    Review validation output:

    + + 
    specfact sdd constitution validate --constitution .specify/memory/constitution.md
+
    + +

    The output will list specific issues (missing sections, placeholders, etc.).

    +
    4. +
  4. +

    Fix issues manually or re-run bootstrap:

    + + 
    specfact sdd constitution bootstrap --repo . --overwrite
+
    +
    5. +
+ +
+ +

Plan Comparison Issues

+ +

Plans Not Found

+ +

Issue: Plan not found when running plan compare

+ +

Solutions:

+ +
    +
  1. +

    Check plan locations:

    + + 
    ls -la .specfact/projects/
+ls -la .specfact/projects/<bundle-name>/reports/brownfield/
+
    +
    2. +
  2. +

    Use explicit paths (bundle directory paths):

    + + 
    specfact plan compare \
+  --manual .specfact/projects/manual-plan \
+  --auto .specfact/projects/auto-derived
+
    +
    3. +
  3. +

    Generate auto-derived plan first:

    + + 
    specfact import from-code --bundle legacy-api --repo .
+
    +
    4. +
+ +

No Deviations Found (Expected Some)

+ +

Issue: Comparison shows no deviations but you expect some

+ +

Solutions:

+ +
    +
  1. +

    Check feature key normalization:

    + +
      +
    • Different key formats may normalize to the same key
      • +
    • Check reference/feature-keys.md for details
      • +
    +
    2. +
  2. +

    Verify plan contents (use CLI commands):

    + + 
    specfact plan review <bundle-name>
+
    +
    3. +
  3. +

    Use verbose mode:

    + + 
    specfact plan compare --bundle legacy-api --verbose
+
    +
    4. +
+ +
+ +

IDE Integration Issues

+ +

Slash Commands Not Working

+ +

Issue: Slash commands not recognized in IDE

+ +

Solutions:

+ +
    +
  1. +

    Reinitialize IDE integration:

    + + 
    specfact init --ide cursor --force
+
    +
    2. +
  2. +

    Check command files:

    + + 
    ls -la .cursor/commands/specfact-*.md
+
    +
    3. +
  3. +

    Restart IDE: Some IDEs require restart to discover new commands

    +
    4. +
  4. +

    Check IDE settings:

    + +
      +
    • VS Code: Check .vscode/settings.json
      • +
    • Cursor: Check .cursor/settings.json
      • +
    +
    5. +
+ +

Command Files Not Created

+ +

Issue: Command files not created after specfact init

+ +

Solutions:

+ +
    +
  1. +

    Check permissions:

    + + 
    ls -la .cursor/commands/
+
    +
    2. +
  2. +

    Use force flag:

    + + 
    specfact init --ide cursor --force
+
    +
    3. +
  3. +

    Check IDE type:

    + + 
    specfact init --ide cursor  # For Cursor
+specfact init --ide vscode  # For VS Code
+
    +
    4. +
+ +
+ +

Mode Detection Issues

+ +

Wrong Mode Detected

+ +

Issue: CI/CD mode when CoPilot should be detected (or vice versa)

+ +

Solutions:

+ +
    +
  1. +

    Use explicit mode:

    + + 
    specfact --mode copilot import from-code my-project --repo .
+
    +
    2. +
  2. +

    Check environment variables:

    + + 
    echo $COPILOT_API_URL
+echo $VSCODE_PID
+
    +
    3. +
  3. +

    Set mode explicitly:

    + + 
    export SPECFACT_MODE=copilot
+specfact import from-code --bundle legacy-api --repo .
+
    +
    4. +
  4. +

    See Operational Modes for details

    +
    5. +
+ +
+ +

Performance Issues

+ +

Slow Analysis

+ +

Issue: Code analysis takes too long

+ +

Solutions:

+ +
    +
  1. +

    Use CI/CD mode (faster):

    + + 
    specfact --mode cicd import from-code my-project --repo .
+
    +
    2. +
  2. +

    Increase confidence threshold (fewer features):

    + + 
    specfact import from-code --bundle legacy-api --repo . --confidence 0.8
+
    +
    3. +
  3. +

    Exclude directories:

    + + 
    # Use .gitignore or exclude patterns
+specfact import from-code --bundle legacy-api --repo . --exclude "tests/"
+
    +
    4. +
+ +

Watch Mode High CPU

+ +

Issue: Watch mode uses too much CPU

+ +

Solutions:

+ +
    +
  1. +

    Increase interval:

    + + 
    specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --watch --interval 10
+
    +
    2. +
  2. +

    Use one-time sync:

    + + 
    specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
    +
    3. +
  3. +

    Check file system events:

    + +
      +
    • Too many files being watched
      • +
    • Consider excluding directories
      • +
    +
    4. +
+ +
+ +

Terminal Output Issues

+ +

SpecFact CLI automatically detects terminal capabilities and adjusts output formatting for optimal user experience across different environments. No manual configuration required - the CLI adapts to your terminal environment.

+ +

How Terminal Auto-Detection Works

+ +

The CLI automatically detects terminal capabilities in this order:

+ +
    +
  1. Test Mode Detection: +
      +
    • TEST_MODE=true or PYTEST_CURRENT_TEST → MINIMAL mode
      • +
    +
    2. +
  2. CI/CD Detection: +
      +
    • CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, TRAVIS, JENKINS_URL, BUILDKITE → BASIC mode
      • +
    +
    3. +
  3. Color Support Detection: +
      +
    • NO_COLOR → Disables colors (respects NO_COLOR standard)
      • +
    • FORCE_COLOR=1 → Forces colors
      • +
    • TERM and COLORTERM environment variables → Additional hints
      • +
    +
    4. +
  4. Terminal Type Detection: +
      +
    • TTY detection (sys.stdout.isatty()) → Interactive vs non-interactive
      • +
    • Interactive TTY with animations → GRAPHICAL mode
      • +
    • Non-interactive → BASIC mode
      • +
    +
    5. +
  5. Default Fallback: +
      +
    • If uncertain → BASIC mode (safe, readable output)
      • +
    +
    6. +
+ +

Terminal Modes

+ +

The CLI supports three terminal modes (auto-selected based on detection):

+ +
    +
  • GRAPHICAL - Full Rich features (colors, animations, progress bars) for interactive terminals
    • +
  • BASIC - Plain text, no animations, simple progress updates for CI/CD and embedded terminals
    • +
  • MINIMAL - Minimal output for test mode
    • +
+ +

Environment Variables (Optional Overrides)

+ +

You can override auto-detection using standard environment variables:

+ +
    +
  • NO_COLOR - Disables all colors (respects NO_COLOR standard)
    • +
  • FORCE_COLOR=1 - Forces color output even in non-interactive terminals
    • +
  • CI=true - Explicitly enables basic mode (no animations, plain text)
    • +
  • TEST_MODE=true - Enables minimal mode for testing
    • +
+ +

Examples

+ +
# Auto-detection (default behavior)
+specfact import from-code my-bundle
+# → Automatically detects terminal and uses appropriate mode
+
+# Manual override: Disable colors
+NO_COLOR=1 specfact import from-code my-bundle
+
+# Manual override: Force colors in CI/CD
+FORCE_COLOR=1 specfact sync bridge
+
+# Manual override: Explicit CI/CD mode
+CI=true specfact import from-code my-bundle
+
+ +

No Progress Visible in Embedded Terminals

+ +

Issue: No progress indicators visible when running commands in Cursor, VS Code, or other embedded terminals.

+ +

Cause: Embedded terminals are non-interactive and may not support Rich animations.

+ +

Solution: The CLI automatically detects embedded terminals and switches to basic mode with plain text progress updates. If you still don’t see progress:

+ +
    +
  1. +

    Verify auto-detection is working:

    + + 
    # Check terminal mode (should show BASIC in embedded terminals)
+python -c "from specfact_cli.runtime import get_terminal_mode; print(get_terminal_mode())"
+
    +
    2. +
  2. +

    Check environment variables:

    + + 
    # Ensure NO_COLOR is not set (unless you want plain text)
+unset NO_COLOR
+
    +
    3. +
  3. Verify terminal supports stdout: +
      +
    • Embedded terminals should support stdout (not stderr-only)
      • +
    • Progress updates are throttled - wait a few seconds for updates
      • +
    +
    4. +
  4. +

    Manual override (if needed):

    + + 
    # Force basic mode
+CI=true specfact import from-code my-bundle
+
    +
    5. +
+ +

Colors Not Working in CI/CD

+ +

Issue: No colors in CI/CD pipeline output.

+ +

Cause: CI/CD environments are automatically detected and use basic mode (no colors) for better log readability.

+ +

Solution: This is expected behavior. CI/CD logs are more readable without colors. To force colors:

+ +
FORCE_COLOR=1 specfact import from-code my-bundle
+
+ +
+ +

Getting Help

+ +

If you’re still experiencing issues:

+ +
    +
  1. +

    Check logs:

    + + 
    specfact repro --verbose 2>&1 | tee debug.log
+
    +
    2. +
  2. +

    Search documentation:

    + + +
    3. +
  3. +

    Community support:

    + + +
    4. +
  4. +

    Direct support:

    + + +
    5. +
+ +

Happy building! 🚀

+ +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/use-cases/index.html b/_site_test/use-cases/index.html new file mode 100644 index 0000000..66f711d --- /dev/null +++ b/_site_test/use-cases/index.html @@ -0,0 +1,868 @@ + + + + + + + +Use Cases | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

Use Cases

+ +

Detailed use cases and examples for SpecFact CLI.

+ +
+

Primary Use Case: Brownfield code modernization (Use Case 1)
+Secondary Use Case: Adding enforcement to Spec-Kit projects (Use Case 2)
+Alternative: Greenfield spec-first development (Use Case 3)

+
+ +

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

+ +
+ +

Use Case 1: Brownfield Code Modernization ⭐ PRIMARY

+ +

Problem: Existing codebase with no specs, no documentation, or outdated documentation. Need to understand legacy code and add quality gates incrementally without breaking existing functionality.

+ +

Solution: Reverse engineer existing code into documented specs, then progressively enforce contracts to prevent regressions during modernization.

+ +

Steps

+ +

1. Analyze Code

+ +
# CI/CD mode (fast, deterministic) - Full repository
+specfact import from-code \
+  --repo . \
+  --shadow-only \
+  --confidence 0.7 \
+  --report analysis.md
+
+# Partial analysis (large codebases or monorepos)
+specfact import from-code \
+  --repo . \
+  --entry-point src/core \
+  --confidence 0.7 \
+  --name core-module \
+  --report analysis-core.md
+
+# CoPilot mode (enhanced prompts, interactive)
+specfact --mode copilot import from-code \
+  --repo . \
+  --confidence 0.7 \
+  --report analysis.md
+
+ +

With IDE Integration:

+ +
# First, initialize IDE integration
+specfact init --ide cursor
+
+# Then use slash command in IDE chat
+/specfact.01-import legacy-api --repo . --confidence 0.7
+
+ +

See IDE Integration Guide for setup instructions. See Integration Showcases for real examples of bugs fixed via IDE integrations.

+ +

What it analyzes (AI-First / CoPilot Mode):

+ +
    +
  • Semantic understanding of codebase (LLM)
    • +
  • Multi-language support (Python, TypeScript, JavaScript, PowerShell, etc.)
    • +
  • Actual priorities, constraints, unknowns from code context
    • +
  • Meaningful scenarios from acceptance criteria
    • +
  • High-quality Spec-Kit compatible artifacts
    • +
+ +

What it analyzes (AST-Based / CI/CD Mode):

+ +
    +
  • Module dependency graph (Python-only)
    • +
  • Commit history for feature boundaries
    • +
  • Test files for acceptance criteria
    • +
  • Type hints for API surfaces
    • +
  • Async patterns for anti-patterns
    • +
+ +

CoPilot Enhancement:

+ +
    +
  • Context injection (current file, selection, workspace)
    • +
  • Enhanced prompts for semantic understanding
    • +
  • Interactive assistance for complex codebases
    • +
  • Multi-language analysis support
    • +
+ +

2. Review Auto-Generated Plan

+ +
cat analysis.md
+
+ +

Expected sections:

+ +
    +
  • Features Detected - With confidence scores
    • +
  • Stories Inferred - From commit messages
    • +
  • API Surface - Public functions/classes
    • +
  • Async Patterns - Detected issues
    • +
  • State Machine - Inferred from code flow
    • +
+ +

3. Sync Repository Changes (Optional)

+ +

Keep plan artifacts updated as code changes:

+ +
# One-time sync
+specfact sync repository --repo . --target .specfact
+
+# Continuous watch mode
+specfact sync repository --repo . --watch --interval 5
+
+ +

What it tracks:

+ +
    +
  • Code changes → Plan artifact updates
    • +
  • Deviations from manual plans
    • +
  • Feature/story extraction from code
    • +
+ +

4. Compare with Manual Plan (if exists)

+ +
specfact plan compare \
+  --manual .specfact/projects/manual-plan \
+  --auto .specfact/projects/auto-derived \
+  --output-format markdown \
+  --out .specfact/projects/<bundle-name>/reports/comparison/deviation-report.md
+
+ +

With CoPilot:

+ +
# Use slash command in IDE chat (after specfact init)
+/specfact.compare --bundle legacy-api
+# Or with explicit paths: /specfact.compare --manual main.bundle.yaml --auto auto.bundle.yaml
+
+ +

CoPilot Enhancement:

+ +
    +
  • Deviation explanations
    • +
  • Fix suggestions
    • +
  • Interactive deviation review
    • +
+ +

Output:

+ +
# Deviation Report
+
+## Missing Features (in manual but not in auto)
+
+- FEATURE-003: User notifications
+  - Confidence: N/A (not detected in code)
+  - Recommendation: Implement or remove from manual plan
+
+## Extra Features (in auto but not in manual)
+
+- FEATURE-AUTO-001: Database migrations
+  - Confidence: 0.85
+  - Recommendation: Add to manual plan
+
+## Mismatched Stories
+
+- STORY-001: User login
+  - Manual acceptance: "OAuth 2.0 support"
+  - Auto acceptance: "Basic auth only"
+  - Severity: HIGH
+  - Recommendation: Update implementation or manual plan
+
+ +

5. Fix High-Severity Deviations

+ +

Focus on:

+ +
    +
  • Async anti-patterns - Blocking I/O in async functions
    • +
  • Missing contracts - APIs without validation
    • +
  • State machine gaps - Unreachable states
    • +
  • Test coverage - Missing acceptance tests
    • +
+ +

6. Progressive Enforcement

+ +
# Week 1-2: Shadow mode (observe)
+specfact enforce stage --preset minimal
+
+# Week 3-4: Balanced mode (warn on medium, block high)
+specfact enforce stage --preset balanced
+
+# Week 5+: Strict mode (block medium+)
+specfact enforce stage --preset strict
+
+ +

Expected Timeline (Brownfield Modernization)

+ +
    +
  • Analysis: 2-5 minutes
    • +
  • Review: 1-2 hours
    • +
  • High-severity fixes: 1-3 days
    • +
  • Shadow mode: 1-2 weeks
    • +
  • Production enforcement: After validation stabilizes
    • +
+ +
+ +

Use Case 2: GitHub Spec-Kit Migration (Secondary)

+ +

Problem: You have a Spec-Kit project but need automated enforcement, team collaboration, and production deployment quality gates.

+ +

Solution: Import Spec-Kit artifacts into SpecFact CLI for automated contract enforcement while keeping Spec-Kit for interactive authoring.

+ +

Steps (Spec-Kit Migration)

+ +

1. Preview Migration

+ +
specfact import from-bridge --adapter speckit --repo ./spec-kit-project --dry-run
+
+ +

Expected Output:

+ +
🔍 Analyzing Spec-Kit project via bridge adapter...
+✅ Found .specify/ directory (modern format)
+✅ Found specs/001-user-authentication/spec.md
+✅ Found specs/001-user-authentication/plan.md
+✅ Found specs/001-user-authentication/tasks.md
+✅ Found .specify/memory/constitution.md
+
+📊 Migration Preview:
+  - Will create: .specfact/projects/<bundle-name>/ (modular project bundle)
+  - Will create: .specfact/protocols/workflow.protocol.yaml (if FSM detected)
+  - Will create: .specfact/gates/config.yaml
+  - Will convert: Spec-Kit features → SpecFact Feature models
+  - Will convert: Spec-Kit user stories → SpecFact Story models
+  
+🚀 Ready to migrate (use --write to execute)
+
+ +

2. Execute Migration

+ +
specfact import from-bridge \
+  --adapter speckit \
+  --repo ./spec-kit-project \
+  --write \
+  --report migration-report.md
+
+ +

3. Review Generated Contracts

+ +
# Review using CLI commands
+specfact plan review <bundle-name>
+
+ +

Review:

+ +
    +
  • .specfact/projects/<bundle-name>/ - Modular project bundle (converted from Spec-Kit artifacts)
    • +
  • .specfact/protocols/workflow.protocol.yaml - FSM definition (if protocol detected)
    • +
  • .specfact/enforcement/config.yaml - Quality gates configuration
    • +
  • .semgrep/async-anti-patterns.yaml - Anti-pattern rules (if async patterns detected)
    • +
  • .github/workflows/specfact-gate.yml - CI workflow (optional)
    • +
+ +

4: Generate Constitution (If Missing)

+ +

Before syncing, ensure you have a valid constitution:

+ +
# Auto-generate from repository analysis (recommended for brownfield)
+specfact sdd constitution bootstrap --repo .
+
+# Validate completeness
+specfact sdd constitution validate
+
+# Or enrich existing minimal constitution
+specfact sdd constitution enrich --repo .
+
+ +

Note: The sync bridge --adapter speckit command will detect if the constitution is missing or minimal and suggest bootstrap automatically.

+ +

5. Enable Bidirectional Sync (Optional)

+ +

Keep Spec-Kit and SpecFact synchronized:

+ +
# One-time bidirectional sync
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
+
+# Continuous watch mode
+specfact sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch --interval 5
+
+ +

What it syncs:

+ +
    +
  • specs/[###-feature-name]/spec.md, plan.md, tasks.md ↔ .specfact/projects/<bundle-name>/ aspect files
    • +
  • .specify/memory/constitution.md ↔ SpecFact business context
    • +
  • specs/[###-feature-name]/research.md, data-model.md, quickstart.md ↔ SpecFact supporting artifacts
    • +
  • specs/[###-feature-name]/contracts/*.yaml ↔ SpecFact protocol definitions
    • +
  • Automatic conflict resolution with priority rules
    • +
+ +

6. Enable Enforcement

+ +
# Start in shadow mode (observe only)
+specfact enforce stage --preset minimal
+
+# After stabilization, enable warnings
+specfact enforce stage --preset balanced
+
+# For production, enable strict mode
+specfact enforce stage --preset strict
+
+ +

7. Validate

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Run validation
+specfact repro --verbose
+
+ +

Expected Timeline (Spec-Kit Migration)

+ +
    +
  • Preview: < 1 minute
    • +
  • Migration: 2-5 minutes
    • +
  • Review: 15-30 minutes
    • +
  • Stabilization: 1-2 weeks (shadow mode)
    • +
  • Production: After validation passes
    • +
+ +
+ +

Use Case 3: Greenfield Spec-First Development (Alternative)

+ +

Problem: Starting a new project, want contract-driven development from day 1.

+ +

Solution: Use SpecFact CLI for spec-first planning and strict enforcement.

+ +

Steps (Greenfield Development)

+ +

1. Create Plan Interactively

+ +
# Standard interactive mode
+specfact plan init --interactive
+
+# CoPilot mode (enhanced prompts)
+specfact --mode copilot plan init --interactive
+
+ +

With CoPilot (IDE Integration):

+ +
# Use slash command in IDE chat (after specfact init)
+/specfact.02-plan init legacy-api
+# Or update idea: /specfact.02-plan update-idea --bundle legacy-api --title "My Project"
+
+ +

Interactive prompts:

+ +
🎯 SpecFact CLI - Plan Initialization
+
+What's your idea title?
+> Real-time collaboration platform
+
+What's the narrative? (high-level vision)
+> Enable teams to collaborate in real-time with contract-driven quality
+
+What are the product themes? (comma-separated)
+> Developer Experience, Real-time Sync, Quality Assurance
+
+What's the first release name?
+> v0.1
+
+What are the release objectives? (comma-separated)
+> WebSocket server, Client SDK, Basic presence
+
+✅ Plan initialized: .specfact/projects/<bundle-name>/
+
+ +

2. Add Features and Stories

+ +
# Add feature
+specfact plan add-feature \
+  --key FEATURE-001 \
+  --title "WebSocket Server" \
+  --outcomes "Handle 1000 concurrent connections" \
+  --outcomes "< 100ms message latency" \
+  --acceptance "Given client connection, When message sent, Then delivered within 100ms"
+
+# Add story
+specfact plan add-story \
+  --feature FEATURE-001 \
+  --key STORY-001 \
+  --title "Connection handling" \
+  --acceptance "Accept WebSocket connections" \
+  --acceptance "Maintain heartbeat every 30s" \
+  --acceptance "Graceful disconnect cleanup"
+
+ +

3. Define Protocol

+ +

Create contracts/protocols/workflow.protocol.yaml:

+ +
states:
+  - DISCONNECTED
+  - CONNECTING
+  - CONNECTED
+  - RECONNECTING
+  - DISCONNECTING
+
+start: DISCONNECTED
+
+transitions:
+  - from_state: DISCONNECTED
+    on_event: connect
+    to_state: CONNECTING
+
+  - from_state: CONNECTING
+    on_event: connection_established
+    to_state: CONNECTED
+    guard: handshake_valid
+
+  - from_state: CONNECTED
+    on_event: connection_lost
+    to_state: RECONNECTING
+    guard: should_reconnect
+
+  - from_state: RECONNECTING
+    on_event: reconnect_success
+    to_state: CONNECTED
+
+  - from_state: CONNECTED
+    on_event: disconnect
+    to_state: DISCONNECTING
+
+ +

4. Enable Strict Enforcement

+ +
specfact enforce stage --preset strict
+
+ +

5. Validate Continuously

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# During development
+specfact repro
+
+# In CI/CD
+specfact repro --budget 120 --verbose
+
+ +

Expected Timeline (Greenfield Development)

+ +
    +
  • Planning: 1-2 hours
    • +
  • Protocol design: 30 minutes
    • +
  • Implementation: Per feature/story
    • +
  • Validation: Continuous (< 90s per check)
    • +
+ +
+ +

Use Case 4: CI/CD Integration

+ +

Problem: Need automated quality gates in pull requests.

+ +

Solution: Add SpecFact GitHub Action to PR workflow.

+ +

Terminal Output: The CLI automatically detects CI/CD environments and uses plain text output (no colors, no animations) for better log readability. Progress updates are visible in CI/CD logs. See Troubleshooting for details.

+ +

Steps (CI/CD Integration)

+ +

1. Add GitHub Action

+ +

Create .github/workflows/specfact.yml:

+ +
name: SpecFact CLI Validation
+
+on:
+  pull_request:
+    branches: [main, dev]
+  push:
+    branches: [main, dev]
+  workflow_dispatch:
+    inputs:
+      budget:
+        description: "Time budget in seconds"
+        required: false
+        default: "90"
+        type: string
+
+jobs:
+  specfact-validation:
+    name: Contract Validation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      checks: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install SpecFact CLI
+        run: pip install specfact-cli
+
+      - name: Set up CrossHair Configuration
+        run: specfact repro setup
+
+      - name: Run Contract Validation
+        run: specfact repro --verbose --budget 90
+
+      - name: Generate PR Comment
+        if: github.event_name == 'pull_request'
+        run: python -m specfact_cli.utils.github_annotations
+        env:
+          SPECFACT_REPORT_PATH: .specfact/projects/<bundle-name>/reports/enforcement/report-*.yaml
+
+ +

Features:

+ +
    +
  • ✅ PR annotations for violations
    • +
  • ✅ PR comments with violation summaries
    • +
  • ✅ Auto-fix suggestions in PR comments
    • +
  • ✅ Budget-based blocking
    • +
  • ✅ Manual workflow dispatch support
    • +
+ +

2. Configure Enforcement

+ +

Create .specfact.yaml:

+ +
version: "1.0"
+
+enforcement:
+  preset: balanced  # Block HIGH, warn MEDIUM
+
+repro:
+  budget: 120
+  parallel: true
+  fail_fast: false
+
+analysis:
+  confidence_threshold: 0.7
+  exclude_patterns:
+    - "**/__pycache__/**"
+    - "**/node_modules/**"
+
+ +

3. Test Locally

+ +
# Before pushing
+specfact repro --verbose
+
+# Apply auto-fixes for violations
+specfact repro --fix --verbose
+
+# If issues found
+specfact enforce stage --preset minimal  # Temporarily allow
+# Fix issues
+specfact enforce stage --preset balanced  # Re-enable
+
+ +

4. Monitor PR Checks

+ +

The GitHub Action will:

+ +
    +
  • Run contract validation
    • +
  • Check for async anti-patterns
    • +
  • Validate state machine transitions
    • +
  • Generate deviation reports
    • +
  • Block PR if HIGH severity issues found
    • +
+ +

Expected Results

+ +
    +
  • Clean PRs: Pass in < 90s
    • +
  • Blocked PRs: Clear deviation report
    • +
  • False positives: < 5% (use override mechanism)
    • +
+ +
+ +

Use Case 5: Multi-Repository Consistency

+ +

Problem: Multiple microservices need consistent contract enforcement.

+ +

Solution: Share common plan bundle and enforcement config.

+ +

Steps (Multi-Repository)

+ +

1. Create Shared Plan Bundle

+ +

In a shared repository:

+ +
# Create shared plan
+specfact plan init --interactive
+
+# Add common features
+specfact plan add-feature \
+  --key FEATURE-COMMON-001 \
+  --title "API Standards" \
+  --outcomes "Consistent REST patterns" \
+  --outcomes "Standardized error responses"
+
+ +

2. Distribute to Services

+ +
# In each microservice
+git submodule add https://github.com/org/shared-contracts contracts/shared
+
+# Or copy files
+cp ../shared-contracts/plan.bundle.yaml contracts/shared/
+
+ +

3. Validate Against Shared Plan

+ +
# In each service
+specfact plan compare \
+  --manual contracts/shared/plan.bundle.yaml \
+  --auto contracts/service/plan.bundle.yaml \
+  --output-format markdown
+
+ +

4. Enforce Consistency

+ +
# First-time setup: Configure CrossHair for contract exploration
+specfact repro setup
+
+# Add to CI
+specfact repro
+specfact plan compare --manual contracts/shared/plan.bundle.yaml --auto .
+
+ +

Expected Benefits

+ +
    +
  • Consistency: All services follow same patterns
    • +
  • Reusability: Shared contracts and protocols
    • +
  • Maintainability: Update once, apply everywhere
    • +
+ +
+ +

See Commands for detailed command reference and Getting Started for quick setup.

+ +

Integration Examples

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/_site_test/ux-features/index.html b/_site_test/ux-features/index.html new file mode 100644 index 0000000..e99e6e9 --- /dev/null +++ b/_site_test/ux-features/index.html @@ -0,0 +1,552 @@ + + + + + + + +UX Features Guide | SpecFact CLI Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+

UX Features Guide

+ +

This guide covers the user experience features that make SpecFact CLI intuitive and efficient.

+ +

Progressive Disclosure

+ +

SpecFact CLI uses progressive disclosure to show the most important options first, while keeping advanced options accessible when needed. This reduces cognitive load for new users while maintaining full functionality for power users.

+ +

Regular Help

+ +

By default, --help shows only the most commonly used options:

+ +
specfact import from-code --help
+
+ +

This displays:

+ +
    +
  • Required arguments
    • +
  • Common options (bundle, repo, output)
    • +
  • Behavior flags (interactive, verbose, dry-run, force)
    • +
  • Essential workflow options
    • +
+ +

Advanced Help

+ +

To see all options including advanced configuration, use --help-advanced (alias: -ha):

+ +
specfact import from-code --help-advanced
+
+ +

This reveals:

+ +
    +
  • Advanced configuration options: Confidence thresholds, key formats, adapter types
    • +
  • Fine-tuning parameters: Watch intervals, time budgets, session limits
    • +
  • Expert-level settings: Taxonomy filtering, content hash matching, backward compatibility checks
    • +
  • CI/CD automation options: Non-interactive JSON inputs, exact name matching
    • +
+ +

Hidden Options Summary

+ +

The following options are hidden by default across commands:

+ +

Import Commands:

+ +
    +
  • --entry-point - Partial analysis (subdirectory only)
    • +
  • --enrichment - LLM enrichment workflow
    • +
  • --adapter - Adapter type configuration (auto-detected)
    • +
  • --confidence - Feature detection threshold
    • +
  • --key-format - Feature key format (classname vs sequential)
    • +
+ +

Sync Commands:

+ +
    +
  • --adapter - Adapter type configuration (auto-detected)
    • +
  • --interval - Watch mode interval tuning
    • +
  • --confidence - Feature detection threshold
    • +
+ +

Plan Commands:

+ +
    +
  • --max-questions - Review session limit
    • +
  • --category - Taxonomy category filtering
    • +
  • --findings-format - Output format for findings
    • +
  • --answers - Non-interactive JSON input
    • +
  • --stages - Filter by promotion stages
    • +
  • --last - Show last N plans
    • +
  • --current - Show only active plan
    • +
  • --name - Exact bundle name matching
    • +
  • --id - Content hash ID matching
    • +
+ +

Spec Commands:

+ +
    +
  • --previous - Backward compatibility check
    • +
+ +

Other Commands:

+ +
    +
  • repro --budget - Time budget configuration
    • +
  • generate contracts-prompt --output - Custom output path
    • +
  • init --ide - IDE selection override (auto-detection works)
    • +
+ +

Tip: Advanced options are still functional even when hidden - you can use them directly without --help-advanced/-ha. The flag only affects what’s shown in help text.

+ +

Example:

+ +
# This works even though --confidence is hidden in regular help:
+specfact import from-code my-bundle --confidence 0.7 --key-format sequential
+
+# To see all options in help:
+specfact import from-code --help-advanced  # or -ha
+
+ +

Context Detection

+ +

SpecFact CLI automatically detects your project context to provide smart defaults and suggestions.

+ +

Auto-Detection

+ +

When you run commands, SpecFact automatically detects:

+ +
    +
  • Project Type: Python, JavaScript, etc.
    • +
  • Framework: FastAPI, Django, Flask, etc.
    • +
  • Existing Specs: OpenAPI/AsyncAPI specifications
    • +
  • Plan Bundles: Existing SpecFact project bundles
    • +
  • Configuration: Specmatic configuration files
    • +
+ +

Smart Defaults

+ +

Based on detected context, SpecFact provides intelligent defaults:

+ +
# If OpenAPI spec detected, suggests validation
+specfact spec validate --bundle <auto-detected>
+
+# If low contract coverage detected, suggests analysis
+specfact analyze --bundle <auto-detected>
+
+ +

Explicit Context

+ +

You can also explicitly check your project context:

+ +
# Context detection is automatic, but you can verify
+specfact import from-code --bundle my-bundle --repo .
+# CLI automatically detects Python, FastAPI, existing specs, etc.
+
+ +

Intelligent Suggestions

+ +

SpecFact provides context-aware suggestions to guide your workflow.

+ +

Next Steps

+ +

After running commands, SpecFact suggests logical next steps:

+ +
$ specfact import from-code --bundle legacy-api
+✓ Import complete
+
+💡 Suggested next steps:
+  • specfact analyze --bundle legacy-api  # Analyze contract coverage
+  • specfact enforce sdd --bundle legacy-api  # Enforce quality gates
+  • specfact sync intelligent --bundle legacy-api  # Sync code and specs
+
+ +

Error Fixes

+ +

When errors occur, SpecFact suggests specific fixes:

+ +
$ specfact analyze --bundle missing-bundle
+✗ Error: Bundle 'missing-bundle' not found
+
+💡 Suggested fixes:
+  • specfact plan select  # Select an active plan bundle
+  • specfact import from-code --bundle missing-bundle  # Create a new bundle
+
+ +

Improvements

+ +

Based on analysis, SpecFact suggests improvements:

+ +
$ specfact analyze --bundle legacy-api
+⚠ Low contract coverage detected (30%)
+
+💡 Suggested improvements:
+  • specfact analyze --bundle legacy-api  # Identify missing contracts
+  • specfact import from-code --bundle legacy-api  # Extract contracts from code
+
+ +

Template-Driven Quality

+ +

SpecFact uses templates to ensure high-quality, consistent specifications.

+ +

Feature Specification Templates

+ +

When creating features, templates guide you to focus on:

+ +
    +
  • WHAT users need (not HOW to implement)
    • +
  • WHY the feature is valuable
    • +
  • Uncertainty markers for ambiguous requirements: [NEEDS CLARIFICATION: specific question]
    • +
  • Completeness checklists to ensure nothing is missed
    • +
+ +

Implementation Plan Templates

+ +

Implementation plans follow templates that:

+ +
    +
  • Keep high-level steps readable
    • +
  • Extract detailed algorithms to separate files
    • +
  • Enforce test-first thinking (contracts → tests → implementation)
    • +
  • Include phase gates for architectural principles
    • +
+ +

Contract Extraction Templates

+ +

Contract extraction uses templates to:

+ +
    +
  • Extract contracts from legacy code patterns
    • +
  • Identify validation logic
    • +
  • Map to formal contracts (icontract, beartype)
    • +
  • Mark uncertainties for later clarification
    • +
+ +

Enhanced Watch Mode

+ +

Watch mode has been enhanced with intelligent change detection.

+ +

Hash-Based Detection

+ +

Watch mode only processes files that actually changed:

+ +
specfact sync intelligent --bundle my-bundle --watch
+
+ +

Features:

+ +
    +
  • SHA256 hash-based change detection
    • +
  • Only processes files with actual content changes
    • +
  • Skips unchanged files (even if modified timestamp changed)
    • +
  • Faster sync operations
    • +
+ +

Dependency Tracking

+ +

Watch mode tracks file dependencies:

+ +
    +
  • Identifies dependent files
    • +
  • Processes dependencies when source files change
    • +
  • Incremental processing (only changed files and dependencies)
    • +
+ +

Cache Optimization

+ +

Watch mode uses an optimized cache:

+ +
    +
  • LZ4 compression (when available) for faster I/O
    • +
  • Persistent cache across sessions
    • +
  • Automatic cache management
    • +
+ +

Unified Progress Display

+ +

All commands use consistent progress indicators that automatically adapt to your terminal environment.

+ +

Progress Format

+ +

Progress displays use a consistent n/m format:

+ +
Loading artifact 3/12: FEATURE-001.yaml
+
+ +

This shows:

+ +
    +
  • Current item number (3)
    • +
  • Total items (12)
    • +
  • Current artifact name (FEATURE-001.yaml)
    • +
  • Elapsed time
    • +
+ +

Automatic Terminal Adaptation

+ +

The CLI automatically detects terminal capabilities and adjusts progress display:

+ +
    +
  • Interactive terminals → Full Rich progress with animations, colors, and progress bars
    • +
  • Embedded terminals (Cursor, VS Code) → Plain text progress updates (no animations)
    • +
  • CI/CD pipelines → Plain text progress updates for readable logs
    • +
  • Test mode → Minimal output
    • +
+ +

No manual configuration required - the CLI adapts automatically. See Troubleshooting for details.

+ +

Visibility

+ +

Progress is shown for:

+ +
    +
  • All bundle load/save operations
    • +
  • Long-running operations (>1 second)
    • +
  • File processing operations
    • +
  • Analysis operations
    • +
+ +

No “dark” periods - you always know what’s happening, regardless of terminal type.

+ +

Best Practices

+ +

Using Progressive Disclosure

+ +
    +
  1. Start with regular help - Most users only need common options
    2. +
  2. Use --help-advanced (-ha) when you need fine-grained control
    3. +
  3. Advanced options work without help - You can use them directly
    4. +
+ +

Leveraging Context Detection

+ +
    +
  1. Let SpecFact auto-detect - It’s usually correct
    2. +
  2. Verify context - Check suggestions match your project
    3. +
  3. Use explicit flags - Override auto-detection when needed
    4. +
+ +

Following Suggestions

+ +
    +
  1. Read suggestions carefully - They’re context-aware
    2. +
  2. Follow the workflow - Suggestions guide logical next steps
    3. +
  3. Use error suggestions - They provide specific fixes
    4. +
+ +

Using Templates

+ +
    +
  1. Follow template structure - Ensures quality and consistency
    2. +
  2. Mark uncertainties - Use [NEEDS CLARIFICATION] markers
    3. +
  3. Complete checklists - Templates include completeness checks
    4. +
+ +
+ +

Related Documentation:

+ + + +
+
+
+ +
+ +
+
+
+

SpecFact CLI Documentation

+

Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.

+
+
+

© 2025 Nold AI (Owner: Dominikus Nold)

+
+
+
+
+ + + + diff --git a/docs/LICENSE.md b/docs/LICENSE.md new file mode 100644 index 0000000..dd8dba5 --- /dev/null +++ b/docs/LICENSE.md @@ -0,0 +1,202 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (which shall not include Communications that are clearly marked or + otherwise designated in writing by the copyright owner as "Not a Work"). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is clearly marked or otherwise designated + in writing by the copyright owner as "Not a Contribution". + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2025 Nold AI (Owner: Dominikus Nold) + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/docs/TRADEMARKS.md b/docs/TRADEMARKS.md new file mode 100644 index 0000000..03d6262 --- /dev/null +++ b/docs/TRADEMARKS.md @@ -0,0 +1,58 @@ +# Trademarks + +## NOLD AI Trademark + +**NOLD AI** (also referred to as **NOLDAI**) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). + +All rights to the NOLD AI trademark are reserved. + +## Third-Party Trademarks + +This project may reference or use trademarks, service marks, and trade names of other companies and organizations. These trademarks are the property of their respective owners. + +### AI and IDE Tools + +- **Claude** and **Claude Code** are trademarks of Anthropic PBC +- **Gemini** is a trademark of Google LLC +- **Cursor** is a trademark of Anysphere, Inc. +- **GitHub Copilot** is a trademark of GitHub, Inc. (Microsoft Corporation) +- **VS Code** (Visual Studio Code) is a trademark of Microsoft Corporation +- **Windsurf** is a trademark of Codeium, Inc. +- **Qwen Code** is a trademark of Alibaba Group +- **opencode** is a trademark of its respective owner +- **Codex CLI** is a trademark of OpenAI, L.P. +- **Amazon Q Developer** is a trademark of Amazon.com, Inc. +- **Amp** is a trademark of its respective owner +- **CodeBuddy CLI** is a trademark of its respective owner +- **Kilo Code** is a trademark of its respective owner +- **Auggie CLI** is a trademark of its respective owner +- **Roo Code** is a trademark of its respective owner + +### Development Tools and Platforms + +- **GitHub** is a trademark of GitHub, Inc. (Microsoft Corporation) +- **Spec-Kit** is a trademark of its respective owner +- **Python** is a trademark of the Python Software Foundation +- **Semgrep** is a trademark of Semgrep, Inc. +- **PyPI** (Python Package Index) is a trademark of the Python Software Foundation + +### Standards and Protocols + +- **OpenAPI** is a trademark of The Linux Foundation +- **JSON Schema** is a trademark of its respective owner + +## Trademark Usage + +When referencing trademarks in this project: + +1. **Always use proper capitalization** as shown above +2. **Include trademark notices** where trademarks are prominently displayed +3. **Respect trademark rights** - do not use trademarks in a way that suggests endorsement or affiliation without permission + +## Disclaimer + +The mention of third-party trademarks in this project does not imply endorsement, sponsorship, or affiliation with the trademark owners. All product names, logos, and brands are property of their respective owners. + +--- + +**Last Updated**: 2025-11-05 diff --git a/docs/examples/quick-examples.md b/docs/examples/quick-examples.md index 7043ac2..aaa9699 100644 --- a/docs/examples/quick-examples.md +++ b/docs/examples/quick-examples.md @@ -66,6 +66,20 @@ specfact import from-code my-project --repo . --shadow-only # CoPilot mode (enhanced prompts) specfact --mode copilot import from-code my-project --repo . --confidence 0.7 +# Re-validate existing features (force re-analysis) +specfact import from-code my-project --repo . --revalidate-features + +# Resume interrupted import (features saved early as checkpoint) +# If import is cancelled, just run the same command again +specfact import from-code my-project --repo . + +# Partial analysis (analyze specific subdirectory only) +specfact import from-code my-project --repo . --entry-point src/core + +# Large codebase with progress reporting +# Progress bars show: feature analysis, source linking, contract extraction +specfact import from-code large-project --repo . --confidence 0.5 + ``` ## Plan Management diff --git a/docs/guides/import-features.md b/docs/guides/import-features.md new file mode 100644 index 0000000..d7a06f2 --- /dev/null +++ b/docs/guides/import-features.md @@ -0,0 +1,246 @@ +--- +layout: default +title: Import Command Features +permalink: /guides/import-features/ +--- + +# Import Command Features + +This guide covers advanced features and optimizations in the `import from-code` command. + +## Overview + +The `import from-code` command has been optimized for large codebases and includes several features to improve reliability, performance, and user experience: + +- **Progress Reporting**: Real-time progress bars for long-running operations +- **Feature Validation**: Automatic validation of existing features when resuming imports +- **Early Save Checkpoint**: Features saved immediately after analysis to prevent data loss +- **Performance Optimizations**: Pre-computed caches for 5-15x faster processing +- **Re-validation Flag**: Force re-analysis of features even if files haven't changed + +--- + +## Progress Reporting + +The import command now provides detailed progress reporting for all major operations: + +### Feature Analysis Progress + +During the initial codebase analysis, you'll see: + +``` +🔍 Analyzing codebase... +✓ Found 3156 features +✓ Detected themes: API, Async, Database, ORM, Testing +✓ Total stories: 5604 +``` + +### Source File Linking Progress + +When linking source files to features, a progress bar shows: + +``` +Linking 3156 features to source files... +[████████████████████] 100% (3156/3156 features) +``` + +This is especially useful for large codebases where linking can take several minutes. + +### Contract Extraction Progress + +During OpenAPI contract extraction, progress is shown for each feature being processed. + +--- + +## Feature Validation + +When you restart an import on an existing bundle, the command automatically validates existing features: + +### Automatic Validation + +```bash +# First import +specfact import from-code my-project --repo . + +# Later, restart import (validates existing features automatically) +specfact import from-code my-project --repo . +``` + +### Validation Results + +The command reports validation results: + +``` +🔍 Validating existing features... +✓ All 3156 features validated successfully (source files exist) +``` + +Or if issues are found: + +``` +⚠ Feature validation found issues: 3100/3156 valid, 45 orphaned, 11 invalid + Orphaned features (all source files missing): + - FEATURE-1234 (3 missing files) + - FEATURE-5678 (2 missing files) + ... + Invalid features (some files missing or structure issues): + - FEATURE-9012 (1 missing file) + ... + Tip: Use --revalidate-features to re-analyze features and fix issues +``` + +### What Gets Validated + +- **Source file existence**: Checks that all referenced implementation and test files still exist +- **Feature structure**: Validates that features have required fields (key, title, stories) +- **Orphaned features**: Detects features whose source files have been deleted +- **Invalid features**: Identifies features with missing files or structural issues + +--- + +## Early Save Checkpoint + +Features are saved immediately after the initial codebase analysis, before expensive operations like source tracking and contract extraction. + +### Benefits + +- **Resume capability**: If the import is interrupted, you can restart without losing the initial analysis +- **Data safety**: Features are persisted early, reducing risk of data loss +- **Faster recovery**: No need to re-run the full codebase scan if interrupted + +### Example + +```bash +# Start import +specfact import from-code my-project --repo . + +# Output shows: +# ✓ Found 3156 features +# 💾 Saving features (checkpoint)... +# ✓ Features saved (can resume if interrupted) + +# If you press Ctrl+C during source linking, you can restart: +specfact import from-code my-project --repo . +# The command will detect existing features and resume from checkpoint +``` + +--- + +## Performance Optimizations + +The import command has been optimized for large codebases (3000+ features): + +### Pre-computed Caches + +- **AST Parsing**: All files are parsed once before parallel processing +- **File Hashes**: All file hashes are computed once and cached +- **Function Mappings**: Function names are extracted once per file + +### Performance Improvements + +- **Before**: ~34 features/minute (515/3156 in 15 minutes) +- **After**: 200-500+ features/minute (5-15x faster) +- **Large codebases**: 3000+ features processed in 6-15 minutes (down from 90+ minutes) + +### How It Works + +1. **Pre-computation phase**: Single pass through all files to build caches +2. **Parallel processing**: Uses cached results (no file I/O or AST parsing) +3. **Thread-safe**: Read-only caches during parallel execution + +--- + +## Re-validation Flag + +Use `--revalidate-features` to force re-analysis even if source files haven't changed. + +### When to Use + +- **Analysis improvements**: When the analysis logic has been improved +- **Confidence changes**: When you want to re-evaluate features with a different confidence threshold +- **File changes outside repo**: When files were moved or renamed outside the repository +- **Validation issues**: When validation reports orphaned or invalid features + +### Example + +```bash +# Re-analyze all features even if files unchanged +specfact import from-code my-project --repo . --revalidate-features + +# Output shows: +# ⚠ --revalidate-features enabled: Will re-analyze features even if files unchanged +``` + +### What Happens + +- Forces full codebase analysis regardless of incremental change detection +- Re-computes all feature mappings and source tracking +- Updates feature confidence scores based on current analysis logic +- Regenerates all contracts and relationships + +--- + +## Best Practices + +### Large Codebases + +For codebases with 1000+ features: + +1. **Use partial analysis**: Start with `--entry-point` to analyze one module at a time +2. **Monitor progress**: Watch the progress bars to estimate completion time +3. **Use checkpoints**: Let the early save checkpoint work for you - don't worry about interruptions +4. **Re-validate periodically**: Use `--revalidate-features` after major code changes + +### Resuming Interrupted Imports + +1. **Don't delete the bundle**: The checkpoint is stored in the bundle directory +2. **Run the same command**: Just re-run the import command - it will detect existing features +3. **Check validation**: Review validation results to see if any features need attention +4. **Use re-validation if needed**: If validation shows issues, use `--revalidate-features` + +### Performance Tips + +1. **Exclude tests if not needed**: Use `--exclude-tests` for faster processing (if test analysis isn't critical) +2. **Use entry points**: For monorepos, analyze one project at a time with `--entry-point` +3. **Adjust confidence**: Lower confidence (0.3-0.5) for faster analysis, higher (0.7-0.9) for more accurate results + +--- + +## Troubleshooting + +### Slow Linking + +If source file linking is slow: + +- **Check file count**: Large numbers of files (10,000+) will take longer +- **Monitor progress**: The progress bar shows current status +- **Use entry points**: Limit scope with `--entry-point` for faster processing + +### Validation Issues + +If validation reports many orphaned features: + +- **Check file paths**: Ensure source files haven't been moved +- **Use re-validation**: Run with `--revalidate-features` to fix mappings +- **Review feature keys**: Some features may need manual adjustment + +### Interrupted Imports + +If import is interrupted: + +- **Don't delete bundle**: The checkpoint is in `.specfact/projects//` +- **Restart command**: Run the same import command - it will resume +- **Check progress**: Validation will show what was completed + +--- + +## Related Documentation + +- [Command Reference](../reference/commands.md#import-from-code) - Complete command documentation +- [Quick Examples](../examples/quick-examples.md) - Quick command examples +- [Brownfield Engineer Guide](brownfield-engineer.md) - Complete brownfield workflow +- [Common Tasks](common-tasks.md) - Common import scenarios + +--- + +**Happy importing!** 🚀 diff --git a/docs/reference/commands.md b/docs/reference/commands.md index bc2b279..22fddb3 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -323,6 +323,11 @@ specfact import from-code [OPTIONS] - Existing features are updated (confidence, outcomes, title if empty) - Stories are merged into existing features (new stories added, existing preserved) - Business context is applied to the plan bundle +- `--revalidate-features/--no-revalidate-features` - Re-validate and re-analyze existing features even if source files haven't changed. Useful when: + - Analysis logic has improved and you want to re-analyze with better algorithms + - Confidence threshold has changed and you want to re-evaluate features + - Source files were modified outside the repository (e.g., moved, renamed) + - Default: `False` (only re-analyze if files changed). When enabled, forces full codebase analysis regardless of incremental change detection **Note**: The bundle name (positional argument) will be automatically sanitized (lowercased, spaces/special chars removed) for filesystem persistence. The bundle is created at `.specfact/projects//`. @@ -363,6 +368,15 @@ specfact import from-code --bundle core-module \ specfact import from-code --bundle api-service \ --repo ./monorepo \ --entry-point projects/api-service + +# Re-validate existing features (force re-analysis even if files unchanged) +specfact import from-code --bundle legacy-api \ + --repo ./my-project \ + --revalidate-features + +# Resume interrupted import (features are saved early as checkpoint) +# If import is cancelled, restart with same command - it will resume from checkpoint +specfact import from-code --bundle legacy-api --repo ./my-project ``` **What it does:** @@ -379,6 +393,19 @@ specfact import from-code --bundle api-service \ - **Optimized Bundle Size**: 81% reduction (18MB → 3.4MB, 5.3x smaller) via test pattern extraction to OpenAPI contracts - **Acceptance Criteria**: Limited to 1-3 high-level items per story, detailed examples in contract files - **Interruptible**: Press Ctrl+C during analysis to cancel immediately (all parallel operations support graceful cancellation) +- **Progress Reporting**: Real-time progress bars show: + - Feature analysis progress (features discovered, themes detected) + - Source file linking progress (features linked to source files) + - Contract extraction progress (OpenAPI contracts generated) +- **Performance Optimizations**: + - Pre-computes AST parsing and file hashes (5-15x faster for large codebases) + - Caches function mappings to avoid repeated file parsing + - Optimized for repositories with thousands of features (e.g., SQLAlchemy with 3000+ features) +- **Early Save Checkpoint**: Features are saved immediately after initial analysis, allowing you to resume if the process is interrupted during expensive operations (source tracking, contract extraction) +- **Feature Validation**: When loading existing bundles, automatically validates: + - Source files still exist (detects orphaned features) + - Feature structure is valid (detects incomplete features) + - Reports validation issues with actionable tips - **Contract Extraction**: Automatically extracts API contracts from function signatures, type hints, and validation logic: - Function parameters → Request schema (JSON Schema format) - Return types → Response schema @@ -2998,27 +3025,33 @@ specfact sync bridge --adapter openspec --mode read-only --bundle my-project --r ``` # Export OpenSpec change proposals to GitHub issues (auto-detect sanitization) + specfact sync bridge --adapter github --mode export-only # Export with explicit repository and sanitization + specfact sync bridge --adapter github --mode export-only \ --repo-owner owner --repo-name repo \ --sanitize \ --target-repo public-owner/public-repo # Export without sanitization (use full proposal content) + specfact sync bridge --adapter github --mode export-only \ --no-sanitize # Export using GitHub CLI for token (enterprise-friendly) + specfact sync bridge --adapter github --mode export-only \ --use-gh-cli # Export specific change proposals only + specfact sync bridge --adapter github --mode export-only \ --repo-owner owner --repo-name repo \ --change-ids add-feature-x,update-api \ --repo /path/to/openspec-repo + ``` **What it syncs (Spec-Kit adapter):** diff --git a/pyproject.toml b/pyproject.toml index b093027..73ece74 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "specfact-cli" -version = "0.22.1" +version = "0.23.0" description = "Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions." readme = "README.md" requires-python = ">=3.11" diff --git a/resources/templates/sidecar/STRUCTURE.md b/resources/templates/sidecar/STRUCTURE.md new file mode 100644 index 0000000..53c915f --- /dev/null +++ b/resources/templates/sidecar/STRUCTURE.md @@ -0,0 +1,70 @@ +# Sidecar Templates Directory Structure + +## Overview + +The sidecar templates are organized into common and framework-specific modules to support multiple frameworks (Django, FastAPI, DRF, etc.). + +## Directory Structure + +```bash +sidecar/ +├── __init__.py # Root package marker +├── common/ # Common modules used by all frameworks +│ ├── __init__.py +│ ├── populate_contracts.py # Orchestrates contract population +│ ├── generate_harness.py # Generates CrossHair harness files +│ ├── adapters.py # Framework adapters (Django, FastAPI, etc.) +│ ├── crosshair_plugin.py # CrossHair plugin +│ ├── run_sidecar.sh # Main sidecar execution script +│ ├── sidecar-init.sh # Sidecar initialization script +│ ├── requirements.txt # Python dependencies +│ ├── README.md # Documentation +│ ├── bindings.yaml.example # Example bindings file +│ └── harness_contracts.py.example # Example harness file (shows generated structure) +├── frameworks/ +│ ├── django/ # Django-specific modules +│ │ ├── __init__.py +│ │ ├── django_url_extractor.py # Extracts Django URL patterns +│ │ ├── django_form_extractor.py # Extracts Django form schemas +│ │ └── crosshair_django_wrapper.py # Django-aware CrossHair wrapper +│ ├── fastapi/ # FastAPI-specific modules +│ │ ├── __init__.py +│ │ └── fastapi_route_extractor.py # Extracts FastAPI routes and Pydantic models +│ └── drf/ # Django REST Framework-specific modules +│ ├── __init__.py +│ └── drf_serializer_extractor.py # Extracts DRF serializer schemas + +``` + +## Import Patterns + +### From Common Modules + +Common modules import framework-specific modules using: + +```python +from frameworks.django.django_url_extractor import extract_django_urls +from frameworks.fastapi.fastapi_route_extractor import extract_fastapi_routes +from frameworks.drf.drf_serializer_extractor import extract_serializer_schema +``` + +### From Framework Modules + +Framework modules are self-contained and don't import from other frameworks. + +## Adding New Framework Support + +To add support for a new framework: + +1. Create a new directory under `frameworks/` (e.g., `frameworks/flask/`) +2. Add framework-specific extractors (e.g., `flask_route_extractor.py`) +3. Update `common/populate_contracts.py` to import and use the new extractor +4. Update `common/adapters.py` to add framework-specific adapter if needed +5. Update `common/run_sidecar.sh` to detect and handle the new framework + +## File Organization Principles + +- **Common modules**: Shared logic used by all frameworks +- **Framework modules**: Framework-specific extraction and adapter logic +- **Separation of concerns**: Each framework module is independent +- **Extensibility**: Easy to add new frameworks without modifying existing code diff --git a/resources/templates/sidecar/bindings.yaml b/resources/templates/sidecar/bindings.yaml deleted file mode 100644 index 917abe8..0000000 --- a/resources/templates/sidecar/bindings.yaml +++ /dev/null @@ -1,26 +0,0 @@ -bindings: - # Map operationId or function_name to a real code function. - # function is module_path:function_name. - # call_style: dict|kwargs|args|none - # args: list of request keys when call_style=args - # adapters: call_method_with_factory, call_constructor_then_method, call_classmethod, - # call_with_context_manager, call_async, call_with_setup_teardown, - # call_with_request_transform, call_generator, call_from_registry, - # call_with_overrides, call_with_contextvars, call_with_session, - # call_with_callbacks, call_django_view - # - # - operation_id: create_item - # target: your_package.factory:ItemFactory - # method: create - # factory: - # args: ["$request.item_type"] - # call_style: kwargs - # - function_name: find_item_by_id - # adapter: call_method_with_factory - # target: your_package.repo:ItemRepository - # method: find_by_id - # factory: - # args: [] - # call_style: args - # args: - # - item_id diff --git a/resources/templates/sidecar/README.md b/resources/templates/sidecar/common/README.md similarity index 88% rename from resources/templates/sidecar/README.md rename to resources/templates/sidecar/common/README.md index 963ad57..139980e 100644 --- a/resources/templates/sidecar/README.md +++ b/resources/templates/sidecar/common/README.md @@ -133,11 +133,32 @@ And per-tool timeouts in seconds: - `TIMEOUT_SEMGREP`, `TIMEOUT_BASEDPYRIGHT`, `TIMEOUT_SPECMATIC`, `TIMEOUT_CROSSHAIR` +## Sidecar Workflow (Intended) + +The sidecar validation follows this workflow: + +1. **AI Enrichment** (BEFORE tests) ⚠️ **CRITICAL STEP**: + - AI analyzes code (routes, models, validation logic) + - AI adds reasoning/value to strengthen contracts: + - Extract Pydantic/Django form schemas + - Add validation rules (minLength, maxLength, pattern, etc.) + - Add required fields and type constraints + - Update OpenAPI contract schemas with enriched details +2. **Populate Contracts**: Framework-specific route extraction and contract population +3. **Generate Harness**: Create CrossHair harness from enriched contracts +4. **Execute Tests**: Run CrossHair, Specmatic with strong contracts + +**Current Status**: AI enrichment step is manual (Phase 2) but should be integrated into sidecar execution. + +**See**: [Sidecar Execution Guide](../../../specfact-cli-internal/docs/internal/brownfield-strategy/oss_validation/SIDECAR-EXECUTION-GUIDE.md) for detailed AI enrichment instructions. + ## Harness Generation The harness is auto-generated from OpenAPI contracts in: `/.specfact/projects//contracts/` +**Note**: Contracts should be **AI-enriched** before harness generation to ensure strong validation rules. + Generated outputs (in the sidecar workspace): - `harness_contracts.py` (CrossHair harness) diff --git a/resources/templates/sidecar/adapters.py b/resources/templates/sidecar/common/adapters.py similarity index 65% rename from resources/templates/sidecar/adapters.py rename to resources/templates/sidecar/common/adapters.py index 74b146c..ccf3b7d 100644 --- a/resources/templates/sidecar/adapters.py +++ b/resources/templates/sidecar/common/adapters.py @@ -10,7 +10,7 @@ import os import sys from collections.abc import Callable -from typing import Any, Protocol, cast, runtime_checkable +from typing import Annotated, Any, Protocol, cast, get_args, get_origin, runtime_checkable @runtime_checkable @@ -630,3 +630,297 @@ def call_django_view( "error": type(e).__name__, "message": str(e), } + + +def call_fastapi_route( + binding: dict[str, Any], + request: Any, + load_binding: Callable[[str], Callable[..., Any]], + call_target: Callable[[Callable[..., Any], str, Any, list[str]], Any], + resolve_value: Callable[[Any, Any], Any], +) -> Any: + """ + Convert dict request to FastAPI route function call. + + This adapter: + 1. Loads the FastAPI route function + 2. Extracts path parameters from the request dict + 3. Creates mock dependencies (SessionDep, CurrentUser, etc.) if needed + 4. Calls the FastAPI route function with proper parameters + 5. Returns the result (Pydantic model or dict) + """ + target_name = binding.get("target") or binding.get("function") + if not target_name: + raise ValueError("Binding missing target") + + # Ensure repo path is in sys.path for FastAPI imports + repo_path_str = os.environ.get("REPO_PATH") + if repo_path_str and repo_path_str not in sys.path: + sys.path.insert(0, repo_path_str) + + # Add backend directory to path for FastAPI apps + backend_path = os.path.join(repo_path_str, "backend") if repo_path_str else None + if backend_path and os.path.exists(backend_path) and backend_path not in sys.path: + sys.path.insert(0, backend_path) + + # Set minimal environment variables for Settings if not already set + # This allows routes to import even if .env file is missing + minimal_env = { + "PROJECT_NAME": "FastAPI App", + "POSTGRES_SERVER": "localhost", + "POSTGRES_USER": "test", + "POSTGRES_PASSWORD": "test", + "POSTGRES_DB": "test", + "FIRST_SUPERUSER": "admin@example.com", + "FIRST_SUPERUSER_PASSWORD": "changethis", + "ENVIRONMENT": "local", + } + for key, value in minimal_env.items(): + if key not in os.environ: + os.environ[key] = value + + # Handle CrossHair's symbolic types - convert to dict if needed + if not isinstance(request, dict): + # CrossHair may pass strings, ints, or other types + # Convert to dict format for processing + if isinstance(request, (str, int, float, bool)) or request is None: + request = {} + else: + # Try to convert to dict if possible + try: + request = dict(request) if hasattr(request, "items") else {} + except (TypeError, ValueError): + request = {} + + # Extract path parameters (e.g., id, email) + # Handle symbolic types in keys - convert to string safely + path_params = {} + query_params = {} + body_data = {} + + for k, v in request.items(): + # Convert key to string safely (handles symbolic types) + key_str = str(k) if not isinstance(k, str) else k + + # Check if key is a string before calling startswith + if isinstance(key_str, str): + if key_str.startswith("_path_"): + path_params[key_str.replace("_path_", "")] = v + elif key_str.startswith("_query_"): + query_params[key_str.replace("_query_", "")] = v + elif not key_str.startswith("_"): + body_data[key_str] = v + else: + # Non-string key - treat as body data + body_data[key_str] = v + + # Load the FastAPI route function + try: + route_func = load_binding(target_name) + except Exception as e: + raise ImportError(f"FastAPI adapter could not load route function {target_name}: {e}") from e + + # Get function signature to understand dependencies + sig = inspect.signature(route_func) + func_kwargs: dict[str, Any] = {} + + def _create_oauth2_form(form_data: dict[str, Any]) -> Any: + """Create OAuth2PasswordRequestForm instance from dict data.""" + try: + # OAuth2PasswordRequestForm expects username and password + # Create a simple mock class that behaves like the form + class MockOAuth2Form: + def __init__(self, username: str = "", password: str = ""): + self.username = username + self.password = password + self.scope = "" + self.client_id: str | None = None + self.client_secret: str | None = None + + username = form_data.get("username", form_data.get("email", "")) + password = form_data.get("password", "") + return MockOAuth2Form(username=str(username), password=str(password)) + except ImportError: + # FastAPI not available, create a simple mock + class SimpleForm: + def __init__(self, **kwargs): + for k, v in kwargs.items(): + setattr(self, k, v) + + return SimpleForm(**form_data) + + def _create_mock_session() -> Any: + """Create a mock database session for testing.""" + + # Create a simple mock session object + class MockSession: + def __init__(self): + self._data: dict[type, dict[Any, Any]] = {} + + def get(self, model: type, ident: Any) -> Any | None: + """Mock get method.""" + return self._data.get(model, {}).get(ident) + + def add(self, instance: Any) -> None: + """Mock add method.""" + model_type = type(instance) + if model_type not in self._data: + self._data[model_type] = {} + # Use id if available, otherwise use object itself + ident = getattr(instance, "id", instance) + self._data[model_type][ident] = instance + + def commit(self) -> None: + """Mock commit method.""" + + def rollback(self) -> None: + """Mock rollback method.""" + + def close(self) -> None: + """Mock close method.""" + + return MockSession() + + def _create_mock_user() -> Any: + """Create a mock user for authentication dependencies.""" + + # Create a simple mock user object + class MockUser: + def __init__(self): + self.id = 1 + self.email = "test@example.com" + self.is_active = True + self.is_superuser = False + self.hashed_password = "hashed_password" + self.full_name = "Test User" + + return MockUser() + + def _is_depends_annotation(annotation: Any) -> tuple[bool, Any]: + """Check if annotation is Annotated with Depends() and return the dependency type.""" + if get_origin(annotation) is Annotated: + args = get_args(annotation) + if len(args) >= 2: + # First arg is the type, second is Depends(...) + dep_type = args[0] + depends_arg = args[1] + # Check if second arg is Depends() + # Depends can be detected by checking the type name or if it has a dependency attribute + depends_type_name = ( + type(depends_arg).__name__ if hasattr(type(depends_arg), "__name__") else str(type(depends_arg)) + ) + if "Depends" in depends_type_name or hasattr(depends_arg, "dependency"): + return True, dep_type + return False, None + + def _get_parameter_type(param: inspect.Parameter) -> Any: + """Get the actual type from parameter annotation, handling Annotated.""" + if param.annotation == inspect.Parameter.empty: + return None + annotation = param.annotation + # If it's Annotated, get the first type argument + if get_origin(annotation) is Annotated: + args = get_args(annotation) + if args: + return args[0] + return annotation + + # Process function parameters + for param_name, param in sig.parameters.items(): + param_type = _get_parameter_type(param) + is_depends, _depends_type = ( + _is_depends_annotation(param.annotation) if param.annotation != inspect.Parameter.empty else (False, None) + ) + + # Path parameters (from URL path) + if param_name in path_params: + func_kwargs[param_name] = path_params[param_name] + # Query parameters + elif param_name in query_params: + func_kwargs[param_name] = query_params[param_name] + # OAuth2PasswordRequestForm with Depends() - check BEFORE body_data check + # This handles cases where body_data has username/password but param_name is form_data + elif is_depends and param_type is not None: + type_name = getattr(param_type, "__name__", str(param_type)) + # Check if it's OAuth2PasswordRequestForm + if "OAuth2PasswordRequestForm" in type_name or "OAuth2PasswordRequestForm" in str(param_type): + # Create OAuth2PasswordRequestForm from body_data + # Use entire body_data dict (contains username/password) + form_data_dict = body_data if body_data else {} + func_kwargs[param_name] = _create_oauth2_form(form_data_dict) + # Check if it's a database Session (SessionDep pattern) + elif "Session" in type_name or "SessionDep" in param_name.lower(): + func_kwargs[param_name] = _create_mock_session() + # Check if it's a User type (CurrentUser pattern) + elif "User" in type_name or "CurrentUser" in param_name: + func_kwargs[param_name] = _create_mock_user() + # For other Depends(), try to use body_data or create None + elif body_data: + func_kwargs[param_name] = body_data + else: + # Unknown Depends() - pass None and let function handle it + func_kwargs[param_name] = None + # Body data (for Pydantic models) - check AFTER Depends() checks + elif param_name in body_data: + func_kwargs[param_name] = body_data[param_name] + # Check parameter type directly (not Annotated) + elif param_type is not None: + type_name = getattr(param_type, "__name__", str(param_type)) + # OAuth2PasswordRequestForm (without Depends annotation check) + if "OAuth2PasswordRequestForm" in type_name: + form_data_dict = body_data if body_data else {} + func_kwargs[param_name] = _create_oauth2_form(form_data_dict) + # Session types + elif "Session" in type_name or param_name in ("session", "db", "SessionDep"): + func_kwargs[param_name] = _create_mock_session() + # User types + elif "User" in type_name or param_name in ("current_user", "CurrentUser", "user"): + func_kwargs[param_name] = _create_mock_user() + # Body data for Pydantic models + elif body_data and param_name not in func_kwargs: + func_kwargs[param_name] = body_data + # Special FastAPI dependencies (fallback for common names) + elif param_name in ("session", "db", "SessionDep"): + func_kwargs[param_name] = _create_mock_session() + elif param_name in ("current_user", "CurrentUser", "user"): + func_kwargs[param_name] = _create_mock_user() + elif param_name in ("skip", "limit"): + # Common pagination parameters + func_kwargs[param_name] = query_params.get( + param_name, param.default if param.default != inspect.Parameter.empty else 0 + ) + elif param.default != inspect.Parameter.empty: + # Use default value + func_kwargs[param_name] = param.default + # Skip parameters with no default and no value (let function handle it) + + # Call the FastAPI route function + try: + result = route_func(**func_kwargs) + + # Handle async functions + if asyncio.iscoroutine(result): + try: + loop = asyncio.get_running_loop() + except RuntimeError: + result = asyncio.run(result) + else: + if loop.is_running(): + raise RuntimeError("FastAPI async adapter cannot run inside a running event loop") + result = loop.run_until_complete(result) + + # Convert Pydantic models to dict for CrossHair + if hasattr(result, "model_dump"): + return result.model_dump() + if hasattr(result, "dict"): + return result.dict() + if hasattr(result, "__dict__"): + return result.__dict__ + + return result + except Exception as e: + # Return error info for CrossHair to analyze + return { + "error": type(e).__name__, + "message": str(e), + } diff --git a/resources/templates/sidecar/bindings.yaml.example b/resources/templates/sidecar/common/bindings.yaml.example similarity index 100% rename from resources/templates/sidecar/bindings.yaml.example rename to resources/templates/sidecar/common/bindings.yaml.example diff --git a/resources/templates/sidecar/crosshair_plugin.py b/resources/templates/sidecar/common/crosshair_plugin.py similarity index 100% rename from resources/templates/sidecar/crosshair_plugin.py rename to resources/templates/sidecar/common/crosshair_plugin.py diff --git a/resources/templates/sidecar/generate_harness.py b/resources/templates/sidecar/common/generate_harness.py similarity index 99% rename from resources/templates/sidecar/generate_harness.py rename to resources/templates/sidecar/common/generate_harness.py index e62c105..da1ebae 100644 --- a/resources/templates/sidecar/generate_harness.py +++ b/resources/templates/sidecar/common/generate_harness.py @@ -287,7 +287,7 @@ def _render_harness( lines.append("") lines.append("import importlib") lines.append("import os") - lines.append("import adapters as sidecar_adapters") + lines.append("from common import adapters as sidecar_adapters") lines.append("") lines.append("# Django initialization (if Django is available)") lines.append("_django_initialized = False") diff --git a/resources/templates/sidecar/harness_contracts.py b/resources/templates/sidecar/common/harness_contracts.py.example similarity index 100% rename from resources/templates/sidecar/harness_contracts.py rename to resources/templates/sidecar/common/harness_contracts.py.example diff --git a/resources/templates/sidecar/common/populate_contracts.py b/resources/templates/sidecar/common/populate_contracts.py new file mode 100644 index 0000000..827faf8 --- /dev/null +++ b/resources/templates/sidecar/common/populate_contracts.py @@ -0,0 +1,1013 @@ +#!/usr/bin/env python3 +# pyright: reportMissingImports=false, reportImplicitRelativeImport=false +""" +Populate OpenAPI contract stubs with Django URL patterns. + +Reads Django URL patterns and populates existing OpenAPI contract files. + +Note: This is a template file that gets copied to the sidecar workspace. +The imports work at runtime when the file is in the sidecar directory. +""" + +from __future__ import annotations + +import argparse +import copy +import sys +from pathlib import Path +from typing import TYPE_CHECKING, cast + +import yaml + + +# Type stubs for template file imports +# These are template files that get copied to sidecar workspace where imports work at runtime +if TYPE_CHECKING: + + def extract_django_urls(repo_path: Path, urls_file: Path | None = None) -> list[dict[str, object]]: ... + def extract_view_form_schema(repo_path: Path, view_module: str, view_function: str) -> dict[str, object] | None: ... + def extract_fastapi_routes(repo_path: Path, routes_dir: Path | None = None) -> list[dict[str, object]]: ... + def extract_serializer_schema( + repo_path: Path, serializer_module: str, serializer_class: str + ) -> dict[str, object]: ... + + +# Import from framework-specific modules +# These scripts are run directly, so we need to handle imports differently +# Add parent directory to path for framework imports when run as script +_script_dir = Path(__file__).parent +_parent_dir = _script_dir.parent +if str(_parent_dir) not in sys.path: + sys.path.insert(0, str(_parent_dir)) + +# These imports work at runtime when scripts are run directly from sidecar directory +# Type checker uses TYPE_CHECKING stubs above; runtime uses actual imports below +# The sidecar directory has __init__.py, making it a package, so relative imports work at runtime +try: + # Try explicit relative imports first (preferred for type checking) + # These work when the sidecar directory is a proper package (has __init__.py) + from frameworks.django.django_form_extractor import ( # type: ignore[reportMissingImports] + extract_view_form_schema, + ) + from frameworks.django.django_url_extractor import extract_django_urls # type: ignore[reportMissingImports] + from frameworks.drf.drf_serializer_extractor import extract_serializer_schema # type: ignore[reportMissingImports] + from frameworks.fastapi.fastapi_route_extractor import extract_fastapi_routes # type: ignore[reportMissingImports] +except ImportError: + # Fallback for when run as script (runtime path manipulation case) + # This happens when the script is executed directly from the sidecar workspace + # and sys.path manipulation makes absolute imports work + from frameworks.django.django_form_extractor import ( # type: ignore[reportMissingImports] + extract_view_form_schema, + ) + from frameworks.django.django_url_extractor import ( + extract_django_urls, # type: ignore[reportImplicitRelativeImport, reportMissingImports] + ) + + try: + from frameworks.fastapi.fastapi_route_extractor import ( + extract_fastapi_routes, # type: ignore[reportMissingImports] + ) + except ImportError: + # FastAPI extractor not available + def extract_fastapi_routes(repo_path: Path, routes_dir: Path | None = None) -> list[dict[str, object]]: # type: ignore[misc] + return [] + + try: + from frameworks.drf.drf_serializer_extractor import ( + extract_serializer_schema, # type: ignore[reportMissingImports] + ) + except ImportError: + # DRF serializer extractor not available + def extract_serializer_schema( + repo_path: Path, serializer_module: str, serializer_class: str + ) -> dict[str, object]: # type: ignore[misc] + return {"type": "object", "properties": {}, "required": []} + + +def _match_url_to_feature(url_pattern: dict[str, object], feature_key: str) -> bool: + """ + Match URL pattern to feature by operation_id or view name. + + Args: + url_pattern: URL pattern dictionary from extractor + feature_key: Feature key (e.g., 'FEATURE-USER-AUTHENTICATION') + + Returns: + True if pattern matches feature + """ + operation_id = str(url_pattern.get("operation_id", "")).lower() + view = str(url_pattern.get("view", "")).lower() + feature_lower = feature_key.lower().replace("feature-", "").replace("-", "_") + + # Check if operation_id or view contains feature keywords + keywords = feature_lower.split("_") + return any(keyword and (keyword in operation_id or keyword in view) for keyword in keywords) + + +def _create_openapi_operation( + url_pattern: dict[str, object], + repo_path: Path, + form_schema: dict[str, object] | None = None, + framework: str = "django", +) -> dict[str, object]: + """ + Create OpenAPI operation from framework URL pattern (Django or FastAPI). + + Args: + url_pattern: URL pattern dictionary from extractor + repo_path: Path to repository (for form extraction, Django only) + form_schema: Optional pre-extracted form schema (Django only) + framework: Framework type ("django" or "fastapi") + + Returns: + OpenAPI operation dictionary + """ + method = str(url_pattern["method"]).lower() + path = str(url_pattern["path"]) + operation_id = str(url_pattern.get("operation_id", "")) + path_params = url_pattern.get("path_params", []) + if not isinstance(path_params, list): + path_params = [] + view_ref = url_pattern.get("view") or url_pattern.get("function") + + operation: dict[str, object] = { + "operationId": operation_id, + "summary": f"{method.upper()} {path}", + "responses": { + "200": {"description": "Success"}, + "400": {"description": "Bad request"}, + "500": {"description": "Internal server error"}, + }, + } + + # Add path parameters + if path_params: + operation["parameters"] = path_params + + # Add request body for POST/PUT/PATCH + if method in ("post", "put", "patch"): + # For FastAPI: try to use extracted Pydantic model schema + schema: dict[str, object] | None = None + if framework == "fastapi": + request_body_schema = url_pattern.get("request_body_schema") + if request_body_schema and isinstance(request_body_schema, dict): + schema = request_body_schema + + # For Django: try to extract form schema from view + if schema is None and framework == "django": + schema = form_schema + if schema is None and view_ref: + # Try to extract from view function + view_str = str(view_ref) + if "." in view_str: + parts = view_str.split(".") + if len(parts) >= 2: + view_module = ".".join(parts[:-1]) + view_function = parts[-1] + schema = extract_view_form_schema(repo_path, view_module, view_function) + + # Special case: login view doesn't use a form + if schema is None and "login" in operation_id.lower(): + schema = { + "type": "object", + "properties": { + "username": {"type": "string", "minLength": 1}, + "password": {"type": "string", "minLength": 1}, + }, + "required": ["username", "password"], + } + + # Use extracted schema or default empty schema + if schema is None: + schema = {"type": "object", "properties": {}, "required": []} + + # FastAPI uses application/json, Django uses application/x-www-form-urlencoded + content_type = "application/json" if framework == "fastapi" else "application/x-www-form-urlencoded" + + operation["requestBody"] = { + "required": True, + "content": { + content_type: { + "schema": schema, + } + }, + } + + return operation # type: ignore[return-value] + + +def _get_common_schemas() -> dict[str, dict[str, object]]: + """ + Get common schema definitions for OpenAPI contracts. + + Returns: + Dictionary of schema name to schema definition + """ + return { + "Path": { + "type": "string", + "description": "File system path", + "example": "/path/to/file.py", + }, + "PlanBundle": { + "type": "object", + "description": "Plan bundle containing features, stories, and product definition", + "properties": { + "version": {"type": "string", "example": "1.0"}, + "idea": { + "type": "object", + "properties": { + "title": {"type": "string"}, + "narrative": {"type": "string"}, + }, + }, + "product": { + "type": "object", + "properties": { + "themes": {"type": "array", "items": {"type": "string"}}, + }, + }, + "features": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": {"type": "string"}, + "title": {"type": "string"}, + "stories": {"type": "array", "items": {"type": "object"}}, + }, + }, + }, + }, + }, + "FileSystemEvent": { + "type": "object", + "description": "File system event (created, modified, deleted)", + "properties": { + "path": {"type": "string"}, + "event_type": {"type": "string", "enum": ["created", "modified", "deleted"]}, + "timestamp": {"type": "string", "format": "date-time"}, + }, + }, + "SyncResult": { + "type": "object", + "description": "Synchronization result", + "properties": { + "success": {"type": "boolean"}, + "message": {"type": "string"}, + "changes": {"type": "array", "items": {"type": "object"}}, + }, + }, + "RepositorySyncResult": { + "type": "object", + "description": "Repository synchronization result", + "properties": { + "success": {"type": "boolean"}, + "synced_files": {"type": "array", "items": {"type": "string"}}, + "conflicts": {"type": "array", "items": {"type": "object"}}, + }, + }, + } + + +def _resolve_schema_refs(contract: dict[str, object]) -> dict[str, object]: + """ + Resolve schema references and add missing schema definitions. + + Args: + contract: OpenAPI contract dictionary + + Returns: + Updated contract with resolved schemas + """ + # Get common schemas + common_schemas = _get_common_schemas() + + # Ensure components.schemas exists + components = contract.get("components", {}) + if not isinstance(components, dict): + components = {} + contract["components"] = components + + schemas = components.get("schemas", {}) + if not isinstance(schemas, dict): + schemas = {} + components["schemas"] = schemas + + # Find all $ref references in the contract + def find_refs(obj: object, refs: set[str]) -> None: + """Recursively find all $ref references.""" + if isinstance(obj, dict): + if "$ref" in obj: + ref = str(obj["$ref"]) + if ref.startswith("#/components/schemas/"): + schema_name = ref.split("/")[-1] + refs.add(schema_name) + for value in obj.values(): + find_refs(value, refs) + elif isinstance(obj, list): + for item in obj: + find_refs(item, refs) + + refs: set[str] = set() + find_refs(contract, refs) + + # Add missing schema definitions + for ref in refs: + if ref not in schemas and ref in common_schemas: + schemas[ref] = common_schemas[ref] + elif ref in schemas and ref in common_schemas: + # Fix incorrect schema definitions (hotpatch for PlanBundle schema bug) + # If schema exists but has incorrect structure, replace with correct one + existing_schema = schemas[ref] + correct_schema = common_schemas[ref] + + # Special case: Fix PlanBundle.themes schema bug (array of objects -> array of strings) + if ref == "PlanBundle" and isinstance(existing_schema, dict) and isinstance(correct_schema, dict): + existing_props = existing_schema.get("properties", {}) + if not isinstance(existing_props, dict): + existing_props = {} + correct_props = correct_schema.get("properties", {}) + if not isinstance(correct_props, dict): + correct_props = {} + + # Check if themes schema is incorrect + existing_product = existing_props.get("product", {}) + if not isinstance(existing_product, dict): + existing_product = {} + existing_product_props = existing_product.get("properties", {}) + if not isinstance(existing_product_props, dict): + existing_product_props = {} + existing_themes = existing_product_props.get("themes", {}) + + correct_product = correct_props.get("product", {}) + if not isinstance(correct_product, dict): + correct_product = {} + correct_product_props = correct_product.get("properties", {}) + if not isinstance(correct_product_props, dict): + correct_product_props = {} + correct_themes = correct_product_props.get("themes", {}) + + if ( + isinstance(existing_themes, dict) + and isinstance(correct_themes, dict) + and existing_themes.get("items", {}).get("type") == "object" + and correct_themes.get("items", {}).get("type") == "string" + ): + # Fix the themes schema + if "product" not in existing_props: + existing_props["product"] = {} + if "properties" not in existing_props["product"]: + existing_props["product"]["properties"] = {} + existing_props["product"]["properties"]["themes"] = correct_themes + + return contract + + +def populate_contracts( + contracts_dir: Path, + repo_path: Path, + urls_file: Path | None = None, + extract_forms: bool = True, + url_patterns: list[dict[str, object]] | None = None, + framework: str = "django", +) -> tuple[dict[str, int], list[dict[str, object]]]: + """ + Populate OpenAPI contract stubs with framework URL patterns (Django or FastAPI). + + Args: + contracts_dir: Directory containing *.openapi.yaml files + repo_path: Path to repository + urls_file: Path to urls.py file (Django only, auto-detected if not provided) + extract_forms: Whether to extract form schemas from views (Django only) + url_patterns: Pre-extracted URL patterns (if None, will extract) + framework: Framework type ("django" or "fastapi") + + Returns: + Tuple of (statistics dict, url_patterns list) + """ + # Extract URL patterns if not provided + if url_patterns is None: + if framework == "fastapi": + url_patterns = extract_fastapi_routes(repo_path) + else: + url_patterns = extract_django_urls(repo_path, urls_file) + + if not url_patterns: + return {"populated": 0, "skipped": 0, "errors": 0}, [] + + # Find all contract files + contract_files = list(contracts_dir.glob("*.openapi.yaml")) + + stats = {"populated": 0, "skipped": 0, "errors": 0} + + for contract_file in contract_files: + try: + # Load contract + with contract_file.open("r", encoding="utf-8") as f: + contract_data = yaml.safe_load(f) # type: ignore[assignment] + if not isinstance(contract_data, dict): + contract_data = {} + contract = cast(dict[str, object], contract_data) + + if "paths" not in contract: + contract["paths"] = {} + + # Extract feature key from filename + feature_key = contract_file.stem.replace(".openapi", "").upper() + + # Find matching URL patterns + matching_patterns = [p for p in url_patterns if _match_url_to_feature(p, feature_key)] + + if not matching_patterns: + stats["skipped"] += 1 + continue + + # Populate paths + for pattern in matching_patterns: + path = str(pattern["path"]) + method = str(pattern["method"]).lower() + + paths_dict = contract.get("paths", {}) + if not isinstance(paths_dict, dict): + paths_dict = {} + contract["paths"] = paths_dict + if path not in paths_dict: + paths_dict[path] = {} # type: ignore[assignment] + + # Check if operation already exists (may have enriched schemas) + existing_operation: dict[str, object] | None = None + if isinstance(paths_dict, dict) and isinstance(paths_dict.get(path), dict): + existing_operation = paths_dict[path].get(method) # type: ignore[index] + if not isinstance(existing_operation, dict): + existing_operation = None + + # Extract form schema if enabled (Django only) + form_schema: dict[str, object] | None = None + if extract_forms and framework == "django": + view_ref = pattern.get("view") + if view_ref: + view_str = str(view_ref) + if "." in view_str: + parts = view_str.split(".") + if len(parts) >= 2: + view_module = ".".join(parts[:-1]) + view_function = parts[-1] + form_schema = extract_view_form_schema(repo_path, view_module, view_function) + + operation = _create_openapi_operation(pattern, repo_path, form_schema, framework) # type: ignore[arg-type] + + # Merge with existing operation, preserving enriched schemas + if existing_operation: + # Preserve enriched requestBody if it exists + existing_request_body = existing_operation.get("requestBody") + if existing_request_body and isinstance(existing_request_body, dict): + existing_content = existing_request_body.get("content", {}) + if isinstance(existing_content, dict): + # Check if ANY content type has enriched schema (has properties with proper types, not just 'object') + # This handles cases where enriched contract uses application/json but + # existing contract might have application/x-www-form-urlencoded + has_enriched_schema = False + for _content_type, content_schema in existing_content.items(): + if isinstance(content_schema, dict): + schema = content_schema.get("schema", {}) + if isinstance(schema, dict): + properties = schema.get("properties", {}) + required = schema.get("required", []) + # Consider enriched if it has properties with proper types (not just 'object') + if isinstance(properties, dict) and properties: + # Check if at least one property has a proper type (not 'object') + for prop in properties.values(): + if isinstance(prop, dict): + prop_type = prop.get("type", "") + if prop_type and prop_type != "object": + has_enriched_schema = True + break + if has_enriched_schema: + break + # Also consider enriched if it has required fields (even with weak types) + elif isinstance(required, list) and required: + has_enriched_schema = True + break + + if has_enriched_schema: + # Has enriched schema - merge individual properties, preserving enriched ones and replacing weak ones + # This allows us to update weak properties (type: 'object') while preserving enriched ones + new_request_body = operation.get("requestBody") + if new_request_body and isinstance(new_request_body, dict): + new_content = new_request_body.get("content", {}) + if isinstance(new_content, dict): + # Merge: keep existing content types, but replace weak properties with extracted ones + merged_content = copy.deepcopy(existing_content) + for content_type, content_schema in new_content.items(): + if content_type not in merged_content: + # New content type - add it + merged_content[content_type] = content_schema + else: + # Content type exists - merge individual properties + existing_schema = merged_content[content_type] + if isinstance(existing_schema, dict) and isinstance( + content_schema, dict + ): + existing_schema_obj = existing_schema.get("schema", {}) + new_schema_obj = content_schema.get("schema", {}) + if isinstance(existing_schema_obj, dict) and isinstance( + new_schema_obj, dict + ): + existing_props = existing_schema_obj.get("properties", {}) + new_props = new_schema_obj.get("properties", {}) + if isinstance(existing_props, dict) and isinstance( + new_props, dict + ): + # Merge properties: replace weak ones (type: 'object') with extracted ones + merged_props = dict(existing_props) + for prop_name, new_prop in new_props.items(): + existing_prop = merged_props.get(prop_name, {}) + if isinstance(new_prop, dict) and isinstance( + existing_prop, dict + ): + new_type = new_prop.get("type", "") + existing_type = existing_prop.get("type", "") + new_has_proper_type = ( + new_type and new_type != "object" + ) + existing_has_weak_type = ( + not existing_type or existing_type == "object" + ) + + # Replace weak properties with extracted ones, preserve enriched ones + if new_has_proper_type and existing_has_weak_type: + merged_props[prop_name] = new_prop + elif ( + new_has_proper_type + and existing_type == new_type + ): + # Both have same type - prefer new if it has more constraints + new_constraints = sum( + 1 + for k in new_prop + if k + in [ + "minLength", + "maxLength", + "format", + "nullable", + "default", + ] + ) + existing_constraints = sum( + 1 + for k in existing_prop + if k + in [ + "minLength", + "maxLength", + "format", + "nullable", + "default", + ] + ) + if new_constraints > existing_constraints: + merged_props[prop_name] = new_prop + elif not existing_prop: + # New property - add it + merged_props[prop_name] = new_prop + # Update the schema with merged properties + existing_schema_obj["properties"] = merged_props + # Also merge required fields + existing_required = existing_schema_obj.get("required", []) + new_required = new_schema_obj.get("required", []) + if isinstance(existing_required, list) and isinstance( + new_required, list + ): + merged_required = list( + set(existing_required + new_required) + ) + existing_schema_obj["required"] = merged_required + # Update the operation's requestBody with merged content + request_body = operation.get("requestBody") + if isinstance(request_body, dict): + request_body["content"] = merged_content + elif "requestBody" in operation: + # If no enriched schema found, but new operation has requestBody, merge content types + # This allows both application/json (FastAPI) and application/x-www-form-urlencoded (Django) to coexist + new_request_body = operation.get("requestBody") + if new_request_body and isinstance(new_request_body, dict): + new_content = new_request_body.get("content", {}) + if isinstance(new_content, dict): + # Merge: keep existing content types, but replace empty ones with extracted schemas + # Use deep copy to ensure nested modifications are preserved + merged_content = copy.deepcopy(existing_content) + for content_type, content_schema in new_content.items(): + if content_type not in merged_content: + # New content type - add it + merged_content[content_type] = content_schema + else: + # Content type exists - check if we should replace weak schema with extracted one + existing_schema = merged_content[content_type] + if isinstance(existing_schema, dict) and isinstance( + content_schema, dict + ): + existing_schema_obj = existing_schema.get("schema", {}) + new_schema_obj = content_schema.get("schema", {}) + if isinstance(existing_schema_obj, dict) and isinstance( + new_schema_obj, dict + ): + existing_props = existing_schema_obj.get("properties", {}) + new_props = new_schema_obj.get("properties", {}) + if isinstance(existing_props, dict) and isinstance( + new_props, dict + ): + # Check if existing schema is weak (all properties have type 'object' or no type) + existing_is_weak = True + if existing_props: + for prop in existing_props.values(): + if isinstance(prop, dict): + prop_type = prop.get("type", "") + if prop_type and prop_type != "object": + existing_is_weak = False + break + else: + existing_is_weak = True # Empty properties = weak + + # Check if new schema has proper types + new_has_proper_types = False + if new_props: + for prop in new_props.values(): + if isinstance(prop, dict): + prop_type = prop.get("type", "") + if prop_type and prop_type != "object": + new_has_proper_types = True + break + + # If existing is weak and new has proper types, replace entire schema + if existing_is_weak and new_has_proper_types: + # Replace the entire content schema with the extracted one + merged_content[content_type] = content_schema + else: + # Merge individual properties: use new if it has more information + merged_props = dict(existing_props) + for prop_name, new_prop in new_props.items(): + existing_prop = merged_props.get(prop_name, {}) + if isinstance(new_prop, dict) and isinstance( + existing_prop, dict + ): + new_type = new_prop.get("type", "") + existing_type = existing_prop.get("type", "") + new_has_proper_type = ( + new_type and new_type != "object" + ) + existing_has_weak_type = ( + not existing_type + or existing_type == "object" + ) + + if ( + new_has_proper_type + and existing_has_weak_type + ): + merged_props[prop_name] = new_prop + elif ( + new_has_proper_type + and existing_type == new_type + ): + # Both have same type - prefer new if it has more constraints + new_constraints = sum( + 1 + for k in new_prop + if k + in [ + "minLength", + "maxLength", + "format", + "nullable", + "default", + ] + ) + existing_constraints = sum( + 1 + for k in existing_prop + if k + in [ + "minLength", + "maxLength", + "format", + "nullable", + "default", + ] + ) + if new_constraints > existing_constraints: + merged_props[prop_name] = new_prop + elif not existing_prop: + merged_props[prop_name] = new_prop + # Update the schema with merged properties + existing_schema_obj["properties"] = merged_props + # Also merge required fields + existing_required = existing_schema_obj.get( + "required", [] + ) + new_required = new_schema_obj.get("required", []) + if isinstance(existing_required, list) and isinstance( + new_required, list + ): + merged_required = list( + set(existing_required + new_required) + ) + existing_schema_obj["required"] = merged_required + # Update the operation's requestBody with merged content + request_body = operation.get("requestBody") + if isinstance(request_body, dict): + request_body["content"] = merged_content + else: + # If new operation has requestBody, merge content types + new_request_body = operation.get("requestBody") + if new_request_body and isinstance(new_request_body, dict): + new_content = new_request_body.get("content", {}) + if isinstance(new_content, dict): + # Merge: keep existing content types, add new ones + merged_content = dict(existing_content) + for content_type, content_schema in new_content.items(): + if content_type not in merged_content: + merged_content[content_type] = content_schema + # Type check to ensure requestBody is a dict before setting content + request_body = operation.get("requestBody") + if isinstance(request_body, dict): + request_body["content"] = merged_content + + # Preserve enriched responses if they exist + existing_responses = existing_operation.get("responses") + if existing_responses and isinstance(existing_responses, dict): + # Check if any response has enriched schema + has_enriched_response = False + for _status_code, response in existing_responses.items(): + if isinstance(response, dict): + content = response.get("content", {}) + if isinstance(content, dict): + for _content_type, content_schema in content.items(): + if isinstance(content_schema, dict): + schema = content_schema.get("schema", {}) + if isinstance(schema, dict): + properties = schema.get("properties", {}) + if isinstance(properties, dict) and properties: + has_enriched_response = True + break + if has_enriched_response: + # Merge responses, preserving enriched ones + merged_responses = dict(existing_responses) + new_responses = operation.get("responses", {}) + if isinstance(new_responses, dict): + for status_code, response in new_responses.items(): + if status_code not in merged_responses: + merged_responses[status_code] = response + elif isinstance(merged_responses[status_code], dict) and isinstance(response, dict): + # Preserve enriched content if it exists + existing_content = merged_responses[status_code].get("content", {}) + new_content = response.get("content", {}) + if isinstance(existing_content, dict) and isinstance(new_content, dict): + # Keep existing enriched content + for content_type, content_schema in existing_content.items(): + if content_type not in new_content: + new_content[content_type] = content_schema + merged_responses[status_code]["content"] = existing_content + operation["responses"] = merged_responses + + # Preserve other enriched fields (parameters, etc.) + if "parameters" in existing_operation: + operation["parameters"] = existing_operation["parameters"] + + if isinstance(paths_dict, dict) and isinstance(paths_dict.get(path), dict): + paths_dict[path][method] = operation # type: ignore[assignment, index] + + # Resolve schema references and add missing schemas + contract = _resolve_schema_refs(contract) + + # Save updated contract + with contract_file.open("w", encoding="utf-8") as f: + yaml.dump(contract, f, default_flow_style=False, sort_keys=False, allow_unicode=True) + + stats["populated"] += 1 + + except Exception as e: + print(f"Error processing {contract_file}: {e}") + stats["errors"] += 1 + + return stats, url_patterns + + +def resolve_schema_refs_in_contracts(contracts_dir: Path) -> dict[str, int]: + """ + Resolve schema references in all OpenAPI contracts. + + This function adds missing schema definitions for common types like Path, PlanBundle, etc. + It can be used for any project type (not just Django). + + Args: + contracts_dir: Directory containing *.openapi.yaml files + + Returns: + Dictionary with statistics (resolved, skipped, errors) + """ + contract_files = list(contracts_dir.glob("*.openapi.yaml")) + stats = {"resolved": 0, "skipped": 0, "errors": 0} + + for contract_file in contract_files: + try: + # Load contract + with contract_file.open("r", encoding="utf-8") as f: + contract_data = yaml.safe_load(f) # type: ignore[assignment] + if not isinstance(contract_data, dict): + contract_data = {} + contract = cast(dict[str, object], contract_data) + + # Resolve schema references + # Get original schemas BEFORE resolving (make a copy since _resolve_schema_refs modifies in place) + import json + + components = contract.get("components") + original_schemas: dict[str, object] = {} + original_schemas_str = "" + if isinstance(components, dict): + schemas = components.get("schemas") + if isinstance(schemas, dict): + original_schemas = schemas.copy() # Make a copy to avoid reference issues + # Also serialize to string for comparison (to detect schema fixes, not just additions) + original_schemas_str = json.dumps(original_schemas, sort_keys=True) + + contract = _resolve_schema_refs(contract) + + new_schemas: dict[str, object] = {} + components_after = contract.get("components") + if isinstance(components_after, dict): + schemas_after = components_after.get("schemas") + if isinstance(schemas_after, dict): + new_schemas = schemas_after + + # Check if schemas were added OR fixed (hotpatch for PlanBundle schema bug) + schemas_changed = False + if len(new_schemas) > len(original_schemas): + schemas_changed = True + elif len(new_schemas) == len(original_schemas) and len(original_schemas) > 0 and original_schemas_str: + # Check if any schemas were modified (e.g., PlanBundle.themes fix) + new_schemas_str = json.dumps(new_schemas, sort_keys=True) + if new_schemas_str != original_schemas_str: + schemas_changed = True + + if schemas_changed: + # Save updated contract + with contract_file.open("w", encoding="utf-8") as f: + yaml.dump(contract, f, default_flow_style=False, sort_keys=False, allow_unicode=True) + stats["resolved"] += 1 + else: + stats["skipped"] += 1 + + except Exception as e: + print(f"Error processing {contract_file}: {e}") + stats["errors"] += 1 + + return stats + + +def generate_bindings(url_patterns: list[dict[str, object]], bindings_path: Path) -> dict[str, int]: + """ + Generate bindings.yaml from Django URL patterns. + + Args: + url_patterns: List of URL pattern dictionaries from extractor + bindings_path: Path to bindings.yaml file to create/update + + Returns: + Dictionary with statistics (generated, skipped, errors) + """ + if not url_patterns: + return {"generated": 0, "skipped": 0, "errors": 0} + + bindings: list[dict[str, object]] = [] + + for pattern in url_patterns: + operation_id = pattern.get("operation_id") + # FastAPI uses "function", Django uses "view" + view = pattern.get("view") or pattern.get("function") + path = str(pattern.get("path", "")) + + if not operation_id or not view: + continue + + # Convert view/function reference to target format (taskManager.views.index -> taskManager.views:index) + # For FastAPI: backend.app.api.routes.login.login_access_token -> backend.app.api.routes.login:login_access_token + if "." in str(view): + parts = str(view).rsplit(".", 1) + target = f"{parts[0]}:{parts[1]}" + else: + target = str(view) + + # Ensure path starts with / + if path and not path.startswith("/"): + path = f"/{path}" + + # Determine adapter based on function path + # FastAPI functions are in backend.app.api.routes.* or *.routes.*, Django views are typically in *.views.* + adapter = "call_fastapi_route" if ("api.routes" in str(view) or ".routes." in str(view)) else "call_django_view" + + binding = { + "operation_id": operation_id, + "adapter": adapter, + "target": target, + "path": path if path else "/", + } + bindings.append(binding) + + # Load existing bindings if file exists + existing_bindings: list[dict[str, object]] = [] + if bindings_path.exists(): + try: + with bindings_path.open("r", encoding="utf-8") as f: + existing_data = yaml.safe_load(f) or {} + existing_bindings = existing_data.get("bindings", []) or [] + except Exception: + existing_bindings = [] + + # Merge: keep existing bindings, add new ones (don't duplicate) + existing_ops = {b.get("operation_id") for b in existing_bindings if isinstance(b, dict)} + new_bindings = [b for b in bindings if b.get("operation_id") not in existing_ops] + merged_bindings = existing_bindings + new_bindings + + # Write bindings.yaml + try: + bindings_data = {"bindings": merged_bindings} + with bindings_path.open("w", encoding="utf-8") as f: + yaml.dump(bindings_data, f, default_flow_style=False, sort_keys=False, allow_unicode=True) + return {"generated": len(new_bindings), "skipped": len(existing_bindings), "errors": 0} + except Exception as e: + print(f"Error writing bindings: {e}") + return {"generated": 0, "skipped": 0, "errors": 1} + + +def main() -> int: + """Main entry point for contract population.""" + parser = argparse.ArgumentParser( + description="Populate OpenAPI contracts with Django URL patterns or resolve schema references." + ) + parser.add_argument("--contracts", required=True, help="Contracts directory containing *.openapi.yaml files") + parser.add_argument("--repo", help="Path to repository (required for URL population)") + parser.add_argument("--urls", help="Path to urls.py file (Django only, auto-detected if not provided)") + parser.add_argument( + "--resolve-schemas-only", action="store_true", help="Only resolve schema references, don't populate URLs" + ) + parser.add_argument("--bindings", help="Path to bindings.yaml file to generate (auto-generated if not provided)") + parser.add_argument( + "--framework", choices=["django", "fastapi"], default="django", help="Framework type (default: django)" + ) + args = parser.parse_args() + + contracts_dir = Path(str(args.contracts)).resolve() # type: ignore[arg-type] + + if not contracts_dir.exists(): + print(f"Error: Contracts directory not found: {contracts_dir}") + return 1 + + # If --resolve-schemas-only, just resolve schema references + if args.resolve_schemas_only: + stats = resolve_schema_refs_in_contracts(contracts_dir) + print(f"Resolved: {stats['resolved']}, Skipped: {stats['skipped']}, Errors: {stats['errors']}") + return 0 if stats["errors"] == 0 else 1 + + # Otherwise, do Django URL population (requires --repo) + if not args.repo: + print("Error: --repo is required for URL population (or use --resolve-schemas-only)") + return 1 + + repo_path = Path(str(args.repo)).resolve() # type: ignore[arg-type] + urls_file = Path(str(args.urls)).resolve() if args.urls else None # type: ignore[arg-type] + + if not repo_path.exists(): + print(f"Error: Repository path not found: {repo_path}") + return 1 + + # Populate URLs and resolve schemas (returns stats and url_patterns) + stats, url_patterns = populate_contracts(contracts_dir, repo_path, urls_file, framework=args.framework) + + # Also resolve schema references after population + schema_stats = resolve_schema_refs_in_contracts(contracts_dir) + stats["schema_resolved"] = schema_stats["resolved"] + + # Generate bindings.yaml if requested + if args.bindings or url_patterns: + bindings_path = Path(str(args.bindings)) if args.bindings else Path("bindings.yaml") + bindings_stats = generate_bindings(url_patterns, bindings_path) + stats["bindings_generated"] = bindings_stats["generated"] + stats["bindings_skipped"] = bindings_stats["skipped"] + stats["bindings_errors"] = bindings_stats["errors"] + + print( + f"Populated: {stats['populated']}, Skipped: {stats['skipped']}, Errors: {stats['errors']}, Schemas resolved: {stats.get('schema_resolved', 0)}" + ) + if "bindings_generated" in stats: + print( + f"Bindings: Generated: {stats['bindings_generated']}, Skipped: {stats['bindings_skipped']}, Errors: {stats['bindings_errors']}" + ) + + return 0 if stats["errors"] == 0 else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/resources/templates/sidecar/run_sidecar.sh b/resources/templates/sidecar/common/run_sidecar.sh similarity index 74% rename from resources/templates/sidecar/run_sidecar.sh rename to resources/templates/sidecar/common/run_sidecar.sh index 62ca567..9de7cbc 100644 --- a/resources/templates/sidecar/run_sidecar.sh +++ b/resources/templates/sidecar/common/run_sidecar.sh @@ -89,8 +89,12 @@ fi # Detect framework type for environment setup FRAMEWORK_TYPE="${FRAMEWORK_TYPE:-}" if [[ -z "${FRAMEWORK_TYPE}" ]]; then + # FastAPI detection + if find "${REPO_PATH}" -maxdepth 3 -name "main.py" -o -name "app.py" | xargs grep -l "from fastapi import\|FastAPI(" 2>/dev/null | head -1 | grep -q .; then + FRAMEWORK_TYPE="fastapi" + echo "[sidecar] detected framework: FastAPI" # Django detection - if [[ -f "${REPO_PATH}/manage.py" ]] || find "${REPO_PATH}" -maxdepth 2 -name "urls.py" -type f 2>/dev/null | grep -q .; then + elif [[ -f "${REPO_PATH}/manage.py" ]] || find "${REPO_PATH}" -maxdepth 2 -name "urls.py" -type f 2>/dev/null | grep -q .; then FRAMEWORK_TYPE="django" echo "[sidecar] detected framework: Django" # Set Django settings module if not already set @@ -116,11 +120,34 @@ if [[ -z "${SIDECAR_SOURCE_DIRS}" ]]; then SIDECAR_SOURCE_DIRS="${REPO_PATH}/src" elif [[ -d "${REPO_PATH}/lib" ]]; then SIDECAR_SOURCE_DIRS="${REPO_PATH}/lib" + elif [[ -d "${REPO_PATH}/backend/app" ]]; then + # FastAPI apps often have backend/app structure + SIDECAR_SOURCE_DIRS="${REPO_PATH}/backend/app" else SIDECAR_SOURCE_DIRS="${REPO_PATH}" fi fi +# Filter out test directories from CrossHair source analysis +# CrossHair tries to import everything, including test files that may require pytest +_filter_crosshair_dirs() { + local dirs=("$@") + local filtered=() + for dir in "${dirs[@]}"; do + # Skip common test directory patterns + if [[ "$dir" == *"/test"* ]] || [[ "$dir" == *"/tests"* ]] || [[ "$dir" == *"/test_"* ]] || [[ "$dir" == *"/__pycache__"* ]]; then + continue + fi + # Check if directory contains test files + if find "$dir" -maxdepth 2 -name "test_*.py" -o -name "*_test.py" -o -name "conftest.py" 2>/dev/null | grep -q .; then + # Directory contains test files, skip it + continue + fi + filtered+=("$dir") + done + echo "${filtered[@]}" +} + run_with_timeout() { local timeout_secs="$1" shift @@ -198,23 +225,47 @@ echo "[sidecar] contracts: ${CONTRACTS_DIR}" echo "[sidecar] sources: ${SIDECAR_SOURCE_DIRS}" echo "[sidecar] reports: ${SIDECAR_REPORTS_DIR}" -# Populate contracts with framework-specific patterns (Django, etc.) +# AI Enrichment Step (BEFORE contract population) +# This is where AI should add reasoning/value to strengthen contracts +# TODO: Integrate AI enrichment here to: +# - Analyze code (FastAPI routes, Pydantic models, validation logic) +# - Extract Pydantic model schemas +# - Add validation rules (minLength, maxLength, pattern, etc.) +# - Add required fields and type constraints +# - Update OpenAPI contract schemas with enriched details +# For now, this step is manual (Phase 2 enrichment) but should be automated in sidecar +ENRICH_CONTRACTS="${ENRICH_CONTRACTS:-0}" +if [[ "${ENRICH_CONTRACTS}" == "1" ]] && [[ -d "${CONTRACTS_DIR}" ]]; then + echo "[sidecar] AI enrichment (strengthen contracts with reasoning)..." + echo "[sidecar] TODO: Integrate AI enrichment to analyze code and strengthen contract schemas" + echo "[sidecar] For now, using existing contracts (may be weak from Phase 1)" + # Future: Call AI enrichment service/command here + # Future: AI analyzes code and updates contract schemas with: + # - Pydantic model schemas + # - Validation rules + # - Required fields + # - Type constraints +fi + +# Populate contracts with framework-specific patterns (Django, FastAPI, etc.) POPULATE_CONTRACTS="${POPULATE_CONTRACTS:-1}" if [[ "${POPULATE_CONTRACTS}" == "1" ]] && [[ -d "${CONTRACTS_DIR}" ]]; then - if [[ "${FRAMEWORK_TYPE}" == "django" ]]; then - echo "[sidecar] populate contracts (Django URL patterns)..." + if [[ "${FRAMEWORK_TYPE}" == "django" ]] || [[ "${FRAMEWORK_TYPE}" == "fastapi" ]]; then + echo "[sidecar] populate contracts (${FRAMEWORK_TYPE} routes)..." run_and_log "${TIMEOUT_CROSSHAIR}" \ "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-populate-contracts.log" \ - "${PYTHON_CMD}" populate_contracts.py \ + "${PYTHON_CMD}" "${SIDECAR_DIR}/populate_contracts.py" \ --contracts "${CONTRACTS_DIR}" \ --repo "${REPO_PATH}" \ + --bindings "${BINDINGS_PATH}" \ + --framework "${FRAMEWORK_TYPE}" \ || echo "[sidecar] warning: contract population failed (continuing anyway)" else # For non-Django projects, just resolve schema references echo "[sidecar] resolve contract schema references..." run_and_log "${TIMEOUT_CROSSHAIR}" \ "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-resolve-schemas.log" \ - "${PYTHON_CMD}" populate_contracts.py \ + "${PYTHON_CMD}" "${SIDECAR_DIR}/populate_contracts.py" \ --contracts "${CONTRACTS_DIR}" \ --resolve-schemas-only \ || echo "[sidecar] warning: schema resolution failed (continuing anyway)" @@ -229,7 +280,7 @@ if [[ "${GENERATE_HARNESS}" == "1" ]]; then echo "[sidecar] generate harness..." run_and_log "${TIMEOUT_CROSSHAIR}" \ "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-harness.log" \ - "${PYTHON_CMD}" generate_harness.py \ + "${PYTHON_CMD}" "${SIDECAR_DIR}/generate_harness.py" \ --contracts "${CONTRACTS_DIR}" \ --output "${HARNESS_PATH}" \ --inputs "${INPUTS_PATH}" \ @@ -363,38 +414,51 @@ if [[ "${RUN_CROSSHAIR}" == "1" ]] && command -v crosshair >/dev/null 2>&1; then # Case A: Analyze source code directly (for existing decorators: beartype, icontract, etc.) # This catches contracts that are already in the source code (e.g., SpecFact CLI dogfooding) - # For Django projects, use the Django-aware wrapper to initialize the app registry first - echo "[sidecar] crosshair (source code - existing decorators)..." - if [[ "${FRAMEWORK_TYPE}" == "django" ]]; then - # Use Django-aware wrapper for source code analysis - CROSSHAIR_WRAPPER="${SIDECAR_DIR}/crosshair_django_wrapper.py" - if [[ -f "${CROSSHAIR_WRAPPER}" ]]; then - echo "[sidecar] using Django-aware CrossHair wrapper for source analysis" - # Export environment variables for Django initialization - CROSSHAIR_ENV="" - if [[ -n "${DJANGO_SETTINGS_MODULE:-}" ]]; then - CROSSHAIR_ENV="DJANGO_SETTINGS_MODULE=${DJANGO_SETTINGS_MODULE} " - fi - if [[ -n "${REPO_PATH:-}" ]]; then - CROSSHAIR_ENV="${CROSSHAIR_ENV}REPO_PATH=${REPO_PATH} " - fi - if [[ -n "${PYTHONPATH:-}" ]]; then - CROSSHAIR_ENV="${CROSSHAIR_ENV}PYTHONPATH=${PYTHONPATH} " + # Skip for FastAPI apps - they typically don't have decorators and require dependencies + if [[ "${FRAMEWORK_TYPE}" == "fastapi" ]]; then + echo "[sidecar] crosshair (source code - existing decorators)... skipped (FastAPI apps typically don't have decorators)" + else + echo "[sidecar] crosshair (source code - existing decorators)..." + + # Filter out test directories to avoid importing test files that require pytest + CROSSHAIR_SOURCE_DIRS_ARRAY=(${SIDECAR_SOURCE_DIRS}) + CROSSHAIR_FILTERED_DIRS=$(_filter_crosshair_dirs "${CROSSHAIR_SOURCE_DIRS_ARRAY[@]}") + + if [[ -z "${CROSSHAIR_FILTERED_DIRS}" ]]; then + echo "[sidecar] warning: all source directories filtered out (contain tests), skipping source code analysis" + else + if [[ "${FRAMEWORK_TYPE}" == "django" ]]; then + # Use Django-aware wrapper for source code analysis + CROSSHAIR_WRAPPER="${SIDECAR_DIR}/../frameworks/django/crosshair_django_wrapper.py" + if [[ -f "${CROSSHAIR_WRAPPER}" ]]; then + echo "[sidecar] using Django-aware CrossHair wrapper for source analysis" + # Export environment variables for Django initialization + CROSSHAIR_ENV="" + if [[ -n "${DJANGO_SETTINGS_MODULE:-}" ]]; then + CROSSHAIR_ENV="DJANGO_SETTINGS_MODULE=${DJANGO_SETTINGS_MODULE} " + fi + if [[ -n "${REPO_PATH:-}" ]]; then + CROSSHAIR_ENV="${CROSSHAIR_ENV}REPO_PATH=${REPO_PATH} " + fi + if [[ -n "${PYTHONPATH:-}" ]]; then + CROSSHAIR_ENV="${CROSSHAIR_ENV}PYTHONPATH=${PYTHONPATH} " + fi + run_and_log "${TIMEOUT_CROSSHAIR}" \ + "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \ + env ${CROSSHAIR_ENV}"${PYTHON_CMD}" "${CROSSHAIR_WRAPPER}" check "${CROSSHAIR_ARGS[@]}" ${CROSSHAIR_FILTERED_DIRS} + else + echo "[sidecar] warning: Django wrapper not found, using standard CrossHair (may fail)" + run_and_log "${TIMEOUT_CROSSHAIR}" \ + "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \ + "${PYTHON_CMD}" -m crosshair check "${CROSSHAIR_ARGS[@]}" ${CROSSHAIR_FILTERED_DIRS} fi - run_and_log "${TIMEOUT_CROSSHAIR}" \ - "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \ - env ${CROSSHAIR_ENV}"${PYTHON_CMD}" "${CROSSHAIR_WRAPPER}" check "${CROSSHAIR_ARGS[@]}" ${SIDECAR_SOURCE_DIRS} else - echo "[sidecar] warning: Django wrapper not found, using standard CrossHair (may fail)" + # Standard CrossHair for non-Django projects run_and_log "${TIMEOUT_CROSSHAIR}" \ "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \ - "${PYTHON_CMD}" -m crosshair check "${CROSSHAIR_ARGS[@]}" ${SIDECAR_SOURCE_DIRS} + "${PYTHON_CMD}" -m crosshair check "${CROSSHAIR_ARGS[@]}" ${CROSSHAIR_FILTERED_DIRS} + fi fi - else - # Standard CrossHair for non-Django projects - run_and_log "${TIMEOUT_CROSSHAIR}" \ - "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \ - "${PYTHON_CMD}" -m crosshair check "${CROSSHAIR_ARGS[@]}" ${SIDECAR_SOURCE_DIRS} fi # Case B: Analyze harness (for contracts added via harness generation) @@ -407,6 +471,9 @@ if [[ "${RUN_CROSSHAIR}" == "1" ]] && command -v crosshair >/dev/null 2>&1; then if [[ -n "${DJANGO_SETTINGS_MODULE:-}" ]]; then CROSSHAIR_ENV="DJANGO_SETTINGS_MODULE=${DJANGO_SETTINGS_MODULE} " fi + if [[ -n "${REPO_PATH:-}" ]]; then + CROSSHAIR_ENV="${CROSSHAIR_ENV}REPO_PATH=${REPO_PATH} " + fi if [[ -n "${PYTHONPATH:-}" ]]; then CROSSHAIR_ENV="${CROSSHAIR_ENV}PYTHONPATH=${PYTHONPATH} " fi diff --git a/resources/templates/sidecar/sidecar-init.sh b/resources/templates/sidecar/common/sidecar-init.sh similarity index 97% rename from resources/templates/sidecar/sidecar-init.sh rename to resources/templates/sidecar/common/sidecar-init.sh index 6ff4148..e302dcb 100755 --- a/resources/templates/sidecar/sidecar-init.sh +++ b/resources/templates/sidecar/common/sidecar-init.sh @@ -2,7 +2,8 @@ set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -TEMPLATE_DIR="${SCRIPT_DIR}" +# Since this script is in common/, the template root is the parent directory +TEMPLATE_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)" TARGET_DIR="${1:-}" REPO_PATH="${2:-}" diff --git a/resources/templates/sidecar/frameworks/django/__init__.py b/resources/templates/sidecar/frameworks/django/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/resources/templates/sidecar/crosshair_django_wrapper.py b/resources/templates/sidecar/frameworks/django/crosshair_django_wrapper.py similarity index 100% rename from resources/templates/sidecar/crosshair_django_wrapper.py rename to resources/templates/sidecar/frameworks/django/crosshair_django_wrapper.py diff --git a/resources/templates/sidecar/django_form_extractor.py b/resources/templates/sidecar/frameworks/django/django_form_extractor.py similarity index 100% rename from resources/templates/sidecar/django_form_extractor.py rename to resources/templates/sidecar/frameworks/django/django_form_extractor.py diff --git a/resources/templates/sidecar/django_url_extractor.py b/resources/templates/sidecar/frameworks/django/django_url_extractor.py similarity index 78% rename from resources/templates/sidecar/django_url_extractor.py rename to resources/templates/sidecar/frameworks/django/django_url_extractor.py index 3ed2d90..7b53361 100644 --- a/resources/templates/sidecar/django_url_extractor.py +++ b/resources/templates/sidecar/frameworks/django/django_url_extractor.py @@ -20,10 +20,10 @@ def _extract_path_parameters(path: str) -> tuple[str, list[dict[str, object]]]: """ Extract path parameters from Django URL pattern. - Converts Django format (, ) to OpenAPI format ({pk}, {name}). + Converts Django format (, ) or regex groups to OpenAPI format ({pk}, {name}). Args: - path: Django URL pattern (e.g., 'notes//') + path: Django URL pattern (e.g., 'notes//' or r'^notes/(?P\\d+)/$') Returns: Tuple of (normalized_path, path_params) @@ -31,9 +31,9 @@ def _extract_path_parameters(path: str) -> tuple[str, list[dict[str, object]]]: path_params: list[dict[str, Any]] = [] normalized_path = path - # Django pattern: or - pattern = r"<(?:(?P\w+):)?(?P\w+)>" - matches = list(re.finditer(pattern, path)) + # Django 2.0+ pattern: or + django_pattern = r"<(?:(?P\w+):)?(?P\w+)>" + matches = list(re.finditer(django_pattern, path)) for match in matches: param_type = match.group("type") or "str" @@ -63,6 +63,24 @@ def _extract_path_parameters(path: str) -> tuple[str, list[dict[str, object]]]: # Replace with OpenAPI format normalized_path = normalized_path.replace(match.group(0), f"{{{param_name}}}") + # Django 1.x regex pattern: (?P...) + regex_pattern = r"\(\?P<(\w+)>[^)]+\)" + regex_matches = list(re.finditer(regex_pattern, normalized_path)) # Use normalized_path for subsequent matches + + for match in regex_matches: + param_name = match.group(1) + # Assume string type for regex-based path parameters + path_params.append( + { + "name": param_name, + "in": "path", + "required": True, + "schema": {"type": "string"}, + } + ) + # Replace with OpenAPI format + normalized_path = normalized_path.replace(match.group(0), f"{{{param_name}}}") + return normalized_path, path_params @@ -188,6 +206,16 @@ def extract_django_urls(repo_path: Path, urls_file: Path | None = None) -> list[ if isinstance(target, ast.Name) and target.id == "urlpatterns": if isinstance(node.value, ast.List): urlpatterns = node.value.elts + elif ( + isinstance(node.value, ast.Call) + and isinstance(node.value.func, ast.Name) + and node.value.func.id == "patterns" + and len(node.value.args) > 1 + ): + # Handle patterns('', ...) - Django 1.x style + # patterns() takes prefix as first arg, then URL patterns as remaining args + # All arguments after the first (prefix) are URL patterns + urlpatterns = node.value.args[1:] # Skip prefix, take rest break results: list[dict[str, object]] = [] @@ -196,7 +224,7 @@ def extract_django_urls(repo_path: Path, urls_file: Path | None = None) -> list[ if not isinstance(pattern_node, ast.Call): continue - # Check if it's path() or re_path() + # Check if it's path(), re_path(), or url() if isinstance(pattern_node.func, ast.Name): func_name = pattern_node.func.id elif isinstance(pattern_node.func, ast.Attribute): @@ -204,14 +232,17 @@ def extract_django_urls(repo_path: Path, urls_file: Path | None = None) -> list[ else: continue - if func_name not in ("path", "re_path"): + if func_name not in ("path", "re_path", "url"): # Added "url" continue - # Extract path pattern (first argument) - if not pattern_node.args: + # Extract path pattern + # path/re_path: args[0] = path pattern + # url: args[0] = regex pattern + path_arg_index = 0 # Same for all: first argument is the pattern + if len(pattern_node.args) <= path_arg_index: continue - path_arg = pattern_node.args[0] + path_arg = pattern_node.args[path_arg_index] if isinstance(path_arg, ast.Constant): path_pattern = path_arg.value elif hasattr(ast, "Str") and isinstance(path_arg, ast.Str): # Python < 3.8 @@ -222,13 +253,16 @@ def extract_django_urls(repo_path: Path, urls_file: Path | None = None) -> list[ if not isinstance(path_pattern, str): continue - # Extract view (second argument) + # Extract view + # path/re_path: args[1] = view + # url: args[1] = view view_ref = None - if len(pattern_node.args) > 1: - view_node = pattern_node.args[1] + view_arg_index = 1 # Same for all: second argument is the view + if len(pattern_node.args) > view_arg_index: + view_node = pattern_node.args[view_arg_index] view_ref = _resolve_view_reference(view_node, imports) - # Extract name (keyword argument or third positional) + # Extract name (keyword argument or third/fourth positional) pattern_name: str | None = None for kw in pattern_node.keywords: if kw.arg == "name" and isinstance(kw.value, ast.Constant): @@ -241,8 +275,8 @@ def extract_django_urls(repo_path: Path, urls_file: Path | None = None) -> list[ pattern_name = str_value if isinstance(str_value, str) else None break - if not pattern_name and len(pattern_node.args) > 2: - name_arg = pattern_node.args[2] + if not pattern_name and len(pattern_node.args) > (view_arg_index + 1): # Check for positional name arg + name_arg = pattern_node.args[view_arg_index + 1] if isinstance(name_arg, ast.Constant): constant_value = name_arg.value if isinstance(constant_value, str): diff --git a/resources/templates/sidecar/frameworks/drf/__init__.py b/resources/templates/sidecar/frameworks/drf/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/resources/templates/sidecar/frameworks/drf/drf_serializer_extractor.py b/resources/templates/sidecar/frameworks/drf/drf_serializer_extractor.py new file mode 100644 index 0000000..da6f11f --- /dev/null +++ b/resources/templates/sidecar/frameworks/drf/drf_serializer_extractor.py @@ -0,0 +1,372 @@ +#!/usr/bin/env python3 +# pyright: reportMissingImports=false, reportImplicitRelativeImport=false, reportArgumentType=false +""" +Django REST Framework serializer extractor for sidecar contract population. + +Extracts serializer field schemas from DRF serializer classes and converts them to OpenAPI format. +Similar to Pydantic model extraction but for DRF serializers. +""" + +from __future__ import annotations + +import ast +from pathlib import Path +from typing import TYPE_CHECKING, Any + + +if TYPE_CHECKING: + from typing import Any +else: + # Runtime: Allow Any for dynamic schema structures + Any = object # type: ignore[assignment, misc] + + +def _drf_field_to_openapi_type(field_class: str) -> dict[str, Any]: + """ + Convert DRF serializer field class to OpenAPI schema type. + + Args: + field_class: DRF field class name (e.g., 'CharField', 'EmailField', 'IntegerField') + + Returns: + OpenAPI schema dictionary + """ + field_lower = field_class.lower() + + # String types + if "char" in field_lower or "slug" in field_lower or "url" in field_lower: + return {"type": "string"} + if "email" in field_lower: + return {"type": "string", "format": "email"} + if "uuid" in field_lower: + return {"type": "string", "format": "uuid"} + if "ipaddress" in field_lower: + return {"type": "string", "format": "ipv4"} + if "filepath" in field_lower: + return {"type": "string", "format": "uri"} + if "file" in field_lower or "image" in field_lower: + return {"type": "string", "format": "binary"} + + # Numeric types + if "integer" in field_lower or "int" in field_lower: + return {"type": "integer"} + if "biginteger" in field_lower: + return {"type": "integer", "format": "int64"} + if "float" in field_lower or "decimal" in field_lower: + return {"type": "number", "format": "float"} + + # Boolean + if "boolean" in field_lower or "bool" in field_lower: + return {"type": "boolean"} + + # Date/time types + if "date" in field_lower: + return {"type": "string", "format": "date"} + if "time" in field_lower: + return {"type": "string", "format": "time"} + if "datetime" in field_lower: + return {"type": "string", "format": "date-time"} + if "duration" in field_lower: + return {"type": "string", "format": "duration"} + + # Complex types + if "json" in field_lower: + return {"type": "object"} # JSON object + if "dict" in field_lower: + return {"type": "object"} + if "list" in field_lower: + return {"type": "array", "items": {"type": "string"}} # Default to string items + + # Choice/select fields + if "choice" in field_lower: + return {"type": "string"} # enum will be added separately if available + + # Default to string + return {"type": "string"} + + +def _extract_field_constraints(field_node: ast.Call) -> dict[str, Any]: + """ + Extract validators and constraints from DRF serializer field. + + Args: + field_node: AST Call node for field instantiation (e.g., CharField(max_length=100)) + + Returns: + Dictionary with validation constraints + """ + constraints: dict[str, Any] = {} + + # Check keyword arguments for validators + for kw in field_node.keywords: + if kw.arg == "max_length" and isinstance(kw.value, ast.Constant): + max_len = kw.value.value + if isinstance(max_len, (int, float)): + constraints["maxLength"] = int(max_len) + elif kw.arg == "min_length" and isinstance(kw.value, ast.Constant): + min_len = kw.value.value + if isinstance(min_len, (int, float)): + constraints["minLength"] = int(min_len) + elif kw.arg == "required" and isinstance(kw.value, ast.Constant): + required_val = kw.value.value + if isinstance(required_val, bool) and required_val is False: + constraints["nullable"] = True + elif kw.arg == "allow_null" and isinstance(kw.value, ast.Constant): + allow_null_val = kw.value.value + if isinstance(allow_null_val, bool) and allow_null_val is True: + constraints["nullable"] = True + elif kw.arg == "allow_blank" and isinstance(kw.value, ast.Constant): + allow_blank_val = kw.value.value + if isinstance(allow_blank_val, bool) and allow_blank_val is True: + # Blank strings are allowed, but still required if required=True + pass + elif kw.arg == "choices" and isinstance(kw.value, (ast.List, ast.Tuple)): + # Extract enum values if available + enum_values: list[str] = [] + for elt in kw.value.elts if hasattr(kw.value, "elts") else []: + if isinstance(elt, (ast.Tuple, ast.List)) and len(elt.elts) >= 1: + first_val = elt.elts[0] + if isinstance(first_val, ast.Constant): + enum_val = first_val.value + if isinstance(enum_val, str): + enum_values.append(enum_val) + if enum_values: + constraints["enum"] = enum_values + elif kw.arg == "min_value" and isinstance(kw.value, ast.Constant): + min_val = kw.value.value + if isinstance(min_val, (int, float)): + constraints["minimum"] = min_val + elif kw.arg == "max_value" and isinstance(kw.value, ast.Constant): + max_val = kw.value.value + if isinstance(max_val, (int, float)): + constraints["maximum"] = max_val + + return constraints + + +def _is_drf_serializer(node: ast.ClassDef, tree: ast.AST) -> bool: + """ + Check if a class is a DRF serializer (BaseSerializer, Serializer, ModelSerializer, etc.). + + Args: + node: AST ClassDef node + tree: Full AST tree for checking parent classes + + Returns: + True if the class is a DRF serializer + """ + bases_to_check = list(node.bases) + checked_bases = set() + + while bases_to_check: + base = bases_to_check.pop(0) + + # Skip if already checked + base_name = None + if isinstance(base, ast.Name): + base_name = base.id + elif isinstance(base, ast.Attribute): + base_name = base.attr + + if base_name and base_name in checked_bases: + continue + if base_name: + checked_bases.add(base_name) + + # Check if it's a DRF serializer base class + if isinstance(base, ast.Name): + if base.id in ("BaseSerializer", "Serializer", "ModelSerializer"): + return True + # Check if parent class exists in the same file + for parent_node in ast.walk(tree): + if isinstance(parent_node, ast.ClassDef) and parent_node.name == base.id: + # Recursively check parent's bases + bases_to_check.extend(parent_node.bases) + break + elif isinstance(base, ast.Attribute): + if base.attr in ("BaseSerializer", "Serializer", "ModelSerializer"): + return True + + return False + + +def _extract_serializer_fields_from_ast(serializer_file: Path, serializer_class_name: str) -> dict[str, dict[str, Any]]: + """ + Extract serializer fields from AST. + + Args: + serializer_file: Path to serializer file + serializer_class_name: Name of serializer class + + Returns: + Dictionary mapping field names to OpenAPI schemas + """ + fields: dict[str, dict[str, Any]] = {} + + try: + with serializer_file.open("r", encoding="utf-8") as f: + content = f.read() + tree = ast.parse(content, filename=str(serializer_file)) + except (SyntaxError, UnicodeDecodeError): + return fields + + # Find the serializer class + serializer_node = None + for node in ast.walk(tree): + if isinstance(node, ast.ClassDef) and node.name == serializer_class_name and _is_drf_serializer(node, tree): + serializer_node = node + break + + if not serializer_node: + return fields + + # Extract fields from parent classes first (inheritance) + parent_classes = [] + for base in serializer_node.bases: + if isinstance(base, ast.Name): + parent_classes.append(base.id) + + # Extract parent class fields + for parent_name in parent_classes: + for parent_node in ast.walk(tree): + if isinstance(parent_node, ast.ClassDef) and parent_node.name == parent_name: + # Recursively extract from parent + for item in parent_node.body: + if isinstance(item, ast.Assign): + # Field assignment: field_name = CharField(...) or serializers.CharField(...) + for target in item.targets: + if isinstance(target, ast.Name): + field_name = target.id + # Only add if not already present (child overrides parent) + if field_name not in fields and isinstance(item.value, ast.Call): + # Extract field type from call + field_class = None + if isinstance(item.value.func, ast.Name): + # Direct: CharField(...) + field_class = item.value.func.id + elif isinstance(item.value.func, ast.Attribute): + # Attribute: serializers.CharField(...) + field_class = item.value.func.attr + + if field_class: + field_schema = _drf_field_to_openapi_type(field_class) + constraints = _extract_field_constraints(item.value) + field_schema.update(constraints) + fields[field_name] = field_schema + break + + # Extract fields from this class (overrides parent) + for item in serializer_node.body: + if isinstance(item, ast.Assign): + # Field assignment: field_name = CharField(...) or serializers.CharField(...) + for target in item.targets: + if isinstance(target, ast.Name): + field_name = target.id + if isinstance(item.value, ast.Call): + # Extract field type from call + field_class = None + if isinstance(item.value.func, ast.Name): + # Direct: CharField(...) + field_class = item.value.func.id + elif isinstance(item.value.func, ast.Attribute): + # Attribute: serializers.CharField(...) + field_class = item.value.func.attr + + if field_class: + field_schema = _drf_field_to_openapi_type(field_class) + constraints = _extract_field_constraints(item.value) + field_schema.update(constraints) + fields[field_name] = field_schema + elif isinstance(item.value, ast.Attribute): + # Nested serializer: field_name = AnotherSerializer() + # For now, treat as object + fields[field_name] = {"type": "object"} + + return fields + + +def extract_serializer_schema(repo_path: Path, serializer_module: str, serializer_class_name: str) -> dict[str, Any]: + """ + Extract OpenAPI schema from DRF serializer class. + + Args: + repo_path: Path to Django repository root + serializer_module: Module path (e.g., 'api.serializers') + serializer_class_name: Serializer class name (e.g., 'UserSerializer') + + Returns: + OpenAPI schema dictionary with properties and required fields + """ + # Convert module path to file path + module_parts = serializer_module.split(".") + serializer_file = repo_path + for part in module_parts: + serializer_file = serializer_file / part + serializer_file = serializer_file.with_suffix(".py") + + if not serializer_file.exists(): + # Try alternative locations + possible_paths = [ + repo_path / serializer_module.replace(".", "/") / "__init__.py", + repo_path / serializer_module.replace(".", "/") / "serializers.py", + ] + for path in possible_paths: + if path.exists(): + serializer_file = path + break + else: + return {"type": "object", "properties": {}, "required": []} + + # Extract fields + fields = _extract_serializer_fields_from_ast(serializer_file, serializer_class_name) + + # Build OpenAPI schema + properties: dict[str, dict[str, Any]] = {} + required: list[str] = [] + + for field_name, field_schema in fields.items(): + properties[field_name] = field_schema + # Assume all fields are required unless explicitly nullable or has default + if not field_schema.get("nullable", False) and "default" not in field_schema: + required.append(field_name) + + return { + "type": "object", + "properties": properties, + "required": required if required else [], + } + + +def main() -> int: + """Main entry point for DRF serializer extractor.""" + import argparse + import json + + parser = argparse.ArgumentParser(description="Extract DRF serializer schemas for contract population.") + _ = parser.add_argument("--repo", required=True, help="Path to Django repository") + _ = parser.add_argument("--serializer-module", required=True, help="Serializer module path (e.g., api.serializers)") + _ = parser.add_argument("--serializer-class", required=True, help="Serializer class name (e.g., UserSerializer)") + _ = parser.add_argument("--output", help="Output JSON file (default: stdout)") + args = parser.parse_args() + + # Use vars() to get dictionary for type checker + args_dict = vars(args) + repo_path = Path(str(args_dict["repo"])).resolve() + + schema = extract_serializer_schema( + repo_path, str(args_dict["serializer_module"]), str(args_dict["serializer_class"]) + ) + + output_json = json.dumps(schema, indent=2) + + output_path = args_dict.get("output") + if output_path: + _ = Path(str(output_path)).write_text(output_json, encoding="utf-8") + else: + print(output_json) + + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/resources/templates/sidecar/frameworks/fastapi/__init__.py b/resources/templates/sidecar/frameworks/fastapi/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/resources/templates/sidecar/frameworks/fastapi/fastapi_route_extractor.py b/resources/templates/sidecar/frameworks/fastapi/fastapi_route_extractor.py new file mode 100644 index 0000000..8745581 --- /dev/null +++ b/resources/templates/sidecar/frameworks/fastapi/fastapi_route_extractor.py @@ -0,0 +1,643 @@ +#!/usr/bin/env python3 +""" +FastAPI route extractor for sidecar contract population. + +Extracts route patterns from FastAPI route files and converts them to OpenAPI paths. +""" + +from __future__ import annotations + +import argparse +import ast +import json +import re +from pathlib import Path +from typing import Any + + +def _extract_path_parameters(path: str) -> tuple[str, list[dict[str, object]]]: + """ + Extract path parameters from FastAPI route path. + + Converts FastAPI format ({id}, {user_id}) to OpenAPI format and extracts parameters. + + Args: + path: FastAPI route path (e.g., '/items/{id}') + + Returns: + Tuple of (normalized_path, path_params) + """ + path_params: list[dict[str, Any]] = [] + normalized_path = path + + # FastAPI path parameter pattern: {param_name} or {param_name:type} + pattern = r"\{([^}:]+)(?::([^}]+))?\}" + matches = list(re.finditer(pattern, path)) + + for match in matches: + param_name = match.group(1) + param_type_hint = match.group(2) if match.group(2) else None + + # Convert type hint to OpenAPI type + type_map = { + "int": "integer", + "float": "number", + "str": "string", + "uuid": "string", + "path": "string", + } + openapi_type = type_map.get(param_type_hint.lower() if param_type_hint else "str", "string") + + path_params.append( + { + "name": param_name, + "in": "path", + "required": True, + "schema": {"type": openapi_type}, + } + ) + + # Path is already in OpenAPI format, no replacement needed + # But we track it for completeness + + return normalized_path, path_params + + +def _resolve_function_reference(func_node: ast.AST, imports: dict[str, str]) -> str | None: + """ + Resolve FastAPI function reference to a module path. + + Args: + func_node: AST node representing the function + imports: Dictionary of import aliases to module paths + + Returns: + Module path string (e.g., 'app.api.routes.items.read_item') or None + """ + if isinstance(func_node, ast.Name): + return func_node.id + return None + + +def _infer_http_method(func_name: str, decorator_attr: str | None = None) -> str: + """ + Infer HTTP method from function name or decorator. + + Args: + func_name: Name of the function + decorator_attr: Attribute name from decorator (e.g., 'get', 'post') + + Returns: + HTTP method (default: 'GET') + """ + if decorator_attr: + return decorator_attr.upper() + + func_lower = func_name.lower() + + # Common patterns + if any(keyword in func_lower for keyword in ["create", "add", "new", "register", "login"]): + return "POST" + if any(keyword in func_lower for keyword in ["update", "edit", "change", "patch"]): + return "PATCH" + if any(keyword in func_lower for keyword in ["put", "replace"]): + return "PUT" + if any(keyword in func_lower for keyword in ["delete", "remove"]): + return "DELETE" + if any(keyword in func_lower for keyword in ["list", "read", "get", "fetch"]): + return "GET" + + return "GET" + + +def _extract_field_constraints(field_value: ast.expr) -> dict[str, Any]: + """ + Extract Field constraints from Pydantic Field() call. + + Args: + field_value: AST node representing Field() call + + Returns: + Dictionary with constraints (minLength, maxLength, format, etc.) + """ + constraints: dict[str, Any] = {} + + if isinstance(field_value, ast.Call) and isinstance(field_value.func, ast.Name) and field_value.func.id == "Field": + # Check if it's a Field() call + for kw in field_value.keywords: + if kw.arg == "min_length" and isinstance(kw.value, ast.Constant): + constraints["minLength"] = kw.value.value + elif kw.arg == "max_length" and isinstance(kw.value, ast.Constant): + constraints["maxLength"] = kw.value.value + elif kw.arg == "format" and isinstance(kw.value, ast.Constant): + constraints["format"] = kw.value.value + elif (kw.arg == "default" and isinstance(kw.value, ast.Constant)) or ( + kw.arg == "default" and isinstance(kw.value, ast.NameConstant) + ): + constraints["default"] = kw.value.value + elif kw.arg == "default" and isinstance(kw.value, ast.Name) and kw.value.id == "None": + constraints["nullable"] = True + + return constraints + + +def _extract_type_hint_schema(type_node: ast.expr | None) -> dict[str, Any]: + """ + Extract OpenAPI schema from AST type hint. + + Args: + type_node: AST node representing type hint + + Returns: + OpenAPI schema dictionary + """ + if type_node is None: + return {"type": "object"} + + # Handle basic types + if isinstance(type_node, ast.Name): + type_name = type_node.id + # Check for Pydantic special types first + if type_name == "EmailStr": + return {"type": "string", "format": "email"} + if type_name == "UUID" or type_name == "uuid": + return {"type": "string", "format": "uuid"} + # Then check basic types + type_map = { + "str": "string", + "int": "integer", + "float": "number", + "bool": "boolean", + "dict": "object", + "list": "array", + "Any": "object", + } + if type_name in type_map: + return {"type": type_map[type_name]} + # Pydantic model reference - will be resolved later + return {"type": "object", "x-model-name": type_name} + + # Handle Python 3.10+ union syntax: str | None (ast.BinOp with BitOr) + if isinstance(type_node, ast.BinOp) and isinstance(type_node.op, ast.BitOr): + # Handle union types like str | None, EmailStr | None + # Extract the first type (left side) and mark as nullable + schema = _extract_type_hint_schema(type_node.left) + schema["nullable"] = True + return schema + + # Handle Optional/Union types (old syntax) + if isinstance(type_node, ast.Subscript) and isinstance(type_node.value, ast.Name): + if type_node.value.id in ("Optional", "Union"): + # Extract the first type from Optional/Union + if isinstance(type_node.slice, ast.Tuple) and type_node.slice.elts: + schema = _extract_type_hint_schema(type_node.slice.elts[0]) + schema["nullable"] = True + return schema + if isinstance(type_node.slice, ast.Name): + schema = _extract_type_hint_schema(type_node.slice) + schema["nullable"] = True + return schema + elif type_node.value.id == "list": + # Handle List[Type] + if isinstance(type_node.slice, ast.Name): + item_schema = _extract_type_hint_schema(type_node.slice) + return {"type": "array", "items": item_schema} + + # Handle EmailStr, UUID, etc. (from pydantic) + if isinstance(type_node, ast.Name): + if type_node.id == "EmailStr": + return {"type": "string", "format": "email"} + if type_node.id == "UUID" or type_node.id == "uuid": + return {"type": "string", "format": "uuid"} + + # Handle Optional[EmailStr] etc. + if ( + isinstance(type_node, ast.Subscript) + and isinstance(type_node.value, ast.Name) + and type_node.value.id in ("Optional", "Union") + ): + inner_type = None + if isinstance(type_node.slice, ast.Tuple) and type_node.slice.elts: + inner_type = type_node.slice.elts[0] + elif isinstance(type_node.slice, ast.Name): + inner_type = type_node.slice + if inner_type and isinstance(inner_type, ast.Name): + if inner_type.id == "EmailStr": + return {"type": "string", "format": "email", "nullable": True} + if inner_type.id == "UUID" or inner_type.id == "uuid": + return {"type": "string", "format": "uuid", "nullable": True} + + return {"type": "object"} + + +def _extract_pydantic_model_schema(repo_path: Path, model_name: str, imports: dict[str, str]) -> dict[str, Any] | None: + """ + Extract OpenAPI schema from a Pydantic model class definition. + + Args: + repo_path: Path to repository root + model_name: Name of the Pydantic model class + imports: Dictionary of import aliases to module paths + + Returns: + OpenAPI schema dictionary or None if model not found + """ + # Try to find the model in common locations + model_file_candidates = [ + repo_path / "backend" / "app" / "models.py", + repo_path / "app" / "models.py", + repo_path / "models.py", + ] + + # Also check if model is imported from a specific module + if model_name in imports: + import_path = imports[model_name] + module_parts = import_path.split(".") + model_file = repo_path + for part in module_parts[:-1]: # Exclude the class name + model_file = model_file / part + model_file = model_file.with_suffix(".py") + if model_file.exists(): + model_file_candidates.insert(0, model_file) + + for model_file in model_file_candidates: + if not model_file.exists(): + continue + + try: + with model_file.open("r", encoding="utf-8") as f: + content = f.read() + tree = ast.parse(content, filename=str(model_file)) + except (SyntaxError, UnicodeDecodeError): + continue + + # Find the model class + for node in ast.walk(tree): + if isinstance(node, ast.ClassDef) and node.name == model_name: + # Check if it's a Pydantic model (BaseModel, SQLModel, etc.) + # Check direct inheritance and also check parent classes recursively + is_pydantic = False + bases_to_check = list(node.bases) + checked_bases = set() + + while bases_to_check: + base = bases_to_check.pop(0) + + # Skip if already checked + base_name = None + if isinstance(base, ast.Name): + base_name = base.id + elif isinstance(base, ast.Attribute): + base_name = base.attr + + if base_name and base_name in checked_bases: + continue + if base_name: + checked_bases.add(base_name) + + # Check if it's a Pydantic base class + if isinstance(base, ast.Name): + if base.id in ("BaseModel", "SQLModel"): + is_pydantic = True + break + # Check if parent class exists in the same file + for parent_node in ast.walk(tree): + if isinstance(parent_node, ast.ClassDef) and parent_node.name == base.id: + # Recursively check parent's bases + bases_to_check.extend(parent_node.bases) + break + elif isinstance(base, ast.Attribute): + if base.attr in ("BaseModel", "SQLModel"): + is_pydantic = True + break + + if not is_pydantic: + continue + + # Extract schema + schema: dict[str, Any] = { + "type": "object", + "properties": {}, + "required": [], + } + + # Extract docstring + docstring = ast.get_docstring(node) + if docstring: + schema["description"] = docstring + + # Extract fields from parent classes first (inheritance) + parent_classes = [] + for base in node.bases: + if isinstance(base, ast.Name): + parent_classes.append(base.id) + + # Extract parent class fields + for parent_name in parent_classes: + for parent_node in ast.walk(tree): + if isinstance(parent_node, ast.ClassDef) and parent_node.name == parent_name: + # Recursively extract from parent + for item in parent_node.body: + if ( + isinstance(item, ast.AnnAssign) + and item.target + and isinstance(item.target, ast.Name) + ): + field_name = item.target.id + # Only add if not already present (child overrides parent) + if field_name not in schema["properties"]: + field_schema = _extract_type_hint_schema(item.annotation) + if item.value: + constraints = _extract_field_constraints(item.value) + field_schema.update(constraints) + schema["properties"][field_name] = field_schema + # Check if required + if item.value is None: + if field_name not in schema["required"]: + schema["required"].append(field_name) + elif ( + isinstance(item.value, ast.Name) + and item.value.id == "None" + and "nullable" not in field_schema + ): + field_schema["nullable"] = True + break + + # Extract fields from this class (overrides parent) + for item in node.body: + if isinstance(item, ast.AnnAssign) and item.target and isinstance(item.target, ast.Name): + field_name = item.target.id + field_schema = _extract_type_hint_schema(item.annotation) + + # Extract Field constraints + if item.value: + constraints = _extract_field_constraints(item.value) + field_schema.update(constraints) + + schema["properties"][field_name] = field_schema + + # Check if required (no default value) + if item.value is None: + schema["required"].append(field_name) + elif isinstance(item.value, ast.Name) and item.value.id == "None": + # Optional field + if "nullable" not in field_schema: + field_schema["nullable"] = True + elif ( + isinstance(item.value, ast.Call) + and "default" not in field_schema + and "nullable" not in field_schema + ): + # Field() call - check for default + # No default means required + schema["required"].append(field_name) + + return schema + + return None + + +def _extract_request_body_model(func_node: ast.FunctionDef, imports: dict[str, str]) -> str | None: + """ + Extract request body model name from FastAPI route function parameters. + + Args: + func_node: AST FunctionDef node + imports: Dictionary of import aliases to module paths + + Returns: + Model name (e.g., 'UserCreate') or None + """ + # FastAPI convention: first parameter without default is request body for POST/PUT/PATCH + # Skip special parameters: session, current_user, etc. + skip_params = {"session", "current_user", "db", "request", "response", "skip", "limit"} + + # Check regular args + for arg in func_node.args.args: + if arg.arg in skip_params: + continue + + # Check if it has a type annotation (Pydantic model) + if arg.annotation: + # Extract model name from type annotation + if isinstance(arg.annotation, ast.Name): + return arg.annotation.id + if ( + isinstance(arg.annotation, ast.Subscript) + and isinstance(arg.annotation.value, ast.Name) + and arg.annotation.value.id in ("Optional", "Union") + ): + # Handle Optional[Model] or Union[Model, None] + if isinstance(arg.annotation.slice, ast.Tuple) and arg.annotation.slice.elts: + first_type = arg.annotation.slice.elts[0] + if isinstance(first_type, ast.Name): + return first_type.id + elif isinstance(arg.annotation.slice, ast.Name): + return arg.annotation.slice.id + + # Check keyword-only args (FastAPI often uses * to separate path/query params from body) + for arg in func_node.args.kwonlyargs: + if arg.arg in skip_params: + continue + + # Check if it has a type annotation (Pydantic model) + if arg.annotation: + # Extract model name from type annotation + if isinstance(arg.annotation, ast.Name): + return arg.annotation.id + if ( + isinstance(arg.annotation, ast.Subscript) + and isinstance(arg.annotation.value, ast.Name) + and arg.annotation.value.id in ("Optional", "Union") + ): + # Handle Optional[Model] or Union[Model, None] + if isinstance(arg.annotation.slice, ast.Tuple) and arg.annotation.slice.elts: + first_type = arg.annotation.slice.elts[0] + if isinstance(first_type, ast.Name): + return first_type.id + elif isinstance(arg.annotation.slice, ast.Name): + return arg.annotation.slice.id + + return None + + +def extract_fastapi_routes(repo_path: Path, routes_dir: Path | None = None) -> list[dict[str, object]]: + """ + Extract route patterns from FastAPI route files. + + Args: + repo_path: Path to FastAPI repository root + routes_dir: Path to routes directory (default: find automatically) + + Returns: + List of route pattern dictionaries with path, method, function, etc. + """ + if routes_dir is None: + # Try to find routes directory + candidates = [ + repo_path / "backend" / "app" / "api" / "routes", + repo_path / "app" / "api" / "routes", + repo_path / "api" / "routes", + repo_path / "routes", + ] + for candidate in candidates: + if candidate.exists(): + routes_dir = candidate + break + + if routes_dir is None: + # Search for route files + route_files = list(repo_path.rglob("**/routes/*.py")) + if route_files: + routes_dir = route_files[0].parent + + if routes_dir is None or not routes_dir.exists(): + return [] + + results: list[dict[str, object]] = [] + + # Process each route file + for route_file in routes_dir.glob("*.py"): + if route_file.name == "__init__.py": + continue + + with route_file.open("r", encoding="utf-8") as f: + content = f.read() + + try: + tree = ast.parse(content, filename=str(route_file)) + except SyntaxError: + continue + + # Extract imports + imports: dict[str, str] = {} + for node in ast.walk(tree): + if isinstance(node, ast.ImportFrom): + module = node.module or "" + for alias in node.names: + alias_name = alias.asname or alias.name + imports[alias_name] = f"{module}.{alias.name}" + elif isinstance(node, ast.Import): + for alias in node.names: + alias_name = alias.asname or alias.name + imports[alias_name] = alias.name + + # Find router variable (usually 'router = APIRouter(...)') + router_prefix = "" + for node in ast.walk(tree): + if isinstance(node, ast.Assign): + for target in node.targets: + if isinstance(target, ast.Name) and target.id == "router" and isinstance(node.value, ast.Call): + # Extract prefix from APIRouter(prefix="...") + for kw in node.value.keywords: + if kw.arg == "prefix" and isinstance(kw.value, ast.Constant): + prefix_value = kw.value.value + if isinstance(prefix_value, str): + router_prefix = prefix_value + break + if kw.arg == "prefix" and hasattr(ast, "Str") and isinstance(kw.value, ast.Str): + str_value = kw.value.s # type: ignore[attr-defined, deprecated] + if isinstance(str_value, str): + router_prefix = str_value + break + + # Find route decorators (@router.get, @router.post, etc.) + for node in ast.walk(tree): + if isinstance(node, ast.FunctionDef): + for decorator in node.decorator_list: + # Check for @router.METHOD patterns + if ( + isinstance(decorator, ast.Call) + and isinstance(decorator.func, ast.Attribute) + and isinstance(decorator.func.value, ast.Name) + and decorator.func.value.id == "router" + ): + method = decorator.func.attr.upper() # get -> GET + + # Extract path from decorator arguments + path = "/" + if decorator.args: + path_arg = decorator.args[0] + if isinstance(path_arg, ast.Constant): + path = path_arg.value + elif hasattr(ast, "Str") and isinstance(path_arg, ast.Str): + path = path_arg.s # type: ignore[attr-defined, deprecated] + + if not isinstance(path, str): + continue + + # Combine router prefix with path + full_path = (router_prefix + path) if router_prefix and isinstance(router_prefix, str) else path + if not full_path.startswith("/"): + full_path = "/" + full_path + + # Normalize path and extract parameters + normalized_path, path_params = _extract_path_parameters(full_path) + + # Extract operation_id from function name + operation_id = node.name + + # Extract response_model if present + response_model: str | None = None + for kw in decorator.keywords: + if kw.arg == "response_model": + if isinstance(kw.value, ast.Name): + response_model = kw.value.id + elif isinstance(kw.value, ast.Attribute): + response_model = kw.value.attr + + # Extract request body model from function parameters + request_body_model = _extract_request_body_model(node, imports) + request_body_schema: dict[str, Any] | None = None + if request_body_model: + request_body_schema = _extract_pydantic_model_schema(repo_path, request_body_model, imports) + + # Build function reference + module_path = str(route_file.relative_to(repo_path)).replace("/", ".").replace(".py", "") + func_ref = f"{module_path}.{node.name}" + + route_data: dict[str, Any] = { + "path": normalized_path, + "method": method, + "function": func_ref, + "operation_id": operation_id, + "path_params": path_params, + "original_path": full_path, + "response_model": response_model, + } + + # Add request body schema if extracted + if request_body_schema: + route_data["request_body_schema"] = request_body_schema + route_data["request_body_model"] = request_body_model + + results.append(route_data) + + return results + + +def main() -> int: + """Main entry point for FastAPI route extractor.""" + parser = argparse.ArgumentParser(description="Extract FastAPI routes for contract population.") + parser.add_argument("--repo", required=True, help="Path to FastAPI repository") + parser.add_argument("--routes", help="Path to routes directory (auto-detected if not provided)") + parser.add_argument("--output", help="Output JSON file (default: stdout)") + args = parser.parse_args() + + repo_path = Path(str(args.repo)).resolve() # type: ignore[arg-type] + routes_dir = Path(str(args.routes)).resolve() if args.routes else None # type: ignore[arg-type] + + results = extract_fastapi_routes(repo_path, routes_dir) + + output_json = json.dumps(results, indent=2, sort_keys=True) + + if args.output: + Path(str(args.output)).write_text(output_json, encoding="utf-8") # type: ignore[arg-type] + else: + print(output_json) + + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/resources/templates/sidecar/populate_contracts.py b/resources/templates/sidecar/populate_contracts.py deleted file mode 100644 index b00b953..0000000 --- a/resources/templates/sidecar/populate_contracts.py +++ /dev/null @@ -1,543 +0,0 @@ -#!/usr/bin/env python3 -# pyright: reportMissingImports=false, reportImplicitRelativeImport=false -""" -Populate OpenAPI contract stubs with Django URL patterns. - -Reads Django URL patterns and populates existing OpenAPI contract files. - -Note: This is a template file that gets copied to the sidecar workspace. -The imports work at runtime when the file is in the sidecar directory. -""" - -from __future__ import annotations - -import argparse -import sys -from pathlib import Path -from typing import TYPE_CHECKING, cast - -import yaml - - -# Type stubs for template file imports -# These are template files that get copied to sidecar workspace where imports work at runtime -if TYPE_CHECKING: - - def extract_django_urls(repo_path: Path, urls_file: Path | None = None) -> list[dict[str, object]]: ... - def extract_view_form_schema(repo_path: Path, view_module: str, view_function: str) -> dict[str, object] | None: ... - - -# Import from same directory (sidecar templates) -# These scripts are run directly, so we need to handle imports differently -# Add current directory to path for direct import when run as script -_script_dir = Path(__file__).parent -if str(_script_dir) not in sys.path: - sys.path.insert(0, str(_script_dir)) - -# These imports work at runtime when scripts are run directly from sidecar directory -# Type checker uses TYPE_CHECKING stubs above; runtime uses actual imports below -# The sidecar directory has __init__.py, making it a package, so relative imports work at runtime -try: - # Try explicit relative imports first (preferred for type checking) - # These work when the sidecar directory is a proper package (has __init__.py) - from .django_form_extractor import ( # type: ignore[reportMissingImports] - extract_view_form_schema, - ) - from .django_url_extractor import extract_django_urls # type: ignore[reportMissingImports] -except ImportError: - # Fallback for when run as script (runtime path manipulation case) - # This happens when the script is executed directly from the sidecar workspace - # and sys.path manipulation makes absolute imports work - from django_form_extractor import ( # type: ignore[reportMissingImports] - extract_view_form_schema, - ) - from django_url_extractor import ( - extract_django_urls, # type: ignore[reportImplicitRelativeImport, reportMissingImports] - ) - - -def _match_url_to_feature(url_pattern: dict[str, object], feature_key: str) -> bool: - """ - Match URL pattern to feature by operation_id or view name. - - Args: - url_pattern: URL pattern dictionary from extractor - feature_key: Feature key (e.g., 'FEATURE-USER-AUTHENTICATION') - - Returns: - True if pattern matches feature - """ - operation_id = str(url_pattern.get("operation_id", "")).lower() - view = str(url_pattern.get("view", "")).lower() - feature_lower = feature_key.lower().replace("feature-", "").replace("-", "_") - - # Check if operation_id or view contains feature keywords - keywords = feature_lower.split("_") - return any(keyword and (keyword in operation_id or keyword in view) for keyword in keywords) - - -def _create_openapi_operation( - url_pattern: dict[str, object], - repo_path: Path, - form_schema: dict[str, object] | None = None, -) -> dict[str, object]: - """ - Create OpenAPI operation from Django URL pattern. - - Args: - url_pattern: URL pattern dictionary from extractor - repo_path: Path to Django repository (for form extraction) - form_schema: Optional pre-extracted form schema - - Returns: - OpenAPI operation dictionary - """ - method = str(url_pattern["method"]).lower() - path = str(url_pattern["path"]) - operation_id = str(url_pattern["operation_id"]) - path_params = url_pattern.get("path_params", []) - if not isinstance(path_params, list): - path_params = [] - view_ref = url_pattern.get("view") - - operation: dict[str, object] = { - "operationId": operation_id, - "summary": f"{method.upper()} {path}", - "responses": { - "200": {"description": "Success"}, - "400": {"description": "Bad request"}, - "500": {"description": "Internal server error"}, - }, - } - - # Add path parameters - if path_params: - operation["parameters"] = path_params - - # Add request body for POST/PUT/PATCH - if method in ("post", "put", "patch"): - # Try to extract form schema from view - schema: dict[str, object] | None = form_schema - if schema is None and view_ref: - # Try to extract from view function - view_str = str(view_ref) - if "." in view_str: - parts = view_str.split(".") - if len(parts) >= 2: - view_module = ".".join(parts[:-1]) - view_function = parts[-1] - schema = extract_view_form_schema(repo_path, view_module, view_function) - - # Special case: login view doesn't use a form - if schema is None and "login" in operation_id.lower(): - schema = { - "type": "object", - "properties": { - "username": {"type": "string", "minLength": 1}, - "password": {"type": "string", "minLength": 1}, - }, - "required": ["username", "password"], - } - - # Use extracted schema or default empty schema - if schema is None: - schema = {"type": "object", "properties": {}, "required": []} - - operation["requestBody"] = { - "required": True, - "content": { - "application/x-www-form-urlencoded": { - "schema": schema, - } - }, - } - - return operation # type: ignore[return-value] - - -def _get_common_schemas() -> dict[str, dict[str, object]]: - """ - Get common schema definitions for OpenAPI contracts. - - Returns: - Dictionary of schema name to schema definition - """ - return { - "Path": { - "type": "string", - "description": "File system path", - "example": "/path/to/file.py", - }, - "PlanBundle": { - "type": "object", - "description": "Plan bundle containing features, stories, and product definition", - "properties": { - "version": {"type": "string", "example": "1.0"}, - "idea": { - "type": "object", - "properties": { - "title": {"type": "string"}, - "narrative": {"type": "string"}, - }, - }, - "product": { - "type": "object", - "properties": { - "themes": {"type": "array", "items": {"type": "string"}}, - }, - }, - "features": { - "type": "array", - "items": { - "type": "object", - "properties": { - "key": {"type": "string"}, - "title": {"type": "string"}, - "stories": {"type": "array", "items": {"type": "object"}}, - }, - }, - }, - }, - }, - "FileSystemEvent": { - "type": "object", - "description": "File system event (created, modified, deleted)", - "properties": { - "path": {"type": "string"}, - "event_type": {"type": "string", "enum": ["created", "modified", "deleted"]}, - "timestamp": {"type": "string", "format": "date-time"}, - }, - }, - "SyncResult": { - "type": "object", - "description": "Synchronization result", - "properties": { - "success": {"type": "boolean"}, - "message": {"type": "string"}, - "changes": {"type": "array", "items": {"type": "object"}}, - }, - }, - "RepositorySyncResult": { - "type": "object", - "description": "Repository synchronization result", - "properties": { - "success": {"type": "boolean"}, - "synced_files": {"type": "array", "items": {"type": "string"}}, - "conflicts": {"type": "array", "items": {"type": "object"}}, - }, - }, - } - - -def _resolve_schema_refs(contract: dict[str, object]) -> dict[str, object]: - """ - Resolve schema references and add missing schema definitions. - - Args: - contract: OpenAPI contract dictionary - - Returns: - Updated contract with resolved schemas - """ - # Get common schemas - common_schemas = _get_common_schemas() - - # Ensure components.schemas exists - components = contract.get("components", {}) - if not isinstance(components, dict): - components = {} - contract["components"] = components - - schemas = components.get("schemas", {}) - if not isinstance(schemas, dict): - schemas = {} - components["schemas"] = schemas - - # Find all $ref references in the contract - def find_refs(obj: object, refs: set[str]) -> None: - """Recursively find all $ref references.""" - if isinstance(obj, dict): - if "$ref" in obj: - ref = str(obj["$ref"]) - if ref.startswith("#/components/schemas/"): - schema_name = ref.split("/")[-1] - refs.add(schema_name) - for value in obj.values(): - find_refs(value, refs) - elif isinstance(obj, list): - for item in obj: - find_refs(item, refs) - - refs: set[str] = set() - find_refs(contract, refs) - - # Add missing schema definitions - for ref in refs: - if ref not in schemas and ref in common_schemas: - schemas[ref] = common_schemas[ref] - elif ref in schemas and ref in common_schemas: - # Fix incorrect schema definitions (hotpatch for PlanBundle schema bug) - # If schema exists but has incorrect structure, replace with correct one - existing_schema = schemas[ref] - correct_schema = common_schemas[ref] - - # Special case: Fix PlanBundle.themes schema bug (array of objects -> array of strings) - if ref == "PlanBundle" and isinstance(existing_schema, dict) and isinstance(correct_schema, dict): - existing_props = existing_schema.get("properties", {}) - if not isinstance(existing_props, dict): - existing_props = {} - correct_props = correct_schema.get("properties", {}) - if not isinstance(correct_props, dict): - correct_props = {} - - # Check if themes schema is incorrect - existing_product = existing_props.get("product", {}) - if not isinstance(existing_product, dict): - existing_product = {} - existing_product_props = existing_product.get("properties", {}) - if not isinstance(existing_product_props, dict): - existing_product_props = {} - existing_themes = existing_product_props.get("themes", {}) - - correct_product = correct_props.get("product", {}) - if not isinstance(correct_product, dict): - correct_product = {} - correct_product_props = correct_product.get("properties", {}) - if not isinstance(correct_product_props, dict): - correct_product_props = {} - correct_themes = correct_product_props.get("themes", {}) - - if ( - isinstance(existing_themes, dict) - and isinstance(correct_themes, dict) - and existing_themes.get("items", {}).get("type") == "object" - and correct_themes.get("items", {}).get("type") == "string" - ): - # Fix the themes schema - if "product" not in existing_props: - existing_props["product"] = {} - if "properties" not in existing_props["product"]: - existing_props["product"]["properties"] = {} - existing_props["product"]["properties"]["themes"] = correct_themes - - return contract - - -def populate_contracts( - contracts_dir: Path, repo_path: Path, urls_file: Path | None = None, extract_forms: bool = True -) -> dict[str, int]: - """ - Populate OpenAPI contract stubs with Django URL patterns. - - Args: - contracts_dir: Directory containing *.openapi.yaml files - repo_path: Path to Django repository - urls_file: Path to urls.py file (auto-detected if not provided) - - Returns: - Dictionary with statistics (populated, skipped, errors) - """ - # Extract Django URL patterns - url_patterns = extract_django_urls(repo_path, urls_file) - - if not url_patterns: - return {"populated": 0, "skipped": 0, "errors": 0} - - # Find all contract files - contract_files = list(contracts_dir.glob("*.openapi.yaml")) - - stats = {"populated": 0, "skipped": 0, "errors": 0} - - for contract_file in contract_files: - try: - # Load contract - with contract_file.open("r", encoding="utf-8") as f: - contract_data = yaml.safe_load(f) # type: ignore[assignment] - if not isinstance(contract_data, dict): - contract_data = {} - contract = cast(dict[str, object], contract_data) - - if "paths" not in contract: - contract["paths"] = {} - - # Extract feature key from filename - feature_key = contract_file.stem.replace(".openapi", "").upper() - - # Find matching URL patterns - matching_patterns = [p for p in url_patterns if _match_url_to_feature(p, feature_key)] - - if not matching_patterns: - stats["skipped"] += 1 - continue - - # Populate paths - for pattern in matching_patterns: - path = str(pattern["path"]) - method = str(pattern["method"]).lower() - - paths_dict = contract.get("paths", {}) - if not isinstance(paths_dict, dict): - paths_dict = {} - contract["paths"] = paths_dict - if path not in paths_dict: - paths_dict[path] = {} # type: ignore[assignment] - - # Extract form schema if enabled - form_schema: dict[str, object] | None = None - if extract_forms: - view_ref = pattern.get("view") - if view_ref: - view_str = str(view_ref) - if "." in view_str: - parts = view_str.split(".") - if len(parts) >= 2: - view_module = ".".join(parts[:-1]) - view_function = parts[-1] - form_schema = extract_view_form_schema(repo_path, view_module, view_function) - - operation = _create_openapi_operation(pattern, repo_path, form_schema) # type: ignore[arg-type] - if isinstance(paths_dict, dict) and isinstance(paths_dict.get(path), dict): - paths_dict[path][method] = operation # type: ignore[assignment, index] - - # Resolve schema references and add missing schemas - contract = _resolve_schema_refs(contract) - - # Save updated contract - with contract_file.open("w", encoding="utf-8") as f: - yaml.dump(contract, f, default_flow_style=False, sort_keys=False, allow_unicode=True) - - stats["populated"] += 1 - - except Exception as e: - print(f"Error processing {contract_file}: {e}") - stats["errors"] += 1 - - return stats - - -def resolve_schema_refs_in_contracts(contracts_dir: Path) -> dict[str, int]: - """ - Resolve schema references in all OpenAPI contracts. - - This function adds missing schema definitions for common types like Path, PlanBundle, etc. - It can be used for any project type (not just Django). - - Args: - contracts_dir: Directory containing *.openapi.yaml files - - Returns: - Dictionary with statistics (resolved, skipped, errors) - """ - contract_files = list(contracts_dir.glob("*.openapi.yaml")) - stats = {"resolved": 0, "skipped": 0, "errors": 0} - - for contract_file in contract_files: - try: - # Load contract - with contract_file.open("r", encoding="utf-8") as f: - contract_data = yaml.safe_load(f) # type: ignore[assignment] - if not isinstance(contract_data, dict): - contract_data = {} - contract = cast(dict[str, object], contract_data) - - # Resolve schema references - # Get original schemas BEFORE resolving (make a copy since _resolve_schema_refs modifies in place) - import json - - components = contract.get("components") - original_schemas: dict[str, object] = {} - original_schemas_str = "" - if isinstance(components, dict): - schemas = components.get("schemas") - if isinstance(schemas, dict): - original_schemas = schemas.copy() # Make a copy to avoid reference issues - # Also serialize to string for comparison (to detect schema fixes, not just additions) - original_schemas_str = json.dumps(original_schemas, sort_keys=True) - - contract = _resolve_schema_refs(contract) - - new_schemas: dict[str, object] = {} - components_after = contract.get("components") - if isinstance(components_after, dict): - schemas_after = components_after.get("schemas") - if isinstance(schemas_after, dict): - new_schemas = schemas_after - - # Check if schemas were added OR fixed (hotpatch for PlanBundle schema bug) - schemas_changed = False - if len(new_schemas) > len(original_schemas): - schemas_changed = True - elif len(new_schemas) == len(original_schemas) and len(original_schemas) > 0 and original_schemas_str: - # Check if any schemas were modified (e.g., PlanBundle.themes fix) - new_schemas_str = json.dumps(new_schemas, sort_keys=True) - if new_schemas_str != original_schemas_str: - schemas_changed = True - - if schemas_changed: - # Save updated contract - with contract_file.open("w", encoding="utf-8") as f: - yaml.dump(contract, f, default_flow_style=False, sort_keys=False, allow_unicode=True) - stats["resolved"] += 1 - else: - stats["skipped"] += 1 - - except Exception as e: - print(f"Error processing {contract_file}: {e}") - stats["errors"] += 1 - - return stats - - -def main() -> int: - """Main entry point for contract population.""" - parser = argparse.ArgumentParser( - description="Populate OpenAPI contracts with Django URL patterns or resolve schema references." - ) - parser.add_argument("--contracts", required=True, help="Contracts directory containing *.openapi.yaml files") - parser.add_argument("--repo", help="Path to Django repository (required for URL population)") - parser.add_argument("--urls", help="Path to urls.py file (auto-detected if not provided)") - parser.add_argument( - "--resolve-schemas-only", action="store_true", help="Only resolve schema references, don't populate URLs" - ) - args = parser.parse_args() - - contracts_dir = Path(str(args.contracts)).resolve() # type: ignore[arg-type] - - if not contracts_dir.exists(): - print(f"Error: Contracts directory not found: {contracts_dir}") - return 1 - - # If --resolve-schemas-only, just resolve schema references - if args.resolve_schemas_only: - stats = resolve_schema_refs_in_contracts(contracts_dir) - print(f"Resolved: {stats['resolved']}, Skipped: {stats['skipped']}, Errors: {stats['errors']}") - return 0 if stats["errors"] == 0 else 1 - - # Otherwise, do Django URL population (requires --repo) - if not args.repo: - print("Error: --repo is required for URL population (or use --resolve-schemas-only)") - return 1 - - repo_path = Path(str(args.repo)).resolve() # type: ignore[arg-type] - urls_file = Path(str(args.urls)).resolve() if args.urls else None # type: ignore[arg-type] - - if not repo_path.exists(): - print(f"Error: Repository path not found: {repo_path}") - return 1 - - # Populate URLs and resolve schemas - stats = populate_contracts(contracts_dir, repo_path, urls_file) - - # Also resolve schema references after population - schema_stats = resolve_schema_refs_in_contracts(contracts_dir) - stats["schema_resolved"] = schema_stats["resolved"] - - print( - f"Populated: {stats['populated']}, Skipped: {stats['skipped']}, Errors: {stats['errors']}, Schemas resolved: {stats.get('schema_resolved', 0)}" - ) - - return 0 if stats["errors"] == 0 else 1 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/setup.py b/setup.py index b89997c..1f75785 100644 --- a/setup.py +++ b/setup.py @@ -7,8 +7,8 @@ if __name__ == "__main__": _setup = setup( name="specfact-cli", - version="0.22.1", - description="SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development", + version="0.23.0", + description="SpecFact CLI - Spec -> Contract -> Sentinel tool for contract-driven development", packages=find_packages(where="src"), package_dir={"": "src"}, install_requires=[ diff --git a/src/__init__.py b/src/__init__.py index 73ce42b..cda2551 100644 --- a/src/__init__.py +++ b/src/__init__.py @@ -3,4 +3,4 @@ """ # Define the package version (kept in sync with pyproject.toml and setup.py) -__version__ = "0.22.1" +__version__ = "0.23.0" diff --git a/src/specfact_cli/__init__.py b/src/specfact_cli/__init__.py index 1da476b..fe1ea48 100644 --- a/src/specfact_cli/__init__.py +++ b/src/specfact_cli/__init__.py @@ -9,6 +9,6 @@ - Validating reproducibility """ -__version__ = "0.22.1" +__version__ = "0.23.0" __all__ = ["__version__"] diff --git a/src/specfact_cli/analyzers/code_analyzer.py b/src/specfact_cli/analyzers/code_analyzer.py index 13bb7e2..51a660c 100644 --- a/src/specfact_cli/analyzers/code_analyzer.py +++ b/src/specfact_cli/analyzers/code_analyzer.py @@ -528,7 +528,18 @@ def _run_semgrep_patterns(self, file_path: Path) -> list[dict[str, Any]]: return [] def _should_skip_file(self, file_path: Path) -> bool: - """Check if file should be skipped.""" + """ + Check if file should be skipped. + + Test files are always skipped from feature extraction because: + - Tests are validation artifacts, not specification artifacts + - Tests validate code, they don't define what code should do + - Test files should only be used for linking to production features and extracting examples + """ + file_str = str(file_path) + file_name = file_path.name + + # Skip common non-source directories skip_patterns = [ "__pycache__", ".git", @@ -540,10 +551,19 @@ def _should_skip_file(self, file_path: Path) -> bool: "dist", "build", ".eggs", - "tests", # Skip test files ] - return any(pattern in str(file_path) for pattern in skip_patterns) + if any(pattern in file_str for pattern in skip_patterns): + return True + + # Skip test directories (both "test/" and "tests/") + # Check if any path component is a test directory + path_parts = file_path.parts + if any(part in ("test", "tests") for part in path_parts): + return True + + # Skip test files by naming pattern (test_*.py, *_test.py) + return file_name.startswith("test_") or file_name.endswith("_test.py") def _analyze_file(self, file_path: Path) -> None: """Analyze a single Python file (legacy sequential version).""" diff --git a/src/specfact_cli/analyzers/graph_analyzer.py b/src/specfact_cli/analyzers/graph_analyzer.py index 04000c1..fe3b0c3 100644 --- a/src/specfact_cli/analyzers/graph_analyzer.py +++ b/src/specfact_cli/analyzers/graph_analyzer.py @@ -28,16 +28,21 @@ class GraphAnalyzer: @beartype @require(lambda repo_path: isinstance(repo_path, Path), "Repo path must be Path") - def __init__(self, repo_path: Path) -> None: + def __init__(self, repo_path: Path, file_hashes_cache: dict[str, str] | None = None) -> None: """ Initialize graph analyzer. Args: repo_path: Path to repository root + file_hashes_cache: Optional pre-computed file hashes (file_path -> hash) for caching """ self.repo_path = repo_path.resolve() self.call_graphs: dict[str, dict[str, list[str]]] = {} # file -> {function -> [called_functions]} self.dependency_graph: nx.DiGraph = nx.DiGraph() + # Cache for file hashes and import extraction results + self.file_hashes_cache: dict[str, str] = file_hashes_cache or {} + self.imports_cache: dict[str, list[str]] = {} # file_hash -> [imports] + self.module_name_cache: dict[str, str] = {} # file_path -> module_name @beartype @require(lambda file_path: isinstance(file_path, Path), "File path must be Path") @@ -127,7 +132,7 @@ def _parse_dot_file(self, dot_path: Path) -> dict[str, list[str]]: @beartype @require(lambda python_files: isinstance(python_files, list), "Python files must be list") @ensure(lambda result: isinstance(result, nx.DiGraph), "Must return DiGraph") - def build_dependency_graph(self, python_files: list[Path]) -> nx.DiGraph: + def build_dependency_graph(self, python_files: list[Path], progress_callback: Any | None = None) -> nx.DiGraph: """ Build comprehensive dependency graph using NetworkX. @@ -136,6 +141,7 @@ def build_dependency_graph(self, python_files: list[Path]) -> nx.DiGraph: Args: python_files: List of Python file paths + progress_callback: Optional callback function(completed: int, total: int) for progress updates Returns: NetworkX directed graph of module dependencies @@ -186,6 +192,7 @@ def process_imports(file_path: Path) -> list[tuple[str, str]]: executor1 = ThreadPoolExecutor(max_workers=max_workers) wait_on_shutdown = os.environ.get("TEST_MODE") != "true" + completed_imports = 0 try: future_to_file = {executor1.submit(process_imports, file_path): file_path for file_path in python_files} @@ -194,13 +201,20 @@ def process_imports(file_path: Path) -> list[tuple[str, str]]: edges = future.result() for module_name, matching_module in edges: graph.add_edge(module_name, matching_module) + completed_imports += 1 + if progress_callback: + progress_callback(completed_imports, len(python_files)) except Exception: + completed_imports += 1 + if progress_callback: + progress_callback(completed_imports, len(python_files)) continue finally: executor1.shutdown(wait=wait_on_shutdown) # Extract call graphs using pyan (if available) - parallelized for performance executor2 = ThreadPoolExecutor(max_workers=max_workers) + completed_call_graphs = 0 try: future_to_file = { executor2.submit(self.extract_call_graph, file_path): file_path for file_path in python_files @@ -216,8 +230,15 @@ def process_imports(file_path: Path) -> list[tuple[str, str]]: callee_module = self._resolve_module_from_function(callee, python_files) if callee_module and callee_module in graph: graph.add_edge(module_name, callee_module) + completed_call_graphs += 1 + if progress_callback: + # Report progress as phase 2 (after imports phase) + progress_callback(len(python_files) + completed_call_graphs, len(python_files) * 2) except Exception: # Skip if call graph extraction fails for this file + completed_call_graphs += 1 + if progress_callback: + progress_callback(len(python_files) + completed_call_graphs, len(python_files) * 2) continue finally: executor2.shutdown(wait=wait_on_shutdown) @@ -229,25 +250,52 @@ def process_imports(file_path: Path) -> list[tuple[str, str]]: @require(lambda file_path: isinstance(file_path, Path), "File path must be Path") @ensure(lambda result: isinstance(result, str), "Must return str") def _path_to_module_name(self, file_path: Path) -> str: - """Convert file path to module name.""" + """Convert file path to module name (cached).""" + file_key = str(file_path) + if file_key in self.module_name_cache: + return self.module_name_cache[file_key] + try: relative_path = file_path.relative_to(self.repo_path) except ValueError: relative_path = file_path parts = [*relative_path.parts[:-1], relative_path.stem] - return ".".join(parts) + module_name = ".".join(parts) + self.module_name_cache[file_key] = module_name + return module_name @beartype @require(lambda file_path: isinstance(file_path, Path), "File path must be Path") @ensure(lambda result: isinstance(result, list), "Must return list") def _extract_imports_from_ast(self, file_path: Path) -> list[str]: """ - Extract imported module names from AST. + Extract imported module names from AST (cached by file hash). Extracts full import paths (not just root modules) to enable proper matching. """ import ast + import hashlib + + # Compute file hash for caching + file_hash = "" + try: + file_key = str(file_path.relative_to(self.repo_path)) + except ValueError: + file_key = str(file_path) + + if file_key in self.file_hashes_cache: + file_hash = self.file_hashes_cache[file_key] + elif file_path.exists(): + try: + file_hash = hashlib.sha256(file_path.read_bytes()).hexdigest() + self.file_hashes_cache[file_key] = file_hash + except Exception: + pass + + # Check cache first + if file_hash and file_hash in self.imports_cache: + return self.imports_cache[file_hash] imports: set[str] = set() stdlib_modules = { @@ -306,7 +354,11 @@ def _extract_imports_from_ast(self, file_path: Path) -> list[str]: except (SyntaxError, UnicodeDecodeError): pass - return list(imports) + result = list(imports) + # Cache result + if file_hash: + self.imports_cache[file_hash] = result + return result @beartype @require(lambda imported: isinstance(imported, str), "Imported name must be str") diff --git a/src/specfact_cli/analyzers/relationship_mapper.py b/src/specfact_cli/analyzers/relationship_mapper.py index a0fa7fb..f04dc6a 100644 --- a/src/specfact_cli/analyzers/relationship_mapper.py +++ b/src/specfact_cli/analyzers/relationship_mapper.py @@ -8,6 +8,7 @@ from __future__ import annotations import ast +import hashlib import os from collections import defaultdict from concurrent.futures import ThreadPoolExecutor, as_completed @@ -31,18 +32,23 @@ class RelationshipMapper: @beartype @require(lambda repo_path: isinstance(repo_path, Path), "Repo path must be Path") - def __init__(self, repo_path: Path) -> None: + def __init__(self, repo_path: Path, file_hashes_cache: dict[str, str] | None = None) -> None: """ Initialize relationship mapper. Args: repo_path: Path to repository root + file_hashes_cache: Optional pre-computed file hashes (file_path -> hash) for caching """ self.repo_path = repo_path.resolve() self.imports: dict[str, list[str]] = defaultdict(list) # file -> [imported_modules] self.dependencies: dict[str, list[str]] = defaultdict(list) # module -> [dependencies] self.interfaces: dict[str, dict[str, Any]] = {} # interface_name -> interface_info self.framework_routes: dict[str, list[dict[str, Any]]] = defaultdict(list) # file -> [route_info] + # Cache for file hashes and AST parsing results + self.file_hashes_cache: dict[str, str] = file_hashes_cache or {} + self.ast_cache: dict[str, ast.AST] = {} # file_path -> parsed AST + self.analysis_cache: dict[str, dict[str, Any]] = {} # file_hash -> analysis_result @beartype @require(lambda file_path: isinstance(file_path, Path), "File path must be Path") @@ -179,11 +185,47 @@ def analyze_file(self, file_path: Path) -> dict[str, Any]: except (SyntaxError, UnicodeDecodeError): # Skip files with syntax errors - return {"imports": [], "dependencies": [], "interfaces": [], "routes": []} + result = {"imports": [], "dependencies": [], "interfaces": [], "routes": []} + # Cache the result even for errors to avoid re-processing + file_hash = self._compute_file_hash(file_path) + if file_hash: + self.analysis_cache[file_hash] = result + return result + + @beartype + @require(lambda self, file_path: isinstance(file_path, Path), "File path must be Path") + def _compute_file_hash(self, file_path: Path) -> str: + """ + Compute SHA256 hash of file content. + + Args: + file_path: Path to file + + Returns: + SHA256 hash as hex string + """ + try: + file_key = str(file_path.relative_to(self.repo_path)) + except ValueError: + file_key = str(file_path) + + # Check cache first + if file_key in self.file_hashes_cache: + return self.file_hashes_cache[file_key] + + # Compute hash + if not file_path.exists(): + return "" + try: + file_hash = hashlib.sha256(file_path.read_bytes()).hexdigest() + self.file_hashes_cache[file_key] = file_hash + return file_hash + except Exception: + return "" def _analyze_file_parallel(self, file_path: Path) -> tuple[str, dict[str, Any]]: """ - Analyze a single file for relationships (thread-safe version). + Analyze a single file for relationships (thread-safe version with caching). Args: file_path: Path to Python file @@ -191,41 +233,55 @@ def _analyze_file_parallel(self, file_path: Path) -> tuple[str, dict[str, Any]]: Returns: Tuple of (file_key, relationships_dict) """ + # Get file key + try: + file_key = str(file_path.relative_to(self.repo_path)) + except ValueError: + file_key = str(file_path) + + # Compute file hash for caching + file_hash = self._compute_file_hash(file_path) + + # Check if we have cached analysis result for this file hash + if file_hash and file_hash in self.analysis_cache: + return (file_key, self.analysis_cache[file_hash]) + # Skip very large files early (>500KB) to speed up processing try: file_size = file_path.stat().st_size if file_size > 500 * 1024: # 500KB - try: - file_key = str(file_path.relative_to(self.repo_path)) - except ValueError: - file_key = str(file_path) - return (file_key, {"imports": [], "dependencies": [], "interfaces": {}, "routes": []}) + result = {"imports": [], "dependencies": [], "interfaces": {}, "routes": []} + if file_hash: + self.analysis_cache[file_hash] = result + return (file_key, result) except Exception: pass try: - with file_path.open(encoding="utf-8") as f: - content = f.read() - # For large files (>100KB), only extract imports (faster) - if len(content) > 100 * 1024: # ~100KB - tree = ast.parse(content, filename=str(file_path)) - large_file_imports: list[str] = [] - for node in ast.walk(tree): - if isinstance(node, ast.Import): - for alias in node.names: - large_file_imports.append(alias.name) - if isinstance(node, ast.ImportFrom) and node.module: - large_file_imports.append(node.module) - try: - file_key = str(file_path.relative_to(self.repo_path)) - except ValueError: - file_key = str(file_path) - return ( - file_key, - {"imports": large_file_imports, "dependencies": [], "interfaces": {}, "routes": []}, - ) + # Check if we have cached AST + if file_key in self.ast_cache: + tree = self.ast_cache[file_key] + else: + with file_path.open(encoding="utf-8") as f: + content = f.read() + # For large files (>100KB), only extract imports (faster) + if len(content) > 100 * 1024: # ~100KB + tree = ast.parse(content, filename=str(file_path)) + large_file_imports: list[str] = [] + for node in ast.walk(tree): + if isinstance(node, ast.Import): + for alias in node.names: + large_file_imports.append(alias.name) + if isinstance(node, ast.ImportFrom) and node.module: + large_file_imports.append(node.module) + result = {"imports": large_file_imports, "dependencies": [], "interfaces": {}, "routes": []} + if file_hash: + self.analysis_cache[file_hash] = result + return (file_key, result) - tree = ast.parse(content, filename=str(file_path)) + tree = ast.parse(content, filename=str(file_path)) + # Cache AST for future use + self.ast_cache[file_key] = tree file_imports: list[str] = [] file_dependencies: list[str] = [] @@ -337,15 +393,18 @@ def _analyze_file_parallel(self, file_path: Path) -> tuple[str, dict[str, Any]]: for interface_info in file_interfaces: interfaces_dict[interface_info["name"]] = interface_info - return ( - file_key, - { - "imports": file_imports, - "dependencies": file_dependencies, - "interfaces": interfaces_dict, - "routes": file_routes, - }, - ) + result = { + "imports": file_imports, + "dependencies": file_dependencies, + "interfaces": interfaces_dict, + "routes": file_routes, + } + + # Cache result for future use (keyed by file hash) + if file_hash: + self.analysis_cache[file_hash] = result + + return (file_key, result) except (SyntaxError, UnicodeDecodeError): # Skip files with syntax errors @@ -353,17 +412,22 @@ def _analyze_file_parallel(self, file_path: Path) -> tuple[str, dict[str, Any]]: file_key = str(file_path.relative_to(self.repo_path)) except ValueError: file_key = str(file_path) - return (file_key, {"imports": [], "dependencies": [], "interfaces": {}, "routes": []}) + result = {"imports": [], "dependencies": [], "interfaces": {}, "routes": []} + # Cache result for syntax errors to avoid re-processing + if file_hash: + self.analysis_cache[file_hash] = result + return (file_key, result) @beartype @require(lambda file_paths: isinstance(file_paths, list), "File paths must be list") @ensure(lambda result: isinstance(result, dict), "Must return dict") - def analyze_files(self, file_paths: list[Path]) -> dict[str, Any]: + def analyze_files(self, file_paths: list[Path], progress_callback: Any | None = None) -> dict[str, Any]: """ Analyze multiple files for relationships (parallelized). Args: file_paths: List of file paths to analyze + progress_callback: Optional callback function(completed: int, total: int) for progress updates Returns: Dictionary with all relationships @@ -390,6 +454,7 @@ def analyze_files(self, file_paths: list[Path]) -> dict[str, Any]: interrupted = False # In test mode, use wait=False to avoid hanging on shutdown wait_on_shutdown = os.environ.get("TEST_MODE") != "true" + completed_count = 0 try: # Submit all tasks future_to_file = {executor.submit(self._analyze_file_parallel, f): f for f in python_files} @@ -405,6 +470,10 @@ def analyze_files(self, file_paths: list[Path]) -> dict[str, Any]: # Merge interfaces for interface_name, interface_info in result["interfaces"].items(): self.interfaces[interface_name] = interface_info + # Update progress + completed_count += 1 + if progress_callback: + progress_callback(completed_count, len(python_files)) # Store routes if result["routes"]: self.framework_routes[file_key] = result["routes"] @@ -416,7 +485,9 @@ def analyze_files(self, file_paths: list[Path]) -> dict[str, Any]: break except Exception: # Skip files that fail to process - pass + completed_count += 1 + if progress_callback: + progress_callback(completed_count, len(python_files)) except KeyboardInterrupt: interrupted = True for f in future_to_file: diff --git a/src/specfact_cli/commands/import_cmd.py b/src/specfact_cli/commands/import_cmd.py index 7a61635..525c720 100644 --- a/src/specfact_cli/commands/import_cmd.py +++ b/src/specfact_cli/commands/import_cmd.py @@ -144,6 +144,85 @@ def _check_incremental_changes( return None +def _validate_existing_features(plan_bundle: PlanBundle, repo: Path) -> dict[str, Any]: + """ + Validate existing features to check if they're still valid. + + Args: + plan_bundle: Plan bundle with features to validate + repo: Repository root path + + Returns: + Dictionary with validation results: + - 'valid_features': List of valid feature keys + - 'orphaned_features': List of feature keys whose source files no longer exist + - 'invalid_features': List of feature keys with validation issues + - 'missing_files': Dict mapping feature_key -> list of missing file paths + - 'total_checked': Total number of features checked + """ + + result: dict[str, Any] = { + "valid_features": [], + "orphaned_features": [], + "invalid_features": [], + "missing_files": {}, + "total_checked": len(plan_bundle.features), + } + + for feature in plan_bundle.features: + if not feature.source_tracking: + # Feature has no source tracking - mark as potentially invalid + result["invalid_features"].append(feature.key) + continue + + missing_files: list[str] = [] + has_any_files = False + + # Check implementation files + for impl_file in feature.source_tracking.implementation_files: + file_path = repo / impl_file + if file_path.exists(): + has_any_files = True + else: + missing_files.append(impl_file) + + # Check test files + for test_file in feature.source_tracking.test_files: + file_path = repo / test_file + if file_path.exists(): + has_any_files = True + else: + missing_files.append(test_file) + + # Validate feature structure + # Note: Features can legitimately have no stories if they're newly discovered + # Only mark as invalid if there are actual structural problems (missing key/title) + has_structure_issues = False + if not feature.key or not feature.title: + has_structure_issues = True + # Don't mark features with no stories as invalid - they may be newly discovered + # Stories will be added during analysis or enrichment + + # Classify feature + if not has_any_files and missing_files: + # All source files are missing - orphaned feature + result["orphaned_features"].append(feature.key) + result["missing_files"][feature.key] = missing_files + elif missing_files: + # Some files missing but not all - invalid but recoverable + result["invalid_features"].append(feature.key) + result["missing_files"][feature.key] = missing_files + elif has_structure_issues: + # Feature has actual structure issues (missing key/title) + result["invalid_features"].append(feature.key) + else: + # Feature is valid (has source_tracking, files exist, and has key/title) + # Note: Features without stories are still considered valid + result["valid_features"].append(feature.key) + + return result + + def _load_existing_bundle(bundle_dir: Path) -> PlanBundle | None: """Load existing project bundle and convert to PlanBundle.""" from specfact_cli.models.plan import PlanBundle as PlanBundleModel @@ -283,6 +362,10 @@ def update_file_hash(feature: Feature, file_path: Path) -> None: if hash_tasks: import os + from rich.progress import Progress + + from specfact_cli.utils.terminal import get_progress_config + # In test mode, use sequential processing to avoid ThreadPoolExecutor deadlocks is_test_mode = os.environ.get("TEST_MODE") == "true" if is_test_mode: @@ -294,42 +377,68 @@ def update_file_hash(feature: Feature, file_path: Path) -> None: update_file_hash(feature, file_path) else: max_workers = max(1, min(multiprocessing.cpu_count() or 4, 16, len(hash_tasks))) - executor = ThreadPoolExecutor(max_workers=max_workers) - interrupted = False - try: - future_to_task = { - executor.submit(update_file_hash, feature, file_path): (feature, file_path) - for feature, file_path in hash_tasks - } + progress_columns, progress_kwargs = get_progress_config() + with Progress( + *progress_columns, + console=console, + **progress_kwargs, + ) as progress: + hash_task = progress.add_task( + f"[cyan]Computing file hashes for {len(hash_tasks)} files...", + total=len(hash_tasks), + ) + + executor = ThreadPoolExecutor(max_workers=max_workers) + interrupted = False + completed_count = 0 try: - for future in as_completed(future_to_task): - try: - future.result() - except KeyboardInterrupt: - interrupted = True - for f in future_to_task: - if not f.done(): - f.cancel() - break - except Exception: - pass + future_to_task = { + executor.submit(update_file_hash, feature, file_path): (feature, file_path) + for feature, file_path in hash_tasks + } + try: + for future in as_completed(future_to_task): + try: + future.result() + completed_count += 1 + progress.update( + hash_task, + completed=completed_count, + description=f"[cyan]Computing file hashes... ({completed_count}/{len(hash_tasks)})", + ) + except KeyboardInterrupt: + interrupted = True + for f in future_to_task: + if not f.done(): + f.cancel() + break + except Exception: + completed_count += 1 + progress.update(hash_task, completed=completed_count) + except KeyboardInterrupt: + interrupted = True + for f in future_to_task: + if not f.done(): + f.cancel() + if interrupted: + raise KeyboardInterrupt except KeyboardInterrupt: interrupted = True - for f in future_to_task: - if not f.done(): - f.cancel() - if interrupted: - raise KeyboardInterrupt - except KeyboardInterrupt: - interrupted = True - executor.shutdown(wait=False, cancel_futures=True) - raise - finally: - if not interrupted: - executor.shutdown(wait=True) - else: - executor.shutdown(wait=False) + executor.shutdown(wait=False, cancel_futures=True) + raise + finally: + if not interrupted: + progress.update( + hash_task, + completed=len(hash_tasks), + description=f"[green]✓[/green] Computed hashes for {len(hash_tasks)} files", + ) + progress.remove_task(hash_task) + executor.shutdown(wait=True) + else: + executor.shutdown(wait=False) + # Update sync timestamps (fast operation, no progress needed) for feature in plan_bundle.features: if feature.source_tracking: feature.source_tracking.update_sync_timestamp() @@ -345,7 +454,7 @@ def _extract_relationships_and_graph( plan_bundle: PlanBundle | None, should_regenerate_relationships: bool, should_regenerate_graph: bool, - include_tests: bool = True, + include_tests: bool = False, ) -> tuple[dict[str, Any], dict[str, Any] | None]: """Extract relationships and graph dependencies.""" relationships: dict[str, Any] = {} @@ -359,90 +468,181 @@ def _extract_relationships_and_graph( return relationships, graph_summary console.print("\n[cyan]🔍 Enhanced analysis: Extracting relationships, contracts, and graph dependencies...[/cyan]") + from rich.progress import Progress, SpinnerColumn, TextColumn + from specfact_cli.analyzers.graph_analyzer import GraphAnalyzer from specfact_cli.analyzers.relationship_mapper import RelationshipMapper from specfact_cli.utils.optional_deps import check_cli_tool_available + from specfact_cli.utils.terminal import get_progress_config + + # Show spinner while checking pyan3 and collecting file hashes + _progress_columns, progress_kwargs = get_progress_config() + with Progress( + SpinnerColumn(), + TextColumn("[progress.description]{task.description}"), + console=console, + **progress_kwargs, + ) as setup_progress: + setup_task = setup_progress.add_task("[cyan]Preparing enhanced analysis...", total=None) + + pyan3_available, _ = check_cli_tool_available("pyan3") + if not pyan3_available: + console.print( + "[dim]💡 Note: Enhanced analysis tool pyan3 is not available (call graph analysis will be skipped)[/dim]" + ) + console.print("[dim] Install with: pip install pyan3[/dim]") - pyan3_available, _ = check_cli_tool_available("pyan3") - if not pyan3_available: - console.print( - "[dim]💡 Note: Enhanced analysis tool pyan3 is not available (call graph analysis will be skipped)[/dim]" - ) - console.print("[dim] Install with: pip install pyan3[/dim]") - - relationship_mapper = RelationshipMapper(repo) - - changed_files: set[Path] = set() - if incremental_changes and plan_bundle: - from specfact_cli.utils.incremental_check import get_changed_files + # Pre-compute file hashes for caching (reuse from source tracking if available) + setup_progress.update(setup_task, description="[cyan]Collecting file hashes for caching...") + file_hashes_cache: dict[str, str] = {} + if plan_bundle: + # Collect file hashes from source tracking + for feature in plan_bundle.features: + if feature.source_tracking: + file_hashes_cache.update(feature.source_tracking.file_hashes) + + relationship_mapper = RelationshipMapper(repo, file_hashes_cache=file_hashes_cache) + + # Discover and filter Python files with progress + changed_files: set[Path] = set() + if incremental_changes and plan_bundle: + setup_progress.update(setup_task, description="[cyan]Checking for changed files...") + from specfact_cli.utils.incremental_check import get_changed_files + + # get_changed_files iterates through all features and checks file hashes + # This can be slow for large bundles - show progress + changed_files_dict = get_changed_files(bundle_dir, repo, list(plan_bundle.features)) + setup_progress.update(setup_task, description="[cyan]Collecting changed file paths...") + for feature_changes in changed_files_dict.values(): + for file_path_str in feature_changes: + clean_path = file_path_str.replace(" (deleted)", "") + file_path = repo / clean_path + if file_path.exists(): + changed_files.add(file_path) + + if changed_files: + python_files = list(changed_files) + setup_progress.update(setup_task, description=f"[green]✓[/green] Found {len(python_files)} changed file(s)") + else: + setup_progress.update(setup_task, description="[cyan]Discovering Python files...") + # This can be slow for large codebases - show progress + python_files = list(repo.rglob("*.py")) + setup_progress.update(setup_task, description=f"[cyan]Filtering {len(python_files)} files...") + + if entry_point: + python_files = [f for f in python_files if entry_point in f.parts] + + # Filter files based on --include-tests/--exclude-tests flag + # Default: Exclude test files (they're validation artifacts, not specifications) + # --include-tests: Include test files in dependency graph (only if needed) + # Rationale for excluding tests by default: + # - Test files are consumers of production code (not producers) + # - Test files import production code, but production code doesn't import tests + # - Interfaces and routes are defined in production code, not tests + # - Dependency graph flows from production code, so skipping tests has minimal impact + # - Test files are never extracted as features (they validate code, they don't define it) + if not include_tests: + # Exclude test files when --exclude-tests is specified (default) + # Test files are validation artifacts, not specifications + python_files = [ + f + for f in python_files + if not any( + skip in str(f) + for skip in [ + "/test_", + "/tests/", + "/test/", # Handle singular "test/" directory (e.g., SQLAlchemy) + "/vendor/", + "/.venv/", + "/venv/", + "/node_modules/", + "/__pycache__/", + ] + ) + and not f.name.startswith("test_") # Exclude test_*.py files + and not f.name.endswith("_test.py") # Exclude *_test.py files + ] + else: + # Default: Include test files, but still filter vendor/venv files + python_files = [ + f + for f in python_files + if not any( + skip in str(f) for skip in ["/vendor/", "/.venv/", "/venv/", "/node_modules/", "/__pycache__/"] + ) + ] + setup_progress.update( + setup_task, description=f"[green]✓[/green] Ready to analyze {len(python_files)} files" + ) - changed_files_dict = get_changed_files(bundle_dir, repo, list(plan_bundle.features)) - for feature_changes in changed_files_dict.values(): - for file_path_str in feature_changes: - clean_path = file_path_str.replace(" (deleted)", "") - file_path = repo / clean_path - if file_path.exists(): - changed_files.add(file_path) + setup_progress.remove_task(setup_task) if changed_files: - python_files = list(changed_files) console.print(f"[dim]Analyzing {len(python_files)} changed file(s) for relationships...[/dim]") else: - python_files = list(repo.rglob("*.py")) - if entry_point: - python_files = [f for f in python_files if entry_point in f.parts] - - # Filter files based on --include-tests/--exclude-tests flag - # Default: Include test files for comprehensive analysis - # --exclude-tests: Skip test files for faster processing (~30-50% speedup) - # Rationale for excluding tests: - # - Test files are consumers of production code (not producers) - # - Test files import production code, but production code doesn't import tests - # - Interfaces and routes are defined in production code, not tests - # - Dependency graph flows from production code, so skipping tests has minimal impact - if not include_tests: - # Exclude test files when --exclude-tests is specified - python_files = [ - f - for f in python_files - if not any( - skip in str(f) - for skip in [ - "/test_", - "/tests/", - "/vendor/", - "/.venv/", - "/venv/", - "/node_modules/", - "/__pycache__/", - ] - ) - ] - else: - # Default: Include test files, but still filter vendor/venv files - python_files = [ - f - for f in python_files - if not any( - skip in str(f) for skip in ["/vendor/", "/.venv/", "/venv/", "/node_modules/", "/__pycache__/"] - ) - ] + console.print(f"[dim]Analyzing {len(python_files)} file(s) for relationships...[/dim]") + + # Analyze relationships in parallel with progress reporting + progress_columns, progress_kwargs = get_progress_config() + with Progress( + *progress_columns, + console=console, + **progress_kwargs, + ) as progress: + # Step 1: Analyze relationships + relationships_task = progress.add_task( + f"[cyan]Analyzing relationships in {len(python_files)} files...", + total=len(python_files), + ) - # Analyze relationships in parallel (optimized for speed) - relationships = relationship_mapper.analyze_files(python_files) - console.print(f"[green]✓[/green] Mapped {len(relationships['imports'])} files with relationships") + def update_relationships_progress(completed: int, total: int) -> None: + """Update progress for relationship analysis.""" + progress.update( + relationships_task, + completed=completed, + description=f"[cyan]Analyzing relationships... ({completed}/{total} files)", + ) + + relationships = relationship_mapper.analyze_files(python_files, progress_callback=update_relationships_progress) + progress.update( + relationships_task, + completed=len(python_files), + description=f"[green]✓[/green] Mapped {len(relationships['imports'])} files with relationships", + ) + progress.remove_task(relationships_task) # Graph analysis is optional and can be slow - only run if explicitly needed # Skip by default for faster imports (can be enabled with --with-graph flag in future) if should_regenerate_graph and pyan3_available: - console.print("[dim]Building dependency graph (this may take a moment)...[/dim]") - graph_analyzer = GraphAnalyzer(repo) - graph_analyzer.build_dependency_graph(python_files) - graph_summary = graph_analyzer.get_graph_summary() - if graph_summary: - console.print( - f"[green]✓[/green] Built dependency graph: {graph_summary.get('nodes', 0)} modules, {graph_summary.get('edges', 0)} dependencies" + with Progress( + *progress_columns, + console=console, + **progress_kwargs, + ) as progress: + graph_task = progress.add_task( + f"[cyan]Building dependency graph from {len(python_files)} files...", + total=len(python_files) * 2, # Two phases: AST imports + call graphs ) + + def update_graph_progress(completed: int, total: int) -> None: + """Update progress for graph building.""" + progress.update( + graph_task, + completed=completed, + description=f"[cyan]Building dependency graph... ({completed}/{total})", + ) + + graph_analyzer = GraphAnalyzer(repo, file_hashes_cache=file_hashes_cache) + graph_analyzer.build_dependency_graph(python_files, progress_callback=update_graph_progress) + graph_summary = graph_analyzer.get_graph_summary() + if graph_summary: + progress.update( + graph_task, + completed=len(python_files) * 2, + description=f"[green]✓[/green] Built dependency graph: {graph_summary.get('nodes', 0)} modules, {graph_summary.get('edges', 0)} dependencies", + ) + progress.remove_task(graph_task) relationships["dependency_graph"] = graph_summary relationships["call_graphs"] = graph_analyzer.call_graphs elif should_regenerate_graph and not pyan3_available: @@ -494,59 +694,89 @@ def load_contract(feature: Feature) -> tuple[str, dict[str, Any] | None]: features_with_contracts = [f for f in plan_bundle.features if f.contract] if features_with_contracts: import os + from concurrent.futures import ThreadPoolExecutor, as_completed + + from rich.progress import Progress + + from specfact_cli.utils.terminal import get_progress_config # In test mode, use sequential processing to avoid ThreadPoolExecutor deadlocks is_test_mode = os.environ.get("TEST_MODE") == "true" existing_contracts_count = 0 - if is_test_mode: - # Sequential processing in test mode - avoids ThreadPoolExecutor deadlocks - for feature in features_with_contracts: - try: - feature_key, contract_data = load_contract(feature) - if contract_data: - contracts_data[feature_key] = contract_data - existing_contracts_count += 1 - except Exception: - pass - else: - max_workers = max(1, min(multiprocessing.cpu_count() or 4, 16, len(features_with_contracts))) - executor = ThreadPoolExecutor(max_workers=max_workers) - interrupted = False - try: - future_to_feature = { - executor.submit(load_contract, feature): feature for feature in features_with_contracts - } + + progress_columns, progress_kwargs = get_progress_config() + with Progress( + *progress_columns, + console=console, + **progress_kwargs, + ) as progress: + load_task = progress.add_task( + f"[cyan]Loading {len(features_with_contracts)} existing contract(s)...", + total=len(features_with_contracts), + ) + + if is_test_mode: + # Sequential processing in test mode - avoids ThreadPoolExecutor deadlocks + for idx, feature in enumerate(features_with_contracts): + try: + feature_key, contract_data = load_contract(feature) + if contract_data: + contracts_data[feature_key] = contract_data + existing_contracts_count += 1 + except Exception: + pass + progress.update(load_task, completed=idx + 1) + else: + max_workers = max(1, min(multiprocessing.cpu_count() or 4, 16, len(features_with_contracts))) + executor = ThreadPoolExecutor(max_workers=max_workers) + interrupted = False + completed_count = 0 try: - for future in as_completed(future_to_feature): - try: - feature_key, contract_data = future.result() - if contract_data: - contracts_data[feature_key] = contract_data - existing_contracts_count += 1 - except KeyboardInterrupt: - interrupted = True - for f in future_to_feature: - if not f.done(): - f.cancel() - break - except Exception: - pass + future_to_feature = { + executor.submit(load_contract, feature): feature for feature in features_with_contracts + } + try: + for future in as_completed(future_to_feature): + try: + feature_key, contract_data = future.result() + completed_count += 1 + progress.update(load_task, completed=completed_count) + if contract_data: + contracts_data[feature_key] = contract_data + existing_contracts_count += 1 + except KeyboardInterrupt: + interrupted = True + for f in future_to_feature: + if not f.done(): + f.cancel() + break + except Exception: + completed_count += 1 + progress.update(load_task, completed=completed_count) + except KeyboardInterrupt: + interrupted = True + for f in future_to_feature: + if not f.done(): + f.cancel() + if interrupted: + raise KeyboardInterrupt except KeyboardInterrupt: interrupted = True - for f in future_to_feature: - if not f.done(): - f.cancel() - if interrupted: - raise KeyboardInterrupt - except KeyboardInterrupt: - interrupted = True - executor.shutdown(wait=False, cancel_futures=True) - raise - finally: - if not interrupted: - executor.shutdown(wait=True) - else: - executor.shutdown(wait=False) + executor.shutdown(wait=False, cancel_futures=True) + raise + finally: + if not interrupted: + progress.update( + load_task, + completed=len(features_with_contracts), + description=f"[green]✓[/green] Loaded {existing_contracts_count} contract(s)", + ) + executor.shutdown(wait=True) + else: + executor.shutdown(wait=False) + + if existing_contracts_count == 0: + progress.remove_task(load_task) if existing_contracts_count > 0: console.print(f"[green]✓[/green] Loaded {existing_contracts_count} existing contract(s) from bundle") @@ -554,9 +784,28 @@ def load_contract(feature: Feature) -> tuple[str, dict[str, Any] | None]: # Extract contracts if needed test_converter = OpenAPITestConverter(repo) if should_regenerate_contracts: - features_with_files = [ - f for f in plan_bundle.features if f.source_tracking and f.source_tracking.implementation_files - ] + # Filter features that need contract regeneration (check file hashes) + features_with_files: list[Feature] = [] + for f in plan_bundle.features: + if f.source_tracking and f.source_tracking.implementation_files: + # Check if contract needs regeneration (file changed or contract missing) + needs_regeneration = False + if not f.contract: + needs_regeneration = True + else: + # Check if any source file changed + contract_path = bundle_dir / f.contract + if not contract_path.exists(): + needs_regeneration = True + else: + # Check if any implementation file changed + for impl_file in f.source_tracking.implementation_files: + file_path = repo / impl_file + if file_path.exists() and f.source_tracking.has_changed(file_path): + needs_regeneration = True + break + if needs_regeneration: + features_with_files.append(f) else: features_with_files = [] @@ -579,6 +828,8 @@ def load_contract(feature: Feature) -> tuple[str, dict[str, Any] | None]: from rich.progress import Progress + from specfact_cli.utils.terminal import get_progress_config + def process_feature(feature: Feature) -> tuple[str, dict[str, Any] | None]: """Process a single feature and return (feature_key, openapi_spec or None).""" try: @@ -637,6 +888,8 @@ def process_feature(feature: Feature) -> tuple[str, dict[str, Any] | None]: progress.update(task, completed=completed_count) console.print(f"[dim]⚠ Warning: Failed to process feature: {e}[/dim]") else: + # Create feature lookup dictionary for O(1) access instead of O(n) search + feature_lookup: dict[str, Feature] = {f.key: f for f in features_with_files} executor = ThreadPoolExecutor(max_workers=max_workers) interrupted = False try: @@ -649,11 +902,13 @@ def process_feature(feature: Feature) -> tuple[str, dict[str, Any] | None]: completed_count += 1 progress.update(task, completed=completed_count) if openapi_spec: - feature = next(f for f in features_with_files if f.key == feature_key) - contract_ref = f"contracts/{feature_key}.openapi.yaml" - feature.contract = contract_ref - contracts_data[feature_key] = openapi_spec - contracts_generated += 1 + # O(1) lookup instead of O(n) search + feature = feature_lookup.get(feature_key) + if feature: + contract_ref = f"contracts/{feature_key}.openapi.yaml" + feature.contract = contract_ref + contracts_data[feature_key] = openapi_spec + contracts_generated += 1 except KeyboardInterrupt: interrupted = True for f in future_to_feature: @@ -704,16 +959,69 @@ def _build_enrichment_context( record_event: Any, ) -> Path: """Build enrichment context for LLM.""" + import hashlib + context_path = bundle_dir / "enrichment_context.md" - if should_regenerate_enrichment: + + # Check if context needs regeneration using file hash + needs_regeneration = should_regenerate_enrichment + if not needs_regeneration and context_path.exists(): + # Check if any source data changed (relationships, contracts, features) + # This can be slow for large bundles - show progress + from rich.progress import SpinnerColumn, TextColumn + + from specfact_cli.utils.terminal import get_progress_config + + _progress_columns, progress_kwargs = get_progress_config() + with Progress( + SpinnerColumn(), + TextColumn("[progress.description]{task.description}"), + console=console, + **progress_kwargs, + ) as check_progress: + check_task = check_progress.add_task("[cyan]Checking if enrichment context changed...", total=None) + try: + existing_hash = hashlib.sha256(context_path.read_bytes()).hexdigest() + # Build temporary context to compare hash + from specfact_cli.utils.enrichment_context import build_enrichment_context + + check_progress.update(check_task, description="[cyan]Building temporary context for comparison...") + temp_context = build_enrichment_context( + plan_bundle, relationships=relationships, contracts=contracts_data + ) + temp_md = temp_context.to_markdown() + new_hash = hashlib.sha256(temp_md.encode("utf-8")).hexdigest() + if existing_hash != new_hash: + needs_regeneration = True + except Exception: + # If we can't check, regenerate to be safe + needs_regeneration = True + + if needs_regeneration: console.print("\n[cyan]📊 Building enrichment context...[/cyan]") + # Building context can be slow for large bundles - show progress + from rich.progress import SpinnerColumn, TextColumn + from specfact_cli.utils.enrichment_context import build_enrichment_context + from specfact_cli.utils.terminal import get_progress_config - enrichment_context = build_enrichment_context( - plan_bundle, relationships=relationships, contracts=contracts_data - ) - _enrichment_context_md = enrichment_context.to_markdown() - context_path.write_text(_enrichment_context_md, encoding="utf-8") + _progress_columns, progress_kwargs = get_progress_config() + with Progress( + SpinnerColumn(), + TextColumn("[progress.description]{task.description}"), + console=console, + **progress_kwargs, + ) as build_progress: + build_task = build_progress.add_task( + f"[cyan]Building context from {len(plan_bundle.features)} features...", total=None + ) + enrichment_context = build_enrichment_context( + plan_bundle, relationships=relationships, contracts=contracts_data + ) + build_progress.update(build_task, description="[cyan]Converting to markdown...") + _enrichment_context_md = enrichment_context.to_markdown() + build_progress.update(build_task, description="[cyan]Writing to file...") + context_path.write_text(_enrichment_context_md, encoding="utf-8") try: rel_path = context_path.relative_to(repo.resolve()) console.print(f"[green]✓[/green] Enrichment context saved to: {rel_path}") @@ -844,23 +1152,48 @@ def _validate_bundle_contracts(bundle_dir: Path, plan_bundle: PlanBundle) -> tup if not contract_files: return 0, 0 - console.print(f"\n[cyan]🔍 Validating {len(contract_files)} contract(s) in bundle with Specmatic...[/cyan]") - for contract_path, feature_key in contract_files[:5]: # Validate up to 5 contracts - console.print(f"[dim]Validating {contract_path.relative_to(bundle_dir)} (from {feature_key})...[/dim]") - try: - result = asyncio.run(validate_spec_with_specmatic(contract_path)) - if result.is_valid: - console.print(f" [green]✓[/green] {contract_path.name} is valid") - validated_count += 1 - else: - console.print(f" [yellow]⚠[/yellow] {contract_path.name} has validation issues") - if result.errors: - for error in result.errors[:2]: - console.print(f" - {error}") + # Limit validation to first 5 contracts to avoid long delays + contracts_to_validate = contract_files[:5] + + console.print(f"\n[cyan]🔍 Validating {len(contracts_to_validate)} contract(s) in bundle with Specmatic...[/cyan]") + + progress_columns, progress_kwargs = get_progress_config() + with Progress( + *progress_columns, + console=console, + **progress_kwargs, + ) as progress: + validation_task = progress.add_task( + "[cyan]Validating contracts...", + total=len(contracts_to_validate), + ) + + for idx, (contract_path, _feature_key) in enumerate(contracts_to_validate): + progress.update( + validation_task, + completed=idx, + description=f"[cyan]Validating {contract_path.name}...", + ) + try: + result = asyncio.run(validate_spec_with_specmatic(contract_path)) + if result.is_valid: + validated_count += 1 + else: + failed_count += 1 + if result.errors: + console.print(f" [yellow]⚠[/yellow] {contract_path.name} has validation issues") + for error in result.errors[:2]: + console.print(f" - {error}") + except Exception as e: failed_count += 1 - except Exception as e: - console.print(f" [yellow]⚠[/yellow] Validation error: {e!s}") - failed_count += 1 + console.print(f" [yellow]⚠[/yellow] Validation error for {contract_path.name}: {e!s}") + + progress.update( + validation_task, + completed=len(contracts_to_validate), + description=f"[green]✓[/green] Validated {validated_count} contract(s)", + ) + progress.remove_task(validation_task) if len(contract_files) > 5: console.print( @@ -1032,11 +1365,27 @@ def _enrich_for_speckit_compliance(plan_bundle: PlanBundle) -> None: console.print("\n[cyan]🔧 Enriching plan for tool compliance...[/cyan]") try: from specfact_cli.enrichers.plan_enricher import PlanEnricher + from specfact_cli.utils.terminal import get_progress_config # Use PlanEnricher for consistent enrichment (same as plan review --auto-enrich) console.print("[dim]Enhancing vague acceptance criteria, incomplete requirements, generic tasks...[/dim]") - enricher = PlanEnricher() - enrichment_summary = enricher.enrich_plan(plan_bundle) + + # Add progress reporting for large bundles + progress_columns, progress_kwargs = get_progress_config() + with Progress( + *progress_columns, + console=console, + **progress_kwargs, + ) as progress: + enrich_task = progress.add_task( + f"[cyan]Enriching {len(plan_bundle.features)} features...", + total=len(plan_bundle.features), + ) + + enricher = PlanEnricher() + enrichment_summary = enricher.enrich_plan(plan_bundle) + progress.update(enrich_task, completed=len(plan_bundle.features)) + progress.remove_task(enrich_task) # Add edge case stories for features with only 1 story (preserve existing behavior) features_with_one_story = [f for f in plan_bundle.features if len(f.stories) == 1] @@ -1044,43 +1393,56 @@ def _enrich_for_speckit_compliance(plan_bundle: PlanBundle) -> None: console.print(f"[yellow]⚠ Found {len(features_with_one_story)} features with only 1 story[/yellow]") console.print("[dim]Adding edge case stories for better tool compliance...[/dim]") - for feature in features_with_one_story: - edge_case_title = f"As a user, I receive error handling for {feature.title.lower()}" - edge_case_acceptance = [ - "Must verify error conditions are handled gracefully", - "Must validate error messages are clear and actionable", - "Must ensure system recovers from errors", - ] - - existing_story_nums = [] - for s in feature.stories: - parts = s.key.split("-") - if len(parts) >= 2: - last_part = parts[-1] - if last_part.isdigit(): - existing_story_nums.append(int(last_part)) - - next_story_num = max(existing_story_nums) + 1 if existing_story_nums else 2 - feature_key_parts = feature.key.split("-") - if len(feature_key_parts) >= 2: - class_name = feature_key_parts[-1] - story_key = f"STORY-{class_name}-{next_story_num:03d}" - else: - story_key = f"STORY-{next_story_num:03d}" - - from specfact_cli.models.plan import Story - - edge_case_story = Story( - key=story_key, - title=edge_case_title, - acceptance=edge_case_acceptance, - story_points=3, - value_points=None, - confidence=0.8, - scenarios=None, - contracts=None, + with Progress( + *progress_columns, + console=console, + **progress_kwargs, + ) as progress: + edge_case_task = progress.add_task( + "[cyan]Adding edge case stories...", + total=len(features_with_one_story), ) - feature.stories.append(edge_case_story) + + for idx, feature in enumerate(features_with_one_story): + edge_case_title = f"As a user, I receive error handling for {feature.title.lower()}" + edge_case_acceptance = [ + "Must verify error conditions are handled gracefully", + "Must validate error messages are clear and actionable", + "Must ensure system recovers from errors", + ] + + existing_story_nums = [] + for s in feature.stories: + parts = s.key.split("-") + if len(parts) >= 2: + last_part = parts[-1] + if last_part.isdigit(): + existing_story_nums.append(int(last_part)) + + next_story_num = max(existing_story_nums) + 1 if existing_story_nums else 2 + feature_key_parts = feature.key.split("-") + if len(feature_key_parts) >= 2: + class_name = feature_key_parts[-1] + story_key = f"STORY-{class_name}-{next_story_num:03d}" + else: + story_key = f"STORY-{next_story_num:03d}" + + from specfact_cli.models.plan import Story + + edge_case_story = Story( + key=story_key, + title=edge_case_title, + acceptance=edge_case_acceptance, + story_points=3, + value_points=None, + confidence=0.8, + scenarios=None, + contracts=None, + ) + feature.stories.append(edge_case_story) + progress.update(edge_case_task, completed=idx + 1) + + progress.remove_task(edge_case_task) console.print(f"[green]✓ Added edge case stories to {len(features_with_one_story)} features[/green]") @@ -1664,9 +2026,15 @@ def from_code( help="Force full regeneration of all artifacts, ignoring incremental changes. Default: False", ), include_tests: bool = typer.Option( - True, + False, "--include-tests/--exclude-tests", - help="Include/exclude test files in relationship mapping. Default: --include-tests (test files are included for comprehensive analysis). Use --exclude-tests to optimize speed.", + help="Include/exclude test files in relationship mapping and dependency graph. Default: --exclude-tests (test files are excluded by default). Test files are never extracted as features (they're validation artifacts, not specifications). Use --include-tests only if you need test files in the dependency graph.", + ), + revalidate_features: bool = typer.Option( + False, + "--revalidate-features/--no-revalidate-features", + help="Re-validate and re-analyze existing features even if source files haven't changed. Useful when analysis logic improved or confidence threshold changed. Default: False (only re-analyze if files changed)", + hidden=True, # Hidden by default, shown with --help-advanced ), # Advanced/Configuration (hidden by default, use --help-advanced to see) confidence: float = typer.Option( @@ -1697,7 +2065,7 @@ def from_code( **Parameter Groups:** - **Target/Input**: bundle (required argument), --repo, --entry-point, --enrichment - **Output/Results**: --report - - **Behavior/Options**: --shadow-only, --enrich-for-speckit, --force, --include-tests/--exclude-tests + - **Behavior/Options**: --shadow-only, --enrich-for-speckit, --force, --include-tests/--exclude-tests (default: exclude) - **Advanced/Configuration**: --confidence, --key-format **Examples:** @@ -1705,7 +2073,8 @@ def from_code( specfact import from-code auth-module --repo . --enrichment enrichment-report.md specfact import from-code my-project --repo . --confidence 0.7 --shadow-only specfact import from-code my-project --repo . --force # Force full regeneration - specfact import from-code my-project --repo . --exclude-tests # Exclude test files for faster processing + specfact import from-code my-project --repo . # Test files excluded by default + specfact import from-code my-project --repo . --include-tests # Include test files in dependency graph """ from specfact_cli.cli import get_current_mode from specfact_cli.modes import get_router @@ -1775,19 +2144,149 @@ def from_code( # Check if we need to regenerate features (requires full codebase scan) # Features need regeneration if: # - No incremental changes detected (new bundle) - # - Relationships need regeneration (indicates source file changes) - # - Contracts need regeneration (indicates source file changes) - # - Bundle needs regeneration (indicates features changed) - # If only graph or enrichment_context need regeneration, we can skip full scan - should_regenerate_features = incremental_changes is None or any( - incremental_changes.get(key, True) - for key in ["relationships", "contracts", "bundle"] # These indicate source file/feature changes - ) + # - Source files actually changed (not just missing relationships/contracts) + # - Revalidation requested (--revalidate-features flag) + # + # Important: Missing relationships/contracts alone should NOT trigger feature regeneration. + # If features exist (from checkpoint), we can regenerate relationships/contracts separately. + # Only regenerate features if source files actually changed. + should_regenerate_features = incremental_changes is None or revalidate_features + + # Check if source files actually changed (not just missing artifacts) + # If features exist from checkpoint, only regenerate if source files changed + if incremental_changes and not should_regenerate_features: + # Check if we have features saved (checkpoint exists) + features_dir = bundle_dir / "features" + has_features = features_dir.exists() and any(features_dir.glob("*.yaml")) + + if has_features: + # Features exist from checkpoint - check if source files actually changed + # The incremental_check already computed this, but we need to verify: + # If relationships/contracts need regeneration, it could be because: + # 1. Source files changed (should regenerate features) + # 2. Relationships/contracts are just missing (should NOT regenerate features) + # + # We can tell the difference by checking if the incremental_check detected + # source file changes. If it did, relationships will be True. + # But if relationships are True just because they're missing (not because files changed), + # we should NOT regenerate features. + # + # The incremental_check function already handles this correctly - it only marks + # relationships as needing regeneration if source files changed OR if relationships don't exist. + # So we need to check if source files actually changed by examining feature source tracking. + try: + # Load bundle to check source tracking (we'll reuse this later if we don't regenerate) + existing_bundle = _load_existing_bundle(bundle_dir) + if existing_bundle and existing_bundle.features: + # Check if any source files actually changed + # If features don't have source_tracking yet (cancelled before source linking), + # we can't check file changes, so assume files haven't changed and reuse features + source_files_changed = False + has_source_tracking = False + + for feature in existing_bundle.features: + if feature.source_tracking: + has_source_tracking = True + # Check implementation files + for impl_file in feature.source_tracking.implementation_files: + file_path = repo / impl_file + if file_path.exists() and feature.source_tracking.has_changed(file_path): + source_files_changed = True + break + if source_files_changed: + break + # Check test files + for test_file in feature.source_tracking.test_files: + file_path = repo / test_file + if file_path.exists() and feature.source_tracking.has_changed(file_path): + source_files_changed = True + break + if source_files_changed: + break + + # Only regenerate features if source files actually changed + # If features don't have source_tracking yet, assume files haven't changed + # (they were just discovered, not yet linked) + if source_files_changed: + should_regenerate_features = True + console.print("[yellow]⚠[/yellow] Source files changed - will re-analyze features\n") + else: + # Source files haven't changed (or features don't have source_tracking yet) + # Don't regenerate features, just regenerate relationships/contracts + if has_source_tracking: + console.print( + "[dim]✓[/dim] Features exist from checkpoint - will regenerate relationships/contracts only\n" + ) + else: + console.print( + "[dim]✓[/dim] Features exist from checkpoint (no source tracking yet) - will link source files and regenerate relationships/contracts\n" + ) + # Reuse the loaded bundle instead of loading again later + plan_bundle = existing_bundle + except Exception: + # If we can't check, be conservative and don't regenerate features + # (relationships/contracts will be regenerated separately) + pass + + # If revalidation is requested, show message + if revalidate_features and incremental_changes: + console.print( + "[yellow]⚠[/yellow] --revalidate-features enabled: Will re-analyze features even if files unchanged\n" + ) # If we have incremental changes and features don't need regeneration, load existing bundle + # (unless we already loaded it above to check for source file changes) if incremental_changes and not should_regenerate_features and not enrichment: - plan_bundle = _load_existing_bundle(bundle_dir) + if plan_bundle is None: + plan_bundle = _load_existing_bundle(bundle_dir) if plan_bundle: + # Validate existing features to ensure they're still valid + # Only validate if we're actually using existing features (not regenerating) + validation_results = _validate_existing_features(plan_bundle, repo) + + # Report validation results + valid_count = len(validation_results["valid_features"]) + orphaned_count = len(validation_results["orphaned_features"]) + total_checked = validation_results["total_checked"] + + # Only show validation warnings if there are actual problems (orphaned or missing files) + # Don't warn about features with no stories - that's normal for newly discovered features + features_with_missing_files = [ + key + for key in validation_results["invalid_features"] + if validation_results["missing_files"].get(key) + ] + + if orphaned_count > 0 or features_with_missing_files: + console.print("[cyan]🔍 Validating existing features...[/cyan]") + console.print( + f"[yellow]⚠[/yellow] Feature validation found issues: {valid_count}/{total_checked} valid, " + f"{orphaned_count} orphaned, {len(features_with_missing_files)} with missing files" + ) + + # Show orphaned features + if orphaned_count > 0: + console.print("[red] Orphaned features (all source files missing):[/red]") + for feature_key in validation_results["orphaned_features"][:5]: # Show first 5 + missing = validation_results["missing_files"].get(feature_key, []) + console.print(f" [dim]- {feature_key}[/dim] ({len(missing)} missing files)") + if orphaned_count > 5: + console.print(f" [dim]... and {orphaned_count - 5} more[/dim]") + + # Show invalid features (only those with missing files) + if features_with_missing_files: + console.print("[yellow] Features with missing files:[/yellow]") + for feature_key in features_with_missing_files[:5]: # Show first 5 + missing = validation_results["missing_files"].get(feature_key, []) + console.print(f" [dim]- {feature_key}[/dim] ({len(missing)} missing files)") + if len(features_with_missing_files) > 5: + console.print(f" [dim]... and {len(features_with_missing_files) - 5} more[/dim]") + + console.print( + "[dim] Tip: Use --revalidate-features to re-analyze features and fix issues[/dim]\n" + ) + # Don't show validation message if all features are valid (no noise) + console.print("[dim]Skipping codebase analysis (features unchanged)[/dim]\n") if plan_bundle is None: @@ -1824,6 +2323,13 @@ def on_incremental_update(features_count: int, themes: list[str]) -> None: console.print(f"[green]✓[/green] Total stories: {total_stories}\n") record_event({"features_detected": len(plan_bundle.features), "stories_detected": total_stories}) + # Save features immediately after analysis to avoid losing work if process is cancelled + # This ensures we can resume from this point if interrupted during expensive operations + console.print("[cyan]💾 Saving features (checkpoint)...[/cyan]") + project_bundle = _convert_plan_bundle_to_project_bundle(plan_bundle, bundle) + save_bundle_with_progress(project_bundle, bundle_dir, atomic=True, console_instance=console) + console.print("[dim]✓ Features saved (can resume if interrupted)[/dim]\n") + # Ensure plan_bundle is not None before proceeding if plan_bundle is None: console.print("[bold red]✗ No plan bundle available[/bold red]") diff --git a/src/specfact_cli/models/project.py b/src/specfact_cli/models/project.py index d85eafc..ac9cc99 100644 --- a/src/specfact_cli/models/project.py +++ b/src/specfact_cli/models/project.py @@ -282,10 +282,16 @@ def load_from_directory( # Load artifacts in parallel using ThreadPoolExecutor # In test mode, use fewer workers to avoid resource contention + # Note: YAML parsing and Pydantic validation are CPU-bound, not I/O-bound + # Too many workers can cause contention and slowdown due to GIL and memory pressure if os.environ.get("TEST_MODE") == "true": max_workers = max(1, min(2, len(load_tasks))) # Max 2 workers in test mode else: - max_workers = min(os.cpu_count() or 4, 8, len(load_tasks)) # Cap at 8 workers + # Optimal worker count balances parallelism with overhead + # For CPU-bound tasks (YAML parsing + Pydantic validation), more workers != faster + # Use CPU count as baseline, but cap at 8 to avoid contention + cpu_count = os.cpu_count() or 4 + max_workers = min(cpu_count, 8, len(load_tasks)) completed_count = current def load_artifact(artifact_name: str, artifact_path: Path, validator: Callable) -> tuple[str, Any]: @@ -445,7 +451,9 @@ def save_to_directory( self.manifest.bundle["format"] = "directory-based" # Prepare tasks for parallel saving (all artifacts except manifest) - save_tasks: list[tuple[str, Path, dict[str, Any]]] = [] + # Note: Features are passed as Feature objects (model_dump() called in parallel) + # Aspects (idea, business, product) are pre-dumped as dicts + save_tasks: list[tuple[str, Path, dict[str, Any] | Feature]] = [] # Add aspect saving tasks if self.idea: @@ -469,6 +477,9 @@ def save_to_directory( if not isinstance(self.features, dict): raise ValueError(f"Expected features to be dict, got {type(self.features)}") + # Pre-compute feature paths (fast operation) + # Note: model_dump() is called inside parallel task to avoid sequential bottleneck + # This prevents sequential serialization of 500+ features before parallel processing starts for key, feature in self.features.items(): # Ensure key is a string, not a FeatureIndex or other object if not isinstance(key, str): @@ -479,23 +490,76 @@ def save_to_directory( feature_file = f"{key}.yaml" feature_path = features_dir / feature_file - save_tasks.append((f"features/{feature_file}", feature_path, feature.model_dump())) + # Pass Feature object instead of dict - model_dump() will be called in parallel + save_tasks.append((f"features/{feature_file}", feature_path, feature)) # Save artifacts in parallel using ThreadPoolExecutor # In test mode, use fewer workers to avoid resource contention + # For large bundles (1000+ features), reduce workers to manage memory usage + # Memory optimization: Each worker keeps model_dump() copy + serialized content in memory if os.environ.get("TEST_MODE") == "true": max_workers = max(1, min(2, len(save_tasks))) # Max 2 workers in test mode else: - max_workers = min(os.cpu_count() or 4, 8, len(save_tasks)) # Cap at 8 workers + cpu_count = os.cpu_count() or 4 + # Reduce workers for large bundles to manage memory (4GB+ usage reported) + # With 2000+ features, 8 workers can use 4GB+ memory (each feature ~2MB serialized) + if num_features > 1000: + # For large bundles, use fewer workers to reduce peak memory + max_workers = min(cpu_count, 4, len(save_tasks)) # Cap at 4 workers for large bundles + else: + max_workers = min(cpu_count, 8, len(save_tasks)) # Cap at 8 workers for smaller bundles completed_count = 0 checksums: dict[str, str] = {} # Track checksums for manifest update - feature_indices: list[FeatureIndex] = [] # Track feature indices + # Pre-allocate feature_indices list to avoid repeated resizing (performance optimization) + # Use None as placeholder, will be replaced with actual FeatureIndex objects + num_features = len(self.features) + feature_indices: list[FeatureIndex | None] = [None] * num_features + # Pre-compute feature key to index mapping for O(1) lookup during result processing + feature_key_to_save_index: dict[str, int] = {} + for save_index, key in enumerate(self.features): + feature_key_to_save_index[key] = save_index - def save_artifact(artifact_name: str, artifact_path: Path, data: dict[str, Any]) -> tuple[str, str]: + def save_artifact(artifact_name: str, artifact_path: Path, data: dict[str, Any] | Feature) -> tuple[str, str]: """Save a single artifact and return (name, checksum).""" - dump_structured_file(data, artifact_path) - # Compute checksum after file is written (static method) - checksum = ProjectBundle._compute_file_checksum(artifact_path) + import hashlib + + # Handle Feature objects (call model_dump() in parallel) vs pre-dumped dicts + # Feature object - serialize in parallel (avoids sequential bottleneck) + # Pre-serialized dict (for aspects like idea, business, product) + dump_data = data.model_dump() if isinstance(data, Feature) else data + + # Compute checksum during serialization to avoid reading file back (memory optimization) + # This reduces memory usage significantly by avoiding duplicate file content in memory + hash_obj = hashlib.sha256() + from specfact_cli.utils.structured_io import StructuredFormat + + path = Path(artifact_path) + path.parent.mkdir(parents=True, exist_ok=True) + fmt = StructuredFormat.from_path(path) + + if fmt == StructuredFormat.JSON: + import json + + content = json.dumps(dump_data, indent=2).encode("utf-8") + hash_obj.update(content) + path.write_bytes(content) + else: + # For YAML, serialize to string first, then hash and write + # This avoids reading file back for checksum computation + from specfact_cli.utils.structured_io import _get_yaml_instance + + yaml_instance = _get_yaml_instance() + # Quote boolean-like strings to prevent YAML parsing issues + quoted_data = yaml_instance._quote_boolean_like_strings(dump_data) + # Serialize to string, then hash and write + yaml_content = yaml_instance.dump_string(quoted_data) + yaml_bytes = yaml_content.encode("utf-8") + hash_obj.update(yaml_bytes) + path.write_bytes(yaml_bytes) + + checksum = hash_obj.hexdigest() + # Clear large objects to help GC (memory optimization) + del dump_data return (artifact_name, checksum) if save_tasks: @@ -521,11 +585,13 @@ def save_artifact(artifact_name: str, artifact_path: Path, data: dict[str, Any]) if progress_callback: progress_callback(completed_count, total_artifacts, artifact_name) - # Build feature indices for features + # Build feature indices for features (optimized with pre-allocated list) if artifact_name.startswith("features/"): feature_file = artifact_name.split("/", 1)[1] key = feature_file.replace(".yaml", "") - if key in self.features: + # Use pre-computed mapping for O(1) lookup (avoids dictionary lookup in self.features) + if key in feature_key_to_save_index: + save_idx = feature_key_to_save_index[key] feature = self.features[key] feature_index = FeatureIndex( key=key, @@ -538,7 +604,8 @@ def save_artifact(artifact_name: str, artifact_path: Path, data: dict[str, Any]) contract=feature.contract, # Link contract from feature checksum=checksum, ) - feature_indices.append(feature_index) + # Direct assignment to pre-allocated list (avoids list.append() resizing) + feature_indices[save_idx] = feature_index except KeyboardInterrupt: interrupted = True for f in future_to_task: @@ -571,7 +638,8 @@ def save_artifact(artifact_name: str, artifact_path: Path, data: dict[str, Any]) # Update manifest with checksums and feature indices self.manifest.checksums.files.update(checksums) - self.manifest.features = feature_indices + # Filter out None placeholders (shouldn't happen, but safety check) + self.manifest.features = [idx for idx in feature_indices if idx is not None] # Save manifest (last, after all checksums are computed) if progress_callback: diff --git a/src/specfact_cli/utils/source_scanner.py b/src/specfact_cli/utils/source_scanner.py index 5b80b08..52585ca 100644 --- a/src/specfact_cli/utils/source_scanner.py +++ b/src/specfact_cli/utils/source_scanner.py @@ -15,9 +15,15 @@ from beartype import beartype from icontract import ensure, require +from rich.console import Console +from rich.progress import Progress from specfact_cli.models.plan import Feature from specfact_cli.models.source_tracking import SourceTracking +from specfact_cli.utils.terminal import get_progress_config + + +console = Console() @dataclass @@ -72,7 +78,18 @@ def scan_repository(self) -> SourceArtifactMap: return artifact_map def _link_feature_to_specs( - self, feature: Feature, repo_path: Path, impl_files: list[Path], test_files: list[Path] + self, + feature: Feature, + repo_path: Path, + impl_files: list[Path], + test_files: list[Path], + file_functions_cache: dict[str, list[str]] | None = None, + file_test_functions_cache: dict[str, list[str]] | None = None, + file_hashes_cache: dict[str, str] | None = None, + impl_files_by_stem: dict[str, list[Path]] | None = None, + test_files_by_stem: dict[str, list[Path]] | None = None, + impl_stems_by_substring: dict[str, set[str]] | None = None, + test_stems_by_substring: dict[str, set[str]] | None = None, ) -> None: """ Link a single feature to matching files (thread-safe helper). @@ -82,61 +99,188 @@ def _link_feature_to_specs( repo_path: Repository path impl_files: Pre-collected implementation files test_files: Pre-collected test files + file_functions_cache: Pre-computed function mappings cache (file_path -> [functions]) + file_test_functions_cache: Pre-computed test function mappings cache (file_path -> [test_functions]) + file_hashes_cache: Pre-computed file hashes cache (file_path -> hash) """ if feature.source_tracking is None: feature.source_tracking = SourceTracking() + # Initialize caches if not provided (for backward compatibility) + if file_functions_cache is None: + file_functions_cache = {} + if file_test_functions_cache is None: + file_test_functions_cache = {} + if file_hashes_cache is None: + file_hashes_cache = {} + if impl_files_by_stem is None: + impl_files_by_stem = {} + if test_files_by_stem is None: + test_files_by_stem = {} + if impl_stems_by_substring is None: + impl_stems_by_substring = {} + if test_stems_by_substring is None: + test_stems_by_substring = {} + # Try to match feature key/title to files feature_key_lower = feature.key.lower() - feature_title_lower = feature.title.lower() - - # Search for matching implementation files - for file_path in impl_files: - if self._is_implementation_file(file_path): - file_name_lower = file_path.stem.lower() - # Simple matching: check if feature key or title appears in filename - if feature_key_lower in file_name_lower or any( - word in file_name_lower for word in feature_title_lower.split() if len(word) > 3 - ): + feature_title_words = [w for w in feature.title.lower().split() if len(w) > 3] + + # Use indexed lookup for O(1) file matching instead of O(n) iteration + # This is much faster for large codebases with many features + matched_impl_files: set[str] = set() + matched_test_files: set[str] = set() + + # Strategy: Use inverted index for O(1) candidate lookup instead of O(n) iteration + # This eliminates the slowdown that occurs when iterating through all stems + + # 1. Check if feature key matches any file stem directly (fastest path - O(1)) + if feature_key_lower in impl_files_by_stem: + for file_path in impl_files_by_stem[feature_key_lower]: + rel_path = str(file_path.relative_to(repo_path)) + matched_impl_files.add(rel_path) + + # 2. Check if any title word matches file stems exactly (O(k) where k = number of title words) + for word in feature_title_words: + if word in impl_files_by_stem: + for file_path in impl_files_by_stem[word]: rel_path = str(file_path.relative_to(repo_path)) - if rel_path not in feature.source_tracking.implementation_files: - feature.source_tracking.implementation_files.append(rel_path) - # Compute and store hash - feature.source_tracking.update_hash(file_path) + matched_impl_files.add(rel_path) - # Search for matching test files - for file_path in test_files: - if self._is_test_file(file_path): - file_name_lower = file_path.stem.lower() - # Match test files to features - if feature_key_lower in file_name_lower or any( - word in file_name_lower for word in feature_title_lower.split() if len(word) > 3 - ): + # 3. Use inverted index for O(1) candidate stem lookup (much faster than O(n) iteration) + # Build candidate stems using the inverted index + # Optimization: Use set union instead of multiple updates to avoid repeated hash operations + candidate_stems: set[str] = set() + + # Collect all sets to union in one operation (more efficient than multiple updates) + sets_to_union: list[set[str]] = [] + + # Check feature key in inverted index + if feature_key_lower in impl_stems_by_substring: + sets_to_union.append(impl_stems_by_substring[feature_key_lower]) + + # Check each title word in inverted index + for word in feature_title_words: + if word in impl_stems_by_substring: + sets_to_union.append(impl_stems_by_substring[word]) + + # Union all sets at once (more efficient than multiple updates) + if sets_to_union: + candidate_stems = set().union(*sets_to_union) + + # Check only candidate stems (much smaller set, found via O(1) lookup) + for stem in candidate_stems: + if stem in impl_files_by_stem: + for file_path in impl_files_by_stem[stem]: + rel_path = str(file_path.relative_to(repo_path)) + matched_impl_files.add(rel_path) + + # Add matched implementation files to feature + for rel_path in matched_impl_files: + if rel_path not in feature.source_tracking.implementation_files: + feature.source_tracking.implementation_files.append(rel_path) + # Use cached hash if available (all hashes should be pre-computed) + if rel_path in file_hashes_cache: + feature.source_tracking.file_hashes[rel_path] = file_hashes_cache[rel_path] + else: + # Fallback: compute hash if not in cache (shouldn't happen, but safe fallback) + file_path = repo_path / rel_path + if file_path.exists(): + feature.source_tracking.update_hash(file_path) + + # Check if feature key matches any test file stem directly (O(1)) + if feature_key_lower in test_files_by_stem: + for file_path in test_files_by_stem[feature_key_lower]: + rel_path = str(file_path.relative_to(repo_path)) + matched_test_files.add(rel_path) + + # Check if any title word matches test file stems exactly (O(k)) + for word in feature_title_words: + if word in test_files_by_stem: + for file_path in test_files_by_stem[word]: rel_path = str(file_path.relative_to(repo_path)) - if rel_path not in feature.source_tracking.test_files: - feature.source_tracking.test_files.append(rel_path) - # Compute and store hash - feature.source_tracking.update_hash(file_path) + matched_test_files.add(rel_path) + + # Use inverted index for O(1) candidate test stem lookup + # Optimization: Use set union instead of multiple updates + candidate_test_stems: set[str] = set() + + # Collect all sets to union in one operation (more efficient than multiple updates) + test_sets_to_union: list[set[str]] = [] + + # Check feature key in inverted index + if feature_key_lower in test_stems_by_substring: + test_sets_to_union.append(test_stems_by_substring[feature_key_lower]) + + # Check each title word in inverted index + for word in feature_title_words: + if word in test_stems_by_substring: + test_sets_to_union.append(test_stems_by_substring[word]) - # Extract function mappings for stories + # Union all sets at once (more efficient than multiple updates) + if test_sets_to_union: + candidate_test_stems = set().union(*test_sets_to_union) + + # Check only candidate test stems (found via O(1) lookup) + for stem in candidate_test_stems: + if stem in test_files_by_stem: + for file_path in test_files_by_stem[stem]: + rel_path = str(file_path.relative_to(repo_path)) + matched_test_files.add(rel_path) + + # Add matched test files to feature + for rel_path in matched_test_files: + if rel_path not in feature.source_tracking.test_files: + feature.source_tracking.test_files.append(rel_path) + # Use cached hash if available (all hashes should be pre-computed) + if rel_path in file_hashes_cache: + feature.source_tracking.file_hashes[rel_path] = file_hashes_cache[rel_path] + else: + # Fallback: compute hash if not in cache (shouldn't happen, but safe fallback) + file_path = repo_path / rel_path + if file_path.exists(): + feature.source_tracking.update_hash(file_path) + + # Extract function mappings for stories using cached results + # Optimization: Use sets for O(1) lookups instead of O(n) list membership checks + # This prevents slowdown as stories accumulate more function mappings for story in feature.stories: + # Convert to sets for fast lookups (only if we need to add many items) + # For small lists, the overhead isn't worth it, but for large lists it's critical + source_functions_set = set(story.source_functions) if story.source_functions else set() + test_functions_set = set(story.test_functions) if story.test_functions else set() + for impl_file in feature.source_tracking.implementation_files: - file_path = repo_path / impl_file - if file_path.exists(): - functions = self.extract_function_mappings(file_path) - for func_name in functions: - func_mapping = f"{impl_file}::{func_name}" - if func_mapping not in story.source_functions: - story.source_functions.append(func_mapping) + # Use cached functions if available (all functions should be pre-computed) + if impl_file in file_functions_cache: + functions = file_functions_cache[impl_file] + else: + # Fallback: compute if not in cache (shouldn't happen, but safe fallback) + file_path = repo_path / impl_file + functions = self.extract_function_mappings(file_path) if file_path.exists() else [] + + for func_name in functions: + func_mapping = f"{impl_file}::{func_name}" + if func_mapping not in source_functions_set: + source_functions_set.add(func_mapping) for test_file in feature.source_tracking.test_files: - file_path = repo_path / test_file - if file_path.exists(): - test_functions = self.extract_test_mappings(file_path) - for test_func_name in test_functions: - test_mapping = f"{test_file}::{test_func_name}" - if test_mapping not in story.test_functions: - story.test_functions.append(test_mapping) + # Use cached test functions if available (all test functions should be pre-computed) + if test_file in file_test_functions_cache: + test_functions = file_test_functions_cache[test_file] + else: + # Fallback: compute if not in cache (shouldn't happen, but safe fallback) + file_path = repo_path / test_file + test_functions = self.extract_test_mappings(file_path) if file_path.exists() else [] + + for test_func_name in test_functions: + test_mapping = f"{test_file}::{test_func_name}" + if test_mapping not in test_functions_set: + test_functions_set.add(test_mapping) + + # Convert back to lists (Pydantic models expect lists) + story.source_functions = list(source_functions_set) + story.test_functions = list(test_functions_set) # Update sync timestamp feature.source_tracking.update_sync_timestamp() @@ -172,7 +316,103 @@ def link_to_specs(self, features: list[Feature], repo_path: Path | None = None) impl_files = list(set(impl_files)) test_files = list(set(test_files)) - # Process features in parallel + # Pre-compute caches to avoid repeated AST parsing and hash computation + # This is a major performance optimization for large codebases + console.print("[dim]Pre-computing file caches (AST parsing, hashes)...[/dim]") + file_functions_cache: dict[str, list[str]] = {} + file_test_functions_cache: dict[str, list[str]] = {} + file_hashes_cache: dict[str, str] = {} + + # Pre-index files by stem (filename without extension) for O(1) lookup + # This avoids iterating through all files for each feature + impl_files_by_stem: dict[str, list[Path]] = {} # stem -> [file_paths] + test_files_by_stem: dict[str, list[Path]] = {} # stem -> [file_paths] + + # Build inverted index: for each word/substring, track which stems contain it + # This allows O(1) lookup of candidate stems instead of O(n) iteration + impl_stems_by_substring: dict[str, set[str]] = {} # substring -> {stems} + test_stems_by_substring: dict[str, set[str]] = {} # substring -> {stems} + + # Pre-parse all implementation files once and index by stem + for file_path in impl_files: + if self._is_implementation_file(file_path): + rel_path = str(file_path.relative_to(repo_path)) + stem = file_path.stem.lower() + + # Index by stem for fast lookup + if stem not in impl_files_by_stem: + impl_files_by_stem[stem] = [] + impl_files_by_stem[stem].append(file_path) + + # Build inverted index: extract all meaningful substrings from stem + # (words separated by underscores, and the full stem) + stem_parts = stem.split("_") + for part in stem_parts: + if len(part) > 2: # Only index meaningful substrings + if part not in impl_stems_by_substring: + impl_stems_by_substring[part] = set() + impl_stems_by_substring[part].add(stem) + # Also index the full stem + if stem not in impl_stems_by_substring: + impl_stems_by_substring[stem] = set() + impl_stems_by_substring[stem].add(stem) + + # Cache functions + if rel_path not in file_functions_cache: + functions = self.extract_function_mappings(file_path) + file_functions_cache[rel_path] = functions + + # Cache hash + if rel_path not in file_hashes_cache and file_path.exists(): + try: + source_tracking = SourceTracking() + source_tracking.update_hash(file_path) + file_hashes_cache[rel_path] = source_tracking.file_hashes.get(rel_path, "") + except Exception: + pass # Skip files that can't be hashed + + # Pre-parse all test files once and index by stem + for file_path in test_files: + if self._is_test_file(file_path): + rel_path = str(file_path.relative_to(repo_path)) + stem = file_path.stem.lower() + + # Index by stem for fast lookup + if stem not in test_files_by_stem: + test_files_by_stem[stem] = [] + test_files_by_stem[stem].append(file_path) + + # Build inverted index for test files + stem_parts = stem.split("_") + for part in stem_parts: + if len(part) > 2: # Only index meaningful substrings + if part not in test_stems_by_substring: + test_stems_by_substring[part] = set() + test_stems_by_substring[part].add(stem) + # Also index the full stem + if stem not in test_stems_by_substring: + test_stems_by_substring[stem] = set() + test_stems_by_substring[stem].add(stem) + + # Cache test functions + if rel_path not in file_test_functions_cache: + test_functions = self.extract_test_mappings(file_path) + file_test_functions_cache[rel_path] = test_functions + + # Cache hash + if rel_path not in file_hashes_cache and file_path.exists(): + try: + source_tracking = SourceTracking() + source_tracking.update_hash(file_path) + file_hashes_cache[rel_path] = source_tracking.file_hashes.get(rel_path, "") + except Exception: + pass # Skip files that can't be hashed + + console.print( + f"[dim]✓ Cached {len(file_functions_cache)} implementation files, {len(file_test_functions_cache)} test files[/dim]" + ) + + # Process features in parallel with progress reporting # In test mode, use fewer workers to avoid resource contention if os.environ.get("TEST_MODE") == "true": max_workers = max(1, min(2, len(features))) # Max 2 workers in test mode @@ -183,40 +423,79 @@ def link_to_specs(self, features: list[Feature], repo_path: Path | None = None) interrupted = False # In test mode, use wait=False to avoid hanging on shutdown wait_on_shutdown = os.environ.get("TEST_MODE") != "true" - try: - future_to_feature = { - executor.submit(self._link_feature_to_specs, feature, repo_path, impl_files, test_files): feature - for feature in features - } + + # Add progress reporting + progress_columns, progress_kwargs = get_progress_config() + with Progress( + *progress_columns, + console=console, + **progress_kwargs, + ) as progress: + task = progress.add_task( + f"[cyan]Linking {len(features)} features to source files...", + total=len(features), + ) + try: - for future in as_completed(future_to_feature): - try: - future.result() # Wait for completion - except KeyboardInterrupt: - interrupted = True - for f in future_to_feature: - if not f.done(): - f.cancel() - break - except Exception: - # Suppress other exceptions (same as before) - pass + future_to_feature = { + executor.submit( + self._link_feature_to_specs, + feature, + repo_path, + impl_files, + test_files, + file_functions_cache, + file_test_functions_cache, + file_hashes_cache, + impl_files_by_stem, + test_files_by_stem, + impl_stems_by_substring, + test_stems_by_substring, + ): feature + for feature in features + } + completed_count = 0 + try: + for future in as_completed(future_to_feature): + try: + future.result() # Wait for completion + completed_count += 1 + # Update progress with meaningful description + progress.update( + task, + completed=completed_count, + description=f"[cyan]Linking features to source files... ({completed_count}/{len(features)} features)", + ) + except KeyboardInterrupt: + interrupted = True + for f in future_to_feature: + if not f.done(): + f.cancel() + break + except Exception: + # Suppress other exceptions but still count as completed + completed_count += 1 + progress.update( + task, + completed=completed_count, + description=f"[cyan]Linking features to source files... ({completed_count}/{len(features)})", + ) + except KeyboardInterrupt: + interrupted = True + for f in future_to_feature: + if not f.done(): + f.cancel() + if interrupted: + raise KeyboardInterrupt except KeyboardInterrupt: interrupted = True - for f in future_to_feature: - if not f.done(): - f.cancel() - if interrupted: - raise KeyboardInterrupt - except KeyboardInterrupt: - interrupted = True - executor.shutdown(wait=False, cancel_futures=True) - raise - finally: - if not interrupted: - executor.shutdown(wait=wait_on_shutdown) - else: - executor.shutdown(wait=False) + executor.shutdown(wait=False, cancel_futures=True) + raise + finally: + if not interrupted: + executor.shutdown(wait=wait_on_shutdown) + else: + executor.shutdown(wait=False) @beartype @require(lambda self, file_path: isinstance(file_path, Path), "File path must be Path") diff --git a/src/specfact_cli/utils/yaml_utils.py b/src/specfact_cli/utils/yaml_utils.py index f0eb8b6..da4d886 100644 --- a/src/specfact_cli/utils/yaml_utils.py +++ b/src/specfact_cli/utils/yaml_utils.py @@ -109,6 +109,10 @@ def _quote_boolean_like_strings(self, data: Any) -> Any: YAML parsers interpret "Yes", "No", "True", "False", "On", "Off" as booleans unless they're quoted. This function ensures these values are quoted. + Optimized: early exit for simple types, avoids unnecessary recursion overhead. + For large structures (>100 items), processes directly without pre-check to avoid + double traversal overhead. + Args: data: Data structure to process @@ -118,13 +122,38 @@ def _quote_boolean_like_strings(self, data: Any) -> Any: # Boolean-like strings that YAML parsers interpret as booleans boolean_like_strings = {"yes", "no", "true", "false", "on", "off", "Yes", "No", "True", "False", "On", "Off"} + # Early exit for simple types (most common case) + if isinstance(data, str): + return DoubleQuotedScalarString(data) if data in boolean_like_strings else data + if not isinstance(data, (dict, list)): + return data + + # Recursive processing for collections if isinstance(data, dict): + # For large dicts, process directly to avoid double traversal (check + process) + # The overhead of checking all items is similar to processing them + if len(data) > 100: + return {k: self._quote_boolean_like_strings(v) for k, v in data.items()} + # For smaller dicts, check first to avoid creating new dict if not needed + needs_processing = any( + (isinstance(v, str) and v in boolean_like_strings) or isinstance(v, (dict, list)) for v in data.values() + ) + if not needs_processing: + return data return {k: self._quote_boolean_like_strings(v) for k, v in data.items()} if isinstance(data, list): + # For large lists, process directly to avoid double traversal (check + process) + # The overhead of checking all items is similar to processing them + if len(data) > 100: + return [self._quote_boolean_like_strings(item) for item in data] + # For smaller lists, check first to avoid creating new list if not needed + needs_processing = any( + (isinstance(item, str) and item in boolean_like_strings) or isinstance(item, (dict, list)) + for item in data + ) + if not needs_processing: + return data return [self._quote_boolean_like_strings(item) for item in data] - if isinstance(data, str) and data in boolean_like_strings: - # Use DoubleQuotedScalarString to force quoting in YAML output - return DoubleQuotedScalarString(data) return data @beartype diff --git a/tests/integration/commands/test_import_command.py b/tests/integration/commands/test_import_command.py index 8b149db..b6a3fed 100644 --- a/tests/integration/commands/test_import_command.py +++ b/tests/integration/commands/test_import_command.py @@ -296,3 +296,46 @@ def create_resource_{i}(): # Should have generated contracts for multiple features (if features were detected) # May be 0 if no contracts detected, which is OK assert len(contract_files) >= 0 + + @pytest.mark.timeout(20) + def test_import_revalidate_features_flag_exists(self, tmp_path: Path) -> None: + """Test that --revalidate-features flag is accepted by the command.""" + import os + + # Ensure TEST_MODE is set to skip Semgrep + os.environ["TEST_MODE"] = "true" + + # Create initial codebase + api_file = tmp_path / "api.py" + api_file.write_text( + ''' +class UserService: + """User management service.""" + + def create_user(self, name: str): + """Create a new user.""" + return {"id": 1, "name": name} +''' + ) + + runner = CliRunner() + + # Test that the flag is accepted (doesn't cause argument parsing error) + result = runner.invoke( + app, + [ + "import", + "from-code", + "test-bundle-revalidate", + "--repo", + str(tmp_path), + "--confidence", + "0.3", + "--revalidate-features", + ], + ) + + # Command should not fail due to unknown argument + # Exit code 0 or 1 is acceptable (1 might mean no features detected or other issues) + # Exit code 2 would indicate argument parsing error + assert result.exit_code != 2, "Flag should be recognized" diff --git a/tests/unit/commands/test_import_feature_validation.py b/tests/unit/commands/test_import_feature_validation.py new file mode 100644 index 0000000..5ad5b3c --- /dev/null +++ b/tests/unit/commands/test_import_feature_validation.py @@ -0,0 +1,475 @@ +""" +Unit tests for feature validation in import command. + +Tests the _validate_existing_features function and related validation logic. +""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from specfact_cli.commands.import_cmd import _validate_existing_features +from specfact_cli.models.plan import Feature, PlanBundle, Product, SourceTracking, Story + + +@pytest.fixture +def sample_repo_path(tmp_path: Path) -> Path: + """Create a sample repository with some files.""" + repo = tmp_path / "repo" + repo.mkdir() + + # Create some source files + (repo / "src").mkdir() + (repo / "src" / "service.py").write_text("class Service: pass\n") + (repo / "src" / "utils.py").write_text("def helper(): pass\n") + + # Create some test files + (repo / "tests").mkdir() + (repo / "tests" / "test_service.py").write_text("def test_service(): pass\n") + + return repo + + +@pytest.fixture +def valid_plan_bundle(sample_repo_path: Path) -> PlanBundle: + """Create a plan bundle with valid features (all source files exist).""" + return PlanBundle( + version="1.0", + product=Product(themes=["Testing"]), + features=[ + Feature( + key="FEATURE-001", + title="Valid Feature", + outcomes=["Outcome 1"], + acceptance=["AC 1"], + stories=[ + Story( + key="STORY-001", + title="Valid Story", + acceptance=["Story AC 1"], + story_points=None, + value_points=None, + scenarios=None, + contracts=None, + ) + ], + source_tracking=SourceTracking( + implementation_files=["src/service.py"], + test_files=["tests/test_service.py"], + source_functions=[], + test_functions=[], + ), + contract=None, + protocol=None, + ) + ], + idea=None, + business=None, + metadata=None, + clarifications=None, + ) + + +@pytest.fixture +def orphaned_plan_bundle(sample_repo_path: Path) -> PlanBundle: + """Create a plan bundle with orphaned features (all source files missing).""" + return PlanBundle( + version="1.0", + product=Product(themes=["Testing"]), + features=[ + Feature( + key="FEATURE-002", + title="Orphaned Feature", + outcomes=["Outcome 1"], + acceptance=["AC 1"], + stories=[ + Story( + key="STORY-002", + title="Orphaned Story", + acceptance=["Story AC 1"], + story_points=None, + value_points=None, + scenarios=None, + contracts=None, + ) + ], + source_tracking=SourceTracking( + implementation_files=["src/nonexistent.py"], + test_files=["tests/nonexistent_test.py"], + source_functions=[], + test_functions=[], + ), + contract=None, + protocol=None, + ) + ], + idea=None, + business=None, + metadata=None, + clarifications=None, + ) + + +@pytest.fixture +def invalid_plan_bundle(sample_repo_path: Path) -> PlanBundle: + """Create a plan bundle with invalid features (some files missing).""" + return PlanBundle( + version="1.0", + product=Product(themes=["Testing"]), + features=[ + Feature( + key="FEATURE-003", + title="Invalid Feature", + outcomes=["Outcome 1"], + acceptance=["AC 1"], + stories=[ + Story( + key="STORY-003", + title="Invalid Story", + acceptance=["Story AC 1"], + story_points=None, + value_points=None, + scenarios=None, + contracts=None, + ) + ], + source_tracking=SourceTracking( + implementation_files=["src/service.py", "src/missing.py"], + test_files=["tests/test_service.py"], + source_functions=[], + test_functions=[], + ), + contract=None, + protocol=None, + ) + ], + idea=None, + business=None, + metadata=None, + clarifications=None, + ) + + +@pytest.fixture +def mixed_plan_bundle(sample_repo_path: Path) -> PlanBundle: + """Create a plan bundle with mixed valid, orphaned, and invalid features.""" + return PlanBundle( + version="1.0", + product=Product(themes=["Testing"]), + features=[ + # Valid feature + Feature( + key="FEATURE-001", + title="Valid Feature", + outcomes=["Outcome 1"], + acceptance=["AC 1"], + stories=[ + Story( + key="STORY-001", + title="Valid Story", + acceptance=["Story AC 1"], + story_points=None, + value_points=None, + scenarios=None, + contracts=None, + ) + ], + source_tracking=SourceTracking( + implementation_files=["src/service.py"], + test_files=["tests/test_service.py"], + source_functions=[], + test_functions=[], + ), + contract=None, + protocol=None, + ), + # Orphaned feature + Feature( + key="FEATURE-002", + title="Orphaned Feature", + outcomes=["Outcome 2"], + acceptance=["AC 2"], + stories=[ + Story( + key="STORY-002", + title="Orphaned Story", + acceptance=["Story AC 2"], + story_points=None, + value_points=None, + scenarios=None, + contracts=None, + ) + ], + source_tracking=SourceTracking( + implementation_files=["src/nonexistent.py"], + test_files=["tests/nonexistent_test.py"], + source_functions=[], + test_functions=[], + ), + contract=None, + protocol=None, + ), + # Invalid feature (some files missing) + Feature( + key="FEATURE-003", + title="Invalid Feature", + outcomes=["Outcome 3"], + acceptance=["AC 3"], + stories=[ + Story( + key="STORY-003", + title="Invalid Story", + acceptance=["Story AC 3"], + story_points=None, + value_points=None, + scenarios=None, + contracts=None, + ) + ], + source_tracking=SourceTracking( + implementation_files=["src/service.py", "src/missing.py"], + test_files=["tests/test_service.py"], + source_functions=[], + test_functions=[], + ), + contract=None, + protocol=None, + ), + # Feature without source tracking + Feature( + key="FEATURE-004", + title="No Source Tracking", + outcomes=["Outcome 4"], + acceptance=["AC 4"], + stories=[], + source_tracking=None, + contract=None, + protocol=None, + ), + # Feature with empty stories (structure issue) + Feature( + key="FEATURE-005", + title="Empty Stories", + outcomes=["Outcome 5"], + acceptance=["AC 5"], + stories=[], + source_tracking=SourceTracking( + implementation_files=["src/service.py"], + test_files=[], + source_functions=[], + test_functions=[], + ), + contract=None, + protocol=None, + ), + ], + idea=None, + business=None, + metadata=None, + clarifications=None, + ) + + +class TestValidateExistingFeatures: + """Test suite for _validate_existing_features function.""" + + def test_validate_all_valid_features(self, valid_plan_bundle: PlanBundle, sample_repo_path: Path) -> None: + """Test validation with all valid features.""" + results = _validate_existing_features(valid_plan_bundle, sample_repo_path) + + assert results["total_checked"] == 1 + assert len(results["valid_features"]) == 1 + assert results["valid_features"] == ["FEATURE-001"] + assert len(results["orphaned_features"]) == 0 + assert len(results["invalid_features"]) == 0 + assert len(results["missing_files"]) == 0 + + def test_validate_orphaned_features(self, orphaned_plan_bundle: PlanBundle, sample_repo_path: Path) -> None: + """Test validation with orphaned features (all files missing).""" + results = _validate_existing_features(orphaned_plan_bundle, sample_repo_path) + + assert results["total_checked"] == 1 + assert len(results["valid_features"]) == 0 + assert len(results["orphaned_features"]) == 1 + assert results["orphaned_features"] == ["FEATURE-002"] + assert len(results["invalid_features"]) == 0 + assert "FEATURE-002" in results["missing_files"] + assert len(results["missing_files"]["FEATURE-002"]) == 2 # Both files missing + + def test_validate_invalid_features(self, invalid_plan_bundle: PlanBundle, sample_repo_path: Path) -> None: + """Test validation with invalid features (some files missing).""" + results = _validate_existing_features(invalid_plan_bundle, sample_repo_path) + + assert results["total_checked"] == 1 + assert len(results["valid_features"]) == 0 + assert len(results["orphaned_features"]) == 0 + assert len(results["invalid_features"]) == 1 + assert results["invalid_features"] == ["FEATURE-003"] + assert "FEATURE-003" in results["missing_files"] + assert len(results["missing_files"]["FEATURE-003"]) == 1 # One file missing + assert "src/missing.py" in results["missing_files"]["FEATURE-003"] + + def test_validate_mixed_features(self, mixed_plan_bundle: PlanBundle, sample_repo_path: Path) -> None: + """Test validation with mixed valid, orphaned, and invalid features.""" + results = _validate_existing_features(mixed_plan_bundle, sample_repo_path) + + assert results["total_checked"] == 5 + # FEATURE-001: Valid (has stories, source_tracking, files exist) + # FEATURE-005: Valid (has source_tracking, files exist, empty stories are allowed for newly discovered features) + assert len(results["valid_features"]) == 2 + assert "FEATURE-001" in results["valid_features"] + assert "FEATURE-005" in results["valid_features"] + assert len(results["orphaned_features"]) == 1 + assert results["orphaned_features"] == ["FEATURE-002"] + assert len(results["invalid_features"]) == 2 # FEATURE-003, FEATURE-004 + assert "FEATURE-003" in results["invalid_features"] # Some files missing + assert "FEATURE-004" in results["invalid_features"] # No source tracking + + def test_validate_feature_without_source_tracking(self, sample_repo_path: Path) -> None: + """Test validation with feature that has no source tracking.""" + plan_bundle = PlanBundle( + version="1.0", + product=Product(themes=["Testing"]), + features=[ + Feature( + key="FEATURE-006", + title="No Source Tracking", + outcomes=["Outcome 1"], + acceptance=["AC 1"], + stories=[ + Story( + key="STORY-006", + title="Story", + acceptance=["Story AC 1"], + story_points=None, + value_points=None, + scenarios=None, + contracts=None, + ) + ], + source_tracking=None, + contract=None, + protocol=None, + ) + ], + idea=None, + business=None, + metadata=None, + clarifications=None, + ) + + results = _validate_existing_features(plan_bundle, sample_repo_path) + + assert results["total_checked"] == 1 + assert len(results["valid_features"]) == 0 + assert len(results["orphaned_features"]) == 0 + assert len(results["invalid_features"]) == 1 + assert results["invalid_features"] == ["FEATURE-006"] + + def test_validate_feature_with_empty_stories(self, sample_repo_path: Path) -> None: + """Test validation with feature that has empty stories.""" + plan_bundle = PlanBundle( + version="1.0", + product=Product(themes=["Testing"]), + features=[ + Feature( + key="FEATURE-007", + title="Empty Stories", + outcomes=["Outcome 1"], + acceptance=["AC 1"], + stories=[], + source_tracking=SourceTracking( + implementation_files=["src/service.py"], + test_files=["tests/test_service.py"], + source_functions=[], + test_functions=[], + ), + contract=None, + protocol=None, + ) + ], + idea=None, + business=None, + metadata=None, + clarifications=None, + ) + + results = _validate_existing_features(plan_bundle, sample_repo_path) + + assert results["total_checked"] == 1 + # Features without stories are now considered valid (they may be newly discovered) + # As long as they have source_tracking and files exist, they're valid + assert len(results["valid_features"]) == 1 + assert results["valid_features"] == ["FEATURE-007"] + assert len(results["orphaned_features"]) == 0 + assert len(results["invalid_features"]) == 0 + + def test_validate_feature_with_partial_files(self, sample_repo_path: Path) -> None: + """Test validation with feature that has some existing and some missing files.""" + plan_bundle = PlanBundle( + version="1.0", + product=Product(themes=["Testing"]), + features=[ + Feature( + key="FEATURE-008", + title="Partial Files", + outcomes=["Outcome 1"], + acceptance=["AC 1"], + stories=[ + Story( + key="STORY-008", + title="Story", + acceptance=["Story AC 1"], + story_points=None, + value_points=None, + scenarios=None, + contracts=None, + ) + ], + source_tracking=SourceTracking( + implementation_files=["src/service.py", "src/missing.py"], + test_files=["tests/test_service.py"], + source_functions=[], + test_functions=[], + ), + contract=None, + protocol=None, + ) + ], + idea=None, + business=None, + metadata=None, + clarifications=None, + ) + + results = _validate_existing_features(plan_bundle, sample_repo_path) + + assert results["total_checked"] == 1 + assert len(results["valid_features"]) == 0 + assert len(results["orphaned_features"]) == 0 # Not orphaned because some files exist + assert len(results["invalid_features"]) == 1 + assert results["invalid_features"] == ["FEATURE-008"] + assert "FEATURE-008" in results["missing_files"] + assert "src/missing.py" in results["missing_files"]["FEATURE-008"] + + def test_validate_empty_bundle(self, sample_repo_path: Path) -> None: + """Test validation with empty bundle.""" + plan_bundle = PlanBundle( + version="1.0", + product=Product(themes=[]), + features=[], + idea=None, + business=None, + metadata=None, + clarifications=None, + ) + + results = _validate_existing_features(plan_bundle, sample_repo_path) + + assert results["total_checked"] == 0 + assert len(results["valid_features"]) == 0 + assert len(results["orphaned_features"]) == 0 + assert len(results["invalid_features"]) == 0 + assert len(results["missing_files"]) == 0 diff --git a/tests/unit/models/test_project.py b/tests/unit/models/test_project.py index 31a46d1..af5a071 100644 --- a/tests/unit/models/test_project.py +++ b/tests/unit/models/test_project.py @@ -376,6 +376,80 @@ def test_compute_file_checksum(self, tmp_path: Path): expected = hashlib.sha256(b"test content").hexdigest() assert checksum == expected + def test_save_to_directory_checksums_computed_during_write(self, tmp_path: Path): + """Test that checksums are computed during serialization (not after reading back).""" + bundle_dir = tmp_path / "test-bundle" + + manifest = BundleManifest(schema_metadata=None, project_metadata=None) + product = Product(themes=["Theme1"]) + bundle = ProjectBundle(manifest=manifest, bundle_name="test-bundle", product=product) + + # Add multiple features to test parallel saving + for i in range(5): + feature = Feature( + key=f"FEATURE-{i:03d}", + title=f"Test Feature {i}", + source_tracking=None, + contract=None, + protocol=None, + ) + bundle.add_feature(feature) + + bundle.save_to_directory(bundle_dir) + + # Verify checksums are computed and stored in manifest + assert "product.yaml" in bundle.manifest.checksums.files + assert len(bundle.manifest.checksums.files["product.yaml"]) == 64 # SHA256 hex digest + + # Verify feature checksums are computed + for i in range(5): + feature_file = f"features/FEATURE-{i:03d}.yaml" + assert feature_file in bundle.manifest.checksums.files + assert len(bundle.manifest.checksums.files[feature_file]) == 64 + + # Verify checksums match file contents (validates checksum computed correctly) + for artifact_name, checksum in bundle.manifest.checksums.files.items(): + artifact_path = bundle_dir / artifact_name + if artifact_path.exists(): + # Compute checksum from file (old method) and compare + file_checksum = ProjectBundle._compute_file_checksum(artifact_path) + assert checksum == file_checksum, f"Checksum mismatch for {artifact_name}" + + @pytest.mark.timeout(30) # Increase timeout for large bundle test + def test_save_to_directory_large_bundle_worker_reduction(self, tmp_path: Path): + """Test that large bundles (1000+ features) use fewer workers for memory optimization.""" + bundle_dir = tmp_path / "test-bundle" + + manifest = BundleManifest(schema_metadata=None, project_metadata=None) + product = Product(themes=["Theme1"]) + bundle = ProjectBundle(manifest=manifest, bundle_name="test-bundle", product=product) + + # Add 1001 features to trigger large bundle logic + # This tests the worker reduction optimization (4 workers instead of 8) + num_features = 1001 + for i in range(num_features): + feature = Feature( + key=f"FEATURE-{i:04d}", + title=f"Test Feature {i}", + source_tracking=None, + contract=None, + protocol=None, + ) + bundle.add_feature(feature) + + # Save should complete successfully with reduced workers + # Note: This test takes longer due to large bundle size (30s timeout) + bundle.save_to_directory(bundle_dir) + + # Verify all features saved + assert (bundle_dir / "features").exists() + saved_features = list((bundle_dir / "features").glob("*.yaml")) + assert len(saved_features) == num_features + + # Verify checksums computed for all features + # Features + product + manifest (and potentially idea/business if present) + assert len(bundle.manifest.checksums.files) >= num_features + class TestBundleFormat: """Tests for BundleFormat enum."""