<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
<!-- Purpose: rendered strategy -->
<!-- Source of truth: packs/strategies/strategies-pack-0.1.json -->
<!-- Regenerate with: task packs:render -->
<!-- Edit the source, not this file. Slice instead of loading every strategy: task packs:slice strategies by-trigger --trigger <kw> (or list) -->

# v0.20 Strategy Output Contract

Canonical contract for the artifacts that every spec-generating strategy MUST produce to be v0.20-conformant.

**Legend (from RFC2119):** !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

**⚠️ See also**: [vbrief/vbrief.md](../vbrief/vbrief.md) | [strategies/README.md](./README.md) | [strategies/artifact-guards.md](./artifact-guards.md) | [skills/deft-directive-build/SKILL.md](../skills/deft-directive-build/SKILL.md) (Pre-Cutover Detection Guard) | [the frozen v0.59.0 migrator](../../UPGRADING.md) | [conventions/machine-generated-banner.md](../conventions/machine-generated-banner.md)

---

## Purpose

Spec-generating strategies (interview, yolo, speckit, rapid, enterprise) historically produced inconsistent artifacts:

- Some wrote only the legacy `vbrief/specification.vbrief.json` + root `SPECIFICATION.md`
- Some wrote scope vBRIEFs without date prefixes and still dual-wrote the old singular spec file
- None consistently seeded the full v0.20 lifecycle folders + `PROJECT-DEFINITION.xbrief.json` + date-prefixed proposed/ items

This caused immediate build failures via the Pre-Cutover Detection Guard for any project generated through those strategies.

This contract is the single source of truth. All future strategy implementations and migrations target exactly these artifacts. The build skill, vbrief validators, and (post-s2) deterministic shape gate enforce it.

## When to Use

Use this contract when authoring, reviewing, or migrating a spec-generating strategy that creates project definition artifacts, scope vBRIEFs, rendered views, or migration handoff material. It also applies when a guard, validator, or setup path needs to decide whether a project is current v0.20 output or legacy pre-cutover content.

## Workflow

1. Identify whether the strategy is spec-generating or preparatory.
2. Apply the matching row in the per-strategy summary table.
3. Create the required lifecycle folders before writing scope artifacts.
4. Write authoritative vBRIEF content to `xbrief/PROJECT-DEFINITION.xbrief.json` and date-prefixed `xbrief/proposed/*.xbrief.json` files.
5. Omit root `SPECIFICATION.md` / `PROJECT.md`, or write only deprecation redirect stubs when transitional UX requires them.
6. Run the validator and content gates before treating the strategy output as v0.20-conformant.

## Canonical v0.20 Output Shape

For a project that has completed any spec-generating strategy (or the full speckit flow), the following MUST exist and be the only authoritative sources:

### Required Directory Structure
- `xbrief/proposed/`
- `xbrief/pending/`
- `xbrief/active/`
- `xbrief/completed/`
- `xbrief/cancelled/`

All five lifecycle folders MUST be present (even if empty). This is the cutover signal used by pre-cutover guards.

### Required Root-Level vBRIEF Artifact
- `xbrief/PROJECT-DEFINITION.xbrief.json` (complete: narratives + items registry populated from the strategy session)

`task project:render` MAY be invoked by the strategy or left to the user; the end state after strategy + any render MUST have a non-skeleton PROJECT-DEFINITION.

### Scope vBRIEF Placement & Naming (Strict)
- All new scope vBRIEFs (user stories, phases, epics from speckit Phase 4/4.5, etc.) MUST be written **only** to `xbrief/proposed/YYYY-MM-DD-<kebab-slug>.xbrief.json`
- Filenames MUST be date-prefixed using the creation date (immutable per vbrief.md conventions)
- Bare names (e.g. `scaffold.vbrief.json`) or names without date prefix are FORBIDDEN in v0.20
- The old singular `vbrief/specification.vbrief.json` MUST NOT be written or updated by v0.20 strategies (it is a legacy container; new work uses the lifecycle folders + PROJECT-DEFINITION)

### SPECIFICATION.md & PROJECT.md (Derivative / Deprecated)
- Strategies SHOULD OMIT writing `SPECIFICATION.md` and `PROJECT.md` entirely. These are **rendered views** only.
- If a strategy does emit them (for UX continuity during transition), they MUST be written **exclusively** as deprecation-redirect stubs:
  - Start with the canonical 4-line machine-generated banner (see conventions/machine-generated-banner.md)
  - Fifth line: `<!-- deft:deprecated-redirect -->`
  - Short explanatory body pointing to `xbrief/PROJECT-DEFINITION.xbrief.json` and the lifecycle folders
  - Never contain real spec or project content
- Real content in these files (without the sentinel) triggers the build/setup/sync pre-cutover guards and forces migration.

### Legacy `specification.vbrief.json`
- ⊗ No v0.20 strategy may create or dual-write `vbrief/specification.vbrief.json` alongside the new model artifacts.
- Existing legacy files are handled only by `task migrate:vbrief` (which ingests them into scope vBRIEFs + PROJECT-DEFINITION and leaves a redirect stub at root if needed).

### Greenfield spec export (#2013 / #1502)

Greenfield projects (no `vbrief/specification.vbrief.json`) export stakeholder-facing spec text via `task project:export-spec`:

- ! Source of truth: `xbrief/PROJECT-DEFINITION.xbrief.json` product narratives + lifecycle scope bodies (never the legacy singular spec file).
- ! Default audience is **stakeholder** — proposed scopes are omitted; only pending/active/completed scopes appear under `## Scope outlook`.
- ! Internal handoff (setup Phase 3, speckit Phase 3→4 when proposed scopes must be visible) uses `task project:export-spec -- --audience=internal`, which adds `### Not yet accepted (proposed)` under `## Scope outlook` with a fixed disclaimer that proposed scopes are ideas, not approved backlog.
- ! Phase 3→4 transition gate: **export succeeded** (exit 0), not spec-file `approved` status — PROJECT-DEFINITION has no spec-approval lifecycle on greenfield trees.
- ~ Legacy migrated trees with `vbrief/specification.vbrief.json` MAY continue using `task spec:render` until fully cut over.
- ⊗ Invoke `task spec:render` on a greenfield tree that lacks `specification.vbrief.json` — use `task project:export-spec` instead.

### plan.xbrief.json and continue.xbrief.json
- Session/tactical state files are permitted at xbrief/ root (they carry `planRef` links). They are not part of the "spec output" contract but strategies that maintain chaining state (e.g. interview) update them per their own rules.

## Per-Strategy Summary Table (Target State After Migration)

| Strategy     | Type             | Must Create Lifecycle Folders | Must Write PROJECT-DEFINITION | Scope vBRIEFs Location                  | specification.vbrief.json | SPECIFICATION.md / PROJECT.md          |
|--------------|------------------|-------------------------------|-------------------------------|-----------------------------------------|-----------------------------|----------------------------------------|
| interview    | spec-generating  | Yes                           | Yes (narratives + items)      | proposed/YYYY-MM-DD-*.xbrief.json only  | Never (post-migration)      | Omit or deprecation redirect only      |
| yolo         | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.xbrief.json only  | Never                       | Omit or deprecation redirect only      |
| speckit      | spec-generating  | Yes                           | Yes (Phase 1+)                | proposed/YYYY-MM-DD-*.xbrief.json only (phases + stories) | Never             | Omit or `task project:export-spec` (legacy: `task spec:render` on migrated trees) |
| rapid        | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.xbrief.json only  | Never                       | Omit or deprecation redirect only      |
| enterprise   | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.xbrief.json only  | Never                       | Omit or deprecation redirect only      |
| preparatory (research, discuss, map, etc.) | preparatory | Yes (if first touch)         | No (unless also spec path)    | proposed/YYYY-MM-DD-*.xbrief.json (context/decision vBRIEFs) | N/A                    | N/A (preparatory only)                 |

## Agent & Strategy Author Rules

- ! Every spec-generating strategy document MUST contain an "Artifacts" or "Output" section that explicitly cites this contract (`strategies/v0-20-contract.md`) and reproduces the relevant row from the table above.
- ! Before emitting any vBRIEF artifact, follow the guards in `artifact-guards.md` (updated to reference this contract).
- ! Date prefixes on scope vBRIEFs are mandatory for swarm readiness, filename sorting, and dedup.
- ⊗ Write real content to root SPECIFICATION.md or PROJECT.md from a strategy.
- ⊗ Emit bare-named vBRIEFs in proposed/ or anywhere outside the dated convention.
- ⊗ Dual-write the old `specification.vbrief.json` in a v0.20 flow.

## Verification & Enforcement

- Build / setup / sync skills: Pre-Cutover Detection Guard (any missing lifecycle folder or real-content legacy md triggers redirect to migrate).
- `task vbrief:validate` + `task check`: filename convention, folder/status consistency, PROJECT-DEFINITION presence.
- Post-s2: deterministic validation gate (s2 story) will parse strategy output trees against this contract and fail non-conformant generations.
- Content tests + migration stories exercise the before/after shapes.

## Migration Path for Existing Strategies

The s3/s4/s5 stories migrate the individual strategy files (and their emitted examples) to the shape defined here. This contract document is the target spec they implement against; do not change strategies first.

## When to Use

Use this contract when:
- Authoring a new spec-generating strategy (interview, yolo, speckit, rapid, enterprise, etc.).
- Migrating an existing strategy to v0.20 (the s3/s4/s5 work).
- Implementing or updating the deterministic validation gate (s2) or build pre-cutover guards.
- Writing migration tooling (the frozen v0.59.0 migrator in UPGRADING.md, reconcile scripts, etc.).
- Auditing a generated project for v0.20 conformance.

## Workflow

1. Read the Canonical v0.20 Output Shape section.
2. Ensure your strategy (or migration) writes exactly the required folders + `PROJECT-DEFINITION.xbrief.json` + dated proposed/ vBRIEFs.
3. Never write the legacy `specification.vbrief.json` or real-content `SPECIFICATION.md`/`PROJECT.md`.
4. Cite this contract explicitly in your strategy's "Artifacts" / "Output" section (see the Per-Strategy Summary Table).
5. Run `task check` (or the deterministic gate once s2 lands) to validate.

---

**Owned by**: `xbrief/active/2026-05-26-define-canonical-v020-strategy-output-contract.vbrief.json` (s1-contract of #1166 strategy consistency decomposition)

This contract lands first so that s2 (gate) and the migration stories have an unambiguous target.