feat(directives): per-PR revision snapshots + sidebar history (#112)

Stage 3 of the doc-mode revamp. Builds the foundation for treating contracts
as living specifications by freezing their content into a revision every
time a PR is raised.

## directive_revisions table (new migration)

(id, directive_id, content, pr_url, pr_branch, pr_state, version, frozen_at)
with UNIQUE(directive_id, version) and a partial index on pr_state='open'
so the next reconciler iteration can poll only what's still in flight.

pr_state is constrained to 'open' | 'merged' | 'closed' to mirror GitHub's
PR lifecycle. For Stage 3 we only freeze on PR creation; pr_state poll is
deferred to a follow-up.

## Repository helpers

- create_directive_revision: idempotent on (directive_id, pr_url) so a
  re-run of the orchestrator's completion task can't double-snapshot.
  Auto-assigns version = MAX(existing) + 1 per directive.
- list_directive_revisions_for_owner: scoped through the directive join
  so users can only read their own contract history.
- update_directive_revision_pr_state: stub for the upcoming poller.
- get_latest_merged_revision: returns the most recent merged revision —
  this is what Stage 4 will diff against on amendments.

## Snapshot trigger

update_directive handler now reads the BEFORE pr_url before the update.
If pr_url transitions None → Some, it snapshots the directive's current
goal as a revision tied to the new pr_url. Failures log and continue —
the directive update itself is unaffected.

## API + OpenAPI

GET /api/v1/directives/{id}/revisions returns DirectiveRevisionListResponse
(revisions newest-first). Schemas registered in OpenAPI.

## Frontend: revisions/ subfolder + read-only viewer

Each contract folder now has a third subfolder ("revisions/") that lazily
fetches and lists past revisions when the parent directive folder is open.
Empty contracts skip the subfolder entirely so brand-new ones aren't
cluttered. Each row shows v<N>.md plus a small pill ('open'/'merged'/
'closed').

Selecting a revision encodes itself into the existing ?task= param as
"revision:<id>", so EditorShell can route between the live task stream
(realTaskId), the read-only RevisionViewer (revisionId), or the editor
itself (neither). The viewer renders the frozen markdown verbatim with
a deep-link to the PR — these are immutable historical records, not edit
surfaces.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

1 files changed, 35 insertions, 0 deletions

diff --git a/makima/migrations/20260430000000_create_directive_revisions.sql b/makima/migrations/20260430000000_create_directive_revisions.sql
new file mode 100644
index 0000000..49d5179
--- /dev/null
+++ b/makima/migrations/20260430000000_create_directive_revisions.sql
@@ -0,0 +1,35 @@
+-- Per-PR snapshots of a directive (contract) goal, plus the PR's lifecycle
+-- state. A new revision is created when a directive transitions from "no PR"
+-- to "has PR" (i.e. the orchestrator's completion task raises one). The
+-- revision is the immutable record of what the contract said when it
+-- produced that PR.
+--
+-- pr_state mirrors the GitHub PR state: 'open' | 'merged' | 'closed'.
+-- Updated by the reconciler when the underlying PR transitions.
+CREATE TABLE directive_revisions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    directive_id UUID NOT NULL REFERENCES directives(id) ON DELETE CASCADE,
+    -- Snapshot of `directives.goal` (inline markdown) at PR-creation time.
+    content TEXT NOT NULL,
+    -- The PR URL this revision is attached to. Mandatory because revisions
+    -- are only frozen at PR-raise time.
+    pr_url TEXT NOT NULL,
+    -- The PR branch name; useful for diffing without a round-trip to GitHub.
+    pr_branch TEXT,
+    -- 'open' | 'merged' | 'closed'.
+    pr_state TEXT NOT NULL DEFAULT 'open'
+        CHECK (pr_state IN ('open', 'merged', 'closed')),
+    -- Per-directive monotonically increasing version starting at 1.
+    version INTEGER NOT NULL,
+    frozen_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (directive_id, version)
+);
+
+CREATE INDEX idx_directive_revisions_directive_id
+    ON directive_revisions(directive_id, frozen_at DESC);
+
+-- Partial index over still-open PRs so the reconciler can quickly find what
+-- to poll.
+CREATE INDEX idx_directive_revisions_open_prs
+    ON directive_revisions(pr_state)
+    WHERE pr_state = 'open';