From fe6b78fa59657449be2e888402e3a0197b5c0621 Mon Sep 17 00:00:00 2001 From: soryu 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.md plus a small pill ('open'/'merged'/ 'closed'). Selecting a revision encodes itself into the existing ?task= param as "revision:", 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) --- .../20260430000000_create_directive_revisions.sql | 35 ++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 makima/migrations/20260430000000_create_directive_revisions.sql (limited to 'makima/migrations') 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'; -- cgit v1.2.3