diff --git a/README.md b/README.md index 68de2ed7..7cde3521 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,19 @@ --- +## Documentation Topology + +`docs.specfact.io` is the canonical docs entry point for SpecFact. + +- Core CLI/runtime/platform documentation remains owned by `specfact-cli`. +- 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. +In short, module-specific deep docs are canonically owned by `specfact-cli-modules`. + +--- + ## Start Here (60 seconds) ### Install @@ -205,9 +218,10 @@ For technical architecture details (module lifecycle, registry internals, adapte SpecFact ships official bundle packages via the dedicated marketplace registry repository `nold-ai/specfact-cli-modules`. -Bundle-specific docs are still temporarily hosted in this docs set while the long-term -bundle docs home is prepared in the modules repository docs site: -`https://nold-ai.github.io/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/`. Install examples: @@ -232,9 +246,8 @@ auto-install dependencies: - `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. Module-specific guides -will move to `specfact-cli-modules` so future bundle-only changes do not require ongoing -docs maintenance in long-lived `specfact-cli` release branches. +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. --- diff --git a/docs/README.md b/docs/README.md index 3da7bb3e..1f593926 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,10 @@ +--- +layout: default +title: Documentation Index +permalink: /documentation-index/ +description: High-level index for the SpecFact CLI documentation sections and guides. +--- + # SpecFact CLI Documentation > **The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow.** @@ -84,8 +91,12 @@ SpecFact CLI uses a lifecycle-managed module system: This is the baseline for marketplace-driven module lifecycle and future community module distribution. -Module-specific guides are still temporarily hosted in this docs set while the long-term -bundle docs home is prepared in `nold-ai/specfact-cli-modules`. +`docs.specfact.io` is the canonical docs entry point for SpecFact, and this repository owns the +core CLI/runtime section of that experience. + +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. ### Why the Module System Is the Foundation @@ -93,7 +104,7 @@ 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 still hosts bundle-specific guidance temporarily for the `0.40.x` release line. +- 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: diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 9356e70c..a6f184cb 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -111,10 +111,9 @@
- Home - Getting Started - Guides - Reference + Docs Home + Core CLI + Modules
diff --git a/docs/adapters/azuredevops.md b/docs/adapters/azuredevops.md index 1648bc7b..95485c85 100644 --- a/docs/adapters/azuredevops.md +++ b/docs/adapters/azuredevops.md @@ -7,8 +7,9 @@ permalink: /adapters/azuredevops/ # Azure DevOps Adapter -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. The Azure DevOps adapter provides bidirectional synchronization between OpenSpec change proposals and Azure DevOps work items, enabling agile DevOps-driven workflow support for enterprise teams. diff --git a/docs/adapters/github.md b/docs/adapters/github.md index f936c84a..6f3059e5 100644 --- a/docs/adapters/github.md +++ b/docs/adapters/github.md @@ -7,8 +7,9 @@ permalink: /adapters/github/ # GitHub Adapter -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. The GitHub adapter provides bidirectional synchronization between OpenSpec change proposals and GitHub Issues, enabling agile DevOps-driven workflow support. diff --git a/docs/getting-started/tutorial-backlog-quickstart-demo.md b/docs/getting-started/tutorial-backlog-quickstart-demo.md index e38ca2ce..e97cb301 100644 --- a/docs/getting-started/tutorial-backlog-quickstart-demo.md +++ b/docs/getting-started/tutorial-backlog-quickstart-demo.md @@ -8,8 +8,9 @@ permalink: /getting-started/tutorial-backlog-quickstart-demo/ # Tutorial: Backlog Quickstart Demo (GitHub + ADO) -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. This is a short, copy/paste-friendly demo for new users covering: diff --git a/docs/getting-started/tutorial-backlog-refine-ai-ide.md b/docs/getting-started/tutorial-backlog-refine-ai-ide.md index a267335f..4d5b72d2 100644 --- a/docs/getting-started/tutorial-backlog-refine-ai-ide.md +++ b/docs/getting-started/tutorial-backlog-refine-ai-ide.md @@ -8,8 +8,9 @@ permalink: /getting-started/tutorial-backlog-refine-ai-ide/ # Tutorial: Backlog Refine with Your AI IDE (Agile DevOps Teams) -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. This tutorial walks agile DevOps teams through integrating SpecFact CLI backlog refinement with their AI IDE (Cursor, VS Code + Copilot, Claude Code, etc.) using the interactive slash prompt. You will improve backlog story quality, make informed decisions about underspecification, split stories when too big, fix ambiguities, respect Definition of Ready (DoR), and optionally use custom template mapping for advanced teams. diff --git a/docs/getting-started/tutorial-daily-standup-sprint-review.md b/docs/getting-started/tutorial-daily-standup-sprint-review.md index 99ef06e0..f181854f 100644 --- a/docs/getting-started/tutorial-daily-standup-sprint-review.md +++ b/docs/getting-started/tutorial-daily-standup-sprint-review.md @@ -8,8 +8,9 @@ permalink: /getting-started/tutorial-daily-standup-sprint-review/ # Tutorial: Daily Standup and Sprint Review with SpecFact CLI -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. This tutorial walks you through a complete **daily standup and sprint review** workflow using SpecFact CLI: view your backlog items, optionally post standup comments to issues, use interactive step-through and Copilot export—with **no need to pass org/repo or org/project** when you run from your cloned repo. diff --git a/docs/guides/agile-scrum-workflows.md b/docs/guides/agile-scrum-workflows.md index 3af4a041..84928c8c 100644 --- a/docs/guides/agile-scrum-workflows.md +++ b/docs/guides/agile-scrum-workflows.md @@ -7,8 +7,9 @@ permalink: /guides/agile-scrum-workflows/ # Agile/Scrum Workflows with SpecFact CLI -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. 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. diff --git a/docs/guides/backlog-delta-commands.md b/docs/guides/backlog-delta-commands.md index 9f88069a..3cabe09c 100644 --- a/docs/guides/backlog-delta-commands.md +++ b/docs/guides/backlog-delta-commands.md @@ -7,8 +7,9 @@ permalink: /guides/backlog-delta-commands/ # Backlog Delta Commands -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. `delta` commands are grouped under backlog because they describe backlog graph drift and impact, not source-code diffs. diff --git a/docs/guides/backlog-dependency-analysis.md b/docs/guides/backlog-dependency-analysis.md index ea68febc..86e03b6b 100644 --- a/docs/guides/backlog-dependency-analysis.md +++ b/docs/guides/backlog-dependency-analysis.md @@ -7,8 +7,9 @@ permalink: /guides/backlog-dependency-analysis/ # Backlog Dependency Analysis -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. Use SpecFact to build a provider-agnostic dependency graph from backlog tools and analyze execution risk before delivery. diff --git a/docs/guides/backlog-refinement.md b/docs/guides/backlog-refinement.md index 5824cb93..d99ddaac 100644 --- a/docs/guides/backlog-refinement.md +++ b/docs/guides/backlog-refinement.md @@ -7,8 +7,9 @@ permalink: /guides/backlog-refinement/ # Backlog Refinement Guide -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. > **🆕 NEW FEATURE: AI-Assisted Template-Driven Backlog Refinement** > Transform arbitrary DevOps backlog input into structured, template-compliant work items using AI-assisted refinement with template detection and validation. diff --git a/docs/guides/contract-testing-workflow.md b/docs/guides/contract-testing-workflow.md index 640bd84d..86ed0ffd 100644 --- a/docs/guides/contract-testing-workflow.md +++ b/docs/guides/contract-testing-workflow.md @@ -1,8 +1,16 @@ +--- +layout: default +title: Contract Testing Workflow +permalink: /guides/contract-testing-workflow/ +description: Practical contract testing workflow guidance for SpecFact users and developers. +--- + # Contract Testing Workflow - Simple Guide for Developers -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. ## Quick Start: Verify Your Contract diff --git a/docs/guides/custom-field-mapping.md b/docs/guides/custom-field-mapping.md index d7d610e1..7e3ddeed 100644 --- a/docs/guides/custom-field-mapping.md +++ b/docs/guides/custom-field-mapping.md @@ -7,8 +7,9 @@ permalink: /guides/custom-field-mapping/ # Custom Field Mapping Guide -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. > **Customize ADO field mappings** for your specific Azure DevOps process templates and agile frameworks. diff --git a/docs/guides/devops-adapter-integration.md b/docs/guides/devops-adapter-integration.md index e3f160e4..3ba5e66b 100644 --- a/docs/guides/devops-adapter-integration.md +++ b/docs/guides/devops-adapter-integration.md @@ -7,8 +7,9 @@ permalink: /guides/devops-adapter-integration/ # DevOps Adapter Integration Guide -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. > **🆕 NEW FEATURE: Integrate SpecFact into Agile DevOps Workflows** > Bidirectional synchronization between OpenSpec change proposals and DevOps backlog tools enables seamless integration of specification-driven development into your existing agile workflows. diff --git a/docs/guides/dual-stack-enrichment.md b/docs/guides/dual-stack-enrichment.md index 66c0db12..0ae66389 100644 --- a/docs/guides/dual-stack-enrichment.md +++ b/docs/guides/dual-stack-enrichment.md @@ -1,8 +1,16 @@ +--- +layout: default +title: Dual-Stack Enrichment Pattern +permalink: /guides/dual-stack-enrichment/ +description: Guidance for combining SpecFact CLI automation with AI IDE enrichment workflows. +--- + # Dual-Stack Enrichment Pattern -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. **Status**: ✅ **AVAILABLE** (v0.13.0+) **Last Updated**: 2025-12-23 diff --git a/docs/guides/import-features.md b/docs/guides/import-features.md index f858135d..9583f93f 100644 --- a/docs/guides/import-features.md +++ b/docs/guides/import-features.md @@ -7,8 +7,9 @@ permalink: /guides/import-features/ # Import Command Features -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. This guide covers advanced features and optimizations in the `import from-code` command. diff --git a/docs/guides/installing-modules.md b/docs/guides/installing-modules.md index de23df95..a7fcb398 100644 --- a/docs/guides/installing-modules.md +++ b/docs/guides/installing-modules.md @@ -180,5 +180,8 @@ specfact module upgrade --all Upgrade applies only to modules with origin `marketplace`. -> Temporary docs note: module-specific install and bundle behavior docs remain hosted in this +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. + > core docs set for the current release line and are planned to migrate to `specfact-cli-modules`. diff --git a/docs/guides/marketplace.md b/docs/guides/marketplace.md index 4a34ec95..6061e850 100644 --- a/docs/guides/marketplace.md +++ b/docs/guides/marketplace.md @@ -82,5 +82,6 @@ specfact module init - [Installing Modules](installing-modules.md) - [Module Categories](../reference/module-categories.md) -> Temporary docs note: bundle-specific marketplace guidance remains hosted in this core docs set -> for the current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. diff --git a/docs/guides/module-development.md b/docs/guides/module-development.md index b527c2e1..6419c7e2 100644 --- a/docs/guides/module-development.md +++ b/docs/guides/module-development.md @@ -9,8 +9,9 @@ description: How to build and package SpecFact CLI modules. This guide defines the required structure and contracts for authoring SpecFact modules. -> Temporary docs note: module-authoring guidance is still hosted in this core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. Official workflow bundle implementation now lives in the dedicated `nold-ai/specfact-cli-modules` repository. `specfact-cli` owns the lean runtime, registry, marketplace lifecycle, shared diff --git a/docs/guides/module-marketplace.md b/docs/guides/module-marketplace.md index 620b2d45..61b43c76 100644 --- a/docs/guides/module-marketplace.md +++ b/docs/guides/module-marketplace.md @@ -115,5 +115,8 @@ Scope boundary: - Full command tree, including subcommands - Short command descriptions derived from Typer command registration -> Temporary docs note: marketplace and bundle-specific docs remain hosted in this core docs set +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. + > for the current release line and are planned to migrate to `specfact-cli-modules`. diff --git a/docs/guides/module-signing-and-key-rotation.md b/docs/guides/module-signing-and-key-rotation.md index a0e47884..4d845cee 100644 --- a/docs/guides/module-signing-and-key-rotation.md +++ b/docs/guides/module-signing-and-key-rotation.md @@ -9,8 +9,9 @@ description: Runbook for signing official workflow bundles, placing public keys, This runbook defines the repeatable process for signing official workflow bundles and verifying signatures in SpecFact CLI. -> Temporary docs note: module signing guidance is still hosted in this core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. ## Key Placement diff --git a/docs/guides/policy-engine-commands.md b/docs/guides/policy-engine-commands.md index 3c800dfd..f086166d 100644 --- a/docs/guides/policy-engine-commands.md +++ b/docs/guides/policy-engine-commands.md @@ -7,8 +7,9 @@ permalink: /guides/policy-engine-commands/ # Policy Engine Commands -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. Use SpecFact policy commands to scaffold, validate, and improve policy configuration for common frameworks. diff --git a/docs/guides/project-devops-flow.md b/docs/guides/project-devops-flow.md index 73a79e68..ac793402 100644 --- a/docs/guides/project-devops-flow.md +++ b/docs/guides/project-devops-flow.md @@ -7,8 +7,9 @@ permalink: /guides/project-devops-flow/ # Project DevOps Flow -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. Use `specfact project devops-flow` to run an integrated lifecycle against a linked backlog provider. diff --git a/docs/guides/publishing-modules.md b/docs/guides/publishing-modules.md index d09b6811..09dcf18c 100644 --- a/docs/guides/publishing-modules.md +++ b/docs/guides/publishing-modules.md @@ -9,8 +9,9 @@ description: Package and publish SpecFact modules to a registry (tarball, checks This guide describes how to package a SpecFact module for registry publishing: validate structure, create a tarball and checksum, optionally sign the manifest, and automate publishing in the dedicated modules repository. -> Temporary docs note: module publishing guidance is still hosted in this core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. ## Repository ownership diff --git a/docs/guides/sidecar-validation.md b/docs/guides/sidecar-validation.md index 9749b54b..cc8cebff 100644 --- a/docs/guides/sidecar-validation.md +++ b/docs/guides/sidecar-validation.md @@ -7,8 +7,9 @@ permalink: /guides/sidecar-validation/ # Sidecar Validation Guide -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. Complete guide for using sidecar validation to validate external codebases without modifying source code. diff --git a/docs/index.md b/docs/index.md index 8d4706a6..02a5477e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,6 +7,12 @@ 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. + +**Core CLI**: this site owns runtime, lifecycle, registry, trust, 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. @@ -152,9 +158,9 @@ Official bundles are now marketplace-distributed as `nold-ai/specfact-*` modules - `nold-ai/specfact-spec` - `nold-ai/specfact-govern` -Bundle-specific documentation is still temporarily hosted in this docs set while the -long-term bundle docs home is prepared in `nold-ai/specfact-cli-modules`: -`https://nold-ai.github.io/specfact-cli-modules/`. +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/`. - **[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 diff --git a/docs/reference/authentication.md b/docs/reference/authentication.md index 2a051718..774b862f 100644 --- a/docs/reference/authentication.md +++ b/docs/reference/authentication.md @@ -7,8 +7,9 @@ permalink: /reference/authentication/ # Authentication -> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. SpecFact CLI supports device code authentication flows for GitHub and Azure DevOps to keep credentials out of scripts and CI logs. When the backlog bundle is installed, authentication commands are available under `specfact backlog auth`. diff --git a/docs/reference/commands.md b/docs/reference/commands.md index aadc08be..3ed06c76 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -93,6 +93,9 @@ specfact backlog ceremony refinement --help - [Module Categories](module-categories.md) - [Marketplace Bundles](../guides/marketplace.md) - [Installing Modules](../guides/installing-modules.md) +- [Canonical modules docs site](https://modules.specfact.io/) -> Temporary docs note: bundle-specific command details are still hosted in this core docs set -> for the current release line and are planned to migrate to `specfact-cli-modules`. +> 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/module-categories.md b/docs/reference/module-categories.md index a0cf9105..2731efa7 100644 --- a/docs/reference/module-categories.md +++ b/docs/reference/module-categories.md @@ -76,8 +76,9 @@ Compatibility note: - Flat top-level command shims were removed. Use category groups (`project`, `backlog`, `code`, `spec`, `govern`). - `specfact backlog auth ...` is provided by the backlog bundle, not by the permanent core command surface. -> Temporary docs note: this bundle/category reference remains hosted in `specfact-cli` for the -> current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. ## First-Run Profiles diff --git a/docs/reference/module-contracts.md b/docs/reference/module-contracts.md index 9323aa8b..cfd9d2ae 100644 --- a/docs/reference/module-contracts.md +++ b/docs/reference/module-contracts.md @@ -9,8 +9,10 @@ description: ModuleIOContract protocol, validation output model, and isolation r SpecFact modules integrate through a protocol-first interface and inversion-of-control loading. -> Temporary docs note: bundle-specific contract guidance remains hosted in this core docs set for -> the current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set because it documents runtime-facing +> contracts and core isolation rules. Bundle-specific contract implementation guidance lives in the +> canonical modules docs site, currently published at +> `https://modules.specfact.io/`. ## ModuleIOContract diff --git a/docs/reference/module-security.md b/docs/reference/module-security.md index 0022423e..32a51422 100644 --- a/docs/reference/module-security.md +++ b/docs/reference/module-security.md @@ -9,8 +9,9 @@ description: Trust model, checksum and signature verification, and integrity lif Module packages carry **publisher** and **integrity** metadata so installation, bootstrap, and runtime discovery verify trust before enabling a module. -> Temporary docs note: bundle-specific security guidance remains hosted in this core docs set for -> the current release line and is planned to migrate to `specfact-cli-modules`. +> Modules docs handoff: this page remains in the core docs set as release-line overview content. +> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently +> published at `https://modules.specfact.io/`. ## Trust model diff --git a/openspec/changes/docs-02-core-docs-canonical-portal/.openspec.yaml b/openspec/changes/docs-02-core-docs-canonical-portal/.openspec.yaml new file mode 100644 index 00000000..bea0667b --- /dev/null +++ b/openspec/changes/docs-02-core-docs-canonical-portal/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-17 diff --git a/openspec/changes/docs-02-core-docs-canonical-portal/CHANGE_VALIDATION.md b/openspec/changes/docs-02-core-docs-canonical-portal/CHANGE_VALIDATION.md new file mode 100644 index 00000000..111a7476 --- /dev/null +++ b/openspec/changes/docs-02-core-docs-canonical-portal/CHANGE_VALIDATION.md @@ -0,0 +1,53 @@ +# Change Validation Report: docs-02-core-docs-canonical-portal + +**Validation Date**: 2026-03-17 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Dry-run documentation dependency and ownership analysis + +## Executive Summary + +- Breaking Changes: 0 detected at runtime +- Dependent Files: Multiple docs entry points and bundle-focused pages in `README.md` and `docs/` +- Impact Level: Medium (public docs topology and ownership language change) +- Validation Result: Pass +- User Decision: Proceed with separate core and modules docs changes + +## Breaking Changes Detected + +None at runtime. This change is documentation-architecture work only. + +Potential reader-facing regression risk exists if core docs remove or reword module pages without clear handoff links, but that is a navigation/content continuity risk rather than a runtime/API break. + +## Dependencies Affected + +### Critical Alignment Dependencies + +- `README.md` still points readers at the modules GitHub Pages project URL and describes module docs migration as future work. +- `docs/index.md` still presents bundle docs as temporarily hosted in core while the modules repo already declares itself canonical. +- `docs/_layouts/default.html` will need coordinated top-level navigation changes so the public IA exposes `Docs Home`, `Core CLI`, and `Modules`. +- Multiple bundle-focused pages in `docs/guides/`, `docs/reference/`, and `docs/adapters/` still carry the current-release temporary-hosting note and will need a keep/handoff/retire decision. + +### Cross-Repository Dependencies + +- `specfact-cli-modules` must publish aligned landing copy and top navigation for the modules site. +- Cloudflare/public-domain work is an external dependency for final public URL cutover, but not a blocker for creating the docs ownership contract and handoff content first. + +## Impact Assessment + +- **Code Impact**: None expected +- **Docs Impact**: High; README, landing page, shared layout, marketplace pages, and module-focused guides/reference pages are all in scope +- **Test Impact**: New lightweight docs validation or assertion coverage is justified to prevent ownership-language drift +- **Release Impact**: Low-to-medium; the main risk is temporary reader confusion during the transition if navigation and handoff pages are incomplete + +## Format Validation + +- **proposal.md Format**: Pass +- **tasks.md Format**: Pass +- **specs Format**: Pass +- **Config.yaml Compliance**: Pass + +## OpenSpec Validation + +- **Status**: Pass +- **Command**: `openspec validate docs-02-core-docs-canonical-portal --strict` +- **Issues Found/Fixed**: 0 diff --git a/openspec/changes/docs-02-core-docs-canonical-portal/DOCS_OWNERSHIP_MAP.md b/openspec/changes/docs-02-core-docs-canonical-portal/DOCS_OWNERSHIP_MAP.md new file mode 100644 index 00000000..f0759b86 --- /dev/null +++ b/openspec/changes/docs-02-core-docs-canonical-portal/DOCS_OWNERSHIP_MAP.md @@ -0,0 +1,53 @@ +# Docs Ownership Map + +## Keep In Core + +- `README.md` +- `docs/index.md` +- `docs/README.md` +- `docs/_layouts/default.html` +- `docs/reference/commands.md` +- `docs/reference/module-contracts.md` +- `docs/reference/module-security.md` +- `docs/reference/module-categories.md` + +These pages remain core-owned because they explain the runtime, command topology, marketplace lifecycle, or the docs navigation contract itself. + +## Convert To Handoff Pages Or Handoff Notes + +- `docs/adapters/azuredevops.md` +- `docs/adapters/github.md` +- `docs/getting-started/tutorial-backlog-quickstart-demo.md` +- `docs/getting-started/tutorial-backlog-refine-ai-ide.md` +- `docs/getting-started/tutorial-daily-standup-sprint-review.md` +- `docs/guides/agile-scrum-workflows.md` +- `docs/guides/backlog-delta-commands.md` +- `docs/guides/backlog-dependency-analysis.md` +- `docs/guides/backlog-refinement.md` +- `docs/guides/contract-testing-workflow.md` +- `docs/guides/custom-field-mapping.md` +- `docs/guides/devops-adapter-integration.md` +- `docs/guides/dual-stack-enrichment.md` +- `docs/guides/import-features.md` +- `docs/guides/installing-modules.md` +- `docs/guides/marketplace.md` +- `docs/guides/module-development.md` +- `docs/guides/module-marketplace.md` +- `docs/guides/module-signing-and-key-rotation.md` +- `docs/guides/policy-engine-commands.md` +- `docs/guides/project-devops-flow.md` +- `docs/guides/publishing-modules.md` +- `docs/guides/sidecar-validation.md` +- `docs/reference/authentication.md` + +These pages remain available in core for release-line continuity, but they should carry a consistent handoff note pointing readers to the canonical modules docs site for bundle-specific deep guidance. + +## Retire Later + +- No page is removed in this change. + +The follow-up removal step should happen only after: + +1. the aligned modules docs pages are live, +2. handoff links or redirects are verified, and +3. the Cloudflare/public-domain cutover plan is ready. diff --git a/openspec/changes/docs-02-core-docs-canonical-portal/TDD_EVIDENCE.md b/openspec/changes/docs-02-core-docs-canonical-portal/TDD_EVIDENCE.md new file mode 100644 index 00000000..385b757c --- /dev/null +++ b/openspec/changes/docs-02-core-docs-canonical-portal/TDD_EVIDENCE.md @@ -0,0 +1,35 @@ +# TDD Evidence + +## Failing Before + +- Timestamp: 2026-03-17 +- Command: `pytest tests/unit/docs/test_release_docs_parity.py -q` +- Result: failed + +Observed failures before the docs updates: + +- `test_readme_and_docs_index_define_core_and_modules_split` +- `test_top_navigation_exposes_docs_home_core_cli_and_modules` +- `test_command_reference_and_docs_readme_link_to_modules_canonical_site` +- `test_bundle_focused_pages_use_handoff_note_instead_of_future_migration_language` + +Failure mode summary: + +- README and landing docs still described module docs as temporary future migration work +- top navigation still exposed legacy `Home / Getting Started / Guides / Reference` labels instead of the docs-home/core/modules split +- docs index and command reference did not link to the canonical modules docs site +- bundle-focused pages still used the old "planned to migrate" note instead of the handoff model + +## Passing After + +- Timestamp: 2026-03-17 +- Command: `pytest tests/unit/docs/test_release_docs_parity.py -q` +- Result: passed (`10 passed`) + +- Timestamp: 2026-03-17 +- Command: `hatch run pytest tests/unit/docs/test_release_docs_parity.py -q` +- Result: passed (`10 passed`) + +- Timestamp: 2026-03-17 +- Command: `openspec validate docs-02-core-docs-canonical-portal --strict` +- Result: passed diff --git a/openspec/changes/docs-02-core-docs-canonical-portal/design.md b/openspec/changes/docs-02-core-docs-canonical-portal/design.md new file mode 100644 index 00000000..93890dfd --- /dev/null +++ b/openspec/changes/docs-02-core-docs-canonical-portal/design.md @@ -0,0 +1,83 @@ +# Design: Core Docs Canonical Portal And Ownership Split + +## Context + +Today `specfact-cli` serves `docs.specfact.io`, while `specfact-cli-modules` publishes a separate GitHub Pages site under a project-path URL. The two sites are built independently and do not aggregate content during build. As a result, the current public architecture is effectively: + +```text +specfact-cli/docs ------------------> docs.specfact.io +specfact-cli-modules/docs -----------> modules.specfact.io +``` + +This change defines the core-side target information architecture without requiring a combined docs build: + +```text +docs.specfact.io -> canonical docs entry point / top-level IA +cli.docs.specfact.io -> core docs origin (specfact-cli) +modules.specfact.io -> modules docs origin (specfact-cli-modules) +``` + +Cloudflare can later route `docs.specfact.io` either: + +- as a lightweight portal that links to the two section sites, or +- as a reverse-proxy entry point for `/core/*` and `/modules/*` + +The change in this repository is limited to the core docs contract and content ownership. It does not require Cloudflare automation or reverse-proxy implementation in this repo. + +## Goals + +- Keep `specfact-cli` as the owner of the canonical docs entry experience and core runtime docs. +- Stop presenting core docs as the long-term canonical source for module-specific workflow content. +- Establish shared navigation vocabulary that both sites can implement consistently. + +## Non-Goals + +- Build a multi-repository docs artifact in CI +- Replace Jekyll +- Complete every modules-page redirect in one change + +## Core Ownership Model + +`specfact-cli` owns: + +- docs landing/portal language +- core runtime and command-surface docs +- installation and onboarding for the CLI runtime +- marketplace lifecycle concepts, trust, compatibility, and registry behavior +- cross-site docs navigation contract + +`specfact-cli` does not own the long-term deep documentation for official bundle workflows once equivalent pages are published in `specfact-cli-modules`. + +## Navigation Contract + +All public docs experiences should converge on the same top-level labels: + +- `Docs Home` +- `Core CLI` +- `Modules` + +In `specfact-cli`, those labels should appear in the top navigation and guide readers toward: + +- local core-runtime pages for core concerns +- the modules docs site for bundle-specific deep guidance + +## Content Strategy In Core + +Core-hosted module pages fall into three buckets: + +1. Keep as core-owned overview pages + - pages that explain marketplace concepts, lifecycle, or navigation into module docs +2. Convert to handoff pages + - short pages that explain the ownership boundary and link to the modules docs canonical page +3. Remove after migration + - duplicate pages with no remaining core-specific value once redirects/handoffs exist + +## Validation Strategy + +Implementation should add lightweight regression checks for: + +- landing page and README ownership language +- top-level navigation links for docs home/core/modules +- marketplace/reference pages that must distinguish core commands from bundle-delivered commands + +These checks are sufficient for this change because the primary output is docs structure and navigation behavior rather than new runtime logic. diff --git a/openspec/changes/docs-02-core-docs-canonical-portal/proposal.md b/openspec/changes/docs-02-core-docs-canonical-portal/proposal.md new file mode 100644 index 00000000..ff37f7d0 --- /dev/null +++ b/openspec/changes/docs-02-core-docs-canonical-portal/proposal.md @@ -0,0 +1,41 @@ +# Change: Core Docs Canonical Portal And Ownership Split + +## Why + +`specfact-cli` currently publishes the canonical docs domain at `docs.specfact.io`, but the live docs set still mixes two different responsibilities: + +- core CLI/runtime/platform documentation owned by `specfact-cli` +- bundle and workflow documentation that now belongs primarily to `specfact-cli-modules` + +That mixed model was acceptable during migration, but it is now creating ongoing drift. The modules repository already has its own Jekyll docs site, yet the public topology still leaves `specfact-cli` acting as the de facto source for many module-specific pages. Readers cannot clearly tell which docs are canonical, and maintainers have to keep overlapping content aligned in two repos. + +This change defines the core side of the final information architecture: `specfact-cli` remains the canonical docs entry point and owner of core runtime docs, while module-specific deep docs move to the dedicated modules site with explicit cross-site navigation. + +## What Changes + +- Modify core docs ownership guidance so `specfact-cli` explicitly owns the docs portal, core runtime/platform docs, and marketplace lifecycle concepts, while bundle-specific deep docs belong to `specfact-cli-modules`. +- Update the core landing page, README, and shared navigation language to present a canonical split between `Docs Home`, `Core CLI`, and `Modules`. +- Convert remaining module-specific pages in the core docs set into either overview/handoff pages or migration notes instead of presenting them as the long-term canonical source. +- Define the core-side publishing contract needed for Cloudflare-backed public topology, including support for an independent core docs origin and a canonical docs entry point. + +## Capabilities + +### Modified Capabilities + +- `module-docs-ownership`: core docs ownership language must move from a temporary migration note to a stable, reader-facing boundary between core docs and module docs. +- `documentation-alignment`: live docs navigation, landing pages, and marketplace guidance must align with a two-site model and stop implying that core docs are the canonical source for all module workflows. + +## Impact + +- Affected docs: `README.md`, `docs/index.md`, `docs/_layouts/default.html`, marketplace/module guidance pages, and any remaining bundle-focused handoff content in `docs/guides/` or `docs/reference/`. +- User-facing impact: readers can distinguish core runtime docs from module-owned deep docs and navigate cleanly between the canonical docs entry point, core docs, and modules docs. +- Integration points: `specfact-cli-modules` docs navigation and landing copy must align with the same ownership model; Cloudflare-managed docs domains will rely on the resulting navigation contract. +- Rollback plan: if the split causes confusion, core docs can temporarily retain handoff notes without removing duplicate content while navigation wording is refined. + +## Source Tracking + + +- **GitHub Issue**: pending +- **Issue URL**: pending +- **Last Synced Status**: local-proposal +- **Sanitized**: true diff --git a/openspec/changes/docs-02-core-docs-canonical-portal/specs/documentation-alignment/spec.md b/openspec/changes/docs-02-core-docs-canonical-portal/specs/documentation-alignment/spec.md new file mode 100644 index 00000000..863c3194 --- /dev/null +++ b/openspec/changes/docs-02-core-docs-canonical-portal/specs/documentation-alignment/spec.md @@ -0,0 +1,34 @@ +## MODIFIED Requirements + +### Requirement: Live docs reflect lean-core and grouped bundle command topology + +The live documentation set SHALL describe the current command surface as a lean core plus marketplace-installed grouped bundle commands, and SHALL organize navigation around a stable split between docs home, core docs, and modules docs. + +#### Scenario: Reader checks command examples and navigation + +- **WHEN** a reader follows command examples in README or published docs +- **THEN** core commands are shown as always available from `specfact-cli` +- **AND** bundle commands are shown through grouped command paths and marketplace installation context +- **AND** the top-level docs navigation exposes clear entry points for `Docs Home`, `Core CLI`, and `Modules`. + +### Requirement: Marketplace guidance is discoverable and non-duplicative + +Marketplace, bundle installation, dependency, trust, and publishing documentation SHALL be available through clear entry points and SHALL avoid contradictory or duplicate guidance across README, landing pages, guides, and reference pages. + +#### Scenario: Reader looks for marketplace workflow guidance + +- **WHEN** a reader wants to install, trust, publish, or understand official bundles +- **THEN** the docs provide a discoverable path from README or docs landing into marketplace-specific pages +- **AND** they provide a clear path into the modules docs site for bundle-specific deep guidance +- **AND** terminology, command examples, and workflow descriptions are consistent across those pages. + +### Requirement: Command reference reflects ownership and package boundaries + +The command reference documentation SHALL distinguish permanent core commands from marketplace-delivered bundle commands and SHALL organize module command coverage by package/category ownership instead of one legacy flat command inventory. + +#### Scenario: Reader checks command reference + +- **WHEN** a reader opens command reference documentation +- **THEN** the reference identifies which commands belong to core and which are provided by installed bundles +- **AND** bundle command coverage is grouped by category or package boundary +- **AND** readers can navigate from command docs to the relevant modules docs without ambiguity. diff --git a/openspec/changes/docs-02-core-docs-canonical-portal/specs/module-docs-ownership/spec.md b/openspec/changes/docs-02-core-docs-canonical-portal/specs/module-docs-ownership/spec.md new file mode 100644 index 00000000..63535797 --- /dev/null +++ b/openspec/changes/docs-02-core-docs-canonical-portal/specs/module-docs-ownership/spec.md @@ -0,0 +1,22 @@ +## MODIFIED Requirements + +### Requirement: Core docs declare current and target docs ownership boundaries + +The documentation SHALL state which documentation concerns remain owned by `specfact-cli` core, which concerns belong to marketplace-installed module bundles, and that module-specific deep docs are canonically owned by `specfact-cli-modules` once published there. + +#### Scenario: Reader checks docs ownership model + +- **WHEN** a reader opens the README, docs landing page, or module architecture/development documentation +- **THEN** the docs explain that core runtime, installation, lifecycle, registry, and marketplace concepts remain documented in `specfact-cli` +- **AND** they explain that bundle-specific command and workflow docs are canonically owned by `specfact-cli-modules` +- **AND** they do not describe the core docs set as the permanent home for module-specific deep guidance. + +### Requirement: Core-hosted module pages use a handoff model during migration + +Any live module-specific guide or reference page that remains in `specfact-cli` SHALL either provide core-owned overview context or a clear handoff to the canonical modules docs page. + +#### Scenario: Reader opens a bundle-focused page in core docs + +- **WHEN** a reader opens a module- or bundle-focused guide in the core docs set +- **THEN** the page states whether it is a core-owned overview or a temporary handoff page +- **AND** the page links the reader to the canonical modules docs destination when module-specific deep guidance lives there. diff --git a/openspec/changes/docs-02-core-docs-canonical-portal/tasks.md b/openspec/changes/docs-02-core-docs-canonical-portal/tasks.md new file mode 100644 index 00000000..55d0c73c --- /dev/null +++ b/openspec/changes/docs-02-core-docs-canonical-portal/tasks.md @@ -0,0 +1,30 @@ +## 1. Change Setup And Discovery + +- [x] 1.1 Create worktree `../specfact-cli-worktrees/feature/docs-02-core-docs-canonical-portal` with branch `feature/docs-02-core-docs-canonical-portal` from `origin/dev` +- [x] 1.2 Inventory the current overlap between core-hosted module pages and modules-repo pages, including which pages should remain core-owned versus become handoff pages +- [x] 1.3 Confirm the Cloudflare/public-domain assumptions with the internal plan so the docs wording does not promise unsupported routing behavior + +## 2. Spec Deltas First + +- [x] 2.1 Add spec deltas for `module-docs-ownership` covering the stable ownership split between core docs and module docs +- [x] 2.2 Add spec deltas for `documentation-alignment` covering the canonical docs portal navigation and the two-site model +- [x] 2.3 Review the affected docs pages and map each one to keep, handoff, or retire behavior before implementation begins + +## 3. Validation First + +- [x] 3.1 Add failing regression coverage or docs assertions for the landing page/README ownership language and top-level docs navigation contract +- [x] 3.2 Add failing regression coverage or docs assertions proving marketplace/module reference pages point readers to module-owned deep docs instead of treating core as the permanent canonical source +- [x] 3.3 Record the failing validation evidence in `openspec/changes/docs-02-core-docs-canonical-portal/TDD_EVIDENCE.md` + +## 4. Core Docs Realignment + +- [x] 4.1 Update `README.md`, `docs/index.md`, and `docs/_layouts/default.html` to establish the canonical docs-home/core/modules navigation model +- [x] 4.2 Convert remaining module-specific core pages into overview/handoff pages or equivalent migration notes according to the ownership map from task 2.3 +- [x] 4.3 Update marketplace/reference wording so core docs distinguish runtime-owned concepts from module-owned deep workflow documentation + +## 5. Validation And Delivery + +- [x] 5.1 Re-run the targeted docs validation checks and record passing evidence in `openspec/changes/docs-02-core-docs-canonical-portal/TDD_EVIDENCE.md` +- [x] 5.2 Run `openspec validate docs-02-core-docs-canonical-portal --strict` +- [x] 5.3 Run the relevant repo quality gates for touched docs/test files +- [x] 5.4 Open PR to `dev` from `feature/docs-02-core-docs-canonical-portal` diff --git a/tests/unit/docs/test_release_docs_parity.py b/tests/unit/docs/test_release_docs_parity.py index 7ce2672a..f126f171 100644 --- a/tests/unit/docs/test_release_docs_parity.py +++ b/tests/unit/docs/test_release_docs_parity.py @@ -44,8 +44,38 @@ def test_module_contracts_reference_external_bundle_boundary() -> None: assert "Core runtime must not import external bundle package namespaces" in contracts_doc -def test_docs_note_module_docs_are_temporarily_hosted_in_core() -> None: +def test_readme_and_docs_index_define_core_and_modules_split() -> None: readme = _repo_file("README.md").read_text(encoding="utf-8") docs_index = _repo_file("docs/index.md").read_text(encoding="utf-8") - assert "temporarily hosted" in readme - assert "temporarily hosted" in docs_index + assert "canonical docs entry point" in readme + assert "module-specific deep docs are canonically owned by `specfact-cli-modules`" in readme + assert "https://modules.specfact.io/" in readme + assert "Docs Home" in docs_index + assert "Core CLI" in docs_index + assert "Modules" in docs_index + + +def test_top_navigation_exposes_docs_home_core_cli_and_modules() -> None: + layout = _repo_file("docs/_layouts/default.html").read_text(encoding="utf-8") + assert ">Docs Home<" in layout + assert ">Core CLI<" in layout + assert ">Modules<" in layout + assert "https://modules.specfact.io/" in layout + + +def test_command_reference_and_docs_readme_link_to_modules_canonical_site() -> None: + docs_readme = _repo_file("docs/README.md").read_text(encoding="utf-8") + commands_doc = _repo_file("docs/reference/commands.md").read_text(encoding="utf-8") + assert "canonical modules docs site" in docs_readme + assert "https://modules.specfact.io/" in docs_readme + assert "canonical modules docs site" in commands_doc + assert "https://modules.specfact.io/" in commands_doc + + +def test_bundle_focused_pages_use_handoff_note_instead_of_future_migration_language() -> None: + backlog_refinement = _repo_file("docs/guides/backlog-refinement.md").read_text(encoding="utf-8") + github_adapter = _repo_file("docs/adapters/github.md").read_text(encoding="utf-8") + assert "canonical modules docs site" in backlog_refinement + assert "canonical modules docs site" in github_adapter + assert "planned to migrate to `specfact-cli-modules`" not in backlog_refinement + assert "planned to migrate to `specfact-cli-modules`" not in github_adapter