sysml-import: add --auto-cache-from-submodule helper for zero-config prev-XMI cache population #259

Follow-up from PR #233 dime review cycle 3 (finding F-IMP-402, TRACKED).

Background

PR #233 landed the zero-config PREV_VERSION auto-derive for the SysML importer: dotnet run --project build/MTConnect.NET-SysML-Import -- --new-xmi <path> --output . picks up PREV_VERSION from MTConnectVersions.Max, resolves the prior XMI via Strategy B (cache at build/.cache/sysml-prev/MTConnectSysMLModel_v${PREV_VERSION}.xml) or Strategy A (submodule tag), and emits the delta.

Strategy B is the primary path but it requires the maintainer to populate the cache manually in Phase 3.2 of the version-bump runbook:

mkdir -p build/.cache/sysml-prev
git -C build/sysml-model checkout v${PREV_VERSION}
cp build/sysml-model/MTConnectSysMLModel.xml \
   build/.cache/sysml-prev/MTConnectSysMLModel_v${PREV_VERSION}.xml
git -C build/sysml-model checkout v${NEW_VERSION}

This is boilerplate that the importer could do itself.

Proposal

Add --auto-cache-from-submodule to the SysML importer. When passed:

1. Parse MTConnectVersions.Max to determine PREV_VERSION (same code path as the current auto-derive).
2. If build/.cache/sysml-prev/MTConnectSysMLModel_v${PREV_VERSION}.xml already exists, skip (cheap idempotency).
3. Otherwise, git -C build/sysml-model checkout v${PREV_VERSION} to move the submodule tip.
4. Copy build/sysml-model/MTConnectSysMLModel.xml to the cache path.
5. Restore the submodule to its original ref (typically v${NEW_VERSION} — capture git rev-parse HEAD before step 3, restore after step 4).
6. Continue into the normal delta emission with the freshly-populated cache.

The flag is idempotent (step 2), cheap when the cache is populated, and rolls back cleanly on failure (step 5's original ref restore). It replaces the four-line runbook snippet with --auto-cache-from-submodule on the same command line.

Alternatives considered

• Auto-run this unconditionally in zero-config mode — rejected. Some maintainers keep the submodule pinned to main (for spec-development work) and expect the importer to fail fast on a missing cache, not silently rewrite the submodule state.
• Separate tools/populate-sysml-cache.sh script — viable but adds a second entry point. Keeping it as an importer flag preserves the single-CLI surface documented in docs/cli/sysml-import.md.

Acceptance criteria

• New CLI flag --auto-cache-from-submodule documented in Program.cs header, PrintHelp, docs/cli/sysml-import.md, and auto-regenerated docs/reference/cli.md.
• Test coverage in tests/MTConnect.NET-Generator-Tests/AutoDerivePreviousXmiTests.cs (or a new fixture) covering: cache already populated (no-op), cache absent (submodule-checkout populates, delta emits), submodule missing (fail-hard with actionable message), submodule ref restored on happy path AND on failure path.
• Composable with --full-tree (the flag is a no-op when the delta path is disabled).

Dime cycle provenance

Filed as TRACKED per §1.0d-trigies-septies during the dime review cycle 3 of PR #233 (2026-08-21). The cycle's HIGH + MEDIUM findings landed atomically in the PR; this follow-up is scoped separately because the cache-population helper is a distinct feature (not a bug-class sibling of the auto-derive resolver already shipped).

Priority: low. The current runbook snippet is four lines and lands under 30 seconds; automating it is quality-of-life, not correctness.