From ce29ae801bcc5a0ba76d5a8d1565242ab267a47d Mon Sep 17 00:00:00 2001
From: soryu <soryu@soryu.co>
Date: Sat, 16 May 2026 19:56:21 +0100
Subject: feat(directives): strict orchestration flow + sidebar overhaul + task
 page rewrite (#134)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

End-to-end rewrite addressing the issues from the user's UX review.
The system now feels like a daemon-orchestration tool: lock a contract
and the orchestrator just goes; PR raised → auto-ship → reopen for
amendments. The sidebar tree shows real entities only (no duplicates,
no inline action buttons polluting the file list), and every entity
gets a right-click context menu. Task page matches the old /exec
layout (diff on the left, feed + composer on the right).

## Backend — strict lifecycle (the orchestrator-never-spawned bug)

Root cause: `phase_planning()` gates on `directive.status='active'`, but
`start_contract()` only flipped the contract row — the parent directive
stayed in whatever state it was. So locking a contract did nothing
visible.

Fix: contract lifecycle now drives directive status in the same
transaction.

  start_contract   → if contract becomes active, flip directive
                     draft|paused|idle|inactive → active
  pause_contract   → after promote, if no active contract left,
                     directive → paused
  complete_contract→ after promote, if no active left, directive →
                     inactive (also fires on auto-ship from PR detect)
  unlock_contract  → if was active and no active left, directive →
                     paused
  reopen_contract  → NEW. shipped → active. Directive → active,
                     orchestrator_task_id/pr_url/pr_branch cleared so
                     the reconciler spawns a fresh planner. The
                     planner reads get_latest_merged_revision and
                     frames the new plan as an amendment.

handlers::directive_documents lifts state.kick_directive_reconciler()
into run_contract_transition so every successful transition wakes the
reconciler immediately (no 15s wait).

handlers::directives `update_directive` (PR-detection branch) calls
`complete_contract(active_contract_id, pr_url, pr_branch)` instead of
`set_directive_inactive`. The contract auto-ships; the directive
follows via the sync above. No more manual "Mark complete" click.

POST /api/v1/contracts/{id}/reopen added + wired through openapi.

Spawn task names dropped the directive-title prefix that looked
redundant in the sidebar:
  "Plan: <title>"      → "orchestrator"
  "Re-plan: <title>"   → "orchestrator (re-plan)"
  "PR: <title>"        → "completion"
  "Update PR: <title>" → "completion (update)"

## Frontend — sidebar

* De-dupe: DocumentTasksFolder filters tasks[] to exclude any task
  whose id already appears in steps[].taskId. Single row per task,
  single highlight on click.
* Generic SidebarContextMenu (new) replaces the directive-only
  DirectiveContextMenu (deleted). Per-entity item arrays built at the
  page level — directive, contract, step, task each have their own
  contextual actions.
* Right-click works on every sidebar entity now (was directive-only).
* `+ New document` / `+ New ephemeral task` inline buttons removed.
  Reachable via the directive folder right-click OR the hover-only
  `+` button on the directive folder row.
* ContractHeader: dropped "Mark complete" button (auto-fires on PR).
  Added "Reopen for amendment" button when contract is shipped.

## Frontend — task page rewrite

TaskPage.tsx replaces DocumentTaskStream.tsx (deleted). Two-column
layout matches the old /exec page that the user preferred:

  ┌────────────────────────┬──────────────────────────────────┐
  │  Changed files (~30%)  │  Transcript feed (scrollable)    │
  │  ──────────────────    │  ──────────────────────          │
  │  src/foo.rs            │  [user] do thing                 │
  │  src/bar.rs            │  [tool] Read foo.rs              │
  │                        │                                  │
  │  Diff (selected file)  │                                  │
  │                        ├──────────────────────────────────┤
  │                        │  Composer (sticky bottom)        │
  └────────────────────────┴──────────────────────────────────┘

Diff comes from getTaskDiff(); parseDiff + DiffFileView exported from
OverlayDiffViewer for reuse (no duplication). Diff auto-refreshes
when the task transitions to a terminal state. Transcript styling +
sticky composer keep the parts the user liked. "Open in task page"
button removed — the right pane IS the task page.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../frontend/src/components/SidebarContextMenu.tsx | 108 +++++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 makima/frontend/src/components/SidebarContextMenu.tsx

(limited to 'makima/frontend/src/components/SidebarContextMenu.tsx')

diff --git a/makima/frontend/src/components/SidebarContextMenu.tsx b/makima/frontend/src/components/SidebarContextMenu.tsx
new file mode 100644
index 0000000..a7b0ae6
--- /dev/null
+++ b/makima/frontend/src/components/SidebarContextMenu.tsx
@@ -0,0 +1,108 @@
+import { useEffect, useRef } from "react";
+
+// Generic right-click context menu for the sidebar tree. Each call site
+// (directive folder, contract row, step row, task row, …) builds its own
+// items array. Lifts the viewport-clamping + click-outside / Esc logic
+// out of the deleted DirectiveContextMenu so we don't end up with one
+// component per entity type.
+
+export interface ContextMenuItem {
+  /** Display text. Empty for separators. */
+  label: string;
+  /** Click handler. Ignored when `separator` is true. */
+  onClick?: () => void;
+  /** Render in red — for destructive operations (delete, archive). */
+  danger?: boolean;
+  /** Render as a thin divider instead of a button. */
+  separator?: boolean;
+  /** Greyed out, non-clickable. Used for items whose preconditions
+   *  aren't met (e.g. "Reopen" on an already-draft contract). */
+  disabled?: boolean;
+}
+
+interface SidebarContextMenuProps {
+  x: number;
+  y: number;
+  items: ContextMenuItem[];
+  onClose: () => void;
+}
+
+export function SidebarContextMenu({ x, y, items, onClose }: SidebarContextMenuProps) {
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  // Close on click outside or Esc.
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (menuRef.current && !menuRef.current.contains(e.target as Node)) {
+        onClose();
+      }
+    };
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    document.addEventListener("mousedown", handleClickOutside);
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("mousedown", handleClickOutside);
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [onClose]);
+
+  // Clamp into viewport if the menu would overflow off the right or
+  // bottom edge.
+  useEffect(() => {
+    if (menuRef.current) {
+      const rect = menuRef.current.getBoundingClientRect();
+      const viewportWidth = window.innerWidth;
+      const viewportHeight = window.innerHeight;
+      if (rect.right > viewportWidth) {
+        menuRef.current.style.left = `${x - rect.width}px`;
+      }
+      if (rect.bottom > viewportHeight) {
+        menuRef.current.style.top = `${y - rect.height}px`;
+      }
+    }
+  }, [x, y]);
+
+  const baseItemClass =
+    "w-full px-3 py-1.5 text-left text-xs font-mono flex items-center gap-2";
+  const enabledClass = "text-[#9bc3ff] hover:bg-[rgba(117,170,252,0.1)]";
+  const dangerClass = "text-red-400 hover:bg-[rgba(239,68,68,0.1)]";
+  const disabledClass = "text-[#3a4a6a] cursor-not-allowed";
+  const dividerClass = "border-t border-[rgba(117,170,252,0.2)] my-1";
+
+  return (
+    <div
+      ref={menuRef}
+      className="fixed z-50 min-w-[180px] bg-[#0a1628] border border-[rgba(117,170,252,0.3)] rounded shadow-lg py-1"
+      style={{ left: x, top: y }}
+      onContextMenu={(e) => e.preventDefault()}
+    >
+      {items.map((item, i) => {
+        if (item.separator) {
+          return <div key={`sep-${i}`} className={dividerClass} />;
+        }
+        const cls = item.disabled
+          ? disabledClass
+          : item.danger
+          ? dangerClass
+          : enabledClass;
+        return (
+          <button
+            key={`item-${i}-${item.label}`}
+            type="button"
+            disabled={item.disabled}
+            onClick={() => {
+              if (item.disabled) return;
+              item.onClick?.();
+              onClose();
+            }}
+            className={`${baseItemClass} ${cls}`}
+          >
+            {item.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
-- 
cgit v1.2.3

