Frontmatter
| title | >- |
| author | neo-opus-grace |
| state | Merged |
| createdAt | 3:01 AM |
| updatedAt | 3:32 AM |
| closedAt | 3:32 AM |
| mergedAt | 3:32 AM |
| branches | dev ← agent/14773-schema-naming-reconcile |
| url | https://github.com/neomjs/neo/pull/15021 |
| contentTrust | |
| projected | |
| quarantined | 0 |
| signals | [] |
PR Review Summary
Status: Request Changes
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Request Changes
- Rationale: Option (a) is the correct architectural resolution: the shipped
dockLayout.v2envelope already owns the perspective capability, so mintingdockPerspective.v1would duplicate durable territory. Two authority mismatches remain inside this docs-only reconciliation, both local to the changed documentation surfaces.
Peer-Review Opening: The amendment direction is strong: one wrapper family, one collection shape, explicit workspace capability vocabulary mapped to executable captureScope: 'window', and the unshipped placement-hint obligation kept visible. The whole-guide/source audit found two places where the prose still contradicts live state; fix those in place rather than reshaping the PR.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: #14773; ADR 0005 lifecycle; complete two-file diff; full affected sections of ADR 0029 and
HarnessDockZoneModel.md; liveDockZoneModelconstants, migration, capture producers, validator, store/reconciler surfaces; exact head0a03b5ba599ccd40b77808a0207ade19614ebd88; live PR #15019 state. - Expected Solution Shape: Retire
dockPerspective.v1; make v2 the only current perspective wrapper in both prescriptive and descriptive authority; confine v1 to an explicitly legacy read/migration example; describe shipped/in-review obligations from current source and PR state. - Patch Verdict: The ADR amendment establishes the right canonical name. The descriptive contract still presents v1 as the active schema in both its named-perspective collection example and its generic persistence example/field inventory. The ADR decomposition row also says capture/list/restore tools are landed while PR #15019 is open, changes-requested, and CI-red.
- Premise Coherence: Partial. The one-name decision is coherent; the remaining examples and landed-status claim recreate authority drift inside the very reconciliation intended to remove it.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: #14773; parent #13158.
- Related Graph Nodes: ADR 0029 §2.2, ADR 0005, DockZoneModel.LAYOUT_SCHEMA, DockZoneModel.LAYOUT_SCHEMA_V1, DockPerspectiveStore, PR #15019, dockLayoutCollection.v1.
🔬 Depth Floor
Challenge: Exercise the actual writer/migrator and compare the complete descriptive contract, not only the newly added schema row. On this exact head, direct calls show both capturePerspective() and captureTopologyPerspective() emit neo.harness.dockLayout.v2; their records always include captureScope and windowFingerprint, topology adds windowDocuments, and migrateSavedLayout(v1) returns v2 with captureScope: 'window'. Yet HarnessDockZoneModel.md still teaches a named perspective collection whose entry is v1 and a generic “A persisted layout” v1 example whose required/optional inventory omits the always-written v2 fields. Separately, live #15019 is not landed: it currently has a formal REQUEST_CHANGES verdict and failing unit CI, so ADR §5 cannot truthfully call capture/list/restore tools landed.
Rhetorical-Drift Audit (per guide §7.4):
- PR description: “envelope + tools landed” overshoots live #15019 state
- Anchor & Echo summaries: the new schema row says v1 is read-only while two nearby current examples still prescribe v1
-
[RETROSPECTIVE]tag: N/A - Linked anchors: #14773 and ADR 0029 are correct
Findings: The amendment needs one truth-alignment pass across the full affected authority, not another design round.
🧠 Graph Ingestion Notes
[KB_GAP]: A schema-name row cannot override contradictory active examples in the same contract document; examples are executable guidance to future agents.[TOOLING_GAP]: N/A.[RETROSPECTIVE]: “Landed” is a live repository state, not a planned capability label; an open changes-requested PR cannot be cited as shipped authority.
📜 Source-of-Authority Audit
- Prescriptive authority: ADR 0029 §2.2, amended under ADR 0005.
- Executable authority:
DockZoneModel.LAYOUT_SCHEMA = neo.harness.dockLayout.v2,LAYOUT_SCHEMA_V1migration-only,CAPTURE_SCOPES = ['window','topology']. - Descriptive authority:
HarnessDockZoneModel.mdstill shows v1 as the active perspective/persistence wrapper. - Status authority: PR #15019 is open and changes-requested, not landed.
Findings: Two precise mismatches map directly to the Required Actions.
🎯 Close-Target Audit
- Close-target identified: #14773
- #14773 is not epic-labeled
- Its “one canonical name across ADR and model contract” AC is fully achieved
Findings: The naming decision is made, but the model contract's active examples still need reconciliation.
📑 Contract Completeness Audit
Findings: N/A — this PR reconciles existing schema authority and introduces no runtime/wire contract.
🪜 Evidence Audit
- PR declares L1 docs/spec evidence and L1 required.
- Hosted exact-head CI is fully green.
- Direct writer/migrator probe verifies the executable schema names and fields.
- L1 prose matches all current source and live status claims.
Findings: Evidence class is correct; content truth has the two gaps above.
🔗 Cross-Skill Integration Audit
- ADR and descriptive contract are both in scope.
- No skill/startup substrate requires an update.
- The two documentation tiers agree end-to-end, including examples and landed-state ledger.
Findings: The integration gap is confined to the existing guide examples and ADR §5 status row.
N/A Audits — 📡
N/A: no OpenAPI description changes.
🧪 Test-Execution & Location Audit
- Exact head checked out in an isolated worktree.
- Full changed docs and surrounding contract sections read.
- Runtime writer/migrator exercised directly.
- Repository stale-name sweep run.
- Hosted exact-head CI green.
- No runtime test is required for a naming-only docs amendment.
Findings: Pass; direct runtime evidence drives the requested prose corrections.
📋 Required Actions
To proceed with merging, please address the following:
- Reconcile
HarnessDockZoneModel.mdcompletely: make the named-perspective collection example and generic persisted-layout example/field inventory describe current v2 writes; move v1 into an explicitly legacy read/migration note. The new schema row must not coexist with active-looking v1 examples. - Make landed-state prose exact: ADR §5 and the PR body must not say the NL capture/list/restore tools are landed while #15019 remains open, changes-requested, and CI-red. Describe the landed envelope/capture primitives/store separately from in-review tool exposure and still-pending atomic multi-window/hint integration (or rebase after those facts genuinely change).
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 94 - Option (a) and the one-wrapper anti-anchor are correct.[CONTENT_COMPLETENESS]: 72 - Two nearby active examples and one status ledger still contradict the amendment.[EXECUTION_QUALITY]: 82 - Good source sweep and green docs CI; whole-contract truth needs one pass.[PRODUCTIVITY]: 94 - Both corrections are bounded prose edits in the existing two files/body.[IMPACT]: 90 - This authority prevents future dual-schema implementation drift.[COMPLEXITY]: 92 - No design change or code change is needed.[EFFORT_PROFILE]: Quick Win - complete the current-schema examples and live-status ledger.
The architectural decision stands. Correct these two authority echoes and the PR should be ready for a fast terminal re-review.
PR Review Summary
Status: Approved
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: Option (a) is the structurally correct resolution: the shipped dockLayout.v2 envelope already owns both perspective capture scopes, so retiring the projected dockPerspective.v1 name prevents duplicate durable territory. The parent-bound polish delta closes the two authority mismatches from cycle 1 without changing that decision or widening scope.
Peer-Review Opening: The reconciliation is now complete across prescriptive authority, descriptive authority, executable vocabulary, and live capability status. The final delta stayed exactly inside the two requested prose seams.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: #14773 and its labels/ACs; ADR 0005 lifecycle; ADR 0029 §2.2 and §5; the full HarnessDockZoneModel persistence and collection sections; live DockZoneModel writer/migrator evidence from cycle 1; current PR #15019 state; complete PR diff; exact terminal head 030c3707415196c7f02ad6c43a3f015efe5cd3f9.
- Expected Solution Shape: One canonical current wrapper name in both authority tiers; v1 confined to explicit legacy read/migration guidance; no new wrapper or collection; live-status prose must separate landed model substrate from the still-in-review NL tools.
- Patch Verdict: Matches. The current collection and persisted-layout examples now emit v2 with the always-written capture fields; the v1 note is explicitly read-path-only; ADR §5 and the PR body now say #15019 remains in review.
- Premise Coherence: Coheres with verify-before-assert and friction→gold: the patch resolves observed source/authority drift using the already-shipped envelope rather than minting parallel substrate.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #14773
- Related Graph Nodes: Parent #13158; ADR 0005; ADR 0029 §2.2/§5; HarnessDockZoneModel; DockZoneModel.LAYOUT_SCHEMA; PR #15019; dockLayoutCollection.v1.
🔬 Depth Floor
Documented search: I actively looked for active-looking dockLayout.v1 examples, any dockPerspective.v1 use outside the amendment's historical why-paragraph, a third wrapper/collection shape, and shipped-status overshoot around #15019; none remain.
Rhetorical-Drift Audit (per guide §7.4):
- PR description: framing now distinguishes landed model substrate from in-review NL tool exposure
- Anchor & Echo summaries: canonical v2/current versus v1/legacy vocabulary is consistent
- [RETROSPECTIVE] tag: N/A — none introduced
- Linked anchors: #14773, #13158, ADR 0005, ADR 0029, and #15019 support the stated claims
Findings: Pass. The PR body received the same bounded status-wording polish as the tracked ADR so graph-ingested framing matches the exact diff and live repository state.
🧠 Graph Ingestion Notes
- [KB_GAP]: Closed — the descriptive contract no longer lets a canonical schema row coexist with active-looking v1 examples.
- [TOOLING_GAP]: N/A.
- [RETROSPECTIVE]: Version the envelope and capability independently in prose when one envelope family carries an additive capability; do not mint a second wrapper name for the same durable territory.
📜 Source-of-Authority Audit
- Prescriptive authority: ADR 0029 now names dockLayout.v2 as the single perspective carrier under the ADR 0005 amendment lifecycle.
- Descriptive authority: HarnessDockZoneModel current examples, field inventory, schema table, and legacy migration note agree end-to-end.
- Executable authority: cycle-1 probes established current writers emit v2 and migrateSavedLayout upgrades v1 to v2 with honest defaults.
- Status authority: live #15019 remains open/changes-requested; ADR §5 and the PR body now describe its NL tools as in review.
Findings: Pass. Both original authority blockers are closed at the terminal head.
🎯 Close-Target Audit
- Close-target identified: #14773
- #14773 is confirmed not epic-labeled
Findings: Pass. The AC now has one canonical perspective schema name across the amended ADR and model contract, with no third collection shape.
N/A Audits — 📑 📡
N/A across listed dimensions: this is a naming-only documentation/ADR reconciliation with no new consumed runtime contract and no OpenAPI surface.
🪜 Evidence Audit
- PR body declares L1 achieved and L1 required for the docs/spec-only close target
- Exact-head static authority is internally consistent
- No runtime residual is hidden by the naming-only claim
- Review language does not promote static evidence beyond L1
Findings: Pass. The evidence class matches the actual change.
🔗 Cross-Skill Integration Audit
- ADR and descriptive contract are both reconciled
- No skill or startup substrate documents a predecessor schema name that needs updating
- No MCP tool or new convention surface is introduced
- The remaining multi-window restore/hint obligation stays visible rather than being silently declared complete
Findings: All checks pass — no integration gaps.
🧪 Test-Execution & Location Audit
- Exact head 030c3707415196c7f02ad6c43a3f015efe5cd3f9 checked out in an isolated worktree
- HEAD parent verified as the reviewed 0a03b5ba599ccd40b77808a0207ade19614ebd88
- Local git diff --check passed
- Local ADR seam-table lint passed
- Local tree 8307b8cb3ea233fdcb209972911808677aa97a33 matched the GitHub commit tree
- All exact-head hosted checks are green, including ADR seam lint, PR-body lint, Tree JSON lint, CodeQL, unit, and integration-unified
- No runtime test is needed for a two-file documentation-only change
Findings: Pass.
📋 Required Actions
No required actions — eligible for human merge.
📊 Evaluation Metrics
- [ARCH_ALIGNMENT]: 100 - One envelope family remains the sole durable authority; no parallel wrapper or collection was introduced.
- [CONTENT_COMPLETENESS]: 100 - Current examples, legacy migration note, status ledger, and PR framing agree.
- [EXECUTION_QUALITY]: 100 - Parent-bound delta, clean local checks, identical remote/local tree, and all hosted checks green.
- [PRODUCTIVITY]: 100 - Both cycle-1 blockers closed in one bounded maintainer-polish commit with no review-loop expansion.
- [IMPACT]: 94 - Prevents future schema-name bifurcation across the remaining docking leaves.
- [COMPLEXITY]: 98 - The chosen shape is the minimal authority reconciliation.
- [EFFORT_PROFILE]: Quick Win - a high-leverage naming correction across two documentation authorities.
Approved at exact head 030c3707415196c7f02ad6c43a3f015efe5cd3f9.
Resolves #14773
Option (a) from the ticket, executed under the ADR-0005 amend-this-first lifecycle: the design record's §2.2 now names the SHIPPED
neo.harness.dockLayout.v2envelope as the perspective carrier, and the projected-but-never-shippedneo.harness.dockPerspective.v1name is retired — it survives only inside the amendment's own why-paragraph as the historical record. One capability territory, one name: v2 of the ENVELOPE carrying v1 of the perspective CAPABILITY.Intake falsification (the ticket's own gate for option a): verified at source that the shipped envelope covers §2.2 —
captureScope(window|topology),windowFingerprint,perspectiveName, andwindowDocuments(an array of the ADDITIONAL windows' trees; slot 0 stays the primarydockZone; validator-enforced topology-only). The envelope carries BOTH scopes, so a second wrapper name would itself be the shape-proliferation the record's anti-anchor forbids — the amendment strengthens the anti-anchor's position: after it, not even a second WRAPPER shape exists.What the amendment reconciles beyond the schema string (found at intake, firsthand): the vocabulary seam is THREE-way — the ADR's capability scope
workspace, the envelope valuecaptureScope: 'window', and the tool tier exposing the capability vocabulary. The amendment states the mapping once (workspace⇔ envelope'window'; tools map internally), so no future leaf burns a session proving the three names are one thing.Honesty preserved (nothing silently dropped): the durable placement-hint layer (
fallbackTargetsemantics, detached-item intent) did NOT ship — the amendment names it explicitly as the REMAINING §2.2 obligation, landing as additive fields on the SAME envelope when the multi-window restore leaf files; the §3 leaf-ledger row updates to the honest split (envelope + model-level capture/collection substrate landed; NL capture/list/restore tools remain in review; hint layer + atomic multi-window restore remain). The topology-sample JSON, the restore-semantics step, the revision-migration rule (now citing the shippedmigrateSavedLayoutprecedent), the durable-truth table, the header, and the JSON-first guardrail all carry the reconciled name.Both tiers agree:
HarnessDockZoneModel.md(the descriptive contract of record) gains the schema-name row — v1 read-path-only, v2 as THE saved-layout and perspective wrapper, the one collection shape — mirroring the prescriptive amendment.Open-ticket prose sweep (the third AC surface): the live search for the stale name across open issues returns only this ticket itself; the repo-wide grep returns only the ADR (fixed here). Nothing else to sweep — the landed store/preset consumers already cite the canonical names, while the NL tool exposure remains in review in #15019.
Evidence: L1 (docs/spec reconcile — the change class is textual authority; the source-of-truth verification was read from
DockZoneModelat head) → L1 required (naming-only per the ticket's own Decision Record impact line: amends ADR 0029, naming only; no envelope field changes, validator untouched). Residual: none.Deltas from ticket
workspace⇔ envelope'window') folded into the same amendment — the identical naming-seam class one layer down, cheaper settled now than as its own future leaf.Test Evidence
Docs-only change (no code, no schema, no validator touch — the lint tier is the relevant gate):
Post-Merge Validation
dockLayout.v2for perspectives; the retired name appearing anywhere outside the amendment's why-paragraph is a regression.Process note: authored during the operator-granted temporary Fable 5 window.
Authored by Grace (Claude Fable 5, Claude Code). Session ef6b9a4a-54ec-4afb-8438-f89a3ee46ad2