From 8cd7b40ace4e5e2b22ad89aafec74c7655def19b Mon Sep 17 00:00:00 2001
From: soryu <soryu@soryu.co>
Date: Sat, 16 May 2026 19:55:34 +0100
Subject: feat(directives): strict orchestration flow + sidebar overhaul + task
 page rewrite
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>
---
 .../components/directives/DirectiveContextMenu.tsx | 251 ---------------------
 1 file changed, 251 deletions(-)
 delete mode 100644 makima/frontend/src/components/directives/DirectiveContextMenu.tsx

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

diff --git a/makima/frontend/src/components/directives/DirectiveContextMenu.tsx b/makima/frontend/src/components/directives/DirectiveContextMenu.tsx
deleted file mode 100644
index eda7e7f..0000000
--- a/makima/frontend/src/components/directives/DirectiveContextMenu.tsx
+++ /dev/null
@@ -1,251 +0,0 @@
-import { useEffect, useRef } from "react";
-import type { DirectiveSummary } from "../../lib/api";
-
-interface DirectiveContextMenuProps {
-  x: number;
-  y: number;
-  directive: DirectiveSummary;
-  onClose: () => void;
-  onStart: () => void;
-  onPause: () => void;
-  onArchive: () => void;
-  onDelete: () => void;
-  onGoToPR: () => void;
-  /**
-   * Reset the contract to a fresh empty draft (clears goal + pr_url, status
-   * back to 'draft'). Past revisions stay as history. Optional so the legacy
-   * tabular UI doesn't have to wire it up.
-   */
-  onNewDraft?: () => void;
-  /** Trigger a fresh PR creation from the current contract state. */
-  onCreatePR?: () => void;
-  /** Manually advance the DAG (find newly-ready steps). */
-  onAdvance?: () => void;
-  /** Run the cleanup task to prune merged/stale steps. */
-  onCleanup?: () => void;
-  /** Pick up linked orders (queue them as new steps). */
-  onPickUpOrders?: () => void;
-}
-
-export function DirectiveContextMenu({
-  x,
-  y,
-  directive,
-  onClose,
-  onStart,
-  onPause,
-  onArchive,
-  onDelete,
-  onGoToPR,
-  onNewDraft,
-  onCreatePR,
-  onAdvance,
-  onCleanup,
-  onPickUpOrders,
-}: DirectiveContextMenuProps) {
-  const menuRef = useRef<HTMLDivElement>(null);
-
-  // Close on click outside
-  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]);
-
-  // Adjust position if menu would overflow viewport
-  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 menuItemClass =
-    "w-full px-3 py-1.5 text-left text-xs font-mono text-[#9bc3ff] hover:bg-[rgba(117,170,252,0.1)] flex items-center gap-2";
-  const dividerClass = "border-t border-[rgba(117,170,252,0.2)] my-1";
-
-  const showStart = directive.status === "draft" || directive.status === "paused" || directive.status === "idle";
-  const showPause = directive.status === "active";
-  const showArchive = directive.status !== "archived";
-  const showGoToPR = !!directive.prUrl;
-  // "New draft" appears once the contract is inactive (its iteration has
-  // shipped) — that's the explicit affordance for starting the next cycle
-  // on a clean slate while keeping prior revisions as history.
-  const showNewDraft = !!onNewDraft && directive.status === "inactive";
-
-  return (
-    <div
-      ref={menuRef}
-      className="fixed z-50 bg-[#0a1628] border border-[rgba(117,170,252,0.3)] shadow-lg min-w-[180px]"
-      style={{ left: x, top: y }}
-    >
-      {/* Header showing directive title */}
-      <div className="px-3 py-1.5 text-[10px] font-mono text-[#555] uppercase border-b border-[rgba(117,170,252,0.2)] truncate max-w-[200px]">
-        {directive.title}
-      </div>
-
-      {/* New draft — the canonical action on an inactive (shipped) contract. */}
-      {showNewDraft && (
-        <>
-          <button
-            className={menuItemClass}
-            onClick={() => {
-              onNewDraft?.();
-              onClose();
-            }}
-          >
-            <span className="text-emerald-300">＋</span>
-            New draft
-          </button>
-          <div className={dividerClass} />
-        </>
-      )}
-
-      {/* Status actions */}
-      {showStart && (
-        <button
-          className={menuItemClass}
-          onClick={() => {
-            onStart();
-            onClose();
-          }}
-        >
-          <span className="text-[#75aafc]">▶</span>
-          Start
-        </button>
-      )}
-
-      {showPause && (
-        <button
-          className={menuItemClass}
-          onClick={() => {
-            onPause();
-            onClose();
-          }}
-        >
-          <span className="text-[#75aafc]">❚❚</span>
-          Pause
-        </button>
-      )}
-
-      {showArchive && (
-        <button
-          className={menuItemClass}
-          onClick={() => {
-            onArchive();
-            onClose();
-          }}
-        >
-          <span className="text-[#75aafc]">▣</span>
-          Archive
-        </button>
-      )}
-
-      {/* Orchestration actions — Advance / Pick up orders / Cleanup. */}
-      {(onAdvance || onPickUpOrders || onCleanup) && (
-        <div className={dividerClass} />
-      )}
-      {onAdvance && (
-        <button
-          className={menuItemClass}
-          onClick={() => {
-            onAdvance();
-            onClose();
-          }}
-        >
-          <span className="text-[#75aafc]">»</span>
-          Advance DAG
-        </button>
-      )}
-      {onPickUpOrders && (
-        <button
-          className={menuItemClass}
-          onClick={() => {
-            onPickUpOrders();
-            onClose();
-          }}
-        >
-          <span className="text-[#c084fc]">◆</span>
-          Plan orders
-        </button>
-      )}
-      {onCleanup && (
-        <button
-          className={menuItemClass}
-          onClick={() => {
-            onCleanup();
-            onClose();
-          }}
-        >
-          <span className="text-[#75aafc]">⎚</span>
-          Clean up
-        </button>
-      )}
-
-      {/* PR actions — Create / Update / Go to PR. */}
-      {(onCreatePR || showGoToPR) && <div className={dividerClass} />}
-      {onCreatePR && (
-        <button
-          className={menuItemClass}
-          onClick={() => {
-            onCreatePR();
-            onClose();
-          }}
-        >
-          <span className="text-emerald-300">↗</span>
-          {directive.prUrl ? "Update PR" : "Create PR"}
-        </button>
-      )}
-      {showGoToPR && (
-        <button
-          className={menuItemClass}
-          onClick={() => {
-            onGoToPR();
-            onClose();
-          }}
-        >
-          <span className="text-[#75aafc]">↗</span>
-          Go to PR
-        </button>
-      )}
-
-      <div className={dividerClass} />
-
-      {/* Delete action */}
-      <button
-        className={`${menuItemClass} text-red-400 hover:bg-red-400/10`}
-        onClick={() => {
-          onDelete();
-          onClose();
-        }}
-      >
-        <span className="text-red-400">✕</span>
-        Delete
-      </button>
-    </div>
-  );
-}
-- 
cgit v1.2.3

