spolvero 0.3.0__tar.gz → 0.4.0__tar.gz

{spolvero-0.3.0 → spolvero-0.4.0}/.gitattributes

@@ -1,2 +1,3 @@
 * text=auto eol=lf
+*.vsdx binary
 

spolvero-0.4.0/.github/CODEOWNERS

@@ -0,0 +1,33 @@
+# Current governance owner for release and sensitive paths.
+# Extend these entries with a Declaratus maintainer team once one exists.
+
+# CI, release automation, and repository-level agent instructions.
+/.github/CODEOWNERS @Barry-Johnston
+/.github/workflows/ @Barry-Johnston
+/.github/copilot-instructions.md @Barry-Johnston
+/.github/instructions/ @Barry-Johnston
+
+# Package metadata, dependency lock state, and release-facing docs.
+/pyproject.toml @Barry-Johnston
+/uv.lock @Barry-Johnston
+/README.md @Barry-Johnston
+
+# Governance and operating posture.
+/HANDOFF.md @Barry-Johnston
+/AGENTS.md @Barry-Johnston
+/CLAUDE.md @Barry-Johnston
+/docs/current-state.md @Barry-Johnston
+/docs/declaratus-migration.md @Barry-Johnston
+/docs/qa-findings-plan.md @Barry-Johnston
+/docs/agent-usage.md @Barry-Johnston
+/docs/agents/ @Barry-Johnston
+
+# Core package behavior, validation, schemas, and bundled Visio assets.
+/src/spolvero/ @Barry-Johnston
+/tests/ @Barry-Johnston
+/src/spolvero/schemas/ @Barry-Johnston
+/src/spolvero/templates/ @Barry-Johnston
+
+# Distributed agent adapters and Codex skill surface.
+/adapters/ @Barry-Johnston
+/skills/ @Barry-Johnston

spolvero-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,60 @@
+---
+name: Bug report
+about: Something in Spolvero is not working as expected
+labels: ["bug"]
+---
+
+## Describe the bug
+
+<!-- What went wrong? Be specific about the command, input type, target engine, or generated artifact. -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+<!-- What did you expect to happen? -->
+
+## Actual behavior
+
+<!-- What happened instead? Include sanitized error output, manifest warnings, or QA excerpts when useful. -->
+
+## Affected area
+
+<!-- Check all that apply. -->
+
+- [ ] CLI or package API
+- [ ] Source extraction
+- [ ] Mermaid parsing or rendering
+- [ ] Topology / TRD parsing
+- [ ] Data Visualizer workbook
+- [ ] VSDX template engine
+- [ ] Visio COM fallback behavior
+- [ ] QA report or manifest fidelity
+- [ ] GitHub Actions or release workflow
+- [ ] Other:
+
+## Environment
+
+- OS:
+- Python version:
+- Spolvero version or commit:
+- Command or workflow:
+- Optional extras installed:
+
+## Minimal sanitized input
+
+<!-- Paste the smallest synthetic or sanitized input that reproduces the issue.
+     Do not include real infrastructure names, credentials, client names, hostnames, or proprietary diagrams. -->
+
+```mermaid
+flowchart TD
+  A[Start] --> B[End]
+```
+
+## Related context
+
+<!-- Links, related issues, or notes for maintainers. -->

spolvero-0.4.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Declaratus governance source of truth
+    url: https://github.com/Declaratus/governance
+    about: Use this for org-level GitHub policy, repository properties, rulesets, and inherited controls.
+  - name: Security policy
+    url: https://github.com/Declaratus/spolvero/security/policy
+    about: Report vulnerabilities privately through the repository security policy.

spolvero-0.4.0/.github/ISSUE_TEMPLATE/feature_engine_work.md

@@ -0,0 +1,62 @@
+---
+name: Feature or engine work
+about: Propose package behavior, parser, renderer, engine, or CLI changes
+labels: ["enhancement", "area: engines"]
+---
+
+## Summary
+
+<!-- One or two sentences describing the desired change. -->
+
+## Motivation
+
+<!-- What problem does this solve? What is hard or missing today? -->
+
+## Proposed behavior
+
+<!-- Describe the target behavior concretely. Include input, target, manifest, QA, or artifact examples if helpful. -->
+
+## Affected area
+
+<!-- Check all that apply. -->
+
+- [ ] CLI or package API
+- [ ] Source extraction
+- [ ] Mermaid IR
+- [ ] Topology / TRD IR
+- [ ] Renderer fallback behavior
+- [ ] Data Visualizer workbook
+- [ ] VSDX template engine
+- [ ] Visio COM engine
+- [ ] Schemas
+- [ ] Agent adapters or Codex skill
+- [ ] Other:
+
+## Editability claim
+
+<!-- If this changes output editability, state the expected declaration:
+     native, semi_native, vector_reference, or raster_reference. Explain why that claim is honest. -->
+
+## Fixture posture
+
+<!-- New fixtures should be synthetic and organization-agnostic. If a real sample inspired the work,
+     describe how it was reduced or sanitized before adding anything to the repo. -->
+
+## Governance fit
+
+<!-- If this changes inherited GitHub policy, repository properties, rulesets, security posture,
+     or publishing posture, open or link the source-of-truth work in Declaratus/governance.
+     Keep repo-local changes here focused on Spolvero behavior and documentation. -->
+
+## Validation plan
+
+<!-- List the commands or manual checks that should prove the work is ready. -->
+
+- [ ] `uv run python -m compileall src tests`
+- [ ] `uv run pytest -rs`
+- [ ] `uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data-visualizer`
+- [ ] Other:
+
+## Related context
+
+<!-- Links, related issues, docs, or prior decisions. -->

spolvero-0.4.0/.github/ISSUE_TEMPLATE/qa_hygiene_work.md

@@ -0,0 +1,52 @@
+---
+name: QA or hygiene work
+about: Track validation, repository hygiene, sanitization, or inspection improvements
+labels: ["type: qa", "type: hygiene"]
+---
+
+## Summary
+
+<!-- What QA, hygiene, inspection, or sanitization concern should be addressed? -->
+
+## Affected area
+
+<!-- Check all that apply. -->
+
+- [ ] `spolvero hygiene`
+- [ ] `spolvero inspect-vsdx`
+- [ ] QA report content
+- [ ] Manifest warnings or schema validation
+- [ ] Test fixtures
+- [ ] CI validation
+- [ ] External corpus or local-only review material
+- [ ] Other:
+
+## Risk being controlled
+
+<!-- Examples: generated artifacts accidentally tracked, sensitive template metadata, stale QA warnings,
+     incomplete schema validation, or overclaimed editability. -->
+
+## Fixture and sample handling
+
+<!-- Keep fixtures synthetic and organization-agnostic. Do not attach raw customer, infrastructure,
+     proprietary, secret, or environment-specific material. Keep external review samples outside git unless
+     they are explicitly approved. -->
+
+## Proposed checks
+
+<!-- List the commands, assertions, or manual review steps that should prove the work is ready. -->
+
+- [ ] `uv run spolvero hygiene --report .tmp/hygiene.md`
+- [ ] Optional local sample scan: `uv run spolvero hygiene --include-untracked --report .tmp/local-hygiene.md`
+- [ ] `uv run spolvero inspect-vsdx PATH --report .tmp/vsdx-inspection.md`
+- [ ] `uv run pytest -rs`
+- [ ] Other:
+
+## Governance fit
+
+<!-- If this changes inherited GitHub policy, repository properties, rulesets, or org-level security posture,
+     open or link the source-of-truth work in Declaratus/governance instead of duplicating policy here. -->
+
+## Related context
+
+<!-- Links, related issues, docs, or prior decisions. -->

spolvero-0.4.0/.github/ISSUE_TEMPLATE/release_work.md

@@ -0,0 +1,54 @@
+---
+name: Release work
+about: Plan or track Spolvero packaging, tag, PyPI, or release-note changes
+labels: ["area: packaging", "type: release"]
+---
+
+## Release summary
+
+<!-- What release, packaging, publishing, or release-note work is being proposed? -->
+
+## Scope
+
+<!-- Check all that apply. -->
+
+- [ ] Package metadata
+- [ ] Dependency or lock state
+- [ ] Build backend or wheel contents
+- [ ] GitHub release workflow
+- [ ] PyPI trusted publishing
+- [ ] Release notes
+- [ ] Post-release docs or handoff
+- [ ] Other:
+
+## Version and compatibility
+
+- Target version:
+- Supported Python versions:
+- Expected extras affected:
+
+## Validation plan
+
+<!-- Reference the commands that prove the release path is ready. -->
+
+- [ ] `uv run python -m compileall src tests`
+- [ ] `uv run pytest -rs`
+- [ ] `uv run spolvero hygiene --report .tmp/release-hygiene.md`
+- [ ] `uv run spolvero inspect-vsdx src/spolvero/templates/minimal_flowchart.vsdx --report .tmp/minimal-flowchart-vsdx.md`
+- [ ] `uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data-visualizer --title "CI Smoke"`
+- [ ] Build sdist/wheel and inspect contents
+
+## Fixture and artifact posture
+
+<!-- Keep generated packages, built distributions, and local smoke output out of git unless explicitly approved.
+     Use synthetic and organization-agnostic fixtures. -->
+
+## Governance fit
+
+<!-- If this changes inherited org release policy, tag controls, repository properties, or publishing controls,
+     open or link the source-of-truth work in Declaratus/governance. Keep repo-local changes here focused on
+     Spolvero package behavior and release documentation. -->
+
+## Related context
+
+<!-- Links, related issues, docs, release runs, or prior decisions. -->

spolvero-0.4.0/.github/ISSUE_TEMPLATE/vsdx_template_work.md

@@ -0,0 +1,53 @@
+---
+name: VSDX or template work
+about: Propose changes to Visio package handling, bundled templates, or Office artifacts
+labels: ["area: visio"]
+---
+
+## Summary
+
+<!-- What VSDX/template behavior should change? -->
+
+## Artifact scope
+
+<!-- Check all that apply. -->
+
+- [ ] Bundled `minimal_flowchart.vsdx`
+- [ ] New or replacement tracked template
+- [ ] `vsdx-template` engine behavior
+- [ ] `inspect-vsdx` report behavior
+- [ ] Data Visualizer workbook interoperability
+- [ ] Visio Plan 2 manual validation
+- [ ] Other:
+
+## Provenance and license
+
+<!-- If this proposes a tracked Office artifact, describe its source and license.
+     Do not attach proprietary, client, environment-specific, or unsanitized binary material. -->
+
+- Source:
+- License:
+- Sanitization / reduction approach:
+
+## Security and metadata review
+
+<!-- Note expected review of document properties, relationships, media, comments, thumbnails,
+     custom properties, and sensitive-pattern findings. -->
+
+- [ ] `uv run spolvero inspect-vsdx PATH --report .tmp/template-inspection.md`
+- [ ] `uv run spolvero hygiene --report .tmp/template-hygiene.md`
+- [ ] Optional local sample scan: `uv run spolvero hygiene --include-untracked --report .tmp/template-local-hygiene.md`
+- [ ] Manual review of package provenance and metadata
+
+## Expected behavior
+
+<!-- Describe the expected generated files, editability declaration, fallback warnings, or Visio import result. -->
+
+## Fixture posture
+
+<!-- Use synthetic diagrams and organization-agnostic sample names. Keep generated packages under `.tmp/`
+     unless a reviewer approves a minimal fixture. -->
+
+## Related context
+
+<!-- Links, related issues, docs, or prior decisions. -->

spolvero-0.4.0/.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/Phoenix"
+    open-pull-requests-limit: 5
+    labels:
+      - "area: packaging"
+      - "area: security"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:30"
+      timezone: "America/Phoenix"
+    open-pull-requests-limit: 5
+    labels:
+      - "area: packaging"
+      - "area: security"

spolvero-0.4.0/.github/pull_request_template.md

@@ -0,0 +1,50 @@
+## Summary
+
+<!-- What changed, and why? Link the issue when available. -->
+
+## Scope
+
+<!-- Check all that apply. -->
+
+- [ ] Package code
+- [ ] Engine, parser, renderer, or IR behavior
+- [ ] Schemas or validation
+- [ ] VSDX/template assets
+- [ ] Agent adapters or Codex skill
+- [ ] Documentation
+- [ ] GitHub workflows, release, or packaging
+- [ ] QA, hygiene, or inspection
+- [ ] Other:
+
+## Fixture and artifact posture
+
+<!-- Confirm new samples are synthetic and organization-agnostic.
+     Keep generated handoff packages, workbooks, local smoke output, and external review material under ignored
+     local paths such as `.tmp/` unless explicitly approved as fixtures. -->
+
+- [ ] New or changed fixtures are synthetic / sanitized.
+- [ ] No generated package output or local smoke artifact is being tracked unexpectedly.
+- [ ] Any tracked Office artifact has provenance, license, metadata, and inspection notes.
+
+## Governance notes
+
+<!-- If this PR changes inherited GitHub policy, repository properties, rulesets, or org-level controls,
+     link the corresponding Declaratus/governance work. Keep repo-local policy focused on Spolvero behavior. -->
+
+- Declaratus/governance link, if needed:
+
+## Validation
+
+<!-- Check the commands you ran. Mark intentionally skipped items with a short reason. -->
+
+- [ ] `uv run python -m compileall src tests`
+- [ ] `uv run pytest -rs`
+- [ ] `uv run spolvero hygiene --report .tmp/pr-hygiene.md`
+- [ ] `uv run spolvero inspect-vsdx src/spolvero/templates/minimal_flowchart.vsdx --report .tmp/minimal-flowchart-vsdx.md`
+- [ ] `uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data-visualizer --title "CI Smoke"`
+- [ ] `git diff --check`
+
+## Release impact
+
+<!-- Note whether this affects package metadata, dependency extras, bundled assets, PyPI publishing,
+     or release notes. -->

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

@@ -4,6 +4,9 @@ on:
   push:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
@@ -31,3 +34,16 @@ 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')"
 
+  ci-summary:
+    name: ci-summary
+    runs-on: ubuntu-latest
+    needs: [test]
+    if: always()
+    steps:
+      - name: Check test matrix result
+        run: |
+          if [ "${{ needs.test.result }}" != "success" ]; then
+            echo "test result: ${{ needs.test.result }}"
+            exit 1
+          fi
+          echo "test result: ${{ needs.test.result }}"

spolvero-0.4.0/.github/workflows/codeql.yml

@@ -0,0 +1,32 @@
+name: CodeQL
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  schedule:
+    - cron: "36 11 * * 1"
+  workflow_dispatch:
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: CodeQL Python
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: python
+          queries: security-and-quality
+
+      - uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:python"

spolvero-0.4.0/.github/workflows/dependency-review.yml

@@ -0,0 +1,20 @@
+name: Dependency Review
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    name: Dependency Review
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high
+          fail-on-scopes: runtime, development, unknown

spolvero-0.4.0/HANDOFF.md

@@ -0,0 +1,75 @@
+# Handoff
+
+Latest durable queue for `spolvero`.
+
+## Current State
+
+- Core goal is unchanged: package docs-as-code diagrams into Visio-friendly handoff artifacts with honest editability declarations.
+- 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.
+- 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.
+- SECURITY.md, issue/PR templates, Dependabot updates, and the security posture audit are in place.
+- Code Security is enabled for the private repo; CodeQL and dependency-review workflows cover Python scanning and dependency-change gates.
+- The `pypi` environment is restricted to release tags matching `v*`. Required reviewers were evaluated but are not available for this private repository under the current GitHub plan.
+- Generated package output, local smoke packages, and external review material belong under ignored `.tmp/` or another local-only path.
+- The bundled `src/spolvero/templates/minimal_flowchart.vsdx` is the only approved tracked `.vsdx` template. It is derived from the BSD-licensed `vsdx` Python package fixture and documented in `src/spolvero/templates/LICENSE.txt`.
+
+## Operating Validation Commands
+
+```bash
+uv run spolvero hygiene --report .tmp/operating-hygiene.md
+uv run spolvero inspect-vsdx src/spolvero/templates/minimal_flowchart.vsdx --report .tmp/minimal-flowchart-vsdx.md
+uv run spolvero sanitize-vsdx src/spolvero/templates/minimal_flowchart.vsdx --out .tmp/minimal-flowchart-sanitized.vsdx --report .tmp/minimal-flowchart-sanitized.md
+uv run pytest -rs
+uv run python -m compileall src tests
+uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data-visualizer
+uv run spolvero build tests/fixtures/sample-trd.topology.json --out .tmp/topology-json-smoke --target data-visualizer --title "Topology JSON Smoke"
+git diff --check
+```
+
+## v0.4 Engine Handoff
+
+Governance cleanup is complete. The v0.4 template mutation pass now covers:
+
+1. #10 Synthetic VSDX stamp/master contract documented in `docs/vsdx-template-contract.md`.
+2. #11 Flowchart shape routing through preferred stamps with explicit degradation warnings.
+3. #12 Topology-aware `vsdx-template` generation with topology/container stamp routing and fallback warnings.
+4. #13 Docs, support matrix, current-state, agent recipes, and skill references refreshed.
+5. #15 QA corpus/sanitization policy plus opt-in `sanitize-vsdx --out` tooling for XML redaction.
+
+Keep #14 true COM-native Visio generation separate. The remaining product follow-up is higher-fidelity synthetic templates beyond the bundled minimal fixture; the COM-native body should wait until that path is better specified and tested.
+
+Residual governance notes:
+
+1. Revisit a `pypi` required-reviewer gate if Declaratus plan/team support becomes available for private repositories.
+2. Revisit `pip-audit` when Spolvero gains default runtime dependencies or release-critical optional extras.
+
+## 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).
+See `docs/specs/01-round-trip-drift-engine.md` for the spec and
+`docs/round-trip-workflow.md` for the end-to-end flow.
+
+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.
+
+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
+   `docs/round-trip-workflow.md`).

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spolvero
-Version: 0.3.0
+Version: 0.4.0
 Summary: Package docs-as-code diagrams into Visio-friendly handoff artifacts.
 Author: Spolvero maintainers
 License: MIT
@@ -11,6 +11,8 @@ Requires-Dist: pywin32>=306; (platform_system == 'Windows') and extra == 'com'
 Provides-Extra: topology
 Requires-Dist: pyyaml>=6.0; extra == 'topology'
 Provides-Extra: vsdx
+Requires-Dist: defusedxml>=0.7; extra == 'vsdx'
+Requires-Dist: pyyaml>=6.0; extra == 'vsdx'
 Requires-Dist: vsdx>=0.5; extra == 'vsdx'
 Description-Content-Type: text/markdown
 
@@ -62,14 +64,15 @@ uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data
 
 Generated packages are intentionally ignored by git.
 
-Migration hygiene checks are also available:
+Operating hygiene checks are also available:
 
 ```bash
-uv run spolvero hygiene --report .tmp/migration-hygiene.md
+uv run spolvero hygiene --report .tmp/operating-hygiene.md
 uv run spolvero inspect-vsdx src/spolvero/templates/minimal_flowchart.vsdx --report .tmp/minimal-flowchart-vsdx.md
+uv run spolvero sanitize-vsdx src/spolvero/templates/minimal_flowchart.vsdx --out .tmp/minimal-flowchart-sanitized.vsdx --report .tmp/minimal-flowchart-sanitized.md
 ```
 
-See [docs/declaratus-migration.md](docs/declaratus-migration.md) for the fresh-history Declaratus import checklist.
+See [docs/declaratus-migration.md](docs/declaratus-migration.md) for post-import operating guidance.
 
 ## Optional Extras
 
@@ -90,11 +93,13 @@ A Mermaid CLI (`mmdc`) on `PATH` is auto-detected for higher-fidelity Mermaid pr
 |---|---|---|---|
 | `package-only` | `internal_preview` | `vector_reference` | Skips workbook generation. Even Mermaid flowcharts and topology IRs are downgraded to a vector reference because no Visio handoff artifact is produced. |
 | `data-visualizer` | `data_visualizer_xlsx` | `semi_native` | Default semi-native path. Generates a Visio Data Visualizer workbook for supported Mermaid flowcharts and topology IRs with recognized nodes. Empty/failed topology parses are downgraded to reference previews with no empty workbook. |
-| `vsdx-template` | `vsdx_template_mutation` | `semi_native` (real `.vsdx`) | Mutates a template via the [`vsdx`] extra to produce a real `.vsdx` for supported flowcharts. Use `--template PATH` to override the bundled template. Unsupported inputs and missing extras/templates cascade with clear warnings. |
+| `vsdx-template` | `vsdx_template_mutation` | `semi_native` (real `.vsdx`) | Mutates a template via the [`vsdx`] extra to produce a real `.vsdx` for supported flowchart and topology IRs. Use `--template PATH` to override the bundled template. Unsupported inputs and missing extras/templates cascade with clear warnings. |
 | `visio-com` | `visio_com_automation` | delegated output editability | Probes Visio Plan 2 / Professional via COM (Windows + [`com`] extra), then currently delegates through `vsdx-template` and `data-visualizer`. A future true COM-native path will be the only source of `native` output. |
 
 The manifest always records both `requested_engine` and `actual_engine` so engine fallbacks are visible without parsing warning strings.
 
+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.
+
 ## Inputs
 
 - Mermaid flowchart (`.mmd`, fenced ` ```mermaid ` in Markdown) — primary input; full IR + workbook.

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

@@ -46,14 +46,15 @@ uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data
 
 Generated packages are intentionally ignored by git.
 
-Migration hygiene checks are also available:
+Operating hygiene checks are also available:
 
 ```bash
-uv run spolvero hygiene --report .tmp/migration-hygiene.md
+uv run spolvero hygiene --report .tmp/operating-hygiene.md
 uv run spolvero inspect-vsdx src/spolvero/templates/minimal_flowchart.vsdx --report .tmp/minimal-flowchart-vsdx.md
+uv run spolvero sanitize-vsdx src/spolvero/templates/minimal_flowchart.vsdx --out .tmp/minimal-flowchart-sanitized.vsdx --report .tmp/minimal-flowchart-sanitized.md
 ```
 
-See [docs/declaratus-migration.md](docs/declaratus-migration.md) for the fresh-history Declaratus import checklist.
+See [docs/declaratus-migration.md](docs/declaratus-migration.md) for post-import operating guidance.
 
 ## Optional Extras
 
@@ -74,11 +75,13 @@ A Mermaid CLI (`mmdc`) on `PATH` is auto-detected for higher-fidelity Mermaid pr
 |---|---|---|---|
 | `package-only` | `internal_preview` | `vector_reference` | Skips workbook generation. Even Mermaid flowcharts and topology IRs are downgraded to a vector reference because no Visio handoff artifact is produced. |
 | `data-visualizer` | `data_visualizer_xlsx` | `semi_native` | Default semi-native path. Generates a Visio Data Visualizer workbook for supported Mermaid flowcharts and topology IRs with recognized nodes. Empty/failed topology parses are downgraded to reference previews with no empty workbook. |
-| `vsdx-template` | `vsdx_template_mutation` | `semi_native` (real `.vsdx`) | Mutates a template via the [`vsdx`] extra to produce a real `.vsdx` for supported flowcharts. Use `--template PATH` to override the bundled template. Unsupported inputs and missing extras/templates cascade with clear warnings. |
+| `vsdx-template` | `vsdx_template_mutation` | `semi_native` (real `.vsdx`) | Mutates a template via the [`vsdx`] extra to produce a real `.vsdx` for supported flowchart and topology IRs. Use `--template PATH` to override the bundled template. Unsupported inputs and missing extras/templates cascade with clear warnings. |
 | `visio-com` | `visio_com_automation` | delegated output editability | Probes Visio Plan 2 / Professional via COM (Windows + [`com`] extra), then currently delegates through `vsdx-template` and `data-visualizer`. A future true COM-native path will be the only source of `native` output. |
 
 The manifest always records both `requested_engine` and `actual_engine` so engine fallbacks are visible without parsing warning strings.
 
+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.
+
 ## Inputs
 
 - Mermaid flowchart (`.mmd`, fenced ` ```mermaid ` in Markdown) — primary input; full IR + workbook.