immune-brain 4.4.1 → 4.6.0

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

@@ -176,6 +176,15 @@ async function runKernelCli(args: string[], root: string): Promise<{
 	// status --json, and the explicit audit command. All other kernel
 	// subcommands (readiness, journal, migrate) are retired.
 	const sub = args[0] ?? "";
+	// The canonical author shape is discoverable before any error probing: a
+	// caller who does not know the destination/stdin contract reads it here
+	// instead of discovering it through a failed call.
+	if (sub === "intent" && (args[1] === "--help" || args[1] === "help" || args[1] === undefined))
+		return {
+			stdout: `${intentAuthorHelp()}\n`,
+			stderr: "",
+			returncode: 0,
+		};
 	// The explicit claimless storage-layout migration is reachable here: a
 	// worktree still on the retired file store has no other entry point, and
 	// every mutating subcommand stays fail-closed behind it.
@@ -224,6 +233,51 @@ async function runCli(command: string, args: string[], root: string): Promise<{
 	};
 }
 
+/**
+ * The canonical TaskIntent author contract, printed by `imm-kernel intent` and
+ * `imm-kernel intent --help`. It states destination, stdin, and the strict v2
+ * descriptor shape before a caller has to discover them by failing a call.
+ */
+export function intentAuthorHelp(): string {
+	return [
+		"imm-kernel intent author <destination> --stdin --json",
+		"  destination: docs/plans/<task-id>.intent.json (created exclusively; never overwritten)",
+		"  stdin:       the complete candidate TaskIntent JSON on file descriptor 0",
+		"  stdout:      { valid, enrollment_ready, intent_ref, git_base_initialization_required, ... }",
+		"",
+		"imm-kernel intent validate <path> --json",
+		"",
+		"Candidate shape (assurance_kernel/task_intent/v1):",
+		JSON.stringify(
+			{
+				contract: "assurance_kernel/task_intent/v1",
+				task_id: "<task-id>",
+				owner: "user",
+				goal: "<one closable outcome>",
+				risk: "routine|material|critical",
+				revision: 1,
+				scope_hint: ["<every file the slice touches>"],
+				acceptance: [
+					{
+						id: "<ID>",
+						assertion: "<observable invariant>",
+						verification: JSON.stringify({
+							contract: "assurance_kernel/verification_descriptor/v2",
+							command: { executable: "bun", argv: ["test", "tests/<focused>.test.ts"], cwd: ".", timeout_ms: 180000, max_output_bytes: 196608 },
+							environment: { prepare: null, writable_paths: [] },
+						}),
+					},
+				],
+			},
+			null,
+			2,
+		),
+		"",
+		"Unknown fields are rejected; the descriptor parser is strict v2 and never infers a runner.",
+		"A v1 descriptor is historical-only and needs an explicit Intent revision before execution.",
+	].join("\n");
+}
+
 async function main(argv: string[]): Promise<number> {
 	const mode = argv[0];
 	const root = process.cwd();

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

@@ -19,11 +19,13 @@ export interface GitWorkspaceSnapshot {
 }
 
 function git(root: string, args: string[]): string | null {
-	const result = spawnSync("git", ["-C", root, ...args], {
+	const diff = args[0] === "diff";
+	const command = diff ? ["diff", "--exit-code", ...args.slice(1)] : args;
+	const result = spawnSync("git", ["--no-optional-locks", "-c", "diff.autoRefreshIndex=false", "-C", root, ...command], {
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 	});
-	return result.status === 0 ? result.stdout : null;
+	return result.status === 0 || (diff && result.status === 1) ? result.stdout : null;
 }
 
 function splitNull(value: string): string[] {
@@ -135,7 +137,9 @@ function fileFingerprint(root: string, relativePath: string): string {
 }
 
 function dirtyPaths(root: string): string[] | null {
-	const tracked = git(root, ["diff", "--name-only", "-z", "HEAD", "--"]);
+	// --no-renames, like the task-path derivations: rename detection would list
+	// only the destination and hide the source path's deletion.
+	const tracked = git(root, ["diff", "--name-only", "--no-renames", "-z", "HEAD", "--"]);
 	const untracked = git(root, [
 		"ls-files",
 		"--others",
@@ -217,12 +221,14 @@ export function setGitTaskSnapshotTestHook(hook: () => void): () => void {
 }
 
 function gitBytes(root: string, args: string[]): Buffer {
-	const result = spawnSync("git", ["-C", root, ...args], {
+	const diff = args[0] === "diff";
+	const command = diff ? ["diff", "--exit-code", ...args.slice(1)] : args;
+	const result = spawnSync("git", ["--no-optional-locks", "-c", "diff.autoRefreshIndex=false", "-C", root, ...command], {
 		encoding: null,
 		stdio: ["ignore", "pipe", "pipe"],
 		maxBuffer: 8 * 1024 * 1024,
 	});
-	if (result.status !== 0 || !Buffer.isBuffer(result.stdout)) {
+	if ((result.status !== 0 && !(diff && result.status === 1)) || !Buffer.isBuffer(result.stdout)) {
 		throw new Error(`Git task snapshot command failed: git ${args.join(" ")}`);
 	}
 	return result.stdout;
@@ -386,6 +392,44 @@ function taskPathMatchesScope(path: string, scope: string[]): boolean {
 	return scope.some((scopePath) => pathMatchesScope(path, scopePath));
 }
 
+/**
+ * A staged in-scope path that still equals the Enrollment baseline predates the
+ * task. Dropping it silently let QA attest workspace bytes that the Review
+ * revision did not carry, so it is a hard stop instead: reverting and reapplying
+ * yields the same bytes, and only a fresh Enrollment from a clean scope recovers.
+ * The task's own planning sidecar is exempt, as it is in dirtyScopePaths:
+ * Enrollment requires it tracked, so it is routinely staged in the baseline.
+ */
+function assertNoPreEnrollmentScopeChanges(root: string, scopedStagedPaths: readonly string[], taskId?: string): void {
+	const baseline = readEnrollmentBaseline(root);
+	if (!baseline) return;
+	const current = captureGitWorkspaceSnapshot(root);
+	if (!current) throw new Error("enrollment baseline cannot be compared because Git is unavailable");
+	const withheld = [...new Set(scopedStagedPaths)]
+		.filter((path) => !isOwnPlanningSidecar(path, taskId))
+		.filter((path) => baseline.dirty_files[path] !== undefined && baseline.dirty_files[path] === current.dirty_files[path])
+		.sort(comparePaths);
+	if (withheld.length > 0)
+		throw new Error(
+			`task scope contains staged changes that predate Enrollment and cannot become task work: ${withheld.join(", ")}; stop the task and re-enroll from a clean scope`,
+		);
+}
+
+/**
+ * In-scope paths that are already staged, modified or untracked relative to
+ * HEAD. Enrollment refuses these: the baseline would record them as user dirt
+ * and they could never be delivered by the task.
+ */
+export function dirtyScopePaths(projectRoot: string, scopeHint: unknown, taskId?: string): string[] {
+	const root = realpathSync(resolve(projectRoot));
+	const scope = assertCanonicalTaskScope(scopeHint);
+	const paths = dirtyPaths(root);
+	if (!paths) throw new Error("cannot inspect the task scope outside a committed Git workspace");
+	return paths.filter(
+		(path) => !isNonDeliveryPath(path) && !isOwnPlanningSidecar(path, taskId) && taskPathMatchesScope(path, scope),
+	);
+}
+
 function taskSnapshotOnce(root: string, scope: string[], taskId?: string): GitTaskSnapshot {
 	const repositoryRoot = git(root, ["rev-parse", "--show-toplevel"])?.trim();
 	const head = git(root, ["rev-parse", "--verify", "HEAD^{commit}"])?.trim();
@@ -421,12 +465,10 @@ function taskSnapshotOnce(root: string, scope: string[], taskId?: string): GitTa
 	if (uncommittedInScope.length > 0)
 		throw new Error(`task scope contains unstaged or untracked changes: ${uncommittedInScope.join(", ")}`);
 
-	const baseline = readEnrollmentBaseline(root);
-	const current = baseline ? captureGitWorkspaceSnapshot(root) : null;
 	const taskPaths = [...new Set(stagedPaths)]
 		.filter((path) => !isNonDeliveryPath(path) && taskPathMatchesScope(path, scope))
-		.filter((path) => !(baseline && current && baseline.dirty_files[path] === current.dirty_files[path] && baseline.dirty_files[path] !== undefined))
 		.sort(comparePaths);
+	assertNoPreEnrollmentScopeChanges(root, taskPaths, taskId);
 	const stagedFiles: Record<string, GitTaskIndexEntry> = {};
 	for (const path of taskPaths) {
 		const current = indexEntry(root, path);
@@ -555,10 +597,8 @@ function taskRevisionSnapshotOnce(
 		"untracked task revision paths",
 	);
 	assertNoEnvelopeEscape(root, stagedPaths, scope, taskId);
-	const baseline = readEnrollmentBaseline(root);
-	const current = baseline ? captureGitWorkspaceSnapshot(root) : null;
-	const scopedStagedPaths = stagedPaths.filter((path) => !isNonDeliveryPath(path) && taskPathMatchesScope(path, scope))
-		.filter((path) => !(baseline && current && baseline.dirty_files[path] === current.dirty_files[path] && baseline.dirty_files[path] !== undefined));
+	const scopedStagedPaths = stagedPaths.filter((path) => !isNonDeliveryPath(path) && taskPathMatchesScope(path, scope));
+	assertNoPreEnrollmentScopeChanges(root, scopedStagedPaths, taskId);
 	const scopedUnstagedPaths = unstagedPaths.filter((path) => taskPathMatchesScope(path, scope));
 	const scopedUntrackedPaths = untrackedPaths.filter((path) => taskPathMatchesScope(path, scope));
 	assertNoCaseFoldCollisions(
@@ -631,6 +671,29 @@ export function taskRevisionIdentity(
 	};
 }
 
+/** The same v4 identity for an immutable delivered commit, without touching the index. */
+export function taskCommitRevisionIdentity(projectRoot: string, scopeHint: unknown, baseHead: string, commit: string): GitTaskDiffIdentity {
+	const requested = resolve(projectRoot);
+	if (lstatSync(requested).isSymbolicLink()) throw new Error("task commit root must be a real directory");
+	const root = realpathSync(requested), scope = assertCanonicalTaskScope(scopeHint);
+	if (!GIT_OBJECT_ID.test(baseHead) || !GIT_OBJECT_ID.test(commit)) throw new Error("invalid task commit identity");
+	if (gitRequired(root, ["cat-file", "-t", baseHead], "unreadable task base") !== "commit" ||
+		gitRequired(root, ["cat-file", "-t", commit], "unreadable task commit") !== "commit" ||
+		git(root, ["merge-base", "--is-ancestor", baseHead, commit]) === null) throw new Error("invalid task commit ancestry");
+	const paths = decodeNullPaths(gitBytes(root, ["diff", "--no-renames", "--name-only", "-z", baseHead, commit, "--"]), "task commit paths")
+		.filter(path => !isNonDeliveryPath(path) && taskPathMatchesScope(path, scope)).sort(comparePaths);
+	assertNoCaseFoldCollisions(paths, "task commit paths");
+	const changed_paths: Record<string, GitTaskIndexEntry> = {};
+	for (const path of paths) {
+		const current = headEntry(root, commit, path), base = headEntry(root, baseHead, path);
+		changed_paths[path] = { status: !base ? "added" : !current ? "deleted" : "modified",
+			mode: current?.mode ?? null, oid: current?.oid ?? null, base_mode: base?.mode ?? null, base_oid: base?.oid ?? null };
+	}
+	const snapshot: GitTaskRevisionSnapshot = { kind: "git-task-revision-v1", repository_root: root, base_head: baseHead,
+		base_tree: gitRequired(root, ["rev-parse", `${baseHead}^{tree}`], "unreadable task base tree"), scope, changed_paths };
+	return { diff_hash: hashTaskSnapshot(snapshot), changed_paths: paths };
+}
+
 /** The single v4 freshness identity shared by QA, Review, authorization, and completion. */
 export function taskRevisionDiffHash(
 	projectRoot: string,

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

@@ -9,6 +9,20 @@
 - Stage only explicit task-owned paths. This staging authority does not grant
   commit, push, broad staging, or authority over pre-existing user changes.
   Never use `git add .` or `git add -A` in a dirty worktree.
+- Grant effects separately: staging, commit, push, publication, and outbound
+  model/data calls are distinct operations. Recovering a stage-only instruction
+  restores staging and nothing more; commit, push, and publication each keep
+  their own existing grant. An explicit approval already covering the same
+  operation, target, and impact — including a valid batch capability — stays
+  usable without another gate.
+- Before a new outbound effect, check the project's existing research channel and
+data scope. A public article, a mock, a documentation example, or a local
+read-only database gives no authority to call an arbitrary provider or send new
+data; authorize only a genuinely new channel/data/effect delta. Distinguish
+documentation, mock, real-channel, and model-quality evidence when reporting.
+- These text rules are instruction contracts, not a hard bash sandbox. They
+guide behavior and are checked as contracts; they do not technically prevent an
+arbitrary shell command, so authority gates and review remain the real boundary.
 - Do not create, switch, or delete Git worktrees; operate only in the Host launch directory.
 - Record reproducible evidence before reporting closure.
 - Required verification must pass before reporting completion; disclosing a gap is not a substitute. Autonomously diagnose, repair, and rerun failing conventional local checks within the authorized scope; never delete, skip, or weaken a valid check to manufacture a pass. If a required check remains failing or cannot run, report the work as incomplete with the concrete blocker.
@@ -81,7 +95,6 @@ non-Kernel operations, an explicit user approval already covering the same
 operation, target, and impact is sufficient; ask again only for a material delta.
 A generic continuation or configured preference is not blanket authorization.
 Mandatory native gates and hash-bound manifest approvals still apply.
-
 Privileged effects include:
 
 - publish, release, deployment, or remote-system mutation;
@@ -91,6 +104,10 @@ Privileged effects include:
   override; and
 - external writes whose target or impact cannot be safely reversed locally.
 
+An existing grant for one of these never inherits another: a stage-only
+instruction stays stage-only, a commit is not push or publication authority,
+and a valid batch capability commits only its own scope-bounded child.
+
 Routine Managed enrollment uses one current-Host native confirmation bound to the TaskIntent content hash after Planner validation. Explicit Plan-only requests stop with candidate artifacts and do not invoke Enrollment; execution-bearing requests open the native gate directly without chat pre-confirmation. Enrollment validates intent, Git ownership, scope, workspace claim, and final authority preconditions without executing acceptance descriptors; deterministic QA executes them after implementation. The routine task proceeds from that single confirmation through enrollment, execution, and QA without a second human stop. Do not request confirmation for local in-scope edits, local verification, ordinary Direct rework, scoped diff review, or completion reporting. Managed evidence, QA, Review, and completion authority remain governed by their Managed contracts; R2 does not weaken them. Managed native-authority failures fail closed with one stable reason and exactly one same-Host recovery action; never offer a Pi, Direct Path, cross-Host/worktree, unmanaged, or automatic-retry fallback.
 
 For an unborn symbolic Git HEAD, the same Enrollment confirmation discloses an empty root commit. After approval, the Host creates that commit without staging project content or changing the index/worktree, then revalidates ownership and rehearses Enrollment against the new base. Git identity uses existing environment/config values with an explicit automation fallback, never config writes. Decline or pre-initialization cancellation leaves HEAD unborn; if later Enrollment fails or is cancelled, report the remaining commit. Invalid Git refs are errors, not initialization candidates.

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

@@ -28,3 +28,8 @@ When framing discusses later execution, describe Enrollment only as the
 current Host's native gate. A failed Managed authority interaction stays
 fail-closed: report one same-Host recovery action, never another Host,
 worktree, or unmanaged implementation.
+
+Every sourced branch closes as resolved, explicitly excluded, explicitly
+deferred, or dependent-blocked with its blocking node named, including for a
+clear zero-question request; a confirmed outcome is never conserved as a
+smaller deliverable.

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

@@ -11,7 +11,9 @@ ordinary host input never resumes a Managed owner implicitly.
 
 Mandatory constraints before any action: verify the active backend claim,
 TaskIntent, and TaskRecord via `imm_kernel_canary` `status` first; invalid or
-contradictory projections fail closed. All Managed authority gates use the
+contradictory projections fail closed. Resume only from those authority facts:
+a compaction heading, HANDOFF summary, or Issue state is prose, never authority.
+All Managed authority gates use the
 current Host's native interaction. A failed gate stays fail-closed and
 reports one same-Host recovery action; never suggest another Host, worktree,
 or unmanaged implementation as a fallback.
@@ -24,5 +26,5 @@ or all references as an entry prerequisite.
 - common: [Shared Guards](../../dist/BASELINE.md#shared-guards), [Workflow Activation](../../dist/BASELINE.md#workflow-activation), [Host Confirmation Boundary](../../dist/BASELINE.md#host-confirmation-boundary), [Kernel Canary Routing and Authority](../../dist/imm-loop.md#kernel-canary-routing-and-authority)
 - unattended batch run, or any question about whether `imm-loop` starts one: [Unattended Batch Opt-In](../../dist/imm-loop.md#unattended-batch-opt-in)
 - steady execution: [Verification and Local Recovery](../../dist/BASELINE.md#verification-and-local-recovery), [Execution Loop](../../dist/imm-loop.md#execution-loop), [Observable Output](../../dist/imm-loop.md#observable-output)
-- rework, scope expansion, breaking revision, user decision, stop, interruption or unknown state before any action: [Decisions and Recovery](../../dist/imm-loop.md#decisions-and-recovery), [Failure Output](../../dist/imm-loop.md#failure-output); re-read `status`, then the pending obligation
+- rework, scope expansion, breaking revision, user decision, stop, interruption or unknown state before any action: [Decisions and Recovery](../../dist/imm-loop.md#decisions-and-recovery), [Failure Output](../../dist/imm-loop.md#failure-output); re-read `status`, then the pending obligation. Rework submits the verdict before editing, and an uncertain interruption resumes from exact task/run authority facts rather than a summary.
 - review or post-settlement learning: [Review and Learning](../../dist/imm-loop.md#review-and-learning)

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

@@ -11,7 +11,10 @@ host-native.
 
 Mandatory constraints before any action: Planner writes a TaskIntent, and a Spec
 only for complex work; it never implements, overwrites an enrolled TaskIntent, or
-grants execution authority — only the native Enrollment gate can.
+grants execution authority — only the native Enrollment gate can. Before
+handoff it maps every upstream item and required phase exactly once and reports
+each Slice result plus the remaining gap; a plan that conserves a smaller
+deliverable than the confirmed outcome fails that check instead of passing.
 
 Section routes - load a section's instructions only when its branch applies.
 Read each linked heading body up to the next heading; nested sections and
@@ -40,3 +43,9 @@ that include execution invoke the current Host's native Enrollment gate
 directly, without chat pre-confirmation. Native-gate failure stays fail-closed
 in that Host: report its reason and one retry action only; never suggest
 another Host, worktree, or unmanaged implementation as a fallback.
+
+Before that handoff, confirm complete mapping of every upstream item and
+required phase with each Slice's result and the remaining gap; reject a plan
+that conserved only part of the confirmed outcome, and ask again only for a
+newly evidenced material delta rather than reconfirming an unchanged clear
+request or an already-confirmed decision.

package/plugins/immune-brain/runtime/unattended/confirmation_deadline.ts

@@ -1,33 +0,0 @@
-// A native confirmation is bounded on both Hosts. Claude bounded its MCP
-// elicitation with IMMUNE_BRAIN_BATCH_TIMEOUT_MS and Pi waited indefinitely; the
-// bound, its default, and the "this deadline expired rather than the user
-// cancelling" distinction are shared here. Each Host still owns its transport:
-// this module only produces the signal to hand it and reports expiry.
-
-export const CONFIRMATION_TIMEOUT_DEFAULT_MS = 60_000;
-export const CONFIRMATION_TIMEOUT_ENV = "IMMUNE_BRAIN_BATCH_TIMEOUT_MS";
-
-export interface ConfirmationDeadline {
-	/** The caller's signal, combined with this deadline. */
-	signal: AbortSignal;
-	/** True when this deadline fired and the caller's own signal did not. */
-	timedOut(): boolean;
-	clear(): void;
-}
-
-export function startConfirmationDeadline(input: {
-	env?: Record<string, string | undefined>;
-	signal?: AbortSignal;
-}): ConfirmationDeadline {
-	const configured = Number(input.env?.[CONFIRMATION_TIMEOUT_ENV]);
-	const timeoutMs = Number.isFinite(configured) && configured > 0 ? configured : CONFIRMATION_TIMEOUT_DEFAULT_MS;
-	const controller = new AbortController();
-	const timer = setTimeout(() => {
-		controller.abort(new Error("native confirmation timed out waiting for user interaction"));
-	}, timeoutMs);
-	return {
-		signal: input.signal ? AbortSignal.any([input.signal, controller.signal]) : controller.signal,
-		timedOut: () => controller.signal.aborted && !input.signal?.aborted,
-		clear: () => clearTimeout(timer),
-	};
-}