immune-brain 5.2.0 → 5.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Immune-Brain agent skill system",
   "publishConfig": {
     "access": "public",

package/plugins/immune-brain/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Immune-Brain Claude Code Host: native Enrollment, QA, Review, and Kernel settlement.",
   "author": {
     "name": "Immune-Brain Team"

package/plugins/immune-brain/dist/BASELINE.md

@@ -55,7 +55,11 @@ framing does not load that execution guidance.
 
 Ordinary host input stays host-native and does not run natural-language Managed
 routing. A new Managed workflow starts only from explicit `imm-brainstorm`,
-`imm-planner`, or `imm-run` Skill entry.
+`imm-planner`, or `imm-run` Skill entry. For `imm-planner` and `imm-brainstorm`
+the user's request for that planning or clarification, by slash command or in
+natural language, is such an entry; a request that asks for neither stays
+host-native. `imm-run` starts only from a literal-user entry. A model-entered
+Planner outside an enrolled task ends the session's run entry.
 
 1. **Continue an existing Managed owner explicitly**: an active Assurance
    projection, TaskIntent, TaskRecord, reviewer `follow_up`, or other nonterminal

package/plugins/immune-brain/dist/claude/mcp-server.mjs

@@ -39,7 +39,7 @@ function probeHost(env = process.env, platform = process.platform, hostVersion)
 }
 
 // plugins/immune-brain/runtime/plugin_version.ts
-var PLUGIN_VERSION = "5.2.0";
+var PLUGIN_VERSION = "5.3.0";
 
 // plugins/immune-brain/runtime/claude/interaction.ts
 import { createHash, randomUUID } from "node:crypto";
@@ -95,14 +95,13 @@ function recognizePhaseEntry(text, readAlias) {
     return null;
   return ALIAS_TARGETS[[...targets][0]] ?? null;
 }
-var NO_PHASE_ENTRY = { prompt_seq: 0, run_live: false, run_prompt_seq: 0, plan_prompt_seq: 0 };
+var NO_PHASE_ENTRY = { run_live: false };
 function applyPrompt(state, entry) {
-  const prompt_seq = state.prompt_seq + 1;
   if (entry === "run")
-    return { ...state, prompt_seq, run_live: true, run_prompt_seq: prompt_seq };
+    return { run_live: true };
   if (entry === "plan")
-    return { prompt_seq, run_live: false, run_prompt_seq: 0, plan_prompt_seq: prompt_seq };
-  return { ...state, prompt_seq };
+    return { run_live: false };
+  return state;
 }
 function phaseEntryLogLine(entry) {
   return `${JSON.stringify({ v: 1, entry })}
@@ -138,17 +137,11 @@ function admitPhaseOperation(operation, state, context) {
       return { ok: true };
     return refuse(RUN_ENTRY_REQUIRED, `${operation.name} needs a literal-user imm-run entry in this session`);
   }
-  const latest = state !== null && state.prompt_seq > 0 ? state.prompt_seq : -1;
-  if (operation.skill === "imm-run") {
-    if (state?.run_live && state.run_prompt_seq === latest)
-      return { ok: true };
-    return refuse(PHASE_ENTRY_REQUIRED, "imm-run is entered by the user, not by a model Skill call");
-  }
-  if (state && state.plan_prompt_seq === latest)
+  if (operation.skill !== "imm-run")
     return { ok: true };
-  if (operation.skill === "imm-planner" && state?.run_live && context.activeClaim)
+  if (state?.run_live)
     return { ok: true };
-  return refuse(PHASE_ENTRY_REQUIRED, `${operation.skill} is entered by the user, not by a model Skill call`);
+  return refuse(PHASE_ENTRY_REQUIRED, "imm-run is entered by the user, not by a model Skill call");
 }
 function phaseRefusalMessage(refusal) {
   return `${refusal.reason_code}: ${refusal.detail}; recovery: ${refusal.recovery_action}`;
@@ -9229,20 +9222,25 @@ function dropPrivate(path) {
       rmSync5(path, { force: true });
   } catch {}
 }
+function appendPhaseEntry(sessionId, entry, root, locations) {
+  const path = entryLogPath(sessionId, root);
+  let recorded = false;
+  try {
+    recorded = (locations.append ?? appendPrivate)(path, cacheDir(root), phaseEntryLogLine(entry));
+  } catch {}
+  if (!recorded)
+    dropPrivate(path);
+  return recorded;
+}
 function recordPhaseEntryPrompt(payload, locations = {}) {
   if (payload.hook_event_name !== "UserPromptSubmit")
     return false;
   const sessionId = sessionIdOf(payload);
   if (!sessionId)
     return false;
-  const root = locations.root ?? tmpdir2();
   const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
   const entry = recognizePhaseEntry(prompt, claudeAliasReader(cwdOf(payload), locations.home ?? homedir()));
-  const path = entryLogPath(sessionId, root);
-  const recorded = (locations.append ?? appendPrivate)(path, cacheDir(root), phaseEntryLogLine(entry));
-  if (!recorded)
-    dropPrivate(path);
-  return recorded;
+  return appendPhaseEntry(sessionId, entry, locations.root ?? tmpdir2(), locations);
 }
 function gatedOperation(payload) {
   const toolName = String(payload.tool_name ?? "");
@@ -9261,15 +9259,21 @@ function phaseEntryGateHookOutput(payload, locations = {}) {
   if (!operation)
     return null;
   const root = locations.root ?? tmpdir2();
+  if (operation.kind === "skill" && operation.skill !== "imm-run") {
+    let activeClaim = false;
+    try {
+      activeClaim = readActiveClaimTaskId(cwdOf(payload)) !== null;
+    } catch {}
+    const sessionId = sessionIdOf(payload);
+    if (!activeClaim && sessionId)
+      appendPhaseEntry(sessionId, "plan", root, locations);
+    return null;
+  }
   let state = null;
   try {
     state = readPhaseEntryState(sessionIdOf(payload), root, locations.read);
   } catch {}
-  let activeClaim = false;
-  try {
-    activeClaim = readActiveClaimTaskId(cwdOf(payload)) !== null;
-  } catch {}
-  const admission = admitPhaseOperation(operation, state, { activeClaim });
+  const admission = admitPhaseOperation(operation, state);
   if (!admission.ok)
     return denyPreToolUse(phaseRefusalMessage(admission));
   if (operation.kind === "skill")

package/plugins/immune-brain/dist/imm-brainstorm.md

@@ -1,6 +1,6 @@
 ---
 name: imm-brainstorm
-description: Use when the user explicitly requests Immune-Brain requirement clarification.
+description: Use when the user asks to clarify or explore requirements before Immune-Brain planning.
 ---
 
 # Immune-Brain: Brainstormer

package/plugins/immune-brain/dist/imm-planner.md

@@ -1,6 +1,6 @@
 ---
 name: imm-planner
-description: Use when the user explicitly requests Immune-Brain Spec and TaskIntent planning.
+description: Use when the user asks for an Immune-Brain Spec, Plan, or TaskIntent for a repository change.
 ---
 
 # Immune-Brain: Planner
@@ -9,10 +9,13 @@ This skill adheres to the **[BASELINE.md](BASELINE.md)**.
 
 ## Managed Request Routing
 
-`imm-planner` is entered explicitly by the user for a clear repository mutation.
-Ordinary host input does not invoke this Skill through natural-language routing.
+`imm-planner` starts on the user's request for a Spec, Plan, or TaskIntent for a
+repository change, by slash command or in natural language. A request that asks
+for none of these stays host-native, and `imm-run` starts only from a
+literal-user entry. A model-entered Planner outside an enrolled task ends the
+session's run entry, so Enrollment needs a fresh `imm-run` entry.
 An active Assurance projection remains authoritative and is resumed only through
-an explicit `imm-run` entry; explicit Planner entry owns planning only.
+an explicit `imm-run` entry; Planner entry owns planning only.
 
 Planner output remains non-authoritative. Planner creates or validates a
 candidate Spec/TaskIntent and never invokes the native Enrollment gate;
@@ -429,7 +432,7 @@ it, and structural Enrollment readiness is not proof that a descriptor executed.
 - **Planning granularity**: Keep a coherent outcome together when acceptance, risk, rollback, and authority can settle together. Use the TaskIntent decomposition rules below for independent outcomes. File count, tokens, compactions, elapsed time, and review rounds are evidence for judgment, not universal gates.
 - **Historical artifacts**: v3 prose Plan mutation is retired. `imm-plan` is a read-only validator for archived Plans; create no new Roadmap, Phase, successor Plan, or State Ledger.
 - **Risk-Triggered Exploration**: Before authoring a TaskIntent, resolve only unknowns that could change scope, design, or verification using targeted read-only probes. Internal `arch-explorer` and explicit-lens `advisory-reviewer` roles return evidence without writing the Spec, TaskIntent, or workflow state. Stop probing when outcome, scope, and verification are concrete. Do not use retired Plan termination flags to classify discovery failures.
-- **Simplicity**: Apply the BASELINE Workflow Activation gate first. Non-mutating host-native work creates no Planner artifact. Explicit Immune-Brain Skill entry starts this Planner phase; ordinary host input does not invoke it through natural-language routing. Create one coherent outcome instead of expanding ceremony.
+- **Simplicity**: Apply the BASELINE Workflow Activation gate first. Non-mutating host-native work creates no Planner artifact. The user's request for a Spec, Plan, or TaskIntent, by slash command or in natural language, starts this Planner phase; other host input stays host-native. Create one coherent outcome instead of expanding ceremony.
 - **Design-Depth Classification**: Classify change design risk with the smallest sufficient tier: **Low risk** (copy, configuration, trivial rename, or contained local fix) may omit a separate Technical Design; **Medium risk** (non-trivial single-module behavior or internal contract) records affected components, decisions, invariants, failure behavior, and verification implications; **High risk** (cross-module/API/data-flow/state-machine, security, migration, concurrency, architecture ownership, cross-runtime/package-contract, or persisted-state work) records boundaries, interfaces or flow, alternatives, invariants, rollback/compatibility, and verification implications. Medium and High risk require Technical Design in the Spec. Do not classify a change as Low risk when it has a contract, ownership, security, persistence, compatibility, or multi-component concern. Every new or revised Spec records `**Design risk**: Low|Medium|High` with an adjacent rationale.
 - **Design-view selection**: For Medium and High risk, select every materially relevant technical-design view from architecture layers, service/component interfaces, data flow, state transitions, and temporal sequence. Record a short `Design views` statement naming the selected views and why any omitted view cannot affect the design. Do not write empty architecture, interface, data-flow, state, or sequence sections. Low risk remains concise and may omit Technical Design. When a selected view is recorded, also record its required decision content: architecture layers need layer responsibilities, dependency direction, ownership, and prohibited coupling; service/component interfaces need inputs, outputs, errors, compatibility/versioning, and caller/callee ownership; data flow needs source, transformations, validation, destination, and failure handling; state transitions need states, legal transitions, trigger, invariant, terminal ownership, and recovery; temporal sequence needs ordered interactions, authority at each point, interruption behavior, and idempotency.
 - **Technical Design Authority**: The Spec is the single Technical Design baseline. TaskIntent acceptance and scope reference the applicable design decisions or invariants without copying Technical Design prose. If discovery invalidates the baseline, stop execution and return to Planner to update the Spec and decide whether `replan` is required. TaskIntent and Initiative text do not duplicate Technical Design prose or become a prose Plan substitute.

package/plugins/immune-brain/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Observe Claude Code Review and session lifecycle for Immune-Brain, keep a batch Lane's file edits inside its Lane, require a literal-user phase entry before Enrollment, batch start or a phase Skill, and announce an active Managed task without resuming it. Hooks never mint authority.",
+  "description": "Observe Claude Code Review and session lifecycle for Immune-Brain, keep a batch Lane's file edits inside its Lane, require a literal-user phase entry before Enrollment, batch start or the imm-run Skill, and announce an active Managed task without resuming it. Hooks never mint authority.",
   "hooks": {
     "PreToolUse": [
       {

package/plugins/immune-brain/runtime/assurance/phase_entry.ts

@@ -63,23 +63,16 @@ export function recognizePhaseEntry(text: string, readAlias: AliasReader): Phase
 }
 
 export interface PhaseEntryState {
-	/** Count of literal prompts observed in the session. */
-	prompt_seq: number;
 	run_live: boolean;
-	/** The prompt that recorded the live run entry, or 0. */
-	run_prompt_seq: number;
-	/** The prompt that recorded the latest plan entry, or 0. */
-	plan_prompt_seq: number;
 }
 
-export const NO_PHASE_ENTRY: PhaseEntryState = { prompt_seq: 0, run_live: false, run_prompt_seq: 0, plan_prompt_seq: 0 };
+export const NO_PHASE_ENTRY: PhaseEntryState = { run_live: false };
 
 /** One literal prompt: a run entry goes live, a plan entry revokes it. */
 export function applyPrompt(state: PhaseEntryState, entry: PhaseEntry | null): PhaseEntryState {
-	const prompt_seq = state.prompt_seq + 1;
-	if (entry === "run") return { ...state, prompt_seq, run_live: true, run_prompt_seq: prompt_seq };
-	if (entry === "plan") return { prompt_seq, run_live: false, run_prompt_seq: 0, plan_prompt_seq: prompt_seq };
-	return { ...state, prompt_seq };
+	if (entry === "run") return { run_live: true };
+	if (entry === "plan") return { run_live: false };
+	return state;
 }
 
 export function phaseEntryLogLine(entry: PhaseEntry | null): string {
@@ -115,26 +108,23 @@ function refuse(reason_code: typeof RUN_ENTRY_REQUIRED | typeof PHASE_ENTRY_REQU
 
 /**
  * Whether the session's entry state admits one operation. `state` is null when
- * the store could not be read, which refuses everything.
+ * the store could not be read, which refuses `enroll`, `start_unattended_batch`
+ * and the `imm-run` Skill. The Planner and Brainstorm Skills are never refused.
+ * `context` is accepted for Host callers; admission no longer depends on it.
  */
 export function admitPhaseOperation(
 	operation: PhaseOperation,
 	state: PhaseEntryState | null,
-	context: { activeClaim: boolean },
+	context?: { activeClaim: boolean },
 ): PhaseAdmission {
+	void context;
 	if (operation.kind === "tool") {
 		if (state?.run_live) return { ok: true };
 		return refuse(RUN_ENTRY_REQUIRED, `${operation.name} needs a literal-user imm-run entry in this session`);
 	}
-	const latest = state !== null && state.prompt_seq > 0 ? state.prompt_seq : -1;
-	if (operation.skill === "imm-run") {
-		if (state?.run_live && state.run_prompt_seq === latest) return { ok: true };
-		return refuse(PHASE_ENTRY_REQUIRED, "imm-run is entered by the user, not by a model Skill call");
-	}
-	if (state && state.plan_prompt_seq === latest) return { ok: true };
-	// Enrolled Intent Revision: the Loop routes to the Planner inside a run.
-	if (operation.skill === "imm-planner" && state?.run_live && context.activeClaim) return { ok: true };
-	return refuse(PHASE_ENTRY_REQUIRED, `${operation.skill} is entered by the user, not by a model Skill call`);
+	if (operation.skill !== "imm-run") return { ok: true };
+	if (state?.run_live) return { ok: true };
+	return refuse(PHASE_ENTRY_REQUIRED, "imm-run is entered by the user, not by a model Skill call");
 }
 
 /** The single-line message both Hosts return for a refusal. */

package/plugins/immune-brain/runtime/claude/lane_guard.ts

@@ -6,8 +6,10 @@
 //
 // Phase entry gate: UserPromptSubmit records which literal prompt entered
 // planning or execution; PreToolUse denies `enroll`, `start_unattended_batch`
-// and the three phase Skills without a matching entry, and otherwise leaves an
-// admission the tool handler consumes by tool-use id.
+// and the `imm-run` Skill without a live run entry, and otherwise leaves an
+// admission the tool handler consumes by tool-use id. A model Skill call for
+// `imm-planner` or `imm-brainstorm` is never denied; with no active claim it
+// revokes the run entry.
 import { lstatSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
@@ -25,6 +27,7 @@ import {
 	reducePhaseEntryLog,
 	RUN_ENTRY_REQUIRED,
 	type AliasReader,
+	type PhaseEntry,
 	type PhaseEntryState,
 	type PhaseOperation,
 } from "../assurance/phase_entry";
@@ -126,22 +129,29 @@ function dropPrivate(path: string): void {
 }
 
 /**
- * UserPromptSubmit: record whether this literal prompt entered a phase. Every
- * prompt is recorded so "the latest prompt" is decidable later. A prompt that
- * could not be recorded drops the log: an earlier entry must not outlive a
- * prompt the store never saw, so the session is back to no entry.
+ * Appends one entry line to the session log. A line that could not be written
+ * drops the log: an earlier entry must not outlive a line the store never saw,
+ * so the session is back to no entry.
+ */
+function appendPhaseEntry(sessionId: string, entry: PhaseEntry | null, root: string, locations: PhaseEntryLocations): boolean {
+	const path = entryLogPath(sessionId, root);
+	let recorded = false;
+	try { recorded = (locations.append ?? appendPrivate)(path, cacheDir(root), phaseEntryLogLine(entry)); } catch { /* an unwritten line drops the log */ }
+	if (!recorded) dropPrivate(path);
+	return recorded;
+}
+
+/**
+ * UserPromptSubmit: record whether this literal prompt entered a phase. A
+ * prompt that could not be recorded drops the log.
  */
 export function recordPhaseEntryPrompt(payload: Record<string, unknown>, locations: PhaseEntryLocations = {}): boolean {
 	if (payload.hook_event_name !== "UserPromptSubmit") return false;
 	const sessionId = sessionIdOf(payload);
 	if (!sessionId) return false;
-	const root = locations.root ?? tmpdir();
 	const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
 	const entry = recognizePhaseEntry(prompt, claudeAliasReader(cwdOf(payload), locations.home ?? homedir()));
-	const path = entryLogPath(sessionId, root);
-	const recorded = (locations.append ?? appendPrivate)(path, cacheDir(root), phaseEntryLogLine(entry));
-	if (!recorded) dropPrivate(path);
-	return recorded;
+	return appendPhaseEntry(sessionId, entry, locations.root ?? tmpdir(), locations);
 }
 
 function gatedOperation(payload: Record<string, unknown>): PhaseOperation | null {
@@ -156,20 +166,27 @@ function gatedOperation(payload: Record<string, unknown>): PhaseOperation | null
 }
 
 /**
- * PreToolUse for a gated tool: deny without a matching entry; for the two MCP
- * tools, otherwise write the admission the handler consumes. Any other tool
- * answers null and runs as configured.
+ * PreToolUse for a gated tool: deny without a live run entry; for the two MCP
+ * tools, otherwise write the admission the handler consumes. A Planner or
+ * Brainstorm Skill call is never denied; with no active claim it records a plan
+ * entry first, which revokes the run entry. Any other tool answers null and
+ * runs as configured.
  */
 export function phaseEntryGateHookOutput(payload: Record<string, unknown>, locations: PhaseEntryLocations = {}): string | null {
 	if (payload.hook_event_name !== "PreToolUse") return null;
 	const operation = gatedOperation(payload);
 	if (!operation) return null;
 	const root = locations.root ?? tmpdir();
+	if (operation.kind === "skill" && operation.skill !== "imm-run") {
+		let activeClaim = false;
+		try { activeClaim = readActiveClaimTaskId(cwdOf(payload)) !== null; } catch { /* unreadable authority is no claim */ }
+		const sessionId = sessionIdOf(payload);
+		if (!activeClaim && sessionId) appendPhaseEntry(sessionId, "plan", root, locations);
+		return null;
+	}
 	let state: PhaseEntryState | null = null;
 	try { state = readPhaseEntryState(sessionIdOf(payload), root, locations.read); } catch { /* an unreadable store refuses */ }
-	let activeClaim = false;
-	try { activeClaim = readActiveClaimTaskId(cwdOf(payload)) !== null; } catch { /* unreadable authority is no claim */ }
-	const admission = admitPhaseOperation(operation, state, { activeClaim });
+	const admission = admitPhaseOperation(operation, state);
 	if (!admission.ok) return denyPreToolUse(phaseRefusalMessage(admission));
 	if (operation.kind === "skill") return null;
 	const toolUseId = typeof payload.tool_use_id === "string" ? payload.tool_use_id : "";

package/plugins/immune-brain/runtime/plugin_version.ts

@@ -1,2 +1,2 @@
 // Generated by scripts/plugin_versioning.ts from the root package.json.
-export const PLUGIN_VERSION = "5.2.0" as const;
+export const PLUGIN_VERSION = "5.3.0" as const;

package/plugins/immune-brain/skills/BASELINE.md

@@ -55,7 +55,11 @@ framing does not load that execution guidance.
 
 Ordinary host input stays host-native and does not run natural-language Managed
 routing. A new Managed workflow starts only from explicit `imm-brainstorm`,
-`imm-planner`, or `imm-run` Skill entry.
+`imm-planner`, or `imm-run` Skill entry. For `imm-planner` and `imm-brainstorm`
+the user's request for that planning or clarification, by slash command or in
+natural language, is such an entry; a request that asks for neither stays
+host-native. `imm-run` starts only from a literal-user entry. A model-entered
+Planner outside an enrolled task ends the session's run entry.
 
 1. **Continue an existing Managed owner explicitly**: an active Assurance
    projection, TaskIntent, TaskRecord, reviewer `follow_up`, or other nonterminal

package/plugins/immune-brain/skills/imm-brainstorm/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: imm-brainstorm
-description: Use when the user explicitly requests Immune-Brain requirement clarification.
+description: Use when the user asks to clarify or explore requirements before Immune-Brain planning.
 ---
 
 # Immune-Brain: Brainstorm
 
 Use [`../../dist/imm-brainstorm.md`](../../dist/imm-brainstorm.md) as the
-canonical contract index, not a whole-document read. Explicit entry only: ordinary host questions do not
-start this workflow.
+canonical contract index, not a whole-document read. Starts on the user's request
+to clarify or explore requirements, by slash command or in natural language;
+ordinary host questions do not start this workflow.
 
 Mandatory constraints before any action: Brainstorm is read-only — no code,
 test, or runtime edits; no Spec, Plan, or workflow-state writes. All modes

package/plugins/immune-brain/skills/imm-planner/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: imm-planner
-description: Use when the user explicitly requests Immune-Brain Spec and TaskIntent planning.
+description: Use when the user asks for an Immune-Brain Spec, Plan, or TaskIntent for a repository change.
 ---
 
 # Immune-Brain: Planner
 
 Use [`../../dist/imm-planner.md`](../../dist/imm-planner.md) as the canonical contract
-index, not a whole-document read. Explicit entry only: ordinary host requests stay
+index, not a whole-document read. Starts on the user's request for a Spec, Plan
+or TaskIntent, by slash command or in natural language; other host requests stay
 host-native.
 
 Mandatory constraints before any action: Planner writes a TaskIntent, and a Spec