# Project Lifecycle

## Status

- Status: active global workflow rule.
- Scope: all `video-workbench` projects, regardless of whether the final artifact is an MV, explainer video, slide-style presentation, or another visual/video package.

This document defines the common lifecycle. Project-specific files decide what each phase means for that medium.

## Lifecycle Phases

Use these phases in `projects/<project>/project.md`:

| Phase | Meaning | Common exit condition |
| --- | --- | --- |
| `intake-cleanup` | Accepted GPT / user source material is repaired, normalized, and stored under `intake/`. | Source files are readable, named, and mapped to local execution roles. |
| `system-definition` | Source material is localized into project production systems. | Local control files and production authorities exist. |
| `pilot-validation` | Core units, risky visual/audio rules, and workflow mechanics are tested. | The user accepts the core route and authorizes production. |
| `production` | Units are produced in batches through the approved route. | All target units are complete, accepted or explicitly deferred, and no active production package remains. |
| `assembly-closeout` | Produced assets are assembled, exported, reviewed for final use, and archived. | Delivery/output artifacts and handoff records are complete. |

The lifecycle phase is not the same as the operating line. A project in `production` can still temporarily use `test/audit` for a repair or failure investigation. A normal production package should use `production-light` after the route is approved.

## Medium-Specific Outputs

The phase names stay stable; the concrete work differs by medium.

| Medium | `system-definition` examples | `pilot-validation` examples | `production` examples |
| --- | --- | --- | --- |
| MV / shot-image package | `visual-system/`, style master, character registry, `slides/slides.md`. | Core shots, character consistency, reference-loading route, callback route. | Sequential slide image packages. |
| Explainer video | Script structure, terminology, visual explanation rules, voice style, asset taxonomy. | One short script section, key diagram, sample narration audio, timing check. | Script sections, diagrams, narration audio, supporting slides. |
| Slide-style presentation | Page system, component patterns, visual hierarchy, case/source map. | Representative pages and transition/page-density checks. | Page batches and export-ready assets. |

Do not copy GPT planning into duplicate project truth. The accepted `intake/` files remain sources; Codex-owned local execution rules live in `execution-plan.md`, `visual-system/`, `slides/`, `tasks/`, and medium-specific control files.

## Production Run State

For any production request that may continue across multiple child sessions, create or update a lightweight run state file:

```text
projects/<project>/tasks/<task-id>/production-run-status.md
```

This file is the compression-safe continuation surface for unattended production. It should be short and current, not an audit report.

It records:

- project path;
- lifecycle phase;
- operating line;
- running mode;
- review mode;
- package size or validation override;
- total target scope;
- completed units;
- active child session and callback target;
- next unresolved cursor;
- stop conditions;
- latest callback summary.

The parent session may be automatically compressed. After each child callback, the parent should reload the minimal source of truth before dispatching the next package:

```text
AGENTS.md
VIDEO_WORKBENCH.md
docs/workflows/project-lifecycle.md
docs/workflows/slide-task-orchestration.md
docs/workflows/slide-task-templates.md
projects/<project>/project.md
projects/<project>/execution-plan.md
projects/<project>/slides/slides.md
projects/<project>/tasks/<task-id>/production-run-status.md
projects/<project>/tasks/<task-id>/task-log.md
```

Only read detailed prompts, images, old session records, or prior handoffs when the current handoff reports `blocked`, `failed`, `warning`, collision, ambiguous scope/status, or the user explicitly asks for inspection.

## Unattended Production Loop

When the user authorizes a full production run:

1. Resolve the target set from the project fact table.
2. Write `production-run-status.md` and `task-log.md`.
3. Dispatch exactly one clean child session for the next package.
4. Stop routine parent polling and wait for callback.
5. The child completes all artifact writes, `slides/slides.md` updates, compact closeout checks, and `child-session-handoff.md` before callback.
6. The callback is the child's final action. The child must not write or verify additional project files after a successful callback.
7. On callback, the parent reads the child handoff and updates the run state.
8. If status is clean and target units remain, dispatch the next package.
9. Stop only when the target set is complete or a stop condition is reached.

The parent does not need exact token/context usage to continue. It relies on file-backed reload after callback. A separate successor orchestration session is a fallback, not the default, and should be used only when the current parent cannot continue cleanly.

## Stop Conditions

Stop and ask the user when:

- a requested scope cannot be mapped cleanly;
- a package would include an already accepted unit unless explicitly requested;
- a target output path already exists and overwrite was not authorized;
- required references or production authority files cannot be loaded;
- child callback reports `blocked`, `failed`, or `warning`;
- user confirmation is explicitly required for the validation package result;
- the next action would change global package-size defaults or lifecycle rules.