Planning gateway: every gate

Every task starts from one checked plan. The gates below hold an agent to that plan: no code before the plan passes, and no automation merge before the plan's proof is there. A bug or a chore needs only the short plan: one phase, one criterion.

There is no bypass. No setting turns a gate off. An urgent fix waits until its short plan is written and passes. A short plan takes minutes.

The plan file

Where: docs/plans/<TASK-KEY>.json in the task's repository. The key comes from the branch name: on feat/ABC-12-login the plan is docs/plans/ABC-12.json.
One plan per task. The plan for ABC-12 does not open the edits on a branch for ABC-13.
How to write it: the kit prompt .iKanban/prompts/feature-plan.md, the template .iKanban/templates/feature-plan-template.json, or the kit skill ikanban-feature-plan.
The check:
```
node .iKanban/hooks/plan-gate.js check docs/plans/ABC-12.json
```
It prints plan ok: … and exits 0, or it lists each problem with its fix and exits 1. ikanban plan check docs/plans/ABC-12.json is the same check. The rules it applies are in .iKanban/prompts/feature-plan.md, under Rules the check applies.

The gates

Gate	When	What it refuses	Where you see it	How to pass
Plan gate	before each edit or shell command of an agent on your laptop	an edit, or a shell command that can write	the agent's tool call is denied with iKanban plan gate: …	write the plan; the check says `plan ok`
Runner plan stage	before the first build of a task on the laptop runner	the build	the task's activity, and the Plan stage in Pipelines	the plan the runner writes passes the check; else fix the plan and send the task again
Deploy and merge gate	before an automation merges the task's PR	the merge	one note on the task, and Merge held with the reason in Pipelines	give each test and command criterion its evidence in the plan
Roadmap sync warning	each Roadmap sync of the plan	nothing: it warns	the sync's warnings, and the phase on iKAgent → Roadmap	add criteria to the phase in the plan file

Related: the Done gate. On Pro and Pro+, an open risk from the check critic's review before Done keeps the task from being marked Done. See Agentification.

Plan gate

The kit hook .iKanban/hooks/plan-gate.js runs before each tool call of Claude Code, Gemini CLI, Copilot CLI and Antigravity CLI. npx ikanban hooks install wires it.

It refuses an edit, and any shell command that is not a read, until the task's plan passes.
It never refuses reads (ls, cat, grep, rg, git status, git diff, git log and the plan check), writes in docs/plans/, and files outside the repository.
A branch with no task key, such as main, is refused. Make a task branch first: git switch -c feat/ABC-12-login.
The refusal says what to do: it names the plan file, each problem with its fix, and the check to run.
Copilot CLI runs a repository's hooks only after you trust the folder. It lets a call through when a hook takes longer than 20 seconds.

Runner plan stage

When a task runs on your laptop runner, the runner plans before it builds:

A fresh agent session writes docs/plans/<TASK-KEY>.json. A bug or a chore gets the short plan; any other task type gets the full plan. The session is told to write only that file, and it stops after 10 minutes.
The runner runs the plan check on the file, with its own copy of the checker (never a checker from the repository). It needs Node.js 18 or later on the laptop. The plan file must be a regular file inside the repository, not a link.
The plan passes: the build starts. It fails: the run ends before the build. The task's activity names each problem; fix the plan and send the task again.

The Plan stage shows in Pipelines before the agent's run (Pipelines is on Pro and Pro+). A follow-up writes no new plan, but its build is checked before a merge like the first one. A task sent again while it already has a pull request works on that PR's branch: when the plan there passes, the run uses it and writes none (the activity says this run works on the task's PR #12), so the plan checked and the plan built are the same file. If criteria change after the check, the held merge says the plan's criteria changed after the check. A Wiki run and a security scan get no plan stage. The plan stage comes to your laptop with the next desktop app release.

Deploy and merge gate

After the build, the runner checks the plan again with --merge: each criterion of kind test or command needs its evidence. Criteria proved on dev (browser, api) get their evidence after the deploy. The criteria themselves must be the ones checked before the build: the build may add evidence, but a changed check, how or expect holds the merge. The Plan stage then reads passed or held.

Whether this check gates the merge is the automation rule's own setting (Then → Merging the agent's pull request): Checks and plan pass (the default) waits for it; Checks pass merges on green checks alone, and the runner then skips this check; A person merges never merges.

With Checks and plan pass, an automation (the laptop runner or a GitHub run) merges a planned task's PR only after the runner's check passed. The task gets one note, for example: iKanban Automation holds the merge of PR #12: the task's plan does not pass yet: P1-C1: no evidence … It merges once the plan passes. With Pipelines, the Merge stage reads held with the same reason. Push the evidence to the pull request: at its new commit, your runner checks the plan again (no agent starts; the task's activity says Plan: re-checked PR #12), and the hold lifts when it passes. A planned run with no check after its build (a runner older than the plan stage) is held too: update the desktop app. Only the runner can report this check; a person or an agent cannot mark it passed.

Run the same checks by hand before a merge or a deploy:

Command	What it adds to the plan check
`… check <plan> --merge <PHASE>`	each `test` and `command` criterion of that phase has evidence
`… check <plan> --done`	every criterion has evidence, and every critic gap in the plan is closed or accepted
`… --task <KEY>` (with `--done` or `--merge`)	also the task's open critic gaps on iKanban

Roadmap sync warning

A Roadmap sync warns for each phase with no criteria: phase <key> has no criteria. The Roadmap shows No criteria: add them to the plan file on that phase. The warning blocks nothing.

Limits

The gates check that criteria exist and have evidence. They cannot judge whether a criterion is strong. The check critic does that.
A hook binds the agents it is wired into. An agent run outside the kit and the runner is not bound. A person can still edit code by hand, and can remove a hook from their own laptop.
The plan gate reads the command's text. It stops an agent that drifts into code without a plan. It does not stop a command built to hide what it writes. The runner's plan stage enforces the plan inside iKanban.
Reading command text has false alarms. A shell command that writes outside the repository can still be refused. Use the agent's edit tools for such files.
Release: the plan gate, npx ikanban hooks install that wires it, and ikanban plan check come with the next release of the desktop app and the ikanban CLI. The CLI on npm today (0.4.9) has no plan check; use the kit's node .iKanban/hooks/plan-gate.js check instead.