llm-orchestrator 1.2.5 → 1.2.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "llm-orchestrator",
   "description": "Write /task once — it plans the work, shards it across parallel subagents, gates every phase and verifies before claiming done. Claude Code, Codex, OpenCode, Kilo.",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "author": {
     "name": "Bogdan-Gabriel Torcescu",
     "url": "https://www.linkedin.com/in/bogdantorcescu/"

package/README.md

@@ -375,13 +375,14 @@ more instructions:
   reports `role_dispatches`, `generic_dispatches` and `runs_without_roles`. The Claude Code plugin
   ships the roles as agents (`llm-orchestrator:<role>`), so they are available without a project
   install.
-- A run opened with two or more shards whose main thread keeps doing the work — two work calls per planned shard, no
+- A run opened with two or more shards whose main thread keeps doing the work — two work calls per planned shard (one per shard in incident, investigation and research flows, whose reads *are* the shards, with one firmer follow-up if the first reminder is ignored), no
   subagent started — gets one more sentence: dispatch the independent shards (searching for the
   Agent tool if it is deferred), or declare the chain inline with
   `run start --type <T> --shards <n> --inline "stateful:<what>"`. Work is inline only while it holds
   live state a subagent cannot inherit (a browser mid-flow, an interactive shell); independent reads
-  are never inline. The audit adds `inline_declared` and `below_fan_out` (incident, investigation or
-  research runs opened with fewer than two shards).
+  are never inline. The audit adds `inline_declared`, `inline_after_nudge` (an `--inline` declared only
+  after a dispatch reminder — a retroactive justification) and `below_fan_out` (incident, investigation
+  or research runs opened with fewer than two shards).
 - Once the entrypoint is loaded, read-only discovery (reading files, `grep`, `git status`, tool
   version checks) before `run start` is SKILL.md steps 2–3, not a deviation. An edit, a write, a
   dispatch or any other shell command before the run is.

package/lib/flow-gate.mjs

@@ -35,7 +35,7 @@ export const NUDGE = nudgeFor();
  * none went to a subagent, and the main thread keeps doing the work itself.
  */
 export function dispatchNudgeFor(cli = 'llm-orchestrator', planned = 2, taskType = null) {
-  const roles = (FLOW_ROLES[taskType] ?? []).slice(0, 4);
+  const roles = (EVIDENCE_TYPES.has(taskType) ? EVIDENCE_ROLES[taskType] : FLOW_ROLES[taskType] ?? []).slice(0, 4);
   const to = roles.length > 0
     ? ` to this flow's roles (${roles.join(', ')}), not a general-purpose agent`
     : ' to the orchestrator\'s roles, not a general-purpose agent';
@@ -67,6 +67,18 @@ function pathHash(path) {
 // Main-thread work calls tolerated per planned shard before the dispatch nudge: a
 // two-shard task that is finished inline in three calls never reached a fixed six.
 export const DISPATCH_CALLS_PER_SHARD = 2;
+// Evidence flows: the reads are the shards, so waiting two calls per shard lets the
+// main thread read everything before the reminder arrives. One call per shard there,
+// and one firmer follow-up if the first reminder is ignored.
+export const EVIDENCE_CALLS_PER_SHARD = 1;
+const MAX_DISPATCH_NUDGES = 2;
+
+/** The follow-up for an evidence flow whose first dispatch reminder was ignored. */
+export function dispatchFollowupFor(cli = 'llm-orchestrator', planned = 2, taskType = null) {
+  const roles = (EVIDENCE_ROLES[taskType] ?? []).slice(0, 3);
+  const who = roles.length > 0 ? ` (${roles.join(', ')})` : '';
+  return `The dispatch reminder was not acted on, and the main thread is still gathering evidence itself. In an evidence flow those reads are the ${planned} planned shards — independent, W-tier, meant for subagents${who}. Dispatch the remaining sources now, or declare why they must stay inline (\`${cli} run start --type <TYPE> --inline "stateful:<what state>"\`).`;
+}
 
 // Evidence-gathering flows: their first phase fans out across independent sources.
 const EVIDENCE_TYPES = new Set(['INCIDENT', 'INVESTIGATION', 'RESEARCH']);
@@ -85,8 +97,12 @@ const ROLE_IDS = new Set([
   ...(readRegistry('registries/agent-roles.json')?.roles ?? []).map((role) => role.id),
   ...(readRegistry('registries/preferred-tools.json')?.tools ?? []).filter((tool) => tool.kind === 'agent_role').map((tool) => tool.id),
 ]);
-const FLOW_ROLES = Object.fromEntries(Object.entries(readRegistry('registries/routing-matrix.json')?.task_flows ?? {})
+const TASK_FLOWS = readRegistry('registries/routing-matrix.json')?.task_flows ?? {};
+const FLOW_ROLES = Object.fromEntries(Object.entries(TASK_FLOWS)
   .map(([type, flow]) => [type, [...new Set(flow.phases.flatMap((phase) => phase.roles ?? []))].filter((role) => role !== 'orchestrator')]));
+// The evidence phase of each flow: who gathers, as opposed to who fixes later.
+const EVIDENCE_ROLES = Object.fromEntries(Object.entries(TASK_FLOWS)
+  .map(([type, flow]) => [type, (flow.phases[0]?.roles ?? []).filter((role) => role !== 'orchestrator')]));
 
 /** 'role' for an orchestrator role (plugin-namespaced ids too), 'generic' otherwise, null when unknown. */
 export function roleKind(agentType) {
@@ -267,6 +283,7 @@ function historyLine(session, fields, now) {
     inline_reason: fields.inline_reason ?? null,
     dispatch_nudged: Boolean(fields.dispatch_nudged),
     overreach: Boolean(fields.overreach_nudged),
+    inline_after_nudge: Boolean(fields.inline_after_nudge),
     role_dispatches: fields.role_dispatches ?? 0,
     generic_dispatches: fields.generic_dispatches ?? 0,
     closed_by: fields.closed_by,
@@ -369,6 +386,8 @@ export function decide(previous, event, now) {
       subagent_ids: [],
       role_dispatches: 0,
       generic_dispatches: 0,
+      dispatch_nudges: 0,
+      inline_after_nudge: Boolean(event.run.inline && session.run?.dispatch_nudged),
     };
     // The work already done is accounted for on the run itself now.
     session.worked_without_run = false;
@@ -396,10 +415,17 @@ export function decide(previous, event, now) {
       }
       return { session, output, history };
     }
+    const evidence = EVIDENCE_TYPES.has(current.task_type);
+    const step = (evidence ? EVIDENCE_CALLS_PER_SHARD : DISPATCH_CALLS_PER_SHARD) * (current.planned_shards ?? 0);
+    const nudges = current.dispatch_nudges ?? (current.dispatch_nudged ? 1 : 0);
+    const allowed = evidence ? MAX_DISPATCH_NUDGES : 1;
     if ((current.planned_shards ?? 0) >= 2 && current.subagents_started === 0 && !current.inline_reason
-      && !current.dispatch_nudged && current.main_work_calls >= DISPATCH_CALLS_PER_SHARD * current.planned_shards) {
+      && nudges < allowed && current.main_work_calls >= step * (nudges + 1)) {
       current.dispatch_nudged = true;
-      output = { additionalContext: dispatchNudgeFor(undefined, current.planned_shards, current.task_type), kind: 'dispatch', planned: current.planned_shards, taskType: current.task_type };
+      current.dispatch_nudges = nudges + 1;
+      output = nudges === 0
+        ? { additionalContext: dispatchNudgeFor(undefined, current.planned_shards, current.task_type), kind: 'dispatch', planned: current.planned_shards, taskType: current.task_type }
+        : { additionalContext: dispatchFollowupFor(undefined, current.planned_shards, current.task_type), kind: 'dispatch_followup', planned: current.planned_shards, taskType: current.task_type };
     }
     return { session, output, history };
   }
@@ -538,6 +564,7 @@ export async function handleHook({ payload, project, now = Date.now(), cli = 'll
   if (!result.output) return null;
   // decide() speaks in the default CLI spelling; the hook swaps in the runnable path.
   const text = result.output.kind === 'dispatch' ? dispatchNudgeFor(cli, result.output.planned, result.output.taskType)
+    : result.output.kind === 'dispatch_followup' ? dispatchFollowupFor(cli, result.output.planned, result.output.taskType)
     : result.output.kind === 'overreach' ? overreachNudgeFor(cli, result.output.files)
       : nudgeFor(cli);
   return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text } };
@@ -584,6 +611,7 @@ export function adherenceSummary(lines) {
     planned_but_not_dispatched: lines.filter((line) => (line.planned_shards ?? 0) > 1 && line.subagents_started === 0).length,
     runs_without_plan: lines.filter((line) => !line.skipped_flow && !line.trivial && line.planned_shards === null).length,
     inline_declared: lines.filter((line) => Boolean(line.inline_reason)).length,
+    inline_after_nudge: lines.filter((line) => line.inline_after_nudge).length,
     trivial_overreach: lines.filter((line) => line.trivial && line.overreach).length,
     role_dispatches: lines.reduce((sum, line) => sum + (line.role_dispatches ?? 0), 0),
     generic_dispatches: lines.reduce((sum, line) => sum + (line.generic_dispatches ?? 0), 0),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-orchestrator",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "description": "Write /task once — it plans the work, shards it across parallel subagents, gates every phase and verifies before claiming done. Claude Code, Codex, OpenCode, Kilo.",
   "type": "module",
   "engines": {

package/schemas/flow-ledger.schema.json

@@ -8,7 +8,7 @@
     "run": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["task_id", "task_type", "trivial", "reason", "opened_at", "planned_shards", "subagents_started", "started_outside_flow", "inline_reason", "main_work_calls", "dispatch_nudged", "edited_files", "touched_tests", "overreach_nudged", "subagent_ids", "role_dispatches", "generic_dispatches"],
+      "required": ["task_id", "task_type", "trivial", "reason", "opened_at", "planned_shards", "subagents_started", "started_outside_flow", "inline_reason", "main_work_calls", "dispatch_nudged", "edited_files", "touched_tests", "overreach_nudged", "subagent_ids", "role_dispatches", "generic_dispatches", "dispatch_nudges", "inline_after_nudge"],
       "properties": {
         "task_id": { "type": "string", "minLength": 1 },
         "task_type": { "type": ["string", "null"], "enum": ["INCIDENT", "FEATURE", "BUG_FIX", "REFACTOR", "INVESTIGATION", "DEPLOY", "CONFIG", "REVIEW", "RESEARCH", null] },
@@ -26,7 +26,9 @@
         "overreach_nudged": { "type": "boolean" },
         "subagent_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{12}$" }, "description": "Short hashes of the distinct subagents started under this run." },
         "role_dispatches": { "type": "integer", "minimum": 0, "description": "Subagents started as one of the orchestrator's roles." },
-        "generic_dispatches": { "type": "integer", "minimum": 0, "description": "Subagents started as a generic agent type (general-purpose, Explore, …)." }
+        "generic_dispatches": { "type": "integer", "minimum": 0, "description": "Subagents started as a generic agent type (general-purpose, Explore, …)." },
+        "dispatch_nudges": { "type": "integer", "minimum": 0, "maximum": 2, "description": "Dispatch reminders sent: one, or two for evidence flows whose first was ignored." },
+        "inline_after_nudge": { "type": "boolean", "description": "This run replaced one that had already received a dispatch reminder, and declared --inline: a retroactive justification." }
       }
     },
     "session": {
@@ -48,7 +50,7 @@
     "historyLine": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["session", "task_id", "task_type", "trivial", "reason", "opened_at", "closed_at", "duration_s", "planned_shards", "subagents_started", "started_outside_flow", "skipped_flow", "inline_reason", "dispatch_nudged", "overreach", "role_dispatches", "generic_dispatches", "closed_by"],
+      "required": ["session", "task_id", "task_type", "trivial", "reason", "opened_at", "closed_at", "duration_s", "planned_shards", "subagents_started", "started_outside_flow", "skipped_flow", "inline_reason", "dispatch_nudged", "overreach", "inline_after_nudge", "role_dispatches", "generic_dispatches", "closed_by"],
       "properties": {
         "session": { "type": "string", "minLength": 1 },
         "task_id": { "type": ["string", "null"] },
@@ -65,6 +67,7 @@
         "inline_reason": { "type": ["string", "null"] },
         "dispatch_nudged": { "type": "boolean" },
         "overreach": { "type": "boolean", "description": "A trivial run that edited two or more files or its tests." },
+        "inline_after_nudge": { "type": "boolean" },
         "role_dispatches": { "type": "integer", "minimum": 0 },
         "generic_dispatches": { "type": "integer", "minimum": 0 },
         "closed_by": { "enum": ["run_close", "next_prompt", "succession", "turn_end", "session_end"] }