Drift Session Handover Authoring

---
name: drift-session-handover-authoring
description: "Drift-specific workflow for authoring session handover artifacts before calling drift_session_end (ADR-079). Use when writing work_artifacts/session_<id>.md, preparing versioned benchmark_results evidence JSON, or drafting ADRs that pair with a session. Keywords: session handover, drift_session_end, DRIFT-6100, handover gate, work_artifacts, session_md, feature evidence, ADR draft, bypass_reason."
argument-hint: "Describe the session you are about to end (change class, touched paths, completed tasks, pending follow-ups)."
---

# Drift Session Handover Authoring

Use this skill when you are about to call `drift_session_end` and must produce
the handover artifacts required by ADR-079 and the session-handover contract in
`.github/prompts/_partials/session-handover-contract.md`.

## When To Use

- You touched files under `src/drift/` during the session.
- You completed one or more fix-plan tasks.
- You ran multiple scans / diffs / nudges and want to hand off to the next
  agent (or to the maintainer).
- `drift_session_end` returned `DRIFT-6100` and you need to fill the missing
  artifacts.

## When Not To Use

- Empty sessions (no tool calls beyond session start, no completed tasks, no
  touched files). The gate auto-exempts them.
- Pure read-only exploration that touched no code.

## Core Rules

1. **Agent writes, server validates.** You author the artifacts. The MCP
   server only checks existence, shape, placeholders (and optionally runs an
   LLM review). Do not try to satisfy the gate with generated filler.
2. **No placeholder tokens.** `TODO`, `FIXME`, `XXX`, `TBD`, `???`, `<N>`,
   `<NNN>`, `LOREM`, `IPSUM`, `FOO`, `BAR`, `BAZ` outside of ≥5-line code
   fences block the gate at L3.
3. **Cross-check session id.** The `session_id` in the Markdown frontmatter
   must match the active session exactly.
4. **SIGNAL / ARCHITECTURE classes require all three artifacts.** Evidence
   JSON, ADR draft, and session markdown.
5. **`force=true` is a last resort.** It requires an auditable
   `bypass_reason` of at least 40 characters without placeholder tokens, and
   it is logged and persisted in the session trace.

## Step 1: Policy Gate

Before writing artifacts, run the mandatory gate from
`.github/instructions/drift-policy.instructions.md`. If the underlying change
is inadmissible the gate blocks you here, not at `drift_session_end`.

## Step 2: Determine Your Change Class

Ask yourself what the session actually changed:

| Touched paths                                                   | Class          | Required artifacts                    |
|-----------------------------------------------------------------|----------------|---------------------------------------|
| `src/drift/signals/**` or `src/drift/scoring/**`                | `signal`       | evidence + ADR + session_md           |
| `src/drift/ingestion/**`, `output/**`, `api/**`, `mcp_*`, `session*` | `architecture` | evidence + ADR + session_md           |
| Other `src/drift/**`                                             | `fix`          | session_md                            |
| `docs/**`, `docs-site/**`, `.github/prompts/**`, skills, instructions | `docs`         | session_md                            |
| Only config, lockfiles, CI, tasks.json                          | `chore`        | session_md                            |

When in doubt, pick the highest-priority class that applies.

## Step 3: Author the Session Markdown

Copy `docs/session_handover_template.md` into
`work_artifacts/session_<first 8 chars of session_id>.md` and fill every
required section. Minimum length ≥ 200 bytes (the template already exceeds
this when filled meaningfully).

Required frontmatter fields:

- `session_id` (full id, matching the active session)
- `duration_seconds`
- `tool_calls`
- `tasks_completed`
- `findings_delta`
- `change_class`

Required sections:

1. `## Scope` — what you changed and what you deliberately did not.
2. `## Ergebnisse` — observable outcomes (tests, metrics, behaviour).
3. `## Offene Enden` — known follow-ups. Write "Keine offenen Enden" (no
   "TODO") if there really are none.
4. `## Next-Agent-Einstieg` — the exact first tool call and the first file
   path the next agent should open.
5. `## Evidenz` — pointers to the evidence JSON, ADR, and updated audit
   artifacts.

## Step 4: Author the Evidence JSON (signal / architecture only)

Use the `drift-evidence-artifact-authoring` skill to produce a versioned file
in `benchmark_results/`. The gate's L2 layer requires these JSON keys at
minimum:

- `version`
- `feature`
- `description`
- `tests`
- `audit_artifacts_updated` (non-empty list when the class is `signal` or
  `architecture`)

## Step 5: Author the ADR Draft (signal / architecture only)

Use the `drift-adr-workflow` skill. The gate's L2 layer requires:

- Frontmatter `status: proposed` or `accepted`.
- `## Kontext` with ≥ 120 substantive characters.
- At least two explicit "Alternative" mentions.
- `## Entscheidung` and `## Konsequenzen` sections with non-empty content.

## Step 6: Call `drift_session_end`

Pass explicit paths so the server can skip path-discovery:

```
drift_session_end(
    session_id="<sid>",
    session_md_path="work_artifacts/session_<id8>.md",
    evidence_path="benchmark_results/v<ver>_<slug>_feature_evidence.json",
    adr_path="docs/decisions/ADR-<NNN>-<slug>.md",
)
```

If the gate blocks, read the `missing_artifacts`, `shape_errors`, and
`placeholder_flags` arrays in the response and fix the specific issue before
retrying.

## Step 7: Force-Bypass (Notausgang)

Only if a release-critical hotfix makes full artifacts impossible and a
follow-up task is already queued:

```
drift_session_end(
    session_id="<sid>",
    force=True,
    bypass_reason=(
        "Hotfix-Session fuer Release-Blocker; Evidence-JSON und ADR "
        "werden im Follow-up-Task <task-id> bis <date> nachgereicht."
    ),
)
```

The reason must be specific, meaningful, and free of placeholder tokens.
`force=true` is logged at WARNING level and recorded in the session trace.
After the limit of 5 blocked retries the gate auto-unblocks if — and only if —
a valid `bypass_reason` is supplied.

## Validation

- `drift_session_end` returns `status: ok` with `handover_gate.ok=true`, or
  `handover_bypass.forced=true` with a valid reason.
- The session markdown shows up in `git status` under `work_artifacts/`.
- Evidence JSON and ADR are parseable and referenced from the session
  markdown's `## Evidenz` section.

## References

- `docs/decisions/ADR-079-session-handover-artifact-gate.md`
- `.github/prompts/_partials/session-handover-contract.md`
- `docs/session_handover_template.md`
- `src/drift/session_handover.py`