Hooks
Generated guardrails that keep repeated checks close to edits
Hooks keep routine feedback close to edits.
They catch formatting, linting, starter scope, and package-manager assumptions early, so the agent does not have to remember every hygiene step manually. They sit below the skill workflow: a hook can keep repeated checks moving, while requirements clarity, browser behavior, runtime evidence, docs ingest, and review judgment still belong to the relevant skills.
hi scaffold writes shared hook files under .agents/hooks/* and records managed output in .devpunks/scaffold-manifest.json. Hook behavior follows selected packs and detected repo facts.
Session-start scaffold hooks run hi check. The command is read-only: it detects CLI executable drift, scaffold baseline drift, managed-file drift, and pack drift, then summarizes changelog entries when available. If an operator accepts remediation, the hook guidance sends hi upgrade or normal hi update to a subagent before project work continues.
The manifest makes hook drift visible. Baseline changes can be refreshed through hi update. Stale ownership evidence heals silently when fixed hook bytes already match the verified baseline. A genuine edit is archived once and replaced; project-owned exceptions remain quiet.
Current Hook Boundaries
- Hook commands infer the target repo package manager from
packageManagerfirst, then lockfiles. - Pack-owned Oxlint rules are applied to nearest package/app configs during setup, creating
oxlint.config.tswith Ultracite presets where needed. - Missing lint dev dependencies are added to the owning package manifest while preserving existing versions.
- Oxfmt/Oxlint hooks are emitted only when scanned manifests declare Oxfmt or Python is detected.
- Generated hooks let Oxlint resolve the nearest config for the edited file.
- The automatic format hook requires a valid managed-files receipt in
.devpunks/scaffold-manifest.jsonand skips every recorded path. The manifest is the sole bootstrap exclusion because it cannot list and hash itself. - A missing, unreadable, malformed, or invalid receipt makes that hook invocation perform no formatter or linter mutation. With valid evidence, eligible unmanaged files keep their existing behavior.
hi checkandhi updatecompare managed bytes without running repository formatters. Manually invoked repository-wide formatting remains outside Harness and can create legitimate managed-file drift.- Generated lint configs extend
ultracite/oxlint/core; framework packs add Ultracite framework presets and explicit overlays only when needed.
Alignment Rule
When an agent adopts or replaces lint and format tooling, it must update the whole workflow together: package scripts, Turborepo task definitions, CI, editor/docs references, and hooks. Partial adoption creates contradictory gates.
hi update refreshes fixed managed hook files from the verified selected baseline. hi update --check previews without writing; combining it with --write or --yes is an error. If verified authority is unavailable, update fails safely. A successful apply leaves the next hi check --json clean.
Done Signal
Hook-related work is complete when generated hook files match selected packs, command assumptions match the repo package manager, and any lint or format tool migration has no stale entrypoints left behind.