immune-brain 5.3.0 → 5.5.1

package/plugins/immune-brain/dist/docs/reference/code-quality-guard.md

@@ -54,5 +54,7 @@ There are no hard line-count, parameter-count, nesting, complexity, boolean-para
 - `blocking`: a concrete correctness, security, error-state, dependency/API authenticity, test-integrity, or unauthorized-behavior defect.
 - `advisory`: a concrete task-local maintenance risk worth fixing in this change, with an affected path and failure rationale.
 - Pure formatting, naming preference, line count, parameter count, design taste, and hypothetical extensibility produce no finding.
-- A passing Review has no findings. Do not turn low-value suggestions into `rework` merely to preserve them.
+- A `pass` may carry advisory notes: they are archived on the review attestation and never require action. A `rework` contains only blocking findings, at least one; a note that blocks nothing is an advisory finding on a `pass`, never on `rework`. Do not turn low-value suggestions into `rework` merely to preserve them.
+- Every blocking finding states its `evidence.trigger` as a concrete input or state and the observable wrong result it produces. A finding that cannot name the wrong result is not blocking.
+- Judge against the threat model and supported environment declared in the Spec or TaskIntent goal. A defect that needs an attacker, input source, repository format, encoding, or platform outside that declaration is advisory. When nothing is declared, assume inputs come from the repository's own tooling and the user's trusted workspace. `security_boundary` means a security, data-loss, or authority boundary the change actually crosses.
 - Findings identify the affected path and risk. Review reports risks and verification criteria; it does not edit code or generate patches.

package/plugins/immune-brain/dist/docs/reference/immune-brain-config.md

@@ -78,7 +78,47 @@ runner reads none of them. None has a built-in default.
   them each Executor Host uses its own default.
 
 Lane-mode agents only create: they close no tab, stop no session and remove no
-Lane. The full contract is `plugins/immune-brain/dist/imm-run.md#lane-preferences`.
+Lane. The full contract is `plugins/immune-brain/dist/imm-run-batch.md#lane-preferences`.
+
+## Risk Floor
+
+The paths that force a higher task risk are declared by the project in one
+tracked file, `.imm/risk-floor.json`. It is not a preference an Agent reads: the
+Kernel enforces it, so it does not live in `AGENTS.md` or `CLAUDE.md`.
+
+```json
+{
+  "contract": "assurance_kernel/risk_floor/v1",
+  "material": { "paths": ["src/auth"], "changed_only": ["db/migrations"] },
+  "critical": { "paths": ["infra/prod"], "changed_only": [] }
+}
+```
+
+- `paths` raises a task whose `scope_hint` can reach the prefix, including
+  through a glob, or whose changed paths sit beneath it.
+- `changed_only` raises a task only through its changed paths, so a scope that
+  merely names the prefix keeps its declared risk.
+- Every entry is a literal, normalized, project-relative path prefix with
+  forward slashes and no wildcard. Both tiers and both lists are optional.
+- A declared risk is only ever raised, never lowered.
+
+The reader fails closed:
+
+- No file means no floor. Every task keeps the risk its TaskIntent declares.
+- A file that is not valid JSON, has an unknown field or a wrong type, is not a
+  regular file, exceeds 64 KiB, or cannot be read makes every task of the
+  project `critical`.
+- A file with staged, unstaged or untracked changes is treated the same way
+  until it is committed, so an edit made beside a task cannot lower that task's
+  floor.
+- `.imm/risk-floor.json` itself is always `critical`: a task whose scope can
+  reach it, or that changes it, is `critical` whatever the file says.
+
+`imm-kernel inspect --json` reports the prefixes in force as
+`risk.floor_prefixes` and the reason an untrusted declaration was refused as
+`risk.floor_invalid`. A TaskRecord keeps the risk it was enrolled with; changing
+the declaration does not re-grade a task that is already enrolled. ADR 0023
+records the decision.
 
 ## Other Preferences
 

package/plugins/immune-brain/dist/docs/reference/planning-quality-gate.md

@@ -23,7 +23,7 @@ Apply the gate when the task touches one or more of these surfaces:
 - **Technical Design baseline**: keep the Spec as the single design authority and make each Plan Step reference the applicable decision or invariant instead of duplicating design prose.
 - **design-view selection**: for Medium/High risk, select every materially relevant technical-design view from architecture layers, service/component interfaces, data flow, state transitions, and temporal sequence. Record selected views and why omitted views cannot affect the design. Low risk remains concise.
 - **TaskIntent decomposition**: use Technical Design boundaries as one retain/split criterion with outcome, Verification, dependency, risk, rollback, compatibility, and authority. Split a successor TaskIntent only when a service, state-machine owner, migration, independently promotable layer, or sequence dependency needs independent verification, rollback, authorization, or settlement. A TaskIntent should normally change one primary trust-boundary invariant, but traversing several boundaries or updating both sides of one authority chain does not itself require a split. Split independently verifiable, reversible, authorizable, migratable, or settleable trust invariants. Keep multiple trust-boundary changes together only for one atomic security outcome whose split would create an unsafe or unusable intermediate state, and record that rationale in the Spec. Treat this as Planner judgment rather than a schema field or Enrollment counting rule. Do not split merely because the design names several layers, files, or services, and do not revive prose Plan authority. For a multi-TaskIntent Initiative only, require each Slice to state what is observable and verifiable when that Slice alone has landed, and no acceptance may require another unfinished Slice's work to pass; a Slice with no such statement is a horizontal layer slice and is re-cut. Record the exception for a wide mechanical refactor whose blast radius prevents any green vertical slice, with the rationale and a final integrate-and-verify Slice that the batches block.
-- **Mermaid intent**: use Mermaid only when it clarifies structure, sequence, data flow, or state transitions; it is not a universal gate or a second source of truth. Medium/High risk Specs record `**Diagram decision**: required|not_required` and a non-empty `**Diagram reason**:`. A `required` decision must include Mermaid; `not_required` explains why prose is sufficient. Low-risk Specs omit the empty ceremony and record neither field.
+- **Mermaid intent**: use Mermaid only when it clarifies structure, sequence, data flow, or state transitions; it is not a universal gate or a second source of truth. Only a Medium/High risk Spec whose design requires a diagram records `**Diagram decision**: required` and a non-empty `**Diagram reason**:`, and it must include Mermaid. A Spec that needs no diagram records neither field and does not explain the omission. Low-risk Specs omit the empty ceremony and record neither field.
 - **Design Conformance**: before final closure, require Spec-to-implementation evidence. A local implementation mismatch routes to `rework`; a structural or intended design change routes to `replan` through Planner. QA cannot silently approve a design change.
 - **Brainstorm traceability**: ensure every `BR-*` item listed in `Brainstorm manifest` is mapped in `Brainstorm Trace`. Every Spec decision and every acceptance names exactly one source — an upstream `BR-*` ID, repository evidence, or a delegated technical choice — with or without an upstream manifest, and a user-owned decision that names no source is a defect the Planner removes or returns for clarification. A Spec for work with a user-observable change has a `User scenarios` section; each scenario keeps its upstream `BR-SCN-<n>` ID, or on direct entry is confirmed in clarification and recorded as Spec-local `SCN-<n>`, is tagged `automated` with at least one acceptance ID or `manual` with the reason it cannot be automated, and the mapping is one-way. In a multi-TaskIntent Initiative a scenario belongs to exactly one Slice, the one that first makes it observable. `BR-SCN-*` items fall under the existing handoff completeness check, a scenario with no source is a defect, and `no user-visible change` requires a recorded reason.
 - **roadmap information preservation**: for large or multi-phase work, distinguish the Roadmap from the current executable slice, preserve deferred phase goals, open questions, promotion criteria, and candidate next Plans.

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

@@ -12,8 +12,8 @@ This skill adheres to the **[BASELINE.md](BASELINE.md)**.
 `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.
+literal-user entry. A model-entered Planner leaves the session's run entry
+unchanged; a literal `imm-planner` entry ends it.
 An active Assurance projection remains authoritative and is resumed only through
 an explicit `imm-run` entry; Planner entry owns planning only.
 
@@ -91,6 +91,13 @@ resolved wrapper and use the resolved `imm-kernel` wrapper for every Kernel
 command below. Do not assume either bare command is available on shell `PATH`.
 Then route deterministically:
 
+When `intent author` reports `layout_migration_required`, run the resolved
+`imm-kernel migrate --storage-layout` wrapper yourself and retry authoring after
+its `ready` result, without interrupting the user. A pending migration diff is
+committed automatically. On a Git failure, repair the reported precondition
+and retry; `recovery_required`, `migration_blocked_active` and `invalid` remain
+blocking layout conditions.
+
 - an active Kernel claim remains with `imm-run` for foreground Kernel Tool
   coordination, except a Loop-requested revision follows Enrolled Intent Revision
   below to prepare a non-authoritative proposal for that same owner;
@@ -179,8 +186,10 @@ integration assertions; for runtime changes, include the generated Claude bundle
 when it inlines that runtime and the required release changeset. Resolve these
 paths from the build and test references before Enrollment. Record the concrete paths in the Spec's discovery evidence when the work is
 complex; simple TaskIntent-only work records them in `scope_hint`.
-Do not author while a referenced sibling is unresolved. Use the smallest
-coherent module directory for ordinary implementation scope. Keep Kernel,
+Do not author while a referenced sibling is unresolved. Default ordinary
+implementation scope to the smallest coherent module directory: name the
+concrete files it needs, so a sibling the work later needs is a same-directory
+addition the Loop owner submits itself with `revise_intent` (ADR 0021). Keep Kernel,
 authority, migration, secret, and security-sensitive scope exact to the files
 proved necessary by the trace. Scope is closed by reference evidence, not by an
 exhaustive filename guess.
@@ -377,16 +386,18 @@ the strict no-amendment default is unchanged.
 Every acceptance verification descriptor must be a focused, deterministic,
 project-owned check that exercises only its acceptance assertion. Use
 `assurance_kernel/verification_descriptor/v2` and reuse an existing project
-script or host tool through its literal `command`; do not infer a language,
-package manager, or runner. Add `environment.prepare` only when the check needs
+script or host tool through its literal `command`. Write a compound command as
+`executable: "sh"` with `argv: ["-c", "<line>"]`; the exit status of that line
+decides the result. Add `environment.prepare` only when the check needs
 explicit setup, and declare only the generated directories it needs in
 `environment.writable_paths`. Never hide package installation inside an
 acceptance command. For every descriptor, identify whether its executable is
 provided by the QA host or by tracked delivery content, where every dependency
-comes from in the disposable delivery, what explicit setup is required, and
-which declared writable paths that setup or check creates. A dependency found
-only in the Planner's live worktree, including an absolute local `node_modules`
-path, is not delivery provenance. Prefer the highest existing observable behavioral test seam
+comes from, and what explicit setup is required. QA runs in the task's working
+directory after an equality check with the frozen snapshot, so a dependency
+already present in that working directory, such as an installed `node_modules`,
+is valid provenance. `environment.writable_paths` is still parsed and no longer
+restricts where a command may write. Prefer the highest existing observable behavioral test seam
 and the fewest sufficient seams; never use the full test suite, a build, network
 access, or redundant heavyweight checks as acceptance. Cite relevant test prior
 art and explain how the selected seam catches the intended regression. This is
@@ -412,9 +423,10 @@ own duration evidence. These are workflow-quality input patterns, not requests
 to edit the original applications that motivated the audit.
 
 **Environment and prerequisite discipline.** A descriptor that needs a
-prerequisite states its provenance and how it is obtained. Preparation must not
-hide a download, credential use, production write, or system change: authorize
-it explicitly, or redesign the check to avoid it. Require cleanup on failure and
+prerequisite states its provenance and how it is obtained. QA commands run with
+the host process environment, and the Kernel does not judge how dependencies are
+obtained. Preparation must not hide a production write or system change:
+authorize it explicitly, or redesign the check to avoid it. Require cleanup on failure and
 interruption, and restoration of any explicitly authorized setting. An absent
 dependency, a missing simulator, or a preparation failure is a failed check, not
 a pass. Zero matched checks and skipped required checks are failures: a required
@@ -424,6 +436,26 @@ human judgment of motion quality; a descriptor can assert only the automated
 half. Textual presence in a contract string is not proof that a provider obeyed
 it, and structural Enrollment readiness is not proof that a descriptor executed.
 
+**Threat model and supported environment.** Every Spec whose design takes
+external input states one `Threat model and supported environment` line: the
+input's trust level, the adversary if any, and the supported Git object formats,
+encodings, and platforms. `None beyond the repository's own tooling` is a valid
+declaration; an omitted line is not. Acceptance and Review are judged against
+that declaration, so an input or environment it excludes is not an acceptance
+case.
+
+**Enumerated negative cases.** Write acceptance as the concrete negative cases
+the slice must reject, each naming its input and its expected rejection. Never
+write an absolute clause such as `any missing, malformed, or unsafe input cannot
+succeed`: it has no bound a descriptor can exercise and invites unbounded
+Review rounds. Name the cases the slice handles, such as an empty value, a
+truncated record, or a path outside the scope, and pin each in a test.
+
+**Focused descriptors.** A descriptor lists the explicit test files that
+exercise its acceptance, such as `bun test tests/<seam>.test.ts`, never a whole
+suite or an unscoped test command, so an unrelated failure cannot fail an
+acceptance.
+
 ## Core Responsibilities
 
 - **Decomposition**: Convert requirements into one or more TaskIntents. Add a Spec under `docs/specs/` only for complex work. Treat Technical Design as one TaskIntent decomposition dimension alongside outcome, Verification, dependency, risk, rollback, compatibility, and authority.
@@ -434,10 +466,10 @@ it, and structural Enrollment readiness is not proof that a descriptor executed.
 - **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. 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.
+- **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. 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.
 - **TaskIntent decomposition**: Use the selected design boundaries as one retain/split criterion for TaskIntent slices. Keep work in one TaskIntent when the selected views describe one coherent executable slice with shared acceptance, risk treatment, rollback, and authority. Split a successor TaskIntent when a service boundary, state-machine owner, migration/compatibility boundary, independently promotable layer, or sequence dependency needs independent verification, rollback, authorization, or settlement. Do not split merely because the design names several layers, files, or services. Treat trust-boundary changes as the same kind of decomposition evidence: a TaskIntent should normally change one primary trust-boundary invariant, while merely traversing several boundaries or updating both sides of one end-to-end authority chain does not require a split. Split separate trust invariants when they can be independently verified, rolled back, authorized, migrated, or settled. Keep multiple trust-boundary changes together only when they form one atomic security outcome and splitting would create an unsafe or unusable intermediate state; record that reason in the Spec. This is Planner judgment, not a TaskIntent schema field or an Enrollment counting rule. This does not revive prose Plan, Roadmap, or Phase authority. For a multi-TaskIntent Initiative only, each Slice also states what is observable and verifiable when that Slice alone has landed, and no acceptance may require another unfinished Slice's work to pass; the Initiative review table's existing `result` column carries that statement. A Slice with no such result is a horizontal layer slice and is re-cut. Exception: a wide mechanical refactor whose blast radius prevents any green vertical slice may be batched, with the rationale recorded and the batches blocking one final integrate-and-verify Slice.
-- **Mermaid Use**: Mermaid is required only when a medium/high-risk design contains structure, sequence, data flow, or state transition relationships that a diagram materially clarifies. Mermaid is not a universal gate; a diagram supplements adjacent prose and never becomes a second design authority. Medium/High risk Specs record `**Diagram decision**: required|not_required` and a non-empty `**Diagram reason**:`. A `required` decision must have a Mermaid block; `not_required` explains why prose is sufficient. Low-risk Specs omit the empty ceremony and record neither field.
+- **Mermaid Use**: Mermaid is required only when a medium/high-risk design contains structure, sequence, data flow, or state transition relationships that a diagram materially clarifies. Mermaid is not a universal gate; a diagram supplements adjacent prose and never becomes a second design authority. Only a Medium/High risk Spec whose design requires a diagram records `**Diagram decision**: required` and a non-empty `**Diagram reason**:`, and it must have a Mermaid block. A Spec that needs no diagram records neither field and does not explain the omission. Low-risk Specs omit the empty ceremony and record neither field.
 - **Verification**: Every acceptance assertion has a concrete focused descriptor that can fail on the intended regression, and every named invariant has positive, negative, and bound controls at an observable seam. Hypothetical evidence is not execution-ready; a check that matches zero tests, is skipped, or lacks its prerequisite is a failure rather than a pass.
 - **Executable Scope**: `scope_hint` is the mutation envelope, not discovery context. Close references across callers, tests, generated mirrors, and state-machine owners before authoring. Simple tasks are TaskIntent-only. A complex task binds at most one active Spec by content identity; do not add archive paths for freeze, and do not relocate artifacts. Collect all known scope gaps in one revision request; ask again only when new evidence changes the boundary.
 - **Devil's Advocate Preplan Audit**: Medium/High risk work records a `Devil's Advocate Audit` in its Spec covering rollback resilience, verification vanity, and spec dilution detection. Explain recovery from partial implementation, why verification detects the regression, and how accepted requirements remain covered. Simple TaskIntent-only work records outcome, boundary, and concrete verification on the Intent. Low-risk work omits the empty template.
@@ -504,11 +536,19 @@ changes in the proposal. Preserve the prior on-disk sidecars until Kernel applie
 the revision; do not overwrite the enrolled TaskIntent, invoke the new-intent
 author command, or request a second Enrollment.
 
-Return the proposal to the current Loop owner for Kernel `revise_intent` or,
+A same-directory file addition is not a Planner request: the Loop owner submits
+it directly (ADR 0021). Return the proposal to the current Loop owner for Kernel `revise_intent` or,
 when breaking, `approve_breaking_intent_revision` with the complete next intent.
 The native gate is the single user decision for a breaking revision; candidate
 preparation does not apply the revision or authorize expanded execution.
 
+Revision ownership: the Loop owner prepares a scope or acceptance revision in
+the executing session, through Kernel `revise_intent` or
+`approve_breaking_intent_revision`. A Planner session is for a change of goal,
+bound Spec design, or decomposition, and returns any other proposal to the
+executing session instead of editing the task's files. No Host refuses a file
+edit because of the session's entry.
+
 A revision is warranted only when the goal, the `scope_hint`, or a user-visible
 commitment changes. A finding whose defect lies inside the current goal and scope
 is ordinary rework for the Loop, not a revision request: decline to prepare one
@@ -631,6 +671,7 @@ a State Ledger. Keep historical Plan validation strictly read-only.
 ## Red Flags
 
 - Acceptance verification names only hypothetical evidence with no runnable descriptor.
+- A Spec with external input omits its `Threat model and supported environment` line, acceptance uses an absolute any-malformed-input clause instead of enumerated negative cases, or a descriptor runs a whole suite instead of focused test files.
 - An acceptance descriptor names no negative or bound control for its invariant, or its required prerequisite (dependency, simulator, preparation) is absent and still counted as a pass.
 - A required check matches zero tests or is skipped and the run is reported as passing.
 - New work depends on a prose Plan validator, Step activation, or State Ledger.