PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

• Decision: Approve
• Rationale: Approve over Approve+Follow-Up because there are no blocking defects and the one seam I found (orphaned componentRef restore behavior) is a genuine non-blocking follow-up, not a release-blocking gap — the contract is internally complete and correctly scoped to the data model. Not Request Changes: nothing blocks substrate correctness, CI is 7/7 green, and the generated surfaces verify clean.

Peer-Review Opening: Clean, well-scoped contract, Euclid. The serializable-vs-runtime boundary — and explicitly excluding PATs/credentials from the persisted model — is exactly the right Neo shape, and rejecting the four alternatives with rationale makes the ownership decision legible. One non-blocking seam noted below; otherwise eligible for merge.

🧭 Patch-Blind Premise Snapshot

• Inputs Read Before Patch: #13061 (leaf ticket), ADR 0020 (harness concept anchor — the source-of-authority naming the QT-docking gap), the changed-file list, the existing Neo substrates the contract composes with (src/layout/*, src/dashboard/Container, src/manager/Window), ADR 0018 (generated-SEO governance), and the tree.json-mirrors-folder invariant.
• Expected Solution Shape: A markdown contract defining a serializable JSON dock model + node-type taxonomy + serializable-vs-runtime boundary + ownership/placement decision, registered in tree.json, with llms.txt/sitemap.xml regenerated (not hand-edited). Must NOT hardcode runtime state (DOMRect/windowId/live instances/credentials) into the persisted model, and must compose with existing substrates rather than fork a docking engine.
• Patch Verdict: Improves. Exceeds the minimal shape — explicit serializable-exclusion list (incl. PATs/credentials/functions), a 3-step code-ownership decision tree, and four rejected-alternatives with rationale. Generated SEO verified regenerated, not hand-edited (see Generated-Surface note).

🕸️ Context & Graph Linking

• Target Issue: Resolves #13061
• Related Graph Nodes: Epic #13012; ADR 0020; Refs #13030 / #13025 / #13028.

🎯 Close-Target Audit

• Close-targets: #13061 (Resolves). Epic #13012 correctly Related: (non-closing); Refs extras non-closing.
• #13061 labels = [enhancement, design, ai, architecture] — not epic-labeled (verified via gh issue view). ✓
• Findings: Pass.

🧷 Generated-Surface (SEO) Verification

The PR touches Class-2 generated files (apps/portal/llms.txt, sitemap.xml — ADR 0018: never hand-edit). Verified regenerated, not hand-edited: tree.json (generator input) gains leaf id: agentos/HarnessDockZoneModel under AgentOS, and llms.txt + sitemap.xml (output) carry the matching entry in the same structural slot, with a generator-format <lastmod> and a minimal incremental diff (no other entries perturbed). Input↔output consistency = a clean generator run. ✓

🔬 Depth Floor — Challenge

Orphaned componentRef resolution at restore is under-specified. Item records define componentRef as "used by the rendering adapter to locate or create the component," but the contract doesn't define behavior when a persisted item references a component that no longer exists or can't be created (removed class, stale blueprint). Since the contract's stated purpose is "so those leaves do not invent incompatible object models," restore-robustness is exactly the dimension where consuming leaves will each improvise. Non-blocking — a model contract may defer this — but a one-line "unresolvable componentRef is adapter-defined (future slice)" acknowledgment, mirroring how the doc already defers detached-window restore, would close the seam. Follow-up, not a blocker.

🔗 Cross-Skill Integration Audit

New doc is discoverable: registered in tree.json nav + linked from ADR 0020 with an honest "contract pointer, not an ADR amendment" clause. No skill / workflow / MCP convention introduced, so no predecessor-skill update needed. Pass.

🧠 Graph Ingestion Notes

• [RETROSPECTIVE]: The serializable-vs-runtime split (persist semantic splits/tabs/order; exclude DOMRect/windowId/live-instances/PATs/credentials) is the correct worker-owned, multi-window, JSON-first shape — a reusable template for future harness persistence contracts, not just docking.

N/A Audits — 📑 🪜 📡 🧪

N/A across listed dimensions: docs-only model-contract — no consumed code surface yet (📑 the doc is the contract, implementation deferred), no runtime ACs beyond the declared Evidence: L1 static audit (🪜), no openapi.yaml touched (📡), no tests required for a docs change (🧪).

📋 Required Actions

No required actions — eligible for human merge.

(Non-blocking suggestion only: the one-line stale-componentRef note above, if a quick polish is wanted.)

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 100 — I actively considered (a) does it fork a parallel docking engine [no — maps to hbox/vbox/card + adapts dashboard/sort-zone], (b) does it persist runtime state [no — explicit exclusion list], (c) does it break worker-owned JSON [no — pure JSON; live instances excluded]; none apply.
• [CONTENT_COMPLETENESS]: 90 — 10 deducted: orphaned/unresolvable componentRef restore behavior is under-specified (locate-or-create stated; not-found path undefined) — the one seam in an otherwise comprehensive contract (model + node types + item records + serializable boundary + operations + rejected alternatives + ownership tree, all with @summary).
• [EXECUTION_QUALITY]: 100 — verified: embedded JSON example parses clean and is id-consistent; SEO regenerated-consistent (input↔output match, not hand-edited); tree.json mirror correct (leaf id↔path, parent AgentOS backed); CI 7/7 green. No execution defects found.
• [PRODUCTIVITY]: 100 — #13061's sole goal (define the dock-zone model contract) fully delivered; the contract is complete and composable.
• [IMPACT]: 70 — anchors the entire harness docking line (multiple future leaves consume it to avoid incompatible object models), but ships as a contract/doc pre-implementation, not running code.
• [COMPLEXITY]: 45 — Moderate: one new doc + ADR pointer + tree.json + SEO regen, no code paths; but real cognitive load — an implementer must internalize the serializable-vs-runtime boundary + node taxonomy + operation semantics before building a consuming leaf.
• [EFFORT_PROFILE]: Quick Win — high ROI (prevents incompatible object models across the docking line) at low complexity (docs-only, composes with existing substrates, zero new code).

Nicely done — approving. The contract reads like it'll save the downstream rendering/persistence leaves real rework.