# Chunk Autopilot

Chunk Autopilot is the canonical full-show lifecycle for approved work packages.
It lets Orchestrator run an approved requirements -> planning -> work package ->
chunk queue continuously through Developer, QA, completion, archive, commit, and
next-chunk continuation while stopping only at configured stop milestones, true
blockers, retry limits, unsafe state, or final work-package review.

Chunk Autopilot does not invent product/security decisions, merge, release, or
bypass required human approvals. Human questions are pauses, not terminal stops:
after a valid shell or Telegram answer is recorded, Orchestrator continues the
same lifecycle unless the answer is a denial/stop or a stop condition applies.

## Preconditions

Chunk Autopilot may run only when all of these are true:

- Requirements are approved, or the human provided an explicit approved scope for a non-product workflow/tooling package.
- Chunk Planner produced an ordered work package and chunk queue.
- Orchestrator reviewed the chunk plan and requested revisions if needed.
- Human approved the final work package/chunk plan.
- Planned implementation chunks exist as backlog/planning artifacts before
  activation. Autonomous execution does not authorize unmanaged active chunks
  created directly from chat.
- The work package defines `Chunk Autopilot: enabled`.
- The work package defines stop milestones, or explicitly says `Stop Milestones: none`.
- The git worktree is clean or contains only work that belongs to the active approved chunk.

If any precondition is missing, Orchestrator stops and asks for the missing approval, plan revision, or cleanup.

## Human Approval Points

Human approval is required for:

- requirements approval.
- final work package and chunk-plan approval.
- optional stop milestone list by chunk number or milestone name.
- product, security, auth, data, destructive, production, or credential decisions.
- final human review before merge or release.

If no stop milestones are provided after work-package approval, Chunk Autopilot uses no intermediate stop points. The end of the approved chunk queue is always a stop point.

## Full-Show Lifecycle

The Orchestrator owns the full lifecycle:

1. Requirements Review returns `PASS`.
2. Human approves requirements when required.
3. Orchestrator runs Chunk Planner.
4. Orchestrator reviews the plan and asks Chunk Planner for revisions until the
   plan is good enough or a stop condition applies.
5. Orchestrator creates or updates the work package and approved chunk queue.
6. If `Chunk Autopilot: enabled`, Orchestrator starts queue execution.
7. For each approved chunk:
   - activate the next queued chunk.
   - route to Developer.
   - run validation and `workflow-state --ready-for-qa`.
   - route to QA.
   - if QA returns `PASS`, run `workflow-state --ready-to-complete`.
   - request/consume required completion/archive approval.
   - complete/archive the chunk.
   - safely stage and commit approved files when the package policy allows it.
   - continue to the next approved chunk unless a stop condition applies.
   - if QA returns `BLOCKED` and retry-safe/fixable, route a focused fix back
     to Developer.
   - if QA returns decision/scope/security/retry-limit blockers, ask the human,
     wait, and continue only after a valid answer allows continuation.
8. After all chunks complete, Orchestrator creates or updates the final report
   and stops for final human work-package review.
9. Orchestrator archives the completed work package only after final approval.

## Planning And Backlog Discipline

Autonomous continuation is execution authority inside an approved queue; it is
not permission to invent new implementation chunks outside planning artifacts.
Every autonomous multi-chunk package must have Chunk Planner output, a work
package or equivalent approved queue, and backlog/planning chunk artifacts before
the first chunk is activated.

Follow-up work found during an autonomous run must be recorded in a chunk,
work-package, or governance artifact. If the follow-up is urgent and must be
handled before normal planning can continue, first decide whether it fits the
current active chunk's goal, scope, out-of-scope boundaries, acceptance
criteria, and validation. If it fits, update the active chunk evidence and
continue. If it does not fit, create an emergency backlog chunk with the reason,
scope, out-of-scope items, acceptance criteria, validation, and stop conditions
before activation. Do not bypass backlog merely because the operator authorized
autonomous continuation.

## Operator Context Capture

During autonomous execution, operationally relevant operator prompts, assistant
inline answers, and assistant work updates should be recorded through the Runtime
message stream at the boundary that receives or emits them. Use
`node ai/runtime/dist/cli.js runtime message-record` when the boundary is
repository-controlled.

This capture is a context window for the operator and consultant review. It is
not a lifecycle transition, approval, dispatcher command, service-health fact,
or validation result. Chunk Autopilot must continue to use canonical lifecycle,
approval, validation, and Runtime Health sources for authority decisions.

If the active runner or platform does not expose a deterministic producer hook,
the Orchestrator records the gap in carry-forward debt and continues using the
available canonical state sources. Do not treat platform chat memory as a
repo-owned audit log.

## Operator Questions And Registered Actions

Canonical operator question rules live in `ai/standards/operator-questions.md`.
Registered local/dev action rules live in
`ai/standards/trusted-operator-daemon.md`. Chunk Autopilot must apply those
standards for every interactive pause and approval-bearing local/dev action.

Use the canonical Q&A helper for human questions:

```sh
ai/tools/operator-questions/ask.sh --type yes-no --kind <kind> --question "<question>"
```

Use the trusted daemon for registered local/dev actions:

```sh
ai/tools/operator-daemon/request-action.sh --action git_add_approved --files "<reviewed files>"
ai/tools/operator-daemon/request-action.sh --action git_commit --message "<message>"
ai/tools/operator-daemon/wait-result.sh <request-id>
```

Local console and Telegram answers are alternative inputs to the same question.
Either channel may answer first; the first valid answer wins and late answers
are stale. Questions wait indefinitely by default.

For registered daemon actions, do not request Codex platform escalation. For
unregistered actions only, Q&A may record operator intent before a Codex
platform prompt, but Telegram/local scripts cannot satisfy the Codex platform UI.
Do not use `ai/tools/operator-daemon/run-once.sh` as an autopilot shortcut; it
is daemon-internal/fixture tooling and requires explicit operator approval for
any direct diagnostic use.

```sh
ai/commands/platform-escalation-preflight.sh --target unregistered-action --platform-action "<exact unregistered command/action>"
```

Legacy Telegram checkpoint details are in
`ai/standards/remote-operator-checkpoints.md` for compatibility only.

## Default Automation Policy

For an approved work package with Chunk Autopilot enabled:

- Auto-run Developer: yes, inside approved chunk scope.
- Auto-run QA: yes, after `ai/commands/workflow-state.sh --ready-for-qa` passes.
- Auto-run focused Developer retry: yes, only when QA classifies the blocker as retry-safe/fixable under `ai/standards/orchestrator-retry-policy.md`.
- Auto-complete/archive: yes, after QA PASS and `ai/commands/workflow-state.sh --ready-to-complete` passes.
- Auto-commit: yes, after safe staging and a meaningful commit message.
- Auto-merge/release: no.

Automation is scoped to the approved chunk queue. Autopilot must not pull in unrelated cleanup, unplanned chunks, or app/package changes outside the work-package scope.

## Chunk Loop

For each chunk in the approved queue:

1. Activate the next backlog chunk.
2. Run Developer implementation.
3. Run `ai/commands/workflow-state.sh --ready-for-qa`.
4. Run QA.
5. If QA is `BLOCKED`, classify and process the blocker.
6. If QA is `PASS`, run `ai/commands/workflow-state.sh --ready-to-complete`.
7. Run `ai/commands/workflow-summary.sh`.
8. Ask/consume the completion/archive approval through the operator Q&A layer
   or trusted daemon when the action is registered.
9. Complete/archive the chunk.
10. Stage only approved safe files through
    `ai/tools/operator-daemon/request-action.sh --action git_add_approved`.
11. Commit through `ai/tools/operator-daemon/request-action.sh --action git_commit`
    with a concise, meaningful, sentence-case commit message.
    Wait for each daemon result with `ai/tools/operator-daemon/wait-result.sh`.
    If no trusted daemon result arrives or trusted Git runtime is unavailable,
    stop for operator daemon startup/fix; do not ask for Codex platform
    escalation and do not run `run-once.sh` directly.
12. Continue to the next chunk unless a stop milestone or stop condition applies.

Completing a chunk, receiving QA `PASS`, generating a prompt handoff, printing
`workflow-summary.sh`, receiving a `yes` approval, archiving one chunk, or seeing
another backlog chunk is not itself a stop condition. Under approved Chunk
Autopilot these are continuation points.

## QA BLOCKED Handling

QA sanity and blocker findings must be classified before Orchestrator continues:

- `blocker`: stop unless QA also classifies it as retry-safe/fixable.
- `retry-safe Developer fix`: run a focused Developer retry with `ai/commands/prompt-synthesize.sh dev-fix`.
- `requirements/product decision needed`: stop for human or requirements clarification.
- `scope-change required`: stop for human approval and a revised/new chunk.
- `follow-up recommendation`: record in summary; do not block if risk is accepted and current scope remains satisfied.
- `not applicable / accepted risk`: record the non-blocking rationale.

QA must return `BLOCKED` when an adversarial sanity finding is a material blocker, even if formal validation passed.

## Auto-Commit Safety

Auto-commit is allowed only when:

- QA verdict is PASS.
- completion readiness passes.
- git status contains only approved files for the active chunk.
- `.env`, `.tmp`, secrets, generated local state, smoke-user artifacts, dependency folders, and unrelated files are absent from staging.
- commit message is meaningful, concise, sentence-case, and derived from the chunk/work-package context.
- helper state and chunk notes agree.
- a `git-commit` approval record exists when human approval is required.

If the suggested commit message is generic, such as `Commit approved changes`, `Update files`, or `Save changes`, Orchestrator stops and asks for a better message.

## Stop Conditions

Stop Chunk Autopilot and require human intervention when any of these occurs:

- requirements ambiguity.
- chunk plan ambiguity.
- product/security/auth/data decision needed.
- scope expansion required.
- QA blocker is not retry-safe.
- retry limit reached.
- validation failure is not resolved.
- runtime smoke required but unavailable.
- destructive data risk.
- production credential risk.
- unexpected git state.
- helper state contradiction.
- weak or generic commit message.
- `.env`, `.tmp`, secrets, local state, or unrelated files would be staged.
- configured stop milestone reached.
- final work-package review boundary or end of approved queue reached.
- required approval is denied.
- command/tool failure cannot be retried safely.
- unsafe or ambiguous active workflow state.

Do not stop merely because:

- a chunk completed.
- commit approval was requested and answered `yes`.
- QA returned `PASS`.
- a prompt handoff was generated.
- `workflow-summary.sh` was printed.
- a human question was asked and later answered.
- one chunk was archived and the next approved backlog chunk exists.

## Helper And Live-Resume Limitations

`workflow-state.sh`, `orchestrator-next.sh`, `workflow-summary.sh`,
`prompt-synthesize.sh`, and Telegram helpers describe the next safe transition.
They do not by themselves keep a Codex process alive or submit prompts unless a
registered bridge/tmux helper explicitly does so. Until a dedicated live
autopilot runner exists, helper output must be honest: it may describe the
post-approval continuation state, but must not claim that printing a summary or
creating a checkpoint automatically resumes Codex.

## Handoff And Summary Expectations

For an approved work package, the handoff should point to the Orchestrator Autopilot run rather than manual per-chunk commands.

Summaries for autopilot runs should include:

- chunks completed.
- commits made.
- chunks remaining.
- QA results.
- validation results.
- cleanup results.
- stop reason.
- next recommended action.
- whether final human review is required.

Final human review before merge/release is always required unless a later standard explicitly grants otherwise.