# Release Inclusion Manifest

Open Orchestra stays trunk-based, but release tags use an explicit release
inclusion manifest to decide which completed work belongs to a version bump.

## Location

The canonical manifest path is:

```text
.agent-workflow/releases/release-inclusion.json
```

The manifest is workflow-local state. It is intended to be reviewed with the
release evidence for a candidate version, not bundled into the published npm
package as product behavior.

## Schema

`schemaVersion` is currently `1`. Each item must declare:

- `state`: one of `included`, `excluded`, `deferred`, `blocked`, or
  `already_released`.
- `taskId`: the Orchestra or GitHub-backed task id.
- `issueUrl`: the HTTPS issue URL for traceability.
- `commitReference`: a commit SHA or `start..end` SHA range.
- `versionTarget`: the semver version the item is evaluated against.
- `releaseNote`: a category and release-note text.
- `evidence`: one or more command, file, report, screenshot, trace, or video
  references.
- `review`: status and reviewer roles or names.
- `risk`: risk status, rationale, and accepted-by marker when accepted.
- `rollback`: rollback note.
- `owner`: owner role and optional owner name.

## Manual Editing

Keep manual edits deterministic:

- Sort items by `versionTarget`, then state, then `taskId`.
- Keep all text concise and reviewable in diffs.
- Prefer stable artifact paths or event ids for evidence references.
- Do not paste secrets, raw provider prompts, or full sensitive transcripts.
- Update `schemaVersion` only through a migration story.

## CLI Workflow

Validate and inspect candidate scope for a version:

```sh
orchestra release inclusion --version 1.1.3
orchestra release inclusion --version 1.1.3 --json
```

Generate release notes from `included` items only:

```sh
orchestra release notes --version 1.1.3
```

Check tag readiness without creating a tag:

```sh
orchestra release readiness --version 1.1.3
```

The readiness gate only evaluates `included` items for the requested version.
Items marked `excluded`, `deferred`, `blocked`, or `already_released` remain
visible in the candidate report but are non-release scope for notes and tag
preparation.

## GitHub and CI Sync

The manifest is the source of truth. GitHub labels, issue comments, project
fields, and CI artifacts are mirrors that help reviewers find state without
making GitHub required for local release work.

Recommended GitHub metadata mapping:

| Manifest state | Optional GitHub label | Release behavior |
| --- | --- | --- |
| `included` | `release:included` | Eligible for release notes and tag readiness. |
| `excluded` | `release:excluded` | Reported separately and omitted from notes. |
| `deferred` | `release:deferred` | Omitted until a later manifest update. |
| `blocked` | `release:blocked` | Omitted and should keep release review blocked. |
| `already_released` | `release:already-released` | Omitted from the next bump/tag scope. |

CI runs release inclusion validation in non-publishing mode. When a manifest is
present, CI should build the package, run `orchestra release inclusion
--version <package.json version> --json`, and upload the JSON report as a
review artifact. This check must not create tags or publish packages.

Manual fallback:

- If GitHub metadata is unavailable, reviewers use the manifest and CLI report.
- If CI cannot access secrets, run the same CLI commands locally and attach the
  JSON output as release evidence.
- If GitHub labels drift from the manifest, update labels/comments to match the
  manifest rather than editing the manifest to match labels.

## Example

```json
{
  "schemaVersion": 1,
  "versionTarget": "1.1.3",
  "items": [
    {
      "state": "included",
      "taskId": "GH-530",
      "issueUrl": "https://github.com/jterrats/open-orchestra/issues/530",
      "commitReference": "82ec5df",
      "versionTarget": "1.1.3",
      "releaseNote": {
        "category": "internal",
        "text": "Define release inclusion manifest schema."
      },
      "evidence": [
        {
          "type": "command",
          "summary": "Release inclusion schema tests passed.",
          "reference": "node --test test/release-inclusion.test.js"
        }
      ],
      "review": {
        "status": "approved",
        "reviewers": ["qa", "release_manager"]
      },
      "risk": {
        "status": "not_required",
        "rationale": "Schema-only change with no release publishing behavior."
      },
      "rollback": {
        "note": "Revert schema and docs commit before candidate generation."
      },
      "owner": {
        "role": "release_manager"
      }
    }
  ]
}
```