AkurAI-Build

public
Latest change 30e6b8c347048d64c2c048dfd05a8ded219d37f6 - Host authenticated Git repositories over Smart HTTP with repo host/sync CLI by Ólafur Búi Ólafsson
# Automation policy

## Local authoritative automation

Use `node .kanban/bin/kanban.mjs`; do not move files manually. The CLI provides:

- validated creation and stage-specific transitions;
- Ready-definition, dependency, WIP, ownership, evidence, and approval gates;
- serialized claim/ownership;
- blocked-state tracking;
- durable handoff creation/acceptance;
- structure and dependency validation;
- flow metrics;
- append-only JSONL events;
- a fail-fast board-command lock.

No dependency install, network call, shell interpolation, secret, or database is
required. Individual file replacement is atomic and all board commands are
serialized, but card moves and event appends are not one filesystem transaction.
After interruption, inspect the lock and run `validate`. Validation reconciles
card status against transition events and inventories every pending/accepted
handoff plus its creation/acceptance events; it cannot make several files one
transaction. The CLI does not edit source code or perform git/release actions.

## Pi automation

Use Pi's native `LoopCreate` only when a user explicitly asks for recurring or
backlog automation. Never create `while`, `sleep`, or shell polling loops.
Recommended worker prompt:

```text
From the project root, validate .kanban, select one pullable Ready task, claim
it with the current agent name, follow the card and project instructions, leave
exact evidence, and move it only through satisfied gates. If no task is
pullable, report once and stop/delete the loop. Never merge, deploy, publish,
or force a transition without explicit authorization.
```

Set `maxFires` (20–50) and stop the loop when no pullable task remains. A
file-based board has no native `tasks:created` event, so use a bounded cron only
when ongoing polling is explicitly requested.

## CI

`.github/workflows/kanban.yml` is the active GitHub Actions workflow. It runs
the dependency-free validator and tests for relevant pull requests and pushes
to `main`. `automation/validate-kanban.yml` is its reviewed source template;
keep both files synchronized when changing CI.

## GitHub Projects integration

Prefer GitHub Projects built-in workflows for issue-close/PR-merge -> Done,
auto-add, and archive. Use repository Actions/GraphQL only when the local card
and GitHub item need synchronization. Organization Projects should authenticate
with a least-privilege GitHub App; never commit tokens or place secrets in card
metadata. Define one direction of authority and idempotency before enabling
sync to avoid status loops.

Suggested mapping:

| Local | GitHub status |
| --- | --- |
| Inbox, Triage, Discovery | Backlog |
| Ready | Ready |
| In Progress | In Progress |
| Review | In Review |
| Verification | Testing |
| Release Ready | Ready to Release |
| Done | Done |

Do not enable remote automation until repository identity, project number,
field IDs, authentication, conflict policy, and rollback are explicitly known.

## Recovery

If a command crashes, run `validate`. A remaining `state/write.lock` must be
inspected before manual removal; confirm its PID is no longer active and no
writer is running. Do not automatically delete locks based only on age.