feat(team-brain): redundant-memory guard and admin pending-review queue (#67)

[Hrithik-Gavankar]

Summary

Closes #67. Adds a feedback engine so remember blocks near-duplicate or conflicting crew memory instead of silently forking context, plus an admin approval queue for overrides members cannot apply directly.

Builds on merged role governance (#66 / PR #68): members queue proposals; admins approve or reject. CLI/MCP v1 ships here; visual inbox is tracked separately in #69.

Problem

Without duplicate detection, two engineers can remember overlapping research on the same Jira key — wasting tokens and polluting recall. Cross-author source_ref overrides on research/decision were also ungoverned.

What ships

Database (20260908120001_team_brain_pending_review.sql)

• memory_pending_submissions — admin review queue (RPC-only access)
• tb_find_similar_memories — FTS + optional vector similarity (distance ≤ 0.12)
• Extended remember(..., p_force_apply, p_queue_for_review):
  • Returns redundant_candidate: true + matches[] when blocked (nothing stored)
  • --queue → pending_submitted for admin review
  • --force → admin-only bypass
• RPCs: list_pending_memories, approve_pending_memory, reject_pending_memory

CLI (team-brain-api.sh)

Command	Who	Behavior
remember …	member+	Blocked on overlap → redundant_candidate
remember … --queue	member+	Submit to pending queue
remember … --force	admin	Bypass guard
pending list [KEY]	admin	Review inbox
pending approve <id>	admin	Promote to live memory
pending reject <id>	admin	Discard proposal
doctor	any	Probes list_pending_memories RPC

MCP (server.py)

• remember(..., queue_for_review=True)
• list_pending, approve_pending, reject_pending

Docs & onboarding

• docs/team-brain-memory.md §7c — product spec
• Demo, tutorial, onboarding — pending workflow + verification checklist
• Bootstrap share bundle — --role on joiner onboard + admin pending list hint
• Spike crew example — step 6 + pending review example
• Cursor skill / rule updates

CI

• tests/team-brain/pending-review-smoke.sh — CLI wiring (no Supabase required)

Admin workflow (v1)

# Member: blocked duplicate
bash core/scripts/team-brain-api.sh remember DEMO-1 research \
  "API uses bearer tokens from /auth/token endpoint."
# → redundant_candidate: true

# Member: queue improved finding
bash core/scripts/team-brain-api.sh remember DEMO-1 research \
  --source-ref "DEMO-1#api-auth" --queue \
  "API uses OAuth2 device flow (preferred for CLI clients)."
# → pending_submitted

# Admin: review
bash core/scripts/team-brain-api.sh pending list DEMO-1
bash core/scripts/team-brain-api.sh pending approve <pending-id> --note "Supersedes prior auth note"

[tejas161]

Summary

Solid v1 implementation for #67. The feedback engine + admin pending queue are wired end-to-end (DB → CLI → MCP → docs/skills), and the design fits cleanly on top of #66 role governance. Recommend: Approve with comments — address doc typos and the remember response-shape regression before merge.

---

Acceptance criteria (#67)

Criterion	Status	Notes
RPC returns explicit redundant_candidate + matches[]	✅	Also returns result, conflict_reason, suggested_action
Semantic path when embeddings enabled; FTS fallback	✅	Vector distance ≤ 0.12; FTS rank ≥ 0.05, body ≥ 8 chars
Pending schema + admin approve/reject RPCs	✅	tb_require_admin enforced
CLI + MCP list/approve/reject	✅	MCP missing admin force_apply (see below)
Skill/docs agent flow	✅	Rule + skill + docs/team-brain-memory.md §7c
Workshop demo (B blocked → recall A)	✅	team-brain-demo.md step 6
Privacy: team-scoped, no anon SELECT widening	✅	revoke all on pending table

---

What works well

1. Guard ordering is correct — exact hash dedupe → same-source_ref merge → cross-author gate (research/decision) → semantic/FTS guard → insert.
2. Cross-author source_ref override is gated — different author on research/decision gets redundant_candidate or --queue, not a silent overwrite.
3. Pending queue design is pragmatic — target_capture_id + match_metadata give admins enough context; approve archives via tb_snapshot_capture before promote.
4. CLI UX for agents — on block, stderr shows matches and exits 0. pending_submitted prints pending_id.
5. Scope discipline — CLI-only v1, dashboard deferred to #69.

---

Issues to address

Should fix before merge

1. Docs omit <pending-id> in pending approve examples — several docs show pending approve --note "..." but CLI requires pending approve <pending-id> [--note TEXT]. Same in team-brain-memory.md §7c, onboarding Step 4, tutorial checklist.

2. remember response shape regression — new remember drops content_hash, has_embedding, author_member_id, author_name, created_at, updated_at, initiative_id. Restore on success paths or document the slimmer contract.

3. Semantic threshold vs issue spec — issue suggested similarity ≥ 0.92 (distance ≤ 0.08); implementation uses distance ≤ 0.12 (~0.88). Document thresholds in §7c.

Non-blocking / follow-up

4. MCP has no admin force_apply (CLI has --force).
5. Thin test coverage — smoke test is CLI wiring only, no DB integration tests.
6. Dead enum value cross_author_override never used.
7. note/learning cross-author source_ref still auto-updates — worth a doc note.
8. No dedup on pending queue (repeated --queue spams rows).
9. approve_pending_memory reattributes author_member_id to submitter — document intent.
10. suggested_action values differ from issue enum (link|dedupe|request_approval).

---

Security & privacy

No security blockers. Pending table is RPC-only; p_force_apply is admin-gated; members see only their own pending rows.

---

Suggested test plan

bash core/scripts/team-brain-api.sh remember DEMO-1 research --source-ref "DEMO-1#api-auth" "API uses bearer tokens from /auth/token endpoint."
bash core/scripts/team-brain-api.sh remember DEMO-1 research "API uses bearer tokens from /auth/token endpoint."  # → redundant_candidate
bash core/scripts/team-brain-api.sh remember DEMO-1 research --source-ref "DEMO-1#api-auth" --queue "API uses OAuth2 device flow."
bash core/scripts/team-brain-api.sh pending list DEMO-1
bash core/scripts/team-brain-api.sh pending approve <pending-id> --note "Supersedes prior auth note"
bash core/scripts/team-brain-api.sh recall DEMO-1 "auth"