fix(agents): make integration checks explicit and recovery scoped

.codex/skills/hack-cli/SKILL.md

@@ -12,11 +12,11 @@ Use `hack` as the primary interface for local-first development.
 
 ## Integration freshness
 
-- These instructions were generated by hack CLI v3.5.2; treat cached rules from another version as potentially stale.
-- At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
-- If anything is stale or missing, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
-- Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `994ef1552d14` (version alone is not a freshness guarantee).
+- These instructions were generated by hack CLI v4.0.2; treat cached rules from another version as potentially stale.
+- Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
+- Repair only the affected integration and scope covered by the request, using the matching `hack setup` command. Missing optional integrations do not require installation. Use `--all-scopes` only for an explicitly requested full refresh.
+- Edit Hack guidance at its generator source and render the affected targets. After a refresh, read the updated guidance; restart only if the client cannot reload the changed hooks or skills. Existing authorization for the same action and scope is sufficient.
+- Content revision: `4f99d4a27609` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -192,20 +192,20 @@ Use `hack` as the primary interface for local-first development.
 
 - Ordinary Hack commands, `hack update`, and `hack doctor --fix` may audit freshness but never render, repair, remove, or otherwise mutate agent integration files.
 - Use `hack setup sync` only when explicitly choosing to manage project or user docs, skills, rules, hooks, or MCP config.
-- Read-only freshness checks are available through `hack setup sync --all-scopes --check`, `hack doctor`, and `hack agent prime`.
+- Read-only freshness checks are available through targeted `hack setup` checks and `hack doctor`. Primer output is guidance; stale-integration notices do not authorize repairs or block unrelated work.
 - Refresh project + user integrations: `hack setup sync --all-scopes`
 - Explicit sync removes recognized Hack-owned artifacts from retired integrations and preserves unrecognized files for manual review.
 - Audit integration state only: `hack setup sync --all-scopes --check`
 - Remove generated integration artifacts: `hack setup sync --all-scopes --remove`
-- After upgrading CLI: `hack update` then `hack setup sync --all-scopes`
+- CLI upgrades do not authorize integration changes. After an upgrade, refresh affected integrations only when requested or needed for the authorized task.
 - When changing hack itself: interface or behavior changes must update docs/ in the same change (regenerate the CLI reference with `bun run docs:cli-reference`).
 
 ## Agent setup (CLI-first)
 
 - Cursor rules: `hack setup cursor`
 - Claude hooks: `hack setup claude`
 - Codex skill: `hack setup codex`
-- Refresh all local agent integrations: `hack setup sync --all-scopes`
+- Explicit full integration refresh: `hack setup sync --all-scopes`
 - Agent-assisted onboarding: `hack init --with claude|codex|both` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
 - Init patterns: `hack agent patterns`

.cursor/rules/hack.mdc

@@ -7,11 +7,11 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 ## Integration freshness
 
-- These instructions were generated by hack CLI v3.5.2; treat cached rules from another version as potentially stale.
-- At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
-- If anything is stale or missing, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
-- Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `994ef1552d14` (version alone is not a freshness guarantee).
+- These instructions were generated by hack CLI v4.0.2; treat cached rules from another version as potentially stale.
+- Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
+- Repair only the affected integration and scope covered by the request, using the matching `hack setup` command. Missing optional integrations do not require installation. Use `--all-scopes` only for an explicitly requested full refresh.
+- Edit Hack guidance at its generator source and render the affected targets. After a refresh, read the updated guidance; restart only if the client cannot reload the changed hooks or skills. Existing authorization for the same action and scope is sufficient.
+- Content revision: `4f99d4a27609` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -93,12 +93,12 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 - Ordinary Hack commands, `hack update`, and `hack doctor --fix` may audit freshness but never render, repair, remove, or otherwise mutate agent integration files.
 - Use `hack setup sync` only when explicitly choosing to manage project or user docs, skills, rules, hooks, or MCP config.
-- Read-only freshness checks are available through `hack setup sync --all-scopes --check`, `hack doctor`, and `hack agent prime`.
+- Read-only freshness checks are available through targeted `hack setup` checks and `hack doctor`. Primer output is guidance; stale-integration notices do not authorize repairs or block unrelated work.
 - Refresh project + user integrations: `hack setup sync --all-scopes`
 - Explicit sync removes recognized Hack-owned artifacts from retired integrations and preserves unrecognized files for manual review.
 - Audit integration state only: `hack setup sync --all-scopes --check`
 - Remove generated integration artifacts: `hack setup sync --all-scopes --remove`
-- After upgrading CLI: `hack update` then `hack setup sync --all-scopes`
+- CLI upgrades do not authorize integration changes. After an upgrade, refresh affected integrations only when requested or needed for the authorized task.
 - When changing hack itself: interface or behavior changes must update docs/ in the same change (regenerate the CLI reference with `bun run docs:cli-reference`).
 
 # END HACK INTEGRATION

AGENTS.md

@@ -57,7 +57,7 @@ Never use any types and always default to leveraging generics and smart types to
 
 - Docs currency is non-negotiable: ANY interface or behavior change (commands, flags, config keys, file layouts, env vars, defaults) must update the affected docs/ pages in the same patch — no matter what.
 - The CLI reference is generated: after changing the CLI surface, run `bun run docs:cli-reference` and commit `docs/reference/cli.md` (a drift test fails otherwise).
-- Agent-facing behavior phrasing lives in `src/agents/instruction-source.ts`; update it (not the generated surfaces) and run `hack setup sync --all-scopes`.
+- Agent-facing behavior phrasing lives in `src/agents/instruction-source.ts`; update it and render the affected targets. Use scoped setup commands; a global refresh requires authorization for that scope.
 - If a change affects `hack run`, `hack exec`, env resolution, runtime-state reconciliation, or lifecycle shell/process semantics, the patch must include both targeted tests and matching docs updates.
 - For env-sensitive command changes, verify the requested env, effective env, cached runtime-state env, and target-service-running matrix instead of a single happy path.
 - For lifecycle changes, verify `sh -c` semantics, process-group cleanup, stale pane/process metadata reconciliation, and interactive stdin behavior.
@@ -70,15 +70,11 @@ Never use any types and always default to leveraging generics and smart types to
 - Before adding new branch-heavy logic there, prefer extracting a small helper with a narrow contract and direct tests.
 - Do not grow top-level command handlers when the real change is a decision table, state transition, or reusable readiness check.
 
-## Landing the Plane (Session Completion)
-**When ending a work session**, you MUST complete ALL steps below.
-
-**MANDATORY WORKFLOW:**
-1. **File tickets for remaining work** - Create tickets for anything that needs follow-up
-2. **Run quality gates** (if code changed) - Tests, linters, builds
-3. **Update issue status** - Close finished work, update in-progress items
-4. **Hand off** - Provide context for next session
+## Session Completion
 
+Run the relevant quality gates and report the verified result and remaining work. Update tickets
+only when tracker changes are authorized; otherwise leave a concrete follow-up in the handoff.
+Do not create tickets or handoff artifacts when there is no actionable remaining work.
 
 # Ultracite Code Standards
 
@@ -210,11 +206,11 @@ Most formatting and common issues are automatically fixed by Biome. Run `bun x u
 Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
 
 Integration freshness:
-- These instructions were generated by hack CLI v3.5.2; treat cached rules from another version as potentially stale.
-- At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
-- If anything is stale or missing, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
-- Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `994ef1552d14` (version alone is not a freshness guarantee).
+- These instructions were generated by hack CLI v4.0.2; treat cached rules from another version as potentially stale.
+- Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
+- Repair only the affected integration and scope covered by the request, using the matching `hack setup` command. Missing optional integrations do not require installation. Use `--all-scopes` only for an explicitly requested full refresh.
+- Edit Hack guidance at its generator source and render the affected targets. After a refresh, read the updated guidance; restart only if the client cannot reload the changed hooks or skills. Existing authorization for the same action and scope is sufficient.
+- Content revision: `4f99d4a27609` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -368,19 +364,19 @@ Docker compose notes:
 Agent integration maintenance:
 - Ordinary Hack commands, `hack update`, and `hack doctor --fix` may audit freshness but never render, repair, remove, or otherwise mutate agent integration files.
 - Use `hack setup sync` only when explicitly choosing to manage project or user docs, skills, rules, hooks, or MCP config.
-- Read-only freshness checks are available through `hack setup sync --all-scopes --check`, `hack doctor`, and `hack agent prime`.
+- Read-only freshness checks are available through targeted `hack setup` checks and `hack doctor`. Primer output is guidance; stale-integration notices do not authorize repairs or block unrelated work.
 - Refresh project + user integrations: `hack setup sync --all-scopes`
 - Explicit sync removes recognized Hack-owned artifacts from retired integrations and preserves unrecognized files for manual review.
 - Audit integration state only: `hack setup sync --all-scopes --check`
 - Remove generated integration artifacts: `hack setup sync --all-scopes --remove`
-- After upgrading CLI: `hack update` then `hack setup sync --all-scopes`
+- CLI upgrades do not authorize integration changes. After an upgrade, refresh affected integrations only when requested or needed for the authorized task.
 - When changing hack itself: interface or behavior changes must update docs/ in the same change (regenerate the CLI reference with `bun run docs:cli-reference`).
 
 Agent setup (CLI-first):
 - Cursor rules: `hack setup cursor`
 - Claude hooks: `hack setup claude`
 - Codex skill: `hack setup codex`
-- Refresh all local agent integrations: `hack setup sync --all-scopes`
+- Explicit full integration refresh: `hack setup sync --all-scopes`
 - Agent-assisted onboarding: `hack init --with claude|codex|both` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
 - Init patterns: `hack agent patterns`

CLAUDE.md

@@ -80,11 +80,11 @@ This project uses Obsidian for project context, specs, research, and progress tr
 Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
 
 Integration freshness:
-- These instructions were generated by hack CLI v3.5.2; treat cached rules from another version as potentially stale.
-- At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
-- If anything is stale or missing, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
-- Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `994ef1552d14` (version alone is not a freshness guarantee).
+- These instructions were generated by hack CLI v4.0.2; treat cached rules from another version as potentially stale.
+- Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
+- Repair only the affected integration and scope covered by the request, using the matching `hack setup` command. Missing optional integrations do not require installation. Use `--all-scopes` only for an explicitly requested full refresh.
+- Edit Hack guidance at its generator source and render the affected targets. After a refresh, read the updated guidance; restart only if the client cannot reload the changed hooks or skills. Existing authorization for the same action and scope is sufficient.
+- Content revision: `4f99d4a27609` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -238,19 +238,19 @@ Docker compose notes:
 Agent integration maintenance:
 - Ordinary Hack commands, `hack update`, and `hack doctor --fix` may audit freshness but never render, repair, remove, or otherwise mutate agent integration files.
 - Use `hack setup sync` only when explicitly choosing to manage project or user docs, skills, rules, hooks, or MCP config.
-- Read-only freshness checks are available through `hack setup sync --all-scopes --check`, `hack doctor`, and `hack agent prime`.
+- Read-only freshness checks are available through targeted `hack setup` checks and `hack doctor`. Primer output is guidance; stale-integration notices do not authorize repairs or block unrelated work.
 - Refresh project + user integrations: `hack setup sync --all-scopes`
 - Explicit sync removes recognized Hack-owned artifacts from retired integrations and preserves unrecognized files for manual review.
 - Audit integration state only: `hack setup sync --all-scopes --check`
 - Remove generated integration artifacts: `hack setup sync --all-scopes --remove`
-- After upgrading CLI: `hack update` then `hack setup sync --all-scopes`
+- CLI upgrades do not authorize integration changes. After an upgrade, refresh affected integrations only when requested or needed for the authorized task.
 - When changing hack itself: interface or behavior changes must update docs/ in the same change (regenerate the CLI reference with `bun run docs:cli-reference`).
 
 Agent setup (CLI-first):
 - Cursor rules: `hack setup cursor`
 - Claude hooks: `hack setup claude`
 - Codex skill: `hack setup codex`
-- Refresh all local agent integrations: `hack setup sync --all-scopes`
+- Explicit full integration refresh: `hack setup sync --all-scopes`
 - Agent-assisted onboarding: `hack init --with claude|codex|both` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
 - Init patterns: `hack agent patterns`

docs/cli.md

@@ -58,11 +58,14 @@ See [Beta workflows](beta.md) for guides on this surface.
 - `NO_COLOR` (or `HACK_NO_COLOR`) disables colored/decorated output.
 
 Generated agent docs, Cursor rules, Codex skills, and the shared `~/.ai/skills/hack-cli` skill carry
-the Hack CLI version that generated them. Audit both project and global surfaces with
-`hack setup sync --all-scopes --check`; repair them with the explicit
-`hack setup sync --all-scopes`, then reload the agent session so it stops using cached guidance.
-Ordinary commands, `hack update`, and `hack doctor --fix` may audit freshness but never render,
-repair, remove, or otherwise mutate these files.
+the Hack CLI version that generated them. Plain `hack agent prime` prints current guidance without
+an integration scan. Use `hack agent prime --check` for an explicit project/global inventory or a
+targeted `hack setup ... --check` when diagnosing drift. Missing optional integrations do not
+require installation. Repair only affected targets within the authorized scope; use
+`hack setup sync --all-scopes` for an explicitly requested full refresh. Read updated guidance after
+repair; restart only if the client cannot reload changed hooks or skills.
+Ordinary commands, `hack update`, and `hack doctor --fix` never render, repair, remove, or otherwise
+mutate integration files. CLI upgrades do not trigger integration updates.
 
 ## First-run path
 

docs/integrations.md

@@ -27,10 +27,16 @@ Recommended replacements:
 Hack maintains project instructions plus global Cursor, Claude, Codex, and shared `~/.ai/skills`
 surfaces. Generated guidance identifies the CLI version that rendered it.
 
-- Audit without writing: `hack setup sync --all-scopes --check`
-- Repair project and global integrations: `hack setup sync --all-scopes`
-- After repair: reload the agent session so cached rules are discarded
-
-Ordinary commands, `hack update`, and `hack doctor --fix` do not inspect or modify these surfaces.
-`hack agent prime` performs a read-only audit at session start and prints a warning before any Hack
-operating guidance.
+Run checks when Hack is relevant and there is evidence of drift; there is no mandatory startup audit.
+Plain `hack agent prime`, including installed SessionStart/PreCompact hooks, prints the current
+primer without scanning project or global integrations. Use `hack agent prime --check` for an
+explicit read-only inventory, or a targeted `hack setup ... --check` for per-artifact detail.
+Outside a Hack project, `hack agent prime --check` inventories global integrations only. Doctor
+classifies inventory commands as follow-up investigation and keeps scoped repair guidance separate.
+Inventory findings do not block unrelated work, and missing optional integrations need not be installed.
+
+Ordinary commands, `hack update`, and `hack doctor --fix` never modify these surfaces. Doctor may
+report freshness findings. Repair only the affected integration and scope covered by the request;
+`hack setup sync --all-scopes` remains available for an explicitly requested full refresh.
+Existing authorization for that action and scope is sufficient. After repair, read the updated
+guidance; restart only if the client cannot reload changed hooks or skills.