diff --git a/docs/adapters/azuredevops.md b/docs/adapters/azuredevops.md index 142ae04..8529e34 100644 --- a/docs/adapters/azuredevops.md +++ b/docs/adapters/azuredevops.md @@ -187,7 +187,7 @@ adapter = AdoAdapter( ### Error diagnostics (PATCH failures) -When a work item PATCH fails (e.g. HTTP 400 during backlog refine or status update), the CLI shows the ADO error message and a hint in the console. With `--debug`, the log includes the ADO response snippet and the JSON Patch paths attempted so you can identify the failing field. See [Debug Logging – Examining ADO API Errors](../reference/debug-logging.md#examining-ado-api-errors) and [Troubleshooting – Backlog refine or work item PATCH fails (400/422)](../guides/troubleshooting.md#backlog-refine-or-work-item-patch-fails-400422). +When a work item PATCH fails (e.g. HTTP 400 during backlog refine or status update), the CLI shows the ADO error message and a hint in the console. With `--debug`, the log includes the ADO response snippet and the JSON Patch paths attempted so you can identify the failing field. See [Debug Logging – Examining ADO API Errors](https://docs.specfact.io/core-cli/debug-logging/#examining-ado-api-errors) and [Troubleshooting – Backlog refine or work item PATCH fails (400/422)](../guides/troubleshooting.md#backlog-refine-or-work-item-patch-fails-400422). ## Usage Examples diff --git a/docs/guides/agile-scrum-workflows.md b/docs/guides/agile-scrum-workflows.md index 9ddc88e..5039185 100644 --- a/docs/guides/agile-scrum-workflows.md +++ b/docs/guides/agile-scrum-workflows.md @@ -1046,5 +1046,5 @@ If template rendering fails: ## Related Documentation - [Command Reference - Project Commands](../reference/commands.md#project---project-bundle-management) - Complete command documentation including `project merge` and `project resolve-conflict` -- [Project Bundle Structure](../reference/directory-structure.md) - Project bundle organization +- [Project Bundle Structure](https://docs.specfact.io/reference/directory-structure/) - Project bundle organization (core CLI docs) - See [Project Commands](../reference/commands.md#project---project-bundle-management) for template customization options diff --git a/docs/reference/README.md b/docs/reference/README.md index 2a22435..399e674 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -19,12 +19,12 @@ Complete technical reference for the official modules site and bundle-owned work - **[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 -- **[Debug Logging](debug-logging.md)** - Where and what is logged when using `--debug` +- **[Debug Logging](https://docs.specfact.io/core-cli/debug-logging/)** - Where and what is logged when using `--debug` (core CLI docs) - **[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 +- **[Feature Keys](https://docs.specfact.io/reference/feature-keys/)** - Key normalization and formats (core CLI docs) +- **[Directory Structure](https://docs.specfact.io/reference/directory-structure/)** - Project structure and organization (core CLI docs) - **[Schema Versioning](schema-versioning.md)** - Bundle schema versions and backward compatibility (v1.0, v1.1) - **[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 diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index 8403805..da4e46b 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -161,6 +161,6 @@ Formal ADR pages are not yet published on the modules docs site. The current arc ## Related Docs -- [Directory Structure](directory-structure.md) +- [Directory Structure](https://docs.specfact.io/reference/directory-structure/) (core CLI docs) - [Module Development Guide](/authoring/module-development/) - [Adapter Development Guide](/authoring/adapter-development/) diff --git a/docs/reference/schema-versioning.md b/docs/reference/schema-versioning.md index 010f1e9..2a12c6b 100644 --- a/docs/reference/schema-versioning.md +++ b/docs/reference/schema-versioning.md @@ -178,4 +178,4 @@ schema_metadata: - [Architecture - Change Tracking Models](../reference/architecture.md#change-tracking-models-v11-schema) - Technical details - [Architecture - Bridge Adapter Interface](../reference/architecture.md#bridge-adapter-interface) - Adapter implementation guide -- [Directory Structure](directory-structure.md) - Bundle file organization +- [Directory Structure](https://docs.specfact.io/reference/directory-structure/) - Bundle file organization (core CLI docs) diff --git a/scripts/check-docs-commands.py b/scripts/check-docs-commands.py index 8cb7741..ef7cc07 100755 --- a/scripts/check-docs-commands.py +++ b/scripts/check-docs-commands.py @@ -18,7 +18,16 @@ REPO_ROOT = Path(__file__).resolve().parents[1] DOCS_ROOT = REPO_ROOT / "docs" CORE_DOCS_HOST = "docs.specfact.io" -ALLOWED_CORE_DOCS_ROUTES = frozenset({"/", "/reference/documentation-url-contract/"}) +ALLOWED_CORE_DOCS_ROUTES = frozenset( + { + "/", + "/reference/documentation-url-contract/", + # Core-owned reference / guides linked from modules docs (see specfact-cli docs/ permalinks) + "/core-cli/debug-logging/", + "/reference/directory-structure/", + "/reference/feature-keys/", + } +) CORE_COMMAND_PREFIXES = frozenset( { ("specfact",), diff --git a/tests/unit/test_check_docs_commands_script.py b/tests/unit/test_check_docs_commands_script.py index 04dfa0b..0b4de63 100644 --- a/tests/unit/test_check_docs_commands_script.py +++ b/tests/unit/test_check_docs_commands_script.py @@ -115,6 +115,23 @@ def test_validate_core_docs_links_rejects_unknown_route(tmp_path: Path) -> None: assert "missing/page" in findings[0].message +def test_validate_core_docs_links_allows_core_handoff_routes(tmp_path: Path) -> None: + """Handoff URLs used in modules docs must stay in ALLOWED_CORE_DOCS_ROUTES (see scripts/check-docs-commands.py).""" + script = _load_script() + doc_path = tmp_path / "handoff.md" + doc_path.write_text( + "[Debug](https://docs.specfact.io/core-cli/debug-logging/)\n" + "[Debug anchor](https://docs.specfact.io/core-cli/debug-logging/#examining-ado-api-errors)\n" + "[Directory](https://docs.specfact.io/reference/directory-structure/)\n" + "[Feature keys](https://docs.specfact.io/reference/feature-keys/)\n", + encoding="utf-8", + ) + + findings = _script_attr(script, "_validate_core_docs_links")({doc_path: doc_path.read_text(encoding="utf-8")}) + + assert not findings + + def test_docs_review_workflow_runs_docs_command_validation() -> None: workflow = (REPO_ROOT / ".github" / "workflows" / "docs-review.yml").read_text(encoding="utf-8")