ktg-plugin-marketplace/plugins/ultraplan-local/docs/HANDOVER-CONTRACTS.md

# Handover Contracts (ultra-suite local pipeline)

This document is the single source of truth for the file formats that pass between the four commands of the `ultraplan-local` pipeline. When you fork the plugin or extend a stage, the contracts below tell you what every producer must write and what every consumer is allowed to assume.

For each handover, the same headings appear in the same order: **Producer**, **Consumer**, **Path conventions**, **Frontmatter schema**, **Body invariants**, **Validation strategy**, **Versioning**, **Failure modes**.

## Versioning policy

Each artifact carries an explicit version field. Schema bumps are coordinated:

| Artifact | Field | Current |
|---|---|---|
| `brief.md` | `brief_version` (frontmatter) | `2.0` |
| `research/*.md` | (implicit; tracked via `type: ultraresearch-brief`) | unversioned |
| `plan.md` | `plan_version` (frontmatter) | `1.7` |
| `progress.json` | `schema_version` (top-level) | `"1"` |
| `review.md` | `review_version` (frontmatter) | `1.0` |

## Breaking-change protocol

1. Bump the artifact's version field.
2. Update the matching validator in `lib/validators/`.
3. Add a fixture under `tests/fixtures/` covering both old and new shapes.
4. Document the change in `MIGRATION.md` with at least an N-1 compatibility window in the validator (read both shapes; warn on old, fail only after one minor version of warning).
5. Bump the plugin version in `package.json` and `.claude-plugin/plugin.json`.

## Validator → handover map

| Handover | Validator |
|---|---|
| 1. brief → research | `lib/validators/brief-validator.mjs` |
| 2. research → plan | `lib/validators/research-validator.mjs` |
| 3. architecture → plan | `lib/validators/architecture-discovery.mjs` |
| 4. plan → execute | `lib/validators/plan-validator.mjs` |
| 5. progress.json (resume) | `lib/validators/progress-validator.mjs` |
| 6. review → plan | `lib/validators/review-validator.mjs` |

Every validator exposes a CLI: `node lib/validators/<name>.mjs --json <path>` returns `{valid, errors[], warnings[], parsed}`. Errors and warnings have stable `code` fields for downstream tooling.

---

## Handover 1 — `brief.md` → research/

**Producer:** `/ultrabrief-local` Phase 4g (after `brief-reviewer` stop-gate passes or iteration cap is hit).

**Consumer:** `/ultraresearch-local` Phase 1 (mode parse + brief validation).

**Path conventions:**
- Project-dir mode (recommended): `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md`.
- Legacy / loose mode: any path passed via `--brief <file>`.

**Frontmatter schema:**

| Field | Type | Required | Allowed values | Notes |
|---|---|---|---|---|
| `type` | string | yes | `ultrabrief` | Hard-coded discriminator |
| `brief_version` | string | yes | `"2.0"` (current) | Bump on schema change |
| `created` | date | yes | YYYY-MM-DD | |
| `task` | string | yes | one-line description | |
| `slug` | string | yes | URL-safe slug | Used in project_dir |
| `project_dir` | string | yes | `.claude/projects/{date}-{slug}/` | |
| `research_topics` | number | yes | ≥ 0 | |
| `research_status` | string | yes | `pending \| in_progress \| complete \| skipped` | State machine — see below |
| `auto_research` | bool | optional | `true \| false` | |
| `interview_turns` | number | optional | ≥ 0 | |
| `source` | string | optional | `interview \| manual` | |
| `brief_quality` | string | optional | `complete \| partial` | Set when iteration cap is hit |

**Body invariants:** required sections (validator runs in strict mode at write-time, soft mode at read-time):
- `## Intent`
- `## Goal`
- `## Success Criteria`

Optional but standard sections: `## Non-Goals`, `## Constraints`, `## Preferences`, `## Non-Functional Requirements`, `## Research Plan`.

**Validation strategy:**

| Layer | When | What |
|---|---|---|
| Frontmatter parse | every read | YAML subset; reject nested dicts |
| Required fields | every read | All `BRIEF_REQUIRED_FRONTMATTER` present |
| Type discriminator | every read | `type === "ultrabrief"` |
| Status enum | every read | `research_status ∈ allowed values` |
| **State machine** | every read | `research_topics > 0 && research_status === "skipped"` requires `brief_quality === "partial"` |
| Body sections | strict only | All `BRIEF_BODY_SECTIONS` present |

**State machine** detail: a brief that says it has research topics but skipped them must explicitly admit it (via `brief_quality: partial`). This is the most common failure mode the validator catches.

**Versioning:** current is `2.0`. There are no live `1.x` briefs; remove legacy paths in next major.

**Failure modes:**
- `BRIEF_NOT_FOUND` → consumer halts with a usage message
- `FM_MISSING` → file has no frontmatter; halt
- `BRIEF_WRONG_TYPE` → file is not a brief; halt
- `BRIEF_MISSING_FIELD` → strict halt; soft-mode warning
- `BRIEF_STATE_INCOHERENT` → strict halt; soft-mode warning (incoherence will haunt downstream agents)
- `BRIEF_MISSING_SECTION` → strict halt; soft-mode warning

---

## Handover 2 — research/*.md → plan

**Producer:** `/ultraresearch-local` Phase 7 (synthesis + brief writer).

**Consumer:** `/ultraplan-local` Phase 1 (project-dir auto-discovery) + `planning-orchestrator` (consumes findings as context).

**Path conventions:**
- Project-dir mode: `.claude/projects/{YYYY-MM-DD}-{slug}/research/{NN}-{topic-slug}.md` (sorted by filename).
- Legacy: `.claude/research/ultraresearch-{date}-{slug}.md`.

**Frontmatter schema:**

| Field | Type | Required | Allowed values |
|---|---|---|---|
| `type` | string | yes | `ultraresearch-brief` |
| `created` | date | yes | YYYY-MM-DD |
| `question` | string | yes | the research question |
| `confidence` | number | optional | `[0.0, 1.0]` — strongly recommended |
| `dimensions` | number | optional | ≥ 1 |
| `mcp_servers_used` | list | optional | server names |
| `local_agents_used` | list | optional | agent names |
| `external_agents_used` | list | optional | agent names |

Missing `confidence` is a warning, not an error — but downstream planning has no signal to weight findings.

**Body invariants:** required sections (strict mode):
- `## Executive Summary`
- `## Dimensions`

Optional: `## Local Context`, `## External Knowledge`, `## Triangulation`, `## Sources`, `## Recommendations`.

**Validation strategy:** schema parse + body-section check. Per-file by `validateResearch`; whole-directory by `validateResearchDir`. Anchoring back to brief topics is currently best-effort, not enforced (planned for a future minor).

**Versioning:** unversioned — research briefs are write-once read-once; no migration concern. If schema changes, change `type` discriminator or add `research_brief_version`.

**Failure modes:** all same shape as brief (`RESEARCH_*` codes). Default soft mode in plan Phase 1 — research drift does not block planning, but warnings surface in the user-visible summary.

---

## Handover 3 — architecture/ → plan (EXTERNAL CONTRACT)

**This is the only handover where the producer is in a *different plugin*.** The `architecture/overview.md` (and optional `gaps.md`) are produced by `/ultra-cc-architect-local` from the separate `ultra-cc-architect` plugin (v0.1.0+). When that plugin is not installed, this handover is absent — and that is fine.

**Producer:** `/ultra-cc-architect-local` (external plugin).

**Consumer:** `/ultraplan-local` Phase 1 (architecture-discovery) + `planning-orchestrator` Phase 7 (cross-reference architecture-note as priors during synthesis).

**Path conventions:**
- Canonical: `{project_dir}/architecture/overview.md`
- Optional: `{project_dir}/architecture/gaps.md`
- Tolerated alternatives (with warning): `architecture-overview.md`, `overview.markdown`, `README.md`

**Frontmatter schema:** **unenforced.** This is the external contract — `ultraplan-local` does not validate the format. We sniff only the first H1 heading.

**Body invariants:** **unenforced.** We never read body content beyond the first heading.

**Validation strategy:** **drift-WARN, never drift-FAIL.**

| Detection | Result |
|---|---|
| File at canonical path | `found: true`, no warnings |
| File at known alternative path | `found: true`, warning `ARCH_NON_CANONICAL_OVERVIEW` |
| Loose `*.md` files in `architecture/` not in known set | warning `ARCH_LOOSE_FILES` |
| No `architecture/` dir | `found: false`, no warnings |

The validator (`lib/validators/architecture-discovery.mjs`) is intentionally minimal. It is unit-tested to assert it does NOT read body content beyond the first heading — guarding against scope creep into the sister plugin's territory.

**Versioning:** the producer (`ultra-cc-architect`) owns its schema. We do not version this handover from our side.

**Failure modes:** none. Discovery always succeeds (returns `found: false` if absent). The handover is additive.

---

## Handover 4 — `plan.md` → execute

**Producer:** `planning-orchestrator` Phase 5 (plan synthesis) + Phase 5.5 (schema self-check via `plan-validator --strict`).

**Consumer:** `/ultraexecute-local` Phase 2 (plan parsing) + `--validate` mode.

**Path conventions:**
- Project-dir: `{project_dir}/plan.md`
- Legacy: `.claude/plans/ultraplan-{date}-{slug}.md`

**Frontmatter schema:**

| Field | Type | Required | Allowed |
|---|---|---|---|
| `plan_version` | string | yes | `"1.7"` (current) |

**Body invariants (strict, v1.7):**

1. Top-level structure:
   - `## Implementation Plan` heading present
   - One or more `### Step N: <title>` headings, numbered 1..N contiguously
   - `### Step N: ` is the literal canonical form — colon + space
2. Forbidden narrative-drift heading forms (Opus 4.7 regression guard):
   - `## Fase N` (Norwegian)
   - `### Phase N`
   - `### Stage N`
   - `### Steg N` (Norwegian variant)
3. Per-step Manifest block — **required for every step**:
   - Indented fenced YAML: ` ```yaml\n  manifest:\n    ...\n  ``` `
   - Required keys: `expected_paths` (list), `min_file_count` (number), `commit_message_pattern` (string compilable to RegExp), `bash_syntax_check` (list), `forbidden_paths` (list), `must_contain` (list of `{path, pattern}` dicts or empty list)
4. Step count == manifest count

**Validation strategy:**

The strongest validation in the entire pipeline. Phase 5.5 (planning-orchestrator) **must** run `plan-validator --strict` before handing the plan to plan-critic. `--validate` mode of `/ultraexecute-local` runs the same check + `progress-validator`.

| Code | Meaning | Recovery |
|---|---|---|
| `PLAN_FORBIDDEN_HEADING` | Narrative drift detected | Rewrite using literal Phase 5 template |
| `PLAN_NO_STEPS` | No `### Step N:` headings | Plan is empty; restart |
| `PLAN_STEP_NUMBERING` | Steps skip a number | Renumber sequentially |
| `PLAN_MANIFEST_COUNT_MISMATCH` | Some step lost its manifest | Add missing manifest |
| `MANIFEST_MISSING` | Specific step has no manifest YAML | Add Manifest block |
| `MANIFEST_MISSING_KEY` | Manifest is missing a required key | Add the key |
| `MANIFEST_PATTERN_INVALID` | `commit_message_pattern` does not compile | Check escaping (`\\(` not `\(` in YAML double-quoted strings) |
| `PLAN_VERSION_MISMATCH` | Older `plan_version` | Warning only; planner should bump |

**Versioning:** v1.7 has been stable since v1.8.0 of the plugin (when literal-template + Phase 5.5 self-check were added to fix Opus 4.7 schema drift). v1.6 → v1.7 added the Manifest block (mandatory). Before bumping to v1.8, write the new validator branch + fixtures first.

**Failure modes:** strict mode is the default for both producer and consumer. There is no soft mode here — a malformed plan is a hard failure for execute.

---

## Handover 5 — `progress.json` (resume contract)

**Producer:** `/ultraexecute-local` per-step (after Verify + Manifest audit + Checkpoint).

**Consumer:** `/ultraexecute-local --resume` (re-entry) + `pre-compact-flush` hook (drift detection before context compaction).

**Path conventions:**
- Project-dir: `{project_dir}/progress.json`
- Legacy: `{plan-dir}/.ultraexecute-progress-{slug}.json`

**Schema (top-level):**

| Field | Type | Required | Notes |
|---|---|---|---|
| `schema_version` | string | yes | `"1"` (current) |
| `plan` | string | yes | Path to the plan being executed |
| `plan_type` | string | optional | `plan \| session-spec` |
| `plan_version` | string | yes | Mirrors plan's frontmatter |
| `started_at` | ISO string | yes | |
| `updated_at` | ISO string | yes | Bumped on every write |
| `completed_at` | ISO string | optional | Set when status flips to completed |
| `mode` | string | yes | `execute \| dry-run \| validate` |
| `total_steps` | number | yes | |
| `current_step` | number | yes | 0..total_steps |
| `status` | string | yes | `pending \| in_progress \| completed \| failed \| partial` |
| `session_start_sha` | string | optional | git sha at execute start |
| `session_end_sha` | string | optional | git sha at execute end |
| `steps` | object | yes | Map of step number → step record |

**Per-step record:**

| Field | Type | Notes |
|---|---|---|
| `status` | `completed \| in_progress \| failed \| pending \| deferred \| skipped` | |
| `attempts` | number | 1..N |
| `error` | string \| null | |
| `completed_at` | ISO string \| null | |
| `commit` | string \| null | git sha after Checkpoint |
| `manifest_audit` | string | `pass \| fail \| pass-with-note \| n/a` |
| `note` | string | optional human-readable annotation |

**Validation strategy:** `progress-validator.mjs` runs at:
1. `/ultraexecute-local --validate` (alongside plan-validator)
2. `/ultraexecute-local --resume` entry (must pass `checkResumeReadiness`)
3. `pre-compact-flush` hook (drift check before compaction; never blocks)

**Drift detection:** the `pre-compact-flush` hook compares `progress.steps[N].commit` against `git log --oneline {session_start_sha}..HEAD`. If git reality has progressed past the recorded `current_step`, the hook updates progress.json atomically (`tmp + rename`, monotonic only) before allowing compaction. This guards against the documented P0 drift in `docs/ultraexecute-v2-observations-from-config-audit-v4.md`.

**Versioning:** `schema_version: "1"` is current. Future bump (e.g. `"2"`) should add a backward-compat read path that downgrades unknown fields to warnings.

**Failure modes:**
- `PROGRESS_PARSE_ERROR` → JSON corruption; resume halts
- `PROGRESS_SCHEMA_MISMATCH` → unknown schema version; resume halts
- `PROGRESS_MISSING_FIELD` → required top-level field absent; resume halts
- `PROGRESS_STEP_RANGE` → `current_step` outside `[0, total_steps]`; resume halts
- `PROGRESS_ALREADY_DONE` → `status === completed`; nothing to resume
- `PROGRESS_STEP_COUNT_MISMATCH` → warning; not a blocker

---

## Handover 6 — `review.md` → plan

**Handover 6 closes the iteration loop.** Where Handovers 1–4 flow forward (brief → research → plan → execute) and Handover 5 makes execute resumable, Handover 6 routes review findings *back* into planning so a remediation plan can be produced with full traceability via `source_findings`.

**Producer:** `/ultrareview-local` Phase 7 (write `review.md` after coordinator dedup + verdict).

**Consumer:** `/ultraplan-local` Phase 1 when `--brief review.md` is supplied and the consumer detects `type: ultrareview` in frontmatter. The plan command branches into a remediation-plan path: BLOCKER + MAJOR findings become plan goals, the produced `plan.md` carries a `source_findings: [<id>, ...]` frontmatter list as the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input.

**Path conventions:**
- Project-dir mode (recommended): `{project_dir}/review.md` (one per review iteration; subsequent runs overwrite atomically).
- Multiple review iterations are allowed in the same project; each overwrites the canonical path. Audit trail lives in git history.

**Frontmatter schema:**

| Field | Type | Required | Allowed values | Notes |
|---|---|---|---|---|
| `type` | string | yes | `ultrareview` | Hard-coded discriminator |
| `review_version` | string | yes | `"1.0"` (current) | Bump on schema change |
| `task` | string | yes | one-line description | Mirrors brief task |
| `slug` | string | yes | URL-safe slug | Used in project_dir |
| `project_dir` | string | yes | `.claude/projects/{date}-{slug}/` | |
| `brief_path` | string | yes | path to consumed `brief.md` | Audit trail back to brief |
| `scope_sha_end` | string | yes | git sha of HEAD at review time | Defines "after" boundary |
| `reviewed_files_count` | number | yes | ≥ 0 | From triage gate Coverage |
| `findings` | list | yes | block-style YAML list of 40-char hex IDs | Flat array; full objects in body |
| `created` | date | optional | YYYY-MM-DD | |
| `scope_sha_start` | string | optional | git sha at review start | `null` if mtime fallback used |
| `verdict` | string | optional | `BLOCK \| WARN \| ALLOW` | Coordinator output |

`findings:` is a flat array of finding-IDs (40-char hex from `lib/parsers/finding-id.mjs`). The full finding objects (severity, location, message, evidence, fix) live in the body as `### <id>` subsections under per-severity `## Findings (...)` headings — same pattern as brief-reviewer to avoid frontmatter-parser fragility on lists of dicts.

**Body invariants:** required sections (validator runs in strict mode at write-time, soft mode at read-time):
- `## Executive Summary`
- `## Coverage`
- `## Remediation Summary`

Optional but standard sections: `## Findings (BLOCKER)`, `## Findings (MAJOR)`, `## Findings (MINOR)`, `## Findings (SUGGESTION)`. The `## Coverage` section enumerates which files were deep-reviewed, summary-only, or skipped (with reason) — this is how the triage gate stays honest and avoids Copilot-style silent skips.

**Validation strategy:**

| Layer | When | What |
|---|---|---|
| Frontmatter parse | every read | YAML subset; reject nested dicts |
| Required fields | every read | All `REVIEW_REQUIRED_FRONTMATTER` present |
| Type discriminator | every read | `type === "ultrareview"` |
| Findings shape | every read | Array of strings, each matching `^[0-9a-f]{40}$` |
| Body sections | strict only | `Executive Summary`, `Coverage`, `Remediation Summary` |
| Version format | every read | `review_version` matches `N.M`; warning otherwise |

The validator (`lib/validators/review-validator.mjs`) exposes the same CLI as the others: `node lib/validators/review-validator.mjs --json <review.md>`. Strict mode is the default; `--soft` downgrades section-missing errors to warnings. `/ultrareview-local` Phase 8 runs `--strict`. `/ultraplan-local` Phase 1 (when consuming `--brief review.md`) runs `--soft` so a partially-valid review can still seed a plan.

**Versioning:** current is `1.0`. There are no live `0.x` reviews. Future schema changes follow the breaking-change protocol above.

**Failure modes:**
- `REVIEW_NOT_FOUND` → consumer halts with usage message
- `REVIEW_READ_ERROR` → I/O failure; halt
- `FM_MISSING` → file has no frontmatter; halt
- `REVIEW_WRONG_TYPE` → `type !== "ultrareview"`; halt
- `REVIEW_MISSING_FIELD` → strict halt; soft-mode warning
- `REVIEW_BAD_FINDINGS_TYPE` → `findings` is not an array; halt (covers the YAML flow-style trap)
- `REVIEW_BAD_FINDING_ID` → an ID is not 40-char hex; halt
- `REVIEW_MISSING_SECTION` → strict halt; soft-mode warning
- `REVIEW_VERSION_FORMAT` → warning only; review_version not in `N.M` form

---

## Stability summary

| Handover | Validation strength | Owner | Risk |
|---|---|---|---|
| 1. brief → research | strict at write, soft at read | this plugin | low |
| 2. research → plan | soft, drift-warn | this plugin | low |
| 3. architecture → plan | discovery-only, drift-WARN | **external** (ultra-cc-architect) | low — by design we tolerate drift |
| 4. plan → execute | **strict, both ends** | this plugin | medium — Opus 4.7 narrative drift requires constant vigilance |
| 5. progress.json | shape + resume readiness | this plugin | medium — drift during compaction handled by pre-compact-flush hook (CC v2.1.105+) |
| 6. review → plan | strict at write, soft at read | this plugin | low — additive feedback loop; consumer falls back gracefully when source_findings is absent |

When extending the plugin or adding a new pipeline stage, follow the same pattern: produce an artifact with a versioned frontmatter (or `schema_version` for JSON), write a validator under `lib/validators/`, add fixtures under `tests/fixtures/`, and add an entry to this document.