ebigunso · ebigunso · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026
diff --git a/docs/coding-agent/lessons.md b/docs/coding-agent/lessons.md
@@ -454,3 +454,69 @@ Prevention:
 ## Purge note (2026-07-23)
 
 Eleven entries purged per the user-directed low-value/invalid sweep (Codex purge map, agmsg 2026-07-23T12:28Z): ten PURGE-LOW-VALUE (restatements of now-mandatory harness/rule content — plan-format task records, PR monitoring, canonical-byte verification, compatibility policy, module layout, evidenced-scope rulebook default, parallel dispatch — plus two cheaply rediscovered one-off quirks and one unstructured batch-notes bundle) and one PURGE-INVALID (the phase-bounded v0.1 compatibility ruling, superseded by the repo-wide Compatibility Policy). Full entries recoverable from git history at 4997bdc.
+
+## 2026-09-03 — Reconcile The Companion Pin Before Filing Cross-Repository Breakage  [tags: review, scope, cross-repo, assumptions]
+
+Context:
+- Plan: `docs/coding-agent/plans/active/v0-1-6-embedded-vector-recall-plan.md`
+- Task/Wave: Task_3 / Wave 2
+- Roles involved: Reviewer | Orchestrator
+
+Symptom:
+- The reviewer filed a preliminary HIGH because a new variant in the closed error vocabulary would not compile in the evaluation repository's exhaustive match once that repository re-pins.
+
+Root cause:
+- The finding treated the companion repository's current main as if it were already pinned to the change under review, although the companion stays pinned at an older library commit until its own migration plan runs; ADR-I-0023's impact section names that conversion as the companion's re-pin prerequisite.
+
+Fix applied:
+- The orchestrator ruled the item out of scope; the reviewer recorded it as the already-tracked re-pin obligation and completed the review on the in-PR acceptance bullets.
+
+Prevention:
+- Before filing cross-repository breakage, reconcile the companion's pin and the plan that owns its migration; when the companion intentionally remains pinned until its own migration, record an obligation, not an in-PR defect.
+
+Evidence:
+- Reviewer messages of 2026-09-03 (preliminary HIGH, ruling acknowledgement, final REVIEW3_DONE) on Task_3 at 773d65e.
+
+## 2026-09-04 — PR Watchers Must Not Depend On Tools Absent From The Monitor Shell  [tags: workflow, monitoring, tooling, orchestrator]
+
+Context:
+- Plan: `docs/coding-agent/plans/active/v0-1-6-embedded-vector-recall-plan.md`
+- Task/Wave: Wave 1–2 PR monitoring
+- Roles involved: Orchestrator
+
+Symptom:
+- Copilot reviews on the wave PRs and on the evaluation repository's PR arrived without any watcher notification; the decider noticed the review before the orchestrator did.
+
+Root cause:
+- The watcher scripts piped GitHub API output through `jq`, which is not on the PATH of the background monitor shell; every poll failed on stderr, which the monitor does not surface, so the watchers stayed silent while appearing armed.
+
+Fix applied:
+- Watchers re-armed using only `gh api --jq` (no external `jq`), one loop covering the whole stack, printing on any change in review count, review-comment count, or merge state.
+
+Prevention:
+- A watcher script uses only tools proven available in the monitor shell (`gh --jq`, POSIX sh); before trusting a new watcher, read its output file once to confirm it produced a first sample rather than errors.
+
+Evidence:
+- Monitor output file for the PR #77 watcher on 2026-09-04: eighteen consecutive `jq: command not found` lines and no events, while Copilot's "approval recommended" review was already posted.
+
+## 2026-09-04 — Edit Only Through Absolute Worktree Paths, And Run Broad Suites Only After The Live Window Is Granted  [tags: workflow, worktrees, live-mutex, worker]
+
+Context:
+- Plan: `docs/coding-agent/plans/active/v0-1-6-embedded-vector-recall-plan.md`
+- Task/Wave: Task_4 / Wave 3
+- Roles involved: Worker | Orchestrator
+
+Symptom:
+- A relative-path patch briefly modified files in the shared main checkout instead of the task worktree before being reverted; and a full test suite started before the exclusive service window was confirmed, so service-backed tests could have collided with another agent's run.
+
+Root cause:
+- Relative paths resolve against whatever the current directory happens to be, and several checkouts of the same repository share identical relative paths; the live-window protocol grants exclusivity only on the explicit `WINDOW_YOURS` reply, not on sending `LIVE_START`.
+
+Fix applied:
+- The stray edits were reverted and verified clean; the suite was re-run inside the granted window.
+
+Prevention:
+- Every edit and every git command names an absolute path inside the task worktree, and the current directory is checked before each edit; a suite that may reach a shared service starts only after `WINDOW_YOURS` is observed, otherwise run the service-free command.
+
+Evidence:
+- Worker Task_4 report of 2026-09-03 (commit d232830) and the orchestrator's clean `git status` check on the main checkout.
diff --git a/docs/coding-agent/plans/active/v0-1-6-embedded-vector-recall-plan.md b/docs/coding-agent/plans/active/v0-1-6-embedded-vector-recall-plan.md
diff --git a/docs/coding-agent/rules/common.md b/docs/coding-agent/rules/common.md
@@ -2,7 +2,7 @@
 rule_schema_version: 2
 suite_id: "rules-cm-20260719"
 rule_file: "common"
-last_updated: "2026-07-24"
+last_updated: "2026-09-02"
 ---
 
 # Common Repository Rules
@@ -15,6 +15,7 @@ last_updated: "2026-07-24"
 
 - Committed artifacts in this repository must not contain machine-local absolute paths (for example user-profile paths); refer to sibling repositories by name and relative relationship instead.
 - When mentioning the `CharacterMemoryEvals` repository in committed docs, describe it as the public companion evaluation repository and state that evaluation tooling is a development aid, not core library functionality. Do not describe it as private or inaccessible (it was made public 2026-07-19); historical records (completed plans, dated ADR bodies) that reflect the earlier private status stay unchanged.
+- Records in this repository (plans, decision records, phase documents) state what the evaluation harness's measurements allow this library to decide and when those measurements are used; the harness's own work is planned and tracked in the evaluation repository and is never mixed into library plans (ruled 2026-09-02).
 - Do not hard-wrap prose in committed documents: never insert line breaks mid-sentence to fit a column width. Write each sentence/paragraph/list item as one line and let editors soft-wrap. Structural line breaks (list items, headings, YAML keys, code) are fine.
 - ADR frontmatter `consulted` entries record model names only (for example "Claude Fable 5", "GPT-5.5 Pro") — no role, platform, or product designations such as "(orchestrator)" or "Codex" (user-directed 2026-07-18).
 

diff --git a/docs/coding-agent/rules/orchestrator.md b/docs/coding-agent/rules/orchestrator.md
@@ -9,6 +9,8 @@ last_updated: "2026-07-23"
 ## Repo-Specific Orchestrator Policies
 
 - When creating or updating a PR, follow the format specified in `.github/pull_request_template.md`.
+- PR titles state what the change achieves, not a list of its contents; the contents go in the body. Never use bare version numbers or milestone labels as titles.
+- When a phase merges as one change, wave PRs target the planning branch and are registered as a GitHub stack on the planning PR with `gh stack link <plan-pr> <wave-pr>...` (bottom to top); later waves are appended with `gh stack link <stack-number> <pr>...`. The stack decides merge order.
 - Layer-boundary reorganizations must include a `use crate::` dependency-direction audit as required Reviewer evidence per ADR-I-0018 (ports/policy/models never import usecases, and import api only for the ADR's one named exception: the `api::types::retrieval` trace/telemetry vocabulary; errors/domain import no upper layer); file-placement conformance alone does not catch inverted edges hidden behind re-export shims.
 - Scope the ADR-I-0018 dependency-direction audit to the diff under review (e.g. `git diff | grep '^+.*use crate::'`) when reviewing incremental changes: pre-existing ports/policy/models imports of domain types via `crate::api::types` are grandfathered debt awaiting a one-time sweep to `crate::domain`, and a blanket grep forces per-line disambiguation between old and newly introduced edges.
 - PR feedback monitors must include terminal merged/closed state (harness pr-review-monitoring owns arming for reviews/comments but does not cover terminal-state watch) (user-directed 2026-07-19).

diff --git a/docs/decisions/README.md b/docs/decisions/README.md
@@ -28,5 +28,12 @@ Separate numbering per track; IDs are never reused.
 - Partial supersession stays in place: the record remains authoritative for its surviving clauses, with `supersession_scope` and reciprocal frontmatter links recording the split.
 - In records predating the current template, a blank warrant means it was not recorded at decision time, not an authoring omission. Fill blank newer frontmatter fields only when the record is substantively revisited.
 
+## Authoring rules
+- One decision per record. A choice of component and a choice of how that component is run or made durable are separate decisions with separate records.
+- A record encodes a locked-in decision. A deciding factor is deferred only when it is out of reach because of external factors, never when the same change produces the evidence.
+- The decision body pins the system's design and, at most, the behaviour of a narrow part of the implementation. Code shapes go in a non-binding appendix, never in the decision.
+- Every protected clause is checked against the project philosophy: it stays only if a philosophy goal (continuity, provenance, inspectable recall, correction) is what it protects. Current state is recorded under "Not covered", not as an invariant.
+- Records read the same at any time. No wording that hinges on when the record was written ("this phase", "later decision", "at decision time", "once", "already", change verbs such as "gains" or "moves"); history is anchored to named records, versions, and absolute dates, and Implementation Impact describes the resulting state.
+
 ## Status values
 `accepted`, `rejected`, `superseded`, `deprecated`. Records capture decisions, not undecided proposals.
diff --git a/docs/decisions/implementation/ADR-I-0001-stable-cross-store-ids.md b/docs/decisions/implementation/ADR-I-0001-stable-cross-store-ids.md
@@ -14,8 +14,8 @@ warrant:
 depends_on: []
 implements: []
 supersedes: []
-superseded_by: null
-supersession_scope: null
+superseded_by: implementation/ADR-I-0025-vector-record-is-a-read-contract.md
+supersession_scope: partial
 ---
 
 # ADR-I-0001: Use stable cross-store IDs and deterministic graph IRIs

diff --git a/docs/decisions/implementation/ADR-I-0002-natural-language-embedding-surfaces.md b/docs/decisions/implementation/ADR-I-0002-natural-language-embedding-surfaces.md
@@ -14,8 +14,8 @@ warrant:
 depends_on: []
 implements: []
 supersedes: []
-superseded_by: null
-supersession_scope: null
+superseded_by: implementation/ADR-I-0025-vector-record-is-a-read-contract.md
+supersession_scope: partial
 ---
 
 # ADR-I-0002: Embed natural-language semantic surfaces, not structured metadata templates

diff --git a/docs/decisions/implementation/ADR-I-0003-qdrant-oxigraph-defaults.md b/docs/decisions/implementation/ADR-I-0003-qdrant-oxigraph-defaults.md
@@ -14,8 +14,8 @@ warrant:
 depends_on: []
 implements: []
 supersedes: []
-superseded_by: null
-supersession_scope: null
+superseded_by: implementation/ADR-I-0023-embedded-qdrant-edge-vector-candidate-store.md
+supersession_scope: partial   # the vector-backend default only (embedded Qdrant Edge is the default); backend roles remain authoritative
 ---
 
 # ADR-I-0003: Use Qdrant and Oxigraph as default storage backends

diff --git a/docs/decisions/implementation/ADR-I-0005-qdrant-payload-vs-graph-authority.md b/docs/decisions/implementation/ADR-I-0005-qdrant-payload-vs-graph-authority.md
@@ -14,8 +14,8 @@ warrant:
 depends_on: []
 implements: []
 supersedes: []
-superseded_by: null
-supersession_scope: null
+superseded_by: implementation/ADR-I-0025-vector-record-is-a-read-contract.md
+supersession_scope: partial
 ---
 
 # ADR-I-0005: Keep Qdrant metadata filterable while graph relationships remain authoritative