@mrciphersmith/keryx 0.2.145 → 0.2.147

package/README.md

@@ -260,7 +260,12 @@ What is in it today:
   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.
+  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

@@ -51463,7 +51463,7 @@ import path47 from "path";
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.145",
+  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: {
@@ -103198,6 +103198,10 @@ function formatPlanMeta(plan, dir) {
     "",
     "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(`
 `);
@@ -103265,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.145",
+  "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