# Chunk Lifecycle Chunks are persistent task files that let AI work move through a predictable lifecycle without repeating prompt boilerplate. For large or unclear work, create and approve requirements before creating implementation chunks. Requirements live under `ai/requirements` and follow `ai/requirements/README.md` plus `ai/standards/requirements.md`. Artifact filenames follow `ai/standards/artifact-naming.md`. ## Lifecycle Folders - `ai/chunks/drafts`: rough prompts or incomplete chunk ideas. - `ai/chunks/backlog`: reviewed chunks that are ready to schedule. - `ai/chunks/active`: exactly one chunk per active implementation thread. - `ai/chunks/completed`: immutable history of completed chunks. ## Naming Convention Use `chunk-000001-slug.md`. See `ai/standards/artifact-naming.md` for ID width, slug rules, lifecycle folders, and reference-update expectations. ## Metadata Convention Every chunk file should start with this metadata block: ```md --- Status: Draft | Backlog | Active | Completed Owner Role: Orchestrator | Developer | QA Created: YYYY-MM-DDTHH:mm:ss.sssZ Completed: Depends On: Validation: --- ``` Metadata fields: - `Status`: current lifecycle state. - `Owner Role`: role expected to execute or review the chunk. - `Created`: UTC ISO-8601 timestamp when the chunk file was created. - `Completed`: UTC ISO-8601 completion timestamp, empty until done. - `Depends On`: chunk ids or external prerequisites. - `Validation`: required validation evidence. Prefer Runtime CLI/API profile commands such as `node ai/runtime/dist/cli.js validate --tier full`; shell validation wrappers are compatibility-only unless explicitly scoped. ## Execution Workflow 1. For rough or broad ideas, run requirements intake and review first. 2. Use chunk planning to turn approved requirements into draft chunks. 3. Create a draft from a pasted prompt in `ai/chunks/drafts`. 4. Normalize it using `ai/tasks/feature-template.md` or `ai/tasks/qa-review-template.md`. 5. Move it to `ai/chunks/backlog` when the goal, scope, out-of-scope items, and validation are clear. 6. Move it to `ai/chunks/active` when work begins and set `Status: Active`. 7. Execute with the relevant role file from `ai/roles`. 8. Run the validation listed in the chunk. 9. Summarize changed files, validation results, `git status`, and `git diff --stat`. ## Planning And Backlog Discipline Autonomous execution does not remove the artifact path. Multi-chunk packages, operator-provided chunk lists, and live follow-up sequences must be formalized by Chunk Planner output, recorded in a work-package or equivalent approved queue, and created as draft/backlog chunk artifacts before activation. When the operator authorizes a larger package or instructs the Orchestrator to derive the needed chunks autonomously, create the expected follow-up chunks as repo-visible draft/backlog artifacts as early as practical. Use the current package prompt, active acceptance criteria, and discovered repository facts to seed concrete goal/scope/out-of-scope/acceptance/validation/stop-condition sections. The transfer from prompt to chunk artifacts should be complete enough that future execution does not need the chat prompt to recover requirements. Later refinement means updating already-created chunks with repository-grounded results from completed chunks, carry-forward debt changes, solved items, or new validation evidence. It must not mean leaving core requirements in chat memory for later reconstruction. Do not create unmanaged active chunks directly from chat text. If urgent/live work needs to happen before a normal package can continue, handle it inside the current active chunk only when it fits that chunk's recorded scope and validation. Otherwise create an emergency backlog chunk first and record the reason, scope, out-of-scope items, acceptance criteria, validation expectations, and stop conditions. Activate it through the canonical lifecycle helper. Carry-forward work must be registered in a chunk, work-package, report, or governance registry artifact. Chat history is not a durable work queue. Authority principle: AI may propose, runtime may enforce, validators may verify, and only canonical transition engines may mutate authority state. Developer execution evidence and validation do not by themselves move a chunk to `Ready for Human Review`. QA must record typed machine-readable `PASS` evidence (`qa_evidence_type`, `qa_executor`, `qa_scope`, `qa_independence`, `qa_result`, `qa_reviewed_artifacts`, `qa_validation_evidence`, and `qa_limitations`), or a human/operator QA override must be recorded, and Orchestrator must coordinate the lifecycle transition through canonical tooling. ## From Requirements To Chunks Use this path for product ideas, larger features, cross-cutting work, or unclear requests: 1. Requirements Intake creates a user-centered draft in `ai/requirements/drafts` or `ai/requirements/active`. 2. Requirements Review returns `PASS` or `BLOCKED`. 3. Approved requirements move to `ai/requirements/approved`. 4. Chunk Planner creates an ordered `## Chunk Plan`. 5. Draft chunks are created under `ai/chunks/drafts` and reference the approved requirement in `Depends On` or the chunk body. 6. Orchestrator moves chunks through backlog, active implementation, QA, completion, and commit readiness. ## Chunk State Sections Active chunks use three state sections: - `## Execution Notes`: current Developer implementation summary, validation status, cleanup status, and known follow-ups. - `## QA Review`: current typed QA verdict summary only. Prose-only `Role: QA` plus `PASS` is not sufficient for new Ready-for-Human-Review transitions. - `## Pass History`: chronological Developer and QA pass history. Use `## Carry Forward` when a chunk introduces or observes unresolved runtime/governance debt that should survive the chunk. The durable source is `ai/governance/registries/carry-forward-debt.yaml`; the chunk section should reference registry ids instead of inventing a separate debt list. Carry-forward entries must distinguish blocking items from non-blocking warnings, advisories, compatibility debt, pending enforcement, observations, and follow-ups. If `Bad`, `Ugly`, or `Policy Enforcement` references unresolved debt or `Pending Enforcement`, Ready validation requires `## Carry Forward`. The section is a deterministic projection from the registry, not another authority source. Use pass history to avoid stale review sections becoming ambiguous during repeated Developer -> QA iterations. Standard pass entries: ```md ### Developer Pass N - Role: Developer - Date: YYYY-MM-DDTHH:mm:ss.sssZ - Goal: - Result: - Blockers: None | - Validation: - Cleanup: - Recommended Next Action: ### QA Pass N - Role: QA - Date: YYYY-MM-DDTHH:mm:ss.sssZ - Goal: - Verdict: PASS | BLOCKED - Blockers: None | - Validation: - Cleanup: - Recommended Next Action: ``` Ready-for-Human-Review role evidence is validator-visible: - Developer evidence must include `Role: Developer`. - QA review must include `Role: QA` and the authoritative `Verdict: PASS` or an explicit human/operator QA override. - Orchestrator handoff must include `Role: Orchestrator`. Developer sections may recommend the next action, but they must not claim lifecycle transition authority, close/commit approval authority, or workflow progression authority. QA owns verdict authority; Orchestrator owns lifecycle coordination and approval-boundary handoff. ## Developer-Only Workflow Use this when a human explicitly asks Developer to execute a small scoped chunk. 1. Read `ai/roles/developer.md`, `ai/standards/done.md`, and applicable conventions. 2. Implement only the assigned chunk. 3. Run requested validation. 4. Run runtime smoke when behavior, UI, integration, auth, configuration, database, or dev-server behavior changed. 5. Clean up test/dev artifacts and stop any servers started for validation. 6. Update chunk Execution Notes. 7. Append or update the current `### Developer Pass N` entry in `## Pass History`. 8. Report `git status` and `git diff --stat`. Developer-only work ends as ready for review unless a human explicitly approves completion. Developer does not self-approve DONE based only on validation. ## QA-Only Workflow Use this when a human asks QA to review an implemented chunk. 1. Read `ai/roles/qa.md`, `ai/standards/done.md`, and `ai/standards/qa-gates.md`. 2. Review the diff against chunk scope, out-of-scope items, acceptance criteria, and conventions. 3. Run requested validation. 4. Decide whether runtime smoke is applicable. 5. Run `yarn smoke:runtime` when the chunk changes behavior, UI, auth, configuration, database access, cross-layer integration, or dev-server behavior, unless the chunk specifies a more precise runtime smoke command. 6. If runtime smoke is not applicable, state why in the QA report. 7. Record any manual/browser checks needed beyond `yarn smoke:runtime`. 8. For frontend/UI chunks, check `apps/frontend/smoke/README.md` for the current browser smoke strategy and document whether Playwright smoke was run, unavailable, or accepted as follow-up. 8. Check cleanup, generated artifacts, documentation, and regression risk. 9. Update `## QA Review` as the current verdict summary. 10. Append or update the current `### QA Pass N` entry in `## Pass History`. 11. Report `PASS` or `BLOCKED` with blockers first. QA-only work does not implement fixes unless explicitly asked. ## Full Orchestrated Workflow Use this when a human asks Orchestrator to manage a chunk through completion. 1. Orchestrator confirms the chunk goal, scope, out-of-scope items, acceptance criteria, and validation. 2. Developer implements the chunk and reports validation, runtime smoke, cleanup, status, and diff stat. 3. QA reviews against `ai/standards/done.md` and `ai/standards/qa-gates.md`. 4. If QA reports `BLOCKED`, Orchestrator sends a focused fix prompt back to Developer. 5. Repeat Developer to QA until QA reports `PASS`, the default max iteration count of 3 is reached, scope changes are needed, or manual intervention is required. 6. Orchestrator transitions lifecycle state only after QA approval and required notes are present. Use canonical transition tooling for authority-state mutation when available. Follow `ai/standards/orchestration-workflow.md` for the full reusable loop standard. Manual intervention is required when requirements are ambiguous, QA and Developer disagree, runtime smoke cannot be executed, validation requires unavailable services, scope needs to change, or max iterations are reached. Useful read-only helpers: ```sh ai/commands/orchestrator-status.sh ai/commands/orchestrator-next.sh ``` ## Workflow Simulation Harness Use `ai/commands/workflow-scenarios-test.sh` when workflow tooling changes affect canonical state, orchestration handoffs, prompt synthesis, pass history, or readiness gates. The harness creates a temporary git repository under `/tmp`, copies the workflow helpers into it, writes fixture chunks, and verifies the Developer -> QA loop without mutating real chunks, requirements, `.tmp`, `.env`, app source, dependencies, Telegram, tmux, Codex, or commits. Run: ```sh ai/commands/workflow-scenarios-test.sh ``` The harness covers no active chunk, commit-ready, ready-for-QA, QA blocked, Developer fix after QA blocked, ready-to-complete, missing, blocked, or mismatched acceptance verification, untracked-only summary visibility, multiple Developer passes before QA, and QA prompt pass-history selection. Use `ai/commands/requirements-scenarios-test.sh` when requirements lifecycle tooling or requirements workflow policy changes. It creates a temporary repository under `/tmp`, writes explicit rough-idea and clarification-answer fixtures, asserts that pre-clarification requirements review is `BLOCKED`, asserts clarified simulation readiness, and confirms chunk-plan structure without mutating real requirements files. Run: ```sh ai/commands/requirements-scenarios-test.sh ``` ## Workflow Summary Reports Use `ai/commands/workflow-summary.sh` when a human, QA reviewer, Telegram workflow, or future orchestrator needs a concise copy-pasteable run packet for the current workflow state. Run: ```sh ai/commands/workflow-summary.sh ai/commands/workflow-summary.sh --full ai/commands/workflow-summary.sh --handoff-only ``` The helper reads fixed repository state only. It summarizes the active chunk, canonical workflow state, handoff, execution notes, acceptance verification, QA review, pass history, validation evidence, git status, and diff stat. When work exists only in untracked files, it shows untracked count and paths instead of a misleading empty diff. When the state is `ready_to_complete` or `commit_ready`, it prints trusted operator-daemon staging/commit requests instead of raw git commands. Telegram workflow commands should stay aligned with these shared helpers instead of duplicating state parsing: - `/workflowstatus` wraps `ai/commands/workflow-summary.sh --handoff-only`. - `/lastreport` wraps `ai/commands/workflow-summary.sh`. - `/nextaction` wraps `ai/commands/orchestrator-next.sh`. - `/qaprompt` and `/devprompt` wrap `ai/commands/prompt-synthesize.sh`. Telegram should remain a mobile-friendly transport layer. If helper output needs to change, update the shared helper first and keep Telegram wrappers thin. ## Completion And Archive Workflow When the chunk is complete: 1. Confirm QA or human approval according to `ai/standards/done.md`. 2. Prefer the canonical dispatcher/daemon close path for completion and commit because it owns lifecycle mutation, staging, commit, and timeline evidence. 3. If using compatibility helpers or manual recovery, record the reason, operator approval, validation evidence, and resulting state explicitly. 4. Treat completed chunks as immutable history. Do not edit them except to correct clerical metadata errors. The old manual sequence of setting `Status: Completed`, filling `Completed`, and moving the file is compatibility-only. It is not the authoritative default when canonical transition or dispatcher tooling is available. If follow-up work is found, create a new chunk with a new id instead of reopening completed history. ## Lifecycle Helpers Run helper scripts from any working directory inside the repository. They locate the repo root from the script path. ### Validate Or Execute A Lifecycle Transition Use the registry-backed transition helpers for chunk status changes when practical: ```sh ai/chunks/validate-transition.sh --to "Ready for Human Review" ai/chunks/transition.sh --to "Ready for Human Review" --dry-run ai/chunks/transition.sh --to "Ready for Human Review" ``` The read-only validation logic is owned by Runtime Core TypeScript modules and the shell scripts remain compatibility entrypoints. The helpers read `ai/governance/registries/chunk-lifecycle.yaml`, validate legal source/target states, check Ready-for-Human-Review evidence, run governance validation unless fixture mode is requested, write transition evidence after validation passes, and emit timeline events. For close/commit recommendations they also surface whether a fresh approval side effect is required or already created. Runtime API exposes read-only inspection/validation methods such as `chunks.find`, `chunks.status`, `chunks.validateReady`, `chunks.validateTransition`, `chunks.evidenceSummary`, `lifecycle.validateTransition`, and `lifecycle.allowedTransitions`. These methods do not mutate lifecycle authority state. Manual status edits are compatibility-only. QA should prefer transition evidence from these helpers when reviewing lifecycle-sensitive work. ### Create A Chunk Use `ai/commands/new-chunk.sh` to create a new chunk with the next immutable id: ```sh ai/commands/new-chunk.sh auth-foundation ai/commands/new-chunk.sh auth-foundation backlog ai/commands/new-chunk.sh auth-foundation active ``` Usage: ```text ai/commands/new-chunk.sh [draft|backlog|active] ``` The helper: - Defaults to `draft`. - Requires a kebab-case slug. - Scans `drafts`, `backlog`, `active`, and `completed` to choose the next zero-padded id. - Creates `chunk-000001-.md`. - Adds standard metadata. - Appends piped or heredoc stdin content below the metadata. - Appends `ai/tasks/feature-template.md` when stdin is empty. - Refuses to overwrite existing files. - Refuses to create an active chunk when another active chunk exists. Inline prompt example: ```sh ai/commands/new-chunk.sh auth-foundation active <<'EOF' # Auth Foundation ## Goal Add a minimal authentication foundation. ## Scope 1. Add backend auth module skeleton. 2. Add placeholder current-user GraphQL query. ## Out Of Scope - OAuth providers - Production login UI - Sockets ## Validation node ai/runtime/dist/cli.js validate --tier full EOF ``` ### Activate A Chunk Use `ai/commands/activate-chunk.sh` to move a draft or backlog chunk into active work: ```sh ai/commands/activate-chunk.sh ai/chunks/backlog/chunk-000009-auth-foundation.md ``` The helper: - Accepts one draft or backlog chunk path. - Validates that the file exists. - Validates that it is inside `ai/chunks/drafts` or `ai/chunks/backlog`. - Refuses to activate when another active chunk exists. - Sets `Status: Active`. - Moves the chunk to `ai/chunks/active` with the same filename. - Prints the destination path. ### Complete A Chunk `ai/commands/complete-chunk.sh` is a compatibility helper for completing and archiving an active chunk safely. Prefer the dispatcher/daemon close path for normal close/commit flows, and prefer transition tooling for Ready-for-Human- Review status changes. ```sh ai/commands/complete-chunk.sh ai/chunks/active/chunk-000005-frontend-config-conventions.md ``` The helper: - Accepts one active chunk path. - Validates that the file exists. - Validates that the file is inside `ai/chunks/active`. - Sets `Status: Completed`. - Sets `Completed` to the current UTC ISO-8601 timestamp. - Moves the chunk to `ai/chunks/completed` with the same filename. - Refuses to overwrite an existing completed chunk. - Prints the destination path. - Records close/commit notification-contract evidence because the helper is a compatibility archive path and does not own Runtime Executor run-summary or Telegram completion delivery.