Spec Sub-Spec: breezing-and-bridge

This sub-spec is part of the spec.md product contract. SSOT order is spec.md core > docs/spec/* sub-specs > Plans.md.

HARNESS_AUTO_APPROVE=on (strict literal on only; true / 1 / ON / yes are rejected) is currently ledger instrumentation only. It records the enablement gate and prereq check result; it does not skip approval prompts or wire any approval-skip branch. The retained scope predicate autoapprove.AppliesTo(path, worktreeRoot) returns false for any path outside the worktree root, so the 5-category runtime floor and wt fingerprint containment continue to adjudicate worktree-external attempts and remain non-overridable by HARNESS_AUTO_APPROVE. The switch is gated on three prereqs being demonstrably done (Phase 92.1.1 parallel base hygiene, 92.2.3 team dispatch hardening, 96.1.2 3-CLI hook parity); if any prereq is missing the gate fail-safes to OFF regardless of the env value. The gate decision is recorded on every harness work --team dispatch through the orchestration ledger. Approval automation will be wired only after HOTL governance verification (Phase 101 U0-U7 evidence).

Breezing Brief Contract

/breezing may accept free-text input that does not match the existing argument-hint surface (all, task ranges, --codex, --cursor, --reviewer-only, --parallel N, --no-commit, --no-discuss, --auto-mode). This contract productizes the Brief Composer and Decision Card schemas, breezing mem write layer, and their precedence against the runtime hard floor. It builds on Tri-Tool Parallel Collaboration Contract (team orchestrator, worktree discipline) and Memory Contract (harness-mem when available); it does not replace them.

Input classification and brief-card.v1

• scripts/breezing-brief.sh classify "<args>" deterministically classifies input as structured or free-text (regex/token parse; no LLM).
• structured input continues on the existing team path unchanged.
• free-text input is decomposed by the Lead into a brief-card.v1 card for user confirmation before any worktree dispatch.
• User confirmation is Yes/No. scripts/breezing-brief.sh confirm no emits DISPATCH: 0 — zero worker executions (dry contract). Yes dispatches one worker per confirmed subtask onto the existing worktree-per-task team path.
• scripts/breezing-brief.sh validate <card.json> validates against templates/schemas/brief-card.v1.json.

Schema brief-card.v1 required fields:

Field	Shape	Constraints
goal	string	non-empty
subtasks	array	3–7 items; each item \{id, title, dod\} (all non-empty strings)
scope_files	string[]	repo-relative paths in scope
risk_notes	string[]	free-form risk strings
confidence	enum	high | medium | low

No additional properties are permitted on the card root or subtask objects.

judgment-card.v1

When a worker or Lead needs human judgment during breezing — and the runtime hard floor does not apply — Harness may issue one judgment-card.v1 card. Schema: templates/schemas/judgment-card.v1.json.

Issuance conditions (any one triggers a card):

1. DoD interpretation diverges (multiple valid readings of done-ness).
2. A change outside the user-approved scope is required.
3. A trade-off choice is required (mutually exclusive options).

Required fields:

Field	Shape	Constraints
question	string	non-empty
options	array	2–3 items; each \{id, label, consequence\} (all non-empty strings)
recommendation	string	non-empty
confidence	enum	high | medium | low
impact	string	non-empty
diff_summary	string	non-empty one-line diff summary

No additional properties are permitted on the card root or option objects. User answer and rationale may be recorded via harness_mem_record_checkpoint when harness-mem is available (fail-open; see below).

Breezing mem lifecycle events

go/internal/breezingmem posts breezing lifecycle events to harness-mem (POST /v1/events/record) and ingests the confirmed brief (POST /v1/ingest/knowledge-file at path breezing/brief-card.v1.json, kind decisions_md). Event type literals (fixed):

Event type	When
breezing_run_started	Breezing team run begins
breezing_brief_confirmed	User confirms the brief card (Yes)
breezing_worker_result	One worker completes (success or failure)
breezing_aggregation_completed	Lead aggregation finishes

This layer does not call workgraph signal APIs (signal_send, signal_read, signal_ack, or /v1/signals/*). Durable cross-session handoff remains in harness-mem signal store per Tri-Tool Parallel Collaboration Contract; breezing mem events are run-scoped lifecycle telemetry only.

Fail-open memory behavior

Breezing must never stop because harness-mem is absent or unreachable.

State	Behavior
not-configured	Silent skip — no warning, no POST
unreachable	One stderr warning line (breezing-mem: record skipped (unreachable) or ingest equivalent), then continue

Configured means ~/.harness-mem or legacy ~/.claude-mem exists (see go/internal/breezingmem configured()). HTTP timeout is 1s. Mem state never blocks brief confirmation, worker dispatch, judgment cards, or aggregation.

Floor precedence over judgment cards

The five-category runtime action hard floor (Phase 92.2.1; money/billing, external send/egress, credential/secret read, production deploy/publish, destruction outside the task worktree) always takes precedence over judgment-card.v1:

• When any hard-floor category matches, Harness hard-stops for the human and does not issue a judgment card.
• Judgment cards apply only to non-floor ambiguity (DoD, scope, trade-offs).
• The pre-merge policy gate (go/internal/floor) and runtime hard floor remain distinct; see Tri-Tool Parallel Collaboration Contract.

Bridge Daemon Contract

The Bridge Daemon normalizes events from three CLI backends (CC Mailbox, Cursor stop hook, Codex app-server) into one source-agnostic envelope, persists them in a unified mailbox store, optionally ingests into harness-mem by lane, and delivers notices to non-CC peers through host hooks. It builds on Tri-Tool Parallel Collaboration Contract (Mode 2 live notice) and Breezing Brief Contract (fail-open memory); it does not replace durable work-handoff in harness-mem signal store.

bridge-event.v1

Schema: templates/schemas/bridge-event.v1.json. Every normalized event uses this envelope; no additional root properties are permitted.

Field	Shape	Constraints
source	enum	cc | cursor | codex
event_type	string	non-empty
payload	object	source-specific fields after normalization
ts	integer	Unix nanoseconds; required (missing timestamp is fail-loud)

Go reference: go/internal/bridge.Event (Source, EventType, Payload, TS).

Source adapter contract

Three adapters implement bridge.Adapter (Source() + Normalize(raw []byte)). Each maps one source-specific raw JSON input to exactly one bridge-event.v1 event (batching is caller responsibility).

Adapter	Source	Raw input keys	Normalized event_type
CC Mailbox	cc	hook_event_name, timestamp	value of hook_event_name
Cursor stop hook	cursor	hook_event_name, ts	fixed stop
Codex app-server	codex	type, ts	value of type

Adapter rules:

• Missing or invalid ts / timestamp is fail-loud (requireNanos error); the event is not appended.
• Unregistered source on bridge.Registry.Normalize returns (Event\{\}, false, nil) — fail-open skip; the caller emits one warning line (the registry package does not write stdout).
• Payload fields are copied per adapter (conversation_id, tool_name, session_id, message, thread_id, etc.) with non-reserved keys merged into payload.

Delivery layer

Notice delivery to peers uses host hooks (Phase 92.6.2 delivery-notice pattern, extended for bridge daemon non-CC peers):

Host	Delivery path
Claude Code	Monitor blocking stream (SessionStart hook)
Cursor 1.7+	Stop hook followup_message
Codex	Bash PreToolUse hook coupling

When delivery fails, Harness must not block the run: emit one warning line, record the failure in the orchestration ledger, and fallback on the next turn (turn-boundary inbox read). Codex and Cursor fall back to turn delivery when Monitor is unavailable.

Mailbox unified store

go/internal/mailbox.Store persists normalized events in SQLite WAL mode as an append-only event log (bridge_events table). Each append selects a lane:

Lane	Mem ingest
fast	Record only
gate	Record + Audit
release	Record + Alert

Ingest runs asynchronously after append; ingest errors are logged and swallowed (fail-open). MemIngestor defaults to NoopIngestor when harness-mem is not wired.

This store is distinct from Phase 92.6.1 livemsg (Mode 2 peer messaging) and from harness-mem signal store (durable work-handoff).

Fail-open memory behavior (bridge read/write)

Bridge and mailbox layers must never stop a breezing or bridge run because harness-mem is absent or unreachable. Same tri-state model as Breezing Brief Contract:

State	Behavior
not-configured	Silent skip — no warning, no POST
unreachable	One stderr warning line, then continue

Configured means ~/.harness-mem or legacy ~/.claude-mem exists (see go/internal/breezingmem configured()). HTTP timeout is 1s.

Channels-Wake

Phase 98.2 adds an opt-in recovery layer for Bridge Daemon communication channels (live-messaging / delivery / inbox hooks). It monitors channel health and may propose hook re-injection when unhealthy; it does not restart daemons or auto-approve actions.

Configuration lives at ~/.harness-bridge/channels.json (override with HARNESS_BRIDGE_HOME). Required keys when enabled:

Key	Purpose
socket_path	Unix domain socket for Bridge Daemon probe
mailbox_db	SQLite WAL mailbox store (bridge_events)
stale_after_seconds	Max age of newest mailbox event before corrupted

Tri-state health (active-watching-test-policy, D40):

State	reason	healthy	CLI exit	Session Monitor warning
Opt-in not used	not-configured	true	0	none
Daemon down / socket unreachable	daemon-unreachable	false	1	yes
Invalid config / stale mailbox	corrupted	false	1	yes
OK	""	true	0	none

CLI: harness channels-wake check emits JSON \{healthy, reason\}. Implementation: go/internal/channelswake.Check().

Wake trigger scope (Lead decision, Phase 98.2): hook re-injection proposal only, opt-in via HARNESS_CHANNELS_WAKE_OPT_IN=1 in scripts/channels-wake-probe.sh. AUTO_APPROVE_DEFAULT=false is preserved. Risk Gate 5-category runtime floor (money-billing, egress, secret-read, prod-deploy, worktree-escape) remains non-overridable.

Event schema: templates/schemas/channel-wake-event.v1.json (channel-wake-event.v1, additionalProperties: false).

workgraph signal boundary

Bridge Daemon, mailbox ingest, and breezing mem lifecycle must not call workgraph signal APIs (signal_send, signal_read, signal_ack, or /v1/signals/*). Durable cross-session handoff remains in harness-mem signal store; bridge events are run-scoped telemetry and live-notice input only.