spolvero 0.4.0__tar.gz → 0.5.0__tar.gz

{spolvero-0.4.0 → spolvero-0.5.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.5.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

{spolvero-0.4.0 → spolvero-0.5.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.5.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.5.0}/.github/workflows/release.yml

@@ -12,7 +12,7 @@ jobs:
     name: Build sdist + wheel
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - uses: actions/setup-python@v6
         with:

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

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

{spolvero-0.4.0 → spolvero-0.5.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.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.
 - 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,19 @@ 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 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).
+4. `spolvero build --layout-patch` regenerates while honouring reviewer
+   layout, including connector endpoint routes.
 
 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
+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
    `docs/round-trip-workflow.md`).

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spolvero
-Version: 0.4.0
+Version: 0.5.0
 Summary: Package docs-as-code diagrams into Visio-friendly handoff artifacts.
 Author: Spolvero maintainers
 License: MIT

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

@@ -0,0 +1,46 @@
+---
+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 / 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.
+- 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.
+
+Requires the `[vsdx]` extra: `pip install 'spolvero[vsdx]'`.

{spolvero-0.4.0 → spolvero-0.5.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.5.0/docs/artifact-governance.md

@@ -0,0 +1,146 @@
+# Artifact governance policy
+
+Date: 2026-07-05
+Status: Policy (DEC-67)
+Related: DEC-66 (`docs/research/artifact-governance.md` — the research this
+policy adopts), DEC-104, `docs/specs/01-round-trip-drift-engine.md` §13.
+
+## Scope
+
+This is the normative policy for every artifact the round-trip workflow
+touches: what's committed, what's local-only, where it lives, and how long
+it's kept. `docs/research/artifact-governance.md` is background — it
+compares options and explains why. This document states the decision. Where
+the two disagree, this document wins.
+
+The organizing principle: **an artifact only gets a durable home if it can't
+be rebuilt from committed source plus a committed patch.** Everything that
+passes that test stays local and ephemeral, no matter how convenient a
+storage mechanism might seem. Everything that fails it gets the lightest
+retention that closes the actual gap, not the most convenient one.
+
+## Reviewed `.vsdx` binaries
+
+Never committed. A reviewer's Visio session produces a reviewed `.vsdx`
+locally; it lives at `layouts/reviewed/<diagram>.vsdx` and is gitignored.
+
+- Do not stage a reviewed `.vsdx` under any prompt, any workflow, any
+  exception.
+- Discard the file once `extract-layout` has produced the patch and
+  `detect-drift` has produced the drift report. The patch and drift report
+  are the durable record of the review session — not the binary.
+- If a reviewer's edit needs a provenance trail beyond what the patch format
+  captures (waypoint/polyline routing, anything below the D1-D5 detectors'
+  coverage), retain the file in the org's existing M365 storage
+  (SharePoint/OneDrive) and record the link in the PR body. This is a
+  human-maintained pointer, not a spolvero-managed artifact, and it's the
+  exception, not routine practice.
+- No Git LFS, no GitHub Releases, no dedicated artifacts repo for this
+  class. None of them improve reproducibility over the patch + report pair,
+  and all of them default to permanent retention where the actual need is a
+  single review cycle.
+
+## Layout patches
+
+Committed. `layouts/<diagram>.layout.yml`, alongside the source diagram,
+tracked in git as long as the diagram exists.
+
+- This is the canonical, durable output of a review session. It's text,
+  small, and diffable — treat it the same as any other reviewed source
+  change.
+- Keyed by `spolvero.source_id`; carries `source_revision` pinning it to the
+  doc-level `spolvero.source_hash` at extraction time. Don't hand-edit a
+  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.
+
+## Drift reports
+
+Committed, in the same PR as the patch it describes.
+
+- `drift.md` / `drift.json` (or the repo's chosen report location, e.g.
+  `docs/reviews/<diagram>-drift.md`) travel with the patch, not separately
+  and not later.
+- This is the durable record of what the reviewed `.vsdx` actually
+  contained, once that file is gone. It captures findings, not the file
+  itself — that asymmetry is accepted, not a gap to close with binary
+  retention.
+- The PR body states drift status explicitly (summary line, any medium
+  findings verbatim) and coverage counts, per
+  `skills/codex/spolvero-roundtrip/references/pr-preparation.md`. The
+  report and the PR body are complementary, not redundant — don't drop one
+  because the other exists.
+- Reviewer identity is not a spolvero-managed field today. Record it in the
+  PR body (author, or an explicit "reviewed by" line if review and
+  PR-authoring are different people). This is a documentation habit, not a
+  new stamp or schema field.
+
+## Generated handoff packages
+
+Never committed. `manifest.json`, `README.md`, `source/`, `normalized/`,
+`preview/`, `visio/`, `qa/` — the full output of `spolvero build` — lives
+under `.tmp/` and nowhere else.
+
+- Fully reproducible from committed source plus a committed patch. A
+  package holds no information a rebuild can't recreate, so it never earns
+  a storage mechanism of its own.
+- Regenerate on demand for inspection; don't keep stale builds around
+  in-tree or out-of-tree.
+- The one narrow exception: if a built package needs to reach someone who
+  isn't running the build themselves, use CI workflow artifacts with a
+  short retention window (7-14 days), not git, LFS, or Releases. Don't
+  stand this up preemptively — wire it only when that need actually shows
+  up.
+
+## Regenerated previews
+
+Committed only as updates to already-tracked docs assets, never as new
+tracked paths.
+
+- If `docs/diagrams/<diagram>.svg` (or equivalent) is already tracked,
+  copy the refreshed render over it and include it in the review PR.
+- If a diagram has no existing tracked preview, its rebuilt preview stays
+  in `.tmp/` with the rest of the package. Don't introduce a new tracked
+  preview path as a side effect of a layout review.
+- Note the mmdc-rendered preview does not reflect layout patches (see
+  `docs/round-trip-workflow.md` MVP limitations) — don't treat an
+  mmdc-rendered SVG as authoritative for reviewer-applied positions.
+
+## The bundled template
+
+`src/spolvero/templates/minimal_flowchart.vsdx` is the single sanctioned
+exception to "no committed binaries," and it stays singular by default.
+
+- Permanent, tracked, ~20 KB. It exists because the engine needs some stamp
+  template to ship runnable, not because binaries are generally welcome in
+  this repo.
+- Provenance is mandatory and already set as precedent: derived from the
+  BSD 3-Clause-licensed `vsdx` Python library's test fixture, license and
+  origin recorded in `src/spolvero/templates/LICENSE.txt`.
+- Any future second tracked `.vsdx` (richer templates, DEC-104 follow-on
+  work) requires the same treatment before it's added: documented origin,
+  compatible license, and an entry in `LICENSE.txt` (or an equivalent
+  provenance file) alongside it. A second template without that paperwork
+  is not an incremental addition, it's a policy exception, and needs the
+  same scrutiny this one got.
+- This exception does not generalize. It justifies exactly the templates
+  that go through this process, not a broader allowance for committing
+  `.vsdx` files elsewhere in the repo. Committed test fixtures are the one
+  other carve-out, below.
+
+## 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
+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
+committed so end-to-end tests are reproducible without regenerating on
+every CI run.
+
+- Each committed fixture's regeneration recipe is documented in the introducing spec/plan checklist, and should be mirrored in the test file that consumes it.
+- Fixtures stay small (tens of KB) and are only added when a spec's test
+  strategy calls for one — not as a convenience for ad-hoc test data.
+- Real reviewer output never becomes a fixture; fixtures are fabricated
+  from tracked sources so they carry nothing a reviewer produced.

spolvero-0.5.0/docs/consumer-ci-recipe.md

@@ -0,0 +1,209 @@
+# Consumer CI: drift-gating recipe
+
+A recipe for gating pull requests in a *consumer* repo (one that uses
+spolvero to generate Visio handoff packages, not spolvero itself) on the
+round-trip drift engine. See `docs/round-trip-workflow.md` for the CLI
+shapes referenced below, `docs/specs/01-round-trip-drift-engine.md` §7 for
+D1–D4 semantics, and `docs/specs/03-connector-endpoint-drift.md` §7 for D5.
+
+## 1. What the gate is
+
+`spolvero detect-drift` exits non-zero when any **high-severity** finding is
+present:
+
+- **D1** — source-owned shape or connector 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.
+
+Medium findings (**D2** invalid/missing metadata, **D3** label changed,
+**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
+errors (missing inputs, missing `vsdx` extra) also exit 1, distinguishable
+from a drift failure by the absence of a written report.
+
+## 2. The artifact-availability problem, stated honestly
+
+Reviewed `.vsdx` binaries are never committed — that's the repo convention
+(`docs/round-trip-workflow.md`, "Suggested file conventions"). A round-trip
+review PR carries the layout patch (`layouts/<diagram>.layout.yml`) and,
+when a review run produced one, the drift report (`drift.md` / `drift.json`)
+— not the reviewed binary. That means a consumer CI job **cannot always
+re-run `detect-drift` itself**: the input it needs may simply not be in the
+PR.
+
+Two patterns cover the two situations:
+
+### Pattern A — gate on the committed drift report (default)
+
+Works with the repo convention as-is, no extra plumbing. CI validates the
+committed `drift.json` instead of regenerating it: fail if
+`summary.high > 0`, and fail if a layout patch changed but no drift report
+came with it (a PR that touches `layouts/**` without evidence a drift check
+ran is treated as ungated, not as clean).
+
+```bash
+# fail if the committed report shows any high-severity finding
+python -c "
+import json, sys
+report = json.load(open('drift.json'))
+high = report['summary']['high']
+print(f\"drift: {report['summary']['total']} finding(s), {high} high\")
+sys.exit(1 if high > 0 else 0)
+"
+```
+
+Equivalent with `jq`:
+
+```bash
+high=$(jq '.summary.high' drift.json)
+echo "drift: $high high-severity finding(s)"
+test "$high" -eq 0
+```
+
+### Pattern B — full re-run when the reviewed file is supplied out of band
+
+When the reviewed `.vsdx` *is* available to the runner — fetched as a
+workflow artifact from an upstream job, or pulled from wherever reviewed
+files are parked — CI can rebuild the package from committed source and run
+`detect-drift` directly, the same way a local review run would. This repo
+stays agnostic about *where* that file comes from: an artifact-governance
+policy for reviewed binaries is being drafted separately (DEC-66/67). Until
+that lands, treat Pattern B as opt-in and gated on the file's presence, not
+as the default path.
+
+## 3. Worked GitHub Actions workflow
+
+Drop this in a **consumer** repo (not spolvero) as
+`.github/workflows/drift-gate.yml`. Pattern A runs unconditionally as the
+required check; Pattern B runs only when a reviewed `.vsdx` is present,
+e.g. dropped at `layouts/reviewed/<diagram>.vsdx` by an earlier job or a
+manual upload — see `docs/round-trip-workflow.md` for the convention.
+
+```yaml
+name: Drift gate
+
+on:
+  pull_request:
+    paths:
+      - "diagrams/**"
+      - "layouts/**"
+
+permissions:
+  contents: read
+
+jobs:
+  # Pattern A: validate the committed drift report. Required check.
+  gate-on-report:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # full history so the base branch is available for the diff below
+          fetch-depth: 0
+
+      - name: Require a drift report alongside a layout patch change
+        run: |
+          if git diff --name-only "origin/${{ github.base_ref }}"...HEAD | grep -q '^layouts/.*\.layout\.yml$'; then
+            test -f drift.json || { echo "layout patch changed but drift.json is missing"; exit 1; }
+          fi
+
+      - name: Fail on high-severity drift
+        run: |
+          if [ -f drift.json ]; then
+            high=$(python -c "import json; print(json.load(open('drift.json'))['summary']['high'])")
+            echo "drift: $high high-severity finding(s)"
+            test "$high" -eq 0
+          fi
+
+  # Pattern B: full re-run, only when the reviewed .vsdx is available to the runner.
+  gate-on-rerun:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Check for reviewed .vsdx
+        id: reviewed
+        run: |
+          if [ -f "layouts/reviewed/diagram-001.vsdx" ]; then
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "present=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install spolvero
+        if: steps.reviewed.outputs.present == 'true'
+        run: pip install "spolvero[vsdx]>=0.4,<0.5"
+
+      - name: Rebuild from source
+        if: steps.reviewed.outputs.present == 'true'
+        run: >
+          spolvero build diagrams/architecture.md --out .tmp/handoff
+          --target vsdx-template
+
+      - name: Detect drift against the reviewed file
+        if: steps.reviewed.outputs.present == 'true'
+        run: >
+          spolvero detect-drift .tmp/handoff/normalized/diagram-001.ir.json
+          layouts/reviewed/diagram-001.vsdx
+          --report drift.md --json drift.json
+          --source diagrams/architecture.md
+
+      - name: Upload drift reports on failure
+        if: failure() && steps.reviewed.outputs.present == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: drift-reports
+          path: |
+            drift.md
+            drift.json
+```
+
+Adjust `diagrams/architecture.md`, `diagram-001`, and the `paths:` filter to
+match the consumer repo's own source layout. The `.tmp/` output directory
+and `--source`/`--diagram` flags follow the exact CLI shape in
+`src/spolvero/cli.py`; nothing here is inferred.
+
+## 4. Exit-code reference
+
+| Code | Meaning | CI action |
+|---|---|---|
+| 0 | Clean, or medium (D2/D3/D5-dangling) findings only | Pass. |
+| 1 | High-severity finding present (D1, D4, or D5-repointed), **or** a runtime error: missing IR/`.vsdx`/source input, `vsdx` extra not installed | Fail the check. |
+| 2 | Usage error (unknown flag, missing required argument; argparse's exit) | Fail the check; pipeline problem, not a drift finding. |
+
+The two exit-1 causes are distinguishable by the report: a genuine drift
+failure writes `drift.md`/`drift.json` and prints a findings summary to
+stderr before exiting; a runtime error prints the error and writes nothing.
+A job that needs to tell them apart should check for `drift.json` after a
+failure — the upload-artifact step in the worked example above surfaces
+exactly that difference.
+
+## 5. What to do when the gate fires
+
+- **D4 (source-revision mismatch).** The reviewed `.vsdx` was built from a
+  source revision that no longer matches HEAD. Regenerate the handoff
+  package from current source and have the reviewer redo their edits
+  against the new file before re-submitting; don't try to patch around a
+  stale D4.
+- **D1 (source-owned shape or connector deleted).** A shape or connector the
+  source still defines was removed in the reviewed file. Either restore it
+  in Visio and re-extract the layout, or, if the deletion was deliberate,
+  remove the node or edge from source first so the next build no longer
+  emits it, then redo the review round-trip.
+- **D5 (`endpoint_repointed`).** A connector endpoint was re-anchored at a
+  different source-owned node in the reviewed file. Update the source edge
+  if the new relationship is intended; otherwise re-anchor the connector in
+  Visio and re-extract.
+- **D2/D3/D5-dangling (medium).** These don't fail the gate but should still
+  be quoted in the review PR's body — a human decides whether an untracked
+  shape (D2), a relabeled one (D3), or a connector endpoint left floating
+  (D5 `endpoint_dangling`) is intentional. Teams using the spolvero-roundtrip
+  agent skill get this quoting automatically as part of its PR preparation
+  flow.

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

@@ -1,24 +1,24 @@
 # Current State
 
-Snapshot of the `spolvero` package after the v0.3.0 release and Declaratus import.
+Snapshot of the `spolvero` package after the round-trip/drift engine merge and the 0.4.0 version bump.
 
 ## Version
 
-- Package: `spolvero` 0.3.0
+- Package: `spolvero` 0.4.0 (version bump merged in PR #49; the `v0.4.0` tag and PyPI publish are pending)
 - Schema version: `1.0.0` (manifest, IR, topology IR)
-- Local validation on this Windows / Python 3.14 host: 61 passed, 5 skipped. Hosted CI runs Linux/Windows on Python 3.11 and 3.13; skip counts vary by optional tools and extras.
+- 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.
 
 ## Governance / Operations
 
 - Repository: `Declaratus/spolvero`
-- Release baseline: `v0.3.0`
+- Release baseline: `v0.3.0`; the 0.4.0 version bump is merged and awaiting the `v0.4.0` tag and PyPI publish.
 - 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.
 - Repo-local branch protection is disabled. Default-branch policy is enforced through Declaratus org rulesets after `ci-summary` proved green.
 - Active governance rulesets applying to Spolvero include `tier-internal` (default-branch PR policy and required `ci-summary`), `tag-all-tiers`, and `push-internal-baseline`.
 - CODEOWNERS routes release workflows, package metadata, schemas, bundled template assets, agent adapters, and core package code to the current owner handle until a Declaratus maintainer team exists.
-- Root `SECURITY.md`, issue/PR templates, Dependabot updates, and the security posture audit are in place. Follow-ups #30, #31, and #32 track release environment protection, Python audit tooling, and Code Security/code scanning.
+- Root `SECURITY.md`, issue/PR templates, Dependabot updates, and the security posture audit are in place. Follow-ups #30, #31, and #32 (release environment protection, Python audit tooling, Code Security/code scanning) are closed; the `pypi` environment is restricted to `v*` release tags and CodeQL/dependency-review workflows are active.
 
 ## What Works
 
@@ -31,7 +31,7 @@ Every declared input type produces a valid handoff package without crashing. The
 - `normalized/<id>.ir.json` — normalized IR (validated before write)
 - `preview/<id>.{svg,png}` — always generated
 - `visio/<id>-data-visualizer.xlsx` — Mermaid flowcharts, valid JSON topology/TRD inputs, and valid YAML topology/TRD inputs when PyYAML is installed
-- `visio/<id>.vsdx` — supported flowchart/topology IRs when `[vsdx]` is installed and the template satisfies the stamp contract
+- `visio/<id>.vsdx` — supported flowchart/topology IRs when `[vsdx]` is installed and the template satisfies the stamp contract; node and connector shapes carry `spolvero.*` source-metadata stamps and `docProps/custom.xml` records the source hash (see [vsdx-template-contract.md](vsdx-template-contract.md))
 - `visio/<id>-template-notes.md` — per-diagram template guidance
 - `qa/<id>-qa.md` and `qa/<id>-conversion-log.json`
 - `README.md` — package overview
@@ -105,6 +105,14 @@ Slashes from parallelogram `[/.../]` are stripped from the label.
 - Generated IR and manifests are schema-validated before write; internal schema drift fails fast with a clear error.
 - `template-notes.md` recommends Cross-Functional Flowchart vs. Basic Flowchart based on whether the IR has containers.
 
+### 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.
+- See [round-trip-workflow.md](round-trip-workflow.md) for the end-to-end flow and MVP limitations.
+
 ### Governance and repository hygiene tooling
 
 - `spolvero hygiene` scans tracked files for governance-sensitive patterns, generated package artifacts, stray workbooks, and unapproved `.vsdx` templates. Use `--include-untracked` only for intentional local workspace review.
@@ -119,6 +127,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. |
 | Workbook metadata | Mermaid metadata columns | Mermaid carries no `Phase`, `System`, `Owner`, or `Criticality` metadata; topology nodes can populate them via `metadata`. |
 
 ## Roadmap
@@ -134,16 +143,22 @@ Major engineering items now landed:
 
 7. Declaratus import, post-import operating docs, repository hygiene gate, read-only VSDX inspector, and opt-in sanitization helper.
 
+8. ✅ Round-trip layout and drift engine (spec 01): source-metadata stamping, `extract-layout`, `detect-drift`, and `build --layout-patch` (PRs #43/#44).
+
+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.
+
 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.
 
 ## References
 
 - [support-matrix.md](support-matrix.md)
 - [vsdx-template-contract.md](vsdx-template-contract.md)
+- [round-trip-workflow.md](round-trip-workflow.md)
 - [qa-corpus-and-sanitization.md](qa-corpus-and-sanitization.md)
 - [qa-findings-plan.md](qa-findings-plan.md)
 - [agent-usage.md](agent-usage.md)