Settings Reconfiguration

Historical (retired in CLI 6.0.0). This page describes the manifest-driven lifecycle (hi scaffold, hi ensure, hi update --check). The Registry Baseline replaced it with hi init, hi update, hi diff, and hi check: see Scaffold Baseline and the CLI scaffolding runbook.

hi ensure changes provider authority and the Product/Backlog Root destination in an existing .devpunks/settings.json. It does not run the broader scaffold initialization flow.

Trigger

An operator needs to change the backlog provider, asset provider, repository manager, or Product/Backlog Root URL after initialization. The same command migrates a legacy Linear Epic Project destination.

Steps

1. Run hi ensure from the initialized repository root.
2. Review the current backlogProvider, assetProviderSlug, and repositoryManager defaults and select replacements where needed.
3. Enter the Product/Backlog Root URL. It must be absolute HTTP(S); surrounding whitespace is removed. Linear requires https://linear.app/<workspace>/initiative/<root-initiative>.
4. The CLI derives the selected repository manager's required tools while preserving unrelated tool IDs.
5. The settings authority validates the complete result, preserves unknown document fields, and rewrites only .devpunks/settings.json.

The existing backlogProjectUrl key keeps its name but identifies the Product/Backlog Root. A Linear /project/ URL points to a legacy Epic Project and fails with guidance to rerun hi ensure; it is never accepted as the default for a later write. Replace it with the selected Root Initiative URL. The settings-only migration preserves unrelated and unknown fields, and a second run with the accepted destination is idempotent.

Legacy settings can omit repositoryManager, requiredTools, or backlogProjectUrl. Reads classify an unambiguous migration as SafeSettingsUpgrade without writing. Missing, invalid, inaccessible, or contradictory evidence stays a typed error instead of being guessed. A repository without settings must run root hi init first.

The authority keeps three writer classes separate:

• operators own backlog, asset, repository-manager, and backlog-URL choices;
• the CLI derives required tools;
• accepted scaffold commands own CLI and baseline version pins.

hi ensure changes only operator choices plus their reconciled tools. It does not stamp managed versions or regenerate scaffold output.

Destination Authority

Scaffolded write-backlog guidance reads backlogProvider and backlogProjectUrl before provider materialization. Missing values, a legacy Linear Project URL, or an unproven Root stop with hi ensure guidance; the destination is not rediscovered or guessed.

hi ensure changes configuration only. hi tools ensure is a separate nested command that may install or repair the tools listed in settings.

Outcome

The repository has an explicit, reusable backlog destination and updated provider authority without regenerated scaffold or wiki output.