@kurrent/kcap 1.0.2 → 1.1.0

package/bin/kcap.js

@@ -11,10 +11,9 @@ const fs = require("fs");
 // module.exports below, so it would see partial exports).
 const { PLATFORM_PACKAGES, platformKey } = require("./resolve");
 
-// Resolves the npm dist-tag to install for `kcap update`, based on the
-// resolved channel reported by `kcap update --check`'s `install_tag` field.
-// Falls back to "latest" when the probe is missing, failed, or has no tag,
-// preserving today's default behavior.
+// The package spec `kcap update` installs, from `kcap update --check`'s `install_tag`: the channel's
+// dist-tag, or an exact version when the connected server caps the update. Falls back to "latest"
+// when the probe is missing, failed, or has no tag.
 function resolveInstallSpec(info) {
   const tag = info && typeof info.install_tag === "string" && info.install_tag
     ? info.install_tag
@@ -22,6 +21,12 @@ function resolveInstallSpec(info) {
   return `@kurrent/kcap@${tag}`;
 }
 
+// npm serves a packument from its cache for five minutes; within that window an install can
+// resolve against a listing that predates the platform package's version and silently skip it.
+function npmInstallArgs(spec) {
+  return ["install", "-g", spec, "--prefer-online"];
+}
+
 // Builds the arg list for the `kcap update --check` probe, forwarding only
 // the channel-switch flags (`--beta`/`--stable`) from the user's `kcap update`
 // invocation. Nothing else is forwarded — the probe already supplies `--check`
@@ -201,7 +206,7 @@ if (require.main === module) {
     binaryDir = path.dirname(require.resolve(`${packageName}/package.json`));
   } catch {
     console.error(`Platform package ${packageName} is not installed.`);
-    console.error(`Try: npm install -g @kurrent/kcap`);
+    console.error(`Try: npm ${npmInstallArgs(`@kurrent/kcap@${require("../package.json").version}`).join(" ")}`);
     process.exit(1);
   }
 
@@ -354,7 +359,7 @@ function runUpdate(binaryPath, updArgs) {
     }
   }
 
-  const res = spawnSync("npm", ["install", "-g", resolveInstallSpec(info)], {
+  const res = spawnSync("npm", npmInstallArgs(resolveInstallSpec(info)), {
     stdio: "inherit",
     windowsHide: true,
     ...npmOpts,
@@ -400,6 +405,7 @@ function runUpdate(binaryPath, updArgs) {
 
 module.exports = {
   resolveInstallSpec,
+  npmInstallArgs,
   probeArgs,
   trashDirFor,
   trashDirFromLauncher,

package/bin/refresh.js

@@ -77,6 +77,7 @@ const PLUGIN_MCP_SERVERS = {
   "kcap-flows":     "flows",
   "kcap-memory":    "memory",
   "kcap-workitems": "workitems",
+  "kcap-plans":     "plans",
   "kcap-analytics": "analytics",
 };
 

package/kcap/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "kcap",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
 }

package/kcap/.codex-mcp.json

@@ -23,6 +23,10 @@
     "kcap-workitems": {
       "command": "kcap",
       "args": ["mcp", "workitems"]
+    },
+    "kcap-plans": {
+      "command": "kcap",
+      "args": ["mcp", "plans"]
     }
   }
 }

package/kcap/.mcp.json

@@ -29,6 +29,12 @@
       "cwd": "${CLAUDE_PROJECT_DIR}",
       "description": "Attach the current session to a work item (issue, PR, or a brand-new item) on the Capacitor server, and list the work items a session is attached to."
     },
+    "kcap-plans": {
+      "command": "kcap",
+      "args": ["mcp", "plans"],
+      "cwd": "${CLAUDE_PROJECT_DIR}",
+      "description": "Plan ledger — declare the plan, spec or design document this session works from (declare_plan_document), declare its task list (set_plan_tasks), record each task's status change (update_plan_task) and read the plan back after compaction (get_plan)."
+    },
     "kcap-analytics": {
       "command": "kcap",
       "args": ["mcp", "analytics"],

package/kcap/README.md

@@ -81,7 +81,7 @@ Each hook pipes its JSON payload through the `kcap` CLI, which enriches it with
 - `hide` / `kcap-hide` — Hide the current session (owner-only visibility)
 - `review-flows` / `kcap-review-flows` — Run structured, iterative spec/code review loops; the reviewer vendor is chosen independently of the driver (pass a lowercase token like `claude`/`codex`/`cursor`)
 - `agent-flows` / `kcap-agent-flows` — Run structured multi-participant agent flows (catalog `definition_id` or an inline `definition_yaml`), each participant declaring its own vendor/model
-- `work-items` / `kcap-work-items` — Declare a work item's breakdown (parent and parts) and its blocks / blocked-by dependencies, so Home renders its topology
+- `work-items` / `kcap-work-items` — Declare a work item's breakdown (parent and parts) and its blocks / blocked-by dependencies, so Home renders its topology, and record the loose ends a session leaves unfinished
 - `guided-tour` / `kcap-guided-tour` — Onboarding tour: what Capacitor has recorded for your team, then per-use-case tutorials (evals, session recall, PR review, analytics)
 
 In Claude they're invoked as `/kcap:recap`, `/kcap:errors`, `/kcap:guided-tour`, etc.

package/kcap/skills/plans/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: plans
+description: >-
+  This skill should be used whenever you write or read a plan, spec or design
+  document, when you start executing a plan, and whenever a task list, todo
+  list or checklist comes up — yours or the user's. It says how to record the
+  plan and its tasks in Kurrent Capacitor through the `kcap mcp plans` MCP
+  tools, so progress shows in the session view and survives context
+  compaction.
+---
+
+# Plans — declaring the document and its tasks
+
+Capacitor keeps its own record of the plan a session executes: the document,
+the ordered task list, and each task's status. It is written only by you,
+through the `kcap-plans` MCP tools; nothing infers it. Three rules:
+
+1. **When you write or are handed a plan, spec or design document, declare it.**
+   Call `declare_plan_document` with its `kind` (`plan`, `spec` or `design`)
+   and `path`. The file is read locally, hashed, and keyed against the
+   repository root; declaring the same file again from a later session lands
+   on the same plan. When a plan implements a spec, or a spec refines a design,
+   pass the other file as `argues_from` so both attach to one plan.
+2. **When a plan has discrete steps, declare them and update each transition.**
+   Call `set_plan_tasks` with the whole ordered list (`title`, optional
+   `task_id`, `status`, `note`); re-send the whole list when the steps change,
+   carrying the `task_id`s you were given. Call `update_plan_task` every time a
+   task starts, finishes or is skipped, by `task_id` or 1-based `ordinal`, with
+   `status` `pending`, `in_progress`, `completed` or `skipped` and a `note`
+   when the reason matters. After compaction, `get_plan` returns the list.
+3. **Keep whatever ledger your own workflow asks for as well.** These tools
+   replace the harness's task list, not your notes or any file another
+   workflow tells you to maintain.
+
+## Tool reference
+
+| Tool | Required args | Purpose |
+|---|---|---|
+| `declare_plan_document` | `kind`, `path` (+ `argues_from`, `work_item_id`, `session_id`) | Declare the document; returns `plan_id`, `document_key`, `created`. |
+| `set_plan_tasks` | `tasks` (+ `plan_id`, `session_id`) | Replace the declared task list; returns tasks with ids and ordinals. |
+| `update_plan_task` | `status` and one of `task_id` / `ordinal` (+ `note`, `plan_id`) | Record one transition; the result names the plan. |
+| `get_plan` | — (+ `plan_id`, `session_id`) | Documents, tasks with status and source, progress. |
+
+Without `plan_id` every tool acts on the session's current plan — the one it
+most recently wrote to; a session on no plan gets one created by
+`set_plan_tasks` and an empty result from `get_plan`. If a tool cannot resolve
+the session, pass `session_id` explicitly.
+
+## Requirements
+
+Requires `kcap login`. The `kcap-plans` MCP server is registered for every
+supported harness by `kcap setup` and `kcap plugin install`.

package/kcap/skills/validate-plan/SKILL.md

@@ -25,9 +25,10 @@ kcap validate-plan <sessionId>
 
 ## What It Returns
 
-The command outputs three sections:
+The command outputs these sections:
 
-- **`## Plan`** — the full plan text
+- **`## Plan`** — the full plan text: the document declared through the `kcap-plans` MCP tools when there is one, otherwise the server's best discovered candidate, followed by the other candidates
+- **`## Tasks`** — the task list declared through the `kcap-plans` MCP tools, one line per task as `ordinal. [status] title (source)` with a progress line above it; absent when no tasks were declared
 - **`## What's Done`** — two sub-sections:
   - **Summary** — AI-generated summary of what was accomplished (from `WhatsDoneGenerated` events, if available)
   - **Details** — list of files created (`Write`) and modified (`Edit`) during the session
@@ -36,7 +37,7 @@ The command outputs three sections:
 ## What To Do With The Output
 
 1. Read the plan carefully and identify each distinct planned item
-2. Compare each item against the summary and file list under "What's Done"
+2. Compare each item against the summary and file list under "What's Done"; when a Tasks section is present, treat it as the checklist — a task still pending or in_progress is not done
 3. If all items are complete, confirm to the user that the plan is fully implemented
 4. If there are gaps, list the missing items and complete them now
 

package/kcap/skills/work-items/SKILL.md

@@ -5,11 +5,14 @@ description: >-
   work item — that it breaks into sub-tasks (a parent and its parts), or that
   one piece must land before another (a blocks / blocked-by dependency) — and
   you want that structure recorded so it shows up in Kurrent Capacitor's Home
-  "Blockers & dependencies" view and progress figures. Use the `kcap mcp
-  workitems` MCP tools to DECLARE the breakdown and relations. Do NOT use this
-  skill for ordinary "attach this session to issue X" correlation alone (a
-  single `declare_work_item` call, no structure) or when the work is a single
-  indivisible task with no parts and no dependencies.
+  "Blockers & dependencies" view and progress figures. Also use it at the end of
+  a session or a plan step that leaves work unfinished, to record each
+  unfinished piece as a loose end in the user's next-work ledger. Use the `kcap
+  mcp workitems` MCP tools to DECLARE the breakdown, the relations and the loose
+  ends. Do NOT declare STRUCTURE for ordinary "attach this session to issue X"
+  correlation alone (a single `declare_work_item` call, no structure), or for a
+  single indivisible task with no parts and no dependencies — a loose end is
+  worth declaring in either case.
 ---
 
 # Work items — declaring breakdown and dependencies
@@ -36,6 +39,8 @@ no breakdown.
 - Two items describe the same work (a title-only item you created and the
   issue/PR-keyed item the server minted) → merge yours into the keyed one.
 - The session was attached to the wrong item → detach it.
+- You are ending a session, or a plan step, with work you did not finish → declare
+  it as a loose end so it lands in the user's next-work ledger instead of evaporating.
 
 ## The flow
 
@@ -69,6 +74,16 @@ two — that records structure that isn't there. Merge instead:
   removal is durable for automated correlation; an attachment a user pinned cannot be
   removed by an agent.
 
+## Loose ends
+
+A loose end is one concrete piece of unfinished work — a missing test, a TODO you left in
+the code, a follow-up the user asked for. Declare each with `declare_loose_end` (`text`,
+one plain sentence). The server keys it on the session, the owner and the normalized text,
+so declaring the same end twice is a no-op (`created: false`). It refuses text shorter than
+12 or longer than 500 characters and "none"-style phrases — do not declare that there is
+nothing left. Loose ends are the user's; they are never converted into work items by this
+tool.
+
 ## Rules the server enforces
 
 - **Visibility, not repository.** Every item you name must be visible to you.
@@ -88,15 +103,16 @@ two — that records structure that isn't there. Merge instead:
 
 | Tool | Required args | Purpose |
 |---|---|---|
-| `declare_work_item` | exactly one of `issue_key` \| `pr_number` \| `work_item_id` \| `new_title` | Attach the session to a work item (or create one). `session_id` defaults to `KCAP_SESSION_ID`. |
+| `declare_work_item` | exactly one of `issue_key` \| `pr_number` \| `work_item_id` \| `new_title` | Attach the session to a work item (or create one). `session_id` defaults to the current session. |
 | `get_session_work_items` | — | List what the current session is attached to. |
+| `declare_loose_end` | `text` | Record one unfinished item in the user's next-work ledger. `session_id` defaults to the current session. |
 | `declare_work_breakdown` | `parent_id`, `part_ids` | Declare parent → parts. |
 | `retract_work_breakdown` | `parent_id`, `part_ids` | Detach parts from the parent. |
 | `declare_work_relation` | `from_id`, `to_id`, `relation_kind` (`blocks`\|`blocked_by`) | Declare a dependency. |
 | `retract_work_relation` | `from_id`, `to_id`, `relation_kind` | Retract a dependency. |
 | `get_work_item_topology` | `work_item_id` | Read parent, parts, and dependencies (visibility-scoped). |
 | `merge_work_item` | `work_item_id`, `into_work_item_id` | Merge a duplicate into the survivor (prefer the keyed item as survivor). |
-| `detach_work_item` | `work_item_id` | Detach the session from a wrongly attached item. `session_id` defaults to `KCAP_SESSION_ID`. |
+| `detach_work_item` | `work_item_id` | Detach the session from a wrongly attached item. `session_id` defaults to the current session. |
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -14,17 +14,17 @@
     "postinstall": "node bin/postinstall.js"
   },
   "optionalDependencies": {
-    "@kurrent/kcap-darwin-arm64": "1.0.2",
-    "@kurrent/kcap-linux-arm64": "1.0.2",
-    "@kurrent/kcap-linux-musl-arm64": "1.0.2",
-    "@kurrent/kcap-linux-musl-x64": "1.0.2",
-    "@kurrent/kcap-linux-x64": "1.0.2",
-    "@kurrent/kcap-win-x64": "1.0.2"
+    "@kurrent/kcap-darwin-arm64": "1.1.0",
+    "@kurrent/kcap-linux-arm64": "1.1.0",
+    "@kurrent/kcap-linux-musl-arm64": "1.1.0",
+    "@kurrent/kcap-linux-musl-x64": "1.1.0",
+    "@kurrent/kcap-linux-x64": "1.1.0",
+    "@kurrent/kcap-win-x64": "1.1.0"
   },
   "files": [
     "bin/",
     "kcap/"
   ],
-  "kcapReleaseCommit": "73089e77f0e3657d1fa858a1f9584e1044624060",
-  "kcapReleaseTag": "v1.0.2"
+  "kcapReleaseCommit": "0d5409540aeff85a0e674505bede436ded6c35ff",
+  "kcapReleaseTag": "v1.1.0"
 }