Problem
/om-vault-upgrade (the vault-migrator agent) is content-migration-focused — it imports notes from a source vault into this instance. It has no awareness that the current vault might be shardmind-managed, so it can't help with the most common real case: "my managed vault drifted / is behind / was incompletely adopted."
This came up live: a months-old work vault was a shardmind install of v6.1.0 with no state.json (incomplete adoption after shardmind's release), which silently froze its upgrade path. /om-vault-upgrade as written would attempt a manual content migration and miss the actual problem (the engine/management layer).
Proposed change — shardmind-aware preflight + branch
On invocation, detect the environment:
which shardmind.shardmind/shard.yaml + .shardmind/state.json present?- installed version vs latest
- adoption completeness (is
state.json present & consistent?)
Then branch:
- Managed + behind → engine/version upgrade = shardmind's job. Delegate to
shardmind update and have the skill act as orchestrator + verifier (run it, then check hooks run, qmd serves, integrity holds) — not a manual file migrator.
- Cloned-but-unmanaged / incomplete adoption (the missing-
state.json case) → repair the management layer first with shardmind adopt --mode keep-all-mine (preserves customizations), then update. The skill should detect the missing state.json and offer this rather than a manual migration that ignores the engine layer.
- No shardmind installed → fall back to today's manual
vault-migrator behavior.
Customization-aware reporting (applies to all branches)
After any shardmind run, classify divergent managed files as ahead/intended vs behind/stale and:
- surface only genuine behind-files to the user (don't blind-
use-all-theirs);
- flag files where the local vault is ahead of the template as upstream candidates.
In the live case, every one of the 33 divergent files turned out to be an intentional local enhancement (recursive active/** globs, Slack-tooled agents, an active-hygiene lib, org-change detection, even an unreleased isBlockedMemoryPath guard) — a blunt take-theirs would have downgraded the vault. The skill must make this ahead/behind distinction, which shardmind's bulk modes can't.
Invocation note
The skill needs shardmind's non-interactive recipe (today CI=true … --yes < /dev/null; see shardmind#139) to run it without the Ink raw-mode crash — or it should instruct the user to run the interactive command via the CLI ! prefix when per-file decisions are required.
Division of ownership
shardmind owns the version/engine lifecycle; /om-vault-upgrade owns content import + verification + the ahead/behind judgment.
Related
Problem
/om-vault-upgrade(thevault-migratoragent) is content-migration-focused — it imports notes from a source vault into this instance. It has no awareness that the current vault might be shardmind-managed, so it can't help with the most common real case: "my managed vault drifted / is behind / was incompletely adopted."This came up live: a months-old work vault was a shardmind install of v6.1.0 with no
state.json(incomplete adoption after shardmind's release), which silently froze its upgrade path./om-vault-upgradeas written would attempt a manual content migration and miss the actual problem (the engine/management layer).Proposed change — shardmind-aware preflight + branch
On invocation, detect the environment:
which shardmind.shardmind/shard.yaml+.shardmind/state.jsonpresent?state.jsonpresent & consistent?)Then branch:
shardmind updateand have the skill act as orchestrator + verifier (run it, then check hooks run, qmd serves, integrity holds) — not a manual file migrator.state.jsoncase) → repair the management layer first withshardmind adopt --mode keep-all-mine(preserves customizations), then update. The skill should detect the missingstate.jsonand offer this rather than a manual migration that ignores the engine layer.vault-migratorbehavior.Customization-aware reporting (applies to all branches)
After any shardmind run, classify divergent managed files as ahead/intended vs behind/stale and:
use-all-theirs);In the live case, every one of the 33 divergent files turned out to be an intentional local enhancement (recursive
active/**globs, Slack-tooled agents, an active-hygiene lib, org-change detection, even an unreleasedisBlockedMemoryPathguard) — a blunt take-theirs would have downgraded the vault. The skill must make this ahead/behind distinction, which shardmind's bulk modes can't.Invocation note
The skill needs shardmind's non-interactive recipe (today
CI=true … --yes < /dev/null; see shardmind#139) to run it without the Ink raw-mode crash — or it should instruct the user to run the interactive command via the CLI!prefix when per-file decisions are required.Division of ownership
shardmind owns the version/engine lifecycle;
/om-vault-upgradeowns content import + verification + the ahead/behind judgment.Related