Co-VibeDocs

Engineering

MCP Overlap Contract#

This file expands the overlap-specific stage-2 protocol referenced by mcp-contract.md.

Overlap Detection v2 (agent-judge)#

Duplicate-work warnings are precise: the server retrieves candidates, and the session's own agent judges whether its task is the SAME SCOPE as each. The server records the verdict and gates the start on it.

covibe_task Check (Stage 1)#

Optional input scope: a short "what this work actually is", richer than the title. It is folded into retrieval (embedding + lexical) and shown to the judge.

Optional precision inputs are additive and never reduce recall:

  • action: create|modify|remove|fix|audit
  • component: a layer tag up to 40 chars, such as server, client, db, or ui

A different declared component, or an opposed action, is treated as different work and will not escalate even on near-identical text. Both persist on the task and help the next agent's check. overlap-precision.md covers the signal set.

Stage 1 retrieves open, recent, and reserved work, then escalates only strong, non-divergent, non-low-information candidates from still-open work. No strong candidate means status: "ok", data.candidates: [], and data.requires_verdict: false. Matches against done/cancelled work inform (they appear in data.matches with their status) but never escalate and never block.

Weak warn-floor matches are still recorded for the dashboard, and they are fully disclosed: whenever a warning is recorded the check response carries warning_id plus data.matches with each match's score and human reason — even when requires_verdict is false. A warn-floor warning is visibility only; it never gates the start (see Stage 2). Strong candidates return status: "warning" with the judge instruction in feedback.required_action and:

json
{
  "warning_id": "warn_123",
  "check_id": "chk_456",
  "requires_verdict": true,
  "candidates": [
    {
      "id": "task_1",
      "type": "task",
      "title": "...",
      "scope": "...",
      "owner": "hakan",
      "status": "active",
      "repo": "co-vibe",
      "score": 0.79,
      "reason": "Semantically similar (79%) to \"...\"."
    }
  ],
  "matches": []
}

Candidates carry the same score + reason evidence the workstream check exposes, so the judging agent sees what the engine saw. data.matches repeats the full warn-floor list in the same shape.

A candidate with "type": "intent" is another agent's live reservation: work that has been checked but not yet started. Reservations close the simultaneous-start race. Two agents checking the same brand-new scope before either starts now see each other's intent as a candidate. Reservation hygiene:

  • a re-check by the same developer with the same title+scope fingerprint REPLACES the prior reservation — never duplicates it
  • plan, start, and start_planned consume the developer's matching reservation, so the real task row becomes the only candidate
  • a reservation can surface as an escalated candidate only at/above the escalation threshold; below it, it informs via data.matches and never blocks anyone
  • reservations have a short TTL and lazily expire

Start / Start Planned (Stage 2)#

New inputs:

  • check_id: the id returned by the matching operation: "check". Required when the warning carries requires_verdict.
  • scope_verdict: { "same_scope_candidate_ids": ["task_1"], "reason": "..." }

The start is bound to the check by session plus a fingerprint of title, scope, and repo, so a check for one scope cannot authorize a different start.

Start blocks ONLY on the escalated path: when the bound warning carries requires_verdict, a missing/stale check_id, a missing scope_verdict, unknown candidate ids, or a confirmed duplicate without confirmation_reason each block with a required_action that names the exact field to send next.

Weak warn-floor warnings (requires_verdict = 0) NEVER block a start — they are dashboard visibility only. The start proceeds with no extra fields; the warning stays pending for the dashboard unless the agent explicitly resolves it (matching check_id + empty verdict dismisses it; the legacy warning_id + confirmation_reason shape still confirms it). The live detection battery (2026-06-09) measured the old behavior — weak warnings silently hard-blocking starts — at a 7/7 false-block rate on non-duplicate traps with scores as low as 29%, which is why this gate is escalation-only now.

Candidates that completed or were cancelled between check and start drop from the required set. If none remain live, the warning auto-clears. The same liveness rule applies to covibe_workstream start: a warning whose matches are all done/cancelled auto-dismisses instead of blocking.

Started work is stamped with an overlap_status derived from how the warning resolved: confirmed only when the agent confirmed a duplicate, warning when a weak warn-floor warning is still pending, otherwise clear.

On a passing verdict the server records one scope_verdicts row per candidate with the stage-1 score and scope fingerprints, resolves the warning, and writes a scope.judged work event.

The warning resolves as confirmed when a duplicate was confirmed, otherwise as dismissed from the agent's reason.

Activation Re-check (start_planned)#

covibe_task and covibe_workstream operation: "start_planned" re-run overlap retrieval at activation time, because work can start between planning (or the agent's fresh check) and activation. The re-check folds in live intents and applies the same escalation bar and cooldown as Stage 1.

If strong candidates emerge that the bound check's warning does not already cover, the start does NOT proceed. It records a new requires_verdict warning plus preflight and returns status: "warning" with the standard escalation shape — warning_id, a NEW check_id, requires_verdict: true, and candidates. The agent judges the candidates and retries start_planned with that check_id and a scope_verdict; the retry flows through the same scope-verdict gate as a direct start (confirmed duplicates still need confirmation_reason). Candidates the bound check already escalated do not re-trigger the re-check — the gate enforces their verdict instead.

The re-check writes a task.checked / workstream.checked work event with payload.activation_recheck: true so audits can tell server re-checks from agent-called preflights.

Cooldown#

Once an agent judges a candidate NOT a duplicate, the server stops re-escalating that same source-to-candidate pair on later checks until either side's title or scope text changes. A new fingerprint re-opens the evaluation.

The trust model is to trust the agent's verdict; the dashboard Audit signal is the backstop.

View as .md