diff --git a/README.md b/README.md index 67c2feef..91fca227 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,8 @@ - Module-specific deep docs are canonically owned by `specfact-cli-modules`. - The live modules docs site is currently published at `https://modules.specfact.io/`. -Use this repository's docs for core runtime, lifecycle, registry, trust, and architecture guidance. Use the modules docs site for bundle-specific workflow and module-authoring deep dives. +Use this repository's docs for the overall SpecFact workflow, CLI runtime lifecycle, module registry, trust model, and command-group topology. +Use the modules docs site for bundle-specific deep dives, adapter details, workflow tutorials, and module-authoring guidance. In short, module-specific deep docs are canonically owned by `specfact-cli-modules`. --- @@ -47,19 +48,14 @@ pip install -U specfact-cli ### Bootstrap and IDE Setup ```bash -# First run: install workflow bundles (required) +# First run: install official bundles specfact init --profile solo-developer -# Other first-run options +# Alternative bundle selection specfact init --install backlog,codebase specfact init --install all -# First-run bundle selection (examples) -specfact init --profile solo-developer -specfact init --install backlog,codebase -specfact init --install all - -# Configure IDE prompts/templates (interactive selector by default) +# IDE prompt/template setup specfact init ide specfact init ide --ide cursor specfact init ide --ide vscode @@ -71,6 +67,9 @@ specfact init ide --ide vscode # Analyze an existing codebase specfact code import my-project --repo . +# Snapshot current project state +specfact project snapshot --bundle my-project + # Validate external code without modifying source specfact code validate sidecar init my-project /path/to/repo specfact code validate sidecar run my-project /path/to/repo @@ -80,9 +79,9 @@ specfact code validate sidecar run my-project /path/to/repo As of `0.40.0`, flat root commands are removed. Use grouped commands: -- `specfact validate ...` → `specfact code validate ...` -- `specfact plan ...` → removed; use `specfact project devops-flow` or `specfact project snapshot` -- `specfact policy ...` → removed; use `specfact backlog verify-readiness` +- `specfact validate ...` -> `specfact code validate ...` +- `specfact plan ...` -> removed; use `specfact project devops-flow` or `specfact project snapshot` +- `specfact policy ...` -> removed; use `specfact backlog verify-readiness` ### Backlog Bridge (60 seconds) @@ -95,19 +94,18 @@ These commands require the backlog bundle to be installed first, for example via specfact backlog init-config --force specfact backlog map-fields --provider ado --ado-org --ado-project "" -# 2) Run standup/refinement on real backlog scope -specfact backlog daily ado --ado-org --ado-project "" --state any --assignee any --limit 5 -specfact backlog refine ado --ado-org --ado-project "" --id --preview +# 2) Run ceremony workflows on real backlog scope +specfact backlog ceremony standup ado --ado-org --ado-project "" --state any --assignee any --limit 5 +specfact backlog ceremony refinement ado --ado-org --ado-project "" --id --preview # 3) Keep backlog + spec intent aligned (avoid silent drift) specfact backlog verify-readiness --bundle ``` -For GitHub, replace adapter/org/project with: -`specfact backlog daily github --repo-owner --repo-name ...` +Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` still exist, but the preferred entrypoints are `backlog ceremony standup` and `backlog ceremony refinement`. -Deep dive: -- **[Backlog Quickstart Demo (GitHub + ADO)](docs/getting-started/tutorial-backlog-quickstart-demo.md)** +For GitHub, replace adapter/org/project with: +`specfact backlog ceremony standup github --repo-owner --repo-name --state any --assignee any --limit 5` **AI IDE quick start** @@ -118,26 +116,9 @@ Deep dive: **Next steps** -- **[Getting Started](docs/getting-started/README.md)** -- **[AI IDE Workflow](docs/guides/ai-ide-workflow.md)** -- **[Command Chains](docs/guides/command-chains.md)** - ---- - -## Proof and Expectations - -- **Typical runtime**: 2-15 minutes depending on repo size and complexity. -- **Checkpointing**: Progress is saved during analysis so you can resume safely. -- **Performance**: Optimized for large codebases with cached parsing and file hashes. - ---- - -## Why It Matters (Plain Language) - -- **Clarity**: Turn messy code into clear specs your team can trust. -- **Safety**: Catch risky changes early with validation and contract checks. -- **Sync**: Keep backlog items, specs, tests, and code aligned end to end. -- **Adoption**: Simple CLI, no platform lock-in, works offline. +- **[Core CLI docs](docs/index.md)** +- **[Reference: command topology](docs/reference/commands.md)** +- **[Canonical modules docs site](https://modules.specfact.io/)** --- @@ -149,14 +130,6 @@ Deep dive: --- -## How It Works (High Level) - -1. **Analyze**: Read code and extract specs, gaps, and risks. -2. **Sync**: Connect specs, backlog items, and plans in one workflow. -3. **Validate**: Enforce contracts and block regressions before production. - ---- - ## The Missing Link (Coder + DevOps Bridge) Most tools help **either** coders **or** agile teams. SpecFact does both: @@ -174,54 +147,37 @@ Recommended command entrypoints: What the backlog readiness and ceremony commands do in practice: - Turns team agreements (DoR, DoD, flow checks) into executable checks against your real backlog data. - Shows exactly what is missing per item (for example missing acceptance criteria or definition of done). -- Run structured ceremony workflows (standup, refinement, retrospective) directly from the CLI. +- Runs structured ceremony workflows directly from the CLI. Start with: - `specfact backlog ceremony standup --help` - `specfact backlog verify-readiness --bundle ` - `specfact backlog refine --help` -**Try it now** - -- **Coders**: [AI IDE Workflow](docs/guides/ai-ide-workflow.md) -- **Agile teams**: [Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md) - --- -## Modules and Capabilities - -**Core runtime** - -- **Permanent commands**: `init`, `module`, `upgrade` -- **Core responsibilities**: lifecycle, registry, trust, contracts, orchestration, shared runtime utilities - -**Marketplace-installed bundles** +## Core CLI Features -- **Backlog**: Refinement, dependency analysis, sprint summaries, risk rollups. -- **Ceremony**: Standup, refinement, and planning entry points. -- **Policy**: DoR, DoD, flow, PI readiness checks. -- **Patch**: Preview, apply, and write changes safely. +The `specfact-cli` repository owns the platform-level features that every workflow bundle depends on: -**Adapters and bridges** +- `specfact init` for first-run bootstrap and IDE setup. +- `specfact module` for install/list/show/search/enable/disable/uninstall/upgrade lifecycle flows. +- `specfact upgrade` for CLI upgrades. +- Runtime contracts, registry bootstrapping, trust checks, logging, and shared orchestration. +- The grouped command surface that mounts installed bundle families under `project`, `backlog`, `code`, `spec`, and `govern`. -- **Specs**: Spec-Kit and OpenSpec -- **Backlogs**: GitHub Issues, Azure DevOps, Jira, Linear -- **Contracts**: Specmatic, OpenAPI +## Official Modules Integration -For technical architecture details (module lifecycle, registry internals, adapters, and implementation status), use: +Official workflow behavior now ships from `nold-ai/specfact-cli-modules`. +The core CLI discovers those bundle packages, mounts their command groups, and enforces compatibility, trust, and lifecycle rules. -- [Architecture Reference](docs/reference/architecture.md) -- [Architecture Docs Index](docs/architecture/README.md) -- [Architecture Implementation Status](docs/architecture/implementation-status.md) +Installed official bundles expose the current grouped surfaces: -### Official Marketplace Bundles - -SpecFact ships official bundle packages via the dedicated marketplace registry repository -`nold-ai/specfact-cli-modules`. - -This core docs set remains the canonical docs entry point and release-line overview for marketplace concepts. -Bundle-specific deep docs are canonically owned by `specfact-cli-modules` and are currently published at: -`https://modules.specfact.io/`. +- `specfact project ...` +- `specfact backlog ...` +- `specfact code ...` +- `specfact spec ...` +- `specfact govern ...` Install examples: @@ -240,16 +196,17 @@ specfact module init --scope project specfact module init ``` -Official bundles are verified as `official` tier (`nold-ai` publisher). Some bundles -auto-install dependencies: +Use this repo's docs for the current CLI/runtime release branch and the overall process of how official modules plug into the core platform. +Use `https://modules.specfact.io/` for the in-depth backlog, project, spec, govern, adapter, and module-authoring guides. -- `nold-ai/specfact-spec` pulls `nold-ai/specfact-project` -- `nold-ai/specfact-govern` pulls `nold-ai/specfact-project` +--- -Use this repo's docs for the current CLI/runtime release branch and for marketplace lifecycle overview content. -Use the modules docs site for bundle-specific deep guidance so bundle-only changes can ship without rebuilding the core docs release branch. +## How It Works (High Level) ---- +1. **Bootstrap**: install the CLI and initialize the official bundles you need. +2. **Analyze or sync**: import code, connect backlog systems, or sync external artifacts into project bundles. +3. **Validate**: run spec, governance, and sidecar validation flows before implementation or release. +4. **Iterate safely**: use module-provided workflows while the core runtime keeps command mounting, trust, and lifecycle consistent. ## Where SpecFact Fits @@ -258,75 +215,3 @@ SpecFact complements your stack rather than replacing it. - **Spec-Kit/OpenSpec** for authoring and change tracking - **Backlog tools** for planning and delivery - **CI/CD** for enforcement and regression prevention - -**SpecFact connects them** with adapters, policy checks, and deterministic validation. - -**Integrations snapshot**: GitHub, Azure DevOps, Jira, Linear, Spec-Kit, OpenSpec, Specmatic. - -- **[Integrations Overview](docs/guides/integrations-overview.md)** -- **[DevOps Adapter Integration](docs/guides/devops-adapter-integration.md)** - ---- - -## Recommended Paths - -- **I want a quick win**: [Getting Started](docs/getting-started/README.md) -- **I use an AI IDE**: [AI IDE Workflow](docs/guides/ai-ide-workflow.md) -- **We have a team backlog**: [Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md) -- **We have a long-lived codebase**: [Working With Existing Code](docs/guides/brownfield-engineer.md) - ---- - -## Documentation Map - -- **[Documentation Index](docs/README.md)** -- **[Command Reference](docs/reference/commands.md)** -- **[Backlog Refinement](docs/guides/backlog-refinement.md)** -- **[Backlog Dependency Analysis](docs/guides/backlog-dependency-analysis.md)** -- **[Backlog Delta Commands](docs/guides/backlog-delta-commands.md)** -- **[Policy Engine Commands](docs/guides/policy-engine-commands.md)** -- **[Project DevOps Flow](docs/guides/project-devops-flow.md)** -- **[Sidecar Validation](docs/guides/sidecar-validation.md)** -- **[OpenSpec Journey](docs/guides/openspec-journey.md)** - ---- - -## Contributing - -We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md). - -```bash -git clone https://github.com/nold-ai/specfact-cli.git -cd specfact-cli -pip install -e ".[dev]" -hatch run contract-test-full -``` - ---- - -## License - -**Apache License 2.0** - Open source and enterprise-friendly. - -[Full license](LICENSE) - ---- - -## Support - -- **GitHub Discussions**: https://github.com/nold-ai/specfact-cli/discussions -- **GitHub Issues**: https://github.com/nold-ai/specfact-cli/issues -- **Email**: hello@noldai.com -- **Debug logs**: Run with `--debug` and check `~/.specfact/logs/specfact-debug.log`. - ---- - -
- -**Built by [NOLD AI](https://noldai.com)** - -Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold) - -**Trademarks**: NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). All other trademarks mentioned in this project are the property of their respective owners. See [TRADEMARKS.md](TRADEMARKS.md) for more information. - -
diff --git a/docs/LICENSE.md b/docs/LICENSE.md index dd8dba5c..8353814c 100644 --- a/docs/LICENSE.md +++ b/docs/LICENSE.md @@ -1,3 +1,9 @@ +--- +layout: default +title: LICENSE +permalink: /LICENSE/ +--- + Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ diff --git a/docs/README.md b/docs/README.md index 8950bdce..e9c38368 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,181 +2,87 @@ layout: default title: Documentation Index permalink: /documentation-index/ -description: High-level index for the SpecFact CLI documentation sections and guides. +description: High-level index for the SpecFact core CLI docs and canonical modules docs handoff. --- # SpecFact CLI Documentation -> **The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow.** -> Keep backlog, specs, tests, and code in sync so AI-assisted changes don’t break production. -> Works for brand-new projects and long-lived codebases — even if you’re new to coding. +This repository owns the **core CLI** documentation set for SpecFact. +It explains the overall process of using SpecFact CLI, the platform runtime, and how official modules integrate into the grouped command surface. -**Built for both worlds** +For **module-specific deep functionality**, use the canonical modules docs site at `https://modules.specfact.io/`. +The canonical modules docs site owns the detailed guides for bundle workflows, adapters, and module authoring. -- **Vibe coders and new builders** who want to ship fast with guardrails and confidence. -- **Legacy professionals** who want AI speed without lowering standards, plus end-to-end spec -> backlog -> code sync. +## Core Docs Scope ---- +Use this docs set for: + +- CLI bootstrap, lifecycle, and upgrade flows +- module registry, trust, and ownership boundaries +- overall workflow topology across `project`, `backlog`, `code`, `spec`, and `govern` +- runtime and architecture reference for the lean-core platform + +## Modules Docs Scope + +Use the canonical modules docs site for: -## The Missing Link (Coder + DevOps Bridge) +- backlog refinement, ceremony, dependency-analysis, and delta workflows +- project bundle and bridge-sync runbooks +- spec bundle deep dives and govern bundle deep dives +- adapter-specific behavior and official bundle tutorials +- module development, publishing, signing, and marketplace operations + +The canonical modules docs site is currently published at `https://modules.specfact.io/`. +This docs set keeps release-line overview and handoff content for bundle workflows while the canonical modules docs site carries the deep bundle-specific guidance. + +## Core Entry Points + +- [Docs Home](index.md) +- [Getting Started](getting-started/README.md) +- [Command Reference](reference/commands.md) +- [Reference Index](reference/README.md) +- [Architecture Reference](reference/architecture.md) -Most tools help **either** coders **or** agile teams. SpecFact does both: +## Current Core Command Topology -- **Backlog sync that is actually strong**: round-trip sync + refinement for GitHub, Azure DevOps, Jira, Linear. -- **Ceremony support teams can run**: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe). -- **Policy + validation**: DoR/DoD/flow checks plus contract enforcement for production-grade safety. +The live CLI groups installed workflow commands by category: + +- `specfact init` +- `specfact module` +- `specfact upgrade` +- `specfact project ...` +- `specfact backlog ...` +- `specfact code ...` +- `specfact spec ...` +- `specfact govern ...` + +Preferred backlog workflow entrypoints: -Recommended command entrypoints: - `specfact backlog ceremony standup ...` - `specfact backlog ceremony refinement ...` - `specfact backlog verify-readiness --bundle ` - `specfact backlog analyze-deps --bundle ` +Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` remain available, but the ceremony forms are the preferred command path. + What the backlog ceremony and readiness commands do in practice: - Converts team working agreements (DoR, DoD, flow/PI readiness) into deterministic checks. - Flags exact readiness gaps per backlog item with actionable evidence pointers. -- Runs structured ceremony workflows (standup, refinement) against live backlog data. +- Runs structured ceremony workflows against live backlog data. Start with: - `specfact backlog ceremony standup --help` - `specfact backlog verify-readiness --bundle ` - `specfact backlog refine --help` -**Try it now** - -- **Coders**: [AI IDE Workflow](guides/ai-ide-workflow.md) -- **Agile teams**: [Agile/Scrum Workflows](guides/agile-scrum-workflows.md) - ---- - -## Start Here (Pick Your Path) - -**Pick your path** - -- **Working with existing code**: [Getting Started](getting-started/README.md) and [Legacy Engineer Guide](guides/brownfield-engineer.md) -- **Agile team workflows**: [Agile/Scrum Workflows](guides/agile-scrum-workflows.md) and [Backlog Refinement](guides/backlog-refinement.md) -- **AI IDE workflow**: [AI IDE Workflow Guide](guides/ai-ide-workflow.md) -- **Integrations**: [Integrations Overview](guides/integrations-overview.md) - ---- - -## Modules and Capabilities - -**Core runtime** - -- **Permanent commands**: `init`, `module`, `upgrade` -- **Core responsibilities**: lifecycle, registry, trust, contracts, orchestration, shared runtime utilities - -**Marketplace-installed bundles** - -- **Backlog**: Refinement, dependency analysis, sprint summaries, risk rollups. -- **Ceremony**: Standup, refinement, and planning entry points. -- **Policy**: DoR, DoD, flow, PI readiness checks. -- **Patch**: Preview, apply, and write changes safely. - -**Adapters and bridges** - -- **Specs**: Spec-Kit and OpenSpec -- **Backlogs**: GitHub Issues, Azure DevOps, Jira, Linear -- **Contracts**: Specmatic, OpenAPI - -## Module Lifecycle System - -SpecFact CLI uses a lifecycle-managed module system: - -- `specfact init` bootstraps local state. -- `specfact init ide` handles IDE prompt/template installation and updates. -- `specfact module` is the canonical lifecycle surface for install/list/show/search/enable/disable/uninstall/upgrade. -- Dependency and compatibility guards prevent invalid module states; `--force` enables dependency-aware cascades. - -This is the baseline for marketplace-driven module lifecycle and future community module distribution. +## Core vs Modules Navigation -`docs.specfact.io` is the canonical docs entry point for SpecFact, and this repository owns the -core CLI/runtime section of that experience. +- **Core CLI docs**: runtime, lifecycle, contracts, command topology, architecture +- **Canonical modules docs site**: bundle-specific tutorials, command details, adapters, module authoring -The canonical modules docs site is currently published at -`https://modules.specfact.io/`. -Bundle-specific deep guides in this repo remain as release-line overview or handoff content rather than the long-term canonical source. +### Recommended next reads -### Why the Module System Is the Foundation - -This architecture intentionally separates the CLI core from feature modules: - -- Core provides lifecycle, registry, contracts, and orchestration. -- Official workflow bundles are authored and released from `nold-ai/specfact-cli-modules`. -- This docs set keeps release-line overview and handoff content for bundle workflows while the canonical modules docs site carries the deep bundle-specific guidance. -- Compatibility shims preserve legacy import paths during migration windows. - -Practical outcomes: - -- Feature modules can be developed and released at different speeds. -- Module teams can iterate without repeatedly rebuilding core command wiring. -- Stable contracts/interfaces keep migrations predictable and reduce regressions. - -For implementation details, see: - -- [Architecture](reference/architecture.md) -- [Module Contracts](reference/module-contracts.md) - [Installing Modules](guides/installing-modules.md) -- [Module Marketplace](guides/module-marketplace.md) -- [Custom registries](guides/custom-registries.md) -- [Publishing modules](guides/publishing-modules.md) -- [Module Signing and Key Rotation](guides/module-signing-and-key-rotation.md) - ---- - -## Documentation Sections - -### Getting Started - -- [Installation](getting-started/installation.md) -- [First Steps](getting-started/first-steps.md) -- [Enhanced Analysis Dependencies](installation/enhanced-analysis-dependencies.md) - -### Guides - -- [Agile/Scrum Workflows](guides/agile-scrum-workflows.md) -- [Backlog Refinement](guides/backlog-refinement.md) -- [Backlog Dependency Analysis](guides/backlog-dependency-analysis.md) -- [Backlog Delta Commands](guides/backlog-delta-commands.md) -- [Policy Engine Commands](guides/policy-engine-commands.md) -- [Project DevOps Flow](guides/project-devops-flow.md) -- [DevOps Adapter Integration](guides/devops-adapter-integration.md) -- [AI IDE Workflow](guides/ai-ide-workflow.md) -- [Sidecar Validation](guides/sidecar-validation.md) -- [Use Cases](guides/use-cases.md) - -### Integrations - -- [Spec-Kit Journey](guides/speckit-journey.md) -- [OpenSpec Journey](guides/openspec-journey.md) -- [Specmatic Integration](guides/specmatic-integration.md) -- [Custom Field Mapping](guides/custom-field-mapping.md) - -### Reference - -- [Command Reference](reference/commands.md) -- [Architecture](reference/architecture.md) -- [Debug Logging](reference/debug-logging.md) - -### Contributing - -- [Development Setup](getting-started/installation.md#development-setup) -- [Testing Procedures](technical/testing.md) -- [Technical Deep Dives](technical/README.md) - ---- - -## Helpful Shortcuts - -- **Command Chains**: [guides/command-chains.md](guides/command-chains.md) -- **Common Tasks**: [guides/common-tasks.md](guides/common-tasks.md) -- **Online Docs**: https://docs.specfact.io/ - ---- - -## Need Help? - -- **GitHub Discussions**: https://github.com/nold-ai/specfact-cli/discussions -- **GitHub Issues**: https://github.com/nold-ai/specfact-cli/issues -- **Email**: hello@noldai.com +- [Module Categories](reference/module-categories.md) +- [Module Contracts](reference/module-contracts.md) +- [Canonical modules docs site](https://modules.specfact.io/) diff --git a/docs/TRADEMARKS.md b/docs/TRADEMARKS.md index 03d6262b..8897f94a 100644 --- a/docs/TRADEMARKS.md +++ b/docs/TRADEMARKS.md @@ -1,3 +1,9 @@ +--- +layout: default +title: TRADEMARKS +permalink: /TRADEMARKS/ +--- + # Trademarks ## NOLD AI Trademark diff --git a/docs/architecture/component-graph.md b/docs/architecture/component-graph.md index 9144958f..47d8a3d0 100644 --- a/docs/architecture/component-graph.md +++ b/docs/architecture/component-graph.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Component Graph +permalink: /architecture/component-graph/ +--- + # SpecFact CLI Component Graph ## High-level components diff --git a/docs/architecture/data-flow.md b/docs/architecture/data-flow.md index 03cfadc5..20aaeb0a 100644 --- a/docs/architecture/data-flow.md +++ b/docs/architecture/data-flow.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Data Flow +permalink: /architecture/data-flow/ +--- + # SpecFact CLI Data Flow Architecture ## Command execution flow diff --git a/docs/architecture/discrepancies-report.md b/docs/architecture/discrepancies-report.md index cde8cf31..8b9dc1e3 100644 --- a/docs/architecture/discrepancies-report.md +++ b/docs/architecture/discrepancies-report.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Discrepancies Report +permalink: /architecture/discrepancies-report/ +--- + # SpecFact CLI Architecture Discrepancies Report ## Executive Summary diff --git a/docs/architecture/interface-contracts.md b/docs/architecture/interface-contracts.md index 8c4f1e42..be51798f 100644 --- a/docs/architecture/interface-contracts.md +++ b/docs/architecture/interface-contracts.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Interface Contracts +permalink: /architecture/interface-contracts/ +--- + # SpecFact CLI Interface Contracts ## Command Registry contract diff --git a/docs/architecture/module-system.md b/docs/architecture/module-system.md index b8a5da49..018568d8 100644 --- a/docs/architecture/module-system.md +++ b/docs/architecture/module-system.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Module System +permalink: /architecture/module-system/ +--- + # SpecFact CLI Module System Architecture ## Status diff --git a/docs/architecture/state-machines.md b/docs/architecture/state-machines.md index 0a1b0962..c8ef3bc1 100644 --- a/docs/architecture/state-machines.md +++ b/docs/architecture/state-machines.md @@ -1,3 +1,9 @@ +--- +layout: default +title: State Machines +permalink: /architecture/state-machines/ +--- + # SpecFact CLI State Machine Logic ## CLI command lifecycle diff --git a/docs/contributing/github-project-gh-cli.md b/docs/contributing/github-project-gh-cli.md index fba7bae3..1dd8a67e 100644 --- a/docs/contributing/github-project-gh-cli.md +++ b/docs/contributing/github-project-gh-cli.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Github Project Gh Cli +permalink: /contributing/github-project-gh-cli/ +--- + # SpecFact CLI project – gh CLI automation How to set **Projects** and project fields (Status, Type, Parent issue) that appear on each issue/PR **sidebar** for the [SpecFact CLI project](https://github.com/orgs/nold-ai/projects/1). All of this can be done with the GitHub CLI (`gh`). diff --git a/docs/examples/brownfield-data-pipeline.md b/docs/examples/brownfield-data-pipeline.md index d3bdb1f4..d29aa958 100644 --- a/docs/examples/brownfield-data-pipeline.md +++ b/docs/examples/brownfield-data-pipeline.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Brownfield Data Pipeline +permalink: /examples/brownfield-data-pipeline/ +--- + # Brownfield Example: Modernizing Legacy Data Pipeline > **Complete walkthrough: From undocumented ETL pipeline to contract-enforced data processing** diff --git a/docs/examples/brownfield-django-modernization.md b/docs/examples/brownfield-django-modernization.md index df6280e4..9782d2eb 100644 --- a/docs/examples/brownfield-django-modernization.md +++ b/docs/examples/brownfield-django-modernization.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Brownfield Django Modernization +permalink: /examples/brownfield-django-modernization/ +--- + # Brownfield Example: Modernizing Legacy Django Code > **Complete walkthrough: From undocumented legacy Django app to contract-enforced modern codebase** diff --git a/docs/examples/brownfield-flask-api.md b/docs/examples/brownfield-flask-api.md index 0a61eaac..ea127bea 100644 --- a/docs/examples/brownfield-flask-api.md +++ b/docs/examples/brownfield-flask-api.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Brownfield Flask Api +permalink: /examples/brownfield-flask-api/ +--- + # Brownfield Example: Modernizing Legacy Flask API > **Complete walkthrough: From undocumented Flask API to contract-enforced modern service** diff --git a/docs/examples/dogfooding-specfact-cli.md b/docs/examples/dogfooding-specfact-cli.md index 5475c586..686ce414 100644 --- a/docs/examples/dogfooding-specfact-cli.md +++ b/docs/examples/dogfooding-specfact-cli.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Dogfooding Specfact Cli +permalink: /examples/dogfooding-specfact-cli/ +--- + # 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. 🚀 diff --git a/docs/examples/integration-showcases/README.md b/docs/examples/integration-showcases/README.md index 80b035b7..5b062f0d 100644 --- a/docs/examples/integration-showcases/README.md +++ b/docs/examples/integration-showcases/README.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Integration Showcases +permalink: /examples/integration-showcases/ +--- + # 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. diff --git a/docs/examples/integration-showcases/integration-showcases-quick-reference.md b/docs/examples/integration-showcases/integration-showcases-quick-reference.md index 08db3680..3bd0a06e 100644 --- a/docs/examples/integration-showcases/integration-showcases-quick-reference.md +++ b/docs/examples/integration-showcases/integration-showcases-quick-reference.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Integration Showcases Quick Reference +permalink: /examples/integration-showcases/integration-showcases-quick-reference/ +--- + # Integration Showcases - Quick Reference > **Quick command reference** for testing all 5 integration examples diff --git a/docs/examples/integration-showcases/integration-showcases-testing-guide.md b/docs/examples/integration-showcases/integration-showcases-testing-guide.md index c6227ed4..253db248 100644 --- a/docs/examples/integration-showcases/integration-showcases-testing-guide.md +++ b/docs/examples/integration-showcases/integration-showcases-testing-guide.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Integration Showcases Testing Guide +permalink: /examples/integration-showcases/integration-showcases-testing-guide/ +--- + # Integration Showcases Testing Guide > **Purpose**: Step-by-step guide to test and validate all 5 integration examples from `integration-showcases.md` diff --git a/docs/examples/integration-showcases/integration-showcases.md b/docs/examples/integration-showcases/integration-showcases.md index 9b904809..84c3fb9e 100644 --- a/docs/examples/integration-showcases/integration-showcases.md +++ b/docs/examples/integration-showcases/integration-showcases.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Integration Showcases +permalink: /examples/integration-showcases/integration-showcases/ +--- + # 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. diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 9187bc1a..528d568f 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Getting Started +permalink: /getting-started/ +--- + # Getting Started with SpecFact CLI Welcome to SpecFact CLI! This guide will help you get started in under 60 seconds. diff --git a/docs/getting-started/tutorial-openspec-speckit.md b/docs/getting-started/tutorial-openspec-speckit.md index 7da1895d..eb52c134 100644 --- a/docs/getting-started/tutorial-openspec-speckit.md +++ b/docs/getting-started/tutorial-openspec-speckit.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Tutorial Openspec Speckit +permalink: /getting-started/tutorial-openspec-speckit/ +--- + # Tutorial: Using SpecFact with OpenSpec or Spec-Kit > **Complete step-by-step guide for new users** diff --git a/docs/guides/README.md b/docs/guides/README.md index 89a286be..1650fa1d 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Guides +permalink: /guides/ +--- + # Guides Practical guides for using SpecFact CLI effectively. diff --git a/docs/guides/brownfield-faq.md b/docs/guides/brownfield-faq.md index fc6b7c47..8120afb0 100644 --- a/docs/guides/brownfield-faq.md +++ b/docs/guides/brownfield-faq.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Brownfield Faq +permalink: /guides/brownfield-faq/ +--- + # Brownfield Modernization FAQ > **Frequently asked questions about using SpecFact CLI for legacy code modernization** diff --git a/docs/guides/brownfield-roi.md b/docs/guides/brownfield-roi.md index 70e2845f..e8e3a746 100644 --- a/docs/guides/brownfield-roi.md +++ b/docs/guides/brownfield-roi.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Brownfield Roi +permalink: /guides/brownfield-roi/ +--- + # Brownfield Modernization ROI with SpecFact > **Calculate your time and cost savings when modernizing legacy Python code** diff --git a/docs/guides/integrations-overview.md b/docs/guides/integrations-overview.md index d44efd35..d2687613 100644 --- a/docs/guides/integrations-overview.md +++ b/docs/guides/integrations-overview.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Integrations Overview +permalink: /guides/integrations-overview/ +--- + # Integrations Overview > **Comprehensive guide to all SpecFact CLI integrations** diff --git a/docs/guides/migration-0.16-to-0.19.md b/docs/guides/migration-0.16-to-0.19.md index d1f0af50..8ae43310 100644 --- a/docs/guides/migration-0.16-to-0.19.md +++ b/docs/guides/migration-0.16-to-0.19.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Migration 0.16 To 0.19 +permalink: /guides/migration-0.16-to-0.19/ +--- + # 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). diff --git a/docs/guides/migration-cli-reorganization.md b/docs/guides/migration-cli-reorganization.md index 1e26e610..d72b3e31 100644 --- a/docs/guides/migration-cli-reorganization.md +++ b/docs/guides/migration-cli-reorganization.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Migration Cli Reorganization +permalink: /guides/migration-cli-reorganization/ +--- + # CLI Reorganization Migration Guide **Date**: 2025-11-27 diff --git a/docs/guides/specmatic-integration.md b/docs/guides/specmatic-integration.md index 1635875c..e9d14102 100644 --- a/docs/guides/specmatic-integration.md +++ b/docs/guides/specmatic-integration.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Specmatic Integration +permalink: /guides/specmatic-integration/ +--- + # Specmatic Integration Guide > **API Contract Testing with Specmatic** diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md index ac419ed1..905d380f 100644 --- a/docs/guides/workflows.md +++ b/docs/guides/workflows.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Workflows +permalink: /guides/workflows/ +--- + # Common Workflows Daily workflows for using SpecFact CLI effectively. diff --git a/docs/index.md b/docs/index.md index 990959d2..d792b2d5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,307 +1,124 @@ --- layout: default title: SpecFact CLI Documentation -description: The swiss knife CLI that keeps backlog, specs, tests, and code in sync. Works for new and long-lived projects. +description: Core CLI docs for runtime lifecycle, command topology, and official module integration. permalink: / --- # SpecFact CLI Documentation -**Docs Home**: `docs.specfact.io` currently serves as the canonical docs entry point and, until the dedicated portal cutover lands, also hosts the Core CLI section. +**Docs Home**: `docs.specfact.io` is the canonical docs entry point for SpecFact. -**Core CLI**: this site owns runtime, lifecycle, registry, trust, and architecture guidance for `specfact-cli`. +**Core CLI**: this site owns runtime, lifecycle, registry, trust, command-topology, and architecture guidance for `specfact-cli`. **Modules**: bundle-specific deep docs are canonically owned by `specfact-cli-modules` and are currently published at `https://modules.specfact.io/`. -**The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow** -Keep backlog, specs, tests, and code in sync so AI-assisted changes don’t break production. +This core docs site should answer two questions: -**Built for both worlds** +- How does the SpecFact platform work end to end? +- How do the official modules plug into the core CLI runtime? -- **Vibe coders and new builders** who want to ship fast with guardrails and confidence. -- **Legacy professionals** who want AI speed without lowering standards, plus end-to-end spec -> backlog -> code sync. - -**Core promise**: Works for new and long-lived projects with contract enforcement and validation. +Use the modules docs site when you need the in-depth workflows for backlog, project, code, spec, govern, adapters, or module authoring. --- -## The Missing Link (Coder + DevOps Bridge) +## What The Core CLI Owns -Most tools help **either** coders **or** agile teams. SpecFact does both: +The `specfact-cli` repository owns the stable platform surface: -- **Backlog sync that is actually strong**: round-trip sync + refinement with GitHub, Azure DevOps, Jira, Linear. -- **Ceremony support teams can run**: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe). -- **Policy + validation**: DoR/DoD/flow checks plus contract enforcement for production-grade stability. +- `specfact init` for bootstrap and IDE setup. +- `specfact module` for lifecycle management of official and marketplace modules. +- `specfact upgrade` for CLI updates. +- Runtime contracts, module discovery, registry bootstrapping, publisher trust, and shared orchestration. +- The grouped command topology that mounts installed workflows under `project`, `backlog`, `code`, `spec`, and `govern`. Recommended command entrypoints: - `specfact backlog ceremony standup ...` - `specfact backlog ceremony refinement ...` - `specfact backlog verify-readiness --bundle ` -**Try it now** +## What The Modules Docs Own -- **Coders**: [AI IDE Workflow](guides/ai-ide-workflow.md) -- **Agile teams**: [Agile/Scrum Workflows](guides/agile-scrum-workflows.md) +The canonical modules docs site covers the official bundle-specific deep guidance: ---- +- backlog ceremonies, refinement, dependency analysis, delta workflows, and adapter specifics +- project bundle workflows and bridge synchronization +- spec validation, mock, backward-compatibility, and contract-test details +- govern enforcement, patch workflows, and bundle-focused runbooks +- module development, publishing, signing, registries, and marketplace operations -## 🚀 Quick Start +Canonical modules site: `https://modules.specfact.io/` -### Backlog Bridge in 60 Seconds +--- -SpecFact closes the drift gap between **backlog -> specs -> code**. -These commands require the backlog bundle to be installed first, for example via -`specfact init --profile backlog-team` or `specfact init --install backlog`. +## Quick Start ```bash -# 1) Initialize backlog config + field mapping -specfact backlog init-config --force -specfact backlog map-fields --provider ado --ado-org --ado-project "" - -# 2) Read and refine real backlog scope -specfact backlog daily ado --ado-org --ado-project "" --state any --assignee any --limit 5 -specfact backlog refine ado --ado-org --ado-project "" --id --preview - -# 3) Validate drift before implementation -specfact backlog verify-readiness --bundle -``` - -GitHub variant: -`specfact backlog daily github --repo-owner --repo-name --state any --assignee any --limit 5` - -Deep dive: -- **[Backlog Quickstart Demo (GitHub + ADO)](getting-started/tutorial-backlog-quickstart-demo.md)** - -### New to SpecFact CLI? - -**Primary Use Case**: Understanding and improving existing codebases (and new projects) - -1. **[Installation](getting-started/installation.md)** - Get started in 60 seconds -2. **[First Steps](getting-started/first-steps.md)** - Run your first command -3. **[Module Bootstrap Checklist](getting-started/module-bootstrap-checklist.md)** - Quickly verify official bundles are installed for user/project scope -4. **[Tutorial: Backlog Refine with AI IDE](getting-started/tutorial-backlog-refine-ai-ide.md)** - Integrate backlog refinement with your AI IDE (agile DevOps) -5. **[Tutorial: Daily Standup and Sprint Review](getting-started/tutorial-daily-standup-sprint-review.md)** - Daily standup view, post comments, and Copilot export (GitHub/ADO) -6. **[Working With Existing Code](guides/brownfield-engineer.md)** ⭐ **PRIMARY** - Legacy-first guide -7. **[The Existing Code Journey](guides/brownfield-journey.md)** ⭐ - Complete modernization workflow - -### Using GitHub Spec-Kit or OpenSpec? - -**Secondary Use Case**: Add automated enforcement to your Spec-Kit or OpenSpec projects - -- **[From Spec-Kit to SpecFact](guides/speckit-journey.md)** - Add enforcement to Spec-Kit projects -- **[Spec-Kit Comparison](guides/speckit-comparison.md)** - Understand when to use each tool -- **[From OpenSpec to SpecFact](guides/openspec-journey.md)** - Add enforcement to OpenSpec projects - -## Module System Foundation - -SpecFact now uses a lean-core plus bundle architecture to reduce hard-wired command coupling. +# Install and bootstrap official bundles +pip install -U specfact-cli +specfact init --profile solo-developer -- Core runtime (`specfact-cli`) handles lifecycle, registry, contracts, and orchestration. -- Official workflow behavior lives in installable bundle packages from `nold-ai/specfact-cli-modules`. -- Flat command-path shims were removed; use workflow command groups. +# Analyze an existing repository +specfact code import my-project --repo . -Implementation ownership: +# Snapshot project state +specfact project snapshot --bundle my-project -- Runtime and registry: `specfact-cli` -- Official bundles and registry artifacts: `specfact-cli-modules` -- Legacy compatibility shims in core: `src/specfact_cli/commands/*.py` (only `app` re-export is guaranteed) +# Validate drift before implementation +specfact backlog verify-readiness --bundle -Why this matters: +# Validate contracts before release +specfact spec validate --bundle my-project +specfact govern enforce sdd my-project +``` -- Modules can evolve at different speeds without repeatedly changing CLI core wiring. -- Interfaces and contracts keep feature development isolated and safer to iterate. -- Pending OpenSpec-driven module changes can land incrementally with lower migration risk. +Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` remain available, but the preferred workflow entrypoints are `specfact backlog ceremony standup ...` and `specfact backlog ceremony refinement ...`. -### Category Command Groups and First-Run Selection +## Current Command Groups -SpecFact now groups feature commands by workflow domain: +The live CLI currently exposes these top-level commands: +- `specfact init` +- `specfact module` +- `specfact upgrade` - `specfact project ...` - `specfact backlog ...` - `specfact code ...` - `specfact spec ...` - `specfact govern ...` -On a fresh setup, `specfact init` supports first-run bundle selection: +Use [Reference: Command Topology](reference/commands.md) for the exact grouped surfaces and migration mapping. -```bash -specfact init --profile solo-developer -specfact init --install backlog,codebase -specfact init --install all -``` +## Core Docs Start Points -See [Module Categories](reference/module-categories.md) for full mappings and profile presets. +- **[Getting Started](getting-started/README.md)** +- **[Command Reference](reference/commands.md)** +- **[Reference Index](reference/README.md)** +- **[Architecture Reference](reference/architecture.md)** +- **[Module Categories](reference/module-categories.md)** +- **[Module Contracts](reference/module-contracts.md)** +- **[Installing Modules](guides/installing-modules.md)** -**Module security and extensions:** +## Canonical Modules Docs Start Points -- **[Using Module Security and Extensions](guides/using-module-security-and-extensions.md)** - How to use verified modules (arch-06) and schema extensions (arch-07) from the CLI and as a module author -- **[Extending ProjectBundle](guides/extending-projectbundle.md)** - Declare and use namespaced extension fields on Feature/ProjectBundle -- **[Module Signing and Key Rotation](guides/module-signing-and-key-rotation.md)** - Runbook for public key placement, signing, CI verification, key rotation, and emergency revocation -- **[Module Security](reference/module-security.md)** - Publisher, integrity (checksum/signature), and versioned dependencies +- **[Modules Docs Home](https://modules.specfact.io/)** +- **[Modules Command Reference](https://modules.specfact.io/reference/commands/)** +- **[Backlog Refinement Guide](https://modules.specfact.io/guides/backlog-refinement/)** +- **[Project DevOps Flow Guide](https://modules.specfact.io/guides/project-devops-flow/)** +- **[Module Development Guide](https://modules.specfact.io/guides/module-development/)** +- **[Publishing Modules Guide](https://modules.specfact.io/guides/publishing-modules/)** -### For Technical Readers +## For Technical Readers - **[Architecture Reference](reference/architecture.md)** - Current architecture model and interfaces - **[Architecture Docs Index](architecture/README.md)** - Component graph, module system, data flow, state machines - **[Architecture Implementation Status](architecture/implementation-status.md)** - Implemented vs planned features - **[Architecture ADRs](architecture/adr/README.md)** - Decision records and template - -## Module Marketplace - -SpecFact now supports a central marketplace workflow for module installation and lifecycle management. - -Official bundles are now marketplace-distributed as `nold-ai/specfact-*` modules: - -- `nold-ai/specfact-project` -- `nold-ai/specfact-backlog` -- `nold-ai/specfact-codebase` -- `nold-ai/specfact-spec` -- `nold-ai/specfact-govern` - -This page remains the core-side overview for marketplace concepts and docs navigation. -Bundle-specific deep documentation is canonically owned by `specfact-cli-modules` and is currently published at: -`https://modules.specfact.io/`. +## Additional Core Guides - **[Installing Modules](guides/installing-modules.md)** - Install, list, uninstall, and upgrade modules - **[Module Marketplace](guides/module-marketplace.md)** - Registry model, security checks, and discovery priority - **[Marketplace Bundles](guides/marketplace.md)** - Official bundle ids, trust tiers, and dependency auto-install behavior - **[Code Review Module](modules/code-review.md)** - Install and use the `nold-ai/specfact-code-review` scaffold under `specfact code review` - **[Module Signing and Key Rotation](guides/module-signing-and-key-rotation.md)** - Signing and key management runbook - -Module lifecycle note: use `specfact module` (`init`, `install`, `list`, `show`, `search`, `enable`, `disable`, `uninstall`, `upgrade`) for module management. - -## 📚 Documentation - -### Guides - -- **[Command Chains](guides/command-chains.md)** ⭐ **NEW** - Complete workflows from start to finish -- **[Agile/Scrum Workflows](guides/agile-scrum-workflows.md)** - Persona-based collaboration for teams -- **[Policy Engine Commands](guides/policy-engine-commands.md)** - Run backlog readiness and ceremony workflows -- **[DevOps Backlog Integration](guides/devops-adapter-integration.md)** 🆕 **NEW FEATURE** - Integrate SpecFact into agile DevOps workflows with bidirectional backlog sync -- **[Backlog Refinement](guides/backlog-refinement.md)** 🆕 **NEW FEATURE** - AI-assisted template-driven backlog refinement for standardizing work items -- **[Backlog Dependency Analysis](guides/backlog-dependency-analysis.md)** - Analyze critical path, cycles, orphans, and dependency impact from backlog graph data -- **[Backlog Delta Commands](guides/backlog-delta-commands.md)** - Track backlog graph changes under `specfact backlog delta` -- **[Project DevOps Flow](guides/project-devops-flow.md)** - Run plan/develop/review/release/monitor stage actions from one command surface -- **[Extending ProjectBundle](guides/extending-projectbundle.md)** - Add namespaced custom fields to Feature/ProjectBundle (arch-07) -- **[Using Module Security and Extensions](guides/using-module-security-and-extensions.md)** - Use arch-06 (module security) and arch-07 (schema extensions) from CLI and as a module author -- **[Sidecar Validation](guides/sidecar-validation.md)** 🆕 - Validate external codebases without modifying source -- **[Thorough Codebase Validation](reference/thorough-codebase-validation.md)** - Quick check, contract-full, sidecar, dogfooding -- **[UX Features](guides/ux-features.md)** - Progressive disclosure, context detection, intelligent suggestions -- **[Use Cases](guides/use-cases.md)** - Real-world scenarios and workflows -- **[IDE Integration](guides/ide-integration.md)** - Set up slash commands in your IDE -- **[CoPilot Mode](guides/copilot-mode.md)** - Using `--mode copilot` on CLI -- **[Template Customization](guides/template-customization.md)** 🆕 **NEW** - Create and customize backlog templates for your team -- **[Troubleshooting](guides/troubleshooting.md)** - Common issues and solutions -- **[Competitive Analysis](guides/competitive-analysis.md)** - How SpecFact compares - -### DevOps & Backlog Sync 🚀 - -**For Developers & DevOps Teams**: Keep your backlogs in sync with feature branches, code changes, and validations. - -- **[DevOps Integration Guide](guides/devops-adapter-integration.md)** ⭐ - Complete guide for GitHub Issues and Azure DevOps integration - - **Cross-Adapter Sync**: Lossless round-trip migration between backlog tools (GitHub ↔ ADO) - - **Bidirectional Sync**: Import backlog items as proposals, export proposals as backlog items - - **Code Change Tracking**: Automatically detect commits and add progress comments - - **Status Synchronization**: Keep OpenSpec and backlog status in sync - -- **[Backlog Refinement Guide](guides/backlog-refinement.md)** 🆕 **NEW** - AI-assisted template-driven refinement for standardizing work items - - **[Tutorial: Backlog Refine with AI IDE](getting-started/tutorial-backlog-refine-ai-ide.md)** - End-to-end tutorial for agile DevOps teams (slash prompt, DoR, split stories, underspec/overspec) - - **[Tutorial: Daily Standup and Sprint Review](getting-started/tutorial-daily-standup-sprint-review.md)** - Daily standup view, post yesterday/today/blockers, interactive mode, Copilot export (GitHub/ADO) - - **Template Detection**: Automatically detect which template matches a backlog item with priority-based resolution - - **AI-Assisted Refinement**: Generate prompts for IDE AI copilots to refine unstructured input - - **Confidence Scoring**: Validate refined content and provide confidence scores - - **Lossless Preservation**: Preserve original backlog data for round-trip synchronization - - **Agile Filtering** 🆕: Filter by sprint, release, iteration, labels, state, assignee for agile workflows - - **Persona/Framework Support** 🆕: Filter templates by persona (product-owner, architect, developer) and framework (scrum, safe, kanban) - - **Definition of Ready (DoR)** 🆕: Validate sprint readiness with repo-level DoR configuration - - **Preview/Write Safety** 🆕: Preview mode by default, explicit `--write` flag for writeback - - **OpenSpec Integration** 🆕: Add OpenSpec reference comments with `--openspec-comment` flag (preserves original body) - - **Template Customization** 🆕: Create custom templates for your team - see [Template Customization Guide](guides/template-customization.md) - -- **[Authentication](reference/authentication.md)** - Device code auth for GitHub and Azure DevOps -- **[GitHub Adapter](adapters/github.md)** - GitHub Issues adapter reference -- **[Azure DevOps Adapter](adapters/azuredevops.md)** - Azure DevOps work items adapter reference -- **[Backlog Adapter Patterns](adapters/backlog-adapter-patterns.md)** - Patterns for implementing backlog adapters - -**Quick Start for DevOps Teams:** - -```bash -# Export OpenSpec proposals to GitHub Issues -specfact project sync bridge --adapter github --mode export-only \ - --repo-owner your-org --repo-name your-repo - -# Export to Azure DevOps work items -specfact project sync bridge --adapter ado --mode export-only \ - --ado-org your-org --ado-project your-project - -# Cross-adapter sync: GitHub -> ADO (lossless round-trip) -specfact project sync bridge --adapter github --mode bidirectional \ - --bundle main --backlog-ids 123 -specfact project sync bridge --adapter ado --mode export-only \ - --bundle main --change-ids -``` - -### Reference - -- **[Reference Documentation](reference/)** - Complete technical reference index -- **[Command Reference](reference/commands.md)** - Complete command documentation -- **[Authentication](reference/authentication.md)** - Device code auth flows and token storage -- **[Architecture](reference/architecture.md)** - Technical design and principles -- **[Architecture Docs Index](architecture/README.md)** - Deep-dive architecture documentation -- **[Architecture Implementation Status](architecture/implementation-status.md)** - Current vs planned architecture scope -- **[Architecture ADRs](architecture/adr/README.md)** - Architecture decision records -- **[Bridge Registry](reference/bridge-registry.md)** 🆕 - Module-declared bridge converters and lifecycle registration -- **[Operational Modes](reference/modes.md)** - CI/CD vs CoPilot modes -- **[Directory Structure](reference/directory-structure.md)** - Project structure - -### Module Protocol Reporting - -- Lifecycle protocol compliance reporting now classifies modules using the effective runtime interface and - emits a single aggregate summary line for full/partial/legacy status. - -### Examples - -- **[Brownfield Examples](examples/)** - Real-world modernization examples -- **[Quick Examples](examples/quick-examples.md)** - Code snippets and patterns - ---- - -## 🆘 Getting Help - -### Documentation - -You're here! Browse the guides above. - -### Community - -- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) - Ask questions -- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) - Report bugs - -### Direct Support - -- 📧 Email: [hello@noldai.com](mailto:hello@noldai.com) - ---- - -## 🤝 Contributing - -Found an error or want to improve the docs? - -1. Fork the repository -2. Edit the markdown files in `docs/` -3. Submit a pull request - -See [CONTRIBUTING.md](https://github.com/nold-ai/specfact-cli/blob/main/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](https://github.com/nold-ai/specfact-cli/blob/main/TRADEMARKS.md) for more information. - -**License**: See [LICENSE](https://github.com/nold-ai/specfact-cli/blob/main/LICENSE) for licensing information. diff --git a/docs/installation/enhanced-analysis-dependencies.md b/docs/installation/enhanced-analysis-dependencies.md index 5c01aaa3..061f0a95 100644 --- a/docs/installation/enhanced-analysis-dependencies.md +++ b/docs/installation/enhanced-analysis-dependencies.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Enhanced Analysis Dependencies +permalink: /installation/enhanced-analysis-dependencies/ +--- + # Enhanced Analysis Dependencies ## Python Package Dependencies diff --git a/docs/openspec-opsx-migration.md b/docs/openspec-opsx-migration.md index c66629f7..16dff6a6 100644 --- a/docs/openspec-opsx-migration.md +++ b/docs/openspec-opsx-migration.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Openspec Opsx Migration +permalink: /openspec-opsx-migration/ +--- + # OpenSpec OPSX Migration SpecFact CLI has migrated to **OpenSpec OPSX** (fluid, action-based workflow). Project context and configuration now use `openspec/config.yaml` as the primary source; `openspec/project.md` is supported as a legacy fallback so existing repos keep working. diff --git a/docs/plans/ci-pr-orchestrator-log-artifacts.md b/docs/plans/ci-pr-orchestrator-log-artifacts.md index fc9cbf25..53e45c5b 100644 --- a/docs/plans/ci-pr-orchestrator-log-artifacts.md +++ b/docs/plans/ci-pr-orchestrator-log-artifacts.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Ci Pr Orchestrator Log Artifacts +permalink: /plans/ci-pr-orchestrator-log-artifacts/ +--- + # Plan: PR Orchestrator — Attach Test and Repro Logs to CI Runs **Repository**: `nold-ai/specfact-cli` (public) diff --git a/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md b/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md index 77fc3057..e9af06b4 100644 --- a/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md +++ b/docs/prompts/PROMPT_VALIDATION_CHECKLIST.md @@ -1,3 +1,9 @@ +--- +layout: default +title: PROMPT VALIDATION CHECKLIST +permalink: /prompts/PROMPT_VALIDATION_CHECKLIST/ +--- + # Prompt Validation Checklist This checklist helps ensure prompt templates are correct, aligned with CLI commands, and provide good UX. diff --git a/docs/prompts/README.md b/docs/prompts/README.md index 0b8f162c..2b45a77e 100644 --- a/docs/prompts/README.md +++ b/docs/prompts/README.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Prompts +permalink: /prompts/ +--- + # 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. diff --git a/docs/reference/README.md b/docs/reference/README.md index d34cf38a..6c54b606 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -6,66 +6,69 @@ permalink: /reference/ # Reference Documentation -Complete technical reference for SpecFact CLI. +Complete technical reference for the **core SpecFact CLI platform**. -## Available References +This section documents the stable runtime, command topology, contracts, registry model, and ownership boundaries that `specfact-cli` owns directly. +For bundle-specific deep command guides and runbooks, use the canonical modules docs site at `https://modules.specfact.io/`. -- **[Commands](commands.md)** - Complete command reference with all options -- **[Thorough Codebase Validation](thorough-codebase-validation.md)** - Quick check, contract-decorated, sidecar, and dogfooding +## Core Reference Topics + +- **[Commands](commands.md)** - Exact grouped command topology and migration mapping - **[Command Syntax Policy](command-syntax-policy.md)** - Source-of-truth argument syntax conventions for docs -- **[Authentication](authentication.md)** - Device code auth flows and token storage - **[Architecture](architecture.md)** - Technical design, module structure, and internals +- **[Authentication](authentication.md)** - Device code auth flows and token storage - **[Debug Logging](debug-logging.md)** - Where and what is logged when using `--debug` - **[Operational Modes](modes.md)** - CI/CD vs CoPilot modes -- **[Specmatic API](specmatic.md)** - Specmatic integration API reference (functions, classes, integration points) -- **[Telemetry](telemetry.md)** - Opt-in analytics and privacy guarantees -- **[Feature Keys](feature-keys.md)** - Key normalization and formats -- **[Directory Structure](directory-structure.md)** - Project structure and organization -- **[Schema Versioning](schema-versioning.md)** - Bundle schema versions and backward compatibility (v1.0, v1.1) +- **[Module Categories](module-categories.md)** - Category grouping model and canonical bundle assignments +- **[Module Contracts](module-contracts.md)** - Runtime-facing interfaces and ownership boundary - **[Module Security](module-security.md)** - Marketplace/module integrity and publisher metadata -- **[Module Categories](module-categories.md)** - Category grouping model, canonical module assignments, bundles, and first-run profiles -- **[Dependency resolution](dependency-resolution.md)** - How module/pip dependency resolution works and bypass options - -## Quick Reference - -### Commands +- **[Bridge Registry](bridge-registry.md)** - Registry-facing bridge converter declarations +- **[Directory Structure](directory-structure.md)** - Project structure and organization +- **[Feature Keys](feature-keys.md)** - Key normalization and formats +- **[Dependency Resolution](dependency-resolution.md)** - Module/pip dependency resolution behavior +- **[Thorough Codebase Validation](thorough-codebase-validation.md)** - Validation strategy overview -- `specfact code import from-bridge --adapter speckit` - Import from external tools via bridge adapter -- `specfact code import ` - Reverse-engineer plans from code -- `specfact project snapshot --bundle ` - Save current backlog graph as baseline snapshot -- `specfact project devops-flow --stage ` - Run integrated DevOps stage actions -- `specfact govern enforce stage` - Configure quality gates -- `specfact code repro` - Run full validation suite -- `specfact project sync bridge --adapter --bundle ` - Sync with external tools via bridge adapter -- `specfact spec validate [--bundle ]` - Validate OpenAPI/AsyncAPI specifications -- `specfact spec generate-tests [--bundle ]` - Generate contract tests from specifications -- `specfact spec mock [--bundle ]` - Launch mock server for development -- `specfact init ide --ide ` - Initialize IDE integration explicitly -- `specfact module install [--scope user|project] [--source auto|bundled|marketplace] [--repo PATH]` - Install modules with scope and source control (bare names resolve through the configured source policy) -- `specfact module list [--source ...] [--show-origin] [--show-bundled-available]` - List modules with trust/publisher, optional origin details, and optional bundled-not-installed section -- `specfact module show ` - Show detailed module metadata and full command tree with short descriptions -- `specfact module search ` - Search marketplace and installed modules -- `specfact module uninstall ` / `specfact module upgrade [|--all]` - Manage module lifecycle with source-aware behavior +## Live Command Topology Summary -### Modes +Current top-level commands in the shipped CLI: -- **CI/CD Mode** - Fast, deterministic execution -- **CoPilot Mode** - Enhanced prompts with context injection +- `specfact init` +- `specfact module` +- `specfact upgrade` +- `specfact project ...` +- `specfact backlog ...` +- `specfact code ...` +- `specfact spec ...` +- `specfact govern ...` -### IDE Integration +Selected current command examples: -- `specfact init ide --ide ` - Set up slash commands in IDE -- See [IDE Integration Guide](../guides/ide-integration.md) for details +- `specfact code import from-bridge --adapter speckit --repo .` +- `specfact code import --repo .` +- `specfact project snapshot --bundle ` +- `specfact project devops-flow --stage ` +- `specfact project sync bridge --adapter --bundle ` +- `specfact project import --bundle ` +- `specfact spec validate --bundle ` +- `specfact spec generate-tests --bundle --output tests/` +- `specfact spec mock --bundle ` +- `specfact govern enforce sdd [BUNDLE]` +- `specfact code repro` +- `specfact init ide --ide ` +- `specfact module install [--scope user|project] [--source auto|bundled|marketplace] [--repo PATH]` +- `specfact module list [--source ...] [--show-origin] [--show-bundled-available]` +- `specfact module show ` +- `specfact module search ` +- `specfact module uninstall ` +- `specfact module upgrade [|--all]` -## Technical Details +## Ownership Boundary -- **Architecture**: See [Architecture](architecture.md) -- **Command Registry and Module System**: See [Architecture - Command Registry and Module System](architecture.md#command-registry-and-module-system) -- **Operational Modes**: See [Architecture - Operational Modes](architecture.md#operational-modes) -- **Ownership Boundary**: See [Architecture - Core vs modules-repo ownership boundary](architecture.md#core-vs-modules-repo-ownership-boundary) +- Core docs site: command topology, runtime lifecycle, contracts, registry, trust, architecture +- Canonical modules docs site: in-depth bundle commands, workflow tutorials, adapters, official module operations -## Related Documentation +See also: -- [Getting Started](../getting-started/README.md) - Installation and first steps -- [Guides](../guides/README.md) - Usage guides and examples -- [Examples](../examples/README.md) - Real-world examples +- [Getting Started](../getting-started/README.md) +- [Documentation Index](../README.md) +- [Canonical modules docs site](https://modules.specfact.io/) diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 593771b3..895cac67 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -6,40 +6,129 @@ permalink: /reference/commands/ # Command Reference -SpecFact CLI now ships a lean core. Workflow commands are installed from marketplace bundles. +SpecFact CLI ships a lean core. Workflow commands are installed from official or marketplace modules and mounted under grouped command families. Flat root-level compatibility shims were removed in `0.40.0`; use category-group commands only. ## Top-Level Commands -Root command surface includes core commands and installed category groups only: +The live root command surface includes: - `specfact init` - `specfact module` - `specfact upgrade` -- `specfact code ...` - `specfact backlog ...` +- `specfact code ...` +- `specfact govern ...` - `specfact project ...` - `specfact spec ...` -- `specfact govern ...` -Use `specfact init --profile ` (or `--install `) to install workflow bundles. +Use `specfact init --profile ` or `specfact init --install ` to bootstrap the workflow bundles you need. -## Workflow Command Groups +## Core-Owned Commands -After bundle install, command groups are mounted by category: +### `specfact init` -- `specfact project ...` -- `specfact backlog ...` -- `specfact code ...` -- `specfact spec ...` -- `specfact govern ...` +Bootstrap SpecFact and manage first-run setup. + +- `specfact init --profile ` +- `specfact init --install ` +- `specfact init ide [--ide ]` + +### `specfact module` + +Manage installed modules and registries. + +- `specfact module init` +- `specfact module install` +- `specfact module uninstall` +- `specfact module add-registry` +- `specfact module list-registries` +- `specfact module remove-registry` +- `specfact module enable` +- `specfact module disable` +- `specfact module search` +- `specfact module list` +- `specfact module show` +- `specfact module upgrade` +- `specfact module alias` + +### `specfact upgrade` + +Check for and install CLI updates. + +## Installed Workflow Command Groups + +After bundle install, workflow commands are mounted by category: + +### `specfact project` -## Bundle to Command Mapping +- `project link-backlog` +- `project health-check` +- `project devops-flow` +- `project snapshot` +- `project regenerate` +- `project export-roadmap` +- `project export` +- `project import` +- `project lock` +- `project unlock` +- `project locks` +- `project init-personas` +- `project merge` +- `project resolve-conflict` +- `project version` +- `project sync` + +### `specfact backlog` + +- `backlog ceremony` +- `backlog delta` +- `backlog auth` +- `backlog sync` +- `backlog verify-readiness` +- `backlog analyze-deps` +- `backlog diff` +- `backlog promote` +- `backlog refine` +- `backlog daily` +- `backlog init-config` +- `backlog map-fields` +- `backlog add` + +Preferred ceremony paths: + +- `specfact backlog ceremony standup ...` +- `specfact backlog ceremony refinement ...` + +Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` remain available. + +### `specfact code` + +- `code review` +- `code import` +- `code analyze` +- `code drift` +- `code validate` +- `code repro` + +### `specfact spec` + +- `spec validate` +- `spec backward-compat` +- `spec generate-tests` +- `spec mock` + +### `specfact govern` + +- `govern enforce` +- `govern patch` + +## Bundle To Command Mapping | Bundle ID | Group | Main command families | |---|---|---| -| `nold-ai/specfact-project` | `project` | `project link-backlog`, `project health-check`, `project devops-flow`, `project snapshot`, `project regenerate`, `project export-roadmap`, `project import`, `project export`, `project sync` | -| `nold-ai/specfact-backlog` | `backlog` | `backlog ceremony`, `backlog refine`, `backlog daily`, `backlog sync`, `backlog auth`, `backlog analyze-deps`, `backlog verify-readiness`, `backlog delta`, `backlog add` | +| `nold-ai/specfact-project` | `project` | `project link-backlog`, `project health-check`, `project devops-flow`, `project snapshot`, `project regenerate`, `project export-roadmap`, `project import`, `project export`, `project sync`, `project version` | +| `nold-ai/specfact-backlog` | `backlog` | `backlog ceremony`, `backlog refine`, `backlog daily`, `backlog sync`, `backlog auth`, `backlog analyze-deps`, `backlog verify-readiness`, `backlog delta`, `backlog add`, `backlog map-fields` | | `nold-ai/specfact-codebase` | `code` | `code analyze`, `code drift`, `code validate`, `code repro`, `code import`, `code review` | | `nold-ai/specfact-spec` | `spec` | `spec validate`, `spec backward-compat`, `spec generate-tests`, `spec mock` | | `nold-ai/specfact-govern` | `govern` | `govern enforce`, `govern patch` | @@ -51,7 +140,7 @@ Flat compatibility shims were removed in `0.40.0`. Use grouped commands. | Removed | Replacement | |---|---| | `specfact plan ...` | Removed — use `specfact project devops-flow` or `specfact project snapshot` | -| `specfact import ...` | `specfact code import ...` (codebase import) or `specfact project import ...` (persona Markdown) | +| `specfact import ...` | `specfact code import ...` (codebase import) or `specfact project import ...` (persona Markdown import) | | `specfact sync ...` | `specfact project sync ...` | | `specfact backlog ...` (flat module) | `specfact backlog ...` (bundle group) | | `specfact analyze ...` | `specfact code analyze ...` | @@ -67,37 +156,37 @@ Flat compatibility shims were removed in `0.40.0`. Use grouped commands. ## Common Flows ```bash -# First run (required) +# First run specfact init --profile solo-developer # Install specific workflow bundle specfact module install nold-ai/specfact-backlog -# Project workflow examples +# Code + project flow specfact code import legacy-api --repo . specfact project snapshot --bundle legacy-api -# Code workflow examples -specfact code validate sidecar init legacy-api /path/to/repo -specfact code repro --verbose - -# Backlog workflow examples +# Backlog flow specfact backlog ceremony standup --help specfact backlog ceremony refinement --help +specfact backlog verify-readiness --bundle legacy-api + +# Bridge synchronization +specfact project sync bridge --adapter github --bundle legacy-api --mode export-only # Spec validation examples specfact spec validate --bundle my-api specfact spec generate-tests --bundle my-api --output tests/ ``` -## See Also +## Handoff To Canonical Modules Docs + +This command reference remains part of the core docs set because it explains the lean-core command topology and ownership boundary. +Bundle-specific command details, tutorials, and adapter runbooks live in the canonical modules docs site, currently published at `https://modules.specfact.io/`. +See also: + +- [Reference Index](README.md) - [Module Categories](module-categories.md) -- [Marketplace Bundles](../guides/marketplace.md) - [Installing Modules](../guides/installing-modules.md) - [Canonical modules docs site](https://modules.specfact.io/) - -> Modules docs handoff: this command reference remains part of the core docs set because it -> explains the lean-core command topology. Bundle-specific command details live in the -> canonical modules docs site, currently published at -> `https://modules.specfact.io/`. diff --git a/docs/reference/feature-keys.md b/docs/reference/feature-keys.md index 15885f4b..a37c0166 100644 --- a/docs/reference/feature-keys.md +++ b/docs/reference/feature-keys.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Feature Keys +permalink: /reference/feature-keys/ +--- + # Feature Key Normalization Reference documentation for feature key formats and normalization in SpecFact CLI. diff --git a/docs/reference/parameter-standard.md b/docs/reference/parameter-standard.md index e045f561..4d2fad77 100644 --- a/docs/reference/parameter-standard.md +++ b/docs/reference/parameter-standard.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Parameter Standard +permalink: /reference/parameter-standard/ +--- + # Parameter Standard **Date**: 2025-11-26 diff --git a/docs/reference/specmatic.md b/docs/reference/specmatic.md index c2646738..dd80079b 100644 --- a/docs/reference/specmatic.md +++ b/docs/reference/specmatic.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Specmatic +permalink: /reference/specmatic/ +--- + # Specmatic API Reference > **API Reference for Specmatic Integration** diff --git a/docs/reference/telemetry.md b/docs/reference/telemetry.md index f325641b..b2917208 100644 --- a/docs/reference/telemetry.md +++ b/docs/reference/telemetry.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Telemetry +permalink: /reference/telemetry/ +--- + # Privacy-First Telemetry (Optional) > **Opt-in analytics that highlight how SpecFact prevents brownfield regressions.** diff --git a/docs/technical/README.md b/docs/technical/README.md index f9241822..4caf47c2 100644 --- a/docs/technical/README.md +++ b/docs/technical/README.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Technical +permalink: /technical/ +--- + # Technical Deep Dives Technical documentation for contributors and developers working on SpecFact CLI. diff --git a/docs/technical/code2spec-analysis-logic.md b/docs/technical/code2spec-analysis-logic.md index 2760d924..36713bc3 100644 --- a/docs/technical/code2spec-analysis-logic.md +++ b/docs/technical/code2spec-analysis-logic.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Code2spec Analysis Logic +permalink: /technical/code2spec-analysis-logic/ +--- + # 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. diff --git a/docs/technical/dual-stack-pattern.md b/docs/technical/dual-stack-pattern.md index 7df5c21e..afa76024 100644 --- a/docs/technical/dual-stack-pattern.md +++ b/docs/technical/dual-stack-pattern.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Dual Stack Pattern +permalink: /technical/dual-stack-pattern/ +--- + # Dual-Stack Enrichment Pattern - Technical Specification **Status**: ✅ **IMPLEMENTED** (v0.13.0+) diff --git a/docs/technical/testing.md b/docs/technical/testing.md index 58dd92ed..c7191fc9 100644 --- a/docs/technical/testing.md +++ b/docs/technical/testing.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Testing +permalink: /technical/testing/ +--- + # Testing Guide This document provides comprehensive guidance on testing the SpecFact CLI, including examples of how to test the `.specfact/` directory structure. diff --git a/docs/validation-integration.md b/docs/validation-integration.md index c5a6b478..ceced7f3 100644 --- a/docs/validation-integration.md +++ b/docs/validation-integration.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Validation Integration +permalink: /validation-integration/ +--- + # Validation Integration with Change Proposals This document describes how SpecFact validation integrates with OpenSpec change proposals to validate against proposed specifications. diff --git a/tests/unit/docs/test_release_docs_parity.py b/tests/unit/docs/test_release_docs_parity.py index f0301af1..12d59235 100644 --- a/tests/unit/docs/test_release_docs_parity.py +++ b/tests/unit/docs/test_release_docs_parity.py @@ -96,7 +96,6 @@ def test_bundle_focused_pages_use_handoff_note_instead_of_future_migration_langu # --------------------------------------------------------------------------- - def _scan_authored_docs(pattern: str) -> list[tuple[str, int, str]]: """Return list of (relative_path, line_number, line_text) for pattern hits. @@ -119,13 +118,13 @@ def _scan_authored_docs(pattern: str) -> list[tuple[str, int, str]]: if pattern not in line: continue stripped = line.strip() - # Skip comment lines in code blocks - if stripped.startswith("#"): + # Skip code-block comment lines, but do not ignore Markdown headings. + if stripped.startswith("#") and not stripped.startswith( + ("# ", "## ", "### ", "#### ", "##### ", "###### ") + ): continue - # Skip blockquote lines (historical/migration notes) if stripped.startswith(">"): continue - # Skip lines that explicitly label the pattern as removed lower = stripped.lower() if "removed" in lower or "(removed)" in lower or "is removed" in lower: continue @@ -138,19 +137,16 @@ def _fmt_hits(hits: list[tuple[str, int, str]]) -> str: def test_removed_project_plan_syntax_absent_from_authored_docs() -> None: - """specfact project plan is not a shipped command; must not appear as current syntax.""" hits = _scan_authored_docs("specfact project plan") assert not hits, f"Removed syntax 'specfact project plan' still present:\n{_fmt_hits(hits)}" def test_removed_project_import_from_bridge_syntax_absent_from_authored_docs() -> None: - """project import from-bridge moved to code import from-bridge; old path must not appear.""" hits = _scan_authored_docs("project import from-bridge") assert not hits, f"Removed syntax 'project import from-bridge' still present:\n{_fmt_hits(hits)}" def test_removed_backlog_policy_syntax_absent_from_authored_docs() -> None: - """backlog policy is not a shipped subcommand; must not appear as current syntax.""" hits = _scan_authored_docs("backlog policy") assert not hits, f"Removed syntax 'backlog policy' still present:\n{_fmt_hits(hits)}" @@ -161,7 +157,6 @@ def test_removed_spec_contract_syntax_absent_from_authored_docs() -> None: def test_removed_spec_api_syntax_absent_from_authored_docs() -> None: - # Search for "specfact spec api" to avoid false positives from --spec api/openapi.yaml paths hits = _scan_authored_docs("specfact spec api") assert not hits, f"Removed syntax 'specfact spec api' still present:\n{_fmt_hits(hits)}" @@ -172,8 +167,6 @@ def test_removed_spec_sdd_syntax_absent_from_authored_docs() -> None: def test_removed_spec_generate_syntax_absent_from_authored_docs() -> None: - # "spec generate " (space) catches stale subcommands like fix-prompt, test-prompt, - # contracts-prompt etc. without matching the valid "spec generate-tests" (hyphen). hits = _scan_authored_docs("spec generate ") assert not hits, f"Removed syntax 'spec generate ' still present:\n{_fmt_hits(hits)}" @@ -184,7 +177,6 @@ def test_removed_spec_generate_syntax_absent_from_authored_docs() -> None: def test_current_code_import_from_bridge_documented() -> None: - """Bridge import moved to code import from-bridge; at least one authored doc must show this.""" hits = _scan_authored_docs("code import") assert hits, "Current syntax 'code import' must appear in at least one authored doc" @@ -204,3 +196,16 @@ def test_current_backlog_subcommands_documented_in_commands_reference() -> None: commands_doc = _repo_file("docs/reference/commands.md").read_text(encoding="utf-8") for sub in ("backlog ceremony", "backlog refine", "backlog daily", "backlog sync"): assert sub in commands_doc, f"Current subcommand '{sub}' missing from commands reference" + + +def test_all_published_docs_markdown_files_have_jekyll_front_matter() -> None: + repo_root = Path(__file__).resolve().parents[3] + docs_root = repo_root / "docs" + missing: list[str] = [] + for path in sorted(docs_root.rglob("*.md")): + if "_site" in path.parts or "vendor" in path.parts: + continue + first_line = path.read_text(encoding="utf-8").splitlines()[0] if path.read_text(encoding="utf-8") else "" + if first_line != "---": + missing.append(str(path.relative_to(repo_root))) + assert not missing, "Docs files missing front matter:\n" + "\n".join(missing)