Scaffold Update

Root hi check is the read-only pre-work drift command. hi update previews or applies scaffold reconciliation from one compiled desired state, the observed repository, and the prior successful receipt.

Trigger

An operator or session-start hook runs hi check after setup. An operator runs hi update --check to preview, then hi update --write or hi update --yes after accepting remediation.

Actors

• Operator
• punks CLI
• Scaffold baseline

Steps

1. Read settings, .devpunks/scaffold-manifest.json, and prior successful ownership evidence.
2. Re-scan repository facts, resolve the active baseline and packs, and compile the desired files, package dependencies, structured keys, projections, and provenance.
3. Observe repository state without treating invalid data as missing.
4. Plan deterministic per-entry create, update, remove, skip, degradation, conflict, and failure outcomes. A divergent managed entry becomes a scoped conflict; unrelated user content stays outside the action.
5. hi check compares through a read-only stage without a writable temporary tree. It reports settings upgrades, executable drift, scaffold/baseline drift, and changelog summaries without changing settings, pins, manifests, or receipts.
6. hi update --check reports the reconciliation preview without applying it.
7. hi update --write and --yes execute independent safe actions even when another entry conflicts or fails. Every planned item receives a typed outcome.
8. Dependency actions refresh the detected Bun, pnpm, npm, Yarn Classic, or modern Yarn lockfile. A failed refresh restores the package manifest and recognized lockfiles and keeps the prior receipt so retry remains deterministic.
9. Update stages the wiki and other managed surfaces, preserves user-modified managed values, and persists the receipt last from captured successful outcomes plus truthful known omissions/degradations.
10. Report changed and stale files, manifests, baseline/pack/wiki drift, reconciliation status, planned actions, outcomes, and whether receipt persistence succeeded.

Outcome

Read-only checks do not update pins, files, or receipts. A write with only successful or skipped work returns succeeded. A write with both blocked and successful actions returns partial; a write with blocked work and no success returns failed. Partial and failed writes exit nonzero, keep conflicts and failures visible, and never claim those entries as applied.

--yes is the non-interactive apply flag and has the same reconciliation behavior as --write. Resolve only the reported conflict, then retry: completed state stays stable, unresolved entries remain planned, and successful ownership is not rewritten from observed user state.

Write-mode update uses the same best-effort required-tool bootstrap behavior as setup. Tool install failures print recovery context but do not block independent managed actions.

Update reports exact .cursor, .codex, .claude, .agents, and .opencode ignore patterns in root .gitignore as harness drift, then removes them when applying.