feat(family): the promotion engine - triggers, the three criteria, the decision log and undo (milestone 463 step 3, #4989)

The agent promotes a family idea when all three criteria hold, and no person approves it. The criteria are product text: services/family.py states them, and the promote tool's docstring names every criterion the service enforces.

- Criteria: each one vetoes on its own when its reasoning is blank. Platform terms also needs an applies-when and a platform scope; proven also needs named evidence. A veto keeps the idea a candidate and is logged, so it becomes precedent.
- Precedent: every promotion stores the decisions on the nearest ideas by meaning, plus any the caller names.
- Promotion sets canon, the applicability test and the platform scope, and opens an unassessed ledger row for each member project the promoter can write. Re-promotion moves the version past every version the idea has held.
- Retire and undo: undo reverses only the latest idea-level decision, restores its recorded before-state, and logs itself with the undone decision as its precedent. Settled here: leaving canon closes the unassessed rows but keeps the judged ones, which read as needing a recheck after a re-promotion.
- Triggers open evaluations but never promote:
  - a cross-project lineage citation ("matching #N") on a note or task write;
  - a same-meaning record in another project on a shared platform, on create, at 0.80 (measured: the known pattern's builds scored 0.79-0.82, an unrelated project's best match 0.65);
  - a milestone closing on a platform.
  Each fails open and rides the response as family_hint.
- Doors: seven MCP tools, /api/family REST endpoints, and a Family page (nav, /family) showing the criteria, the ideas, and the decision log with undo and retire.
- utils/recordHref.ts holds the one copy of "where a record opens", now shared with LessonDetailView.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/scribe/mcp/tools/family.py

@@ -0,0 +1,183 @@
+"""Family canon MCP tools — the promotion engine's agent door (milestone 463).
+
+Thin wrappers over services/family.py. The agent is the decider here: no
+person approves a promotion, so the criteria are stated in these docstrings
+and enforced by the service, and every decision is logged with its reason.
+"""
+from __future__ import annotations
+
+from scribe.mcp._context import current_user_id
+from scribe.services import family as family_svc
+
+
+async def list_family_ideas(
+    status: str = "", platform: str = "", limit: int = 50, offset: int = 0,
+) -> dict:
+    """Family ideas — records that every project on a platform shares — with
+    their state: `candidate` (waiting to be evaluated, or held back by a
+    criterion), `canon` (promoted; every project on its platforms answers it)
+    or `retired`.
+
+    Args:
+        status: candidate | canon | retired. Empty = all.
+        platform: a platform slug (list_platforms). Empty = all.
+        limit / offset: page through the list.
+    """
+    ideas = await family_svc.list_ideas(
+        current_user_id(), status=status or None, platform=platform or None,
+        limit=max(1, min(limit, 200)), offset=max(0, offset),
+    )
+    return {"ideas": ideas, "limit": limit, "offset": offset}
+
+
+async def get_family_idea(note_id: int) -> dict:
+    """One family idea with what an evaluation needs: its state, platforms,
+    full decision history, ledger counts, THE THREE CRITERIA, and the
+    `precedents` — the decisions on the ideas nearest this one by meaning.
+    Read the precedents before deciding, and decide consistently with them
+    unless this idea differs in a way you can name.
+
+    Args:
+        note_id: the idea's record id.
+    """
+    uid = current_user_id()
+    idea = await family_svc.get_idea(uid, note_id)
+    if idea is None:
+        raise ValueError(f"#{note_id} is not a family idea you can read")
+    idea["precedents"] = await family_svc.precedents(uid, note_id)
+    return idea
+
+
+async def propose_family_idea(note_id: int, reason: str, applies_when: str = "") -> dict:
+    """Record a note, snippet or lesson as a family-idea CANDIDATE: something
+    you believe every project on some platform will face. It reaches no
+    project's ledger until it is promoted.
+
+    Proposing is cheap and does not promote. When the record already meets
+    the three criteria, call promote_family_idea directly instead.
+
+    Args:
+        note_id: the record that carries the idea.
+        reason: why this looks like a family idea.
+        applies_when: optional draft of when it applies, in platform terms.
+    """
+    idea, created = await family_svc.propose(
+        current_user_id(), note_id, reason=reason, applies_when=applies_when or None,
+    )
+    return {"idea": idea, "created": created}
+
+
+async def promote_family_idea(
+    note_id: int,
+    applies_when: str,
+    platforms: list[str],
+    platform_terms: str,
+    platform_problem: str,
+    proven: str,
+    evidence: list[str],
+    reason: str,
+    precedent_ids: list[int] | None = None,
+) -> dict:
+    """Evaluate a record against the three criteria and, if all hold, promote
+    it to family canon. YOU decide; nobody approves. The record of why is what
+    makes the decision reviewable and the next one consistent.
+
+    An idea is promoted only when ALL THREE hold, and each is answered with
+    your reasoning:
+
+    1. platform_terms — its 'when it applies' is stated in terms of a
+       platform (what a project is built on or ships as), not one app's
+       domain. Any project on the platform could read it and know whether it
+       applies.
+    2. platform_problem — it answers a problem the platform itself causes, or
+       a stance the operator holds across projects. One app's preference does
+       not qualify.
+    3. proven — it has worked for real at least once (CI green, verified on a
+       device, shipped). Name that in `evidence`.
+
+    Any criterion left blank — or `applies_when`, `platforms` or `evidence`
+    left empty — VETOES the promotion on its own. A veto is not an error: the
+    idea stays a candidate and the veto is logged, so the next evaluation of
+    something like it sees why this one was held. That is also how you record
+    "evaluated, and it does not qualify": leave the failing criterion blank
+    and say why in `reason`.
+
+    Before deciding, read get_family_idea's `precedents`. The engine also
+    finds the nearest earlier decisions itself and stores them as consulted.
+
+    On promotion every project that is on one of `platforms` and that you can
+    write gets an `unassessed` row in its adoption ledger. If the idea was
+    canon before, its version moves, so earlier answers read as needing a
+    recheck.
+
+    Args:
+        note_id: the record that carries the idea.
+        applies_when: when it applies, in platform terms.
+        platforms: platform slugs it is for (list_platforms).
+        platform_terms: why criterion 1 holds (blank = it does not).
+        platform_problem: why criterion 2 holds (blank = it does not).
+        proven: why criterion 3 holds (blank = it does not).
+        evidence: what proved it — a CI run, a task, a commit, a device check.
+        reason: the decision in one or two sentences.
+        precedent_ids: earlier family decisions you followed, if any.
+    """
+    return await family_svc.promote(
+        current_user_id(), note_id,
+        applies_when=applies_when, platforms=platforms or [],
+        criteria={
+            "platform_terms": platform_terms,
+            "platform_problem": platform_problem,
+            "proven": proven,
+        },
+        evidence=evidence or [], reason=reason, precedent_ids=precedent_ids or [],
+    )
+
+
+async def retire_family_idea(note_id: int, reason: str) -> dict:
+    """Demote a family idea — it no longer applies, or a better one replaces
+    it. Its history and every judged ledger answer are kept; rows nobody had
+    judged yet are closed. Undoable with undo_family_decision.
+
+    Args:
+        note_id: the idea.
+        reason: why it is retired.
+    """
+    return await family_svc.retire(current_user_id(), note_id, reason=reason)
+
+
+async def undo_family_decision(decision_id: int, reason: str) -> dict:
+    """Reverse a family decision — a promotion, a retirement or a proposal —
+    restoring the state it recorded as `before`. Only the latest idea-level
+    decision on an idea can be undone; the undo is logged too, so the history
+    keeps both.
+
+    Args:
+        decision_id: the decision (list_family_decisions).
+        reason: why it is undone.
+    """
+    return await family_svc.undo(current_user_id(), decision_id, reason=reason)
+
+
+async def list_family_decisions(note_id: int = 0, limit: int = 50, offset: int = 0) -> dict:
+    """The family decision log, newest first: every proposal, promotion,
+    veto, retirement and undo, with its reason, evidence and the precedents
+    it followed. `undoable` marks the decision an undo would reverse.
+
+    Args:
+        note_id: only this idea's decisions. 0 = all.
+        limit / offset: page through the log.
+    """
+    rows = await family_svc.list_decisions(
+        current_user_id(), idea_id=note_id or None,
+        limit=max(1, min(limit, 200)), offset=max(0, offset),
+    )
+    return {"decisions": rows, "limit": limit, "offset": offset}
+
+
+def register(mcp) -> None:
+    for fn in (
+        list_family_ideas, get_family_idea, propose_family_idea,
+        promote_family_idea, retire_family_idea, undo_family_decision,
+        list_family_decisions,
+    ):
+        mcp.tool(name=fn.__name__)(fn)