feat(projection): reconcile a repository's projection against the forge

Implements ADR-012 decision 7 as amended (STATE-WP-0083-T03). Creates what the
forge has and the hub lacks, updates what differs, retires what no longer
derives. It never deletes: hub-native records reference workplans with ON DELETE
RESTRICT, and destroying a progress event to tidy a derived projection would
lose hub-native truth to fix a derived-state problem.

Retirement is refused by default. A record that stops deriving may mean a
deliberately deleted file or a caller pointed at the wrong branch; only the
caller can say which.

Verified against live data and rolled back: whitehat-security applied 5 updates
with no retirements; the-custodian refused, naming the four hub-first records
confirmed by hand to have no backing file.

Tasks of existing workplans are deliberately untouched — hub tasks carry no
canonical identifier, so matching is by title and a renamed heading would
destroy and recreate a record. Tasks are created only alongside a new workplan,
where nothing exists to mis-match. Tracked as T06.

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

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 2583210@bnt-lap001
Assistant-Session: f2bff2d5-e9b2-4338-92ca-10282a927006

api/services/forge_projection.py

@@ -378,3 +378,195 @@ def diff_against_hub(
                      "changed": {"status": {"hub": cur.get("status"), "forge": t.status}}}
                 )
     return d
+
+
+# ---------------------------------------------------------------------------
+# Applying the reset (STATE-WP-0083-T03)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ResetOutcome:
+    repo_slug: str
+    commit: str
+    status: str                      # applied | refused | noop
+    created: list[str] = field(default_factory=list)
+    updated: list[str] = field(default_factory=list)
+    retired: list[str] = field(default_factory=list)
+    refused: list[dict[str, Any]] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema": "state-hub.projection-reset.v1",
+            "repo_slug": self.repo_slug,
+            "commit": self.commit,
+            "status": self.status,
+            "counts": {
+                "created": len(self.created),
+                "updated": len(self.updated),
+                "retired": len(self.retired),
+                "refused": len(self.refused),
+            },
+            "created": self.created,
+            "updated": self.updated,
+            "retired": self.retired,
+            "refused": self.refused,
+            "notes": self.notes,
+        }
+
+
+RETIRE_REASON = "no longer derived from the forge"
+
+
+async def reset_repository_projection(
+    session: Any,
+    repo_slug: str,
+    *,
+    acknowledge_retirements: bool = False,
+    forge_base: str = DEFAULT_FORGE_BASE,
+    derived: DerivedProjection | None = None,
+) -> ResetOutcome:
+    """Reconcile one repository's workplan projection against the forge.
+
+    Creates what the forge has and the hub lacks, updates what differs, and
+    retires what no longer derives. It does not delete: hub-native records
+    reference workplans with `ON DELETE RESTRICT`, and destroying a progress
+    event to tidy a derived projection would lose hub-native truth to fix a
+    derived-state problem (`ADR-012` decision 7 as amended).
+
+    Retirement is refused by default. A record that stops deriving may mean the
+    file was removed deliberately — or that someone pointed this at the wrong
+    branch. The caller must say which.
+
+    Scope: workplans, and the tasks of workplans being created. Tasks of
+    *existing* workplans are left alone, because hub task rows carry no
+    canonical identifier and can only be matched by title — renaming a heading
+    would otherwise destroy and recreate its record (`T06`).
+    """
+    from datetime import datetime, timezone
+
+    from sqlalchemy import select
+
+    from api.models.managed_repo import ManagedRepo
+    from api.models.task import Task
+    from api.models.workplan import Workplan
+
+    derived = derived or derive_from_forge(repo_slug, forge_base=forge_base)
+    outcome = ResetOutcome(repo_slug=repo_slug, commit=derived.commit, status="noop")
+
+    repo = (
+        await session.execute(select(ManagedRepo).where(ManagedRepo.slug == repo_slug))
+    ).scalar_one_or_none()
+    if repo is None:
+        outcome.status = "refused"
+        outcome.refused.append({"reason": "repository is not registered", "slug": repo_slug})
+        return outcome
+
+    rows = list(
+        (
+            await session.execute(select(Workplan).where(Workplan.repo_id == repo.id))
+        ).scalars()
+    )
+
+    want = {w.record_id.strip().lower(): w for w in derived.workplans}
+    want_paths = {_path_key(w.relative_path): k for k, w in want.items()}
+
+    matched: dict[str, Any] = {}
+    for row in rows:
+        key = (row.slug or "").strip().lower()
+        if key not in want:
+            bp = row.backing_relative_path
+            if bp and _path_key(bp) in want_paths:
+                key = want_paths[_path_key(bp)]
+            else:
+                cand = [k for k in want if key.startswith(k + "-")]
+                key = cand[0] if len(cand) == 1 else key
+        matched[key] = row
+
+    stale = [
+        r for k, r in matched.items()
+        if k not in want and r.projection_retired_at is None
+    ]
+    if stale and not acknowledge_retirements:
+        outcome.status = "refused"
+        for r in stale:
+            outcome.refused.append(
+                {
+                    "reason": "would be retired; the forge no longer derives it",
+                    "slug": r.slug,
+                    "status": r.status,
+                    "backing_relative_path": r.backing_relative_path,
+                }
+            )
+        outcome.notes.append(
+            "Re-run with acknowledgement to retire these. Nothing was changed."
+        )
+        return outcome
+
+    now = datetime.now(tz=timezone.utc)
+
+    for key, w in want.items():
+        row = matched.get(key)
+        if row is None:
+            row = Workplan(
+                id=uuid.UUID(w.uuid),
+                repo_id=repo.id,
+                topic_id=repo.topic_id,
+                slug=w.record_id.lower(),
+                title=w.title or w.record_id,
+                status=w.status or "proposed",
+                backing_filename=w.relative_path.rsplit("/", 1)[-1],
+                backing_relative_path=w.relative_path,
+                backing_archived=w.archived,
+                derived_from_commit=derived.commit,
+            )
+            session.add(row)
+            await session.flush()
+            for t in w.tasks:
+                # Safe only because nothing exists to mis-match against: this
+                # workplan is new to the hub.
+                session.add(
+                    Task(
+                        id=uuid.UUID(t.uuid),
+                        workplan_id=row.id,
+                        title=t.title or t.record_id,
+                        status=t.status or "todo",
+                        priority=t.priority or "medium",
+                    )
+                )
+            outcome.created.append(w.record_id)
+            continue
+
+        changed = False
+        if w.status and row.status != w.status:
+            row.status = w.status
+            changed = True
+        if row.backing_relative_path != w.relative_path:
+            row.backing_relative_path = w.relative_path
+            row.backing_filename = w.relative_path.rsplit("/", 1)[-1]
+            row.backing_archived = w.archived
+            changed = True
+        if row.projection_retired_at is not None:
+            # It derives again; un-retire rather than leaving a contradiction.
+            row.projection_retired_at = None
+            row.projection_retired_reason = None
+            changed = True
+        if row.derived_from_commit != derived.commit:
+            row.derived_from_commit = derived.commit
+            changed = True
+        if changed:
+            outcome.updated.append(w.record_id)
+
+    for r in stale:
+        r.projection_retired_at = now
+        r.projection_retired_reason = RETIRE_REASON
+        outcome.retired.append(r.slug or str(r.id))
+
+    if outcome.created or outcome.updated or outcome.retired:
+        outcome.status = "applied"
+    outcome.notes.append(
+        "Tasks of existing workplans were not touched; hub tasks carry no "
+        "canonical identifier (STATE-WP-0083-T06)."
+    )
+    return outcome