Scaffold Manifest

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.

.devpunks/scaffold-manifest.json records detected repository facts, final packs, generated files, checksums, required tools, prompt specs, lint specs, and subagent specs from hi scaffold. .devpunks/settings.json records provider authority plus project-local cliVersion and baselineVersion pins.

The manifest and reconciliation receipt are evidence of the last successful managed application. They are not desired state. The CLI recompiles desired state from current semantic inputs, observes the repository separately, then reconciles those inputs with prior receipt evidence.

Responsibilities

• Record repo shape, detected technologies, selected packs, prompt specs, subagent specs, required tools, and generated files.
• Record managed files with hashes and kinds.
• Record baseline identity.
• Pair with .devpunks/settings.json so hi check can compare accepted CLI and baseline versions before work starts.
• Drive hi update observation and reconciliation without authorizing overwrite of divergent user state.
• Retain successful per-file, dependency, and structured-entry evidence plus truthful projection omissions/degradations.

Invariants

• hi check is read-only and does not change manifest, receipt, or settings pins.
• hi update reads prior evidence for ownership, but never treats it as the current desired tree.
• Conflicted, failed, or invalid entries do not advance receipt ownership. Independent successful entries do.
• Receipt persistence runs after independent actions. A rejected persistence operation does not roll back already successful unrelated actions; receiptPersisted: false means the on-disk receipt must be checked or repaired before relying on it.
• Managed file ownership requires exact content, file kind, and type-aware mode evidence. Package dependencies and structured configuration are owned per entry, not as whole-file replacement.
• The root-level legacy scaffold-manifest.json is outside the current update contract.
• Recorded finalPacks preserve the prior accepted selection. Write-mode desired packs augment that evidence with currently resolved default and detected packs.
• Write modes automatically adopt newly resolved default and detected packs into finalPacks. Optional-pack additions/removals, policy changes, and surface-shape changes remain explicit setup decisions.
• Missing managed files can be restored during update when they still belong to the recorded scaffold output.
• Stale receipt entries are removed only when the observed value still matches the prior successful evidence. Divergence is preserved as a scoped conflict.