Handoff MCP v0.36–0.37 — V-Model Traceability Puts an End to "Write and Forget" Requirements

Handoff MCP v0.36 and v0.37 are out. These two versions lay the foundation for V-model requirements traceability — mechanically tracking where each requirement is implemented, what tests verify it, and what breaks when it changes.

The "Write and Forget" Problem

Writing requirements isn't the hard part. Keeping them connected to reality is. Which code implements requirement X? Which tests verify it? If a spec changes, what else needs updating? Maintaining these links by hand doesn't scale.

With AI agents doing the implementation, this gets worse. An agent completes the task it's given, but it has no way to know whether every linked requirement is covered and every related test still passes — unless there's a mechanical tracking system in place.

V-Model Layer Documents in Plain Markdown

Layer documents, introduced in v0.37, bring V-model structure to plain Markdown files. Pass a layer parameter (requirement, basic_spec, detailed_spec, acceptance, system_test, unit_test) to handoff_doc_save, and each Markdown heading in that document becomes an individually tracked item.

## REQ-AUTH-001 Login attempt rate limiting
- priority: P0
- method: automated

Lock an account for 30 minutes after 5 consecutive authentication failures.

Acceptance criteria:
- Account is locked after 5 failures
- Lock expires after 30 minutes
- Successful login resets the counter

You write normal Markdown. Give headings a recognized ID prefix (REQ-, SPEC-, AT-, etc.), add attribute lines (priority, method, test, etc.), and they're automatically wired into the traceability graph. Acceptance criteria are classified as gwt (Given-When-Then), ears (Event-Action-Response-State), or text (free-form), and each criterion becomes its own verification target.

Cross-layer relationships use refines (detailing a higher-level item) and verifies (testing a left-side item). Target a specific criterion with verifies: REQ-AUTH-001#AC1.

Coverage and Change Tracking

Trace Reports

handoff_trace_report computes horizontal coverage (are requirements covered by verification items?) and vertical coverage (are top-level requirements refined into lower-level specs?) across every layer document. Coverage is reported in five states: covered, partial, uncovered, waived, and na.

Automatic Suspect Detection

handoff_trace_suspect detects three kinds of change impact automatically:

• Link suspect — an upstream item referenced by refines/verifies has changed
• Task suspect — a requirement linked to a task has been modified
• Result suspect — the definition has changed since the last test was recorded

When you save an upstream document, the handoff_doc_save response includes a suspect_introduced summary showing exactly what was affected.

Change-Impact Analysis

handoff_trace_impact answers "what would break if I changed this?" before you save. It accepts a file change, a git diff, or a proposed Markdown block, and returns the links that would become suspect and the verification items worth re-running.

Bidirectional Task Links

handoff_update_task(requirement_ids=[...]), introduced in v0.36, creates bidirectional links between tasks and requirements. When a task's status changes, the development stage of its linked requirements follows automatically (all tasks done → implemented). v0.37 adds link roles — implements (for implementation tasks) and executes (for test tasks) — so the two are tracked separately.

Custom Layers and Profiles

Beyond the six built-in layers, define project-specific layers in config.toml with [[trace.layer]]. Profiles (minimal, standard, full, bugfix, or custom) select which layers are active, and individual documents can override the project default.

Key New Tools (v0.36–v0.37)

Install / Update

npx handoff-mcp-server@latest

If you're using it as a Claude Code plugin:

/plugin install alphaelements/handoff-mcp

View Handoff case studies