From a29c1fcdd8dc096b042eaa6fd2a09f439dbd78de Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Fri, 5 Jun 2026 10:56:57 +0100 Subject: [PATCH 1/4] docs(skill-fixtures): document the validate-skills render + diff loop The five fixture READMEs (and their expected-output mirrors) now describe the wired render/visual-diff loop: node scripts/validate-skills.mjs re-renders via the *FixtureDocument adapter and tools/preview-renderer, then compares the PNG against the committed baseline (expects IDENTICAL). Drops the stale Phase 6/7 deferred wording and points at validation/reports/skill-render-validation-2026-06-03.md. --- .../layer-stack-badge/README.md | 46 +++++++++++----- .../expected-output/README.md | 45 ++++++++------- examples/skill-fixtures/row-basic/README.md | 55 +++++++++++++------ .../row-basic/expected-output/README.md | 45 ++++++++------- .../skill-fixtures/section-basic/README.md | 46 +++++++++++----- .../section-basic/expected-output/README.md | 45 ++++++++------- .../shape-container-card/README.md | 46 +++++++++++----- .../expected-output/README.md | 45 ++++++++------- examples/skill-fixtures/table-basic/README.md | 46 +++++++++++----- .../table-basic/expected-output/README.md | 45 ++++++++------- 10 files changed, 299 insertions(+), 165 deletions(-) diff --git a/examples/skill-fixtures/layer-stack-badge/README.md b/examples/skill-fixtures/layer-stack-badge/README.md index edd433b..725fe15 100644 --- a/examples/skill-fixtures/layer-stack-badge/README.md +++ b/examples/skill-fixtures/layer-stack-badge/README.md @@ -40,22 +40,42 @@ overlap), so the layer stack is the correct primitive. ## How to run 1. `cd examples/skill-fixtures/layer-stack-badge` -2. `mvn test` +2. `mvn test` — the JUnit smoke test; asserts `compose(...)` does not + throw 3. inspect `expected-output/layout-snapshot.json` for the intended layer order, region shapes, and anchor -Phase 6 will additionally write `expected-output/output.pdf` and -`expected-output/output.png` on every run. +The committed render baseline is captured separately from the JUnit +test. A no-arg +[`LayerStackBadgeFixtureDocument`](src/main/java/com/demcha/compose/document/fixtures/layerstackbadge/LayerStackBadgeFixtureDocument.java) +exposes the same `compose(DocumentSession)` the test exercises, and +`tools/preview-renderer` drives it to `expected-output/output.pdf` and +`output.png`. Run the loop from the repo root: -## Deferred checks +- `node scripts/validate-skills.mjs` — re-render and visual-diff the PNG + against the committed baseline (expects `IDENTICAL`). +- `node scripts/validate-skills.mjs --update-baseline` — (re)capture the + `expected-output/output.{pdf,png}` baseline. -The JUnit test currently asserts only that `compose(...)` does not -throw. Three checks are pending the Phase 6 renderer and the Phase 7 -visual-diff tool: +## Checks -- layout-snapshot equality against - `expected-output/layout-snapshot.json` -- PDF byte sanity (non-empty, valid header) on - `expected-output/output.pdf` -- preview-image visual diff against a committed - `expected-output/output.png` baseline +The JUnit test still asserts only that `compose(...)` does not throw. The +render and visual-diff now run through the `LayerStackBadgeFixtureDocument` +adapter and `node scripts/validate-skills.mjs`, not the test: + +- preview-image visual diff against the committed + `expected-output/output.png` — wired. `node scripts/validate-skills.mjs` + re-renders via `tools/preview-renderer` and compares the PNG with + `tools/visual-diff`, expecting `IDENTICAL` (AE == 0). +- rendered-output sanity — wired. The runner asserts the render produced a + non-empty `output.pdf` and `output.png` (CI runs `--render-only`, since + PNG rasterisation is platform-specific). Full PDF byte equality is + intentionally skipped: PDFs carry timestamps, so parity is judged on the + PNG. +- layout-snapshot equality against `expected-output/layout-snapshot.json` + — still not enforced. `layout-snapshot.json` stays illustrative; it + documents intent, not a measured engine run. + +The captured baseline sizes and the `IDENTICAL` result for all five +fixtures are recorded in +[`../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../validation/reports/skill-render-validation-2026-06-03.md). diff --git a/examples/skill-fixtures/layer-stack-badge/expected-output/README.md b/examples/skill-fixtures/layer-stack-badge/expected-output/README.md index 83fe3c9..51f16db 100644 --- a/examples/skill-fixtures/layer-stack-badge/expected-output/README.md +++ b/examples/skill-fixtures/layer-stack-badge/expected-output/README.md @@ -1,30 +1,37 @@ # expected-output for layer-stack-badge -This folder is where the Phase 6 render-and-preview tool will write the -rendered artifacts for this fixture. Until that lands, only -`layout-snapshot.json` is present, and it is illustrative — the values -describe the layout shape the fixture intends to produce, not values -measured by a real engine run. +This folder holds the committed render baseline for this fixture. +`output.pdf` and `output.png` are produced by `tools/preview-renderer` +driving the fixture's no-arg `LayerStackBadgeFixtureDocument` adapter. +`layout-snapshot.json` is still illustrative — its values describe the +layout shape the fixture intends to produce, not values measured by a +real engine run. ## Files | File | Status | Populated by | |---|---|---| -| `layout-snapshot.json` | present, illustrative | placeholder for Phase 6 | -| `output.pdf` | absent, Phase 6 deferred | preview-renderer tool | -| `output.png` | absent, Phase 6 deferred | preview-renderer tool | +| `layout-snapshot.json` | present, illustrative | hand-authored (documents intent) | +| `output.pdf` | present (committed baseline) | `tools/preview-renderer` via `LayerStackBadgeFixtureDocument` | +| `output.png` | present (committed baseline) | `tools/preview-renderer` via `LayerStackBadgeFixtureDocument` | -## What lands when +## How the baseline was captured -- **Phase 6** (preview-renderer): every `mvn test` regenerates - `layout-snapshot.json` from the real engine, writes - `output.pdf`, and converts the first page to `output.png`. The - illustrative `notes` field on the snapshot will be removed at that - point. -- **Phase 7** (visual-diff): introduces a committed `output.png` - baseline and a tool that compares a new render against both - `layout-snapshot.json` and that baseline. Diffs are classified per +The render plus visual-diff loop is built (see +[`../../../../scripts/validate-skills.mjs`](../../../../scripts/validate-skills.mjs) +and the run recorded in +[`../../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../../validation/reports/skill-render-validation-2026-06-03.md)): + +- **Render** (`tools/preview-renderer`): `node scripts/validate-skills.mjs + --update-baseline` instantiates the no-arg `LayerStackBadgeFixtureDocument`, + calls its `compose(DocumentSession)`, writes `output.pdf`, and converts + the first page to `output.png` here. +- **Visual-diff** (`tools/visual-diff`): `node scripts/validate-skills.mjs` + re-renders and compares the new PNG against this committed `output.png`, + expecting `IDENTICAL` (AE == 0). PDFs carry timestamps, so parity is + judged on the PNG, not the PDF bytes. Diffs are classified per [`../../../../docs/visual-accuracy-contract.md`](../../../../docs/visual-accuracy-contract.md). -Do not edit `layout-snapshot.json` by hand once Phase 6 is wired; it -will be regenerated. Do edit it by hand now — it documents intent. +`layout-snapshot.json` is not part of that loop. It stays hand-authored +and illustrative, so it is safe to edit by hand; the render loop never +regenerates it. diff --git a/examples/skill-fixtures/row-basic/README.md b/examples/skill-fixtures/row-basic/README.md index d7de35b..7887eeb 100644 --- a/examples/skill-fixtures/row-basic/README.md +++ b/examples/skill-fixtures/row-basic/README.md @@ -38,25 +38,44 @@ composes its `Header` row. ## How to run 1. `cd examples/skill-fixtures/row-basic` -2. `mvn test` +2. `mvn test` — the JUnit smoke test; asserts `compose(...)` does not + throw 3. inspect `expected-output/layout-snapshot.json` for the intended region shape -Phase 6 will additionally write `expected-output/output.pdf` and -`expected-output/output.png` on every run. - -## Deferred checks - -The JUnit test currently asserts only that `compose(...)` does not -throw. Three checks are pending the Phase 6 renderer and the Phase 7 -visual-diff tool: - -- layout-snapshot equality against - `expected-output/layout-snapshot.json` -- PDF byte sanity (non-empty, valid header) on - `expected-output/output.pdf` -- preview-image visual diff against a committed - `expected-output/output.png` baseline - -Each deferred check is listed in a comment block inside +The committed render baseline is captured separately from the JUnit +test. A no-arg +[`RowBasicFixtureDocument`](src/main/java/com/demcha/compose/document/fixtures/rowbasic/RowBasicFixtureDocument.java) +exposes the same `compose(DocumentSession)` the test exercises, and +`tools/preview-renderer` drives it to `expected-output/output.pdf` and +`output.png`. Run the loop from the repo root: + +- `node scripts/validate-skills.mjs` — re-render and visual-diff the PNG + against the committed baseline (expects `IDENTICAL`). +- `node scripts/validate-skills.mjs --update-baseline` — (re)capture the + `expected-output/output.{pdf,png}` baseline. + +## Checks + +The JUnit test still asserts only that `compose(...)` does not throw. The +render and visual-diff now run through the `RowBasicFixtureDocument` +adapter and `node scripts/validate-skills.mjs`, not the test: + +- preview-image visual diff against the committed + `expected-output/output.png` — wired. `node scripts/validate-skills.mjs` + re-renders via `tools/preview-renderer` and compares the PNG with + `tools/visual-diff`, expecting `IDENTICAL` (AE == 0). +- rendered-output sanity — wired. The runner asserts the render produced a + non-empty `output.pdf` and `output.png` (CI runs `--render-only`, since + PNG rasterisation is platform-specific). Full PDF byte equality is + intentionally skipped: PDFs carry timestamps, so parity is judged on the + PNG. +- layout-snapshot equality against `expected-output/layout-snapshot.json` + — still not enforced. `layout-snapshot.json` stays illustrative; it + documents intent, not a measured engine run. + +The captured baseline sizes and the `IDENTICAL` result for all five +fixtures are recorded in +[`../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../validation/reports/skill-render-validation-2026-06-03.md). +The same three checks are noted in a comment block inside [`RowBasicFixtureTest`](src/test/java/com/demcha/compose/document/fixtures/rowbasic/RowBasicFixtureTest.java). diff --git a/examples/skill-fixtures/row-basic/expected-output/README.md b/examples/skill-fixtures/row-basic/expected-output/README.md index 437d837..62393dc 100644 --- a/examples/skill-fixtures/row-basic/expected-output/README.md +++ b/examples/skill-fixtures/row-basic/expected-output/README.md @@ -1,30 +1,37 @@ # expected-output for row-basic -This folder is where the Phase 6 render-and-preview tool will write the -rendered artifacts for this fixture. Until that lands, only -`layout-snapshot.json` is present, and it is illustrative — the values -describe the layout shape the fixture intends to produce, not values -measured by a real engine run. +This folder holds the committed render baseline for this fixture. +`output.pdf` and `output.png` are produced by `tools/preview-renderer` +driving the fixture's no-arg `RowBasicFixtureDocument` adapter. +`layout-snapshot.json` is still illustrative — its values describe the +layout shape the fixture intends to produce, not values measured by a +real engine run. ## Files | File | Status | Populated by | |---|---|---| -| `layout-snapshot.json` | present, illustrative | placeholder for Phase 6 | -| `output.pdf` | absent, Phase 6 deferred | preview-renderer tool | -| `output.png` | absent, Phase 6 deferred | preview-renderer tool | +| `layout-snapshot.json` | present, illustrative | hand-authored (documents intent) | +| `output.pdf` | present (committed baseline) | `tools/preview-renderer` via `RowBasicFixtureDocument` | +| `output.png` | present (committed baseline) | `tools/preview-renderer` via `RowBasicFixtureDocument` | -## What lands when +## How the baseline was captured -- **Phase 6** (preview-renderer): every `mvn test` regenerates - `layout-snapshot.json` from the real engine, writes - `output.pdf`, and converts the first page to `output.png`. The - illustrative `notes` field on the snapshot will be removed at that - point. -- **Phase 7** (visual-diff): introduces a committed `output.png` - baseline and a tool that compares a new render against both - `layout-snapshot.json` and that baseline. Diffs are classified per +The render plus visual-diff loop is built (see +[`../../../../scripts/validate-skills.mjs`](../../../../scripts/validate-skills.mjs) +and the run recorded in +[`../../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../../validation/reports/skill-render-validation-2026-06-03.md)): + +- **Render** (`tools/preview-renderer`): `node scripts/validate-skills.mjs + --update-baseline` instantiates the no-arg `RowBasicFixtureDocument`, + calls its `compose(DocumentSession)`, writes `output.pdf`, and converts + the first page to `output.png` here. +- **Visual-diff** (`tools/visual-diff`): `node scripts/validate-skills.mjs` + re-renders and compares the new PNG against this committed `output.png`, + expecting `IDENTICAL` (AE == 0). PDFs carry timestamps, so parity is + judged on the PNG, not the PDF bytes. Diffs are classified per [`../../../../docs/visual-accuracy-contract.md`](../../../../docs/visual-accuracy-contract.md). -Do not edit `layout-snapshot.json` by hand once Phase 6 is wired; it -will be regenerated. Do edit it by hand now — it documents intent. +`layout-snapshot.json` is not part of that loop. It stays hand-authored +and illustrative, so it is safe to edit by hand; the render loop never +regenerates it. diff --git a/examples/skill-fixtures/section-basic/README.md b/examples/skill-fixtures/section-basic/README.md index 12d60f5..bd028eb 100644 --- a/examples/skill-fixtures/section-basic/README.md +++ b/examples/skill-fixtures/section-basic/README.md @@ -37,22 +37,42 @@ panel section in the backgrounds-and-panels skill. ## How to run 1. `cd examples/skill-fixtures/section-basic` -2. `mvn test` +2. `mvn test` — the JUnit smoke test; asserts `compose(...)` does not + throw 3. inspect `expected-output/layout-snapshot.json` for the intended region shape, padding, and background token -Phase 6 will additionally write `expected-output/output.pdf` and -`expected-output/output.png` on every run. +The committed render baseline is captured separately from the JUnit +test. A no-arg +[`SectionBasicFixtureDocument`](src/main/java/com/demcha/compose/document/fixtures/sectionbasic/SectionBasicFixtureDocument.java) +exposes the same `compose(DocumentSession)` the test exercises, and +`tools/preview-renderer` drives it to `expected-output/output.pdf` and +`output.png`. Run the loop from the repo root: -## Deferred checks +- `node scripts/validate-skills.mjs` — re-render and visual-diff the PNG + against the committed baseline (expects `IDENTICAL`). +- `node scripts/validate-skills.mjs --update-baseline` — (re)capture the + `expected-output/output.{pdf,png}` baseline. -The JUnit test currently asserts only that `compose(...)` does not -throw. Three checks are pending the Phase 6 renderer and the Phase 7 -visual-diff tool: +## Checks -- layout-snapshot equality against - `expected-output/layout-snapshot.json` -- PDF byte sanity (non-empty, valid header) on - `expected-output/output.pdf` -- preview-image visual diff against a committed - `expected-output/output.png` baseline +The JUnit test still asserts only that `compose(...)` does not throw. The +render and visual-diff now run through the `SectionBasicFixtureDocument` +adapter and `node scripts/validate-skills.mjs`, not the test: + +- preview-image visual diff against the committed + `expected-output/output.png` — wired. `node scripts/validate-skills.mjs` + re-renders via `tools/preview-renderer` and compares the PNG with + `tools/visual-diff`, expecting `IDENTICAL` (AE == 0). +- rendered-output sanity — wired. The runner asserts the render produced a + non-empty `output.pdf` and `output.png` (CI runs `--render-only`, since + PNG rasterisation is platform-specific). Full PDF byte equality is + intentionally skipped: PDFs carry timestamps, so parity is judged on the + PNG. +- layout-snapshot equality against `expected-output/layout-snapshot.json` + — still not enforced. `layout-snapshot.json` stays illustrative; it + documents intent, not a measured engine run. + +The captured baseline sizes and the `IDENTICAL` result for all five +fixtures are recorded in +[`../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../validation/reports/skill-render-validation-2026-06-03.md). diff --git a/examples/skill-fixtures/section-basic/expected-output/README.md b/examples/skill-fixtures/section-basic/expected-output/README.md index 7f4b938..bc20122 100644 --- a/examples/skill-fixtures/section-basic/expected-output/README.md +++ b/examples/skill-fixtures/section-basic/expected-output/README.md @@ -1,30 +1,37 @@ # expected-output for section-basic -This folder is where the Phase 6 render-and-preview tool will write the -rendered artifacts for this fixture. Until that lands, only -`layout-snapshot.json` is present, and it is illustrative — the values -describe the layout shape the fixture intends to produce, not values -measured by a real engine run. +This folder holds the committed render baseline for this fixture. +`output.pdf` and `output.png` are produced by `tools/preview-renderer` +driving the fixture's no-arg `SectionBasicFixtureDocument` adapter. +`layout-snapshot.json` is still illustrative — its values describe the +layout shape the fixture intends to produce, not values measured by a +real engine run. ## Files | File | Status | Populated by | |---|---|---| -| `layout-snapshot.json` | present, illustrative | placeholder for Phase 6 | -| `output.pdf` | absent, Phase 6 deferred | preview-renderer tool | -| `output.png` | absent, Phase 6 deferred | preview-renderer tool | +| `layout-snapshot.json` | present, illustrative | hand-authored (documents intent) | +| `output.pdf` | present (committed baseline) | `tools/preview-renderer` via `SectionBasicFixtureDocument` | +| `output.png` | present (committed baseline) | `tools/preview-renderer` via `SectionBasicFixtureDocument` | -## What lands when +## How the baseline was captured -- **Phase 6** (preview-renderer): every `mvn test` regenerates - `layout-snapshot.json` from the real engine, writes - `output.pdf`, and converts the first page to `output.png`. The - illustrative `notes` field on the snapshot will be removed at that - point. -- **Phase 7** (visual-diff): introduces a committed `output.png` - baseline and a tool that compares a new render against both - `layout-snapshot.json` and that baseline. Diffs are classified per +The render plus visual-diff loop is built (see +[`../../../../scripts/validate-skills.mjs`](../../../../scripts/validate-skills.mjs) +and the run recorded in +[`../../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../../validation/reports/skill-render-validation-2026-06-03.md)): + +- **Render** (`tools/preview-renderer`): `node scripts/validate-skills.mjs + --update-baseline` instantiates the no-arg `SectionBasicFixtureDocument`, + calls its `compose(DocumentSession)`, writes `output.pdf`, and converts + the first page to `output.png` here. +- **Visual-diff** (`tools/visual-diff`): `node scripts/validate-skills.mjs` + re-renders and compares the new PNG against this committed `output.png`, + expecting `IDENTICAL` (AE == 0). PDFs carry timestamps, so parity is + judged on the PNG, not the PDF bytes. Diffs are classified per [`../../../../docs/visual-accuracy-contract.md`](../../../../docs/visual-accuracy-contract.md). -Do not edit `layout-snapshot.json` by hand once Phase 6 is wired; it -will be regenerated. Do edit it by hand now — it documents intent. +`layout-snapshot.json` is not part of that loop. It stays hand-authored +and illustrative, so it is safe to edit by hand; the render loop never +regenerates it. diff --git a/examples/skill-fixtures/shape-container-card/README.md b/examples/skill-fixtures/shape-container-card/README.md index 58a820e..4df314c 100644 --- a/examples/skill-fixtures/shape-container-card/README.md +++ b/examples/skill-fixtures/shape-container-card/README.md @@ -39,22 +39,42 @@ canvas paint. ## How to run 1. `cd examples/skill-fixtures/shape-container-card` -2. `mvn test` +2. `mvn test` — the JUnit smoke test; asserts `compose(...)` does not + throw 3. inspect `expected-output/layout-snapshot.json` for the intended corner radius and child content -Phase 6 will additionally write `expected-output/output.pdf` and -`expected-output/output.png` on every run. +The committed render baseline is captured separately from the JUnit +test. A no-arg +[`ShapeContainerCardFixtureDocument`](src/main/java/com/demcha/compose/document/fixtures/shapecontainercard/ShapeContainerCardFixtureDocument.java) +exposes the same `compose(DocumentSession)` the test exercises, and +`tools/preview-renderer` drives it to `expected-output/output.pdf` and +`output.png`. Run the loop from the repo root: -## Deferred checks +- `node scripts/validate-skills.mjs` — re-render and visual-diff the PNG + against the committed baseline (expects `IDENTICAL`). +- `node scripts/validate-skills.mjs --update-baseline` — (re)capture the + `expected-output/output.{pdf,png}` baseline. -The JUnit test currently asserts only that `compose(...)` does not -throw. Three checks are pending the Phase 6 renderer and the Phase 7 -visual-diff tool: +## Checks -- layout-snapshot equality against - `expected-output/layout-snapshot.json` -- PDF byte sanity (non-empty, valid header) on - `expected-output/output.pdf` -- preview-image visual diff against a committed - `expected-output/output.png` baseline +The JUnit test still asserts only that `compose(...)` does not throw. The +render and visual-diff now run through the `ShapeContainerCardFixtureDocument` +adapter and `node scripts/validate-skills.mjs`, not the test: + +- preview-image visual diff against the committed + `expected-output/output.png` — wired. `node scripts/validate-skills.mjs` + re-renders via `tools/preview-renderer` and compares the PNG with + `tools/visual-diff`, expecting `IDENTICAL` (AE == 0). +- rendered-output sanity — wired. The runner asserts the render produced a + non-empty `output.pdf` and `output.png` (CI runs `--render-only`, since + PNG rasterisation is platform-specific). Full PDF byte equality is + intentionally skipped: PDFs carry timestamps, so parity is judged on the + PNG. +- layout-snapshot equality against `expected-output/layout-snapshot.json` + — still not enforced. `layout-snapshot.json` stays illustrative; it + documents intent, not a measured engine run. + +The captured baseline sizes and the `IDENTICAL` result for all five +fixtures are recorded in +[`../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../validation/reports/skill-render-validation-2026-06-03.md). diff --git a/examples/skill-fixtures/shape-container-card/expected-output/README.md b/examples/skill-fixtures/shape-container-card/expected-output/README.md index 61dd700..265938a 100644 --- a/examples/skill-fixtures/shape-container-card/expected-output/README.md +++ b/examples/skill-fixtures/shape-container-card/expected-output/README.md @@ -1,30 +1,37 @@ # expected-output for shape-container-card -This folder is where the Phase 6 render-and-preview tool will write the -rendered artifacts for this fixture. Until that lands, only -`layout-snapshot.json` is present, and it is illustrative — the values -describe the layout shape the fixture intends to produce, not values -measured by a real engine run. +This folder holds the committed render baseline for this fixture. +`output.pdf` and `output.png` are produced by `tools/preview-renderer` +driving the fixture's no-arg `ShapeContainerCardFixtureDocument` adapter. +`layout-snapshot.json` is still illustrative — its values describe the +layout shape the fixture intends to produce, not values measured by a +real engine run. ## Files | File | Status | Populated by | |---|---|---| -| `layout-snapshot.json` | present, illustrative | placeholder for Phase 6 | -| `output.pdf` | absent, Phase 6 deferred | preview-renderer tool | -| `output.png` | absent, Phase 6 deferred | preview-renderer tool | +| `layout-snapshot.json` | present, illustrative | hand-authored (documents intent) | +| `output.pdf` | present (committed baseline) | `tools/preview-renderer` via `ShapeContainerCardFixtureDocument` | +| `output.png` | present (committed baseline) | `tools/preview-renderer` via `ShapeContainerCardFixtureDocument` | -## What lands when +## How the baseline was captured -- **Phase 6** (preview-renderer): every `mvn test` regenerates - `layout-snapshot.json` from the real engine, writes - `output.pdf`, and converts the first page to `output.png`. The - illustrative `notes` field on the snapshot will be removed at that - point. -- **Phase 7** (visual-diff): introduces a committed `output.png` - baseline and a tool that compares a new render against both - `layout-snapshot.json` and that baseline. Diffs are classified per +The render plus visual-diff loop is built (see +[`../../../../scripts/validate-skills.mjs`](../../../../scripts/validate-skills.mjs) +and the run recorded in +[`../../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../../validation/reports/skill-render-validation-2026-06-03.md)): + +- **Render** (`tools/preview-renderer`): `node scripts/validate-skills.mjs + --update-baseline` instantiates the no-arg `ShapeContainerCardFixtureDocument`, + calls its `compose(DocumentSession)`, writes `output.pdf`, and converts + the first page to `output.png` here. +- **Visual-diff** (`tools/visual-diff`): `node scripts/validate-skills.mjs` + re-renders and compares the new PNG against this committed `output.png`, + expecting `IDENTICAL` (AE == 0). PDFs carry timestamps, so parity is + judged on the PNG, not the PDF bytes. Diffs are classified per [`../../../../docs/visual-accuracy-contract.md`](../../../../docs/visual-accuracy-contract.md). -Do not edit `layout-snapshot.json` by hand once Phase 6 is wired; it -will be regenerated. Do edit it by hand now — it documents intent. +`layout-snapshot.json` is not part of that loop. It stays hand-authored +and illustrative, so it is safe to edit by hand; the render loop never +regenerates it. diff --git a/examples/skill-fixtures/table-basic/README.md b/examples/skill-fixtures/table-basic/README.md index 1be22ef..941bcca 100644 --- a/examples/skill-fixtures/table-basic/README.md +++ b/examples/skill-fixtures/table-basic/README.md @@ -46,22 +46,42 @@ engine). ## How to run 1. `cd examples/skill-fixtures/table-basic` -2. `mvn test` +2. `mvn test` — the JUnit smoke test; asserts `compose(...)` does not + throw 3. inspect `expected-output/layout-snapshot.json` for the intended columns, header config, and data rows -Phase 6 will additionally write `expected-output/output.pdf` and -`expected-output/output.png` on every run. +The committed render baseline is captured separately from the JUnit +test. A no-arg +[`TableBasicFixtureDocument`](src/main/java/com/demcha/compose/document/fixtures/tablebasic/TableBasicFixtureDocument.java) +exposes the same `compose(DocumentSession)` the test exercises, and +`tools/preview-renderer` drives it to `expected-output/output.pdf` and +`output.png`. Run the loop from the repo root: -## Deferred checks +- `node scripts/validate-skills.mjs` — re-render and visual-diff the PNG + against the committed baseline (expects `IDENTICAL`). +- `node scripts/validate-skills.mjs --update-baseline` — (re)capture the + `expected-output/output.{pdf,png}` baseline. -The JUnit test currently asserts only that `compose(...)` does not -throw. Three checks are pending the Phase 6 renderer and the Phase 7 -visual-diff tool: +## Checks -- layout-snapshot equality against - `expected-output/layout-snapshot.json` -- PDF byte sanity (non-empty, valid header) on - `expected-output/output.pdf` -- preview-image visual diff against a committed - `expected-output/output.png` baseline +The JUnit test still asserts only that `compose(...)` does not throw. The +render and visual-diff now run through the `TableBasicFixtureDocument` +adapter and `node scripts/validate-skills.mjs`, not the test: + +- preview-image visual diff against the committed + `expected-output/output.png` — wired. `node scripts/validate-skills.mjs` + re-renders via `tools/preview-renderer` and compares the PNG with + `tools/visual-diff`, expecting `IDENTICAL` (AE == 0). +- rendered-output sanity — wired. The runner asserts the render produced a + non-empty `output.pdf` and `output.png` (CI runs `--render-only`, since + PNG rasterisation is platform-specific). Full PDF byte equality is + intentionally skipped: PDFs carry timestamps, so parity is judged on the + PNG. +- layout-snapshot equality against `expected-output/layout-snapshot.json` + — still not enforced. `layout-snapshot.json` stays illustrative; it + documents intent, not a measured engine run. + +The captured baseline sizes and the `IDENTICAL` result for all five +fixtures are recorded in +[`../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../validation/reports/skill-render-validation-2026-06-03.md). diff --git a/examples/skill-fixtures/table-basic/expected-output/README.md b/examples/skill-fixtures/table-basic/expected-output/README.md index 04fe5c4..9b26091 100644 --- a/examples/skill-fixtures/table-basic/expected-output/README.md +++ b/examples/skill-fixtures/table-basic/expected-output/README.md @@ -1,30 +1,37 @@ # expected-output for table-basic -This folder is where the Phase 6 render-and-preview tool will write the -rendered artifacts for this fixture. Until that lands, only -`layout-snapshot.json` is present, and it is illustrative — the values -describe the layout shape the fixture intends to produce, not values -measured by a real engine run. +This folder holds the committed render baseline for this fixture. +`output.pdf` and `output.png` are produced by `tools/preview-renderer` +driving the fixture's no-arg `TableBasicFixtureDocument` adapter. +`layout-snapshot.json` is still illustrative — its values describe the +layout shape the fixture intends to produce, not values measured by a +real engine run. ## Files | File | Status | Populated by | |---|---|---| -| `layout-snapshot.json` | present, illustrative | placeholder for Phase 6 | -| `output.pdf` | absent, Phase 6 deferred | preview-renderer tool | -| `output.png` | absent, Phase 6 deferred | preview-renderer tool | +| `layout-snapshot.json` | present, illustrative | hand-authored (documents intent) | +| `output.pdf` | present (committed baseline) | `tools/preview-renderer` via `TableBasicFixtureDocument` | +| `output.png` | present (committed baseline) | `tools/preview-renderer` via `TableBasicFixtureDocument` | -## What lands when +## How the baseline was captured -- **Phase 6** (preview-renderer): every `mvn test` regenerates - `layout-snapshot.json` from the real engine, writes - `output.pdf`, and converts the first page to `output.png`. The - illustrative `notes` field on the snapshot will be removed at that - point. -- **Phase 7** (visual-diff): introduces a committed `output.png` - baseline and a tool that compares a new render against both - `layout-snapshot.json` and that baseline. Diffs are classified per +The render plus visual-diff loop is built (see +[`../../../../scripts/validate-skills.mjs`](../../../../scripts/validate-skills.mjs) +and the run recorded in +[`../../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../../validation/reports/skill-render-validation-2026-06-03.md)): + +- **Render** (`tools/preview-renderer`): `node scripts/validate-skills.mjs + --update-baseline` instantiates the no-arg `TableBasicFixtureDocument`, + calls its `compose(DocumentSession)`, writes `output.pdf`, and converts + the first page to `output.png` here. +- **Visual-diff** (`tools/visual-diff`): `node scripts/validate-skills.mjs` + re-renders and compares the new PNG against this committed `output.png`, + expecting `IDENTICAL` (AE == 0). PDFs carry timestamps, so parity is + judged on the PNG, not the PDF bytes. Diffs are classified per [`../../../../docs/visual-accuracy-contract.md`](../../../../docs/visual-accuracy-contract.md). -Do not edit `layout-snapshot.json` by hand once Phase 6 is wired; it -will be regenerated. Do edit it by hand now — it documents intent. +`layout-snapshot.json` is not part of that loop. It stays hand-authored +and illustrative, so it is safe to edit by hand; the render loop never +regenerates it. From 62c76f1aa9dd93e183dc9754b50d287a5f340e34 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Fri, 5 Jun 2026 10:56:57 +0100 Subject: [PATCH 2/4] skills: fix spacing-and-alignment claim about 1.6 cross-axis align 1.6 row/section primitives expose no cross-axis alignment knob (no row top/center/baseline/bottom, no section left/right/center/stretch). Correct the doc to say so and route centring through shape containers / layer stacks (.center(...) / LayerAlign), plus a note that text has no per-line vertical centring. --- .../graphcompose-1.6/spacing-and-alignment.md | 48 +++++++++++++------ 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/skills/versions/graphcompose-1.6/spacing-and-alignment.md b/skills/versions/graphcompose-1.6/spacing-and-alignment.md index 480e253..29466ee 100644 --- a/skills/versions/graphcompose-1.6/spacing-and-alignment.md +++ b/skills/versions/graphcompose-1.6/spacing-and-alignment.md @@ -55,19 +55,37 @@ token without touching unrelated spacing. ## Alignment grids and how primitives enforce them -Rows align their children horizontally; sections align their -children vertically. Both primitives expose alignment options that -should be the first tool reached for, not bespoke offsets. - -- A row primitive aligns children along a shared baseline (top, - center, baseline-of-text, or bottom). Use the alignment option - rather than inserting blank space to fake vertical balance. -- A section primitive aligns children along a shared edge (left, - right, center, or stretch). Use the section's alignment, not - per-child padding hacks. +Rows arrange their children horizontally (side by side); sections +stack their children vertically. Neither primitive exposes a +cross-axis alignment option in 1.6 — there is no row-level "centre +the children vertically" knob and no section-level "centre the +children horizontally" knob. Reach for the right structural tool +instead of faking balance with blank space. + +- A row places children along the horizontal axis by weight or + width. It does NOT vertically align children of different heights + — `RowBuilder` has no top / center / baseline / bottom option. To + put an icon and a text label on a shared vertical axis, give them + the same height, or wrap the pair in a shape container / layer + stack and centre each layer with `.center(...)` / `LayerAlign` + (see [`layer-stacks-and-overlays`](layer-stacks-and-overlays.md) + and [`shapes-and-containers`](shapes-and-containers.md)). +- A section stacks children vertically at the content width. It has + no left / right / center / stretch child-alignment option; a + child's horizontal position comes from its own width and, for + text, the paragraph's `TextAlign`. For a centred badge or label + inside a box, use a shape container / layer-stack layer with a + `LayerAlign` anchor, not a section option. - When two adjacent regions must share a visual edge (a header - bottom flush with a hero top), align them through the parent - primitive rather than per-region padding fudges. + bottom flush with a hero top), align them by matching their + measured heights / widths and the parent gap, not by per-region + padding fudges. + +Note: 1.6 has no per-line vertical-centring control on text. A +single line dropped into a taller box sits on its font baseline, +not optically centred — centre the whole text layer with a shape +container / layer-stack `.center(...)` rather than nudging it with +blank lines or padding lifts. If the reference clearly uses a column grid (12 columns, 8 columns, etc.), the template should express that grid through the row or @@ -107,7 +125,7 @@ Load this skill any time: - the reference uses an obvious column grid This skill chains with [`layout-primitives`](layout-primitives.md) -(for alignment options on the row and section primitives), +(for choosing the right primitive), [`tables`](tables.md) (for cell padding), and [`themes-and-colors`](themes-and-colors.md) (for the shared naming discipline). @@ -134,8 +152,8 @@ discipline). - [`graphcompose-basics`](graphcompose-basics.md) for the place of layout in the semantic model -- [`layout-primitives`](layout-primitives.md) for the primitive - alignment options +- [`layout-primitives`](layout-primitives.md) for choosing the + right primitive - [`tables`](tables.md) for cell padding and table-internal gaps - [`themes-and-colors`](themes-and-colors.md) for the shared naming convention From 5186dbacc0d2d5550580cf89e148bbcfed98e979 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Fri, 5 Jun 2026 10:56:57 +0100 Subject: [PATCH 3/4] feat(publish-template): infer source class name instead of hardcoding it copyJavaClass renamed from a hardcoded GeneratedCvTemplate, so templates whose generated class has another name were left unrenamed. Derive the source class from projectMeta.render.templateClass / projectMeta.templateClass / the public class declared in the source file, falling back to GeneratedCvTemplate. --- scripts/publish-template.mjs | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/scripts/publish-template.mjs b/scripts/publish-template.mjs index 66faacc..02d2826 100644 --- a/scripts/publish-template.mjs +++ b/scripts/publish-template.mjs @@ -81,6 +81,11 @@ mkdirp(targetSrcDir, targetDataDir, targetAssetsDir, targetIconsDir, targetPrevi const sourceClassFile = path.join(revisionDir, "generated-template.java"); const targetClassFile = path.join(targetSrcDir, `${className}.java`); +const sourceClassName = + simpleClassName(projectMeta.render && projectMeta.render.templateClass) + || simpleClassName(projectMeta.templateClass) + || inferPublicClassName(sourceClassFile) + || "GeneratedCvTemplate"; // The template class carries the agent's editorial Javadoc polish on // top of the renamed source. Subsequent publishes preserve that work // by default — pass --force-template to overwrite (e.g. after a real @@ -89,7 +94,7 @@ if (fs.existsSync(targetClassFile) && !args["force-template"]) { console.log(`[publish-template] ${path.relative(repoRoot, targetClassFile)} already exists; preserving the agent's Javadoc polish. Pass --force-template to overwrite.`); } else { copyJavaClass(sourceClassFile, targetClassFile, { - oldClassName: "GeneratedCvTemplate", + oldClassName: sourceClassName, newClassName: className, }); } @@ -263,6 +268,24 @@ function pascalCase(s) { .join(""); } +function simpleClassName(fqcn) { + if (typeof fqcn !== "string" || fqcn.trim() === "") { + return null; + } + const parts = fqcn.trim().split("."); + return parts[parts.length - 1] || null; +} + +function inferPublicClassName(filePath) { + if (!fs.existsSync(filePath)) { + return null; + } + const content = fs.readFileSync(filePath, "utf8"); + const match = content.match(/\bpublic\s+final\s+class\s+([A-Za-z_$][\w$]*)\b/) + || content.match(/\bpublic\s+class\s+([A-Za-z_$][\w$]*)\b/); + return match ? match[1] : null; +} + function readJsonIfExists(filePath) { if (!fs.existsSync(filePath)) { return null; From 00e96a4eaed1cc7dbf1fb8f01dc19bedb3517684 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Sun, 7 Jun 2026 19:40:08 +0100 Subject: [PATCH 4/4] chore: migrate flow to GraphCompose 1.7.0 Bump io.github.demchaav:graph-compose 1.6.7 -> 1.7.0 across all render-runner / skill-fixture / preview-renderer poms, live example template-project.json, and tooling defaults (init, validate-skills, skill-validation-gate). Add skills/versions/graphcompose-1.7/ -- a port of the 1.6 pack plus the v1.7.0 additive primitives (inline shape runs, polygon geometry, composite inline figures + swappable tick/arrow styles, per-corner roundedRect, verticalAlign(TextVerticalAlign), addTimeline, dashed lines, headingBar, softPanel stroke, JetBrains Mono, availableHeight, nested-stack position() fix). The frozen graphcompose-1.6 snapshot is retained for projects pinned back. Manifest -> skillsVersion 0.3.0, default 1.7.x, supported [1.6.x, 1.7.x]. Refresh prompts (architecture-mapper mapping rows, template-coder idioms), docs, README, CONTRIBUTING, CHANGELOG and the CI job label to the 1.7.0 target, keeping the pre-1.6.7 JitPack boundary as history. Verified: 5 skill-fixture render-only smoke green vs 1.7.0 from Maven Central; revision-manager 31/31; cv-reference + invoice-reference mvn verify green vs 1.7.0. --- .github/workflows/ci.yml | 2 +- AGENTS.md | 7 +- CHANGELOG.md | 33 ++ CONTRIBUTING.md | 4 +- README.md | 8 +- docs/implementation-status.md | 8 +- docs/integration-with-graphcompose.md | 11 +- docs/limitations.md | 4 +- docs/overview.md | 4 +- docs/quickstart.md | 6 +- docs/revision-model.md | 4 +- docs/roadmap.md | 4 +- docs/skill-validation.md | 8 +- docs/versioned-skills.md | 5 + examples/cover-letter-reference/README.md | 4 +- .../template-project.json | 4 +- examples/cv-reference/render-runner/pom.xml | 2 +- examples/cv-reference/template-project.json | 4 +- .../invoice-reference/render-runner/pom.xml | 2 +- .../invoice-reference/template-project.json | 4 +- .../noir-corporate-cv/render-runner/pom.xml | 2 +- .../noir-corporate-cv/template-project.json | 4 +- examples/proposal-reference/README.md | 2 +- .../reference/PLACEHOLDER.md | 2 +- .../proposal-reference/template-project.json | 4 +- examples/skill-fixtures/README.md | 2 +- .../skill-fixtures/layer-stack-badge/pom.xml | 2 +- examples/skill-fixtures/row-basic/pom.xml | 2 +- examples/skill-fixtures/section-basic/pom.xml | 2 +- .../shape-container-card/pom.xml | 2 +- examples/skill-fixtures/table-basic/pom.xml | 2 +- prompts/architecture-mapper-agent.md | 26 +- prompts/orchestrator-agent.md | 2 +- prompts/template-coder-agent.md | 21 +- scripts/lib/skill-validation-gate.mjs | 4 +- scripts/validate-skills.mjs | 4 +- skills/README.md | 15 +- skills/skill-manifest.json | 65 ++-- .../backgrounds-and-panels.md | 290 ++++++++++++++++++ .../graphcompose-1.7/graphcompose-basics.md | 205 +++++++++++++ .../layer-stacks-and-overlays.md | 242 +++++++++++++++ .../graphcompose-1.7/layout-primitives.md | 211 +++++++++++++ .../versions/graphcompose-1.7/pagination.md | 224 ++++++++++++++ .../graphcompose-1.7/revision-discipline.md | 197 ++++++++++++ .../graphcompose-1.7/shapes-and-containers.md | 278 +++++++++++++++++ .../graphcompose-1.7/spacing-and-alignment.md | 204 ++++++++++++ skills/versions/graphcompose-1.7/tables.md | 132 ++++++++ .../graphcompose-1.7/themes-and-colors.md | 125 ++++++++ .../graphcompose-1.7/troubleshooting.md | 246 +++++++++++++++ .../versions/graphcompose-1.7/typography.md | 203 ++++++++++++ .../graphcompose-1.7/visual-regression.md | 205 +++++++++++++ .../visual-to-graphcompose-mapping.md | 120 ++++++++ tools/preview-renderer/README.md | 4 +- tools/preview-renderer/pom.xml | 2 +- .../src/test/resources/sample-revision.json | 2 +- tools/revision-manager/src/commands/init.ts | 4 +- .../test/commands/init.test.ts | 8 +- .../test/projectStore.test.ts | 2 +- tools/skill-validation-cache/README.md | 12 +- validation/api-compatibility-checklist.md | 59 ++-- validation/skill-fix-template.md | 4 +- 61 files changed, 3114 insertions(+), 156 deletions(-) create mode 100644 skills/versions/graphcompose-1.7/backgrounds-and-panels.md create mode 100644 skills/versions/graphcompose-1.7/graphcompose-basics.md create mode 100644 skills/versions/graphcompose-1.7/layer-stacks-and-overlays.md create mode 100644 skills/versions/graphcompose-1.7/layout-primitives.md create mode 100644 skills/versions/graphcompose-1.7/pagination.md create mode 100644 skills/versions/graphcompose-1.7/revision-discipline.md create mode 100644 skills/versions/graphcompose-1.7/shapes-and-containers.md create mode 100644 skills/versions/graphcompose-1.7/spacing-and-alignment.md create mode 100644 skills/versions/graphcompose-1.7/tables.md create mode 100644 skills/versions/graphcompose-1.7/themes-and-colors.md create mode 100644 skills/versions/graphcompose-1.7/troubleshooting.md create mode 100644 skills/versions/graphcompose-1.7/typography.md create mode 100644 skills/versions/graphcompose-1.7/visual-regression.md create mode 100644 skills/versions/graphcompose-1.7/visual-to-graphcompose-mapping.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a29307e..50bfd4e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -103,7 +103,7 @@ jobs: node scripts/render-cv-reference.mjs revision-002 skill-fixtures: - name: skill-fixtures (GraphCompose 1.6.7 via Maven Central) + name: skill-fixtures (GraphCompose 1.7.0 via Maven Central) runs-on: ubuntu-latest strategy: fail-fast: false diff --git a/AGENTS.md b/AGENTS.md index fe550aa..a381839 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ GraphCompose AI Template Flow turns a visual document reference (a PNG screenshot of a CV, invoice, proposal, cover letter, report, brochure, datasheet — ANY single-page or multi-page document GraphCompose primitives can express) into a maintainable Java -template that targets GraphCompose 1.6.7 — with a strict visual +template that targets GraphCompose 1.7.0 — with a strict visual parity contract, a typed data spec the user can edit without touching Java, a per-revision asset bundle (Iconify icons + Google Fonts), a clean and a debug render, and a publish-quality bundle @@ -23,7 +23,7 @@ change creates a new revision; nothing is overwritten. **Document-kind contract.** The four canonical upstream surfaces are `cv`, `coverletter`, `invoice`, `proposal`, with three distinct -generations as of GraphCompose 1.6.7: +generations as of GraphCompose 1.7.0: - `cv` — V2 layered (data → theme → components → widgets → preset orchestrator). @@ -204,7 +204,8 @@ docs/ long-form reference skills/ versioned skill packs skill-manifest.json - versions/graphcompose-1.6/*.md one skill per topic, tied to GraphCompose 1.6.x (verified against 1.6.7) + versions/graphcompose-1.7/*.md active skill pack, tied to GraphCompose 1.7.x (verified against 1.7.0) + versions/graphcompose-1.6/*.md frozen 1.6.x snapshot (retained for projects pinned back to 1.6.x) tools/ asset-resolver/ Iconify + Google Fonts CLI (Node) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c2775e..b1697e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,39 @@ the full visual-baseline pass is the gate to `1.0.0`. ## Unreleased +### GraphCompose 1.7.0 +- **Dependency bumped 1.6.7 → 1.7.0.** All render-runner, skill-fixture, + and preview-renderer poms now resolve + `io.github.demchaav:graph-compose:1.7.0` from Maven Central; every live + example `template-project.json` (`targetGraphComposeVersion`) and the + `graphcompose-flow init` scaffold default move with them. 1.7.0 is + additive over 1.6.x (zero breaking changes), so existing generated + templates compile and render unchanged. +- **New `skills/versions/graphcompose-1.7/` pack.** A port of the 1.6 + pack (the frozen `graphcompose-1.6/` snapshot is retained for projects + pinned back) with the v1.7.0 additive primitives folded into the topic + skills: inline shape runs (rating dots / bullets / arrows / checkboxes + drawn from geometry, no font glyph), polygon `ShapeOutline` geometry, + composite inline figures + swappable tick/arrow styles, per-corner + `roundedRect(...)`, vertical text alignment + (`verticalAlign(TextVerticalAlign)`), semantic timelines + (`addTimeline(...)`), dashed/dotted lines (`LineBuilder.dashed(...)`), + `headingBar(...)`, `softPanel(..., stroke)`, `FontName.JETBRAINS_MONO`, + `DocumentSession.availableHeight()`, and the nested-stack + `position(...)` offset fix. The `spacing-and-alignment` "no per-line + vertical centring" note was corrected for the new `verticalAlign`. +- **Manifest repointed to 1.7.x.** `skill-manifest.json` → + `skillsVersion 0.3.0`, `defaultGraphComposeVersion 1.7.x`, + `supportedGraphComposeVersions [1.6.x, 1.7.x]`, all 14 entries + `verifiedAgainst 1.7.0` (`status: needs-validation` until the render + + visual-diff loop runs on 1.7.0). +- **Prompts + docs refreshed.** The Architecture Mapper gains mapping + rows for the 1.7.0 primitives; the Template Coder lists them as Stable, + surface-agnostic idioms; `AGENTS.md`, the quickstart / overview / + roadmap / limitations / implementation-status / skill-validation / + integration docs, README, and CONTRIBUTING move their "current target" + to 1.7.0 (the pre-1.6.7 JitPack boundary is left intact as history). + ### Live preview - **`live/` mirror.** Every render now also writes a single stable copy of the latest output to `live/current.pdf` (plus `current-debug.pdf`, `current.png`, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 230af9e..5dce660 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,9 +12,9 @@ honest about its limitations. Phases 1 through 7 of the project plan are shipped. See [docs/roadmap.md](docs/roadmap.md) for the per-phase table and [docs/implementation-status.md](docs/implementation-status.md) for the -honest claim-vs-reality matrix. GraphCompose 1.6.7 is reachable for +honest claim-vs-reality matrix. GraphCompose 1.7.0 is reachable for fixture validation through Maven Central as -`io.github.demchaav:graph-compose:1.6.7` (older pins ≤ 1.6.5 still +`io.github.demchaav:graph-compose:1.7.0` (older pins ≤ 1.6.5 still resolve via JitPack as `com.github.DemchaAV:GraphCompose:vX.Y.Z`), and the five committed skill fixtures compile and run against it. The preview renderer now executes compiled templates and writes diff --git a/README.md b/README.md index a1f07aa..504448a 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ setup. **Works for any document kind** GraphCompose primitives can express — CV, cover letter, invoice, proposal, report, brochure, datasheet, single-page brand collateral. The four canonical template surfaces upstream are -first-class targets as of GraphCompose 1.6.7: +first-class targets as of GraphCompose 1.7.0: | Surface | Generation | Shape | |---|---|---| @@ -63,7 +63,7 @@ Source reference: [`examples/cv-reference/`](examples/cv-reference/) → publish | Published template bundle (`mint-editorial-cv`) | Available | | GitHub Actions CI matrix | Green (Node 20 + Java 21 + Maven) | | Full visual baseline orchestration | In progress | -| Skills under `skills/versions/graphcompose-1.6/` | `needs-validation` until baseline pass lands | +| Skills under `skills/versions/graphcompose-1.7/` | `needs-validation` until baseline pass lands | Full claim-vs-reality matrix: [`docs/implementation-status.md`](docs/implementation-status.md). @@ -266,8 +266,8 @@ and a Node visual-diff CLI ([`visual-diff`](tools/visual-diff/)). All three ship with passing test suites and are wired to GitHub Actions CI. -GraphCompose 1.6.7 is reachable for fixture validation through -Maven Central as `io.github.demchaav:graph-compose:1.6.7` +GraphCompose 1.7.0 is reachable for fixture validation through +Maven Central as `io.github.demchaav:graph-compose:1.7.0` (JitPack `com.github.DemchaAV:GraphCompose:vX.Y.Z` still resolves for pre-1.6.7 pins). The five fixture projects under [`examples/skill-fixtures/`](examples/skill-fixtures/) compile and diff --git a/docs/implementation-status.md b/docs/implementation-status.md index efacd20..de55064 100644 --- a/docs/implementation-status.md +++ b/docs/implementation-status.md @@ -12,14 +12,14 @@ The repository is no longer only documentation. The workflow scaffold, revision tooling, preview tooling, visual diff tooling, repository-contract checks, and five GraphCompose skill fixtures all exist on disk. The Java fixture projects compile and run against -GraphCompose 1.6.7 through Maven Central using: +GraphCompose 1.7.0 through Maven Central using: ```text -io.github.demchaav:graph-compose:1.6.7 +io.github.demchaav:graph-compose:1.7.0 ``` Older pins (≤ v1.6.5) continue to resolve via JitPack as -`com.github.DemchaAV:GraphCompose:vX.Y.Z`. GraphCompose 1.6.7 is +`com.github.DemchaAV:GraphCompose:vX.Y.Z`. GraphCompose 1.7.0 is compiled for Java 21, so GraphCompose-backed Maven jobs run on Java 21 in CI. The invoice and CV reference examples both render through local render-runner projects. @@ -39,7 +39,7 @@ visual review loop completes against committed baselines. |---|---|---| | Documentation MVP | README, docs, AGENTS, prompts, contributing guide, limitations, roadmap | REAL | | Agent prompt pack | 10 prompt files under `prompts/` | REAL | -| Versioned skill pack | 14 files under `skills/versions/graphcompose-1.6/` with manifest/frontmatter checks | REAL, still `needs-validation` | +| Versioned skill pack | 14 files under `skills/versions/graphcompose-1.7/` with manifest/frontmatter checks | REAL, still `needs-validation` | | Manual invoice example | Three revisions under `examples/invoice-reference/`, render-runner, committed `output.pdf`/`output.png` | REAL-WITH-CAVEAT: visual baseline absent | | Manual CV example | Two two-page drafts under `examples/cv-reference/`, render-runner, committed `output.pdf`, `output.png`, and `output-page-2.png` for the current draft | REAL-WITH-CAVEAT: visual baseline absent | | Revision statuses | `DRAFT`, `APPROVED`, `REJECTED`, `SUPERSEDED`, `FAILED`, `REVERTED` in `tools/revision-manager/src/types.ts` | REAL | diff --git a/docs/integration-with-graphcompose.md b/docs/integration-with-graphcompose.md index 0afe338..dd35650 100644 --- a/docs/integration-with-graphcompose.md +++ b/docs/integration-with-graphcompose.md @@ -9,11 +9,12 @@ workflow that uses GraphCompose as the target language. GraphCompose itself is maintained at [https://github.com/DemchaAV/GraphCompose](https://github.com/DemchaAV/GraphCompose). The skill packs in this repository currently target GraphCompose -`1.6.x` (the `defaultGraphComposeVersion` in `skills/skill-manifest.json`). -A `1.5.x` skill pack is also planned per the structure in -[versioned-skills.md](versioned-skills.md). When GraphCompose ships a -new minor version, a new skill pack directory is added under -`skills/versions/` rather than mutating the existing one. +`1.7.x` (the `defaultGraphComposeVersion` in `skills/skill-manifest.json`), +with the frozen `1.6.x` pack retained under `skills/versions/` for +projects that pin back. When GraphCompose ships a new minor version, a +new skill pack directory is added under `skills/versions/` rather than +mutating the existing one — the `1.6.x` → `1.7.x` port followed exactly +this rule (see [versioned-skills.md](versioned-skills.md)). ## How this strengthens GraphCompose positioning diff --git a/docs/limitations.md b/docs/limitations.md index 2f77157..612ca2b 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -45,8 +45,8 @@ Three tools ship under [`../tools/`](../tools/) and pass CI: 21 unit tests; functional. - The five fixture projects under [`../examples/skill-fixtures/`](../examples/skill-fixtures/) compile - and run with Maven against GraphCompose 1.6.7 from Maven Central: - `io.github.demchaav:graph-compose:1.6.7`. Pre-1.6.7 pins still + and run with Maven against GraphCompose 1.7.0 from Maven Central: + `io.github.demchaav:graph-compose:1.7.0`. Pre-1.6.7 pins still resolve via JitPack as `com.github.DemchaAV:GraphCompose:vX.Y.Z`. What is intentionally NOT in this repository today: diff --git a/docs/overview.md b/docs/overview.md index 7f5c4ac..54f70bc 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -110,8 +110,8 @@ and a `render` path for compiled GraphCompose templates), and a Node visual-diff CLI. All three have passing test suites and are wired to GitHub Actions CI. -GraphCompose 1.6.7 is reachable through Maven Central as -`io.github.demchaav:graph-compose:1.6.7` (JitPack +GraphCompose 1.7.0 is reachable through Maven Central as +`io.github.demchaav:graph-compose:1.7.0` (JitPack `com.github.DemchaAV:GraphCompose:vX.Y.Z` still resolves for pre-1.6.7 pins), and the five fixture projects under [`examples/skill-fixtures/`](../examples/skill-fixtures/) compile diff --git a/docs/quickstart.md b/docs/quickstart.md index a7994c1..227a4b8 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -39,10 +39,10 @@ npm --version git --version ``` -GraphCompose 1.6.7 is resolved by Maven through Maven Central as: +GraphCompose 1.7.0 is resolved by Maven through Maven Central as: ```text -io.github.demchaav:graph-compose:1.6.7 +io.github.demchaav:graph-compose:1.7.0 ``` Older pins (≤ v1.6.5) continue to resolve through JitPack as @@ -255,7 +255,7 @@ That runner shows how to: - copy the selected revision's `generated-template.java` into Maven generated sources -- compile it against GraphCompose 1.6.7 +- compile it against GraphCompose 1.7.0 - provide sample business data through a spec provider - call `tools/preview-renderer` to write `output.pdf` and `output.png` diff --git a/docs/revision-model.md b/docs/revision-model.md index b82853d..df87ec0 100644 --- a/docs/revision-model.md +++ b/docs/revision-model.md @@ -20,7 +20,7 @@ Example: "projectName": "invoice-reference", "referenceImage": "reference/reference.png", "targetGraphComposeVersion": "1.6.0", - "skillPack": "skills/versions/graphcompose-1.6", + "skillPack": "skills/versions/graphcompose-1.7", "currentApprovedRevisionId": "revision-001", "currentDraftRevisionId": "revision-002", "createdAt": "2026-05-12T16:00:00Z", @@ -50,7 +50,7 @@ Example: "status": "DRAFT", "userRequest": "Make the table darker and move the footer down", "targetGraphComposeVersion": "1.6.0", - "skillPack": "skills/versions/graphcompose-1.6", + "skillPack": "skills/versions/graphcompose-1.7", "changedComponents": [ "LineItemsTable", "Footer" diff --git a/docs/roadmap.md b/docs/roadmap.md index 3cb1649..0a0831c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -5,9 +5,9 @@ and one manual example. Tooling starts at Phase 5. ## Current phase -All seven phases of the project plan are shipped. GraphCompose 1.6.7 +All seven phases of the project plan are shipped. GraphCompose 1.7.0 is reachable for fixture validation through Maven Central as -`io.github.demchaav:graph-compose:1.6.7` (JitPack +`io.github.demchaav:graph-compose:1.7.0` (JitPack `com.github.DemchaAV:GraphCompose:vX.Y.Z` remains the fallback for pre-1.6.7 pins), and the five skill fixtures compile and run against it. `preview-renderer render` can diff --git a/docs/skill-validation.md b/docs/skill-validation.md index 8b8df97..721e899 100644 --- a/docs/skill-validation.md +++ b/docs/skill-validation.md @@ -5,8 +5,8 @@ documents the validation discipline. Phase 4 has shipped the [`validation/`](../validation/) folder (templates, checklists, the baseline report) and the [`examples/skill-fixtures/`](../examples/skill-fixtures/) projects. -The fixture projects now compile and run against GraphCompose 1.6.7 -from Maven Central (`io.github.demchaav:graph-compose:1.6.7`; older +The fixture projects now compile and run against GraphCompose 1.7.0 +from Maven Central (`io.github.demchaav:graph-compose:1.7.0`; older pre-1.6.7 pins remain resolvable via JitPack as `com.github.DemchaAV:GraphCompose:vX.Y.Z`). The remaining validation work is the full render + preview + visual-diff loop that promotes @@ -153,7 +153,7 @@ Phase 4 has shipped: the historical baseline report from before fixture execution. - [`validation/reports/fixture-smoke-2026-05-18.md`](../validation/reports/fixture-smoke-2026-05-18.md) — the first compile/run smoke report against GraphCompose 1.6.0 via - JitPack (historical; the fixtures now resolve 1.6.7 from Maven Central). + JitPack (historical; the fixtures now resolve 1.7.0 from Maven Central). - Five fixture projects under [`examples/skill-fixtures/`](../examples/skill-fixtures/): `row-basic`, `section-basic`, `table-basic`, `layer-stack-badge`, @@ -162,7 +162,7 @@ Phase 4 has shipped: are not part of the Phase 4 scope. The fixture smoke proves the covered DSL calls compile and run against -the real 1.6.7 artifact. As of 2026-06-03 the render + visual-diff loop +the real 1.7.0 artifact. As of 2026-06-03 the render + visual-diff loop is built too: `scripts/validate-skills.mjs` renders each fixture through `tools/preview-renderer` (a no-arg `*FixtureDocument` adapter per fixture) and compares the PNG against a committed diff --git a/docs/versioned-skills.md b/docs/versioned-skills.md index c23ebd5..0109cc7 100644 --- a/docs/versioned-skills.md +++ b/docs/versioned-skills.md @@ -56,6 +56,11 @@ skills/ visual-regression.md revision-discipline.md troubleshooting.md + + graphcompose-1.7/ + (same 14 files — the active pack, ported to 1.7.x and verified + against 1.7.0; graphcompose-1.6/ is retained as the frozen + 1.6.x snapshot) ``` Skills are physically duplicated per supported GraphCompose version diff --git a/examples/cover-letter-reference/README.md b/examples/cover-letter-reference/README.md index 2f799e6..1e6e14c 100644 --- a/examples/cover-letter-reference/README.md +++ b/examples/cover-letter-reference/README.md @@ -15,8 +15,8 @@ kick-off gesture that opens `revision-001`. ## Surface V2 layered (`com.demcha.compose.document.templates.coverletter.v2.*`) -on GraphCompose 1.6.7 — the only surface upstream for cover letters -as of the 1.6.7 release. See the upstream +on GraphCompose 1.7.0 — the only surface upstream for cover letters +as of the 1.7.0 release. See the upstream [v2-layered authoring cheatsheet](https://github.com/DemchaAV/GraphCompose/blob/main/docs/templates/v2-layered/authoring-presets.md) for the canonical reference. diff --git a/examples/cover-letter-reference/template-project.json b/examples/cover-letter-reference/template-project.json index bad01ee..76c2252 100644 --- a/examples/cover-letter-reference/template-project.json +++ b/examples/cover-letter-reference/template-project.json @@ -4,8 +4,8 @@ "tagline": "Scaffold project for the first cover-letter run through the GraphCompose AI Template Flow. Pairs with a CV preset via shared CvIdentity + CvTheme on the V2 layered surface (coverletter.v2).", "referenceImage": "reference/reference.png", "referenceDescription": "reference/PLACEHOLDER.md", - "targetGraphComposeVersion": "1.6.7", - "skillPack": "skills/versions/graphcompose-1.6", + "targetGraphComposeVersion": "1.7.0", + "skillPack": "skills/versions/graphcompose-1.7", "currentApprovedRevisionId": null, "currentDraftRevisionId": null, "createdAt": "2026-06-01T12:30:00.000Z", diff --git a/examples/cv-reference/render-runner/pom.xml b/examples/cv-reference/render-runner/pom.xml index 91b3cc8..279ea3c 100644 --- a/examples/cv-reference/render-runner/pom.xml +++ b/examples/cv-reference/render-runner/pom.xml @@ -12,7 +12,7 @@ 21 21 UTF-8 - 1.6.7 + 1.7.0 revision-002 ${project.build.directory}/generated-sources/revision diff --git a/examples/cv-reference/template-project.json b/examples/cv-reference/template-project.json index 6259c3e..7301594 100644 --- a/examples/cv-reference/template-project.json +++ b/examples/cv-reference/template-project.json @@ -4,8 +4,8 @@ "tagline": "Two-page editorial-style resume for a graphic designer, with a mint accent rule and Iconify-backed contact and social glyphs.", "referenceImage": "reference/reference.png", "referenceDescription": "reference/reference.md", - "targetGraphComposeVersion": "1.6.7", - "skillPack": "skills/versions/graphcompose-1.6", + "targetGraphComposeVersion": "1.7.0", + "skillPack": "skills/versions/graphcompose-1.7", "currentApprovedRevisionId": "revision-009", "currentDraftRevisionId": "revision-008", "previouslyApprovedRevisionId": "revision-008", diff --git a/examples/invoice-reference/render-runner/pom.xml b/examples/invoice-reference/render-runner/pom.xml index 7a51f93..abb6e75 100644 --- a/examples/invoice-reference/render-runner/pom.xml +++ b/examples/invoice-reference/render-runner/pom.xml @@ -12,7 +12,7 @@ 21 21 UTF-8 - 1.6.7 + 1.7.0 revision-003 ${project.build.directory}/generated-sources/revision diff --git a/examples/invoice-reference/template-project.json b/examples/invoice-reference/template-project.json index f42c7f1..cb8e8c9 100644 --- a/examples/invoice-reference/template-project.json +++ b/examples/invoice-reference/template-project.json @@ -2,8 +2,8 @@ "projectName": "invoice-reference", "referenceImage": "reference/reference.png", "referenceDescription": "reference/reference.md", - "targetGraphComposeVersion": "1.6.7", - "skillPack": "skills/versions/graphcompose-1.6", + "targetGraphComposeVersion": "1.7.0", + "skillPack": "skills/versions/graphcompose-1.7", "currentApprovedRevisionId": "revision-003", "currentDraftRevisionId": null, "createdAt": "2026-05-18T12:00:00Z", diff --git a/examples/noir-corporate-cv/render-runner/pom.xml b/examples/noir-corporate-cv/render-runner/pom.xml index 2eef347..3f98cce 100644 --- a/examples/noir-corporate-cv/render-runner/pom.xml +++ b/examples/noir-corporate-cv/render-runner/pom.xml @@ -12,7 +12,7 @@ 21 21 UTF-8 - 1.6.7 + 1.7.0 revision-001 ${project.build.directory}/generated-sources/revision diff --git a/examples/noir-corporate-cv/template-project.json b/examples/noir-corporate-cv/template-project.json index 4f77e14..949aa01 100644 --- a/examples/noir-corporate-cv/template-project.json +++ b/examples/noir-corporate-cv/template-project.json @@ -4,8 +4,8 @@ "tagline": "Single-page corporate-style resume / CV with a dark aubergine sidebar plate, circular CV avatar badge, dark section header bars, rating-dot skills and languages blocks, and Iconify-backed contact and interest glyphs.", "referenceImage": "reference/reference.png", "referenceDescription": "reference/reference.md", - "targetGraphComposeVersion": "1.6.7", - "skillPack": "skills/versions/graphcompose-1.6", + "targetGraphComposeVersion": "1.7.0", + "skillPack": "skills/versions/graphcompose-1.7", "currentApprovedRevisionId": null, "currentDraftRevisionId": "revision-007", "previouslyApprovedRevisionId": null, diff --git a/examples/proposal-reference/README.md b/examples/proposal-reference/README.md index 8721012..3eb3216 100644 --- a/examples/proposal-reference/README.md +++ b/examples/proposal-reference/README.md @@ -15,7 +15,7 @@ kick-off gesture that opens `revision-001`. ## Surface `com.demcha.compose.document.templates.proposal.*` on GraphCompose -1.6.7 — single-preset V2 architecture upstream (`ModernProposal` + +1.7.0 — single-preset V2 architecture upstream (`ModernProposal` + `ProposalSpec`). New presets live in the same package and share `ProposalSpec` as the typed input. diff --git a/examples/proposal-reference/reference/PLACEHOLDER.md b/examples/proposal-reference/reference/PLACEHOLDER.md index d0efafa..769a2cd 100644 --- a/examples/proposal-reference/reference/PLACEHOLDER.md +++ b/examples/proposal-reference/reference/PLACEHOLDER.md @@ -20,7 +20,7 @@ The orchestrator routes that gesture through the 11-agent chain. ## Surface -GraphCompose 1.6.7 ships a single proposal preset upstream: +GraphCompose 1.7.0 ships a single proposal preset upstream: - Package: `com.demcha.compose.document.templates.proposal` - Preset: `ModernProposal` diff --git a/examples/proposal-reference/template-project.json b/examples/proposal-reference/template-project.json index f764045..15c0afa 100644 --- a/examples/proposal-reference/template-project.json +++ b/examples/proposal-reference/template-project.json @@ -4,8 +4,8 @@ "tagline": "Scaffold project for the first proposal run through the GraphCompose AI Template Flow. Targets the V2 proposal surface (single-preset upstream: ModernProposal).", "referenceImage": "reference/reference.png", "referenceDescription": "reference/PLACEHOLDER.md", - "targetGraphComposeVersion": "1.6.7", - "skillPack": "skills/versions/graphcompose-1.6", + "targetGraphComposeVersion": "1.7.0", + "skillPack": "skills/versions/graphcompose-1.7", "currentApprovedRevisionId": null, "currentDraftRevisionId": null, "createdAt": "2026-06-01T12:45:00.000Z", diff --git a/examples/skill-fixtures/README.md b/examples/skill-fixtures/README.md index 8a2ce6a..d7e03c1 100644 --- a/examples/skill-fixtures/README.md +++ b/examples/skill-fixtures/README.md @@ -4,7 +4,7 @@ This folder is the home of the Phase 4 skill validation fixtures. A *skill fixture* is a small, self-contained Maven project that exercises one GraphCompose primitive documented by the -[`skills/versions/graphcompose-1.6/`](../../skills/versions/graphcompose-1.6/) +[`skills/versions/graphcompose-1.7/`](../../skills/versions/graphcompose-1.7/) skill pack. Each fixture proves, at the smallest possible scope, that the primitive the skill documents is real GraphCompose API surface and not fantasy documentation. The fixtures are the on-disk receipts for the diff --git a/examples/skill-fixtures/layer-stack-badge/pom.xml b/examples/skill-fixtures/layer-stack-badge/pom.xml index 3ac70e4..8c9bf58 100644 --- a/examples/skill-fixtures/layer-stack-badge/pom.xml +++ b/examples/skill-fixtures/layer-stack-badge/pom.xml @@ -12,7 +12,7 @@ 21 21 UTF-8 - 1.6.7 + 1.7.0