nobrainer-tech-flow 0.0.0-stage → 2.4.0

package/skills/nobrainer-review/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: nobrainer-review
+description: "Use when the owner says nb-review, deep-audit, deep-code-review, or deep-autoreview; explicitly requests an evidence-gated CLOSEOUT, adversarial BUG_HUNT or RELEASE_GATE; or needs final findings filtered to verified actionable defects. Use nobrainer-build for ordinary implementation and correction work."
+---
+
+# NoBrainer Review
+
+Review the exact requested change, prove real defects against current code, and
+filter out speculative AI noise. This skill owns the final NoBrainer evidence
+gate. Ordinary implementation and correction work belongs to
+`nobrainer-build` and the project's maintained engineering capabilities. This
+skill does not silently implement fixes or expand the product scope.
+Use `nobrainer-skill-doctor` for a portfolio-wide audit of instruction and skill
+systems; this skill remains the owner of the exact change's final evidence gate.
+
+## Choose one mode
+
+- `CLOSEOUT`: default for an implementation diff before handoff or merge.
+- `BUG_HUNT`: adversarial search for reachable defects in an exact module, diff
+  or commit.
+- `RELEASE_GATE`: acceptance, migration, security, build/runtime and rollback
+  evidence for a consequential release.
+
+Do not turn a small diff into a release ceremony. Escalate the mode only when
+the changed boundary, risk or owner request justifies it.
+
+## Start gate
+
+Before reviewing:
+
+1. Resolve repository root, current checkout/commit, dirty state and nearest
+   instructions.
+2. Freeze the scope as exact files, diff, commit, branch/PR base or component.
+   Do not review unrelated existing changes.
+3. Read the goal/spec/acceptance and relevant tests. If none exists, derive only
+   the observable behavior implied by the request and code.
+4. Identify high-risk boundaries: authentication, authorization, money, data
+   loss, migrations, concurrency, external contracts, user-visible state,
+   secrets and irreversible operations.
+5. Default to read-only. A review request does not authorize fixes, commits,
+   pushes, merges or deployments.
+
+If the base, scope or required runtime is inaccessible, state the exact gap. A
+partial review cannot return `CLEAN` for the unavailable surface.
+
+## Pre-read predictions and name/path audit
+
+Before reading implementation details, record two or three falsifiable defect
+hypotheses from the acceptance, changed boundary and risk. Include the trigger
+and expected impact, but do not report a hypothesis as a finding. At the end,
+mark each `HIT`, `MISS` or `UNTESTED` with its evidence. This counters
+confirmation bias without inventing bugs.
+
+Before the verdict, run an explicit `NAME_PATH_AUDIT` for every new or renamed
+symbol, import, export, configuration key and migration reference. Use a literal
+`rg` or project-native checker and retain the command/result or evidence path.
+If the scope has none, record `NOT_APPLICABLE`; a green test does not replace
+this identity check.
+
+## Pass 1: acceptance and backward trace
+
+Read current files from disk, not remembered implementation context. For each
+changed behavior:
+
+- trace from the promised outcome backward through output, state transition,
+  caller, input validation and source data;
+- inspect the full changed function plus its callers/consumers, not only added
+  lines;
+- verify renamed/moved symbols, imports, exports, configuration and migrations
+  against actual references with the recorded `NAME_PATH_AUDIT`;
+- compare public types/contracts and all affected call sites;
+- run concrete values through risky conditions, boundaries and error paths;
+- compare implemented behavior with acceptance, including negative cases and
+  exclusions.
+
+An exit code, generated file, mocked test or worker report is evidence at its
+own layer. It does not prove runtime, production or user usefulness unless that
+layer was exercised. A missing or `NOT_PROVEN` `TEST_SENSITIVITY` keeps a "no
+behavior change" claim open. `STALE` or `CHANGED_DURING_RUN` evidence does not
+prove the current artifact.
+
+## Pass 2: adversarial defect search
+
+Assume at least one defect hypothesis is worth testing, while requiring proof
+before reporting it. Check the classes relevant to the scope:
+
+- inverted/missing conditions, empty/null/zero/large inputs and off-by-one;
+- stale caller, broken import/export, incompatible schema or API contract;
+- lost update, race, retry/idempotence and partial-failure behavior;
+- authorization bypass, unsafe input/output, secret leakage and trust-boundary
+  confusion;
+- rollback gaps, destructive migration, hidden state or duplicate writers;
+- error suppression, false success, timeout treated as completion;
+- tests that assert a fixture or mock but miss the real integration path.
+
+For `BUG_HUNT`, repeat with a different defect class or data-flow direction
+after the first pass. Stop when the bounded scope has been covered and a second
+independent pass produces no new verified candidate; never loop merely to invent
+findings.
+
+## Independent reviewer
+
+Use a native subagent for delegated review. A separate visible conversation
+requires an explicit owner request; `create_thread` is not a subagent fallback.
+If native delegation is unavailable, perform the review in MAIN and report
+the missing independence. A failed review does not authorize another sidebar
+conversation, and a reviewer cannot recursively delegate without express
+authority in its assignment.
+
+Use a second model or native review command when change size, unfamiliar code,
+security, money/data risk or independence justifies the latency. Keep it
+read-only and give it the same frozen scope and acceptance. Prefer the current
+client's maintained review capability; do not ship a custom multi-model harness
+or spawn an automatic reviewer swarm.
+
+Treat every external finding as an unverified candidate. Re-open the cited code,
+trace reachability and reject anything that fails the gate below. Reviewer
+agreement does not replace evidence; disagreement is a prompt to inspect, not a
+vote.
+
+Choose review perspectives from the actual changed boundary and risk: for example
+testing, compatibility, context size or security. Do not automatically run every
+available perspective or require maximum reasoning effort for each one. Record
+which perspectives were selected and why; unchecked relevant risk remains visible.
+
+## Optional pull-request monitoring
+
+When the owner asks to monitor an open pull request, bind every snapshot and action
+to the exact PR head SHA. Check CI, mergeability and published review feedback;
+pending draft reviews are not published feedback and must not be marked handled.
+After a new head appears, discard conclusions for the old SHA and inspect again.
+Retry only a diagnosed transient failure, with a finite recorded budget and a new
+fact that justifies each retry. Persistent, branch-caused or ambiguous failures
+need diagnosis or a stop, not repeated reruns. A green snapshot is progress, not
+merge authorization. Monitoring never grants permission to merge, publish, reply
+to reviewers or perform another externally visible action.
+
+## Finding gate
+
+Report a finding only when all are present:
+
+- severity and exact `file:line`;
+- reachable input/state/sequence that triggers it;
+- observable impact;
+- why current guards/tests do not prevent it;
+- smallest required fix at the correct ownership boundary;
+- regression proof that would fail before and pass after.
+
+Reject style preferences, speculative future risks, unreachable edge cases,
+generic “consider refactoring”, dependency guesses without current primary
+documentation, and broad rewrites unrelated to a proven defect. Do not pad the
+report with low-value observations to look thorough.
+
+## Fix-and-recheck loop
+
+If the owner requested review only, stop after findings. If fixes are also in
+scope:
+
+1. route the smallest accepted fix through `nobrainer-build`;
+2. run the focused regression plus affected baseline tests;
+3. reread the final diff and recheck the original failure path;
+4. rerun the relevant review pass once.
+
+A changed fix invalidates earlier test/review evidence for that path. Do not
+silently self-approve a consequential release; preserve the owner gate.
+
+## Final output
+
+Lead with actionable findings ordered by severity. For each, use the finding
+gate fields and keep the location tight. Then report:
+
+```text
+MODE: CLOSEOUT | BUG_HUNT | RELEASE_GATE
+SCOPE:
+ACCEPTANCE_CHECKED:
+PREDICTIONS: <HIT | MISS | UNTESTED with evidence>
+NAME_PATH_AUDIT: PASS | NOT_APPLICABLE | PARTIAL | BLOCKED; <command/evidence>
+TESTS_AND_RUNTIME:
+INDEPENDENT_REVIEW: USED | NOT_JUSTIFIED | UNAVAILABLE
+REJECTED_CANDIDATES:
+UNCHECKED_SURFACE:
+ROLLBACK_OR_FIX_PATH:
+RESULT: FINDINGS | CLEAN | PARTIAL | BLOCKED
+```
+
+Return `CLEAN` only when the complete frozen scope was inspected, required
+evidence passed and no candidate survived verification. Otherwise say `PARTIAL`
+or `BLOCKED` and name the missing proof.
+
+## Review convergence
+
+Follow the [delivery contract](../nobrainer-tech-flow/references/delivery.md#keep-review-proportional-to-progress)
+for slice-sized review and correction. Repeated amendments do not reset the
+review budget. Keep concrete safety and acceptance blockers open; proceed with
+authorized independent work instead of restarting a whole-plan perfection loop.

package/skills/nobrainer-security/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: nobrainer-security
+description: "Use when the owner says nb-security or security-review, requests a threat model or security review, or when a change crosses authentication, authorization, secrets, untrusted input, sensitive data, dependency, installer, or production trust boundaries."
+---
+
+# NoBrainer Security
+
+Find exploitable security defects and missing controls in one frozen scope, then
+separate proven risk from checklist noise. Default to `READ_ONLY`. This skill
+does not authorize attacking a live target, retrieving secrets, weakening a
+control, changing credentials or implementing a fix.
+
+## Choose one mode
+
+- `THREAT_MODEL`: map assets, actors, entry points, trust boundaries, abuse
+  paths and required controls before a consequential design is frozen.
+- `SECURITY_REVIEW`: trace an exact diff, component, endpoint or data flow and
+  report only reachable, actionable defects.
+- `SUPPLY_CHAIN`: inspect an exact dependency, installer, plugin, script,
+  workflow or external skill for provenance, pinning, permissions and execution
+  risk.
+- `RELEASE_GATE`: verify required security controls, tests, migration safety and
+  rollback evidence before a high-risk release.
+
+If the owner does not name a mode, infer from scope:
+
+- an exact diff, component, endpoint or data flow -> `SECURITY_REVIEW`;
+- a pre-freeze design -> `THREAT_MODEL`;
+- a dependency, installer, plugin or workflow -> `SUPPLY_CHAIN`;
+- pre-release acceptance -> `RELEASE_GATE`.
+
+When modes overlap, choose the primary mode from the requested outcome and state
+that choice; include relevant checks from adjacent modes without expanding scope.
+Ask one focused clarification only if unresolved ambiguity materially changes
+the outcome or authority. Continue independent read-only inspection meanwhile.
+
+Use `nobrainer-review` for a general closeout with no material security boundary.
+Use `nobrainer-rca` when the question is what caused an observed incident.
+
+## Freeze scope and authority
+
+Record:
+
+```text
+MODE:
+SCOPE: <exact diff/files/component/endpoint/artifact>
+ASSETS_AND_DATA:
+TRUST_BOUNDARIES:
+ATTACKER_CAPABILITIES:
+ENVIRONMENT_AND_VERSION:
+WRITE_AUTHORITY: READ_ONLY unless explicitly expanded
+LIVE_TEST_AUTHORITY: NONE unless exact target and actions are approved
+OWNER_GATES:
+```
+
+Resolve actual checkout, dirty state, deployed/runtime distinction, data
+classification and existing controls. Never place credentials, full tokens,
+private payloads or exploit-ready production details in prompts or reports.
+
+Do not test a live target, scan infrastructure, create an account, send a
+payload, access another user's data or install/run untrusted code without exact
+authorization. Prefer local fixtures, static traces and isolated reproductions.
+
+## Trace the trust boundary
+
+Follow each relevant flow from attacker-controlled or externally supplied input
+through validation, canonicalization, authorization, state changes and output.
+For every boundary, establish:
+
+- who controls the input and what identity/account/tenant it represents;
+- parsing, normalization and validation order;
+- authorization decision and its ownership point;
+- storage, logging, cache, queue and retry behavior;
+- sensitive output, side effect and failure mode;
+- current guard and evidence that it runs on the real path.
+
+A plaintext `.env` or credential file in a workspace an agent can read counts
+as secret exposure. Prefer fetching secrets from a secret manager at launch,
+scoped to the process that needs them. Never print a secret value.
+
+Prioritize classes that fit the actual boundary: broken access control, confused
+deputy, injection, SSRF, unsafe path handling, secret exposure, insecure
+deserialization, XSS/CSRF, request smuggling, race/idempotence, unsafe defaults,
+dependency or workflow substitution, and rollback bypass. Do not paste a generic
+vulnerability list into findings.
+
+When a material claim depends on current standards, advisories, dependency
+behavior or vendor guidance, invoke `nobrainer-research` and prefer primary
+sources for the exact version. If required current evidence is inaccessible,
+return `RESEARCH_BLOCKED`; memory is not a security proof.
+
+## Mode-specific evidence
+
+### `THREAT_MODEL`
+
+Produce a compact data-flow/trust-boundary map. For each plausible abuse path,
+state precondition, attacker action, affected asset, existing control, residual
+risk and one testable requirement. Rank by expected loss and reachability, not
+by dramatic wording.
+
+### `SECURITY_REVIEW`
+
+Inspect the full changed function plus callers and consumers. Trace negative
+paths and concrete boundary values. Run the smallest safe test or reproduction
+that would distinguish a defect from a false alarm. A scanner result, model
+finding or dependency label is only a candidate.
+
+### `SUPPLY_CHAIN`
+
+Resolve exact source, version/ref, integrity/pinning, release provenance,
+license, install scripts, hooks, network calls, requested permissions,
+credential access, write targets, update channel and rollback. Review the actual
+artifact before executing it. Prefer temporary isolated use over global or
+persistent installation.
+
+### `RELEASE_GATE`
+
+Map each security acceptance item to current code/config, a focused test,
+runtime or migration evidence, and rollback. Static validation does not prove a
+deployed control. Unknown production state remains unknown.
+
+## Finding and false-positive gate
+
+Report a defect only when all are present:
+
+- severity with impact and realistic preconditions;
+- exact location or trust boundary;
+- attacker-controlled input/state/sequence;
+- reachable code or runtime path;
+- observable confidentiality, integrity or availability impact;
+- why current controls fail;
+- smallest ownership-correct fix contract;
+- regression or verification proof.
+
+Run a false-positive pass against every candidate: seek the guard, caller
+constraint, deployment setting, parser behavior or version fact that would make
+the path unreachable. Reject generic hardening, style preferences, stale
+advisories for another version and speculative chains missing a necessary step.
+
+## Handoff and remediation
+
+Security review ends with evidence and a fix contract. If remediation is in
+scope, route each accepted finding to `nobrainer-build` as a bounded stage with
+a failing regression, allowed write scope and rollback. Then repeat the relevant
+security trace with fresh evidence. Consequential fixes still require an
+independent `nobrainer-review` or release gate; self-authored code is not
+self-approved.
+
+## Final report
+
+```text
+MODE: THREAT_MODEL | SECURITY_REVIEW | SUPPLY_CHAIN | RELEASE_GATE
+SCOPE_AND_AUTHORITY:
+ASSETS_AND_TRUST_BOUNDARIES:
+FINDINGS: <severity, location, path, impact, fix contract, proof>
+REJECTED_CANDIDATES:
+TESTS_AND_SOURCES:
+UNTESTED_OR_INACCESSIBLE_SURFACE:
+OWNER_GATES:
+ROLLBACK_OR_CONTAINMENT:
+RESULT: FINDINGS | CLEAN | PARTIAL | BLOCKED | RESEARCH_BLOCKED
+```
+
+Return `CLEAN` only for the complete frozen scope with required evidence. A
+partial review, inaccessible runtime or unverified external claim cannot be
+green.

package/skills/nobrainer-sessions/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: nobrainer-sessions
+description: "Use when the owner says nb-sessions, nb-multi, session-handoff, session-restart, or nb-session-restart, or asks for visible named reusable multi-session work with exact identity, isolated write scopes, audited handoffs, recovery, or controlled parallelism; do not use for a coherent one-session task."
+---
+
+# NoBrainer Sessions
+
+Operate visible sessions as a small control plane. Human-readable titles make
+the workflow understandable; exact identity and readback make it trustworthy.
+This skill does not invent the project plan, select the ready batch or replace
+implementation skills. `nobrainer-dispatcher` owns scheduling when a queue has
+multiple delegated units.
+
+Describe the outcome, success criteria and verification, let one project-level
+session prepare bounded task prompts, and bring child results back for review.
+Exact identity, write ownership, stop gates and independent receive-audit are
+required; a convenient parent-child topology is not itself a safety contract.
+
+For ordinary native subagents, use the compact packet, returned IDs, observable
+completion and artifact review in nobrainer-tech-flow
+[team execution](../nobrainer-tech-flow/references/delivery.md#coordinated-team-execution).
+No durable registry or new visible task is required. Use this full protocol for
+durable or explicitly visible sessions.
+
+Read [references/protocol.md](references/protocol.md) before setup, dispatch, or
+RECEIVE_AUDIT.
+
+For project work, use the default isolated-worktree lifecycle in
+[references/worktrees.md](../nobrainer-tech-flow/references/worktrees.md):
+discover and fetch the remote default branch before creating a task worktree,
+preserve the original checkout, and retain the worktree for owner review until
+the exact PR merge is verified. After that gate, remove only the clean,
+task-owned worktree without force and verify its removal. Follow an explicit
+owner instruction to use another checkout or lifecycle.
+
+## Choose the smallest topology
+
+Default to one visible session named `<repo> | MAIN`.
+One visible coordinator can own many bounded native workers; this topology does
+not limit useful native concurrency under nobrainer-tech-flow's team execution contract.
+Delegated work uses native subagents inside the current task. Creating a visible
+conversation (for example with `create_thread`) requires an explicit owner
+request for that conversation or an explicitly authorized MAIN restart.
+Delegation, independent review, retries, context pressure and a continuing goal
+do not grant that permission. If native subagents or the requested model are
+unavailable, continue in MAIN and report the limitation; never substitute a
+visible task. Workers cannot delegate further or create successors unless their
+assignment expressly authorizes it.
+Reuse an authorized worker for follow-up corrections; do not create a visible
+conversation per review round.
+
+Use stable role titles such as `<repo> | QA` or `<repo> | RESEARCH` when the
+responsibility persists. Use `<repo> | <TASK_ID>` for a bounded disposable work
+unit. Never treat a title as identity and never create a worker merely to make
+the topology look multi-agent.
+
+## Capability and identity gate
+
+Discover the current harness capabilities for listing, creating, renaming,
+sending, reading, and waiting on visible sessions. Verify each mutation by
+readback. If exact session transport is unavailable, remain in MAIN and report
+the degraded mode; hidden workers are not equivalent to requested visible
+sessions.
+
+Before reuse or dispatch, bind the target in the session registry:
+
+- `THREAD_ID`, `HOST_ID`, harness and current status;
+- repository, `CHECKOUT` or worktree, branch/base/HEAD;
+- role, task, write scope and isolation;
+- active-turn state and last successful readback.
+
+Unknown, ambiguous, stale, or title-only identity is a stop condition. A
+submission is not delivery; record `SENT` only with transport readback.
+
+## Bounded turns and runtime release
+
+A goal may span turns, but each turn/session is bounded. Run
+`SESSION_HEALTH_GATE` at `START`, `AFTER_COMPACTION`, `MATERIAL_TRANSITION` and
+`BEFORE_CLOSEOUT` using host/configured signals such as turn age, history size,
+compactions, cost/tokens and owned workers. `UNKNOWN` or `UNSUPPORTED` lowers
+runtime proof; optional telemetry does not block safe work. An unmeasurable
+explicitly required hard budget blocks work relying on that guarantee.
+`WARNING` checkpoints the goal/TODO, stops optional workers and
+large new units, and permits only the safe current unit to continue. A hard
+limit persists the canonical Markdown goal, writes a compact handoff, verifies
+no write is in flight, then selects verified host clear or `END_TURN`, or the
+authorized [session-restart protocol](references/session-restart.md). Standing
+restart consent covers later rotations in its recorded scope; installation alone
+is not consent. Resume by reading that file and
+reconciling identity and checkout; stale transcript or native-goal text cannot
+override it.
+`task_complete` is not `RUNTIME_RELEASE`; require owned-worker readback where
+the host supports it.
+
+## Startup care
+
+Flow invokes [automatic start and observation](references/session-restart.md#automatic-start-and-observation)
+on explicit Flow entry for resumable, long or delegated work; the quick path skips it.
+Name the session immediately from verified creation metadata; assess current
+context and full necessary startup inputs. A health restart does not require an
+economic saving, but still requires separately recorded owner consent, progress
+and safe takeover.
+
+## Modes
+
+- `session-restart` / `nb-session-restart`: evaluate long-run restart benefit,
+  persist a compact checkpoint, create a fresh MAIN through supported native
+  transport, verify takeover, then archive the exact retired source if authorized.
+  Read [references/session-restart.md](references/session-restart.md); no fixed
+  timer, forked full history or per-rotation approval inside standing consent.
+
+- `setup`: reconcile an existing registry, name MAIN, and create only the next
+  justified session. Do not pre-create a swarm.
+- `delegate`: send one already-selected, self-contained work unit to one exact
+  session.
+- `RECEIVE_AUDIT`: independently verify one report before any state advance.
+- `recover`: resume from canonical state and evidence without repeating the
+  same failed attempt.
+- `handoff`: create a compact owner-requested continuation snapshot for a fresh
+  MAIN session, including live state, exact unfinished work, evidence and the
+  first safe action; do not pretend that writing the snapshot created or
+  delivered a session.
+
+## Writer and lease contract
+
+MAIN normally owns sequential workflow state. A worker owns only its bounded
+implementation scope and report. Never let two writers mutate the same state or
+checkout concurrently.
+
+Use the project's authoritative lease mechanism when one exists. A Markdown
+`LEASE` is advisory coordination, not atomic locking. `FENCING_EPOCH` is valid
+only when an authoritative control plane allocates a monotonically increasing
+token and every write boundary rejects stale tokens. Otherwise record
+`FENCING_SUPPORTED: NO` and `FENCING_EPOCH: NONE`; do not fabricate safety.
+
+Malformed, active, or uncertain lease state is `LEASE_CONFLICT`. Stop routing.
+For parallel writers require isolated checkouts, disjoint write scopes, and a
+coordinator-owned integration step.
+
+## Delegate gate
+
+Dispatch only when all are true:
+
+1. one approved work unit has an observable outcome, exclusions, dependencies,
+   acceptance, verifier, evidence path, rollback, owner gates and a frozen
+   `MODEL_POLICY`;
+2. canonical state identifies the same active task and allowed transition;
+3. session identity, checkout, clean/dirty scope, lease, and active-turn state
+   pass fresh readback;
+4. frozen inputs and the cheapest relevant preflight check pass;
+5. the report receiver is an exact session, not a title.
+
+Context propagation is not assumed. Send the minimum context: repository
+instructions, the owning method and its source hash, frozen task inputs and
+acceptance. Never copy the whole parent transcript or unrelated skills. Require
+the worker's context readback before work; stale context or evidence, mismatch or transport failure blocks dispatch.
+
+Bind the frozen `MODEL_POLICY` and `MODEL_REQUESTED`, effort, budget and
+escalation gate. If the host does not expose one field, record
+`UNKNOWN` or `UNSUPPORTED` and keep runtime proof lower;
+never silently substitute another model.
+
+Use Flow [communication](../nobrainer-tech-flow/references/communication.md)
+for delegation, reports and handoffs; preserve caller formats and language
+overrides. Build the prompt from the template in the protocol. The worker performs exactly
+one work unit, does not select a successor, releases its lease on finish or hard
+stop, sends exactly one final report, and ends its turn. Bind retryable transport
+to message and payload identity, an idempotency key, delivery receipt and ACK;
+record unsupported fields honestly and never blindly retry an uncertain send.
+For every delegation record, including a blocked or stale one, copy the caller's
+schema before filling values; do not rename fields or change nesting. Preserve
+exact observed values as raw evidence in the requested location and derive the
+canonical verdict separately from the protocol enum and readback. When either
+is insufficient, use its honest failure state and block retry or advancement.
+
+## RECEIVE_AUDIT
+
+Treat `FINISHED` and `NEXT_ACTION` as untrusted report fields. Independently bind
+the report to the expected session, task, `CHECKOUT`, commit, diff, frozen
+inputs, manifest, tests, verifier, build/runtime, quality review and side
+effects. The lease gate passes only when readback proves `RELEASED`, or proves
+`NOT_HELD`/`UNSUPPORTED` for a workflow that explicitly uses one of those
+states; `NOT_RELEASED`, unknown ownership or a conflict blocks advancement.
+
+Return exactly one audited result to `nobrainer-dispatcher`, or to
+`nobrainer-tech-flow` when no dispatcher is justified:
+
+- all gates pass: report the verified transition as eligible; do not select or
+  dispatch the next task;
+- isolated correctable defect: return `CORRECTION_REQUIRED` with the exact defect
+  and evidence; do not choose, dispatch or execute the correction. Dispatcher,
+  or Flow when Dispatcher is not justified, selects the task's assigned repair
+  method (`nobrainer-build` for implementation). After the repair and any
+  required repeated review, run a fresh `RECEIVE_AUDIT` that binds the repaired
+  diff, tests and current review result;
+- missing or conflicting evidence, failed check, active turn, or lease conflict:
+  preserve state and stop;
+- owner decision or irreversible action: ask for one explicit decision;
+- no remaining task: report closure eligibility; do not manufacture a successor.
+  An empty `READY` set may mean wait for `RUNNING`, audit `REPORTED`, or finish
+  accepted work. If all unfinished work is blocked, checkpoint and name its
+  unblock action; use `OWNER_DECISION_REQUIRED` only for an actual owner decision.
+
+Retries require new evidence or a changed condition. Preserve a stable blocker
+fingerprint, attempt number, recovery owner, retry budget, checkpoint, rollback,
+and one concrete remediation action.
+
+## Final response
+
+Report topology, exact identities created or reused, canonical state change,
+transport readback, audit result, evidence, uncertainty, recovery/rollback, and
+one next action. Never claim session creation, rename, dispatch, receipt, or
+completion without readback from the responsible system.
+
+## Optional bounded command
+
+For a non-interactive command that needs enforced wall-time/output limits, use
+the inspected [bundled runner](scripts/run_bounded.py) when Python 3.11+ and POSIX
+are available. Pass explicit argv, finite `--wall-seconds`, `--max-output-bytes`
+and a fresh `--receipt`; no shell or automatic retries. It controls only its
+child process group, not model context, cost, escaped sessions or other tools.
+A receipt is process evidence, never task acceptance; missing proof is not success.
+To bind a check to the files it ran against, see the [evidence receipt](references/evidence-receipt.md).

package/skills/nobrainer-sessions/references/evidence-receipt.md

@@ -0,0 +1,55 @@
+# Evidence receipt
+
+Optional local tool. Sessions owns the command capture; Review owns acceptance.
+[`evidence_receipt.py`](../scripts/evidence_receipt.py) runs one command through
+the bounded runner and records a declared input scope before and after it.
+`check` is read-only and never re-executes a command from the receipt.
+
+## Use
+
+```bash
+python3 skills/nobrainer-sessions/scripts/evidence_receipt.py capture \
+  --root ./project --input src --input tests \
+  --receipt ./check-evidence.json --label 'unit tests' \
+  --wall-seconds 30 --max-output-bytes 65536 -- \
+  python3 -B -m unittest discover -s tests -v
+
+python3 skills/nobrainer-sessions/scripts/evidence_receipt.py check \
+  --root ./project --receipt ./check-evidence.json --format markdown
+```
+
+The caller supplies the root on every check. Inputs are relative files or
+directories without links or special files. The receipt must be new and outside
+every input. Keep caches and outputs outside the scope (`-B` avoids bytecode).
+An error after the command started can mean it already ran: reconcile effects
+before retrying.
+
+## Statuses
+
+- `CURRENT`: the before, after and current snapshots agree.
+- `STALE`: the selected scope differs now.
+- `CHANGED_DURING_RUN`: before and after differ, so no single source version
+  was established, even if the command returned zero.
+- `UNAVAILABLE`: the scope or the after snapshot could not be read safely.
+
+## Exit codes
+
+Capture keeps the command's nonzero result; a zero exit with non-current
+inputs or an incomplete run (for example output cut short) returns 1. Check
+returns 0 only for current inputs and a completed command, 1 for stale,
+unavailable, failed or incomplete evidence, and 2 for invalid input or an
+unsupported operation.
+
+## Limits
+
+- Python 3.11+ and POSIX only. Windows capture and check are unsupported.
+- Unsigned: anyone who can rewrite the receipt and the files can forge a
+  consistent record. Hashes do not prove a trustworthy observer or a sufficient test.
+- Output is stored as base64 with hashes, which is not redaction. Do not capture
+  commands that can emit secrets; inspect a copy before sharing.
+- Caps: 64 selectors, 1,000 entries, 64 MiB input, 256 KiB output, 4 MiB receipt.
+- A change and revert between snapshots can go undetected; the bounded runner is not a sandbox.
+
+A receipt is evidence, not acceptance. Test counts stay `UNKNOWN`, task acceptance
+`NOT_EVALUATED`, human approval `NOT_RECORDED`, authenticity `NOT_VERIFIED`.
+STALE or CHANGED_DURING_RUN evidence does not prove the current artifact.