agnes-the-ai-analyst/docs/pd-ps-comments.md

# Corporate Memory V1 — review notes (pd × ps)

**Branch:** `pabu/local-dev` (worktree review)
**Date:** 2026-04-25
**Reviewers:** pd (with Claude Code), independent second opinion from Codex (GPT-5.5, xhigh reasoning)
**Scope:** verification flywheel + corporate memory V1 — `services/verification_detector/`, `services/corporate_memory/`, `app/api/memory.py`, schema `v7→v8`.

This document captures open questions and proposed changes raised during a walkthrough of the branch. It is not a blocker list — it is a starting point for a follow-up conversation. Severity ratings are pd's initial estimate; please push back where they feel off.

---

## Context

The branch implements a "verification flywheel": session JSONLs are scanned by `verification_detector`, an LLM extracts corrections / confirmations / unprompted definitions, and the resulting facts feed `knowledge_items` with calibrated confidence. Admin governance (HITL) gates everything before approval. New schema columns track provenance (`source_type`, `source_ref`, `confidence`, `domain`, `entities`, `valid_from/until`, `supersedes`, `sensitivity`, `is_personal`) and two new tables (`knowledge_contradictions`, `session_extraction_state`).

The mechanism is sound. The notes below are about edges where V1 calibration choices may not survive contact with real data, and one suspected access-control issue.

---

## 1. Knowledge-item deduplication

### Problem

`services/verification_detector/detector.py` derives the item ID as:

```python
id = "kv_" + sha256(f"{title}:{content}").hexdigest()[:12]
```

Two analysts independently surfacing the same fact will almost never produce identical `title` and `content` strings — LLM phrasing varies even on the same underlying claim. So this hash collides ~never in practice. It is a deterministic ID, not a deduplication mechanism.

The branch has no other dedup safeguard at create time. Practical result: the admin review queue will grow with near-duplicates that humans must triage.

### Our proposal

Do not attempt auto-dedup at create time. Instead, surface near-duplicates into the admin queue via three layers:

1. **V1.5** — entity-tag match: items sharing ≥N normalized entities become a "likely duplicate" candidate pair, exposed in the admin UI alongside the existing contradictions tab.
2. **V2** — embedding similarity: at create time, compute cosine against existing approved items in the same domain; threshold (e.g. ≥ 0.85) → flag as `likely_duplicate_of: <id>` for admin merge.
3. The contradiction detector already surfaces "soft contradictions" — these can be repurposed to also catch near-duplicates with a single LLM judge call (same infra, different prompt).

Reasoning: auto-merge at create time is risky (false positives bury new nuance under stale items). Admin queue spam is the lesser evil; embedding pre-filter at V2 keeps admin load bounded.

### Codex second opinion

> Codex run: `gpt-5.5`, `model_reasoning_effort = xhigh`, executed against the same files in worktree.

- **Verdict:** Partial. Don't auto-merge at create time, but pre-check likely duplicates *before* inserting into the admin queue (don't punt entirely to admin manual review).
- **Blind spot we missed:** contradiction detection is **not a duplicate detector**, and in the current pipeline it is not wired into `verification_detector.run()` at all. Items are created at `detector.py:178` but `detect_and_record()` is never called. The contradiction prompt explicitly says "specificity / different perspective is not a contradiction", so near-duplicates would not surface there even if it were wired.
- **Concrete alternative:** add a relation table `knowledge_item_relations(item_a_id, item_b_id, relation_type, score, resolved)` near `src/db.py:76`. Add `repo.create_relation()` near `src/repositories/knowledge.py:182`. In `detector.py:171`, run duplicate-candidate lookup (entity-overlap is fine for V1.5; embeddings later) and attach `relation_type='likely_duplicate'` so the admin queue shows duplicate candidates explicitly.
- **Severity:** medium. Must fix before broad historical backfill; acceptable for narrow V1 only if confirmations are limited and admins see explicit duplicate candidates.
- **Confidence:** 90%.

### Plan (revised after Codex)

- V1: accept that duplicate hint is missing; flag this loudly in PR description so reviewers know what's deferred.
- V1.5: add `knowledge_item_relations` table + entity-overlap-based duplicate suggestion. Surface in admin UI alongside contradictions. ~1 day work.
- V2: embedding similarity at create time, gated by domain.

**Severity:** medium (was: medium). Codex agrees on default but raises the bar for V1.5 — duplicate candidates should be surfaced explicitly, not discovered ad-hoc by admin.

---

## 2. Contradiction detection — synchronous + SQL pre-filter vs Anthropic Batch API

### Current

`services/corporate_memory/contradiction.py` runs synchronously per new item:

1. **Pre-filter (DuckDB):** find candidates with same `domain` + keyword match on `title.split()` words >3 chars. Limit 10.
2. **LLM-as-judge (sync):** Haiku prompt returns `{contradicts, explanation, severity, suggested_resolution}`.

The pre-filter has predictable recall problems: synonyms, paraphrases, cross-domain conflicts (a finance metric definition can contradict a data engineering definition of the same metric).

### Proposed migration to Batch API

Anthropic's Batch API offers ~50% cost reduction with async SLA (≤24h, typically <1h). This is attractive because contradiction detection does not need real-time response — admins review queues, not push notifications.

### Our proposal

Layered evolution:

- **V1**: keep synchronous + SQL filter as-is. Ship.
- **V1.5**: add embedding-based pre-filter. Voyage embeddings at ~$0.02/1M tokens are essentially free at our volume. Replace keyword filter with `cosine(item, candidate) > 0.6` per domain; LLM judge unchanged. Catches paraphrases the keyword filter misses.
- **V2**: switch the LLM judge phase to Batch API. Run a nightly sweep over `pending × approved` per domain. With 50% cost reduction and higher rate limits, we can afford O(N²) within domain shards (no pre-filter needed in Batch mode — let the model judge all pairs).

### Open questions

- **Hidden Batch API costs** beyond cost: dev experience (test cycles), observability (job tracking, retries), debug latency. Worth it?
- **Hybrid mode**: keep sync for high-priority sources (admin_mandate, user corrections) and batch for bulk (`session_transcript`, low-confidence pending)? Or single mode for simplicity?
- **Embedding threshold**: 0.6 is a guess. Calibrate against held-out labeled pairs from V1 data once we have them.

### Codex second opinion

- **Verdict:** Partial. Batch API is likely a V2 win for bulk sweeps, **but not as the only mode.**
- **Blind spot we missed (two of them, both severe):**
  1. The SQL pre-filter is **weaker than we described.** It is not `domain AND keyword`; it is `domain OR keyword` — `src/repositories/knowledge.py:287` joins all conditions with `OR`. Combined with `ORDER BY updated_at DESC LIMIT 10`, recent same-domain noise crowds out the actual conflict.
  2. Detector-created items **never invoke contradiction detection at all.** `detect_and_record()` exists in `services/corporate_memory/contradiction.py` but is not called from `services/verification_detector/detector.py`. So V1 contradiction governance is effectively a stub.
- **Concrete alternative:** first fix V1 before optimizing.
  1. In `src/repositories/knowledge.py:272`, build `domain = ?` as a top-level conjunct (`AND`) and the title/content keyword expansion as an inner `OR` group.
  2. In `services/verification_detector/detector.py:178`, after `repo.create()`, call `contradiction.detect_and_record(extractor, item_dict, repo)`. Or enqueue it for nightly batch — but it must run somewhere.
  3. For V2, use **one shared job model with two executors**: sync for admin/manual/high-priority items, batch for session backfills and nightly sweeps. Don't fork prompt/candidate logic.
- **On embeddings threshold:** `cosine > 0.6` is arbitrary. Calibrate using labeled pairs (duplicate / contradiction / related-but-compatible / unrelated). Optimize for recall before LLM judging — target `>95% recall` with bounded candidate count. **Use top-k plus threshold, not threshold alone.**
- **Severity:** **high.** If V1 claims contradiction governance, this needs fixing before merge — currently the feature is shipped but inert.
- **Confidence:** 92%.

### Plan (revised after Codex)

- **V1 must-fix (was missed):**
  - Fix `OR` → `AND domain + (OR keywords)` in `find_contradiction_candidates`.
  - Wire `detect_and_record()` from `verification_detector.detector.run()`. Or, if we don't want sync LLM cost in detector, enqueue items into a `pending_contradiction_check` table for a nightly batch.
  - Either of those, or remove the V1 claim that contradictions are surfaced.
- V1.5: embedding pre-filter (top-k + threshold, calibrated against labeled pairs). Single shared job model.
- V2: batch executor for nightly sweeps; sync executor for admin/manual; same prompt+candidate logic.

**Severity:** **high** (was: low for V1). Codex's nailed two bugs we missed entirely.

---

## 3. Confidence scoring — calibration, decay, feedback

### Current

`services/corporate_memory/confidence.py` is a hand-rolled lookup:

- `_BASE_CONFIDENCE`: hard-coded dict, e.g. `user_verification.correction = 0.90`, `admin_mandate = 1.00`, `claude_local_md = 0.50`.
- `_MODIFIER_EFFECTS`: hard-coded modifiers (`+0.05` per additional verifier, `+0.20` for admin confirmation).
- `apply_decay()`: linear `0.02` per month → everything reaches 0 at ~50 months including admin policies.

Three problems:

1. **Tuning requires deploy.** The numbers are guesses; in real use we will discover that, say, `user_verification.confirmation` (currently 0.60) is overoptimistic. Each iteration = code change + deploy.
2. **Linear decay is wrong for admin policies.** `admin_mandate = 1.00` decaying linearly to 0 in 50 months is sematically incorrect — admin policies are policies, not "aging facts". They are explicitly revoked, not slowly forgotten.
3. **No feedback from admin actions.** When an admin rejects an item, that signal is lost — we don't update the prior for `(source_type, detection_type)` based on observed approval rates.

### Our proposal

Three layers:

**A. Externalize all numbers to `instance.yaml`** (V1.5, mandatory):

```yaml
corporate_memory:
  confidence:
    base:
      user_verification.correction: 0.90
      user_verification.confirmation: 0.60
      user_verification.unprompted_definition: 0.90
      admin_mandate: 1.00
      claude_local_md: 0.50
      session_transcript: 0.50
    modifiers:
      additional_verifiers_per_user: 0.05
      admin_confirmed_bonus: 0.20
    decay:
      mode: exponential       # or "linear" for back-compat
      half_life_months: 12    # confidence halves every 12 months
      floor:
        admin_mandate: 0.50   # admin items never decay below 0.5
        user_verification.correction: 0.10
        claude_local_md: 0.0
        session_transcript: 0.0
```

**B. Switch to exponential decay with per-source-type floor** (V1.5):

```python
def apply_decay(confidence, created_at, source_type, half_life_months=12, floor_per_source=None):
    age_months = ...
    decayed = confidence * (0.5 ** (age_months / half_life_months))
    floor = (floor_per_source or {}).get(source_type, 0.0)
    return max(decayed, floor)
```

**C. Bayesian prior calibration from admin actions** (V2):

Nightly: compute `P(approve | source_type, detection_type)` over the last N items per category. Surface as a metric in admin UI. Initially: human-edited config update. Later: gated auto-update with selection-bias mitigation (random sampling holdout).

### Open questions

- **Power-law vs exponential decay.** Ebbinghaus forgetting curve research suggests power-law may match human knowledge half-life better. Does that translate to organizational knowledge? Probably yes for "memorized facts", probably no for "policies that are explicitly maintained".
- **Per-domain calibration.** Finance metrics churn quarterly; engineering conventions persist for years. Should `decay.half_life_months` be per-domain, not just per-source-type?
- **Selection bias in feedback loop.** If priors gate which items admins see (sorted by confidence), and we update priors from approval rate, low-confidence items rarely get reviewed → priors stay biased. Mitigation: reserve a small random sample (e.g. 10%) outside the priority queue for unbiased measurement.
- **No "post-create confirmation" mechanism.** When a new verification cites an existing approved item, only the new item gets confidence; the existing item doesn't receive a verification-count boost. This loses the "multiple analysts independently cited this" signal over time.

### Codex second opinion

- **Verdict:** Partial. External config + floors are good. **The decay framing is wrong, and there are bigger V1 bugs in the data flow.**
- **Blind spot we missed (significant):**
  1. **LLM-controlled confidence.** `services/verification_detector/prompts.py:37` asks the LLM to return `base_confidence` as part of the JSON output, and `services/verification_detector/detector.py:187` stores it directly into the DB. **Confidence should not be LLM-controlled.** The current `compute_confidence()` exists but is bypassed for verification-detector items.
  2. **Lost evidence.** The detector extracts `user_quote` from the LLM (the exact quote that constitutes the verification — the most valuable signal!) and **discards it.** It is not stored anywhere. Without `user_quote` and `detection_type` persisted in DB, future Bayesian re-calibration has no raw material.
  3. **Decay framing is wrong.** Confidence is being treated as "truth decays with age" (Ebbinghaus). Organizational facts usually change by **events, scope, or validity windows** — not by smooth forgetting. The `valid_from/valid_until` columns already exist; the right model is "fact has a validity window", not "fact slowly fades".
- **Concrete alternative:**
  1. Remove `base_confidence` from the LLM-required output in `services/verification_detector/schemas.py:30`, **or** ignore it on the read side. Compute confidence in code: `compute_confidence("user_verification", v["detection_type"])`.
  2. Add an **evidence table**: `verification_evidence(id, item_id, source_user, source_ref, detection_type, user_quote, created_at)`. Persist `user_quote` and `detection_type` per-verification. Multiple evidence rows per item enables real "additional verifiers" boost computation (one user × one quote = one evidence row).
  3. Split "evidence confidence" (signal strength from sources) from "freshness / review-due" (validity windows, explicit revocation). Don't conflate them in one number.
- **On power-law vs exponential:** secondary issue. Domain-specific volatility matters more — use **hierarchical priors**: global `(source_type, detection_type)` priors plus per-domain freshness policy.
- **On feedback loops:** mitigate via random review sampling, holdout calibration sets, and **never use learned priors as the sole gate for admin visibility.** Codex agrees with our concern but emphasizes random sampling more strongly.
- **Severity:** medium. Bayesian/config overhaul can wait, but **LLM-controlled confidence and missing evidence should be fixed before V1.**
- **Confidence:** 88%.

### Plan (revised after Codex)

- **V1 must-fix (was missed):**
  - Stop trusting LLM-returned `base_confidence`. Either drop it from `VERIFICATION_SCHEMA` or ignore it on insert and call `compute_confidence(...)` instead.
  - Add `verification_evidence` table to persist `user_quote` + `detection_type` + source reference. This is also what makes "multi-user verification boost" actually computable post-create.
- V1.5: externalize numbers to `instance.yaml` (A) + exponential decay with per-source floor (B).
- V2: Bayesian metric surface (read-only) + per-domain decay policy. Auto-update behind feature flag with random-sample holdout.

**Severity:** **high** for V1 must-fix items above; medium for the rest.

---

## 4. Entity resolution v1

### Problem

`services/corporate_memory/entities.py` does case-insensitive **substring** match against a static registry. Two consequences:

- **False positives** on short tokens. A registry containing `"MD"` matches every occurrence of `"markdown"`, `"command"`, `"admin"`, `"medical"`. Severe noise.
- **False negatives** on synonyms. `"churn"` does not match `"attrition"`, `"customer loss"`, `"logo churn"`. Severe miss.
- No lemmatization, no co-occurrence, no confidence on the match itself.

### Our proposal

Three layers:

**1. V1.5 — word-boundary regex + canonical+aliases registry:**

```yaml
corporate_memory:
  entities:
    metrics:
      - canonical: churn
        aliases: [attrition, customer loss, logo churn]
      - canonical: MRR
        aliases: [monthly recurring revenue, monthly revenue]
```

```python
import re
def resolve_entities(content, title, registry):
    text = f"{title} {content}"
    matched = set()
    for category, entries in registry.items():
        for entry in entries:
            patterns = [entry["canonical"]] + entry.get("aliases", [])
            for p in patterns:
                if re.search(rf"\b{re.escape(p)}\b", text, re.IGNORECASE):
                    matched.add(entry["canonical"])  # always store canonical
                    break
    return sorted(matched)
```

Cost: ~30 LOC, no new dependencies, deterministic, eliminates false positives on short tokens.

**2. V2 — embedding-based fuzzy match.** Pre-compute embeddings for all canonical entities (cache). Per item: embed text, cosine to each entity embedding, threshold 0.75. Catches paraphrases the alias list misses. Voyage cost is negligible.

**3. V2.5 — LLM extraction for low-entity items, batch mode.** Items with <2 resolved entities go into a nightly batch LLM job that suggests candidates for admin curation. This is also how the synonym registry grows over time without manual curation.

### Open questions

- **Skip V1.5, go straight to embeddings?** Argument for: per-item cost is ~$0.0000002, negligible. Argument against: word-boundary fix is so cheap (~30 LOC) it's a no-brainer; embeddings pull in voyage_sdk + caching infrastructure that we don't need yet.
- **Synonym registry maintenance.** Who curates it? Does it become a Big Ball Of Mud? Mitigation: V2.5 LLM-suggest pipeline auto-grows it; admin reviews additions.
- **Hierarchical entities.** "EMEA Sales" is a sub-team of "Sales". "MRR Q3" is an instance of "MRR". Layered approach doesn't model this. Do we need it for V1? Probably not. For V2? Maybe — depends on how often analysts ask drill-down questions.

### Codex second opinion

- **Verdict:** Partial. **Do not skip V1.5.** Embeddings are not a replacement for deterministic entity resolution.
- **Blind spot we missed:** embeddings are **bad at exact short entities, acronyms, product codes, metric names, and aliases where precision matters** (e.g. `MRR`, `NPS`, internal product codes). Substring → embeddings would trade one class of false positives for a different class of *silent* errors that are harder to detect. Word-boundary regex with a maintained alias list is *more correct* than embeddings for these cases, not just cheaper.
- **Concrete alternative:** rebuild `entities.py:14` to use a **typed registry with stable canonical IDs**:
  ```yaml
  metrics:
    - id: metric.churn
      canonical: churn
      aliases: [attrition, customer loss, logo churn]
      kind: metric
      parent_id: null
      blocked_terms: []
    - id: org.team.sales.emea
      canonical: EMEA Sales
      kind: team
      parent_id: org.team.sales
  ```
  Replace substring matching at `entities.py:57` with escaped word-boundary regex, with **special rules for short aliases** (e.g. require leading + trailing whitespace or punctuation). Store canonical **IDs** (`metric.churn`) in `knowledge_items.entities`, not display strings — display is a join. Use embeddings/LLM **only to suggest aliases or candidates for admin approval**, never to bypass deterministic resolution.
- **On hierarchies:** worth modeling minimally now. `parent_id` is sufficient. `EMEA Sales` rolls up to `Sales`. `MRR Q3` is "metric + time period", not a separate flat entity — model it as `entity_ref + valid_from/valid_until`.
- **Severity:** medium. Not a V1 blocker by itself, but **definitely required before V1.5** if dedup or contradiction depend on entities (which our V1.5 plan does).
- **Confidence:** 86%.

### Plan (revised after Codex)

- V1: ship as-is, accept noise.
- V1.5: typed registry with canonical IDs, word-boundary regex, **store IDs not strings**, support `parent_id` for hierarchies. Use this for duplicate-candidate detection (Q1 V1.5 plan). ~2 days now (more scope than originally planned).
- V2+: embeddings + LLM-suggest pipeline for **alias growth**, not entity resolution. Admin approves auto-suggested aliases.

**Severity:** medium. Codex sharpened the design — store canonical IDs, not strings; hierarchy is V1.5, not V2.

---

## 5. `is_personal` flag — suspected leak

### Code paths

`app/api/memory.py`:

- `POST /{item_id}/personal` (line ~196) — only the contributor (`item.source_user == user.email`) can flag. Correct.
- `GET /api/memory` (line ~63) — accepts query parameter `exclude_personal: bool = True`. Default excludes personal items, but the endpoint accepts `exclude_personal=False` from any authenticated user with no role check.
- `GET /api/memory/my-contributions` — returns contributor's own items including personal ones. Correct.

### Concern

Any authenticated user can request:

```
GET /api/memory?exclude_personal=false
```

…and receive items flagged `is_personal=true` by other users. The flag is meant to keep an item private to the contributor, but the list endpoint exposes it whenever the caller asks.

### Impact

`is_personal` was introduced for emergency-exit cases (the detector pulled out something private that shouldn't be team-wide). If any user can override the default, the flag provides false security. This is a confidentiality leak unless `is_personal` is purely an "admin convenience flag" — but that's not how the toggle UI presents it.

### Proposed fix

Two options:

**Option A — kill the override entirely.** Remove the `exclude_personal` query parameter. Personal items are never visible via `GET /api/memory`. Contributors see them only via `/my-contributions`. Admins see them via a separate admin endpoint guarded by `Role.KM_ADMIN`.

**Option B — gate the override by role.** Keep the parameter, but require `Role.KM_ADMIN` to set it to `False`. Add a server-side check; non-admin requests with `exclude_personal=False` get 403 or are silently coerced to `True`.

Option A is simpler, safer, and matches the most likely product intent. Option B preserves a flexible audit endpoint for admins but is easier to misuse.

### Codex second opinion

- **Verdict:** **Y. This is a leak.**
- **Blind spot we missed (worse than the list path alone):**
  - The public list endpoint passes caller-controlled `exclude_personal` into `repo.list_items()` at `app/api/memory.py:87`, and `repo.list_items()` only filters when that flag is true at `src/repositories/knowledge.py:113` — caller controls it.
  - **Search ignores `exclude_personal` entirely** via `app/api/memory.py:78` and `src/repositories/knowledge.py:119`. Any authenticated user can `GET /api/memory?search=foo` and see personal items unconditionally.
  - **Direct item access** (`/{id}`, `/{id}/provenance`, vote endpoints) has no `is_personal` check either. If a user knows or guesses an item ID, they retrieve it.
- **Concrete alternative:**
  1. For the public `GET /api/memory`, **force `exclude_personal=True`** unless `user.role in ("km_admin", "admin")`. Or simpler: always force true and leave personal review to admin endpoints.
  2. Add `exclude_personal` support to `repo.search()` (currently it's only on `list_items()`).
  3. Add a shared `_can_view_item(user, item)` check used by provenance, vote, and direct item actions. Personal items are visible only to the contributor + admins.
- **Severity:** **high. Must fix before merging V1.**
- **Confidence:** **99%.**

### Plan (revised after Codex)

- **V1 blocker.** Fix all three vectors (list, search, direct access), not just the list parameter.
  - Force `exclude_personal=True` for non-admins on `GET /api/memory`.
  - Plumb `exclude_personal` through `repo.search()`.
  - Add `_can_view_item(user, item)` helper, apply on `/{id}`, `/{id}/provenance`, and any other direct-item endpoint.
- Add regression test that an authenticated non-contributor cannot retrieve another user's `is_personal` item via list, search, or direct GET.

**Severity:** **high.**

---

## Top issues to address before merging V1

(Initial pd list was three items. Codex review added two more high-severity findings we missed entirely. Updated list below.)

1. **`is_personal` leak in full breadth (Q5).** Fix list, search, and direct-item access. Force `exclude_personal=True` for non-admins on `GET /api/memory`; plumb the filter through `repo.search()`; add `_can_view_item(user, item)` for `/{id}`, `/{id}/provenance`, vote endpoints. Add regression test. **Severity: high. Confidence: 99%.**
2. **Contradiction detection is shipped but inert (Q2).** `detect_and_record()` is never called from `verification_detector.run()`. Either wire it (sync after `repo.create()` or enqueue for batch) or remove the V1 claim that contradictions are surfaced. Also fix the `OR → AND` bug in the SQL pre-filter at `src/repositories/knowledge.py:272-287` so `domain` is a top-level conjunct and keywords are an inner `OR` group. **Severity: high.**
3. **LLM-controlled confidence + lost evidence (Q3).** Detector trusts `base_confidence` from the LLM and discards `user_quote`. Drop `base_confidence` from `VERIFICATION_SCHEMA` (or ignore on insert), call `compute_confidence(...)` in code instead. Add `verification_evidence` table to persist `user_quote`, `detection_type`, `source_user`, `source_ref` per evidence row. Without this, "additional verifiers boost" is computable in theory only. **Severity: high.**

The rest (Q1 explicit duplicate hint, Q2 batch sweep, Q3 YAML externalize + exponential decay, Q4 typed registry) can land in V1.5 as planned.

### What V1.5 must own (consequential refinements, not blockers)

- Q1: `knowledge_item_relations` table for explicit duplicate candidate hints in admin queue.
- Q2: embedding pre-filter (top-k + threshold, calibrated against labeled pairs).
- Q3: externalize confidence to `instance.yaml`; exponential decay with per-source floor.
- Q4: typed entity registry with canonical IDs, word-boundary regex, hierarchical `parent_id`.

---

## Process notes

- Worktree: `/Users/padak/github/agnes-pabu-local-dev`, branch `pabu/local-dev` tracks `origin/pabu/local-dev`.
- Walkthrough done file-by-file with paired reading; second-opinion run via Codex CLI (model `gpt-5.5`, `model_reasoning_effort = xhigh`) over the same files.
- Document is intended for round-trip discussion: pd commits the first pass, ps reads, replies inline or in PR comments.