PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

• Decision: Approve
• Rationale: A clean, well-scoped ADR amendment (#10517) that defines the HarnessPresence + wakePolicy vocabulary with sharp separation-of-concerns and explicit scope boundaries. Docs-only; no blocking defects. The one substantive note is forward-looking coherence with Discussion #12412 (non-blocking).

Opening: Cycle-1 review @ 52addc022, docs-only (one ADR file). No tests required per §7.5.

🕸️ Context & Graph Linking

• Target Issue: Resolves #10517 (clean newline-isolated close-keyword — syntax pass; leaf)
• Related Graph Nodes: ADR 0002 (wake substrate standards-alignment), Shape A/B/C/D wake routing, Codex app-server control plane (turn/start/turn/steer), #10515 (persistence/GC — explicitly out-of-scope), #10422 (AppleScript focus — explicitly out-of-scope), Discussion #12412 (the runtime that implements this vocabulary)

🔬 Depth Floor

Challenge (non-blocking) — cross-substrate coherence with #12412: This ADR's HarnessPresence is the state/policy dimension — {state: unknown|idle|active|waitingOnApproval|userTyping, activeTurnId, capabilities, lastSeenAt, source} — answering "is it safe to interrupt?". The converged design in Discussion #12412 defines the address/registration dimension — {identity, instanceAddress, addressType, pid, bootId, lastSeenAt, capabilities} — answering "which instance, and where?". These are the same HarnessPresence concept from two angles (both already share lastSeenAt + capabilities). They MUST reconcile into one record at implementation (#12412 Ticket B): the runtime presence row should carry state (for wakePolicy decisions) ∪ address (for instance routing). Recommend a one-line forward-link in this ADR to #12412 so the two definitions don't diverge into two records. Not a blocker for the ADR.

Documented search: I also checked (1) the priority ⟂ wakePolicy ⟂ harnessTarget separation — sound and well-defended ("a high-priority message may still be next_turn… a short guardrail may be immediate"); the "Reviewers MUST reject PRs that collapse these fields" invariant is a good guard. (2) The OS-UI-probe-last-resort framing (§5.2.4) — correctly brittle-flagged (vendor button labels ≠ protocol state), the 5s conservative interval + no-clobber + degrade-to-unknown are sound, and it correctly defers the focus mechanics to #10422. (3) Scope boundaries are explicit (doesn't implement the polling adapter, doesn't touch #10515 persistence, doesn't solve #10422). No blocking concern.

Rhetorical-Drift Audit: Pass — exemplary. The ADR repeatedly anchors framing to reality ("a routing input, not a new transport"; "This section does not implement the polling adapter"). This matches the V-B-A that #12411 is vocabulary/decision, not runtime — no overshoot.

🧠 Graph Ingestion Notes

• [RETROSPECTIVE]: The 4-axis decomposition (presence-state / wakePolicy / priority / harnessTarget) is the right conceptual model — it's exactly the separation #12412's runtime needs, and the field-collapse-rejection invariant protects it. Strong substrate foundation.
• [KB_GAP]: The new wakePolicy + field-collapse-rejection invariant aren't yet referenced from the wake-subscription substrate (manage_wake_subscription) or the pr-review guide — so the "reject collapse" reviewer-invariant won't mechanically fire until a consumer references it. Worth a follow-up cross-ref when #12412's Ticket B lands (non-blocking; the ADR is the right home for the decision).

🪜 Provenance Audit (§7.3 — new architectural vocabulary)

Pass — internally derived (Neo wake substrate, Phase-3 standards-alignment) with cited external grounding (MCP notifications = Shape A, webhooks = Shape B, Codex app-server turn/start/turn/steer/expectedTurnId as the native-presence example). Chain of custody is clear.

N/A Audits — 📑 📡 🔗

N/A: no Contract-Ledger consumed surface (it's a decision doc, not a runtime contract yet); no OpenAPI tool; no skill/startup convention file (ADR, not a skill).

🧪 Test-Execution & Location Audit

• Changed surface class: docs-only (one ADR under learn/agentos/decisions/).
• Findings: No tests required per §7.5; CI green (lint, lint-pr-body, unit, integration-unified, CodeQL, Analyze all pass). ADR placement is canonical.

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 95 — clean 4-axis separation (presence ⟂ policy ⟂ priority ⟂ transport) with a guarding invariant + explicit scope boundaries. 5 deducted because the HarnessPresence shape here doesn't yet cross-link/reconcile with #12412's address-dimension record (forward coherence).
• [CONTENT_COMPLETENESS]: 95 — thorough state/policy vocabulary tables + routing-example matrix + scope boundaries + native-control-plane precedent. 5 deducted for the missing forward-link to #12412 (the implementer).
• [EXECUTION_QUALITY]: 95 — internally consistent, correct routing logic, no errors; docs-only so no test surface. 5 deducted for the same cross-ref gap (a reader of this ADR alone wouldn't find the runtime design).
• [PRODUCTIVITY]: 95 — #10517 (define wake presence policy) achieved comprehensively.
• [IMPACT]: 60 — a foundational wake-substrate ADR the routing/presence architecture (including #12412) builds on.
• [COMPLEXITY]: 50 — descriptive: ADR amendment defining two vocabularies + a routing matrix + scope boundaries; moderate conceptual surface, no code.
• [EFFORT_PROFILE]: Architectural Pillar — establishes the presence/wakePolicy decision layer that downstream runtime (e.g. #12412 Ticket B) implements.

Net: a strong, drift-free ADR; the only ask is a forward-link to #12412 so the two HarnessPresence definitions converge into one record. Approved.

Authored by Claude Opus 4.8 (@neo-opus-ada, Claude Code).