spolvero 0.4.0__tar.gz → 0.6.0__tar.gz

{spolvero-0.4.0 → spolvero-0.6.0}/.github/instructions/spolvero.instructions.md

@@ -14,3 +14,5 @@ Expected outputs include `manifest.json`, `README.md`, `source/`, `normalized/`,
 
 For unsupported diagrams, still preserve the source and generate preview/reference artifacts with a clear `vector_reference` or `raster_reference` editability declaration.
 
+Round-trip review runs (`spolvero-roundtrip` skill) commit only the layout patch and drift report. Rebuilt packages stay in `.tmp/`; regenerated previews are committed only over already-tracked docs assets, never as new paths. Reviewed `.vsdx` binaries are never committed (headless test fixtures under `tests/fixtures/` are a separate, sanctioned class). `docs/artifact-governance.md` is the governing policy for all round-trip artifact retention.
+

{spolvero-0.4.0 → spolvero-0.6.0}/.github/workflows/ci.yml

@@ -18,11 +18,11 @@ jobs:
         python-version: ["3.11", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Compile
@@ -34,16 +34,33 @@ jobs:
       - name: Assert generated artifacts
         run: uv run python -c "import json, pathlib, zipfile; root=pathlib.Path('.tmp/ci-smoke'); manifest=json.loads((root/'manifest.json').read_text()); assert manifest['schema_version']=='1.0.0'; assert len(manifest['diagrams'])==3; assert (root/'preview/diagram-001.png').read_bytes().startswith(b'\x89PNG\r\n\x1a\n'); assert zipfile.is_zipfile(root/'visio/diagram-001-data-visualizer.xlsx')"
 
+  test-vsdx:
+    # Real-VSDX round-trip tests are skipped in the matrix above (no [vsdx] extra).
+    name: Real-VSDX tests (Python 3.13 on ubuntu-latest)
+    runs-on: ubuntu-latest
+    env:
+      SPOLVERO_TEST_VSDX: "1"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Test with [vsdx] extra
+        run: uv run --extra vsdx pytest -rs
+
   ci-summary:
     name: ci-summary
     runs-on: ubuntu-latest
-    needs: [test]
+    needs: [test, test-vsdx]
     if: always()
     steps:
-      - name: Check test matrix result
+      - name: Check test results
         run: |
-          if [ "${{ needs.test.result }}" != "success" ]; then
-            echo "test result: ${{ needs.test.result }}"
+          echo "test result: ${{ needs.test.result }}"
+          echo "test-vsdx result: ${{ needs.test-vsdx.result }}"
+          if [ "${{ needs.test.result }}" != "success" ] || [ "${{ needs.test-vsdx.result }}" != "success" ]; then
             exit 1
           fi
-          echo "test result: ${{ needs.test.result }}"

{spolvero-0.4.0 → spolvero-0.6.0}/.github/workflows/codeql.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - uses: github/codeql-action/init@v4
         with:

{spolvero-0.4.0 → spolvero-0.6.0}/.github/workflows/dependency-review.yml

@@ -12,9 +12,9 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
-      - uses: actions/dependency-review-action@v4
+      - uses: actions/dependency-review-action@v5
         with:
           fail-on-severity: high
           fail-on-scopes: runtime, development, unknown

{spolvero-0.4.0 → spolvero-0.6.0}/.github/workflows/release.yml

@@ -12,12 +12,21 @@ jobs:
     name: Build sdist + wheel
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - uses: actions/setup-python@v6
         with:
           python-version: "3.13"
 
+      - name: Check tag matches package version
+        run: |
+          version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match pyproject.toml version ${version} (expected v${version})."
+            exit 1
+          fi
+          echo "Tag ${GITHUB_REF_NAME} matches version ${version}."
+
       - name: Install build tooling
         run: python -m pip install --upgrade build twine
 
@@ -57,6 +66,20 @@ jobs:
     permissions:
       contents: write
     steps:
+      - uses: actions/checkout@v7
+        with:
+          sparse-checkout: docs/releases
+
+      - name: Select curated release notes
+        id: notes
+        run: |
+          notes="docs/releases/${GITHUB_REF_NAME#v}.md"
+          if [ -f "$notes" ]; then
+            echo "body_path=$notes" >> "$GITHUB_OUTPUT"
+          else
+            echo "::warning::No $notes; the release body will be auto-generated only."
+          fi
+
       - uses: actions/download-artifact@v8
         with:
           name: dist
@@ -65,5 +88,6 @@ jobs:
       - uses: softprops/action-gh-release@v3
         with:
           files: dist/*
+          body_path: ${{ steps.notes.outputs.body_path }}
           generate_release_notes: true
           draft: false

{spolvero-0.4.0 → spolvero-0.6.0}/.gitignore

@@ -18,3 +18,4 @@ __pycache__/
 /generated/
 /packages/
 .codex/
+layouts/reviewed/

{spolvero-0.4.0 → spolvero-0.6.0}/HANDOFF.md

@@ -8,6 +8,7 @@ Latest durable queue for `spolvero`.
 - The repository now lives at `Declaratus/spolvero`; `main` should remain ready for post-release governance and operations work.
 - CI exposes a single `ci-summary` aggregate check for org ruleset readiness.
 - Latest default-branch checks are green, including `ci-summary`, CodeQL, and Dependency Review.
+- v0.5.0 is the previous tagged release. The package version is 0.6.0 (container stamping, multi-diagram patch matching, and manual annotation preservation; PRs #63–#66). Tagging and publication require separate approval; check for a `v0.6.0` tag before assuming it has shipped. See [docs/releases/0.6.0.md](docs/releases/0.6.0.md).
 - Spolvero is promoted to `tier=internal`; repo-local branch protection is disabled, and default-branch policy is enforced through Declaratus org rulesets.
 - Spolvero is recorded in `Declaratus/governance` property assignments; issue #18 is closed.
 - CODEOWNERS covers release and governance-sensitive paths with the current owner handle until a Declaratus maintainer team exists.
@@ -49,8 +50,10 @@ Residual governance notes:
 
 ## Round-trip & drift engine (spec 01)
 
-The round-trip/drift engine is merged to `main` and released in v0.4.0
-(Tasks 1–14 pure-logic foundation in PR #43, Tasks 15–25 VSDX integration in PR #44).
+The round-trip/drift engine is merged to `main`
+(Tasks 1–14 pure-logic foundation in PR #43, Tasks 15–25 VSDX integration in PR #44)
+and shipped in 0.4.0. Connector-endpoint drift and edge routes (spec 03, PR #61)
+ship in 0.5.0.
 See `docs/specs/01-round-trip-drift-engine.md` for the spec and
 `docs/round-trip-workflow.md` for the end-to-end flow.
 
@@ -59,17 +62,24 @@ New capabilities:
 1. Source-metadata stamping (per-shape Visio Shape Data plus doc-level
    `docProps/custom.xml`) on every `vsdx-template` build; see
    `docs/vsdx-template-contract.md` for the stamp keys.
-2. `spolvero extract-layout` lifts reviewer node positions into a YAML layout
-   patch keyed by `spolvero.source_id`.
-3. `spolvero detect-drift` runs the D1–D4 detectors against the source IR (and,
-   with `--source`, the doc-level source hash).
-4. `spolvero build --layout-patch` regenerates while honouring reviewer layout.
+2. `spolvero extract-layout` lifts reviewer node positions, connector
+   endpoints, and topology container bounds into a YAML layout patch
+   (`patch_schema_version: 3`) keyed by `spolvero.source_id`; `--diagram`
+   defaults to the stamped `spolvero.diagram_id`.
+3. `spolvero detect-drift` runs the D1–D6 detectors against the source IR
+   (D5 connector-endpoint drift landed with spec 03 / DEC-169; D1 containers
+   and the D6 pairing guard with spec 04 / DEC-170).
+4. `spolvero build --layout-patch` regenerates while honouring reviewer
+   layout, including connector endpoint routes and container bounds;
+   `--layout-patch` is repeatable and matched to diagrams by id.
+5. `spolvero extract-layout --annotations-out` / `build --annotations`
+   capture and re-materialize reviewer-added shapes as `ownership: manual`
+   annotations via a committed sidecar (spec 05 / DEC-172).
 
 Follow-ups:
 
-1. The Visio Diagram Handoff Assistant skill (DEC-104) is the next piece.
-2. Connector-endpoint drift detection plus edge-route geometry is the next
-   engine follow-up.
-3. Container/topology shape stamping and multi-diagram patch-to-diagram matching
-   remain unimplemented (see the MVP limitations in
+1. The residual engine scope is tracked in Linear on the Visio Renderer
+   initiative: waypoint/polyline route geometry, annotation styling fidelity,
+   and reviewer-drawn (1-D) annotations. Container membership drift and
+   flowchart-subgraph stamping are out of scope (see the MVP limitations in
    `docs/round-trip-workflow.md`).

spolvero-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Declaratus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{spolvero-0.4.0 → spolvero-0.6.0}/PKG-INFO

@@ -1,9 +1,10 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: spolvero
-Version: 0.4.0
+Version: 0.6.0
 Summary: Package docs-as-code diagrams into Visio-friendly handoff artifacts.
 Author: Spolvero maintainers
 License: MIT
+License-File: LICENSE
 Keywords: data-visualizer,diagram,handoff,mermaid,visio
 Requires-Python: >=3.11
 Provides-Extra: com
@@ -24,12 +25,47 @@ The package treats source diagrams as canonical unless a project deliberately mo
 
 See [docs/using-the-package.md](docs/using-the-package.md) for what to do with the handoff folder once it has been generated.
 
+**Status:** pre-1.0. The manifest and IR schemas are versioned, but the CLI and Python API may still change between minor releases. The `visio-com` engine does not create native COM shapes yet; it delegates to the engines below it.
+
+## Install
+
+Requires Python 3.11 or later.
+
+```bash
+pip install spolvero
+```
+
+The core install is stdlib-only. Each extra unlocks one optional engine or input format and is feature-detected at runtime so it never blocks the default path.
+
+```bash
+pip install 'spolvero[vsdx]'     # vsdx-template engine (cross-platform)
+pip install 'spolvero[topology]' # YAML topology inputs (PyYAML)
+pip install 'spolvero[com]'      # visio-com engine (Windows + Visio Plan 2)
+```
+
+A Mermaid CLI (`mmdc`) on `PATH` is auto-detected for higher-fidelity Mermaid previews. Set `SPOLVERO_DISABLE_MMDC=1` to force the built-in renderer.
+
 ## Quick Start
 
 ```bash
 spolvero build input.md --out ./handoff --target data-visualizer
 ```
 
+For an input with one supported Mermaid flowchart, the output folder looks like this (`<id>` is the diagram id, such as `diagram-001`):
+
+```text
+handoff/
+├── manifest.json                  # everything that was built, plus warnings
+├── README.md                      # auto-generated package overview
+├── source/                        # original input + per-diagram extracted source
+├── normalized/<id>.ir.json        # validated intermediate representation
+├── preview/<id>.svg, <id>.png     # always generated
+├── visio/<id>-data-visualizer.xlsx
+└── qa/<id>-qa.md, <id>-conversion-log.json
+```
+
+The workbook appears only for supported flowcharts and topology inputs; other diagrams are packaged as previews with reference editability. Open `manifest.json` for the summary and `qa/<id>-qa.md` for per-diagram warnings. The [handoff guide](docs/using-the-package.md) walks through each file.
+
 From a checkout without installation:
 
 ```bash
@@ -51,6 +87,7 @@ build_package(Path("input.md"), Path("handoff"), "data-visualizer", title="Revie
 - `src/spolvero/`: neutral Python library and CLI.
 - `src/spolvero/schemas/`: versioned manifest and IR schemas.
 - `skills/codex/spolvero/`: Codex-installable skill bundle generated from canonical docs and wrappers.
+- `skills/codex/spolvero-roundtrip/`: Codex skill bundle for processing a reviewed `.vsdx` (coverage, layout patch, drift report).
 - `adapters/`: Claude Code, GitHub Copilot, and generic agent install notes/instruction files.
 - `tests/`: pytest coverage for extraction, Mermaid parsing, schemas, artifacts, adapters, and CLI smoke builds.
 
@@ -74,19 +111,6 @@ uv run spolvero sanitize-vsdx src/spolvero/templates/minimal_flowchart.vsdx --ou
 
 See [docs/declaratus-migration.md](docs/declaratus-migration.md) for post-import operating guidance.
 
-## Optional Extras
-
-The core install is stdlib-only. Each extra unlocks one optional engine or input format and is feature-detected at runtime so it never blocks the default path.
-
-```bash
-pip install spolvero            # stdlib-only default
-pip install 'spolvero[vsdx]'     # vsdx-template engine (cross-platform)
-pip install 'spolvero[topology]' # YAML topology inputs (PyYAML)
-pip install 'spolvero[com]'      # visio-com engine (Windows + Visio Plan 2)
-```
-
-A Mermaid CLI (`mmdc`) on `PATH` is auto-detected for higher-fidelity Mermaid previews. Set `SPOLVERO_DISABLE_MMDC=1` to force the built-in renderer.
-
 ## Targets and Editability
 
 | Target | Engine | Flowchart editability | Notes |
@@ -100,6 +124,33 @@ The manifest always records both `requested_engine` and `actual_engine` so engin
 
 The VSDX template stamp contract is documented in [docs/vsdx-template-contract.md](docs/vsdx-template-contract.md). The bundled template is intentionally minimal; richer templates can provide preferred flowchart, topology, and container stamp names while remaining synthetic and organization-agnostic.
 
+## Round-trip Review
+
+When a `vsdx-template` file comes back from review in Visio, Spolvero keeps the reviewer's layout without editing your source. Every generated shape is stamped with its source id, so the reviewed file can be read back. Requires the `[vsdx]` extra.
+
+```bash
+# Capture reviewer positions, connector routes, and container bounds as a layout patch.
+# --annotations-out also keeps shapes the reviewer added (callouts, notes) as a sidecar.
+spolvero extract-layout reviewed.vsdx --out diagram-001.layout.yml \
+    --annotations-out diagram-001.annotations.yml
+
+# Check what changed against the source: deleted or relabelled shapes,
+# re-pointed connectors, stale source, or a file paired with the wrong diagram.
+spolvero detect-drift handoff/normalized/diagram-001.ir.json reviewed.vsdx \
+    --source input.md --report drift.md
+```
+
+`detect-drift` exits 1 on high-severity drift. Stop there and review `drift.md` before rebuilding; only continue once the drift is understood or accepted.
+
+```bash
+# Rebuild with the reviewer's layout and annotations. Both flags are repeatable
+# and matched to diagrams by id in multi-diagram packages.
+spolvero build input.md --out handoff --target vsdx-template \
+    --layout-patch diagram-001.layout.yml --annotations diagram-001.annotations.yml
+```
+
+Routes keep endpoints, not waypoints, and annotations keep geometry and text only. See [docs/round-trip-workflow.md](docs/round-trip-workflow.md) for the full workflow and limits, and the `spolvero-roundtrip` agent skill for a scripted review run.
+
 ## Inputs
 
 - Mermaid flowchart (`.mmd`, fenced ` ```mermaid ` in Markdown) — primary input; full IR + workbook.
@@ -109,3 +160,9 @@ The VSDX template stamp contract is documented in [docs/vsdx-template-contract.m
 ## The name
 
 Spolvero (Italian, *spol-VEH-roh*) is the Renaissance pouncing technique: an artist pricks holes along the lines of a finished drawing, then dusts pigment through them to transfer the design onto a wall or panel. The pricked cartoon is a deliberate intermediate — made for transfer, distinct from the original. This tool works the same way: it produces a transfer-ready rendering of a source diagram for the Visio surface, while the source stays canonical.
+
+## Security and License
+
+Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
+
+Spolvero is released under the [MIT License](LICENSE). The bundled `minimal_flowchart.vsdx` template is redistributed under the BSD 3-Clause License; see [src/spolvero/templates/LICENSE.txt](src/spolvero/templates/LICENSE.txt).

{spolvero-0.4.0 → spolvero-0.6.0}/README.md

@@ -6,12 +6,47 @@ The package treats source diagrams as canonical unless a project deliberately mo
 
 See [docs/using-the-package.md](docs/using-the-package.md) for what to do with the handoff folder once it has been generated.
 
+**Status:** pre-1.0. The manifest and IR schemas are versioned, but the CLI and Python API may still change between minor releases. The `visio-com` engine does not create native COM shapes yet; it delegates to the engines below it.
+
+## Install
+
+Requires Python 3.11 or later.
+
+```bash
+pip install spolvero
+```
+
+The core install is stdlib-only. Each extra unlocks one optional engine or input format and is feature-detected at runtime so it never blocks the default path.
+
+```bash
+pip install 'spolvero[vsdx]'     # vsdx-template engine (cross-platform)
+pip install 'spolvero[topology]' # YAML topology inputs (PyYAML)
+pip install 'spolvero[com]'      # visio-com engine (Windows + Visio Plan 2)
+```
+
+A Mermaid CLI (`mmdc`) on `PATH` is auto-detected for higher-fidelity Mermaid previews. Set `SPOLVERO_DISABLE_MMDC=1` to force the built-in renderer.
+
 ## Quick Start
 
 ```bash
 spolvero build input.md --out ./handoff --target data-visualizer
 ```
 
+For an input with one supported Mermaid flowchart, the output folder looks like this (`<id>` is the diagram id, such as `diagram-001`):
+
+```text
+handoff/
+├── manifest.json                  # everything that was built, plus warnings
+├── README.md                      # auto-generated package overview
+├── source/                        # original input + per-diagram extracted source
+├── normalized/<id>.ir.json        # validated intermediate representation
+├── preview/<id>.svg, <id>.png     # always generated
+├── visio/<id>-data-visualizer.xlsx
+└── qa/<id>-qa.md, <id>-conversion-log.json
+```
+
+The workbook appears only for supported flowcharts and topology inputs; other diagrams are packaged as previews with reference editability. Open `manifest.json` for the summary and `qa/<id>-qa.md` for per-diagram warnings. The [handoff guide](docs/using-the-package.md) walks through each file.
+
 From a checkout without installation:
 
 ```bash
@@ -33,6 +68,7 @@ build_package(Path("input.md"), Path("handoff"), "data-visualizer", title="Revie
 - `src/spolvero/`: neutral Python library and CLI.
 - `src/spolvero/schemas/`: versioned manifest and IR schemas.
 - `skills/codex/spolvero/`: Codex-installable skill bundle generated from canonical docs and wrappers.
+- `skills/codex/spolvero-roundtrip/`: Codex skill bundle for processing a reviewed `.vsdx` (coverage, layout patch, drift report).
 - `adapters/`: Claude Code, GitHub Copilot, and generic agent install notes/instruction files.
 - `tests/`: pytest coverage for extraction, Mermaid parsing, schemas, artifacts, adapters, and CLI smoke builds.
 
@@ -56,19 +92,6 @@ uv run spolvero sanitize-vsdx src/spolvero/templates/minimal_flowchart.vsdx --ou
 
 See [docs/declaratus-migration.md](docs/declaratus-migration.md) for post-import operating guidance.
 
-## Optional Extras
-
-The core install is stdlib-only. Each extra unlocks one optional engine or input format and is feature-detected at runtime so it never blocks the default path.
-
-```bash
-pip install spolvero            # stdlib-only default
-pip install 'spolvero[vsdx]'     # vsdx-template engine (cross-platform)
-pip install 'spolvero[topology]' # YAML topology inputs (PyYAML)
-pip install 'spolvero[com]'      # visio-com engine (Windows + Visio Plan 2)
-```
-
-A Mermaid CLI (`mmdc`) on `PATH` is auto-detected for higher-fidelity Mermaid previews. Set `SPOLVERO_DISABLE_MMDC=1` to force the built-in renderer.
-
 ## Targets and Editability
 
 | Target | Engine | Flowchart editability | Notes |
@@ -82,6 +105,33 @@ The manifest always records both `requested_engine` and `actual_engine` so engin
 
 The VSDX template stamp contract is documented in [docs/vsdx-template-contract.md](docs/vsdx-template-contract.md). The bundled template is intentionally minimal; richer templates can provide preferred flowchart, topology, and container stamp names while remaining synthetic and organization-agnostic.
 
+## Round-trip Review
+
+When a `vsdx-template` file comes back from review in Visio, Spolvero keeps the reviewer's layout without editing your source. Every generated shape is stamped with its source id, so the reviewed file can be read back. Requires the `[vsdx]` extra.
+
+```bash
+# Capture reviewer positions, connector routes, and container bounds as a layout patch.
+# --annotations-out also keeps shapes the reviewer added (callouts, notes) as a sidecar.
+spolvero extract-layout reviewed.vsdx --out diagram-001.layout.yml \
+    --annotations-out diagram-001.annotations.yml
+
+# Check what changed against the source: deleted or relabelled shapes,
+# re-pointed connectors, stale source, or a file paired with the wrong diagram.
+spolvero detect-drift handoff/normalized/diagram-001.ir.json reviewed.vsdx \
+    --source input.md --report drift.md
+```
+
+`detect-drift` exits 1 on high-severity drift. Stop there and review `drift.md` before rebuilding; only continue once the drift is understood or accepted.
+
+```bash
+# Rebuild with the reviewer's layout and annotations. Both flags are repeatable
+# and matched to diagrams by id in multi-diagram packages.
+spolvero build input.md --out handoff --target vsdx-template \
+    --layout-patch diagram-001.layout.yml --annotations diagram-001.annotations.yml
+```
+
+Routes keep endpoints, not waypoints, and annotations keep geometry and text only. See [docs/round-trip-workflow.md](docs/round-trip-workflow.md) for the full workflow and limits, and the `spolvero-roundtrip` agent skill for a scripted review run.
+
 ## Inputs
 
 - Mermaid flowchart (`.mmd`, fenced ` ```mermaid ` in Markdown) — primary input; full IR + workbook.
@@ -91,3 +141,9 @@ The VSDX template stamp contract is documented in [docs/vsdx-template-contract.m
 ## The name
 
 Spolvero (Italian, *spol-VEH-roh*) is the Renaissance pouncing technique: an artist pricks holes along the lines of a finished drawing, then dusts pigment through them to transfer the design onto a wall or panel. The pricked cartoon is a deliberate intermediate — made for transfer, distinct from the original. This tool works the same way: it produces a transfer-ready rendering of a source diagram for the Visio surface, while the source stays canonical.
+
+## Security and License
+
+Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
+
+Spolvero is released under the [MIT License](LICENSE). The bundled `minimal_flowchart.vsdx` template is redistributed under the BSD 3-Clause License; see [src/spolvero/templates/LICENSE.txt](src/spolvero/templates/LICENSE.txt).

spolvero-0.6.0/adapters/claude/.claude/skills/spolvero-roundtrip/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: spolvero-roundtrip
+description: Process a reviewed VSDX back into source control — verify source-metadata coverage, extract a layout patch, detect drift against the source IR, and produce a validation report before preparing a layout-patch PR. Use for reviewed VSDX, layout patch, drift, or validation report requests; building new handoff packages is the spolvero skill.
+---
+
+# Spolvero Roundtrip
+
+Return leg only: a reviewed `.vsdx` comes back; the outcome is a layout patch
+plus reports, never an automatic edit to canonical source.
+
+Run the hardened script from the skill bundle
+(`skills/codex/spolvero-roundtrip/scripts/roundtrip_review.py` in the spolvero
+repo):
+
+```bash
+python scripts/roundtrip_review.py run \
+    --vsdx reviewed.vsdx --ir diagram-001.ir.json --source sample.md \
+    --out-dir .tmp/review
+```
+
+For source checkouts:
+
+```bash
+uv run --extra vsdx python skills/codex/spolvero-roundtrip/scripts/roundtrip_review.py run \
+    --vsdx reviewed.vsdx --ir handoff/normalized/diagram-001.ir.json \
+    --source sample.md --out-dir .tmp/review
+```
+
+Core rules:
+
+- Engine work goes through the committed script or named `spolvero`
+  subcommands only. Never run ad-hoc Python against a `.vsdx`.
+- Exit 0: clean or medium findings — proceed to PR preparation per the
+  bundle's `references/pr-preparation.md`.
+- Exit 1: high-severity drift (D1 deleted shape, connector, or container /
+  D4 revision mismatch / D5 re-pointed endpoint / D6 wrong diagram) — HALT
+  before PR preparation; show `validation-report.md` and let a human decide.
+- Shapes the reviewer added in Visio are medium (D2) findings and are dropped
+  on rebuild. Keep them only if the user asks: run
+  `spolvero extract-layout reviewed.vsdx --out <diagram>.layout.yml --annotations-out <diagram>.annotations.yml`
+  and commit the sidecar next to the patch (see the bundle's
+  `references/coverage-and-drift.md`).
+- Exit 2: input/environment error or failed/incomplete rebuild. HALT before
+  PR preparation. Rebuild failures retain a HALT validation report; the "not
+  a round-trip candidate" stop retains `coverage.json` and `drift.*` as evidence.
+- If the `.vsdx` came from outside the repo, run `spolvero inspect-vsdx`
+  (read-only) first and surface sensitive-pattern findings.
+- Never merge, never push to a protected branch, never commit a reviewed
+  `.vsdx` binary. No COM automation.
+
+The wrapper requires a non-empty IR id; explicit `--diagram` must match it.
+Rebuild patch warnings (`patch_unmatched`, `patch_diagram_mismatch`,
+`patch_stale`) halt PR preparation with exit 2 and a HALT validation report.
+Failed rebuilds also halt; retained previews are not validated.
+
+Requires the `[vsdx]` extra: `pip install 'spolvero[vsdx]'`.

{spolvero-0.4.0 → spolvero-0.6.0}/adapters/copilot/.github/instructions/spolvero.instructions.md

@@ -14,3 +14,5 @@ Expected outputs include `manifest.json`, `README.md`, `source/`, `normalized/`,
 
 For unsupported diagrams, still preserve the source and generate preview/reference artifacts with a clear `vector_reference` or `raster_reference` editability declaration.
 
+Round-trip review runs (`spolvero-roundtrip` skill) commit only the layout patch and drift report. Rebuilt packages stay in `.tmp/`; regenerated previews are committed only over already-tracked docs assets, never as new paths. Reviewed `.vsdx` binaries are never committed.
+

{spolvero-0.4.0 → spolvero-0.6.0}/docs/agents/recipes.md

@@ -19,6 +19,19 @@ set SPOLVERO_TEST_COM=1
 uv run pytest -q
 ```
 
+## Live Visio acceptance checks
+
+`tests/desktop` opens generated files in an invisible Visio instance, moves
+connected nodes, saves, reopens and rebuilds. Hosted CI cannot run it (no
+licensed Visio), so a maintainer runs it on a licensed Windows machine:
+
+```bash
+SPOLVERO_TEST_VSDX=1 SPOLVERO_TEST_VISIO_DESKTOP=1 uv run --extra vsdx --extra com pytest -m visio_desktop -rsx
+```
+
+Report which tests passed, failed, xfailed or were skipped. Never run these on
+a self-hosted runner that executes public pull-request code.
+
 ## Smoke build a sample package
 
 ```bash