@mrciphersmith/keryx 0.2.144 → 0.2.145

package/README.md

@@ -255,9 +255,12 @@ What is in it today:
   completed, blocked, and skipped steps in the sidebar, and restored sessions
   continue from the same plan instead of rebuilding it from transcript text.
   Clicking the sidebar's Plan section (its header or any row) opens the whole
-  plan in a modal: a Steps tab grouped and coloured by state, a Meta tab with the
-  revision, per-status counts, the active item, the blocked ids, and the plan
-  file it lives in.
+  plan in a modal: a Plan tab that spells each item's status out and colours it
+  by state, a Meta tab with the revision, per-status counts, the active item, the
+  blocked ids, and the plan file it lives in. A plan can also be published FOR
+  APPROVAL — items marked `proposed` await a human, never force the agent to
+  continue, and are shown as `◇ awaiting approval` in both the sidebar and the
+  modal.
 - **Theme-aware rich transcripts.** Assistant prose, headings, emphasis,
   inline code, fenced code, diffs, and GFM pipe tables use semantic colors
   derived from the selected `/theme`. Use a language fence such as

package/dist/cli.js

@@ -24214,6 +24214,9 @@ async function updateExecutionPlan(dir, input) {
 function hasActionableExecutionPlanItems(plan) {
   return plan?.items.some((item) => item.status === "pending" || item.status === "in_progress") ?? false;
 }
+function executionPlanApprovalItems(plan) {
+  return plan?.items.filter((item) => item.status === "proposed") ?? [];
+}
 function renderExecutionPlanSnapshot(plan, maxItems = 7) {
   if (plan === undefined || plan.items.length === 0)
     return;
@@ -24231,7 +24234,7 @@ var EXECUTION_PLAN_STATUSES, listeners, ExecutionPlanConflictError, ExecutionPla
 var init_execution_plan = __esm(() => {
   init_fs();
   init_slate();
-  EXECUTION_PLAN_STATUSES = ["pending", "in_progress", "completed", "blocked", "skipped"];
+  EXECUTION_PLAN_STATUSES = ["proposed", "pending", "in_progress", "completed", "blocked", "skipped"];
   listeners = new Set;
   ExecutionPlanConflictError = class ExecutionPlanConflictError extends Error {
     constructor(expected, actual) {
@@ -29527,7 +29530,7 @@ function buildAgentSystemInstruction(orient, ctx = {}) {
 ` + locateRule + "- read_file returns a bounded window starting at `start_line` (default 1). A large file " + "is read by paging: its truncation notice names the start_line to continue from, and a " + `line number from ${hasGraph ? "search_code or graph_symbol" : "search_code"} can be read directly \u2014 do not re-read the ` + `same head hoping for more.
 ` + "- Prefer ONE correct shell_exec over many exploratory tool calls when the user asks " + `to run a known keryx workflow.
 ` + "- Tool-call budget: shell_exec, file-mutating shell, workspace_create/workspace_propose, and spawn_subagent " + "all share ONE small per-turn pool (distinct non-read actions), separate from the much larger read-tool pool. " + (hasGraph ? "search_code/graph_*/memory_search/read_wiki/wiki_*/test_related/health_status/flow_status/repomap/read_file/" : "search_code/read_file/") + "list_dir do NOT touch it. Conserve the small pool: batch multiple shell steps into ONE call with `&&` instead " + "of issuing them one at a time, get a command's arguments right the first time instead of trying variants, and " + "for any check covered by a read tool above, use that tool instead of shelling out to the equivalent `keryx \u2026` " + `CLI command.
-` + "- For multi-step work, use **plan_set** to publish a structured plan, **plan_update** after each real status " + "change, and **plan_get** before resolving a revision conflict. Keep stable item ids, at most one " + "`in_progress` item, and do not mark work complete before verification. These tools update session metadata " + "only; `/plan` remains the operator's separate read-only permission mode.\n" + "- This session has its own Slate (working-set scratch, not project knowledge): " + "**slate_read** shows the Course (if a Flow is bound) and Seeds recorded so far \u2014 nothing " + "here is auto-injected, so call it if you want to see it. **slate_write_seed** with " + "`{ text, kind? }` records a draft hypothesis/decision/follow-up worth a later human " + "review. WRITE A SEED when you: found a root cause or a bug worth remembering; changed or " + "added code (summarize WHAT changed and WHY); took a design/architecture decision; " + "identified a risk; or discovered a constraint/lesson. Use the `kind` that fits: " + "`decision` (a choice made), `wiki-update` (something a wiki page should say), " + "`memory-entry` (a lesson/constraint), `follow-up` (a TODO for a later session), " + "`risk`, or `contract-change`. Keep each Seed to 2-3 sentences, concrete and specific. " + "Do NOT write Seeds for routine progress notes, one-shot operational requests (e.g. " + '"run git pull", "count files"), or trivia \u2014 those need no workspace and no proposal. ' + "Seeds are the ONLY input wrap-up proposes from: a session whose Slate has zero Seeds " + `produces zero proposals. A Seed is never accepted knowledge by itself.
+` + "- For multi-step work, use **plan_set** to publish a structured plan, **plan_update** after each real status " + "change, and **plan_get** before resolving a revision conflict. Keep stable item ids, at most one " + "`in_progress` item, and do not mark work complete before verification. These tools update session metadata " + "only; `/plan` remains the operator's separate read-only permission mode.\n" + "- **Publishing a plan FOR APPROVAL is a real, supported stopping point.** Mark the items `proposed`, " + "state the plan in your reply, and END THE TURN: `proposed` is not work in progress, so it never forces " + "another round on its own. When the operator approves, move those items to `pending`/`in_progress` and " + "continue. Use `pending` (not `proposed`) only when you are going to execute the plan in this same turn.\n" + "- This session has its own Slate (working-set scratch, not project knowledge): " + "**slate_read** shows the Course (if a Flow is bound) and Seeds recorded so far \u2014 nothing " + "here is auto-injected, so call it if you want to see it. **slate_write_seed** with " + "`{ text, kind? }` records a draft hypothesis/decision/follow-up worth a later human " + "review. WRITE A SEED when you: found a root cause or a bug worth remembering; changed or " + "added code (summarize WHAT changed and WHY); took a design/architecture decision; " + "identified a risk; or discovered a constraint/lesson. Use the `kind` that fits: " + "`decision` (a choice made), `wiki-update` (something a wiki page should say), " + "`memory-entry` (a lesson/constraint), `follow-up` (a TODO for a later session), " + "`risk`, or `contract-change`. Keep each Seed to 2-3 sentences, concrete and specific. " + "Do NOT write Seeds for routine progress notes, one-shot operational requests (e.g. " + '"run git pull", "count files"), or trivia \u2014 those need no workspace and no proposal. ' + "Seeds are the ONLY input wrap-up proposes from: a session whose Slate has zero Seeds " + `produces zero proposals. A Seed is never accepted knowledge by itself.
 ` + "- Shared Agent Context (SAC) workspaces hold accepted, evidence-backed project context " + "beyond this codebase. **workspace_list** with `{ includeArchived? }` shows every workspace " + "visible to you \u2014 call it first when the user references a shared team workspace or accepted " + "project context, or before creating a new workspace, to judge whether an existing one " + "already fits the current topic. **workspace_show** with `{ workspaceId }` shows one " + "workspace's manifest. **workspace_overview** with `{ workspaceId }`, then **workspace_read** " + "with `{ workspaceId, itemId }` for one specific item, reads its accepted Facts/Work/Know-how. " + "**workspace_create** with `{ title, component? }` creates a new workspace AND binds it to " + "this session's slate (wrap-up then proposes into it) \u2014 only when workspace_list found no " + "fitting one and the session has real, durable results worth persisting; a workspace is " + "meant to persist across sessions, so prefer an existing one over creating another for the " + "same topic, and do NOT create one for one-shot operational requests. **workspace_propose** with " + "`{ workspaceId, kind, sessionId?, note? }` (sessionId defaults to this session) proposes a decision/wiki-update/memory-entry/" + "follow-up/contract-change/risk from this session for later human review \u2014 it never accepts " + "anything by itself; accepting always requires a human running `keryx workspace review` at a " + `real terminal, never this tool.
 ` + "- When you need a decision, interview step, or clarification: use **ask_user** with " + "2\u20136 options `{ id, label, description, recommended? }` (mark one recommended). " + `Do not dump long prose questions without options.
 ` + "- For a focused independent subtask (investigate X, review Y, research Z): use " + "**spawn_subagent** with `{ task, mode?: 'read_only'|'general', label? }`. " + "Default mode is read_only (no shell). Prefer spawn for work that can finish " + `without your intermediate turns; do not spawn for trivial one-line answers.
@@ -30093,6 +30096,19 @@ ${planSnapshot}`;
         }
         continue;
       }
+      const approvalItems = executionPlanApprovalItems(currentPlan);
+      if (approvalItems.length > 0 && !hasActionableExecutionPlanItems(currentPlan)) {
+        const shown = approvalItems.slice(0, 7).map((item) => `- ${item.id}: ${item.title.length > 120 ? `${item.title.slice(0, 119)}\u2026` : item.title}`);
+        if (approvalItems.length > shown.length) {
+          shown.push(`- \u2026 ${approvalItems.length - shown.length} more`);
+        }
+        system(`
+[plan] Published for your approval \u2014 nothing is in progress, so this turn ends here:
+${shown.join(`
+`)}
+` + `Approve by continuing (the agent moves them to pending/in_progress), or ask for changes.
+`);
+      }
       if (!planFollowThroughUsed && hasActionableExecutionPlanItems(currentPlan)) {
         planFollowThroughUsed = true;
         history.push({
@@ -51447,7 +51463,7 @@ import path47 from "path";
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.144",
+  version: "0.2.145",
   description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   private: false,
   publishConfig: {
@@ -102987,6 +103003,7 @@ init_execution_plan();
 // src/tui/execution-plan-panel.ts
 init_execution_plan();
 var GLYPHS = {
+  proposed: "\u25C7",
   completed: "\u2713",
   in_progress: "\u25B6",
   pending: "\u25CB",
@@ -103013,8 +103030,12 @@ function projectExecutionPlanPanel(plan, options) {
     return { visible: false, rows: [], revision: undefined };
   }
   const size = Math.max(1, Math.min(options.maxRows ?? 7, 7, plan.items.length));
-  const active = Math.max(0, plan.items.findIndex((item) => item.status === "in_progress"));
-  const start = Math.max(0, Math.min(active - Math.floor(size / 2), plan.items.length - size));
+  const firstOf = (status) => plan.items.findIndex((i) => i.status === status);
+  const anchorIndex = firstOf("in_progress");
+  const pendingIndex = firstOf("pending");
+  const proposedIndex = firstOf("proposed");
+  const anchor = anchorIndex >= 0 ? anchorIndex : pendingIndex >= 0 ? pendingIndex : Math.max(0, proposedIndex);
+  const start = Math.max(0, Math.min(anchor - Math.floor(size / 2), plan.items.length - size));
   const rows = plan.items.slice(start, start + size).map((item) => {
     const glyph = GLYPHS[item.status];
     return { id: item.id, status: item.status, glyph, text: truncate7(`${glyph} ${item.title}`, options.width) };
@@ -103085,6 +103106,7 @@ var PLAN_INSPECTOR_FOOTER = [
   { key: "esc", label: "close" }
 ];
 var PLAN_STATUS_GLYPH = {
+  proposed: "\u25C7",
   completed: "\u2713",
   in_progress: "\u25B6",
   pending: "\u25CB",
@@ -103092,6 +103114,7 @@ var PLAN_STATUS_GLYPH = {
   skipped: "\u2212"
 };
 var PLAN_STATUS_LABEL = {
+  proposed: "awaiting approval",
   completed: "completed",
   in_progress: "in progress",
   pending: "pending",
@@ -103099,6 +103122,7 @@ var PLAN_STATUS_LABEL = {
   skipped: "skipped"
 };
 var PLAN_STATUS_ORDER = [
+  "proposed",
   "in_progress",
   "pending",
   "blocked",
@@ -103108,6 +103132,7 @@ var PLAN_STATUS_ORDER = [
 var PLAN_EMPTY_TEXT = "No execution plan in this session. The agent publishes one with `plan_set` before multi-step work.";
 function planCounts(plan) {
   const counts = {
+    proposed: 0,
     completed: 0,
     in_progress: 0,
     pending: 0,
@@ -103136,6 +103161,7 @@ function formatPlanSummary(plan) {
   const parts = [
     `revision ${plan.revision}`,
     `${counts.completed}/${plan.items.length} done`,
+    ...counts.proposed > 0 ? [`${counts.proposed} awaiting approval`] : [],
     ...counts.in_progress > 0 ? [`${counts.in_progress} in progress`] : [],
     ...counts.blocked > 0 ? [`${counts.blocked} blocked`] : [],
     ...counts.pending > 0 ? [`${counts.pending} pending`] : [],
@@ -103143,8 +103169,9 @@ function formatPlanSummary(plan) {
   ];
   return `Plan \xB7 ${parts.join(" \xB7 ")}`;
 }
+var PLAN_LABEL_WIDTH = Math.max(...Object.values(PLAN_STATUS_LABEL).map((label) => label.length));
 function formatPlanRow(item) {
-  return `${PLAN_STATUS_GLYPH[item.status]} ${PLAN_STATUS_LABEL[item.status].padEnd(12)} ${item.title}`;
+  return `${PLAN_STATUS_GLYPH[item.status]} ${PLAN_STATUS_LABEL[item.status].padEnd(PLAN_LABEL_WIDTH)} ${item.title}`;
 }
 function formatPlanLegend() {
   return PLAN_STATUS_ORDER.map((status) => `${PLAN_STATUS_GLYPH[status]} ${PLAN_STATUS_LABEL[status]}`).join("   ");
@@ -103164,9 +103191,10 @@ function formatPlanMeta(plan, dir) {
   const blocked = plan.items.filter((item) => item.status === "blocked").map((item) => item.id);
   return [
     `Revision  ${plan.revision}`,
-    `Items     ${plan.items.length} \u2014 ${counts.completed} completed, ${counts.in_progress} in progress, ${counts.pending} pending, ${counts.blocked} blocked, ${counts.skipped} skipped`,
+    `Items     ${plan.items.length} \u2014 ${counts.completed} completed, ${counts.in_progress} in progress, ${counts.pending} pending, ${counts.blocked} blocked, ${counts.skipped} skipped, ${counts.proposed} awaiting approval`,
     `Active    ${active === undefined ? "(none \u2014 no item is in_progress)" : `${active.id} \u2014 ${active.title}`}`,
     ...blocked.length > 0 ? [`Blocked   ${blocked.join(", ")}`] : [],
+    ...counts.proposed > 0 ? [`Approval  ${counts.proposed} item(s) published for your approval \u2014 nothing is running; they start once you approve`] : [],
     "",
     "Storage   <session>/plan.json \u2014 a sibling of slate.json, so a completed",
     "          Flow closing its slate can no longer take the plan with it.",
@@ -103176,6 +103204,8 @@ function formatPlanMeta(plan, dir) {
 }
 function toneFor(status) {
   switch (status) {
+    case "proposed":
+      return "yellow";
     case "in_progress":
       return "cyan";
     case "blocked":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.144",
+  "version": "0.2.145",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {