# Batch Queue Contract

This file owns batch coordination after the mandatory intake in `../SKILL.md`
has been resolved. It never replaces the single-video state machine defined
in `run-state.md`.

## Location And Ownership

Each batch owns one queue directory:

`videos/_queues/<batch-id>/`

It contains:

- `queue.json`: machine-readable coordination, ordering and aggregate status.
- `SUMMARY.md`: operator-facing outcome and publish readiness report.

Each item continues to own its operational truth in:

`videos/<project-name>/run-state.json`

The manifest links to that state file and may report an aggregate item status,
output path, QA result and concise blocker/error. It must not copy item stage
records, artifact fingerprints, retry attempts or fallback approval history.

## Shared Intake

Create a queue only after the normal intake gate has resolved:

- channel profile;
- output language;
- template strategy and template set when applicable;
- execution mode and reporting level.

Persist those shared choices once in `queue.json`. For a coherent batch, use
one approved template set by default. An item may select a different approved
template only when its proof or content needs differ materially; the linked
`run-state.json` stores the selection and rationale.

A `candidate` template is never made production-ready by batch execution.
Candidate review and promotion remain governed by `template-library.md`.

## Manifest Rules

The manifest records:

- batch identity, timestamps, shared intake and mode;
- retained source URLs in input order;
- project directory and `run-state.json` link for each retained item;
- aggregate item status, output/QA disclosure and short issue text;
- compact queue events including exact duplicate suppression.

Only exact duplicate source URLs are removed during initialization. Potential
same-story URLs remain distinct items and may be noted for operator review.

Allowed aggregate item statuses are:

`pending`, `running`, `complete`, `blocked`, `failed`, `skipped`

## Sequential Execution And Resume

Process items in manifest order. Item `N` completes, fails, blocks or is
explicitly skipped before production begins for item `N+1`. Do not use batch
coordination as permission for concurrent source capture, voice generation,
composition or rendering.

On resume:

1. Read `queue.json`.
2. Validate a relevant item's linked state with `run_state.py resume-check`.
3. Skip an item only when the linked current state remains fully complete.
4. If one completed item is invalidated, resume only that item from its
   earliest invalid checkpoint; do not rerender sibling items.

An item that has exhausted same-output retries is `failed`; independent later
items may proceed. A quality-changing fallback remains `blocked` until the
item receives explicit run-scoped approval or is skipped. A queue never
approves a fallback itself.

## Summary Contract

`SUMMARY.md` includes batch identity and shared intake, counts for every
aggregate status and an ordered row for each item. Each row reports the
project/state path, output when present, QA result, approved template
selection or override, voice/fallback disclosure and a concise error or
blocked reason when applicable. Each completed project's `PUBLISH.md` stores
its post-ready title, caption and hashtags.

Include a separate `Ready to publish` section containing only current renders
whose linked item state has passed QA and whose `PUBLISH.md` exists. This
section repeats each render's publish title and hashtags. Failed, blocked and
skipped items stay visible and actionable rather than being hidden by
successful output.