Upgrade

/llmdoc:upgrade

Use this command only for an explicit legacy-to-V3 migration.

Do not suggest this command proactively. Do not mention its internals outside this file.

CLI commands below run as npx -y @tokenroll/llmdoc <cmd>.

Authorization

An explicit /llmdoc:upgrade invocation authorizes this run to:

• rewrite the repository's llmdoc/ surface into the V3 layout
• create or rewrite llmdoc/meta.json
• delete obsolete legacy llmdoc docs and state files when their content has been migrated or intentionally dropped
• write temporary investigation reports under .llmdoc-tmp/investigations/

This command should run against a rollback-safe git state.

Preconditions

• git status -- llmdoc/ must be clean before the first formal write.
• Rollback means git checkout -- llmdoc/ plus deleting newly created files, restoring the pre-migration legacy surface; never hand-edit files back.
• Confirm the legacy surface has a recoverable git backup, and keep the migration isolated so it can be reverted as one change.
• Run the CLI migration surface directly; do not hand-simulate the deterministic migration logic in prompt text.
• If validation fails after migration writes and cannot be repaired in-run, roll back the migration write-set before reporting failure.

Workflow

1. Map the legacy knowledge surface.

   • Use investigator to identify the current legacy structure, surviving durable knowledge, and obsolete material.

2. Run the deterministic CLI migration or diagnostic path.

   • Call upgrade.
   • Use CLI diagnostics as the primary migration truth for what was transformed, skipped, or rejected.
   • The CLI inventories legacy markers and reports the target V3 shape; it does not move document bodies on its own.

3. Finalize with recorder.

   • Rebuild or adjust the knowledge surface around the V3 root singleton plus topic docs when the CLI reports follow-up recorder work.
   • Fold still-valid historical conclusions into active architecture and guide docs.
   • Drop obsolete migration-only material instead of preserving it as dead weight.

4. Validate before reporting success.

   • Seed the ledger with init-state when no llmdoc/meta.json survives the migration; validate cannot pass without a ledger.
   • When a ledger already exists, batch-register migrated docs with adopt <path...>; never hand-edit meta.json or rebuild existing bodies through new.
   • Run validate and repair every failure it reports.
   • Finalize with commit --all -m "<message>".

State Invariants

• Successful migration initializes V3 baseline state only after validation passes.
• Per-document fingerprint updates happen only for the migrated or replacement docs that survived.
• A successful first V3 migration seeds the initial convergence snapshot with source: init; later convergence changes belong only to prune.

Result Contract

• success: CLI migration completed, recorder follow-up succeeded, and validation passed.
• no_change: the declared scope was fully verified and no migration write was needed.
• dry_run: migration diagnostics or a plan was produced without writing llmdoc/; do not advance state.
• incomplete: evidence was insufficient, user input is required, or normal update/prune is needed; roll back writes and do not advance state.
• failed: migration failed and writes were rolled back.

Always report:

• the legacy surfaces consumed
• the upgrade result
• the V3 surfaces created
• the legacy files deleted or intentionally dropped
• the validate and commit results