Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
d532691
✨ Add fanout utilization and rationale category retrieval telemetry
ebigunso Jul 11, 2026
1971215
🧪 Match real gRPC connection-refused shape in Qdrant skip predicate
ebigunso Jul 11, 2026
745412f
📝 Add ADR-I-0019: continuity eval harness placement in private evals …
ebigunso Jul 11, 2026
3112a3a
📝 Add v0.1.4 continuity harness plan and refresh coding-agent rules
ebigunso Jul 11, 2026
0b11112
📝 Unwrap hard-wrapped prose in plan; add no-hard-wrap doc rule
ebigunso Jul 11, 2026
373072e
📝 Close Task_4 gate and re-scope Tasks 5-6 after evals architecture r…
ebigunso Jul 11, 2026
26f689e
📝 Add model-strength-aware delegation routing to orchestrator rules
ebigunso Jul 11, 2026
43162ea
📝 Make delegation routing a runtime-conditional platform recommendation
ebigunso Jul 11, 2026
e58434c
fix: gate fanout utilization tracing
ebigunso Jul 11, 2026
055b049
📝 Record PR review-fix cycle and Tier D approval in plan log
ebigunso Jul 11, 2026
2d00759
📝 Update Copilot re-review rule with verified REST fallback
ebigunso Jul 11, 2026
8aaba85
📝 Address review housekeeping: stale metadata, backlog note, gate cri…
ebigunso Jul 11, 2026
279891f
fix: correct retrieval telemetry provenance
ebigunso Jul 11, 2026
2e4a7fc
fix: derive rationale from admission signals
ebigunso Jul 11, 2026
8323eb1
📝 Stage admission-signal truth-table testing as harness migration can…
ebigunso Jul 11, 2026
89108dd
fix: track rationale along admission paths
ebigunso Jul 11, 2026
14b5d94
📝 Stage truth-table-first design lesson as harness migration candidate
ebigunso Jul 11, 2026
4a6fcb2
📝 Add provenance semantics contract doc on graph_provenance
ebigunso Jul 11, 2026
d9fc357
📝 Stage producer/consumer-set telemetry review audit as harness candi…
ebigunso Jul 11, 2026
6150373
fix: filter fanout traces by expanded nodes
ebigunso Jul 11, 2026
eb5e1f7
📝 Document max-depth subset relation in fanout utilization contract
ebigunso Jul 11, 2026
20d4743
📝 Unwrap fanout contract doc sentence per no-hard-wrap rule
ebigunso Jul 11, 2026
3b0b6db
📝 Stage cost-gate and staged-cardinality review guidance as harness c…
ebigunso Jul 11, 2026
2c7a59e
fix: gate provenance and count hub omissions
ebigunso Jul 11, 2026
06b35c0
📝 Record frozen-snapshot lesson for destructive shared-resource ops
ebigunso Jul 11, 2026
d8de2bd
📝 Stage labels-are-not-invariants review guidance as harness candidate
ebigunso Jul 11, 2026
60f7d84
fix: classify rationale by endpoint types
ebigunso Jul 11, 2026
78051ad
📝 Unwrap all provenance contract doc bullets per no-hard-wrap rule
ebigunso Jul 11, 2026
1801608
📝 Stage paired positive/negative category coverage guidance as harnes…
ebigunso Jul 11, 2026
3bdb69c
test: cover salience rationale attribution
ebigunso Jul 11, 2026
01f9b11
📝 Stage action-set reconciliation guidance as harness candidate
ebigunso Jul 11, 2026
5cbc529
fix: filter utilization by expanded nodes
ebigunso Jul 11, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/coding-agent/lessons.md
Original file line number Diff line number Diff line change
Expand Up @@ -1017,3 +1017,47 @@ Prevention:

Evidence:
- `common.md` now contains only repo-wide validation, naming, module-layout, and test-placement rules.

## 2026-07-11 — No Hard-Wrapped Prose In Committed Docs [tags: formatting, docs, plans]

Context:
- Plan: `docs/coding-agent/plans/active/v0-1-4-continuity-evaluation-harness-plan.md`
- Task/Wave: plan/rule bookkeeping across CM and CME
- Roles involved: Orchestrator

Symptom:
- Plan files and log entries were written with hard line breaks mid-sentence to fit a column width; user corrected that prose must not contain arbitrary newlines inside sentences.

Root cause:
- Habitual fixed-column wrapping applied to markdown prose where soft-wrap is expected; the wrapping conveys nothing and pollutes diffs.

Fix applied:
- Reflowed both active plan files (CM and CME) so every sentence/paragraph/list item is a single line; YAML keys and structural lines untouched.

Prevention:
- Repo rule added to `docs/coding-agent/rules/common.md` in both repositories: never hard-wrap prose mid-sentence in committed documents.
- Repo-wide cleanup of pre-existing files is deferred by user decision until after the current feature PR merges.

Evidence:
- Reflow commits on `v0-1-4-cm-groundwork` (CM) and `eval-harness-architecture-revision` (CME).

## 2026-07-11 — Freeze The Target List Before Destructive Ops On Shared Resources [tags: operations, shared-state, qdrant]

Context:
- Task: user-directed cleanup of ephemeral Qdrant collections while reviewer test runs were active
- Roles involved: Orchestrator

Symptom:
- The deletion script re-enumerated collections at execution time instead of using the announced snapshot, so 14 collections created by a reviewer's in-flight test run were also deleted, contaminating its green result and forcing a full uncontaminated rerun.

Root cause:
- The coordination message promised a fixed-snapshot deletion, but the implementation piped a fresh listing into the delete loop — the announced safety property was never actually implemented.

Fix applied:
- Reviewer reran the full suite post-all-clear and reconfirmed; no lasting damage.

Prevention:
- For destructive operations on shared mutable resources: enumerate once, freeze the list, act only on the frozen list — and verify the implementation actually matches any safety property announced to peers before running it.

Evidence:
- cm-reviewer coordination messages (provisional APPROVED, then reconfirmed post-rerun) on 2026-07-11.

Large diffs are not rendered by default.

10 changes: 8 additions & 2 deletions docs/coding-agent/rules/common.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,16 @@
# Common Repository Rules

last_updated: 2026-07-02
last_updated: 2026-07-11

## Repository Reference Documents

- None yet.
- Evaluation harnesses live in a separate private companion repository, `CharacterMemoryEvals` (checked out as a sibling directory of this repo; note the directory name is `CharacterMemoryEvals`, not `character-memory-evals`). It is a Rust workspace consuming this crate via a path dependency. Evaluation tooling exists there — do not assume it is unimplemented — but it is not part of this library's core functionality and the repo is not publicly accessible.

## Repo Documentation Wording

- 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 private `CharacterMemoryEvals` repository in committed docs, word it so public readers are not confused by being unable to access it: state that it is private and that evaluation tooling is a development aid, not core library functionality.
- 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.

## Repository-Specific Validation Commands

Expand Down
12 changes: 10 additions & 2 deletions docs/coding-agent/rules/orchestrator.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,20 @@
# Orchestrator Repository Rules

last_updated: 2026-07-04
last_updated: 2026-07-11

## Repo-Specific Orchestrator Policies

- When creating or updating a PR, follow the format specified in `.github/pull_request_template.md`.
- Layer-boundary reorganizations must include a `use crate::` dependency-direction audit as required Reviewer evidence (errors/domain/ports/policy must not import api or usecases); file-placement conformance alone does not catch inverted edges hidden behind re-export shims.
- When requesting Copilot PR re-review, try the normal reviewer path first with PowerShell-safe quoting: `gh pr edit PR_NUMBER --add-reviewer '@copilot'`. If Copilot has already reviewed the PR and that command returns success without starting a review, use GitHub GraphQL `requestReviewsByLogin` with `userLogins: ["copilot-pull-request-reviewer"]`, then verify `reviewRequests` or a new `latestReviews` entry instead of trusting the `gh pr edit` exit code alone.
- 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 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.
- When requesting Copilot PR re-review, try the normal reviewer path first with PowerShell-safe quoting: `gh pr edit PR_NUMBER --add-reviewer '@copilot'`. If Copilot has already reviewed the PR, that command returns success WITHOUT starting a review (verify with `gh pr view PR_NUMBER --json reviewRequests` — empty means it no-opped). The working fallback (verified 2026-07-11) is REST: `gh api repos/OWNER/REPO/pulls/PR_NUMBER/requested_reviewers -f 'reviewers[]=copilot'` — the login is plain `copilot`; `copilot-pull-request-reviewer` is rejected as a non-collaborator, and the GraphQL `requestReviews` mutation no longer accepts `userLogins`. Confirm success by `requested_reviewers` containing `Copilot` in the response.

## Delegation Routing (model-strength aware platform recommendation; user-approved 2026-07-11)

- When both Claude and Codex delegation targets are available at runtime, prefer routing by failure mode: if a miss would be a subtle bug or overlooked line, prefer a Codex agent (detail scrutiny); if a miss would be building the wrong thing well, prefer a Claude agent (altitude and lateral judgment). If only one platform is available, any agent may take any role.
- Research: prefer Claude for exploratory research (design-space surveys, alternatives with tradeoffs, cross-repo implications); prefer Codex for forensic research (exhaustive inventories with file:line evidence, call-site censuses, computability tables).
- Review tiers: Tier D defect/compliance review (post-implementation diff correctness, dependency-direction and entity-neutrality audits, serde/schema verification, determinism sweeps, acceptance-evidence checking) prefers a Codex reviewer — never the same agent identity that authored the diff, on any platform. Tier A altitude review (design/plan soundness, goal-achievement and what-will-bite-later review) prefers a Claude reviewer. Routine impl diffs get Tier D only; design docs get Tier A only; milestone gates get both tiers in parallel.
- Implementation prefers Codex workers; give creative-design subtasks a Claude design pass first and hand the implementing worker a spec.

## Repo-Specific Integration / Git Policy

Expand Down
51 changes: 51 additions & 0 deletions docs/coding-agent/skill-candidates.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Harness Migration Candidates

Repo-local staging for cross-repo harness improvements, per the improvement-loop skill. Entries here are candidates for promotion into first-party harness skills/references; they are not repo rules.

## 2026-07-11 — Admission-signal truth-table testing for diagnostic attribution [from PR #59 rationale-category defect chain]

- Symptom: three successive review rounds found provenance/attribution defects in diagnostic telemetry (categories seeded from destination metadata, relation endpoints conflated with admission causes, order-dependent propagation) that the first fix's tests missed.
- Root cause: tests asserted expected positive categories only — no systematic forbidden-category assertions and no permutation tests where input order is semantically neutral.
- Candidate guidance (for a validation/testing reference in the harness): when implementing or reviewing diagnostic attribution (rationale categories, provenance labels, cause tagging), require (1) a truth table covering each admission signal in isolation and in combination, with BOTH positive and forbidden-category assertions per case; (2) permutation-invariance tests wherever processing order is semantically neutral (e.g. same-depth graph edges ordered by ID); (3) an explicit check that no structural metadata (destination section, endpoint membership) doubles as a causal signal.
- Provenance: character-memory PR #59, commits 279891f → 2e4a7fc; findings by Copilot review and Tier D codex review.

## 2026-07-11 — Choose the data model AFTER deriving the attribution truth table [second lesson from the same defect chain]

- Symptom: even after adopting truth-table testing, two more defect rounds occurred because each implementation abstraction (score-presence, component closure) was chosen before the complete signal-by-path semantics were written down; the abstraction could not represent rows it was never designed for (side branches, relation-specific categories).
- Candidate guidance: for provenance/attribution features, derive the full test matrix FIRST — positive, forbidden, side-branch, fallback, union, root-exclusion, and permutation rows — then select a data model capable of representing every row (here: per-path signal tracking, not set closure). The truth table is a design input, not just a test artifact.
- Provenance: character-memory PR #59, commits 2e4a7fc -> 89108dd.

## 2026-07-11 — Producer-set/consumer-set reconciliation for pre-admission telemetry [reviewer-miss triage, PR #59 round 6]

- Symptom: Tier D review approved pre-hydration fanout telemetry although visibility-layer rows for lifecycle-suppressed intermediate nodes were copied wholesale into the final expansion, where the policy expansion never expanded those nodes.
- Root cause: review verified count timing/value correctness, adapter parity, and absence of double counting, but never reconciled the telemetry PRODUCER set (pre-hydration visibility frontier) against the final eligible CONSUMER set (lifecycle-admitted, actually-expanded nodes). Parity/high-fanout tests used only active nodes, so scope leakage was invisible.
- Candidate guidance (for harness review/diagnostics references): whenever diagnostics or telemetry are computed before hydration, filtering, admission, or dedupe and then attached to a final result, the reviewer must audit that producer-set == final-eligible-set (or that a subset relation is explicitly documented), and require at least one rejected/filtered-candidate negative regression.
- Provenance: character-memory PR #59 round 6; cm-reviewer self-triage after a Copilot catch.

## 2026-07-11 — Cost-gate table and staged-cardinality binding for optional diagnostics [reviewer-miss triage, PR #59 round 7]

- Symptom: review approved optional telemetry although (a) the disabled path still paid the full provenance-walk cost, and (b) a fanout omission metric consumed an already hub-truncated list, silently redefining what "omitted" measured.
- Root cause: review verified value semantics of enabled output and final row filtering/parity, but built neither an execution-cost gate table for the disabled path nor an ordered cardinality table across the chained limiters (eligible -> hub cap -> fanout cap).
- Candidate guidance (harness review references): for every optional diagnostic, review BOTH value semantics and disabled-path work (prove the computation itself is gated, not merely its output). For every chained limiter, enumerate producer cardinality at each stage and bind every emitted metric to exactly one named stage before approval, with boundary tests where stages interact.
- Provenance: character-memory PR #59 round 7; cm-reviewer self-triage.

## 2026-07-11 — Labels are not invariants: prove endpoint-type guarantees before semantic classification [reviewer-miss triage, PR #59 round 8]

- Symptom: review approved a relation-label => Entity mapping although the domain permits Mentions/Involves/About between non-Entity endpoints; entity-less paths were classified Entity.
- Root cause: review validated mapping exhaustiveness and propagation mechanics but accepted relation-name intuition without proving endpoint-type invariants from domain validation and production constructors.
- Candidate guidance (harness review references): whenever a semantic category is inferred from an enum label, require a truth table against all domain-permitted endpoint/state combinations, and cite the specific validation invariant that makes any label shortcut sound; if no invariant exists, classify from the actual node/state types instead.
- Provenance: character-memory PR #59 round 8; cm-reviewer self-triage after a Copilot catch.

## 2026-07-11 — Every emittable category needs a paired positive and zero/negative row at the consumer boundary [reviewer-miss triage, PR #59 round 9]

- Symptom: Salience attribution had absence-style coverage only; a threshold or producer regression could silently remove the category with tests staying green.
- Root cause: review required forbidden/spurious-category rows and broad truth tables, but not at least one production-reachable positive row for every category the classifier can emit, asserted at the final consumer boundary (not helper-level values).
- Candidate guidance (harness validation references): for every enum variant/category a classifier can emit, require one positive row (fixture strictly beyond the production threshold) and one zero/boundary row through the same path, both asserted on the final consumed output. Absence-only coverage is insufficient.
- Provenance: character-memory PR #59 round 9; cm-reviewer self-triage after a Copilot catch.

## 2026-07-11 — Reconcile against the semantic ACTION set, never the returned set; depth is phase-dependent [reviewer-miss triage, PR #59 round 10]

- Symptom: post-hydration utilization filtering used returned-object membership, keeping rows for a node returned at max_depth but measured pre-hydration at a shallower depth through a path later suppressed.
- Root cause: the review proved "visibility never measures its own max-depth frontier" but implicitly assumed producer and consumer phases assign the same depth to a shared object; lifecycle filtering of alternate paths can change an object's minimum reachable depth between phases.
- Candidate guidance (harness review references): when reconciling diagnostics across filtering/hydration phases, compare against the exact semantic action set (expanded/executed/persisted), never a broader returned/admitted set — and explicitly test phase-dependent path-rank/depth changes caused by rejected alternate paths.
- Provenance: character-memory PR #59 round 10; cm-reviewer self-triage after a Copilot catch.
1 change: 1 addition & 0 deletions docs/decisions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,3 +83,4 @@ Records in this repository are expected to capture decisions, not undecided prop
- [ADR-I-0016: Use retrieval intent as query-time policy](implementation/ADR-I-0016-use-retrieval-intent-as-query-time-policy.md)
- [ADR-I-0017: Persist association support, not derived association scores](implementation/ADR-I-0017-persist-association-support-not-derived-association-scores.md)
- [ADR-I-0018: Organize the crate into responsibility-boundary modules with enforced dependency direction](implementation/ADR-I-0018-responsibility-boundary-modules-with-enforced-dependency-direction.md)
- [ADR-I-0019: Place the continuity evaluation harness in the private evals repository](implementation/ADR-I-0019-continuity-eval-harness-placement.md)
Loading
Loading