From fe6b78fa59657449be2e888402e3a0197b5c0621 Mon Sep 17 00:00:00 2001
From: soryu <soryu@soryu.co>
Date: Thu, 30 Apr 2026 17:08:30 +0100
Subject: feat(directives): per-PR revision snapshots + sidebar history (#112)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 makima/frontend/src/lib/api.ts | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

(limited to 'makima/frontend/src/lib')

diff --git a/makima/frontend/src/lib/api.ts b/makima/frontend/src/lib/api.ts
index 8896f2c..e3dbc30 100644
--- a/makima/frontend/src/lib/api.ts
+++ b/makima/frontend/src/lib/api.ts
@@ -3451,6 +3451,40 @@ export interface PickUpOrdersResponse {
   taskId: string | null;
 }
 
+/**
+ * Per-PR snapshot of a directive's goal — frozen at PR creation, lifecycle
+ * tracked alongside the PR itself.
+ */
+export interface DirectiveRevision {
+  id: string;
+  directiveId: string;
+  /** Inline-markdown content of the directive goal at the moment the PR was raised. */
+  content: string;
+  prUrl: string;
+  prBranch: string | null;
+  /** "open" | "merged" | "closed" — tracks the PR lifecycle. */
+  prState: string;
+  version: number;
+  frozenAt: string;
+}
+
+export interface DirectiveRevisionListResponse {
+  revisions: DirectiveRevision[];
+  total: number;
+}
+
+export async function listDirectiveRevisions(
+  directiveId: string,
+): Promise<DirectiveRevisionListResponse> {
+  const res = await authFetch(
+    `${API_BASE}/api/v1/directives/${directiveId}/revisions`,
+  );
+  if (!res.ok) {
+    throw new Error(`Failed to list revisions: ${res.statusText}`);
+  }
+  return res.json();
+}
+
 export async function createDirectivePR(id: string): Promise<DirectiveWithSteps> {
   const res = await authFetch(`${API_BASE}/api/v1/directives/${id}/create-pr`, { method: "POST" });
   if (!res.ok) throw new Error(`Failed to create PR: ${res.statusText}`);
-- 
cgit v1.2.3