immune-brain 5.1.1 → 5.2.0

package/plugins/immune-brain/dist/imm-test-prune.md

@@ -0,0 +1,233 @@
+---
+name: imm-test-prune
+description: Use when the user explicitly requests Immune-Brain audit or pruning of redundant, bloated, or orphaned tests.
+---
+
+# Immune-Brain: Test Prune
+
+Reduce test-suite bloat in one Git repository. The Skill works through explicit
+invocation, a comprehensive test inventory, evidence-based candidate narrowing,
+one exact user-approved manifest, and bounded test-only mutation that never
+weakens a live guarantee. It is language- and runner-agnostic: it uses the
+target repository's own test, coverage, and static-check commands. This is a
+standalone host-native maintenance entry, not a Managed Path continuation and
+not an `imm-run` internal-role dispatch.
+
+## Authority Boundary
+
+This Skill restructures and prunes tests without creating or mutating
+TaskIntent, TaskRecord, Kernel, Spec, or Plan authority. An already active
+Managed task remains owned by `imm-run`. Read-only inventory and manifest
+production remain available.
+
+Classify each of the following candidates as `BLOCKED_ACTIVE_SCOPE` and
+continue auditing unaffected candidates:
+- a candidate overlapping the active TaskIntent `scope_hint`;
+- a candidate named by an active acceptance descriptor's verification `argv`.
+
+If the routing owner or scope cannot be read reliably, fail closed for
+mutation. This Skill does not invoke `imm-doc-prune`. Tests whose only behavior
+is asserting document existence or wording remain that Skill's job and are
+reported as `DEFER_DOC_PRUNE`.
+
+## Invocation
+
+Requires explicit invocation: `imm-test-prune` or `/imm-test-prune`. Ordinary
+"is this test redundant?" questions and routine test maintenance during a
+change stay host-native and do not enter this Skill.
+
+- `imm-test-prune audit`: read-only. Produce the manifest and stop.
+- `imm-test-prune`: produce the manifest, then wait for exact manifest
+  approval before any mutation.
+- An optional path argument narrows inventory to the named test files or
+  directories. The evidence rules still read the whole repository.
+
+No automatic invocation. No daemon, no cron, no CI gate, no allowlist, no
+runtime, no persistent report, no dependency installation, and no automatic
+commit.
+
+## Ordered Pruning Protocol
+
+### Inventory and Manifest
+
+1. **Establish repository safety.** Mutation requires a Git worktree. A
+   non-Git repository or an untracked candidate is audit-only. For each
+   candidate, record:
+   - path;
+   - blob/content hash;
+   - tracked status;
+   - candidate-local worktree status;
+   - line count;
+   - test-case count.
+
+   Unrelated dirty files do not block the run; a dirty candidate is `BLOCKED`.
+
+2. **Discover the repository's commands.** Read existing scripts, task files,
+   CI configuration, and runner configuration to identify the following,
+   without installing anything:
+   - the test command;
+   - its single-file and single-test selection syntax;
+   - its coverage command and report format;
+   - the static checks a contributor runs locally.
+
+   Record the result as the coverage capability:
+   - `isolated`: coverage can be collected for one selected test;
+   - `file`: coverage can be collected only for one test file;
+   - `unavailable`: no coverage tool is already configured or installed, or
+     collection fails.
+
+   Never add a coverage tool, plugin, or configuration to obtain coverage.
+
+3. **Record the baseline.** Run the discovered test command over the
+   inventoried scope once and record pass/fail per file and wall time. A file
+   already failing at baseline is `BLOCKED` for mutation and reported. This
+   Skill never repairs or deletes a failing test to make the suite green. When
+   coverage capability is not `unavailable`, also record baseline line
+   coverage for the source files the candidates exercise.
+
+4. **Inventory tests and support code.** Enumerate tracked test files,
+   fixtures, helpers, and snapshots. Exclude dependency, vendor, build-output,
+   and cache trees.
+
+5. **Classify test roles.**
+   - behavior: asserts runtime or public-surface behavior;
+   - documentation contract: asserts document existence, wording, links, or
+     sections;
+   - packaging and mirror consistency: asserts that registries, generated
+     output, and packaged copies agree;
+   - historical evidence: protects readers of frozen or archived records;
+   - `UNCLASSIFIED`: grouped, not interrogated file by file.
+
+   Historical-evidence and packaging-consistency tests are `KEEP` unless the
+   protected reader or consumer is proven retired.
+
+6. **Mechanically narrow candidates.**
+   - Find structurally identical cases that differ only in literal inputs.
+   - Find repeated setup blocks across cases or files.
+   - Find hard-coded lists that duplicate a canonical registry or manifest.
+   - Find assertions whose subject (symbol, path, command, or public surface)
+     no longer exists in current source.
+   - Find orphaned fixtures and helpers with no remaining importer.
+   - Find tests that assert private implementation detail where a
+     public-surface assertion already covers the same behavior.
+
+7. **Apply evidence rules.** Age, file length, test count, and intermittent
+   failure alone never prove a test redundant.
+
+   `DELETE` requires one of the following:
+   - **Retirement**: the protected behavior is retired, with the retiring
+     commit or a current owner showing it removed.
+   - **Subsumption**: a named surviving test covers the same behavior with
+     equal or stronger assertions, and coverage evidence supports it. With
+     `isolated` or `file` capability, the surviving test's covered lines must
+     be a superset of the removed test's covered lines. Collect this only for
+     candidate entries, at the finest available granularity.
+
+   Line coverage is necessary, not sufficient: the assertion comparison is
+   still required.
+
+   A subsumption claim is `UNVERIFIED` and not mutable when any of these holds:
+   - coverage capability is `unavailable`;
+   - collection fails;
+   - repeated runs disagree.
+
+   A `MERGE` that drops any case follows the same subsumption rule. `MERGE` and
+   `PARAMETERIZE` that keep every distinct input and assertion need no coverage
+   evidence.
+
+   `RELAX_TO_STRUCTURE` is allowed only where the asserted text is not a
+   machine contract consumed by code, a host, or a packaged surface.
+
+8. **Produce one exact manifest.** State the discovered commands and coverage
+   capability first. Classify each entry as one of:
+   - `MERGE`
+   - `PARAMETERIZE`
+   - `EXTRACT_HELPER`
+   - `DERIVE_FROM_SOURCE`
+   - `RELAX_TO_STRUCTURE`
+   - `DELETE`
+   - `KEEP`
+   - `BLOCKED`
+   - `BLOCKED_ACTIVE_SCOPE`
+   - `DEFER_DOC_PRUNE`
+   - `UNVERIFIED`
+
+   Each entry includes:
+   - evidence;
+   - the exact file, case, or helper action;
+   - for every `DELETE`, the retirement proof, or the surviving owner with its
+     coverage evidence;
+   - the expected change in case count and line count;
+   - the candidate hash.
+
+   Group `UNCLASSIFIED` files.
+
+9. **Gate mutation.** `audit` mode stops after the manifest. Mutation mode
+   also stops until the literal user approves exact manifest entries (for
+   example, "all recommendations except 4 and 7"). Broad approval such as
+   "clean up the tests" is insufficient. Interruption starts a fresh scan; no
+   manifest is persisted.
+
+### Approved Mutation
+
+10. **Revalidate and mutate minimally.** Before each approved change, re-read
+    the candidate bytes, Git status, importers, and active scope. Drift blocks
+    that item. Apply one manifest entry at a time, then run that entry's
+    focused tests before the next. A failing focused check stops further
+    mutation and leaves the inspectable diff.
+
+## Mutation Envelope
+
+This Skill may modify, merge, parameterize, or delete approved test files,
+fixtures, helpers, and snapshots, and may add shared helpers beside the
+repository's existing test helpers. It must stop when completion requires
+changing any of the following:
+- production source;
+- public API;
+- package exports;
+- registries or generated output;
+- dependencies, lockfiles, or coverage configuration;
+- credentials or network writes;
+- Git history;
+- any Managed authority mutation.
+
+**Never weaken a live guarantee.** Never do any of the following to make a
+check pass or to reduce counts:
+- skip, focus, or mark a test pending;
+- loosen an assertion's strength (exact to partial, equality to existence,
+  specific error to any error);
+- widen a timeout;
+- delete a negative assertion that still guards a live boundary.
+
+Snapshot updates are allowed only for cases whose structure the approved entry
+changed, never as a blanket refresh.
+
+## Verify and Report
+
+11. **Verify and report.**
+    - Re-run every touched test file plus the baseline scope, the discovered
+      static checks, and `git diff --check`.
+    - The baseline pass set must be preserved: every previously passing
+      behavior keeps a passing owner.
+    - When coverage capability is not `unavailable`, re-collect line coverage
+      for the baseline's source files. Any decrease blocks the run: name the
+      responsible entry and leave the diff for the user. Report coverage as
+      unavailable rather than inferring it.
+    - This Skill does not commit.
+    - Report only these sections:
+      - `Changed` (with entry IDs);
+      - `Deleted` (each with its retirement proof, or its surviving owner and
+        coverage evidence);
+      - `Blocked`;
+      - `Deferred to imm-doc-prune`;
+      - `Unverified`;
+      - `Delta` (case count, line count, wall time, and line coverage before
+        and after, or `coverage unavailable`);
+      - `Verification`;
+      - `Recovery: git log -- <path>`.
+
+## Recovery
+
+Git history is the archive for removed tests. Every `DELETE` entry reports
+`Recovery: git log -- <path>`. Untracked, dirty, baseline-failing, or non-Git
+candidates are never mutated.

package/plugins/immune-brain/dist/registry.yaml

@@ -56,6 +56,15 @@ skills:
     output_artifacts: [maintain_report]
     next_actions: []
     boundary: Minimize tracked agent-instruction context after explicit manifest approval; no Managed authority mutation, contract installation, or reference-document creation.
+  - name: imm-test-prune
+    path: skills/imm-test-prune/SKILL.md
+    role: execute
+    title: Test Prune
+    role_class: repair
+    canonical: true
+    output_artifacts: [test_prune_report]
+    next_actions: []
+    boundary: Audit and prune redundant tests after explicit manifest approval; no Managed authority mutation, production-source change, or assertion weakening.
   - name: imm-retro
     path: skills/imm-retro/SKILL.md
     role: execute

package/plugins/immune-brain/dist/role-prompts/code-review.md

@@ -26,6 +26,11 @@ material task-local maintenance risks. Pure naming, length, complexity
 thresholds, formatting, and design preference are not findings and must not
 cause style-only rework.
 
+Test-suite growth is advisory, never blocking: note a delivered test that
+duplicates an existing assertion, asserts only private implementation, or
+leaves a test protecting behavior the change retired. Weakened or missing
+tests for an acceptance remain blocking under the rules above.
+
 When a finding repeats an acceptance id or anchor that already produced rework in
 this task, do not file it as a fresh single-trigger defect. Name the invariant
 class it belongs to and state in `evidence.trigger` why the previously accepted
@@ -34,6 +39,13 @@ about the fix's scope, not a new bug. A trigger the accepted contract explicitly
 excludes is reported as an advisory note against that boundary, never as blocking
 rework.
 
+A defect that lies inside the TaskIntent goal and `scope_hint` is a blocking
+finding even when no acceptance assertion names its exact case word for word:
+cite the acceptance whose principle it violates as `acceptance_id` and
+`violated.ref`. Ask for the fix and a test that pins the case, never for the case
+to be written into the acceptance text; a missing literal clause is not itself a
+finding and does not call for an Intent revision.
+
 ## Invariant and Evidence Coverage
 
 Judge whether the change actually closes the invariant its acceptance names,
@@ -53,6 +65,14 @@ seam, or a seam silently replaced by a different one, is a finding carrying
 named, its absence is not a finding: candidates written before this rule carries
 no defect for lacking one.
 
+When the Spec referenced by an acceptance maps an `automated` user scenario to
+it, check that the delivered tests at that acceptance's agreed seam assert the
+scenario's `Then`: a scenario whose observable result is asserted nowhere is a
+finding carrying `violated.kind` of `acceptance` with `ref` the acceptance id.
+A `manual` scenario, and an acceptance with no mapped scenario, produce no such
+finding. This adds no finding kind and no verdict branch: it is the same
+`acceptance` finding the seam rule above already defines.
+
 Before pass, enumerate the immutable change set and read each complete per-file
 diff, including deletions. Page bounded reads until every hunk is visible; a
 truncated aggregate output or summary is incomplete coverage. Trace changed

package/plugins/immune-brain/dist/role-prompts/executor.md

@@ -54,6 +54,13 @@ Record missing evidence as blocked and repair it before handoff. The Loop owns
 verdict submission, finding disposition and the second-rework generalize-or-refute
 rule.
 
+A finding whose defect lies inside the TaskIntent goal and `scope_hint` is
+ordinary rework even when no acceptance names its exact case: fix the code and
+add the test that pins the case. Do not propose an Intent revision for it, and
+never append a single input case to an acceptance assertion to close a finding;
+acceptance states principles, tests enumerate cases. Route to `imm-planner` only
+when the goal, the scope, or a user-visible commitment must change.
+
 ## Code Quality Guard
 
 Before handoff, check the implementation for real implementation rather than
@@ -61,6 +68,14 @@ mock or hard-coded success, swallowed unexpected errors, missing validation at
 external trust boundaries, invented dependencies or APIs, unauthorized
 observable behavior changes, and production paths without a current caller.
 Do not weaken tests or hide an incomplete result to make Verification pass.
+
+Keep the test suite lean. Each added test pins one acceptance invariant or
+finding case at its public seam; do not mirror private calls, mock order or
+internal return values that a public assertion already covers. Before adding a
+test, search existing tests for the same behavior and extend or parameterize
+them instead of duplicating setup. When the change retires or replaces a
+behavior, update or delete the tests that protected it within scope and name
+the retired behavior or continuing owner in Delivery Evidence.
 Treat naming, function length, parameter count, nesting, and abstraction taste
 as contextual signals, never as automatic failure thresholds.
 

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

@@ -1,6 +1,36 @@
 {
-  "description": "Observe Claude Code Review and session lifecycle for Immune-Brain. 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 a phase Skill, and announce an active Managed task without resuming it. Hooks never mint authority.",
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/claude/mcp-server.mjs\" --hook"
+          }
+        ]
+      },
+      {
+        "matcher": "Skill|mcp__.*immune-brain.*__(enroll|start_unattended_batch)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/claude/mcp-server.mjs\" --hook"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/claude/mcp-server.mjs\" --hook"
+          }
+        ]
+      }
+    ],
     "SubagentStart": [
       {
         "hooks": [

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

@@ -0,0 +1,42 @@
+// A read-only Host notice for ordinary input while a Managed task is active in
+// the workspace. It tells the model, and through it the user, that the task
+// exists and what it is waiting for, so a fresh session does not commit or edit
+// inside that task's scope blind. It never resumes the task: ordinary input
+// stays host-native, and only an explicit `imm-run` entry continues it.
+import { readTaskRecordRaw } from "../kernel/storage";
+import { readActiveClaimTaskId } from "../unattended/batch_preflight";
+
+const MAX_SCOPE_ENTRIES = 12;
+
+export async function activeTaskNotice(root: string): Promise<string | null> {
+	let taskId: string | null;
+	try {
+		taskId = readActiveClaimTaskId(root);
+	} catch {
+		return null;
+	}
+	if (!taskId) return null;
+	// One TaskRecord read, no workspace diff: this runs on every prompt, and the
+	// exact next obligation is what the model reads from `status` afterwards.
+	let lifecycle = "unknown";
+	let artifactState = "unknown";
+	let scope: string[] = [];
+	try {
+		const record = readTaskRecordRaw(root, taskId).record;
+		if (record) {
+			lifecycle = record.lifecycle;
+			artifactState = record.artifact_state;
+			scope = [...record.intent_snapshot.scope_hint];
+		}
+	} catch {
+		// The notice is advisory; an unreadable projection still names the task.
+	}
+	if (lifecycle === "done" || lifecycle === "stopped") return null;
+	const shown = scope.slice(0, MAX_SCOPE_ENTRIES).join(", ") + (scope.length > MAX_SCOPE_ENTRIES ? ", ..." : "");
+	return [
+		`Immune-Brain: Managed task ${taskId} is active in this workspace (lifecycle ${lifecycle}, artifacts ${artifactState}).`,
+		"Ordinary input does not resume it, and another session may be running its assurance right now.",
+		`Before committing or modifying files inside its scope${shown ? ` (${shown})` : ""}, read its status and tell the user that this task is active and which obligation it is waiting on.`,
+		"Only an explicit imm-run entry continues it.",
+	].join(" ");
+}

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

@@ -0,0 +1,24 @@
+// Reads one user command alias for phase entry recognition. An alias may be a
+// symlink, so the size bound is taken from the opened file, never from the link.
+
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+
+export const MAX_ALIAS_BYTES = 64 * 1024;
+
+/** The alias body, or null when it is absent, not a regular file, or over the bound. */
+export function readAliasFile(path: string, maxBytes = MAX_ALIAS_BYTES): string | null {
+	let fd: number;
+	try { fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK); } catch { return null; }
+	try {
+		const stat = fstatSync(fd);
+		if (!stat.isFile() || stat.size > maxBytes) return null;
+		// One byte past the bound: a file that grew after the stat is refused too.
+		const buf = Buffer.alloc(maxBytes + 1);
+		const read = readSync(fd, buf, 0, buf.length, 0);
+		return read > maxBytes ? null : buf.toString("utf8", 0, read);
+	} catch {
+		return null;
+	} finally {
+		closeSync(fd);
+	}
+}

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

@@ -23,6 +23,7 @@ import type { AssuranceProjectionResult } from "../kernel/assurance_projection";
 import type { TaskIntentIdentityToken } from "../kernel/intent_token_registry";
 import type { AssuranceHostPort, HostReviewReservation } from "./host_port";
 import type { GithubTrackerResult as GithubTrackerProjectionResult } from "../github_issue_tracker";
+import { isLaneWorkspaceForTask } from "../unattended/lane_workspace";
 
 
 export type AssuranceRole = "qa" | "review";
@@ -87,6 +88,10 @@ export function deriveGithubTerminalProjectionInput(
  * null otherwise), a tracker failure is reported as a retryable failure rather
  * than evidence or a blocker, and a failure never repeats the settling Kernel
  * mutation.
+ *
+ * A completed settlement inside a batch Lane writes nothing to the tracker: the
+ * Lane's delivery is not on the batch branch yet, so the coordinator closes the
+ * Child only after it integrates that child's commit.
  */
 export async function projectTerminalTrackerState(input: {
 	root: string;
@@ -94,10 +99,14 @@ export async function projectTerminalTrackerState(input: {
 	projection: AssuranceProjectionResult;
 	tombstone: TaskTombstone | null;
 	markTerminal: (root: string, projection: GithubTerminalProjectionInput) => Promise<GithubTrackerProjectionResult>;
+	isLaneWorkspace?: (root: string, taskId: string) => boolean;
 }): Promise<GithubTrackerProjectionResult | undefined> {
 	if (input.projection.error) return undefined;
 	const terminal = deriveGithubTerminalProjectionInput(input.task_id, input.projection, input.tombstone);
 	if (!terminal) return undefined;
+	// Only a completed delivery waits for integration; an explicit stop inside a
+	// Lane is never integrated and still projects `not planned` here.
+	if (terminal.phase === "done" && (input.isLaneWorkspace ?? isLaneWorkspaceForTask)(input.root, input.task_id)) return undefined;
 	try {
 		return await input.markTerminal(input.root, terminal);
 	} catch {

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

@@ -54,8 +54,11 @@ function isolatedGitEnv(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
 	};
 }
 
+// `maintenance.auto=false`: fetch otherwise starts `maintenance run --auto`,
+// which newer Git detaches; the detached child still owns
+// objects/maintenance.lock after fetch returns and mutates the sealed .git.
 function git(cwd: string, args: string[], extra: Record<string, string> = {}): string {
-	return execFileSync("git", args, {
+	return execFileSync("git", ["-c", "maintenance.auto=false", ...args], {
 		cwd,
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],

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

@@ -0,0 +1,143 @@
+// Host-neutral phase entry: which literal user input enters planning or
+// execution, the per-session entry state, and whether an operation is admitted.
+// Pure: a Host supplies the alias reader and owns where the state is stored.
+// A live entry mints no authority; it only lets the existing native gate open.
+
+export type PhaseEntry = "plan" | "run";
+
+/** Returns the body of a user command alias, or nothing when it does not exist. */
+export type AliasReader = (name: string) => string | null | undefined;
+
+export const RUN_ENTRY_REQUIRED = "run_entry_required";
+export const PHASE_ENTRY_REQUIRED = "phase_entry_required";
+
+export const PHASE_ENTRY_RECOVERY: Record<typeof RUN_ENTRY_REQUIRED | typeof PHASE_ENTRY_REQUIRED, string> = {
+	[RUN_ENTRY_REQUIRED]: "ask the user to enter imm-run in the current Host",
+	[PHASE_ENTRY_REQUIRED]: "ask the user to enter the Skill themselves in the current Host",
+};
+
+const PACKAGED: Record<string, PhaseEntry> = {
+	"imm-planner": "plan",
+	"imm-brainstorm": "plan",
+	"imm-run": "run",
+};
+// An alias body may still name the retired Loop skill.
+const ALIAS_TARGETS: Record<string, PhaseEntry> = { ...PACKAGED, "imm-loop": "run" };
+const PREFIXES = ["immune-brain:", "skill:"];
+const ALIAS_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const SKILL_MENTION = /(?<![A-Za-z0-9_-])imm-(?:planner|brainstorm|run|loop)(?![A-Za-z0-9_-])/g;
+// The Host-expanded form of a slash command, anchored at the start of the prompt.
+const EXPANDED = /^<command-message>[^<]*<\/command-message>\s*<command-name>\/([^\s<]+)<\/command-name>/;
+const RAW = /^\/(\S+)/;
+
+function stripPrefix(name: string): string {
+	for (const prefix of PREFIXES) if (name.startsWith(prefix)) return name.slice(prefix.length);
+	return name;
+}
+
+/** The packaged phase Skill a Skill-tool name refers to, or null for any other Skill. */
+export function packagedPhaseSkill(name: string): keyof typeof PACKAGED | null {
+	// Trimmed first: a Host that resolves a padded Skill name must not skip the gate.
+	const trimmed = name.trim();
+	const bare = stripPrefix(trimmed.startsWith("/") ? trimmed.slice(1) : trimmed);
+	return Object.hasOwn(PACKAGED, bare) ? bare : null;
+}
+
+/**
+ * The phase a literal prompt enters, or null. Only a leading slash command
+ * counts: a packaged name, a prefixed packaged name, or a user alias whose body
+ * names exactly one phase Skill. A mention anywhere else is not an entry.
+ */
+export function recognizePhaseEntry(text: string, readAlias: AliasReader): PhaseEntry | null {
+	const command = (RAW.exec(text) ?? EXPANDED.exec(text))?.[1];
+	if (!command) return null;
+	const packaged = packagedPhaseSkill(command);
+	if (packaged) return PACKAGED[packaged];
+	if (!ALIAS_NAME.test(command)) return null;
+	let body: string | null | undefined;
+	try { body = readAlias(command); } catch { return null; }
+	if (!body) return null;
+	const targets = new Set(body.match(SKILL_MENTION) ?? []);
+	if (targets.size !== 1) return null;
+	return ALIAS_TARGETS[[...targets][0]] ?? null;
+}
+
+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 };
+
+/** 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 };
+}
+
+export function phaseEntryLogLine(entry: PhaseEntry | null): string {
+	return `${JSON.stringify({ v: 1, entry })}\n`;
+}
+
+/** Folds a session's entry log. Any malformed line makes the whole log unreadable. */
+export function reducePhaseEntryLog(text: string): PhaseEntryState | null {
+	let state = NO_PHASE_ENTRY;
+	for (const line of text.split("\n")) {
+		if (!line) continue;
+		let record: unknown;
+		try { record = JSON.parse(line); } catch { return null; }
+		if (!record || typeof record !== "object") return null;
+		const { v, entry } = record as { v?: unknown; entry?: unknown };
+		if (v !== 1 || (entry !== null && entry !== "plan" && entry !== "run")) return null;
+		state = applyPrompt(state, entry);
+	}
+	return state;
+}
+
+export type PhaseOperation =
+	| { kind: "tool"; name: "enroll" | "start_unattended_batch" }
+	| { kind: "skill"; skill: keyof typeof PACKAGED };
+
+export type PhaseAdmission =
+	| { ok: true }
+	| { ok: false; reason_code: typeof RUN_ENTRY_REQUIRED | typeof PHASE_ENTRY_REQUIRED; detail: string; recovery_action: string };
+
+function refuse(reason_code: typeof RUN_ENTRY_REQUIRED | typeof PHASE_ENTRY_REQUIRED, detail: string): PhaseAdmission {
+	return { ok: false, reason_code, detail, recovery_action: PHASE_ENTRY_RECOVERY[reason_code] };
+}
+
+/**
+ * Whether the session's entry state admits one operation. `state` is null when
+ * the store could not be read, which refuses everything.
+ */
+export function admitPhaseOperation(
+	operation: PhaseOperation,
+	state: PhaseEntryState | null,
+	context: { activeClaim: boolean },
+): PhaseAdmission {
+	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`);
+}
+
+/** The single-line message both Hosts return for a refusal. */
+export function phaseRefusalMessage(refusal: Extract<PhaseAdmission, { ok: false }>): string {
+	return `${refusal.reason_code}: ${refusal.detail}; recovery: ${refusal.recovery_action}`;
+}

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

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
+import { PHASE_ENTRY_RECOVERY } from "../assurance/phase_entry";
 
 export const PRIVILEGED_OPERATIONS = [
 	"enroll",
@@ -17,7 +18,9 @@ export type NativeFailureCode =
 	| "user_cancelled"
 	| "correlation_missing"
 	| "unsupported_host"
-	| "workspace_changed";
+	| "workspace_changed"
+	| "run_entry_required"
+	| "phase_entry_required";
 
 const RECOVERY_ACTIONS: Record<NativeFailureCode, string> = {
 	interaction_not_opened: "retry through a fresh native gate in the current Host",
@@ -26,6 +29,7 @@ const RECOVERY_ACTIONS: Record<NativeFailureCode, string> = {
 	correlation_missing: "retry through a fresh native gate in the current Host",
 	unsupported_host: "upgrade to a supported Claude Code version and retry in the current Host",
 	workspace_changed: "review the current workspace and retry through a fresh native gate",
+	...PHASE_ENTRY_RECOVERY,
 };
 
 export class NativeAuthorityError extends Error {
@@ -88,6 +92,9 @@ export interface NativeConfirmationInput {
 			max_parallel: number;
 			parallel_groups: string[][];
 			serialized: Array<{ task_id: string; overlaps_with: string[] }>;
+			final_verification?: string[];
+			/** ADR 0018: the gate offers the opt-in delegation of in-envelope Lane Intent revisions. */
+			offer_revision_delegation?: boolean;
 		};
 	};
 	/** Present only for a batch disposition: the record the user is asked to retire. */
@@ -105,6 +112,8 @@ export interface NativeConfirmationInput {
 export interface NativeConfirmationResult {
 	decision: NativeDecision;
 	requestId: string;
+	/** ADR 0018: true only when the user ticked the delegation in a lane batch gate. */
+	delegateRevisions?: boolean;
 }
 
 export type NativeConfirmationPort = (input: NativeConfirmationInput) => Promise<NativeConfirmationResult>;