@storybloq/storybloq 1.4.0 → 1.4.2

package/README.md

@@ -40,7 +40,7 @@ The real cost isn't wasted setup time. It's repeated mistakes, relitigated desig
 Every project gets a `.story/` directory of JSON and markdown files. Tickets, issues, roadmap phases, session handovers, and lessons learned all live there, tracked by git, readable by any AI.
 
 - **CLI:** `storybloq` - inspect and mutate `.story/` from the terminal.
-- **MCP server:** 49 tools Claude Code and Codex can call directly, no subprocess spawning.
+- **MCP server:** 53 tools Claude Code and Codex can call directly, no subprocess spawning.
 - **Skill:** `/story` in Claude Code or `$story` in Codex loads project state at the start of every session.
 - **Mac app:** native sidebar that watches `.story/` and updates live while your AI client works (separate product, free on the App Store).
 
@@ -82,6 +82,8 @@ cd your-project
 storybloq init --name "your-project"
 ```
 
+For multi-repo projects, see [Federation](#federation) below.
+
 That scaffolds:
 
 ```
@@ -117,6 +119,36 @@ Outside Claude Code, the same state is one `storybloq` invocation away.
   <img src="https://raw.githubusercontent.com/Storybloq/storybloq/main/assets/autonomous.png" alt="Autonomous mode running a ticket through plan, implement, test, review" />
 </p>
 
+## Federation
+
+Federation coordinates AI agent work across multiple repos. One project becomes the orchestrator. It declares which repos (nodes) are part of the system, how they depend on each other, and how they communicate at runtime. Each node keeps its own `.story/` with its own tickets, issues, and handovers. The orchestrator reads across all of them.
+
+```bash
+# Create an orchestrator
+storybloq init --type orchestrator --name "my-platform"
+
+# Register nodes
+storybloq node add api --path ../api --stack typescript --role "REST backend"
+storybloq node add web --path ../web --stack nextjs --depends-on api
+storybloq node add sdk --path ../sdk --stack typescript
+```
+
+Three relationship types connect nodes:
+
+- **`dependsOn`** on node config: build-order edges. The web app depends on the API.
+- **`links`** on node config: runtime integration. The web app calls the API over HTTP.
+- **`crossNodeBlockedBy`** on tickets: a ticket in one repo is blocked until a ticket in another repo is complete. Example: `"crossNodeBlockedBy": ["api:T-012"]`.
+
+From the orchestrator directory:
+
+```bash
+storybloq status              # aggregated view across all nodes
+storybloq recommend           # federation-aware suggestions (bottlenecks, stale nodes, blockers)
+storybloq ticket list --node api   # list tickets in the api node without cd-ing
+```
+
+The recommendation engine generates federation-specific suggestions: nodes blocking downstream work, bottleneck nodes depended on by many others, nodes with no handover in two weeks. Tickets with `crossNodeBlockedBy` refs never surface in recommendations until the blocking ticket is complete.
+
 ## CLI reference
 
 All commands accept `--format json|md` (default `md`). Pipe JSON through `jq` for scripting, read the markdown variant directly.
@@ -125,7 +157,7 @@ All commands accept `--format json|md` (default `md`). Pipe JSON through `jq` fo
 
 | Command | Description |
 |---------|-------------|
-| `storybloq init [--name] [--force]` | Scaffold `.story/` in the current directory |
+| `storybloq init [--name] [--type orchestrator] [--force]` | Scaffold `.story/` (add `--type orchestrator` for multi-repo) |
 | `storybloq status` | Project summary with phase statuses, counts, and risks |
 | `storybloq validate` | Reference integrity + schema checks |
 | `storybloq setup --client claude\|codex\|all [--skip-hooks]` | Install Storybloq skills, register MCP, and configure client hooks |
@@ -152,8 +184,8 @@ All commands accept `--format json|md` (default `md`). Pipe JSON through `jq` fo
 | `storybloq ticket get <id>` | Full ticket detail |
 | `storybloq ticket next` | Highest-priority unblocked ticket |
 | `storybloq ticket blocked` | All currently blocked tickets |
-| `storybloq ticket create --title --type --phase [--description] [--blocked-by] [--parent-ticket]` | Create |
-| `storybloq ticket update <id> [--status] [--title] [--phase] [--order] ...` | Update |
+| `storybloq ticket create --title --type --phase [--description] [--blocked-by] [--parent-ticket] [--node <name>]` | Create (use `--node` from orchestrator) |
+| `storybloq ticket update <id> [--status] [--title] [--phase] [--cross-node-blocked-by] [--node <name>] ...` | Update |
 | `storybloq ticket meta get\|set\|unset <id> [path] [value]` | Manage custom passthrough metadata |
 | `storybloq ticket delete <id> [--force]` | Delete |
 
@@ -186,6 +218,17 @@ All commands accept `--format json|md` (default `md`). Pipe JSON through `jq` fo
 | `storybloq snapshot` · `storybloq recap` | Capture state and diff against the last snapshot |
 | `storybloq export [--phase <id>] [--all] [--format json\|md]` | Self-contained project document |
 
+### Federation (orchestrator projects)
+
+| Command | Description |
+|---------|-------------|
+| `storybloq init --type orchestrator` | Scaffold an orchestrator `.story/` with a nodes map |
+| `storybloq node add <name> --path <dir> [--stack] [--role] [--depends-on] [--link]` | Register a node repo |
+| `storybloq node remove <name> [--force \| --prune]` | Unregister a node (checks for dependents first) |
+| `storybloq node update <name> [--stack] [--role] [--depends-on] [--health]` | Update node metadata |
+| `storybloq node list` | Table of all configured nodes |
+| `storybloq config set-federation --allow-node-writes` | Allow orchestrator to write into node repos |
+
 ## MCP server reference
 
 Register with Claude Code or Codex (done automatically by setup):
@@ -197,7 +240,7 @@ codex mcp add storybloq --env STORYBLOQ_CLIENT=codex -- storybloq --mcp
 
 The server imports the same TypeScript modules as the CLI directly, so there's no subprocess overhead. It auto-discovers the project root by walking up from the working directory to the nearest `.story/` parent.
 
-**49 tools** grouped by responsibility:
+**53 tools** grouped by responsibility:
 
 ### Read (no side effects)
 
@@ -215,6 +258,12 @@ The server imports the same TypeScript modules as the CLI directly, so there's n
 
 `storybloq_session_report` · `storybloq_register_subprocess` · `storybloq_unregister_subprocess` surface session health to the Mac app.
 
+### Federation (orchestrator projects)
+
+`storybloq_node_init` bootstraps `.story/` in a node repo from the orchestrator context.
+
+`storybloq_node_add` · `storybloq_node_list` · `storybloq_node_update` manage the orchestrator's node registry.
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/Storybloq/storybloq/main/assets/handover.png" alt="Handover timeline with AI-summarized date groups" />
 </p>
@@ -282,7 +331,8 @@ Full type definitions ship with the package (`exports.types`).
   "createdDate": "2026-04-12",
   "completedDate": null,
   "blockedBy": [],
-  "parentTicket": null
+  "parentTicket": null,
+  "crossNodeBlockedBy": []
 }
 ```
 

package/dist/cli.js

@@ -13996,10 +13996,11 @@ var init_types3 = __esm({
        * Updates the internal snapshot so subsequent reads via `this.state` are consistent.
        */
       writeState(updates, opts) {
+        const prevState = this._state.state;
         const merged = { ...this._state, ...updates };
         const written = writeSessionSync(this.dir, merged);
         this._state = written;
-        if (opts?.refreshStatus) {
+        if (opts?.refreshStatus || written.state !== prevState) {
           try {
             refreshStatusForSession(this.root, this.dir, written, "guide");
           } catch {
@@ -17570,7 +17571,7 @@ function getInstalledVersion() {
   }
 }
 function getRunningVersion() {
-  return "1.4.0";
+  return "1.4.2";
 }
 var init_version_check = __esm({
   "src/autonomous/version-check.ts"() {
@@ -18612,7 +18613,12 @@ async function runPipelineStage(root, dir, state, report, recipe) {
   }
   const ctx = new StageContext(root, dir, state, recipe);
   const advance = await stage.report(ctx, report);
-  return processAdvance(ctx, stage, advance);
+  const result = await processAdvance(ctx, stage, advance);
+  try {
+    refreshStatusForSession(root, dir, ctx.state, "guide");
+  } catch {
+  }
+  return result;
 }
 async function handleReport(root, args) {
   if (!args.sessionId) return guideError(new Error("sessionId is required for report action"));
@@ -19857,7 +19863,7 @@ function registerAllTools(server, pinnedRoot) {
     const result = await runMcpReadTool(pinnedRoot, handleStatus);
     try {
       const { readUpdateCacheSync: readUpdateCacheSync2, refreshUpdateCacheInBackground: refreshUpdateCacheInBackground2 } = await Promise.resolve().then(() => (init_update_check(), update_check_exports));
-      const running = "1.4.0";
+      const running = "1.4.2";
       const info = readUpdateCacheSync2(running);
       refreshUpdateCacheInBackground2();
       if (info?.updateAvailable && result.content[0]?.type === "text") {
@@ -21500,7 +21506,7 @@ var init_mcp = __esm({
     ENV_VAR2 = "STORYBLOQ_PROJECT_ROOT";
     LEGACY_ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
     CONFIG_PATH2 = ".story/config.json";
-    version = "1.4.0";
+    version = "1.4.2";
     main().catch((err) => {
       process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}
 `);
@@ -24422,7 +24428,8 @@ var init_setup_skill = __esm({
       "storybloq_recap",
       "storybloq_recommend",
       "storybloq_export",
-      "storybloq_session_report"
+      "storybloq_session_report",
+      "storybloq_node_list"
     ];
   }
 });
@@ -28600,7 +28607,7 @@ async function runCli() {
     registerMigrateCommand: registerMigrateCommand2,
     registerNodeCommand: registerNodeCommand2
   } = await Promise.resolve().then(() => (init_register(), register_exports));
-  const version2 = "1.4.0";
+  const version2 = "1.4.2";
   const { preCommandHousekeeping: preCommandHousekeeping2 } = await Promise.resolve().then(() => (init_housekeeping(), housekeeping_exports));
   await preCommandHousekeeping2(version2);
   class HandledError extends Error {

package/dist/mcp.js

@@ -13295,10 +13295,11 @@ var StageContext = class {
    * Updates the internal snapshot so subsequent reads via `this.state` are consistent.
    */
   writeState(updates, opts) {
+    const prevState = this._state.state;
     const merged = { ...this._state, ...updates };
     const written = writeSessionSync(this.dir, merged);
     this._state = written;
-    if (opts?.refreshStatus) {
+    if (opts?.refreshStatus || written.state !== prevState) {
       try {
         refreshStatusForSession(this.root, this.dir, written, "guide");
       } catch {
@@ -16742,7 +16743,7 @@ function getInstalledVersion() {
   }
 }
 function getRunningVersion() {
-  return "1.4.0";
+  return "1.4.2";
 }
 
 // src/autonomous/guide.ts
@@ -17802,7 +17803,12 @@ async function runPipelineStage(root, dir, state, report, recipe) {
   }
   const ctx = new StageContext(root, dir, state, recipe);
   const advance = await stage.report(ctx, report);
-  return processAdvance(ctx, stage, advance);
+  const result = await processAdvance(ctx, stage, advance);
+  try {
+    refreshStatusForSession(root, dir, ctx.state, "guide");
+  } catch {
+  }
+  return result;
 }
 async function handleReport(root, args) {
   if (!args.sessionId) return guideError(new Error("sessionId is required for report action"));
@@ -18747,7 +18753,7 @@ function registerAllTools(server, pinnedRoot) {
     const result = await runMcpReadTool(pinnedRoot, handleStatus);
     try {
       const { readUpdateCacheSync: readUpdateCacheSync2, refreshUpdateCacheInBackground: refreshUpdateCacheInBackground2 } = await Promise.resolve().then(() => (init_update_check(), update_check_exports));
-      const running = "1.4.0";
+      const running = "1.4.2";
       const info = readUpdateCacheSync2(running);
       refreshUpdateCacheInBackground2();
       if (info?.updateAvailable && result.content[0]?.type === "text") {
@@ -20106,7 +20112,7 @@ async function trimFailedDirectory(inboxPath) {
 var ENV_VAR2 = "STORYBLOQ_PROJECT_ROOT";
 var LEGACY_ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
 var CONFIG_PATH2 = ".story/config.json";
-var version = "1.4.0";
+var version = "1.4.2";
 function tryDiscoverRoot() {
   const envRoot = process.env[ENV_VAR2] ?? process.env[LEGACY_ENV_VAR2];
   const envName = process.env[ENV_VAR2] ? ENV_VAR2 : LEGACY_ENV_VAR2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storybloq/storybloq",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "license": "PolyForm-Noncommercial-1.0.0",
   "description": "Project memory for Claude Code. Storybloq stores tickets, issues, handovers, and lessons in a .story/ folder inside your repo so every session starts where the last one left off. Pairs with the Storybloq Mac app on the App Store.",
   "homepage": "https://storybloq.com",