Use when asked to auto-merge, merge-when-green, land-on-pass, or "merge once CI/reviews pass" for a pull request, or when subscribed to a PR's activity and a check/review event arrives that could unblock a merge. Enforces a fail-closed merge gate: a PR merges ONLY when every CI check completed successfully AND reviews pass (no changes requested, required approvals met) AND the PR is mergeable and not a draft. Any check still pending, missing, or failed — or any blocking/absent-but-required review — means HOLD, never merge. Security- sensitive diffs always require an explicit human approval regardless of CI. Pairs with the autonomous build routine (docs/AUTONOMOUS-ROUTINE.md): the routine never merges directly — landing to main goes through this gate.
Use proactively when shipping any change in this self-hosted V1 vault — after a commit lands, before declaring "done", or when the user says "ship", "release", "deploy", "is it working?". Enforces verify-ledger-first shipping: run the `verify:*` gate(s) for the changed surface (and the full `npm run verify` chain before declaring done) until each prints `VERDICT: GO` / exits 0, then smoke-test the changed path against the actual process the user runs (stdio MCP, REST+portal on :8787, public publish on :8788), update the living docs, and emit a [✓]/[—] ledger. Refuses the CLAUDE.md §10 anti-pattern ("might have worked"). Includes V1 change-class smoke recipes (foundation/ crypto, MCP tools, REST+portal, ingest/blob, embed/pipeline, migrations, publish) and flags that distribution (npm/Tauri) and remote (Tunnel) are unshipped — there is nothing to push to yet.
Use proactively when ending a working session that produced commits or decisions, before context compaction, when a phase of multi-phase work completes, when the user signals end-of-session ("compact", "wrap up", "we'll continue later", "next session", "let's stop here", "handoff"), or when work is being parked/paused. Enforces the discipline of writing a structured handoff doc that lets a fresh session pick up cleanly with no re-discovery. The handoff is the artifact that proves the work is recoverable across sessions; without one, every compact loses unrecoverable context. Pairs with /sweep-first-design (verifies a design was written), /deploy-and-verify (verifies deploys are documented), and /pre-deletion-caller-audit (verifies the audit table persists).
Use proactively after any change that alters what the system IS or what the plan SAYS — a new/removed module, tool, endpoint, port, data-flow, schema migration, decision, or a shift in scope/sequence. Before declaring a unit done, update the three living docs so they never drift from reality: the PLAN (docs/V1-BUILD-SPEC.md status + verification table), the ARCHITECTURE (docs/ARCHITECTURE.md — the as-built system), and the build log (docs/V1-BUILD-HANDOFF-*.md). Docs describe what is ACTUALLY built, with file-path evidence, distinguishing built from planned — never aspirational. Pairs with handoff-discipline (session-end recap) and deploy-and-verify (verified state). Refuses "I'll document it later".
Use proactively when deleting or replacing existing code, schema, or infrastructure in this codebase — a function, module, file, env var, config flag, D1 table or column, endpoint, Worker route, MCP tool, or package. Including renames (a rename is a delete-plus-add). Enforces the audit-and-verify discipline: inventory every caller, classify each (migrated / not-migrated / dead), prove migration with concrete evidence (tests + audit data + smoke), define falsifiable decision criteria BEFORE the deletion lands, run the pre-flight gate, then execute. Refuses "soft delete" comments and grep-only audits. Required for Phase N "delete the old path" work in any multi-phase refactor.
Use proactively before designing or implementing any structural change in this codebase — picking up a handoff doc, planning Phase N of a multi-phase refactor, designing a new module that touches shared abstractions (egress, encryption, channel registry, scheduling, lanes, MCP tools, send-handler), or about to write a design doc. Enforces the sweep-before-design discipline: every load-bearing assumption must be inventoried, verified against live code with file:line citations, and addressed before the design is locked. Pivots when sweeps contradict the plan. Mandatory for work that will produce code in packages/, migrations/, or affect cross-process boundaries.