beadboard/docs/protocols/operative-protocol-v1.md

Operative Protocol v1 (Session Constitution)

Date: 2026-02-14
Status: Approved for implementation
Scope: bb-u6f.6.1
Applies to: bb-u6f.6.2, bb-u6f.6.3, bb-u6f.6.4, bb-u6f.6.5

1. Purpose and Boundaries

This protocol defines non-negotiable coordination behavior for multi-agent work in BeadBoard Sessions.

Boundaries:

1. Work lifecycle state remains Beads-native (bd commands only).
2. Agent coordination state lives in bb agent surfaces and supporting local stores.
3. No direct writes to .beads/issues.jsonl.
4. User-facing labels must stay plain language.

2. Normative Language

1. MUST: required behavior.
2. SHOULD: recommended unless explicit exception is justified.
3. MAY: optional behavior.

3. Identity Trust Model

3.1 Identity primitives

Every active session has:

1. session_agent_id: unique working identity for the current runtime.
2. logical_agent_id: persistent persona name used in coordination records.

For v1 implementation, both map to the same field (agent_id), but contract keeps room for split in future.

3.2 Adoption policy (resume prior identity)

Identity adoption is allowed only when at least one condition is true:

1. Uncommitted changes exist in target scope (git status --porcelain contains files in claimed scope).
2. Target identity owns at least one in_progress bead relevant to current scope.

If neither condition is true, adoption MUST be rejected in non-interactive mode and SHOULD require explicit confirmation in interactive mode.

3.3 Session uniqueness policy

1. Each runtime session MUST start with a unique identity name for that session, unless valid adoption is selected.
2. Reusing previous identity without adoption checks is forbidden.
3. Recommended naming style is adjective-noun (for example, amber-otter, cobalt-harbor).

3.4 Mandatory resume audit signal

Any successful identity adoption MUST emit a RESUME protocol event with:

1. prior owner identity,
2. adoption reason (uncommitted_scope or in_progress_ownership),
3. linked bead id(s) when known.

Event must be persisted in coordination history exposed to Sessions APIs.

4. Heartbeat and Liveness Contract

4.1 Environment and defaults

1. BB_AGENT_STALE_MINUTES default: 15.
2. Stale threshold: T_last_seen + stale_minutes.
3. Eviction threshold: T_last_seen + (2 * stale_minutes); default 30 minutes.

4.2 Heartbeat behavior

1. bb agent heartbeat --agent <id> MUST update last_seen_at in UTC ISO-8601.
2. Heartbeat command MUST be idempotent and safe to run repeatedly.
3. Heartbeat command MUST support JSON envelope output (ok, command, data, error).

4.3 Liveness states

Derived states:

1. active: now < stale threshold.
2. stale: stale threshold <= now < eviction threshold.
3. evicted: now >= eviction threshold.

4.4 Reservation interaction rules

For scope takeover:

1. If reservation owner is active: takeover MUST fail.
2. If owner is stale: takeover MAY succeed only when --takeover-stale is supplied.
3. If owner is evicted: takeover SHOULD succeed with --takeover-stale; prior reservation must be archived as expired.

5. Path Overlap Canonicalization Contract

5.1 Normalization pipeline

All scope comparisons MUST use the same normalization pipeline:

1. Resolve to absolute path (path.resolve).
2. Normalize separators to /.
3. On Windows, lowercase normalized path for comparisons.
4. Remove trailing slash except root.

5.2 Scope classes

Given normalized A and B:

1. exact: A === B.
2. partial: A is parent of B or B is parent of A.
3. disjoint: neither exact nor parent-child.

Wildcards:

1. Prefix wildcard (src/*) is treated as directory prefix match for overlap checks.
2. Glob semantics beyond suffix * are out of scope for v1.

5.3 Required examples

1. src/* vs src/lib/parser.ts => partial.
2. src/lib vs src/lib/parser.ts => partial.
3. src/lib/parser.ts vs src/lib/parser.ts => exact.
4. src/lib vs src/components => disjoint.

6. Protocol Event Schema (Stable JSON Contract)

6.1 Envelope (all protocol events)

{
  "id": "proto_20260214_001",
  "version": "v1",
  "event_type": "HANDOFF",
  "project_root": "C:/Users/Zenchant/codex/beadboard",
  "bead_id": "bb-u6f.6.3",
  "from_agent": "amber-otter",
  "to_agent": "cobalt-harbor",
  "scope": "src/components/sessions/*",
  "created_at": "2026-02-14T18:05:11.000Z",
  "payload": {}
}

Required fields:

1. id
2. version (must be v1 for this protocol)
3. event_type
4. project_root
5. bead_id
6. from_agent (nullable for system-originated events only)
7. to_agent (nullable for system-originated events only)
8. scope (nullable where not applicable)
9. created_at
10. payload

6.2 Event-specific payloads

HANDOFF payload:

1. subject (required)
2. summary (required)
3. next_action (required)
4. requires_ack (required, true by default)

BLOCKED payload:

1. subject (required)
2. blocker (required)
3. requested_action (required)
4. urgency (required: low|medium|high)
5. requires_ack (required, true)

INCURSION payload:

1. incursion_kind (required: exact|partial)
2. owner_agent (required)
3. incoming_agent (required)
4. owner_liveness (required: active|stale|evicted)
5. resolution_hint (required)

RESUME payload:

1. resume_reason (required: uncommitted_scope|in_progress_ownership)
2. prior_session_agent (required)
3. adopted_agent (required)
4. evidence (required string summary of why adoption passed)

6.3 UI mapping requirements

Sessions UI mapping contract:

1. HANDOFF label: Passed to
2. BLOCKED label: Needs input
3. Read action label: Seen
4. Ack action label: Accepted

INCURSION and RESUME MUST render as first-class protocol rows in the conversation timeline, not hidden diagnostics.

7. CLI Contract Requirements for Implementers

Required commands for v1 rollout:

1. bb agent heartbeat --agent <id> [--json]
2. node scripts/bb-init.mjs --non-interactive --json
3. node scripts/bb-init.mjs --adopt <agentId> --json
4. node scripts/bb-init.mjs --register <name> --json

Non-interactive requirements:

1. MUST not prompt.
2. MUST fail with structured error when decision cannot be made safely.
3. MUST include deterministic recommendation reason in output.

8. Mapping to Existing Code Modules

8.1 Backend

1. src/lib/agent-registry.ts
2. src/lib/agent-reservations.ts
3. src/lib/realtime.ts
4. src/lib/agent-sessions.ts

8.2 API

1. src/app/api/sessions/route.ts
2. src/app/api/sessions/[beadId]/conversation/route.ts

8.3 UI

1. src/components/sessions/session-feed-card.tsx
2. src/components/sessions/session-task-feed.tsx
3. src/components/sessions/conversation-drawer.tsx
4. src/components/sessions/sessions-page.tsx
5. src/hooks/use-session-feed.ts
6. src/hooks/use-beads-subscription.ts

8.4 CLI and skill

1. tools/bb.ts
2. scripts/bb-init.mjs (new)
3. skills/beadboard-driver/SKILL.md

9. Acceptance Checklist for Downstream Beads

bb-u6f.6.2 MUST implement:

1. heartbeat mutation,
2. stale/evicted derivation,
3. overlap classification,
4. protocol event emission.

bb-u6f.6.3 MUST implement:

1. heartbeat command,
2. non-interactive bb-init contract and flags.

bb-u6f.6.4 MUST implement:

1. protocol event rendering in Sessions,
2. incursion/stale visibility,
3. no-refresh-required update behavior.

bb-u6f.6.5 MUST implement:

1. updated skill flow matching this protocol exactly.

10. Rejected Alternatives

1. Interactive-only bootstrap prompts. Reason: automation sessions require deterministic non-blocking behavior.

2. Implicit overlap inference without normalization contract. Reason: inconsistent behavior across Windows paths.

3. UI-first implementation before protocol schema. Reason: high risk of repeated API/UI contract churn.