test(guards): fail the build on the documentation drift this line kept re-fixing (#478)

* test(guards): fail the build on the documentation drift this line kept re-fixing

Four releases of hand-corrections shared one property: nothing would have caught
any of them. The guards below close that, each one keyed to a defect that
actually shipped.

Link liveness reads what the documents point at, so it needs no token list and
cannot go stale. It found nine dead source links in implementation-guide.md on
its first run.

Retired-surface scanning covers README, CONTRIBUTING, SECURITY, SUPPORT,
ROADMAP, the examples gallery, docs/ and .github/ — the last four sat outside
every existing guard, which is how an issue template could route reporters to a
theme class removed in 2.0. The token list is what verification supports: seven
types absent from every src/main tree. BusinessTheme and PptxSemanticBackend are
deliberately absent from it — both are alive, in 21 and 2 source files, and
forbidding them would fail the build on correct text. Historical records are
skipped by path prefix rather than a file allowlist, so a new page under
docs/archive/ is covered the day it lands.

DocsBoldFaceGuardTest pins the font rule: a *_BOLD constant resolves to its base
family and the face comes from the decoration, so naming the alias without one
renders regular. Its self-check counts every font selection rather than every
alias — counting aliases made a clean tree look like a broken scan, because the
correct end state has none.

The release-status assertion requires a published version and requires the link
to point at the tag the text names, so a half-updated block cannot pass.

implementation-guide.md loses the two sections built on the execution layer 2.0
removed, and the render-contract references that went with them: Render,
RenderPassSession, RenderStream, TextComponent and BlockText are absent from
every src/main tree. Deleting them makes the guide less wrong; describing the
real pipeline in their place is still open.

* docs: archive the engine guide that still teaches the removed execution layer

Deleting the dead names from implementation-guide.md left the model behind. The
document still walked a contributor through attaching components to an entity,
adding a render marker and a container-growth marker, implementing Breakable,
registering through build() and checking entity.hasRender() — forty lines of a
pipeline 2.0 removed, and one CONTRIBUTING now contradicts point for point.
Breakable, ParentComponent and hasRender are absent from every src/main tree.

It is archived rather than rewritten. extension-guide.md already walks the live
pipeline end to end — a semantic node, a fluent setter, a render handler, a whole
backend, snapshot tests — and package-map.md covers the layout; inventing a
replacement for an engine guide risks shipping something plausible and wrong,
which is worse than pointing at the documents that are correct. The archived copy
opens with what it describes, what removed it, and where to go instead.

Breakable, ParentComponent and hasRender( join the retired-token list, so the
model cannot return to a live document.

Two guards were weaker than the defects they were written for.

The retired-token scan could not catch BusinessTheme, because the name survives
as an examples-local helper and a repository-wide existence check cannot tell
"this type is gone" from "this type is an example's private business". The
question that matters to a reader is whether a type ships in a published
artifact, so API guidance — issue and pull-request templates, CONTRIBUTING, the
template docs — is scanned against its own list. examples/README.md is
deliberately outside it: the helper it documents is real.

The font guard accepted an alias paired with any decoration, so
HELVETICA_BOLD with decoration(ITALIC) passed while rendering neither bold nor
what the constant claims. Published snippets now name the family outright; the
rule has no exception to get subtly wrong, and the builder-chain analysis it
needed is gone.

The link check now reads .github too. The retired-token scan already covered it,
while the issue templates carry the relative links most likely to break silently.

Author: DemchaAV

CHANGELOG.md

@@ -22,6 +22,22 @@ follow semantic versioning; release dates are ISO 8601.
 - **`graph-compose-render-pptx` declares PDFBox.** It compiles against
   `org.apache.pdfbox` types while declaring only `fontbox`, taking the rest
   transitively; the resolved version is unchanged.
+- **The contributor guide stops teaching a removed architecture.** The engine
+  implementation guide still walked a new object through attaching components to an
+  entity, adding a render marker and a container-growth marker, and implementing
+  `Breakable` — a model 2.0 removed, and one the current contributing guide
+  contradicts. It is archived, with a banner naming what replaced it; the extension
+  guide and the package map are now the route for anyone adding a node, a handler or
+  a backend.
+- **Documentation drift fails the build.** Three checks now cover what four
+  releases of hand-fixing kept re-breaking: a relative link in the public docs
+  must resolve, a contributor-facing document must not name a type 2.0 removed,
+  and a published snippet that names a `*_BOLD` font constant must pair it with a
+  decoration — the constant resolves to its base family, so without the decoration
+  the text renders regular. The README release-status block must name a published
+  version and link the tag it names. `SECURITY.md`, `SUPPORT.md`, `ROADMAP.md` and
+  `.github/` are scanned for the first time; historical records are skipped by path,
+  so a new archived page is covered the day it lands.
 - **The release publishes the showcase it just built.** `cut-release.ps1` never
   ran `GenerateAllExamples`, so the site was synced from whatever happened to be
   in `examples/target/generated-pdfs` — nothing at all on a clean checkout, which

CONTRIBUTING.md

@@ -11,10 +11,9 @@ Read these files first:
 - [docs/architecture/package-map.md](./docs/architecture/package-map.md) — what lives in which package, and which of them are internal
 - [docs/operations/benchmarks.md](./docs/operations/benchmarks.md) when you touch benchmark tooling, render hot paths, layout hot paths, or performance-facing docs
 
-[docs/contributing/implementation-guide.md](./docs/contributing/implementation-guide.md)
-goes deeper on the engine, but parts of it still describe the execution layer that
-2.0 removed — read `overview.md` and `package-map.md` first and treat the guide as
-background until it is rewritten.
+[docs/contributing/extension-guide.md](./docs/contributing/extension-guide.md)
+walks the extension points end to end — a new semantic node, a fluent setter, a
+render handler, a whole backend — and is the guide to follow when adding one.
 
 They explain the current public surface, the engine/template split, and the recommended extension points.
 
@@ -320,7 +319,7 @@ For text-heavy primitives, also read:
 
 - [TextMeasurementSystem.java](./core/src/main/java/com/demcha/compose/engine/measurement/TextMeasurementSystem.java)
 - [docs/architecture/overview.md](./docs/architecture/overview.md)
-- [docs/contributing/implementation-guide.md](./docs/contributing/implementation-guide.md)
+- [docs/contributing/extension-guide.md](./docs/contributing/extension-guide.md)
 
 If the primitive should be available to application developers,
 expose it through `DocumentDsl` and a public `DocumentNode`, not a
@@ -364,7 +363,7 @@ If a change affects resolved geometry, pagination, or ordering, prefer adding or
 - Keep [README.md](./README.md) aligned with the tested examples.
 - Keep benchmark values clearly dated when they are refreshed.
 - Keep `assets/readme/*` screenshots consistent with the current render outputs.
-- If you add a new extension point or contribution pattern, update [README.md](./README.md), [docs/architecture/overview.md](./docs/architecture/overview.md), and [docs/contributing/implementation-guide.md](./docs/contributing/implementation-guide.md) as part of the same change.
+- If you add a new extension point or contribution pattern, update [README.md](./README.md), [docs/architecture/overview.md](./docs/architecture/overview.md), and [docs/contributing/extension-guide.md](./docs/contributing/extension-guide.md) as part of the same change.
 - If you change benchmark flow, benchmark artifact layout, or diff selection rules, update [README.md](./README.md) and [docs/operations/benchmarks.md](./docs/operations/benchmarks.md) in the same change.
 - Visual PDF artifacts are grouped under `target/visual-tests/clean/*` and `target/visual-tests/guides/*` so guide-line renders are easy to find separately from clean outputs.
 

core/src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java

@@ -8,6 +8,8 @@
 import java.util.List;
 import java.util.Set;
 import java.util.TreeSet;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 import java.util.function.Predicate;
 import java.util.stream.Collectors;
 
@@ -26,6 +28,62 @@ class CanonicalSurfaceGuardTest {
             "ModuleYml",
             "ModuleSummary");
 
+    /**
+     * Types the 2.0 line removed. Every one is absent from every {@code src/main}
+     * tree, so a contributor-facing document naming one is teaching code that cannot
+     * compile — which is how the template-authoring and engine-primitive sections of
+     * CONTRIBUTING went stale for a full release cycle.
+     *
+     * <p>Deliberately absent: {@code BusinessTheme} survives as an examples-local
+     * theme helper used by twenty-one example sources, and {@code PptxSemanticBackend}
+     * still ships beside the fixed-layout PPTX backend. Forbidding either would fail
+     * the build on text that is correct.</p>
+     */
+    private static final List<String> RETIRED_IN_2_0_TOKENS = List.of(
+            "InvoiceTemplateV2",
+            "ProposalTemplateV2",
+            "WeeklyScheduleTemplateV1",
+            "EntityBounds",
+            "ParentContainerUpdater",
+            "ParentComponent",
+            "Breakable",
+            "hasRender(",
+            "CvSpec",
+            "CvBuilder");
+
+    /**
+     * Types a contributor must not be pointed at when told how to build against the
+     * library, <em>even though the name still resolves somewhere in this repository</em>.
+     *
+     * <p>{@code BusinessTheme} is the case that motivated the list: 2.0 removed it from
+     * the published surface, but the examples keep a local helper of the same name, so a
+     * repository-wide existence check cannot tell "this type is gone" from "this type is
+     * an example's private business". The distinction that matters to a reader is
+     * whether the type ships in a Maven artifact, and for API guidance it does not.</p>
+     *
+     * <p>Scanned over API guidance only — issue templates, the contributing guide, the
+     * template docs — and deliberately not over {@code examples/README.md}, which
+     * documents that local helper correctly.</p>
+     */
+    private static final List<String> FORBIDDEN_IN_API_GUIDANCE = List.of(
+            "BusinessTheme");
+
+    /**
+     * Documents whose job is to record history. A migration guide, an ADR, an archived
+     * page or the changelog names retired surface on purpose, so the retired-token scan
+     * skips them by path rather than by a file list — a new historical page is then
+     * covered the day it is added, instead of failing the build until someone
+     * remembers to allowlist it.
+     */
+    private static final List<String> HISTORICAL_RECORD_PREFIXES = List.of(
+            "CHANGELOG.md",
+            "docs/adr/",
+            "docs/archive/",
+            "docs/migration/",
+            "docs/private/",
+            "docs/roadmaps/",
+            "docs/templates/v1-classic/");
+
     private static final Set<String> MAIN_CANONICAL_SOURCE_ALLOWLIST = Set.of();
 
     private static final Set<String> DOCUMENTATION_ALLOWLIST = Set.of(
@@ -117,6 +175,142 @@ void publicMarkdownDocsShouldAvoidLegacySurfaceOutsideHistoricalAuditNotes() thr
                 PUBLIC_MARKDOWN_ALLOWLIST);
     }
 
+    /**
+     * The contributor-facing surface must not teach types 2.0 removed.
+     *
+     * <p>Scans wider than the legacy check above: {@code SECURITY.md},
+     * {@code SUPPORT.md}, {@code ROADMAP.md} and {@code .github/} sit outside every
+     * existing guard, which is why an issue template could route reporters to a theme
+     * class that no longer exists and a pull-request template could offer a lane the
+     * repository dropped.</p>
+     */
+    @Test
+    void contributorFacingDocsShouldNotNameSurfaceRetiredIn2_0() throws IOException {
+        List<Path> roots = List.of(
+                PROJECT_ROOT.resolve("README.md"),
+                PROJECT_ROOT.resolve("CONTRIBUTING.md"),
+                PROJECT_ROOT.resolve("SECURITY.md"),
+                PROJECT_ROOT.resolve("SUPPORT.md"),
+                PROJECT_ROOT.resolve("ROADMAP.md"),
+                PROJECT_ROOT.resolve("examples/README.md"),
+                PROJECT_ROOT.resolve("docs"),
+                PROJECT_ROOT.resolve(".github"));
+
+        Set<String> violations = new TreeSet<>();
+        for (Path root : roots) {
+            for (Path doc : markdownUnder(root)) {
+                String rel = relative(doc);
+                if (isHistoricalRecord(rel) || PUBLIC_MARKDOWN_ALLOWLIST.contains(rel)) {
+                    continue;
+                }
+                String source = Files.readString(doc);
+                RETIRED_IN_2_0_TOKENS.stream()
+                        .filter(source::contains)
+                        .forEach(token -> violations.add(rel + " names " + token));
+            }
+        }
+
+        assertThat(violations)
+                .describedAs("these documents name a type 2.0 removed, so anyone following "
+                        + "them writes code that does not compile. A document whose purpose "
+                        + "is to record the removal belongs under one of %s.",
+                        HISTORICAL_RECORD_PREFIXES)
+                .isEmpty();
+    }
+
+    /**
+     * API guidance must not name a type that no longer ships, even when the name still
+     * resolves inside this repository.
+     *
+     * <p>Separate from the retired-token scan because the question is different: not
+     * "does this identifier exist anywhere" but "can a reader of a published artifact
+     * use it". {@code BusinessTheme} answers yes to the first and no to the second,
+     * which is exactly how an issue template came to offer it as the theming entry
+     * point months after 2.0 removed it.</p>
+     */
+    @Test
+    void apiGuidanceShouldNotOfferTypesThatNoLongerShip() throws IOException {
+        List<Path> roots = List.of(
+                PROJECT_ROOT.resolve("README.md"),
+                PROJECT_ROOT.resolve("CONTRIBUTING.md"),
+                PROJECT_ROOT.resolve("docs/templates"),
+                PROJECT_ROOT.resolve("docs/getting-started.md"),
+                PROJECT_ROOT.resolve("docs/first-document.md"),
+                PROJECT_ROOT.resolve(".github"));
+
+        Set<String> violations = new TreeSet<>();
+        for (Path root : roots) {
+            for (Path doc : markdownUnder(root)) {
+                String rel = relative(doc);
+                if (isHistoricalRecord(rel) || PUBLIC_MARKDOWN_ALLOWLIST.contains(rel)) {
+                    continue;
+                }
+                String source = Files.readString(doc);
+                FORBIDDEN_IN_API_GUIDANCE.stream()
+                        .filter(source::contains)
+                        .forEach(token -> violations.add(rel + " offers " + token));
+            }
+        }
+
+        assertThat(violations)
+                .describedAs("these documents tell a reader to build against a type that no "
+                        + "longer ships in any published artifact. A name that survives as an "
+                        + "examples-local helper is still unusable by a consumer.")
+                .isEmpty();
+    }
+
+    /**
+     * Every relative link in the public documentation resolves on disk.
+     *
+     * <p>Needs no token list and cannot go stale: it reads what the documents actually
+     * point at. Renaming a test, archiving a page or deleting an example breaks the
+     * links to it here rather than for a reader.</p>
+     */
+    @Test
+    void publicMarkdownLinksShouldResolve() throws IOException {
+        List<Path> roots = List.of(
+                PROJECT_ROOT.resolve("README.md"),
+                PROJECT_ROOT.resolve("CONTRIBUTING.md"),
+                PROJECT_ROOT.resolve("SECURITY.md"),
+                PROJECT_ROOT.resolve("SUPPORT.md"),
+                PROJECT_ROOT.resolve("ROADMAP.md"),
+                PROJECT_ROOT.resolve("examples/README.md"),
+                PROJECT_ROOT.resolve("docs"),
+                // Issue and pull-request templates carry relative links out of
+                // .github/ISSUE_TEMPLATE/, two levels deep — the shape most likely
+                // to break silently when a target moves.
+                PROJECT_ROOT.resolve(".github"));
+
+        Pattern link = Pattern.compile("\\]\\(([^)\\s]+)\\)");
+        Set<String> broken = new TreeSet<>();
+        for (Path root : roots) {
+            for (Path doc : markdownUnder(root)) {
+                if (isHistoricalRecord(relative(doc))) {
+                    continue;
+                }
+                Matcher matcher = link.matcher(Files.readString(doc));
+                while (matcher.find()) {
+                    String target = matcher.group(1);
+                    if (target.startsWith("http") || target.startsWith("mailto:") || target.startsWith("#")) {
+                        continue;
+                    }
+                    String file = target.split("#", 2)[0];
+                    if (file.isEmpty()) {
+                        continue;
+                    }
+                    if (!Files.exists(doc.getParent().resolve(file).normalize())) {
+                        broken.add(relative(doc) + " -> " + target);
+                    }
+                }
+            }
+        }
+
+        assertThat(broken)
+                .describedAs("a relative link in the public docs points at a file that does "
+                        + "not exist; the reader gets a 404 on GitHub")
+                .isEmpty();
+    }
+
     @Test
     void publicAuthoringDocsAndExamplesShouldNotImportEngineInternals() throws IOException {
         assertNoForbiddenAuthoringImports(
@@ -140,6 +334,26 @@ void semanticAuthoringValuePackagesShouldNotImportEngineInternals() throws IOExc
                         PROJECT_ROOT.resolve("core/src/main/java/com/demcha/compose/document/image")));
     }
 
+    /** Markdown files under a root, or the root itself when it is one. */
+    private static List<Path> markdownUnder(Path root) throws IOException {
+        if (Files.isRegularFile(root)) {
+            return root.toString().endsWith(".md") ? List.of(root) : List.of();
+        }
+        if (!Files.isDirectory(root)) {
+            return List.of();
+        }
+        try (var paths = Files.walk(root)) {
+            return paths.filter(Files::isRegularFile)
+                    .filter(path -> path.toString().endsWith(".md"))
+                    .sorted()
+                    .toList();
+        }
+    }
+
+    private static boolean isHistoricalRecord(String relativePath) {
+        return HISTORICAL_RECORD_PREFIXES.stream().anyMatch(relativePath::startsWith);
+    }
+
     private void assertNoForbiddenReferences(Path root, Set<String> allowlist) throws IOException {
         assertNoForbiddenReferences(root, path -> true, allowlist);
     }

core/src/test/java/com/demcha/documentation/VersionConsistencyGuardTest.java

@@ -216,6 +216,38 @@ void readmeBannerVersionDerivesFromProjectVersion() throws Exception {
                 .isFalse();
     }
 
+    /**
+     * The README release-status block advertises a version that exists.
+     *
+     * <p>It used to be a hand-edit no test covered, and the release script demanded it
+     * already name the version being cut — so between releases {@code develop} carried
+     * an unpublished version as "latest stable" behind a tag URL that 404s. The script
+     * rewrites the block now; this pins the result, and pins the link to the text so a
+     * half-updated block cannot pass.</p>
+     */
+    @Test
+    void readmeReleaseStatusNamesAPublishedVersion() throws Exception {
+        Set<String> targets = acceptableTargets();
+        String readme = Files.readString(PROJECT_ROOT.resolve("README.md"));
+
+        Matcher stable = Pattern.compile(
+                        "\\*\\*Latest stable\\*\\*:\\s*\\[v(\\d+\\.\\d+\\.\\d+)]\\(([^)]+)\\)")
+                .matcher(readme);
+        assertThat(stable.find())
+                .describedAs("README must carry a '**Latest stable**: [vX.Y.Z](…)' release-status "
+                        + "line — cut-release.ps1 rewrites it during the cut and aborts without it")
+                .isTrue();
+
+        assertThat(stable.group(1))
+                .describedAs("README 'Latest stable' must name a published release, not the one "
+                        + "in development: its tag page does not exist until the cut (one of %s)", targets)
+                .isIn(targets);
+        assertThat(stable.group(2))
+                .describedAs("the 'Latest stable' link must point at the tag it names, or the badge "
+                        + "sends readers to a different release than the text claims")
+                .endsWith("/releases/tag/v" + stable.group(1));
+    }
+
     @Test
     void readmeInstallSnippetsMatchTheProjectVersion() throws Exception {
         Set<String> targets = acceptableTargets();

docs/README.md

@@ -19,7 +19,7 @@ back here.
 | **Designer / author** wanting a custom visual style for CVs | [Templates v2 (layered) — authoring presets](templates/v2-layered/authoring-presets.md) |
 | **Maintainer of a pre-2.0 caller** (classic `*Spec` + builder templates, removed in 2.0) | [Which template system? — migration map](templates/which-template-system.md) |
 | **Contributor adding a new template family** to the library | [Templates v2 (layered) — contributor guide](templates/v2-layered/contributor-guide.md) |
-| **Contributor extending the engine** (new node type, new backend handler) | [Extension guide](contributing/extension-guide.md) → [Implementation guide](contributing/implementation-guide.md) |
+| **Contributor extending the engine** (new node type, new backend handler) | [Extension guide](contributing/extension-guide.md) → [Package map](architecture/package-map.md) |
 | **Operator** running GraphCompose in production | [Production rendering](operations/production-rendering.md) → [Performance](operations/performance.md) → [Logging](operations/logging.md) |
 
 ---
@@ -59,7 +59,7 @@ back here.
 
 ### Contributing
 - **[contributing/extension-guide.md](contributing/extension-guide.md)** — add a new node type, backend handler, or theme primitive.
-- **[contributing/implementation-guide.md](contributing/implementation-guide.md)** — internal engine notes for contributors hacking on layout / measurement / pagination.
+- **[architecture/pagination-ordering.md](architecture/pagination-ordering.md)** — how nodes are paginated and ordered, for contributors working on layout / measurement.
 - **[contributing/release-process.md](contributing/release-process.md)** — versioning, tag procedure, Maven Central publication.
 
 ### Migrations & roadmap