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.
This commit is contained in:
sam committed 2026-09-18 13:17:02 +10:00
1 parent 8adc010577
commit a533810546
2 files changed
+17 -6

No files matched your search

+15 -6
View File
@@ -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
+2
View File
@@ -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: