@mrciphersmith/keryx 0.2.144 → 0.2.147

package/README.md

@@ -255,9 +255,17 @@ 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. Orchestrators publish into this same view — `job-orchestrator`,
+  `flow-orchestrator`, `review-orchestrator`, `issue-analyzer`,
+  `feature-analyzer`, `autodoc-orchestrator`, `docpack-orchestrator`,
+  `feature-dev` and `review-pr-feedback` project their own steps here under the
+  `session-plan-bridge` rule, so a run driven by one of them is watchable while
+  it runs instead of only after it reports.
 - **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.147",
   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,18 +103191,25 @@ 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.",
+    "",
+    "Note      This is the agent's own plan for this session. The `/plan on|off`",
+    "          COMMAND is a different thing \u2014 the session's read-only mode, which",
+    "          this view neither shows nor changes.",
     ...dir === undefined ? [] : [`Session   ${dir}`]
   ].join(`
 `);
 }
 function toneFor(status) {
   switch (status) {
+    case "proposed":
+      return "yellow";
     case "in_progress":
       return "cyan";
     case "blocked":
@@ -103235,7 +103269,7 @@ function presentExecutionPlanInspector(openModalFn, otui, chrome, options) {
   };
   let unsubscribe;
   const handle = openModalFn(otui, chrome, {
-    title: "/plan",
+    title: "Session plan",
     tabs: [
       { id: "plan", label: "Plan" },
       { id: "meta", label: "Meta" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.144",
+  "version": "0.2.147",
   "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": {

package/src/gdskills/bundled/rules/core/session-plan-bridge.mdc

@@ -0,0 +1,96 @@
+---
+description: "Bridge between an orchestrator's own CLI-owned plan and the session execution plan the operator watches in the sidebar and the /plan modal: publish the orchestrator's steps as plan items under the SAME ids, mirror every status change at the moment the orchestrator updates its own state, and use `proposed` for a plan awaiting a human. Use when a skill orchestrates multi-step work (job-orchestrator, flow-orchestrator, review-orchestrator)."
+alwaysApply: false
+---
+
+# Session Plan Bridge
+
+## Purpose
+
+An orchestrator already has a plan. `job-orchestrator` has fifteen steps in a job
+package that `keryx job status` prints; `flow-orchestrator` has tasks `T1..Tn`
+with dependencies in the Flow package; `review-orchestrator` has a fifteen-step
+checklist. Until this rule existed, every one of those plans was invisible while
+it ran: the operator saw phases announced in prose, and had to ask.
+
+The session execution plan is the surface that fixes that. It is not a second
+plan — it is a PROJECTION of the orchestrator's own plan into the one place the
+operator is already looking (the sidebar's Plan section, and `/plan` for the
+whole list). The orchestrator's own state stays the only source of truth for
+what the work is.
+
+## The mechanism, in one paragraph
+
+`plan_set` publishes the whole plan (replace-all, optimistic `expectedRevision`);
+`plan_update` moves one item (`{expectedRevision, itemId, status}`); `plan_get`
+reads it back before a write when a conflict is possible. Statuses are
+`proposed | pending | in_progress | completed | blocked | skipped`, item ids are
+stable strings, and at most one item may be `in_progress` — the mechanism refuses
+a second one. `proposed` means "published for a human to approve": it is NOT work
+in progress, so it never makes the agent continue on its own, which is what makes
+"publish the plan, then stop and wait for the operator" a real stopping point.
+
+## Item ids are the orchestrator's own ids — never invented
+
+| Orchestrator | Item ids | Where they come from |
+|---|---|---|
+| `job-orchestrator` | the step ids `keryx job status <name> --json` reports — `analyze`, `context`, `prepare`, `tests-creator`, `implement`, `sanity-check`, `verify`, `review`, `security`, `fix`, `verify-post-fix`, `perf-check`, `report`, `pr`, `deploy` | `keryx job status <name>` (read it, never retype it) |
+| `flow-orchestrator` | the Flow's task ids `T1..Tn` | `keryx flow status <id>` / the Flow's `tasks.md` |
+| `review-orchestrator` | `step-0` … `step-14`, from its own numbered checklist | its Workflow section |
+
+An id that exists only in the session plan is drift by construction: the operator
+cannot reconcile it with the CLI, and a resumed run cannot match it. If a
+conditional step never runs, it is `skipped` — never absent.
+
+## Status mapping — the vocabularies disagree, this is the translation
+
+| Orchestrator's own status | Session plan status |
+|---|---|
+| `pending` (job) | `pending` |
+| `in-progress` (job, hyphenated) | `in_progress` |
+| `completed` | `completed` |
+| `skipped` | `skipped` |
+| `failed` (job / flow task) | `blocked` — it needs a human, and the failure reason goes in the item's title |
+| `blocked` (flow task) | `blocked` |
+
+## When to publish, and when to update
+
+1. **Publish once, as soon as the plan exists** — after `job-orchestrator`'s 1.1
+   plan build, after the Flow's task list exists in Phase 1, after
+   `review-orchestrator` fixes its scope and dispatch in Step 6. Not at the end.
+2. **`proposed` for a plan that is awaiting the operator.** Where an orchestrator
+   stops to ask — `job-orchestrator` 1.3's "Proceed? (yes / adjust …)" and
+   `flow-orchestrator` Phase 4's completion choice — the items are `proposed`
+   until the answer arrives, then become `pending`/`in_progress`. This is the
+   whole point of the status: the sidebar says `◇ awaiting approval` at exactly
+   the moment the orchestrator is waiting for the human.
+3. **Mirror every status change in the same breath as your own.** The call that
+   marks a step in `keryx job step …` / `keryx flow task done …` is the call that
+   updates the session plan. A batch of `plan_update`s after the work is done is
+   not progress reporting, it is a summary.
+4. **One `in_progress`** — the step being executed right now. Progress the
+   operator can see is a moving marker, not a growing list of ticks.
+5. **`blocked` when the run needs the operator** — an approval, a credential, a
+   failure that needs a decision.
+6. **`plan_get` before a write when a conflict is possible** (a resumed session, a
+   second shell on the same checkout) and re-apply against the revision you read.
+
+## What the bridge is NOT
+
+- Not a journal. Dispatch details, subagent names, token budgets and reasoning
+  belong in `journal.md` / the job's `man/` documents, not in plan items.
+- Not authoritative. If the session plan and `keryx job status` / `keryx flow
+  status` disagree, the CLI state wins and the session plan is corrected on the
+  next update — the projection follows the plan, never the other way round.
+- Not a completion signal. A plan whose items are all `completed` does not mean
+  the job is done: verification, review and the completion report are the
+  orchestrator's own gates.
+
+## Red Flags — stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "I'll publish the plan when the work is finished and I know all the statuses" | That is a report, not a plan. The sidebar exists so the operator can watch WHILE it runs — a plan published at the end has nothing to show. |
+| "The ids are mine to choose, as long as the titles match" | Then the session plan and `keryx job status` cannot be reconciled by a human or by a resumed run, and the projection has become a second plan. |
+| "`proposed` is the same as `pending`, I'll just use `pending`" | `pending` is actionable work, so the agent continues on its own and the "wait for approval" gate disappears. |
+| "Skipping the plan is fine when the job is short" | Then the operator's single progress surface is empty for exactly the runs where watching matters most. |

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/SKILL.md

@@ -32,7 +32,7 @@ Proceed directly with your assigned task.
 
 ## Purpose
 
-Performs deep cross-repository analysis to understand business logic, architecture, API contracts, and implementation requirements. Generates structured documentation for both human developers and AI agents.
+Performs deep cross-repository analysis to understand business logic, architecture, API contracts, and implementation requirements. Generates structured documentation for both human developers and AI agents. Plan bridge: publish each `Step N` this run will take with `plan_set`, and update it with `plan_update` as it finishes — see the `session-plan-bridge` rule.
 
 **Two Analysis Modes:**
 

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.md

@@ -28,7 +28,7 @@ End-to-end feature development workflow from idea to merge-ready PR.
 
 ## Arguments
 
-- `/feature-dev <description>` — start from a text description
+- `/feature-dev <description>` — start from a text description. Plan bridge: publish `phase-1`…`phase-8` with `plan_set`/`plan_update`; while a confirmation question is open the items are `proposed` — see the `session-plan-bridge` rule.
 - `/feature-dev #<issue>` — start from a GitHub issue
 - `/feature-dev --resume` — resume interrupted feature-dev (checks for existing worktree/branch)
 

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/SKILL.md

@@ -23,7 +23,7 @@ license: "MIT"
 
 ## Purpose
 
-Flow Orchestrator is the Task Manager-aware implementation orchestrator.
+Flow Orchestrator is the Task Manager-aware implementation orchestrator. Plan bridge: publish the tasks with `plan_set` under the ids `T1`…`Tn`, mirror each `keryx flow task done` with `plan_update`, and publish Phase 4's completion choice as `proposed` — see the `session-plan-bridge` rule.
 It wraps the existing gdskills pipeline with `keryx flow` state.
 
 Use this skill instead of `job-orchestrator` when the user wants a managed

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/SKILL.md

@@ -20,7 +20,7 @@ license: "MIT"
 
 ## Purpose
 
-Analyzes a GitHub issue and decomposes it into atomic implementation tasks that can be dispatched to `task-implementer` sub-agents. Designed to run autonomously as a sub-agent — no user interaction required.
+Analyzes a GitHub issue and decomposes it into atomic implementation tasks that can be dispatched to `task-implementer` sub-agents. Designed to run autonomously as a sub-agent — no user interaction required. Plan bridge: publish these four phases with `plan_set` under the ids `phase-1`…`phase-4` and move each with `plan_update` — see the `session-plan-bridge` rule.
 
 **Input:** GitHub issue URL (or repo + number) + codebase path(s)
 **Output:** JSON analysis object with one task entry per atomic task, each containing full context for implementation

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.md

@@ -32,7 +32,7 @@ Proceed directly with your assigned task.
 
 ## Purpose
 
-Dynamic orchestrator that builds execution plans based on user intent. Unlike a fixed pipeline, the orchestrator adapts its workflow to what the user actually needs — from "just analyze this issue" to "implement, review, and create a PR". It dispatches sub-agents (`issue-analyzer`, `context-collector`, `tests-creator`, `task-implementer`, `code-verifier`, `review-orchestrator`) and persists every step, document and retry through `keryx job`, which writes `.metaproject/jobs/<job-name>/`.
+Dynamic orchestrator that builds execution plans based on user intent. Unlike a fixed pipeline, the orchestrator adapts its workflow to what the user actually needs — from "just analyze this issue" to "implement, review, and create a PR". It dispatches sub-agents (`issue-analyzer`, `context-collector`, `tests-creator`, `task-implementer`, `code-verifier`, `review-orchestrator`) and persists every step, document and retry through `keryx job`, which writes `.metaproject/jobs/<job-name>/`. Plan bridge: publish these steps with `plan_set` under the ids `keryx job status` reports, mirror each `keryx job step` with `plan_update`, and mark them `proposed` while the approval above is open — see the `session-plan-bridge` rule.
 
 **The package is the state.** `keryx job` is the only writer of `state.json`; it validates every write against the registered contract `job-orchestrator-state` and refuses one that does not conform. Never hand-write `state.json`, and never hold a step's outcome only in this session — a step recorded nowhere is a step that did not happen as far as the next session is concerned.
 

package/src/gdskills/bundled/skills/planning/autodoc-orchestrator/SKILL.md

@@ -27,7 +27,7 @@ metadata:
 
 ## Purpose
 
-Thin orchestrator that drives a 5-phase autonomous documentation pipeline.
+Thin orchestrator that drives a 5-phase autonomous documentation pipeline. Plan bridge: publish `phase-0`…`phase-5` with `plan_set` and `plan_update`; `state.json` stays the source of truth — see the `session-plan-bridge` rule.
 Takes an existing codebase as input, dispatches specialized subagents to scan,
 analyze, and write documentation, and produces a complete documentation package
 with no human gates.

package/src/gdskills/bundled/skills/planning/docpack-orchestrator/SKILL.md

@@ -34,7 +34,7 @@ When a USER runs this orchestrator directly (not as a dispatched subagent), at
 the start ask "Collect execution statistics for this run? (yes/no)" per
 `.metaproject/rules/core/execution-metrics.md`. If yes, append the
 `## Execution Metrics` section at the end and save it under the docpack output
-dir. Never ask or emit it when dispatched as a subagent.
+dir. Never ask or emit it when dispatched as a subagent. Plan bridge: publish `phase-0`…`phase-5` with `plan_set`/`plan_update`, and hold them `proposed` while Phase 0's location question is open — see the `session-plan-bridge` rule.
 
 ## Iron Laws
 

package/src/gdskills/bundled/skills/review/review-orchestrator/SKILL.md

@@ -61,7 +61,7 @@ already hold (`--scope`, `--findings`, `--diff-lines`, `--fix-attempt`,
 `--verifier`, `--security`, `--forced-strategy-change`) and paste the `model`
 block it prints into that dispatch.
 
-Do NOT assign the tier by reading the table in `rules/core/model-selection.mdc`.
+Do NOT assign the tier by reading the table in `rules/core/model-selection.mdc`. Plan bridge: publish this checklist with `plan_set` under the ids `step-0`…`step-14` and move each item with `plan_update` as its step completes — see the `session-plan-bridge` rule.
 Working it out in your head is exactly the mechanical step that rule moves into
 code — and it is the step that was documented as running for a whole release
 while nothing called it.

package/src/gdskills/bundled/skills/review/review-pr-feedback/SKILL.md

@@ -56,7 +56,7 @@ a plan is the deliverable of analyze mode, not a preamble to one.
 
 ```
 review-pr-feedback Progress:
-- [ ] Step 1: Read job context (if CONTEXT_PATH provided)
+- [ ] Step 1: Read job context (if CONTEXT_PATH provided). Plan bridge: publish each `Step N` with `plan_set`, and move it with `plan_update` as the step completes — see the `session-plan-bridge` rule.
 - [ ] Step 2: Resolve the PR — owner, repo, number, head branch, base branch, head SHA
 - [ ] Step 3: Collect comments — `keryx review comments collect`, never by hand
 - [ ] Step 4: Group by author