# One-step Kanban CLI

The CLI runs one explicitly selected implementation or review dispatch through
the existing session. It never opens a Kanban panel or enables continuous
scheduling. A successful dispatch can leave the card awaiting review; exit 0
does not certify a finished game.

Use the project's Unity version (currently 2022.3.30f1). Save and close the project
before running it in batch mode. For automated tests, use a separate verification
project and fixture board. Do not point an isolated copy at the live board: tools
operate on the project opened by that Unity process.

From PowerShell:

```powershell
& .\Tools\Invoke-KanbanCli.ps1 `
  -ProjectPath 'C:\Dev\Unity\AIRuntime' `
  -BoardPath 'C:\Users\valtinh\Documents\AIRuntime\kanban\board.json' `
  -TaskId '<exact persisted card Id>' `
  -ResultPath 'C:\Dev\Unity\AIRuntime\Logs\cli-run-001.json' `
  -TimeoutSeconds 600
```

The board must exist, be paused, contain the requested ID exactly once, and have
no live dispatch claims. Agent activation, provider configuration, dependencies,
workflow rules, ownership and persistence checks remain in force. A blocked card
returns immediately rather than selecting another card or waiting for cooldowns.
Compilation/import can wait until the deadline. Existing output files are refused.

The underlying entry point is `AIRuntime.Editor.AIRuntimeKanbanCli.Run`, invoked
with `-batchmode -executeMethod` and these arguments:

- `-airuntimeBoard`: explicit board path.
- `-airuntimeTaskId`: exact card ID, not title.
- `-airuntimeResult`: new JSON output path.
- `-airuntimeTimeoutSeconds`: 1–86400 seconds, default 600.

Do not pass `-quit`. The runner waits for the completion callback and persisted
dispatch before it exits. The PowerShell wrapper additionally bounds startup and
native hangs, allowing 180 extra seconds by default (`StartupAllowanceSeconds`).
It refuses a project with a live recorded Editor process and keeps a separate
Unity log. It does not force `-nographics`, since rendering capabilities may need
graphics access.

| Exit | Outcome | Meaning |
| --- | --- | --- |
| 0 | Completed | Selected dispatch completed and its result was persisted. |
| 1 | Failed | Execution, persistence, reporting, or startup failed. |
| 2 | InvalidRequest | Invalid arguments, missing card, or board not paused. |
| 3 | Blocked | No dispatch started; inspect `Reason`. |
| 4 | TimedOut | Deadline exceeded. Managed timeout checkpoints and cancels active work. |
| 5 | Interrupted | Assembly reload interrupted the attempt; inspect its checkpoint before resuming. |

Reports contain board revision, task and dispatch identity, final task/review
state, blocker/error, UTC timestamps and exit code. They are published by atomic
rename to a new file, with an exclusive `.cli.lock` sidecar reserving the output.
Invalid invocations before reservation are
reported in the Unity log. The launcher writes a `.launcher.json` failure report
when Unity produces no valid matching terminal report or must be terminated.
That fallback explicitly does not confirm a checkpoint. Do not infer success
from process exit alone. After a native crash, use a new output path; a stale
reservation sidecar can remain.

Assembly reload checkpoints work and ends this invocation as interrupted; it
never automatically starts a second attempt. Interrupted and timed-out work may
have already produced artifacts. Inspect the board, execution memory and assets
before explicitly resuming. External tool effects are not transactionally undone.

## Recovering a contradictory completion kickback

For a paused board whose worker emitted `[PlanningKickback]` while explicitly
claiming that all acceptance criteria were met or no further work was needed,
the operator entry point is
`AIRuntime.Editor.AIRuntimeKanbanSession.RecoverCompletionKickbackForCommandLine`.
Set `AIRUNTIME_KANBAN_BOARD_PATH` and `AIRUNTIME_KANBAN_TASK_TITLE` to the exact
board and source card, and invoke with `-batchmode -quit -executeMethod` in the
owning project after closing its Editor.

This command creates a timestamped board backup, requires scheduler ownership
and no live dispatches, validates the complete saved child graph, and preserves
card IDs and execution memory. It promotes interrupted drafts only after graph
validation and restores implementation. Existing outputs go to fresh Review;
missing outputs go to implementation rework. It never marks the card Done or
enables continuous scheduling. Genuine ownership conflicts still block recovery.

When a planning commit reports omitted existing cards, restate every desired
card in the current attempt before committing. Reading history does not include
those cards in the authoritative snapshot; omitted cards cannot satisfy dependencies.

Prefab review captures current component properties, including Unity-decoded
Rigidbody constraint flags. Historical checkpoint claims cannot replace this
evidence. A PASS containing an explicit `FreezePositionX/Y/Z` or
`FreezeRotationX/Y/Z` boolean claim contradicted by every captured Rigidbody is
rejected as an evidence gap. This checks explicit claims; it is not a complete
physics or gameplay validator.
