spolvero 0.5.0__tar.gz → 0.6.0__tar.gz

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

@@ -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.5.0 → spolvero-0.6.0}/.github/workflows/release.yml

@@ -18,6 +18,15 @@ jobs:
         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.5.0 → spolvero-0.6.0}/HANDOFF.md

@@ -8,7 +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.4.0 is tagged and published to PyPI. Connector-endpoint drift and edge routes are merged (PR #61); the 0.5.0 version bump is staged, and the `v0.5.0` tag/publish should follow once the bump is merged.
+- 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.
@@ -62,19 +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 and connector
-   endpoints into a YAML layout patch (`patch_schema_version: 2`) keyed by
-   `spolvero.source_id`.
-3. `spolvero detect-drift` runs the D1–D5 detectors against the source IR
-   (D5 connector-endpoint drift landed with spec 03 / DEC-169).
+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.
+   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. The residual engine scope is tracked in Linear on the Visio Renderer
-   initiative: waypoint/polyline route geometry, container/topology shape
-   stamping and multi-diagram patch-to-diagram matching, manual annotations,
-   and a consumer CI recipe (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.5.0 → spolvero-0.6.0}/PKG-INFO

@@ -1,9 +1,10 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: spolvero
-Version: 0.5.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.5.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.5.0 → spolvero-0.6.0}/adapters/claude/.claude/skills/spolvero-roundtrip/SKILL.md

@@ -32,15 +32,25 @@ Core rules:
   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 / D4 revision mismatch) —
-  HALT before PR preparation; show `validation-report.md` and let a human
-  decide.
-- Exit 2: usage/environment error. Usage and environment stops leave nothing
-  valid; the "not a round-trip candidate" stop (no `spolvero.*` stamps) leaves
-  `coverage.json` and `drift.*` as evidence of the rejection.
+- 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.5.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

{spolvero-0.5.0 → spolvero-0.6.0}/docs/artifact-governance.md

@@ -53,6 +53,10 @@ tracked in git as long as the diagram exists.
   patch to work around a stale `source_revision` — re-extract instead.
 - Lives alongside the diagram it patches, not in a separate patches
   directory or branch.
+- Annotation sidecars (`layouts/<diagram>.annotations.yml`, spec 05) follow
+  the same rules: committed text, keyed by `manual-NNN`, tracked alongside the
+  diagram. They are reviewer-owned rather than source-owned, so unlike a patch
+  they are not pinned to a `source_revision` and survive source changes.
 
 ## Drift reports
 
@@ -131,8 +135,9 @@ exception to "no committed binaries," and it stays singular by default.
 ## Test fixtures
 
 Checked-in adversarial `.vsdx` fixtures under `tests/fixtures/` are
-sanctioned — `reviewed-simple.vsdx` has been tracked since spec 01, and
-spec 03 adds `reviewed-connectors.vsdx`. They are not reviewer output and
+sanctioned — `reviewed-simple.vsdx` has been tracked since spec 01, spec 03
+adds `reviewed-connectors.vsdx`, and spec 04 adds `reviewed-topology.vsdx`.
+They are not reviewer output and
 the "reviewed `.vsdx` binaries are never committed" rule does not apply to
 them: they are generated headlessly from tracked sources by
 `tests/_review_toolkit.py` (spec 01 §11's stand-in for a Visio session) and

{spolvero-0.5.0 → spolvero-0.6.0}/docs/consumer-ci-recipe.md

@@ -11,13 +11,17 @@ D1–D4 semantics, and `docs/specs/03-connector-endpoint-drift.md` §7 for D5.
 `spolvero detect-drift` exits non-zero when any **high-severity** finding is
 present:
 
-- **D1** — source-owned shape or connector deleted from the reviewed VSDX.
+- **D1** — source-owned shape, connector, or container deleted from the
+  reviewed VSDX.
 - **D4** — doc-level source-hash no longer matches the `--source` file.
 - **D5** (`endpoint_repointed`) — a connector endpoint re-pointed at a
   different source-owned node.
+- **D6** (`diagram_mismatch`) — the reviewed VSDX was generated as a
+  different diagram than the paired IR (short-circuits all other detectors).
 
-Medium findings (**D2** invalid/missing metadata, **D3** label changed,
-**D5** `endpoint_dangling`) are reported but exit 0 — they're
+Medium findings (**D2** invalid/missing metadata, **D3** label changed on a
+node, connector, or container, **D5** `endpoint_dangling`) are reported but
+exit 0 — they're
 recommendations for a human reviewer, not blockers. That non-zero-on-high exit is the CI gate: wire it into a required
 check and a round-trip review PR cannot merge with undetected shape deletions
 or a stale source revision. Exit codes are enumerated in §4; note that runtime

{spolvero-0.5.0 → spolvero-0.6.0}/docs/current-state.md

@@ -1,17 +1,17 @@
 # Current State
 
-Snapshot of the `spolvero` package after the round-trip/drift engine merge and the 0.4.0 version bump.
+Snapshot for 0.6.0: container stamping, multi-diagram patches, and manual annotation preservation. See [releases/0.6.0.md](releases/0.6.0.md).
 
 ## Version
 
-- Package: `spolvero` 0.4.0 (version bump merged in PR #49; the `v0.4.0` tag and PyPI publish are pending)
+- Package: `spolvero` 0.6.0 (publication is recorded by the `v0.6.0` tag and the PyPI release)
 - Schema version: `1.0.0` (manifest, IR, topology IR)
-- Local validation on this Windows / Python 3.14 host: 108 passed, 16 skipped. Hosted CI runs Linux/Windows on Python 3.11 and 3.13; skip counts vary by optional tools and extras.
+- Hosted CI runs Linux/Windows on Python 3.11 and 3.13. Release validation must also install `[vsdx]` and enable `SPOLVERO_TEST_VSDX=1`; skip counts vary by optional tools.
 
 ## Governance / Operations
 
 - Repository: `Declaratus/spolvero`
-- Release baseline: `v0.3.0`; the 0.4.0 version bump is merged and awaiting the `v0.4.0` tag and PyPI publish.
+- Previous release: `v0.5.0`. 0.6.0 ships by following the [release process](releases/0.6.0.md#release-process), which requires explicit publication approval.
 - Current governance track: post-import operations and follow-up security hardening.
 - Custom properties: `tier=internal`, `data-classification=internal`, `lifecycle-stage=active`; owner assignment is managed in the governance source of truth.
 - CI runs the Linux/Windows Python 3.11/3.13 matrix and exposes `ci-summary` as the aggregate check for Declaratus org ruleset readiness.
@@ -108,9 +108,10 @@ Slashes from parallelogram `[/.../]` are stripped from the label.
 ### Round-trip layout and drift tooling
 
 - Every `vsdx-template` build stamps source metadata: per-shape `spolvero.*` Visio Shape Data keys plus doc-level `docProps/custom.xml` entries including the source hash, per [vsdx-template-contract.md](vsdx-template-contract.md).
-- `spolvero extract-layout` lifts reviewer node positions and connector begin/end endpoints from a reviewed `.vsdx` into a YAML layout patch (`patch_schema_version: 2`) keyed by `spolvero.source_id`. Requires the `[vsdx]` extra.
-- `spolvero detect-drift` runs the D1–D5 detectors against the source IR and compares the doc-level source hash against `--source`; it exits non-zero on high-severity findings (D1 deleted shape or connector, D4 source-hash mismatch, D5 re-pointed connector endpoint). Requires the `[vsdx]` extra.
-- `spolvero build --layout-patch` regenerates a package while honouring reviewer positions; patched node x/y and connector endpoints apply to the VSDX and the built-in preview. v1 (node-only) patches still load and apply.
+- `spolvero extract-layout` lifts reviewer node positions, connector begin/end endpoints, and topology container bounds from a reviewed `.vsdx` into a YAML layout patch (`patch_schema_version: 3`) keyed by `spolvero.source_id`. `--diagram` is optional and defaults to the stamped `spolvero.diagram_id`. Requires the `[vsdx]` extra.
+- `spolvero detect-drift` runs the D1–D6 detectors against the source IR and compares the doc-level source hash against `--source`; it exits non-zero on high-severity findings (D1 deleted shape, connector, or container; D4 source-hash mismatch; D5 re-pointed connector endpoint; D6 wrong IR/vsdx pairing). Requires the `[vsdx]` extra.
+- `spolvero build --layout-patch` regenerates a package while honouring reviewer positions; patched node x/y, connector endpoints, and container bounds apply to the VSDX and the built-in preview. `--layout-patch` is repeatable and matched to diagrams by id. v1/v2 patches still load and apply.
+- `spolvero extract-layout --annotations-out` adopts reviewer-added unstamped 2-D shapes into a YAML annotations sidecar (`annotations_schema_version: 1`, keyed by `manual-NNN`); `spolvero build --annotations` re-materializes them as `ownership: manual` / `role: annotation` shapes on the vsdx-template surface (spec 05). Geometry and text are preserved; styling is not.
 - See [round-trip-workflow.md](round-trip-workflow.md) for the end-to-end flow and MVP limitations.
 
 ### Governance and repository hygiene tooling
@@ -127,7 +128,7 @@ Slashes from parallelogram `[/.../]` are stripped from the label.
 | Engines | TODO: higher-fidelity synthetic templates | The engine now documents preferred flowchart/topology/container stamp names and warns on degradation, but the bundled template remains intentionally minimal. |
 | Engines | TODO: `visio-com` native body | The Windows-only path currently delegates to downstream engines and preserves delegated editability. A fully COM-driven shape/connector pass is a future iteration and should be the only path that emits `native`. |
 | QA / safety | TODO: external corpus automation | Read-only inspection and opt-in XML sanitization are implemented. External corpus manifests, license approvals, and media/OCR automation remain outside tracked source until explicitly approved. |
-| Round-trip | Residual engine scope | Waypoint/polyline route geometry, container/topology shape stamping, multi-diagram patch-to-diagram matching, and manual annotations are deferred (see the MVP limitations in [round-trip-workflow.md](round-trip-workflow.md)); tracked in Linear on the Visio Renderer initiative. |
+| Round-trip | Residual engine scope | Waypoint/polyline route geometry, annotation styling fidelity, and reviewer-drawn connectors are deferred; container membership drift and flowchart-subgraph stamping are out of scope (see the MVP limitations in [round-trip-workflow.md](round-trip-workflow.md)); tracked in Linear on the Visio Renderer initiative. |
 | Workbook metadata | Mermaid metadata columns | Mermaid carries no `Phase`, `System`, `Owner`, or `Criticality` metadata; topology nodes can populate them via `metadata`. |
 
 ## Roadmap
@@ -147,12 +148,16 @@ Major engineering items now landed:
 
 9. ✅ Connector-endpoint drift and edge-route geometry (spec 03, DEC-169): D5 detector with glue read-through, layout patch v2 with edge routes, and edge overrides on both rebuild surfaces.
 
+10. ✅ Container stamping and multi-diagram patch matching (spec 04, DEC-170): topology containers stamped with `spolvero.role`, patch v3 with a containers section, D1 `container_deleted` + D3 container relabels, the `spolvero.diagram_id` doc stamp with the D6 pairing guard, and repeatable diagram-matched `--layout-patch`. Also removed the false D2-per-container finding on topology round-trips.
+
+11. ✅ Manual-annotation ownership and preservation (spec 05, DEC-172): `ownership: manual` activated via a committed annotations sidecar — `extract-layout --annotations-out` adopts reviewer-added 2-D shapes, `build --annotations` re-materializes them, and extraction routes them out of the source-owned drift maps. D2's unstamped-shape recommendation now names the adoption flag.
+
 Next-up TODO areas:
 
 - Hand-rolled `.vsdx` body in the visio-com engine (true native shapes/connectors when Visio is reachable).
 - Higher-fidelity synthetic templates for flowchart/topology stamps beyond the bundled minimal fixture.
 - External corpus harnesses and media/OCR review workflows as post-release security/QA work.
-- Residual round-trip scope (waypoint/polyline routes, container/topology stamping, multi-diagram patch matching, manual annotations, consumer CI recipe), tracked in Linear on the Visio Renderer initiative.
+- Residual round-trip scope (waypoint/polyline routes; annotation styling fidelity and reviewer-drawn connectors), tracked in Linear on the Visio Renderer initiative.
 
 ## References
 

{spolvero-0.5.0 → spolvero-0.6.0}/docs/declaratus-migration.md

@@ -10,7 +10,7 @@ git, and keep Visio/Office artifacts reviewable.
 ## Operating Baseline
 
 - Repository: `Declaratus/spolvero`
-- Package version: `0.3.0`
+- Import baseline: `0.3.0` (historical); see [current-state.md](current-state.md) for the current release candidate.
 - Schema version: `1.0.0`
 - Custom properties: `tier=internal`, `data-classification=internal`, `lifecycle-stage=active`
 - Default-branch policy: inherited from Declaratus org rulesets, especially `tier-internal`
@@ -95,10 +95,8 @@ Future changes to organization-wide policy, repository classification, rulesets,
 controls belong in `Declaratus/governance`. Spolvero-local docs should describe how inherited policy affects
 this package without duplicating it as repo-local policy.
 
-## Open Follow-Ups
+## Completed Governance Follow-Ups
 
-- #30: Add PyPI environment protection for releases.
-- #31: Evaluate Python dependency audit workflow.
-- #32: Enable Code Security and add scanning gates.
-
-Keep the v0.4 VSDX template expansion and future COM-native work separate from this governance cleanup.
+- #30 (closed): Add PyPI environment protection for releases.
+- #31 (closed): Evaluate Python dependency audit workflow.
+- #32 (closed): Enable Code Security and add scanning gates.