microsoft/hve-core

---
description: 'ADR Creator Govern-phase handoff protocol: compact summary template, peer-agent routing heuristics, and dual-format (ADO + GitHub) work item templates - Brought to you by microsoft/hve-core'
applyTo: '**/.copilot-tracking/adr-plans/**, **/docs/planning/adrs/**'
---

# ADR Creator Govern-Phase Handoff

Instructions for the ADR Creator Govern-phase exit. After an architectural decision reaches `accepted` (or `proposed` with explicit handoff intent), the agent emits a compact summary, evaluates trigger heuristics for downstream peers, generates dual-format work items for any opted-in backlog systems, and records each handoff event in session state.

## Govern-Phase Protocol

1. If `state.userPreferences.autonomyTier` is unset, prompt the user to choose `manual`, `partial` (default), or `full` and persist the answer. The tier is selected once at Govern-phase entry and is read-only for the remainder of the session, mirroring the Phase-5 pattern in Security Planner and SSSC Planner.
2. Confirm the ADR has a stable identifier (`ADR-NNNN`), title, status, and a final placement path.
3. Produce the compact summary using the template below.
4. Evaluate every row in the Handoff Peers table against the captured ADR content. Multiple peers can fire from a single ADR.
5. For each peer that fires, prepare the artifact described in that row.
6. Present the disclaimer block to the user before writing any external work item, and record `state.disclaimerShownAt` (ISO-8601 timestamp).
7. Apply the autonomy-tier behavior below before any external write.
8. On confirmation (per tier), generate work items in the requested format(s). For `ado-backlog` and `github-backlog` handoffs, append a canonical record to `state.handoffs[]` (see Handoff State Recording). For agent-peer handoffs (RPI, Security, RAI), record the compact summary and excerpt paths in the Handoff Summary table only; do not append them to `state.handoffs[]`.
9. Present a final handoff summary listing peers fired, work items generated, and any deferred decisions.

## Autonomy Tiers at Govern

The selected tier governs every external write and handoff in the Govern phase. Frame and Decide are unaffected and always run with full coaching cadence.

| Tier      | Govern-Phase Behavior                                                                                                                                                                                     |
|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `manual`  | Present each generated artifact (compact summary, work item bodies, peer excerpts) and pause; require explicit user approval per artifact before writing externally or appending to `state.handoffs[]`.   |
| `partial` | Generate all Govern artifacts in a single batch, present the bundle for review, and require one batch approval before writing externally and appending to `state.handoffs[]`. Default tier.               |
| `full`    | Generate and write all Govern artifacts and append `state.handoffs[]` records without per-artifact approval. Still respect every disclaimer and gate, and emit the final Handoff Summary unconditionally. |

If any gate fails (missing disclaimer, missing target system, missing required ADR field), downgrade to `partial` for that gate, surface the failure, and proceed only after the user resolves it.

## Compact Summary Template

The compact summary is always produced at Govern exit and is the canonical artifact handed to every downstream peer.

```markdown
# ADR Compact Summary

* **ADR ID:** ADR-{NNNN}
* **Title:** {ADR title}
* **Status:** {proposed|accepted|rejected|deprecated|superseded|withdrawn}
* **ADR Path:** {relative path to final ADR file}
* **Date:** {YYYY-MM-DD}

## Key Decision

{One- or two-sentence statement of the decision that was made.}

## Rationale

{No more than two sentences explaining why this option was chosen over the alternatives.}

## Affected Components

* {component or surface 1}
* {component or surface 2}

## Follow-up Triggers Detected

* {peer-name}: {short reason this trigger fired}
* {peer-name}: {short reason this trigger fired}

> **Note** — This summary was prepared with assistance from AI. Validate the decision, rationale, and follow-up triggers with the responsible architects before propagating to downstream systems.
```

Populate `Follow-up Triggers Detected` directly from the Handoff Peers table evaluation. If no peers fire, state `None — ADR is informational only` and skip work item generation.

## Handoff Peers

| Peer             | Trigger heuristic                                                                          | Artifact handed over                               |
|------------------|--------------------------------------------------------------------------------------------|----------------------------------------------------|
| RPI Task Planner | Decision creates implementable engineering work                                            | ADR ID + compact summary + work item stubs         |
| Security Planner | Decision affects threat model, attack surface, or trust boundary                           | ADR ID + compact summary + STRIDE-relevant excerpt |
| RAI Planner      | Decision affects AI/ML behavior, training data, model selection, or user-facing AI surface | ADR ID + compact summary + RAI-relevant excerpt    |
| ADO backlog      | User opted for ADO work items                                                              | Dual-format `WI-ADR-{NNN}` template (see below)    |
| GitHub backlog   | User opted for GitHub Issues                                                               | Dual-format `{{ADR-TEMP-N}}` template (see below)  |

A single ADR may fire any combination of these peers. Always evaluate all rows; do not stop at the first match.

## Trigger Heuristics

Explicit decision rules that determine when each handoff fires. When in doubt, fire the handoff and let the receiving peer triage.

### RPI Task Planner

Fire when any of the following is true:

* The decision introduces, removes, or restructures a code component, service, schema, or interface.
* The decision specifies a migration, refactor, or rollout sequence with discrete steps.
* The decision requires configuration, infrastructure, or tooling changes that an engineer must implement.
* Acceptance Criteria in the ADR contain verifiable engineering outcomes.

Hand over: ADR ID, compact summary, and one or more work item stubs describing the engineering deliverables.

### Security Planner

Fire when any of the following is true:

* The decision changes a trust boundary, authentication path, authorization model, or data classification surface.
* The decision adds, removes, or relocates an exposed network endpoint, API, or message channel.
* The decision affects secrets handling, credential storage, key management, or cryptographic primitives.
* The decision touches a component already covered by an existing security model.

Hand over: ADR ID, compact summary, and a STRIDE-relevant excerpt that highlights the components, data flows, and trust boundaries the Security Planner should re-examine.

### RAI Planner

Fire when any of the following is true:

* The decision selects, replaces, fine-tunes, or removes an AI/ML model.
* The decision changes training data sources, data curation, labeling, or evaluation datasets.
* The decision modifies a user-facing AI surface (prompts, outputs, agent behavior, recommendation logic).
* The decision affects automated decision-making, content generation, or human-in-the-loop policy.

Hand over: ADR ID, compact summary, and a RAI-relevant excerpt covering affected NIST AI RMF trustworthiness characteristics, model lifecycle stages, and stakeholder impact.

### ADO Backlog

Fire when `state.userPreferences.targetSystem` includes `ado`. Generate one or more `WI-ADR-{NNN}` work items per the ADO template below.

### GitHub Backlog

Fire when `state.userPreferences.targetSystem` includes `github`. Generate one or more `{{ADR-TEMP-N}}` issues per the GitHub template below.

If `targetSystem` is unset at Govern exit, ask the user which backlog system(s) to target and persist the selection before generating work items.

## Disclaimer Integration

Every work item body and every peer-handoff artifact MUST include the standard disclaimer block. Reference the canonical text at `../shared/disclaimer-language.instructions.md` and use the section that matches the planner identity. When an `ADR Planning` section is present in that shared file, use it; otherwise use the generic AI-assistance note shown in the templates below and link to the shared file.

Before displaying any disclaimer to the user, record the timestamp:

* Set `state.disclaimerShownAt` to the ISO-8601 timestamp of presentation.
* Do not regenerate handoff artifacts until `state.disclaimerShownAt` is non-empty for the current Govern cycle.

## Dual-Format Work Item Templates

Generate ADO and GitHub formats simultaneously when both backlogs are targeted. ID conventions are distinct from RAI (`WI-RAI-{NNN}`), Security (`WI-SEC-{NNN}`), and SSSC (`WI-SSSC-{NNN}`) to prevent collisions.

### ADO Format — `WI-ADR-{NNN}`

Required fields:

* **ID:** `WI-ADR-{NNN}` (sequential within the ADR plan).
* **Type:** User Story / Task / Bug as appropriate to the deliverable.
* **Title:** `[ADR-{NNNN}] {concise description of the work item}`.
* **Description:** HTML-formatted using the template below. Includes the disclaimer block.
* **Acceptance Criteria:** Verifiable outcomes derived from the ADR's Consequences and decision drivers.
* **Tags:** Include `adr:{NNNN}` plus any peer-relevant tags (for example, `security`, `rai`, `migration`).
* **Linked ADR:** Relative path to the final ADR file (for example, `docs/planning/adrs/{NNNN}-{slug}.md`).

HTML description template:

```html
<div>
  <h3>ADR-{NNNN}: {ADR title}</h3>
  <p><strong>Decision:</strong> {key decision in one sentence}</p>
  <p><strong>Rationale:</strong> {rationale in no more than two sentences}</p>
  <p><strong>Affected Components:</strong> {component list}</p>
  <p><strong>Linked ADR:</strong> <a href="{adr_path}">{adr_path}</a></p>
  <h4>Work Item Scope</h4>
  <p>{what this work item delivers in service of the ADR}</p>
  <h4>Acceptance Criteria</h4>
  <ul>
    <li>{criterion 1}</li>
    <li>{criterion 2}</li>
  </ul>
  <blockquote>
  <p><strong>Disclaimer</strong> — This work item was generated with assistance from AI based on an architectural decision record. Review and validate before use. See the shared disclaimer text in <code>../shared/disclaimer-language.instructions.md</code>.</p>
  <ul><li><input type="checkbox" disabled /> Reviewed and validated by a qualified human reviewer</li></ul>
  </blockquote>
</div>
```

Execution follows `ado-update-wit-items.instructions.md`.

### GitHub Format — `{{ADR-TEMP-N}}`

Required fields:

* **Temporary ID:** `{{ADR-TEMP-N}}`, replaced with the real issue number on creation.
* **Title:** `[ADR-{NNNN}] {concise description of the issue}`.
* **Body:** Markdown using the template below. Includes the disclaimer block and a link to the ADR.
* **Labels:** Include `adr:{NNNN}` plus any peer-relevant labels (for example, `security`, `rai`, `migration`).
* **Milestone:** Optional. Assign when the ADR ties to a release or planning increment.

YAML metadata block prepended to the issue body:

```yaml
---
adr_id: ADR-{NNNN}
adr_path: {relative path to the ADR file}
peer_handoffs: [{rpi|security|rai|none}, ...]
---
```

Markdown body template:

```markdown
## ADR-{NNNN}: {ADR title}

**Decision:** {key decision in one sentence}
**Rationale:** {rationale in no more than two sentences}
**Affected Components:** {component list}
**Linked ADR:** [{adr_path}]({adr_path})

### Work Item Scope

{what this issue delivers in service of the ADR}

### Acceptance Criteria

* [ ] {criterion 1}
* [ ] {criterion 2}

> **Disclaimer** — This issue was generated with assistance from AI based on an architectural decision record. Review and validate before use. See the shared disclaimer text in [`../shared/disclaimer-language.instructions.md`](../shared/disclaimer-language.instructions.md).
> - [ ] Reviewed and validated by a qualified human reviewer
```

Execution follows `github-backlog-update.instructions.md`.

## Handoff State Recording

After each backlog handoff event (`ado-backlog` or `github-backlog`), append a canonical record to `state.handoffs[]`:

```json
{
  "id": "{handoff identifier, e.g. WI-ADR-001 or ADR-TEMP-1}",
  "target": "ado | github",
  "payloadPath": "{relative path to the generated payload artifact under .copilot-tracking/adr-plans/{slug}/handoffs/}",
  "generatedAt": "{ISO-8601 timestamp}",
  "source": { "planner": "adr-planner" },
  "tier": "manual | partial | full"
}
```

Rules:

* One entry per backlog handoff. Re-runs append new entries; do not mutate prior entries.
* `id` for `ado` is the `WI-ADR-{NNN}` identifier (or, for batches, the lead identifier with a sibling list captured inside the payload).
* `id` for `github` is the `{{ADR-TEMP-N}}` placeholder until issue creation, then the real issue number recorded in the payload artifact.
* `tier` is the active `state.userPreferences.autonomyTier` at the time the handoff fired.
* Agent-peer handoffs (RPI Task Planner, Security Planner, RAI Planner) are NOT recorded in `state.handoffs[]`. They are inbound to those planners and surface only in the Handoff Summary table and the compact summary file referenced therein. Those receiving planners record the inbound artifact in their own `state.inputs[]`.
* If the schema does not yet include `state.handoffs[]`, add it. Do not overload `state.inputs[]`, which records inbound assessment inputs.

## Handoff Summary Format

After all handoffs complete, present a summary covering peers fired, work items generated, and outstanding decisions.

```markdown
# ADR Handoff Summary

## ADR: ADR-{NNNN} — {title}
## Date: {YYYY-MM-DD}
## Status: {proposed|accepted|rejected|deprecated|superseded|withdrawn}

### Peers Fired

| Peer             | Triggered? | Artifact Reference    |
|------------------|------------|-----------------------|
| RPI Task Planner | {Yes/No}   | {path or "n/a"}       |
| Security Planner | {Yes/No}   | {path or "n/a"}       |
| RAI Planner      | {Yes/No}   | {path or "n/a"}       |
| ADO backlog      | {Yes/No}   | {WI IDs or "n/a"}     |
| GitHub backlog   | {Yes/No}   | {issue refs or "n/a"} |

### Work Items Generated

| ID / Ref       | System | Title   | Tags / Labels   |
|----------------|--------|---------|-----------------|
| WI-ADR-{NNN}   | ADO    | {title} | adr:{NNNN}, ... |
| {{ADR-TEMP-N}} | GitHub | {title} | adr:{NNNN}, ... |

### Outstanding Decisions

{list of decisions deferred to humans, including stakeholder owners}

### Next Steps

{recommended follow-up actions, including who to notify}

> **Disclaimer** — See `../shared/disclaimer-language.instructions.md`. All ADR-derived work items must be reviewed by a qualified human before execution.
```

Log every generation event (create, skip, defer) and the reason for any skip.