immune-brain 2.8.2

package/plugins/immune-brain/bin/imm-pr-diag

@@ -0,0 +1,230 @@
+#!/bin/sh
+set -eu
+
+# ─────────────────────────────────────────────────────────────────────────────
+# imm-pr-diag — Collect PR diagnostic data and emit a single JSON report
+# ─────────────────────────────────────────────────────────────────────────────
+# This is a STANDALONE script. It does NOT depend on Python or
+# immune_brain_runtime.py.  It requires only `gh` (GitHub CLI) and `jq`.
+# ─────────────────────────────────────────────────────────────────────────────
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") <PR>
+
+Collect diagnostic data for a GitHub pull request and output a single JSON
+object to stdout.
+
+Arguments:
+  <PR>    Pull request identifier — a number, URL, or branch name.
+
+Options:
+  -h, --help    Show this help message and exit.
+
+Prerequisites:
+  • gh   — GitHub CLI (https://cli.github.com)
+  • jq   — Command-line JSON processor (https://stedolan.github.io/jq)
+
+Output:
+  A JSON object containing pr_target, checks, reviews, review_threads,
+  conflicts, and blocker_summary fields.
+EOF
+  exit 0
+}
+
+# ── Argument handling ────────────────────────────────────────────────────────
+
+if [ $# -eq 0 ]; then
+  usage
+fi
+
+case "${1:-}" in
+  -h|--help) usage ;;
+esac
+
+PR="$1"
+
+# ── Dependency checks ───────────────────────────────────────────────────────
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "error: 'gh' (GitHub CLI) is required but not found in PATH." >&2
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "error: 'jq' is required but not found in PATH." >&2
+  exit 1
+fi
+
+# ── Fetch PR metadata ───────────────────────────────────────────────────────
+
+PR_JSON=$(gh pr view "$PR" --json number,headRefName,baseRefName,url,mergeable,mergeStateStatus,files 2>&1) || {
+  echo "error: failed to fetch PR data for '${PR}'. Is this a valid PR identifier?" >&2
+  echo "       gh output: ${PR_JSON}" >&2
+  exit 1
+}
+
+PR_NUMBER=$(printf '%s\n' "$PR_JSON" | jq -r '.number')
+
+# ── Fetch CI checks ─────────────────────────────────────────────────────────
+
+CHECKS_STATUS=0
+CHECKS_JSON=$(gh pr checks "$PR" --json name,state,bucket,link,workflow 2>&1) || CHECKS_STATUS=$?
+if [ "$CHECKS_STATUS" -ne 0 ] && [ "$CHECKS_STATUS" -ne 8 ]; then
+  echo "error: failed to fetch PR checks for '${PR}'." >&2
+  echo "       gh output: ${CHECKS_JSON}" >&2
+  exit 1
+fi
+
+# ── Fetch reviews ───────────────────────────────────────────────────────────
+
+REVIEWS_JSON=$(gh pr view "$PR" --json reviews --jq '.reviews' 2>/dev/null) || REVIEWS_JSON="[]"
+
+# ── Fetch review threads (comments) ─────────────────────────────────────────
+
+REPO_FULL_NAME=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>&1) || {
+  echo "error: failed to determine repository name for review thread lookup." >&2
+  echo "       gh output: ${REPO_FULL_NAME}" >&2
+  exit 1
+}
+REPO_OWNER=${REPO_FULL_NAME%/*}
+REPO_NAME=${REPO_FULL_NAME#*/}
+THREADS_PAGES=$(gh api graphql --paginate --slurp \
+  -f owner="$REPO_OWNER" \
+  -f repo="$REPO_NAME" \
+  -F pr="$PR_NUMBER" \
+  -f query='
+query($owner: String!, $repo: String!, $pr: Int!, $endCursor: String) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      reviewThreads(first: 100, after: $endCursor) {
+        nodes {
+          path
+          line
+          startLine
+          isResolved
+          comments(first: 1) {
+            nodes {
+              body
+            }
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+}
+' 2>&1) || {
+  echo "error: failed to fetch PR review threads for '${PR}'." >&2
+  echo "       gh output: ${THREADS_PAGES}" >&2
+  exit 1
+}
+THREADS_JSON=$(printf '%s\n' "$THREADS_PAGES" | jq '[.[].data.repository.pullRequest.reviewThreads.nodes[]?]')
+
+# ── Assemble the final JSON ─────────────────────────────────────────────────
+
+jq -n \
+  --argjson pr "$PR_JSON" \
+  --argjson checks "$CHECKS_JSON" \
+  --argjson reviews "$REVIEWS_JSON" \
+  --argjson threads "$THREADS_JSON" \
+'
+# ── pr_target ──────────────────────────────────────────────────────────────
+($pr.mergeable // "UNKNOWN") as $mergeable |
+
+{
+  pr_target: {
+    number:    $pr.number,
+    branch:    $pr.headRefName,
+    base:      $pr.baseRefName,
+    url:       $pr.url,
+    mergeable: $mergeable
+  },
+
+# ── checks ─────────────────────────────────────────────────────────────────
+  checks: [
+    $checks[] | {
+      name:       .name,
+      status:     .state,
+      bucket:     (.bucket // null),
+      conclusion: (.bucket // .state),
+      url:        (.link // null),
+      workflow:   (.workflow // null)
+    }
+  ],
+
+# ── reviews (deduplicate to latest per author) ─────────────────────────────
+  reviews: [
+    ($reviews
+      | group_by(.author.login)
+      | map(sort_by(.submittedAt) | last)
+      | .[]
+    ) | {
+      author: .author.login,
+      state:  .state,
+      body:   (.body // "")
+    }
+  ],
+
+# ── review_threads ─────────────────────────────────────────────────────────
+  review_threads: [
+    $threads[] | {
+      path:       .path,
+      line:       (.line // .startLine // null),
+      body:       (.comments.nodes[0].body // .comments[0].body // ""),
+      isResolved: .isResolved
+    }
+  ],
+
+# ── conflicts ──────────────────────────────────────────────────────────────
+  conflicts: (
+    ($mergeable == "CONFLICTING") as $has |
+    {
+      has_conflicts:    $has,
+      conflicting_files_status: (
+        if $has then
+          "unknown"
+        else
+          "none"
+        end
+      ),
+      conflicting_files: (
+        if $has then
+          []
+        else
+          []
+        end
+      )
+    }
+  ),
+
+# ── blocker_summary (computed) ─────────────────────────────────────────────
+  blocker_summary: (
+    # Failing checks
+    [ $checks[] | select(.bucket == "fail" or .state == "FAILURE" or .state == "ACTION_REQUIRED") | .name ] as $failing |
+
+    # Unresolved review threads
+    [ $threads[] | select(.isResolved == false) ] | length as $pending |
+
+    # Merge conflicts
+    ($mergeable == "CONFLICTING") as $has_conflicts |
+
+    # Categories
+    (
+      (if ($failing | length) > 0     then ["check_repair"]    else [] end) +
+      (if $pending > 0                then ["feedback_repair"]  else [] end) +
+      (if $has_conflicts              then ["conflict_repair"]  else [] end)
+    ) as $cats |
+
+    {
+      failing_checks:       $failing,
+      pending_feedback_count: $pending,
+      has_merge_conflicts:  $has_conflicts,
+      blocker_categories:   $cats
+    }
+  )
+}
+'

package/plugins/immune-brain/bin/imm-retire-stale-wrapper

@@ -0,0 +1,4 @@
+#!/bin/sh
+set -eu
+PLUGIN_ROOT=$(cd "$(dirname "$0")/.." && pwd -P)
+exec bun "$PLUGIN_ROOT/runtime/v4_runtime.ts" cli imm-retire-stale-wrapper "$@"

package/plugins/immune-brain/bin/imm-retired

@@ -0,0 +1,4 @@
+#!/bin/sh
+set -eu
+PLUGIN_ROOT=$(cd "$(dirname "$0")/.." && pwd -P)
+exec bun "$PLUGIN_ROOT/runtime/v4_runtime.ts" cli imm-work "$@"

package/plugins/immune-brain/bin/imm-tracker

@@ -0,0 +1,4 @@
+#!/bin/sh
+set -eu
+PLUGIN_ROOT=$(cd "$(dirname "$0")/.." && pwd -P)
+exec bun "$PLUGIN_ROOT/runtime/v4_runtime.ts" cli imm-tracker "$@"

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

@@ -0,0 +1,138 @@
+# Immune-Brain Skill Baseline
+
+## Shared Guards
+
+- Load detailed workflow text from `dist/` only on invocation.
+- Ask only when missing information changes outcome or risk.
+- Keep edits inside the user-requested Direct scope or the active Managed step boundary.
+- Record reproducible evidence before reporting closure.
+- Use shallow discovery first.
+- Lead with conclusion, evidence, and Next Action.
+- Advisory roles do not implement; Managed execution roles do not close QA.
+- An explicit Managed Skill entry stops host-native mutation and routes scope changes to `imm-planner`; Managed execution remains inside its accepted boundary.
+
+## Workflow Activation
+
+Ordinary host input stays host-native and does not run natural-language Managed
+routing. A new Managed workflow starts only from explicit `imm-brainstorm`,
+`imm-planner`, or `imm-loop` Skill entry.
+
+1. **Continue an existing Managed owner explicitly**: an active Assurance
+   projection, TaskIntent, TaskRecord, reviewer `follow_up`, or other nonterminal
+   Managed owner remains authoritative; the user resumes it with `imm-loop`.
+2. **Start explicitly**: the selected Immune-Brain Skill owns its planning or
+   coordination work. It creates only requested artifacts and their required
+   parent directories; it does not install project-wide contract files.
+3. **Preserve authority**: Planner output is a candidate for later literal-user
+   Enrollment, and Fast-Track preserves TaskIntent scope, Enrollment, QA,
+   Review, authorization, and completion boundaries.
+
+Do not inspect or mutate Immune-Brain state merely because ordinary host input
+contains a mutation verb. File count, local verifier count, ordinary retries,
+read-only advisors, and unrelated dirty files do not change these boundaries.
+
+### Non-Mutating Host Path
+
+Read-only and explicit no-modification requests stay with the ordinary host
+agent. This path creates no Spec, Plan, TaskIntent, TaskRecord, State Ledger,
+acceptance evidence, QA job, mandatory Review job, HANDOFF update, or
+Compounder state. It may explain, inspect, or review without Enrollment.
+
+### Managed Execution And Completion
+
+The matching Managed owner drives execution, evidence, QA, Review, and
+completion without switching to a non-authoritative path. Scope expansion
+returns to `imm-planner`; an enrolled task resumes through `imm-loop` from the
+current Assurance projection. Do not create or mutate workflow state while
+classifying a non-mutating request.
+
+Stage only explicit task-owned paths. Never use `git add .` or `git add -A` in a dirty worktree.
+
+### Host Confirmation Boundary
+
+Require exact host confirmation only for privileged effects:
+
+- publish, release, deployment, or remote-system mutation;
+- destructive or irreversible operations and Git history rewrite;
+- credential, secret, permission, or access-control changes;
+- authority discard, task stop, breaking intent revision, or risk/policy
+  override; and
+- external writes whose target or impact cannot be safely reversed locally.
+
+Routine Managed enrollment uses one host confirmation bound to the TaskIntent content hash at the Planner's final `ctx.ui.custom` gate. 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.
+
+## Parallel Read-Only Dispatch
+
+State mutations, step activations, QA decisions, and plan switches remain
+strictly sequential. Read-only work — repo exploration, advisory review,
+host probing, planner research — may be dispatched in parallel.
+
+Parallel dispatch is restricted by capability, not by a closed Skill list. Every
+child delegation packet must enforce read-only advisory behavior: no file edits,
+Plan writes, workflow-state mutation, or QA closure. Eligible examples include
+Brainstorm and Planner research children, Domain Mappers and architecture
+explorers, advisory reviewers, and provider-native read-only explorers such as
+Pi `Explore`. Executor, QA, Compounder, owning Planner, and test-fixer children
+always run sequentially.
+
+## Output Language Policy
+
+- Honor the configured language for user-facing replies and short summaries.
+- Persisted Immune-Brain documents default to English, including `HANDOFF.md`,
+  `docs/brainstorms/`, `docs/specs/`, `docs/plans/`, and `docs/solutions/`.
+- A reply-language instruction such as "use Chinese when replying" does not
+  change document language. Change persisted document language only when the
+  current user request, project instructions such as `AGENTS.md`, or host/user
+  preference contains an explicit document-language instruction.
+- Reply language precedence is: current user instruction, then project
+  instructions such as `AGENTS.md`, then host or user-level preference, then
+  the repo-wide default output contract. Document language precedence is:
+  current explicit document-language instruction, then project explicit
+  document-language instruction, then host or user-level explicit
+  document-language preference, then English.
+- Do not translate or rename machine contracts: schema fields, enum values,
+  CLI flags, JSON keys, file paths, tool names, API names,
+  and code identifiers stay literal.
+- Preserve `CONTEXT.md` canonical terms such as `Step`, `Plan`, `Spec`,
+  `Skill`, `Brainstorm`, `Executor`, `QA`, `Compounder`, `Learning`, and `ADR`;
+  add local-language explanations around them when helpful.
+
+## Success Criteria
+
+- Direct work closes only under the Direct completion contract above.
+- A Managed Step is ready to execute only when the target result, boundary, and
+  verification path are clear enough to avoid speculative edits.
+- A Managed Step is closable only when execution evidence proves the recorded
+  verification path and the active boundary still matches the Plan.
+- Managed scope changes, missing evidence, or structural mismatch return to
+  `imm-planner` instead of being hidden inside execution or QA.
+
+## Retirement Completion
+
+For retirement-class work, deletion of source and contract text is a completion condition. A retirement is not complete until the source and its contract text are deleted.
+
+An absence test is transitional scaffolding proving an in-progress deletion rather than a substitute for one. An absence test is transitional evidence of an in-progress deletion and may not stand in place of one. Distinguish an absence assertion that guards something already gone, which is durable and correct, from one that stands in for a deletion still owed, which is a promise recorded as if it were a result.
+
+## Collaboration Posture
+
+- When to ask: ask only when missing information would change the outcome,
+  authority boundary, or risk profile.
+- When to proceed: proceed on explicit, low-risk assumptions when the next
+  evidence path can validate or reject them.
+- Keep uncertainty visible in evidence, notes, or Next Action instead of
+  silently widening scope.
+
+## Hub skill anatomy
+
+The public Skills `imm-brainstorm`, `imm-planner`, and `imm-loop` carry the
+repo's user-facing workflow authority. Execution, QA, review, repair,
+exploration, and learning are internal runtime roles dispatched by Loop through
+packaged role prompts; they are not additional public Skills. Keep explicit
+`Rationalizations`, `Red Flags`, and Verification guidance grounded in
+Immune-Brain commands and `.imm` state.
+
+## Shallow Discovery
+
+Prefer shallow discovery before full-file reads. Start with file lists,
+`rg` hits, symbol/signature scans, and targeted line ranges; read whole files
+only when the narrower evidence path cannot answer the active Step question.

package/plugins/immune-brain/dist/docs/reference/HANDOFF-template.md

@@ -0,0 +1,122 @@
+# HANDOFF.md Template
+
+Reference template for the `HANDOFF.md` file at project root.
+
+Ownership is split. Everything between the `GENERATED` markers is derived from
+the State Ledger and rewritten by the runtime on every `imm-review pass`; edits
+there are lost on the next pass. Everything outside the markers is narrative the
+runtime cannot derive, and the runtime preserves it untouched. A `HANDOFF.md`
+without markers is adopted on the first pass: the block is inserted below the
+title and existing content is kept.
+
+## Standard sections
+
+```markdown
+# Immune-Brain Handoff
+
+<!-- GENERATED: immune-brain-handoff-state -->
+## Current state
+
+- Plan: `<plan path>`
+- Summary: <one-line plan summary>
+
+### Completed steps
+
+- <Step ID>: <Result line>
+
+### Active step
+
+- <Step ID>: <Result line>
+
+### Known blockers
+
+- <Step ID>: <failure exit>
+<!-- END GENERATED: immune-brain-handoff-state -->
+
+## Decisions this session
+
+<judgement calls a reader would not recover from the Ledger>
+
+## Files in play
+
+<the few files that matter most on reload, highest priority first>
+```
+
+## Compaction Handoff section
+
+Appended when compaction is imminent or at each QA pass. Fields match spec R2.
+
+```markdown
+## Compaction Handoff
+
+### Active plan
+<relative plan path>
+
+### Active step
+Step <N> (<Step ID>): <Result line>
+
+### Files in play (compaction priority)
+1. <path> — <reason: actively editing / test target / config>
+2. <path> — <reason>
+(max 5; these are the files the agent should reload first post-compact)
+
+### Uncommitted work
+<N> files modified, <M> untracked
+Top paths: <path1>, <path2>
+
+### Decisions this session
+- <decision 1>
+- <decision 2>
+(not a substitute for ADR/solutions; temporary session context)
+
+### Next boundary
+<imm-work | imm-qa | imm-executor> — <one-line reason>
+```
+
+## Successor decision (non-authoritative mirror)
+
+Include this section only when the current Plan declares a non-terminal successor. Copy the values from a fresh runtime checkpoint; do not infer them from filenames or prose.
+
+```markdown
+## Successor decision (non-authoritative mirror)
+
+- Current Plan: <canonical relative Plan path>
+- Current Phase: <stable Phase ID>
+- Closure/review state: <closed and reviewed | unresolved boundary>
+- Successor candidate: <stable Phase ID>
+- Successor preconditions: <declared preconditions>
+- Expected Ledger revision: <opaque lowercase revision>
+- Next user decision: <create and validate | explicitly approve a validated successor Plan>
+- Deferred scope: <remaining Roadmap scope or explicit reference>
+```
+
+This mirror may be stale. The State Ledger plus a fresh validated Plan read remains authoritative, and HANDOFF must never be parsed as transition authority. A placeholder successor path is not executable approval.
+
+## Machine-readable mirror (retired)
+
+A machine-readable mirror of these fields was once specified for `imm-dehydrate`
+to store under `logic_state.compaction_handoff` in `.imm/memory/state.json`. That
+whole path is retired: the command is gone, `state.json` is deleted, and spec R3
+is withdrawn. `HANDOFF.md` is the only place the compaction fields live, which is
+why the narrative sections below the generated block matter. The shape below is
+kept for historical reference only.
+
+```json
+{
+  "compaction_handoff": {
+    "active_plan": "<relative plan path>",
+    "active_step_id": "<Step ID>",
+    "active_step_result": "<Result line>",
+    "priority_files": ["<path1>", "<path2>"],
+    "uncommitted_summary": "<N files modified, M untracked>",
+    "session_decisions": ["<decision 1>"],
+    "next_boundary": "<skill name>"
+  }
+}
+```
+
+## Notes
+
+- `imm-work` owns HANDOFF.md writes (boundary exception documented in skill)
+- `.imm/memory/` is the source of truth; HANDOFF.md is a convenience artifact
+- Priority files list is advisory (max 5) and exists only to make Pi session continuation faster

package/plugins/immune-brain/dist/docs/reference/design-contract-audit-rubric.md

@@ -0,0 +1,149 @@
+# Design Contract Audit Rubric
+
+Use this rubric to audit a project's `DESIGN.md` for completeness, internal
+consistency, accessibility specification, and machine-readability. The rubric
+uses Vercel Geist (`design.md` / `design.dark.md`) as a structural reference for
+what a well-formed, agent-consumable design contract contains — not as a required
+style or aesthetic to adopt.
+
+This document is the **audit side**: it evaluates whether a `DESIGN.md` is itself
+a good contract. The separate `design-contract-review-checklist.md` is the
+**consumer side**: it tells reviewers to treat `DESIGN.md` as the authority when
+reviewing rendered UI.
+
+## Scope
+
+- This rubric is read-only and advisory. It does not write, scaffold, or modify
+  any project file.
+- It checks whether the project's **own declared choices** are complete and
+  machine-consumable. It does not require a project to adopt Geist's specific
+  values.
+- Geist is a structural reference for which dimensions a design contract should
+  cover and how tokens should be expressed — never a style authority that
+  overrides project decisions.
+
+## Audit Dimensions
+
+### 1. Structural Coverage
+
+Does the `DESIGN.md` cover the core sections an implementation agent needs?
+Check for the presence of:
+
+- Overview / design philosophy
+- Colors (semantic palette)
+- Typography (font families, sizes, weights, line-heights)
+- Layout and spacing
+- Elevation and depth
+- Motion and animation
+- Shapes and radii
+- Components (buttons, inputs, common controls)
+- Voice and content guidelines
+- Do's and Don'ts or usage rules
+
+A missing section is a gap finding; it is not a failure if the project
+intentionally omits a section and documents why.
+
+### 2. Color-Scale Semantics
+
+- Are color tokens organized by **intent** (background, border, text, accent,
+  state) rather than only by raw lightness?
+- Does the palette define steps or roles that carry semantic meaning (for
+  example, `100` = default background, `700` = solid fill)?
+- Are accent colors mapped to state or function (error, warning, success, info,
+  link, focus)?
+- Is contrast information referenced or WCAG compliance noted?
+
+### 3. Light/Dark Token Parity
+
+- If the project supports multiple themes (light/dark), do both themes use the
+  **same token names** with different values?
+- Can an agent consume one token vocabulary that works across themes without
+  conditional branching on theme names?
+- Are both themes documented in the same structure (or a parallel file with the
+  same heading layout)?
+
+### 4. Typography Tokens
+
+- Are typography choices expressed as **named tokens** with concrete values
+  (`fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`) rather than prose
+  descriptions alone?
+- Are categories distinguished (headings, body/copy, labels, buttons, code/mono)?
+- Do tokens cover the full range of sizes the project uses?
+- Are font families specified (not only implied)?
+
+### 5. Spacing/Layout Rhythm
+
+- Is there a defined spacing scale (for example 4px base with named steps)?
+- Are layout rules concrete: max content width, breakpoints, padding
+  conventions, responsive behavior?
+- Can an agent derive correct spacing from the contract without guessing?
+
+### 6. Elevation/Shape
+
+- Are shadow values expressed as concrete `box-shadow` tokens (or equivalent)
+  rather than qualitative labels?
+- Are border-radius values defined per context (controls, cards, modals, pills)?
+- Is the elevation hierarchy clear (flat → raised → popover → modal)?
+
+### 7. Motion
+
+- Are animation durations, easing curves, and allowed motion types specified?
+- Is `prefers-reduced-motion` handling documented?
+- Does the contract distinguish functional motion (reveals, transitions) from
+  decorative motion, and discourage the latter?
+
+### 8. Component Tokens
+
+- Are primary interactive components (buttons, inputs, selects, toggles)
+  described with token-level detail: background, text color, border, height,
+  radius, padding?
+- Are interaction states covered: default, hover, active, focus, disabled, error?
+- Is the focus ring or focus indicator specified?
+
+### 9. Accessibility
+
+- Does the contract specify minimum contrast ratios (for example WCAG AA 4.5:1
+  for body text)?
+- Is focus visibility required for all interactive elements?
+- Does the contract prohibit signaling state with color alone (requiring icon or
+  text pairing)?
+- Are touch targets / minimum sizes referenced for mobile?
+
+### 10. Voice/Content
+
+- Does the contract include content rules: capitalization conventions, action
+  labeling, error message format, empty-state copy, in-progress wording?
+- Are the rules concrete enough that an agent can apply them without subjective
+  judgment?
+
+### 11. Machine-Readability
+
+- Are design decisions expressed as **named tokens with concrete values** that an
+  implementation agent can directly consume?
+- Or are decisions expressed only as qualitative prose (for example "use generous
+  whitespace") that requires interpretation?
+- Can the contract be parsed section-by-section by an agent without resolving
+  ambiguity?
+
+## Severity
+
+- **Gap**: A section or dimension is entirely absent.
+- **Weak**: A section exists but gives only qualitative prose without
+  machine-consumable token values.
+- **Inconsistency**: Two parts of the contract contradict each other (for
+  example, a radius value in Components differs from the Shapes section).
+- **Parity drift**: Light and dark themes define different token sets or
+  miss entries in one theme.
+- **Accessibility gap**: The contract omits minimum contrast, focus visibility,
+  or color-only signaling rules.
+
+## Guardrails
+
+- This rubric is read-only. Route fixes through normal follow-up handoff paths
+  rather than modifying the project `DESIGN.md` during an audit.
+- Do not impose Geist's specific palette, radii, spacing, font choices, or
+  aesthetic on the audited project.
+- Do not treat a missing `DESIGN.md` as a rubric failure; report the absence and
+  recommend authoring one.
+- Keep findings style-neutral: critique completeness and consumability, not
+  taste.