From f8af83c2313ca8acef1bb2c227563340947c44cc Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 18 Sep 2026 13:17:02 +1000 Subject: [PATCH] docs(site): close the excluded-PRD link chain and reconcile the CI section Two fixes to the published site, both about not shipping something false. exclude_docs held back prds/ but let ui-service-boundary.md through, because architecture/migration-decisions.md links to it three times. That PRD in turn links to service-decomposition.md and config-schema.md, so the exclusion was still producing two dead links on the published site. Letting those two through closes the chain: the build now reports no excluded-link references at all. generated-documentation.md's "Step 9: CI" said no workflow builds, checks or publishes documentation. Adding .github/workflows/docs.yml made the first clause false. Restated to say what that workflow does and, more importantly, what it deliberately does not: it does not run docsgen, regenerate contracts.json, or publish. Generated-artifact drift is still gated locally by task check, which is the split that section exists to protect, since a CI job that regenerated output could paper over uncommitted differences rather than fail on them. --- docs/architecture/generated-documentation.md | 21 ++++++++++++++------ mkdocs.yml | 2 ++ 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/architecture/generated-documentation.md b/docs/architecture/generated-documentation.md index 473caef53..762348521 100644 --- a/docs/architecture/generated-documentation.md +++ b/docs/architecture/generated-documentation.md @@ -349,13 +349,22 @@ exist, and only the single `contracts.json` artifact is generated today. ### Step 9: CI -The documentation workflow was deleted on 2026-09-12. No workflow builds, checks, -or publishes documentation. `deploy.yml` does not reference `docs/**`. +The original documentation workflow was deleted on 2026-09-12. `deploy.yml` still +does not reference `docs/**`. -Drift is therefore gated locally, by `task check` running `docs:check` — not in -CI. Reintroducing CI for documentation requires the renderer decision first. -Any such workflow MUST check generated output and MUST NOT regenerate and -silently publish uncommitted differences. +`.github/workflows/docs.yml` (added 2026-09-18) builds the MkDocs site with +`mkdocs build --strict` on changes to `docs/**` or `mkdocs.yml`, so a dead +internal link fails before it reaches a deploy. It deliberately does no more +than that: it does not run `docsgen`, does not regenerate `contracts.json`, and +does not publish. Deployment is a separate path, run from the Ansible control +node by the `vectislabs.automation` `docs_site` role. + +Generated-artifact drift is therefore still gated locally, by `task check` +running `docs:check`, and not in CI. That split is the point. A CI job that +regenerated output would be able to paper over uncommitted differences instead +of failing on them, which is the failure this section exists to prevent, so any +future documentation workflow MUST check generated output rather than produce +it. ### Step 10: cutover — done, in reverse diff --git a/mkdocs.yml b/mkdocs.yml index 570879c3a..bdfd28eb0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,6 +19,8 @@ exclude_docs: | inspiration/ prds/* !prds/ui-service-boundary.md + !prds/service-decomposition.md + !prds/config-schema.md github-token.md theme: