gentle-pi 4.1.0 → 4.3.0

package/tests/fixtures/provider-contract-bundle/v1.4.0/routing/pi.md

@@ -0,0 +1,92 @@
+## Implementation Routing
+
+Organic Driven Development (ODD) is the predefined workflow of this orchestrator. Every request enters it, on every runtime, without the user asking for a workflow, a plan, or task tracking. Never describe this workflow only when asked about it: run it.
+
+### ODD protocol (MANDATORY, in this order, on every request)
+
+1. **Authorize.** Investigation, explanation, review, comparison, and proposal-only requests stay read-only: no writer, apply, or implementation artifacts. Ambiguous or conditional change intent (unclear whether a change is authorized at all) gets one clarification; stop and wait. A user saying they may stop you or resume later asks for notes and separate commits, not a stop.
+2. **Explore.** Explore existing code and requirements first, proportionately to the request, before proposing or writing anything. Do not delegate exploration of files you will read anyway to work inline; explore only for a map you need to decide or route.
+3. **Resolve uncertainty.** Recommend optional research only for a named uncertainty; ask one focused user question only for a real unresolved product decision, then stop and wait; use at most one scoped read-only assumption challenge for a high-consequence unproven premise.
+4. **Classify.** Size the task by the orchestrator's Task Size section; its criteria and resume test alone decide small or large, and small work follows its small path.
+5. **Track before the first write.** For large authorized implementation, create `odd/tasks/<feature-name>.md` and its Engram mirror `odd/<feature-name>/tasks` automatically, then create or rebuild the visible `todo` list from the reconciled feature tasks, all before the first source write and without asking permission for tasks or storage. Tell the user in one line which feature document was created and how many tasks it holds. The document is the specification subagents read, in this order: a two- or three-line header; `## Specs` with numbered `S#` that quote the user's exact strings, error messages, and examples verbatim, never summarized and never adding unrequested requirements; `## Tasks` with one line per task (ID, linked `S#`, route, commit); `## Log` last, where `L1` is the user's original request verbatim and later user corrections, evidence, and decisions are appended. A requirement change appends its verbatim Log entry, rewrites only the affected `S#`, and reopens only its task.
+6. **Implement task by task.** Hand off by reference, never by paraphrase: name the document, task, and specs (for example `Spec: odd/tasks/<feature>.md, T2, S3-S4`), tell workers to read until `## Log`, and ask which `S#` were covered. Without a feature document, include the user's request verbatim. Verify reads the whole document, runs the spec's examples the parent authorized, against isolated state when they mutate data, and returns a verdict per `S#`. When the user reports a failure, reproduce it before deciding it already works. Each test asserts every observable effect of the rule it covers (exit code, exact stdout and stderr, and that rejected input leaves stored data and counters unchanged), covers the cases the rule itself names (its examples, boundaries, and errors), and checks through the public interface, never internal storage. When you add or change a command, option, or message, update the help text and docs that describe it. Route each task through the orchestrator's Mechanisms, honoring its delegation triggers when their conditions truly hold, with applicable test-first development and checks. No trigger holds by default and, when in doubt, work inline; executing past a fired trigger inline is a routing defect even if the work succeeds. Check an item off only after its outcome and checks were observed; update the file, mirror, and visible `todo` projection after every task transition and material plan change. Commit work units in reviewable slices of about 400 authored changed lines on the feature branch (branch first when on the default branch), with tests and docs alongside the behavior and a Conventional Commit message; a unit whose Risk line names a high-risk item gets its own commit so native review can take it alone, and the last slice closes the feature. Record the commit that holds each task in the feature document as evidence. Work-unit commits on the feature branch are part of authorized large ODD implementation; push, pull request creation, and merge remain the user's decisions.
+7. **Close.** Report the verified outcome, every failed, skipped, or pending check, and the next step. Before writing `Risk: none`, check whether your diff changes code that existing behavior the request did not mention also uses (shared options, parsers, helpers); if it does, that is item 3. Never end with a tracked task pending unless you quote the user's explicit stop. An applicable quick check runs once; an unavailable verifier or subagent is reported as unavailable, never retried or escalated into extra ceremony. Partial, blocked, unavailable, or exhausted proof becomes one **Needs your decision** result naming the open blockers or missing proof, never more verification; that result is a valid stop, hedged wording is not. The native review candidate is a work-unit commit or a PR slice, never a TODO checkbox and never the accumulated feature branch; native review runs only under the user-owned RDD switch.
+
+Phase reporting: the Gentle Shell prompt label is inferred automatically from the primary session's tool activity (reads show `exploring`, edits `implementing`, test runs `checking`, user questions `deciding`). When the `gentle_odd_phase` tool is available, use it to refine that label with phases tools cannot show (`authorizing`, `researching`, `deciding`, `closing`): call `gentle_odd_phase` only when the primary session's ODD phase actually changes, never per tool call or on a fixed cadence, and never from a subagent. It drives the Gentle Shell prompt label only.
+
+Resume an interrupted feature with `mem_context`, then project- and feature-scoped `mem_search`, then `mem_get_observation` for the full document, then the task file itself; reconcile before continuing the next unfinished task. Detail for steps 3–7: `orchestrator-delegation.md` and `orchestrator-memory.md`.
+
+### Task Size
+
+A task is **small** when all three hold:
+
+1. **Understood**: the outcome is specified, what and where to change is known, and no product or design decision is open; prove it within one bounded read batch (at most 3 calls, approximately 10k tokens).
+2. **Contained risk**: it touches no high-risk item below.
+3. **Resumable from the diff**: resume test, if the session stopped now, someone could finish the work from the original request and `git diff` alone.
+
+The number of files, commands or tests, fixes, or a requested todo list never decides size. A task is **large** only when the resume test fails: several sessions, waiting on something external, separate deliverables the user wants apart (never several features asked at once), or requirements too long to survive compaction. A large task gets tracking; it gets a writer only by the Writer trigger, otherwise the parent works inline.
+
+Small path: work inline. Read and edit, several files of one understood change included; observe RED inline before the fix; run the focused test and the suite inline, once each. No explore, worker, or verifier; no feature document, mirror, or commits unless the user asks; a todo list is optional.
+
+**High risk**: a mistake would be hard to detect, hard to undo, or reaches beyond the change. It touches (1) data or irreversible effects: migrations, changing or deleting existing stored data, persisted format changes (not saving new records); (2) security: auth, permissions, credentials, secrets, guards, sandbox; (3) contracts others consume: changing or removing public API, CLI flags, config formats, published exports, or mirrored prompts or contracts others already consume (not adding a flag, command, or optional field; requested changes are not high risk by themselves; unrequested breaks in shared code are); (4) concurrency: locks, races, async ordering; (5) delivery or environment: installers, release, CI, deploy, dependencies; (6) no test would catch a regression in what changes. Count "unclear" as high only when a bounded look cannot tell whether (1)-(5) apply. When RDD is on, the native assess tier decides native review and you may only raise it; it never adds an independent verifier by itself, only a named high-risk item does.
+
+**Risk line**: close every code change, small path or delegated, with `Risk: item N (reason)` or `Risk: none` per the list; any item fires the Verification trigger. Before writing `Risk: none`, check whether the diff changes code that existing behavior the request did not mention also uses (shared options, parsers, helpers); if it does, that is item 3.
+
+After explicit change intent is established, route work for the requested outcome with the smallest useful topology. Every authorized change takes exactly one implementation route: direct inline or delegated direct.
+
+- **Direct inline:** small tasks, by the Task Size section, and large tasks without a Writer trigger reason, which follow their logbook. Decide or verify with one parallel batch (1 maximum), at most 3 calls and approximately 10k tokens of evidence. Use bounded search/line ranges, not whole large files. One understood change stays inline even when it spans files, and its focused test and suite run inline.
+- **Delegated direct:** understanding that needs more evidence or more than approximately 5 sequential lookups takes one read-only explorer, then task size is re-evaluated; a writer is delegated only by the Writer trigger.
+- File count, changed lines, size, or perceived risk alone never forces a heavier route.
+- These are implementation routes, not a ban on per-action delegation. Tests, builds, installs, and review actors may still use fresh workers without changing the selected route.
+
+### Delegation Triggers
+
+Each trigger holds only when its condition truly holds, and only then is it mandatory, not advisory; no trigger holds by default, and when in doubt work inline. Each mechanism turns on only by its own trigger. When one fires, stop and delegate through the runtime's subagent mechanism before continuing; executing past a fired trigger inline is a routing defect even if the work succeeds. When it resolves, re-evaluate task size and stay small while the three criteria hold. Delegation keeps the parent context thin enough to orchestrate; it does not slow the work down.
+
+- **Ask trigger:** an open product or design decision gets one focused user question; stop and wait.
+- **Mapping trigger:** when understanding exceeds the inline batch budget or needs more than approximately 5 sequential lookups, delegate one read-only explorer before deciding or writing anything. Return a handoff of at most approximately 2k tokens with path:line evidence; use one parent spot check (1 maximum). Do not reread the entire mapped evidence. Never explore to read files you will read anyway before writing inline.
+- **Verification trigger:** only a change whose Risk line names a high-risk item gets an independent verifier after the change's own checks, as rarely as possible; a native tier, an unclear or failed assessment, and the writer's model or effort never add one by themselves. Otherwise whoever made the change runs its focused test and suite inline, small tasks included.
+- **Tracking trigger:** a large task gets the feature document, its mirror, and work-unit commits.
+- **Writer trigger:** a writer is delegated only for a named reason, one bounded writer per unit: (a) parallelism: two or more independent units of behavior with disjoint edit surfaces, each needing several minutes of work (several files or roughly 100+ changed lines; a subagent spends one to two minutes reading before it writes), launched together; (b) context: the long-session backstop below. A unit is one independent piece of behavior with its code, tests, and docs together: never split one behavior into test, docs, and code writers, and a delivery that depends on another is not independent; several small independent changes run inline, one after another. Units of about 100 changed lines or less always run inline: writing them costs less than starting workers. Never delegate a writer for size, a large task alone, file count, or a price ratio; file count never fires this trigger. Without a reason, the parent works inline, following its logbook (feature document, mirror, work-unit commits).
+- **Parallel writers:** work in another repository goes in a fresh worktree based on that repository's main, never in a checkout someone else may be using. Parallel units in the same local repository run in the same tree, each with declared disjoint edit surfaces: the parent owns git; writers run no repository-wide formatters, generators, or installs; a shared file has one owner or the parent edits it at the end; the parent checks each writer's diff against its surface before accepting it; and one seam check runs at the end (the full suite, once). Units that need the same file use isolated worktrees.
+- **Invariants:** each writer prompt names the existing helpers its unit must reuse for shared state (for example the function that adds an entry other commands also add) and the invariants they keep (ordering, uniqueness, validation, normalization); units built in parallel cannot see each other, so the prompt is the only place they learn them. Whoever writes, inline or delegated, reuses the existing function for shared state and never re-implements that step with a different shape.
+- **Preparation trigger:** when the Writer trigger delegates a write, reading that prepares it, and broad research or context compression, delegate together with or ahead of the write instead of filling the parent context. Inline writes read inline.
+- **Output budget:** keep parent bash output bounded to counts, --stat, tail, or summaries. On a large task, delegate long suites and builds and return concise observed results, including failures.
+- **Long-session backstop:** at approximately 150k parent-context tokens, pause and delegate the next bounded unit. This is advisory context guidance, not mechanically observed or enforced; do not claim runtime telemetry or enforcement.
+- **Route declaration:** for large work, record the chosen route per task (inline or delegated) and the trigger evidence in the feature document, so skipped delegation is observable instead of silent.
+- These triggers only choose between direct inline and delegated direct inside the organic flow.
+
+### Organic Driven Development
+
+Use this flow for direct and delegated work. Explore the existing code and requirements first, proportionately to the request; the mutation-authorization guard above still applies.
+
+This section is the reference detail for the protocol above.
+
+- Recommend optional research only for a named uncertainty. If declined, continue within authorized scope only where safe without the missing evidence; disclose unresolved uncertainty and pause affected unsafe decisions. Offer a concise proposal only when a real scope or product decision needs it. Neither research nor a proposal is mandatory.
+- Establish the problem, intended outcome, constraints, and current evidence; inspect relevant code. Adapt depth to uncertainty and consequence, not a fixed questionnaire or mandatory rounds. The parent owns product decisions: ask one focused user question only for a real unresolved product decision, then stop and wait. Workers return gaps to the parent rather than assuming choices.
+- When the question needs external evidence, use available authorized documentation/web tools and prefer primary sources. Attribute material claims to source URLs or code locations; distinguish verified facts, assumptions, contradictions, freshness, and gaps. If tools are unavailable, disclose limitations without inventing access or evidence; pause only unsafe decisions dependent on missing evidence.
+- Return concise findings, recommendation, tradeoffs, open questions, and implementation implications. When delegating research, forward these research instructions to a fresh general exploration/research worker through existing delegation; do not create a specialized research agent. Keep research read-only; its findings do not authorize implementation or require new persistence or readiness machinery.
+- Use at most one scoped independent read-only assumption challenge for a high-consequence unproven premise, even in a small security-critical change. Name the premise, evidence, and consequence; do not start a debate loop. Deterministic failures need fixes, not model debate. The native RDD refuter owns native review claims; never duplicate or bypass it.
+- Validate consequential premises against available evidence before building; reuse relevant sibling investigation instead of repeating it. Run focused checks during iteration and all applicable full checks at task closure. Keep spend proportional without a hard spend or line gate; preserve the applicable test-first policy, native RDD, safety, and consent requirements.
+- Size every task by the Task Size section; small work creates no durable task artifacts, and counts of files, commands, tests, fixes, or lines never make it large. For large authorized implementation, automatically create the feature document after exploration, without a task or storage permission prompt.
+- Use about 400 authored changed lines per ODD task only as a planning heuristic, counting additions plus deletions; prefer the smallest coherent behavior with its tests and docs. This is not a task acceptance criterion, hard cap, counter-trigger, automatic stop, forced split, or RDD trigger. If the correct, clear solution naturally exceeds it, briefly explain why and continue without size-only rework loops. Never delete spaces, blank lines, or comments for cosmetic line savings; never omit tests, minify, add gratuitous abstractions, or split artificially to fit the heuristic. Forward this same advisory-only instruction when delegating tasks to subagents. The delivery budget below reads the accumulated branch, not this per-task heuristic. Existing PR size gates remain unchanged; continue under existing repository policy.
+- Keep `odd/tasks/<feature-name>.md` and an Engram recovery copy under topic `odd/<feature-name>/tasks`, scoped to the current project. Use a descriptive filename-safe feature name. Reuse the same feature identity; never overwrite another feature. Keep one feature document, not a separate plan file or topic. It is the specification subagents read by reference, so keep this fixed order, stable content first and the growing log last: a header of two or three lines with the objective, branch, delivery strategy, and test runner; `## Specs` with numbered `S1`..`Sn` requirements and their authorized scope, acceptance criteria, and applicable checks, quoting the user's exact strings, error messages, commands, and examples verbatim in the user's language (number and order them, but never summarize or reword those fragments; Do not add requirements the user never asked for, and mark assumptions as assumptions); `## Tasks` with one line per task, using stable task IDs, with its linked `S#`, route (inline or delegated), status, and commit identity or RED/GREEN evidence; `## Log` as the logbook, where `L1` holds the user's original request verbatim, later user corrections are logged verbatim with their date, and problem analysis, rationale for meaningful accepted changes, verification evidence, progress, and next step are appended. Routine corrections stay brief; no exhaustive decision journal. Mirror the full current document and repository-relative file locator, not just a summary or completion notice.
+- Accepted user, review, or verification changes automatically update affected intent and TODOs, unlike a process that regenerates every artifact: a requirement change appends its verbatim `## Log` entry, rewrites only the affected `S#`, and reopens only its linked task; preserve valid completed and unrelated work; add genuinely new tasks or reopen invalidated items with a reason, and revise their checks. Findings alone never authorize scope expansion or automatic acceptance. Business scope changes still require user authorization. Check off only observed outcomes with applicable proof; record failed, unavailable, skipped, or pending checks honestly. Checkboxes grant no approval or receipt.
+- Read back both writes; they are not atomic. If Engram is unavailable, preserve local progress and explicitly mark the mirror pending; do not claim success or block unrelated safe work. Resynchronize when available. If a file write is unsafe or unavailable, preserve existing state and report the limitation. Preserve both versions on irreconcilable edits and ask only about the real conflict.
+- On resume, use `mem_context`, then `mem_search` scoped to the current project and feature, and `mem_get_observation` for the full saved document; read the actual task file. Do not infer active work from the newest global memory. Reconcile current requirements, code, and proof before resuming the next unfinished task; preserve pending mirrors and conflicting edits.
+- Before implementation or resume, the parent reads both the actual file and full observation, reconciles them, and passes the locator, task IDs, and linked `S#`; workers read the document until `## Log` before edits and report which `S#` they covered. Small work without a document still receives its authorized scope and checks.
+- Apply one default test-first policy to ODD behavior changes: when a relevant runnable deterministic test and clear expected outcome exist, observe RED before implementation, implement GREEN, then refactor while tests stay green. Write one RED test per requested rule. For every existing command or option the change touches, add one test proving its previous behavior still holds; add no other cases. An existing behavior counts as touched when it shares the code you changed (options, parsers, helpers, validation). Before finishing, run a differential check: for each existing command that shares the code you changed, run it with the new or changed input (for example a new option passed to a sibling subcommand) against the previous code (a copy of the base commit in a `mktemp -d` scratch directory, never committed as a test; committed tests never read git history or a fixed commit) and against your change, and compare stdout, stderr, and exit code; any difference nobody asked for is a regression to fix and pin with a test. Tests or frameworks being present alone do not establish applicability. For passive documentation, unavailable runners, or no meaningful runnable RED, explain the exception and run proportionate functional or structural checks. Keep test scratch state (temporary directories, `HOME`, `TMPDIR`, tool caches) outside the worktree in a `mktemp -d` directory; when it must live inside the worktree, use a path git excludes and remove it before finishing, so no tool cache or scratch path remains in the change. Subagents never delete scratch: they report its exact paths, and the parent removes outside scratch after use, including the paths a worker or verifier reports. Forward the applicable runner, this test discipline, and the evidence or exception to workers; never invent RED/GREEN evidence or a runner.
+- Preserve existing native risk selection and applicable functional verification. Run applicable functional checks per task, not a review cycle per TODO checkbox. The native review candidate is a work-unit commit or a PR slice, never a TODO checkbox and never the accumulated feature branch. After each work-unit commit, when RDD is enabled, run `gentle-ai review assess --cwd <repo> --agent pi --base-ref <last reviewed boundary> --committed-only --json` on that commit and read `review_due` and `review_due_reason`. When `review_due` is true (`high_risk`), or when the user explicitly asks for a review, execute the returned `next_transition.command` verbatim with your `--lenses`/`--lenses-reason` selection appended: it is the exact preflight STATUS for the same `--base-ref`/`--committed-only` selectors; follow the transitions it returns, and the reviewed boundary advances to this commit once that review is acknowledged. When `review_due` is false, record `review_due_reason` and continue: `passive` needs no review and the boundary advances; `under_budget` stays pending in the slice until a later commit reaches the budget; `already_reviewed` means this exact range is already covered by terminal authority. When a high-risk unit follows pending `under_budget` commits, close the open slice first, assessing and reviewing it as the slice, so the high-risk commit is then reviewed alone against the new boundary. The first boundary is the branch point, and every reviewed boundary becomes the next base. Record per commit the assessed tier and outcome: granted, declined, passive, under budget, already reviewed, or unavailable. An unavailable or failed assessment never lowers the tier: treat the commit as due and run the preflight STATUS with `--base-ref <last reviewed boundary> --committed-only`. Never infer low risk from a failed assessment, and keep existing risk, consent, and authority unchanged. Never skip an existing delivery gate. A task list or assumption challenge never enables RDD, replaces its roles or candidate consent, or adds an execution harness.
+- Delivery follows work units. At feature-document creation, forecast authored changed lines (additions plus deletions, generated files excluded) from the task list, and keep a running count from work-unit commits. Choose one delivery strategy per feature: `ask-on-risk` (default), `auto-chain`, `single-pr`, or `exception-ok`. When the forecast or the running count exceeds about 400 authored changed lines, apply the chosen strategy before the next commit: `ask-on-risk` asks once for the chain strategy, `stacked-to-main` or `feature-branch-chain`; `auto-chain` asks only for a missing chain strategy and slices automatically. Cache both choices, and record slice boundaries, which commits each pull request holds, in the feature document. Resolve the `work-unit-commits` and `chained-pr` skills by registry name before planning or creating any pull request, never hardcode their paths.
+- When RDD is enabled, first use the existing native candidate risk assessment (`gentle-ai review assess --cwd <repo> --agent pi --json`). Passive/low uses silent structural checks with no reviewer or consent ceremony. Medium/high relays the existing candidate consent and follows the native plan: native review runs only on grant; a decline continues under ordinary policy. Do not substitute model judgment, task size, or defect severity to lower prospective candidate risk; never infer low risk from a failed assessment. You may raise a candidate you know is high risk with `--escalate-item <1-6> --escalate-reason "<one line>"` on that same assessment command, citing the high-risk list; never lower it. Follow native continuations and authority without bypassing gates. When RDD is disabled, do not start or prompt for RDD; ordinary checks remain.
+
+### Receipt-driven development is user-owned
+
+The user controls receipt-driven development with a switch: `gentle-ai review mode enable|disable|status`.
+
+- It is **on by default and opt-out**. An unset preference permits review without recording a user decision; explicit global or clone-local OFF still wins. Candidate consent remains separate from the mode default.
+- `status` is read-only. It reports the deciding source and the effective mode, and changes nothing. A `default` deciding source means nobody has chosen, so the effective mode is on.
+- When the user asks to stop using receipt-driven development, run `disable`. Do not argue, do not work around it, and do not propose alternatives first.
+- While it is disabled, keep implementing organically through direct inline or delegated direct: do not start reviews, do not retry, do not reactivate it, and do not fall back to any retired path.
+- Delivery under a disabled switch follows ordinary repository policy and reports `disabled/unmanaged`, never a fabricated approval.
+- Never toggle the mode automatically or persist a preference just because the default is on. Never enable receipt-driven development on the user's behalf unless the user explicitly asks for it.

package/tests/fixtures/provider-contract-bundle/v1.4.0/schemas/lens.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/schema/review/reviewer/v1",
+  "title": "Gentle AI reviewer result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["subject_hash", "inspection", "findings", "evidence"],
+  "properties": {
+    "subject_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "inspection": {"type": "object", "additionalProperties": false, "required": ["status", "paths"], "allOf": [{"if": {"properties": {"status": {"const": "unavailable"}}, "required": ["status"]}, "then": {"required": ["reason"]}}], "properties": {"status": {"type": "string", "enum": ["completed", "unavailable"], "description": "\"completed\" asserts every changed_path_manifest path was actually inspected. \"unavailable\" asserts the candidate could not be inspected at all and requires a non-empty reason; this is the typed admission-completeness signal; evidence prose is not a substitute for it."}, "paths": {"type": "array", "description": "Complete unique unordered set of every changed_path_manifest.path when status is \"completed\"; empty when status is \"unavailable\".", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "reason": {"type": "string", "minLength": 1, "description": "Required and non-empty only when status is \"unavailable\": why the candidate could not be inspected."}}},
+    "lens": {"type": "string", "description": "Optional selected lens binding. Omission canonicalizes to the selected subject lens.", "enum": ["risk", "resilience", "readability", "reliability", "review-risk", "review-resilience", "review-readability", "review-reliability"]},
+    "findings": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["location", "severity", "claim", "proof_refs"], "allOf": [{"if": {"properties": {"severity": {"enum": ["BLOCKER", "CRITICAL"]}}, "required": ["severity"]}, "then": {"required": ["evidence_class", "causal_disposition"]}}], "properties": {"id": {"type": "string", "pattern": "^R[1-4]-[A-Za-z0-9][A-Za-z0-9._-]*$", "description": "Optional explicit ID; omit it to receive a native-assigned ID. When present it must carry the prefix bound to the selected lens, not the selection order: review-risk=R1-, review-readability=R2-, review-reliability=R3-, review-resilience=R4-."}, "lens": {"type": "string", "enum": ["risk", "resilience", "readability", "reliability", "review-risk", "review-resilience", "review-readability", "review-reliability"]}, "location": {"type": "string", "description": "One canonical repository-relative path:line or inclusive path:start-end span.", "pattern": "^.+:[1-9][0-9]*(?:-[1-9][0-9]*)?$"}, "severity": {"type": "string", "enum": ["BLOCKER", "CRITICAL", "WARNING", "SUGGESTION"]}, "claim": {"type": "string", "minLength": 1}, "proof_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "\\S", "not": {"pattern": "^\\s*(?:[nN]/[aA]|[nN][aA]|[nN][oO][nN][eE]|[tT][oO][dD][oO]|[tT][bB][dD]|[pP][aA][sS][sS]|[pP][aA][sS][sS][eE][dD]|[sS][uU][cC][cC][eE][sS][sS]|[pP][lL][aA][cC][eE][hH][oO][lL][dD][eE][rR])\\s*$"}}}, "evidence_class": {"type": "string", "enum": ["deterministic", "inferential", "insufficient"]}, "causal_disposition": {"type": "string", "enum": ["introduced", "behavior-activated", "worsened", "pre-existing", "base-only", "unknown"]}}}},
+    "evidence": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "\\S", "not": {"pattern": "^\\s*(?:[nN]/[aA]|[nN][aA]|[nN][oO][nN][eE]|[tT][oO][dD][oO]|[tT][bB][dD]|[pP][aA][sS][sS]|[pP][aA][sS][sS][eE][dD]|[sS][uU][cC][cC][eE][sS][sS]|[pP][lL][aA][cC][eE][hH][oO][lL][dD][eE][rR])\\s*$"}}}
+  },
+  "examples": [{"subject_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "inspection": {"status": "completed", "paths": ["internal/example.go"]}, "findings": [], "evidence": ["reviewed the complete candidate scope"]}, {"subject_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "inspection": {"status": "unavailable", "paths": [], "reason": "the immutable inspection command timed out before any path could be read"}, "findings": [], "evidence": ["inspection was unavailable; see inspection.reason"]}]
+}

package/tests/fixtures/provider-contract-bundle/v1.4.0/schemas/refuter.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://gentle-ai.dev/schema/review/refuter/v1","title":"Gentle AI refuter result","type":"object","additionalProperties":false,"required":["refuter_request_hash","results"],"properties":{"refuter_request_hash":{"$ref":"#/$defs/sha256"},"results":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["finding_id","outcome","proof_refs"],"properties":{"finding_id":{"type":"string"},"outcome":{"type":"string","enum":["corroborated","refuted","inconclusive"]},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}}},"$defs":{"sha256":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"}},"examples":[{"refuter_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","results":[]}]}

package/tests/fixtures/provider-contract-bundle/v1.4.0/schemas/targeted-validator.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://gentle-ai.dev/schema/review/validator/v1","title":"Gentle AI targeted validator result","type":"object","additionalProperties":false,"required":["targeted_validation_request_hash","correction_target_identity","original_criteria","correction_regression","follow_ups"],"properties":{"targeted_validation_request_hash":{"$ref":"#/$defs/sha256"},"correction_target_identity":{"$ref":"#/$defs/sha256"},"original_criteria":{"$ref":"#/$defs/check"},"correction_regression":{"$ref":"#/$defs/check"},"follow_ups":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["observation","proof_refs"],"properties":{"observation":{"type":"string"},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}}},"allOf":[{"if":{"properties":{"correction_regression":{"type":"object","properties":{"passed":{"const":false}},"required":["passed"]}},"required":["correction_regression"]},"then":{"properties":{"correction_regression":{"type":"object","properties":{"regressions":{"minItems":1}},"required":["regressions"]}}}}],"$defs":{"sha256":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"check":{"type":"object","additionalProperties":false,"required":["passed","evidence"],"properties":{"passed":{"type":"boolean","description":"true means the named check passed; false means the named check failed."},"evidence":{"type":"array","minItems":1,"items":{"type":"string"}},"regressions":{"type":"array","items":{"$ref":"#/$defs/regression"},"description":"Required with at least one entry when this is correction_regression and passed is false: one entry per observed regression, omitted or empty otherwise."},"inspection":{"$ref":"#/$defs/inspection"}},"allOf":[{"if":{"properties":{"inspection":{"type":"object","properties":{"status":{"const":"unavailable"}},"required":["status"]}},"required":["inspection"]},"then":{"properties":{"inspection":{"type":"object","required":["reason"]}}}}]},"inspection":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["completed","unavailable"],"description":"completed means this check's verdict came from actually reading the frozen candidate trees. unavailable means it did not, and this check produced no verdict."},"reason":{"type":"string","minLength":1,"description":"Required when status is unavailable: why the frozen candidate trees could not be read."}},"description":"Optional. Omit this field entirely when inspection completed normally -- every check that predates this field already assumed that default. Never infer unavailable from evidence wording; only this typed field marks a check inconclusive."},"regression":{"type":"object","additionalProperties":false,"required":["location","claim","proof_refs"],"properties":{"id":{"type":"string","description":"Optional explicit ID; omit it to receive a native-assigned ID."},"location":{"type":"string","description":"One canonical repository-relative path:line or inclusive path:start-end span.","pattern":"^.+:[1-9][0-9]*(?:-[1-9][0-9]*)?$"},"claim":{"type":"string","minLength":1},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}},"examples":[{"targeted_validation_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","correction_target_identity":"sha256:1111111111111111111111111111111111111111111111111111111111111111","original_criteria":{"passed":true,"evidence":["acceptance test passed"]},"correction_regression":{"passed":true,"evidence":["regression test passed"]},"follow_ups":[]}]}

package/tests/fixtures/provider-contract-bundle/v1.4.0/vectors/lens.json

@@ -0,0 +1 @@
+{"subject_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","inspection":{"status":"completed","paths":["internal/example.go"]},"findings":[],"evidence":["reviewed the complete candidate scope"]}

package/tests/fixtures/provider-contract-bundle/v1.4.0/vectors/refuter.json

@@ -0,0 +1 @@
+{"refuter_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","results":[]}

package/tests/fixtures/provider-contract-bundle/v1.4.0/vectors/targeted-validator.json

@@ -0,0 +1 @@
+{"targeted_validation_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","correction_target_identity":"sha256:1111111111111111111111111111111111111111111111111111111111111111","original_criteria":{"passed":true,"evidence":["acceptance test passed"]},"correction_regression":{"passed":true,"evidence":["regression test passed"]},"follow_ups":[]}

package/tests/gauge-theme.test.ts

@@ -0,0 +1,120 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { clearGaugePaintCache, gaugePaintFor, resolveGaugePaint } from "../lib/gauge-theme.ts";
+import { paintGauge } from "../lib/shell-gauge.ts";
+
+// Issue #2222: reserved `vars` keys (`gauge.*`) give the gauges their own
+// roles and glyphs; everything else falls back. `vars` is the only open map
+// in Pi's theme schema, and these tests run every fixture through the same
+// validation the theme loader applies.
+
+const taggedTheme = {
+	fg(color: string, text: string) {
+		return `<${color}>${text}</${color}>`;
+	},
+};
+
+function withThemeSource(body: unknown): string {
+	const directory = mkdtempSync(join(tmpdir(), "gauge-theme-"));
+	const path = join(directory, "Theme.json");
+	writeFileSync(path, typeof body === "string" ? body : JSON.stringify(body));
+	return path;
+}
+
+const BASE_THEME = {
+	name: "Test",
+	colors: { accent: "magenta", warning: "yellow", error: "red", border: "cyan", success: "green", syntaxString: "blue" },
+};
+
+test("resolveGaugePaint reads token references and glyphs from the gauge vars", () => {
+	const path = withThemeSource({
+		...BASE_THEME,
+		vars: { "gauge.ok": "success", "gauge.warning": "syntaxString", "gauge.error": "error", "gauge.empty": "border", "gauge.filled": "█", "gauge.emptyGlyph": "░" },
+	});
+	const paint = resolveGaugePaint(path);
+	assert.deepEqual(paint, { ok: "success", warning: "syntaxString", error: "error", empty: "border", filled: "█", emptyGlyph: "░" });
+	assert.equal(paintGauge(45, taggedTheme, 8, paint), `<success>████</success><border>░░░░</border>`);
+});
+
+test("a theme without gauge vars resolves no paint", () => {
+	assert.equal(resolveGaugePaint(withThemeSource(BASE_THEME)), undefined);
+	assert.equal(resolveGaugePaint(withThemeSource({ ...BASE_THEME, vars: { brand: "#ff0000" } })), undefined);
+});
+
+test("invalid entries fall back per role and glyphs must be single visible characters", () => {
+	const path = withThemeSource({
+		...BASE_THEME,
+		vars: { "gauge.ok": 300, "gauge.warning": "noSuchToken", "gauge.error": "error", "gauge.filled": "██", "gauge.emptyGlyph": "" },
+	});
+	assert.deepEqual(resolveGaugePaint(path), { error: "error" });
+});
+
+test("gauge colors accept direct hex, okhsl, 256 indexes, and vars references", () => {
+	const path = withThemeSource({
+		name: "Test",
+		colors: { accent: "brand" },
+		vars: { brand: "#ff0000", "gauge.ok": "#22c55e", "gauge.warning": "brand", "gauge.error": 196, "gauge.empty": "okhsl(70 0.1 0.5)" },
+	});
+	const paint = resolveGaugePaint(path);
+	assert.equal(paint?.ok, "\x1b[38;2;34;197;94m");
+	assert.equal(paint?.warning, "\x1b[38;2;255;0;0m");
+	assert.match(paint?.error ?? "", /^\x1b\[38;5;196m$/);
+	assert.match(paint?.empty ?? "", /^\x1b\[38;2;\d+;\d+;\d+m$/);
+});
+
+test("direct colors use the same color grammar themes use everywhere: 3-digit hex, oklch, and case-insensitive okhsl", () => {
+	const path = withThemeSource({
+		name: "Test",
+		colors: {},
+		vars: { "gauge.ok": "#f00", "gauge.warning": "OKHSL(120 50% 50%)", "gauge.error": "oklch(0.7 0.1 200)", "gauge.empty": "okhsl(bogus)" },
+	});
+	const paint = resolveGaugePaint(path);
+	assert.equal(paint?.ok, "\x1b[38;2;255;0;0m");
+	assert.match(paint?.warning ?? "", /^\x1b\[38;2;\d+;\d+;\d+m$/);
+	assert.match(paint?.error ?? "", /^\x1b\[38;2;\d+;\d+;\d+m$/);
+	assert.equal(paint?.empty, undefined);
+});
+
+test("glyphs must occupy exactly one terminal column", () => {
+	const path = withThemeSource({
+		...BASE_THEME,
+		vars: { "gauge.filled": "０", "gauge.emptyGlyph": "\u200b" },
+	});
+	assert.deepEqual(resolveGaugePaint(path), {});
+});
+
+test("paintGauge paints raw ANSI roles directly and token roles through the theme", () => {
+	const raw = { ok: "\x1b[38;2;34;197;94m" };
+	assert.equal(paintGauge(45, taggedTheme, 8, raw), "\x1b[38;2;34;197;94m▰▰▰▰\x1b[39m<border>▱▱▱▱</border>");
+	assert.equal(paintGauge(45, taggedTheme, 8, { ok: "success" }), "<success>▰▰▰▰</success><border>▱▱▱▱</border>");
+});
+
+test("paintGauge tolerates regex metacharacters in theme-authored glyphs", () => {
+	assert.equal(paintGauge(50, taggedTheme, 4, { emptyGlyph: "*" }), "<accent>▰▰</accent><border>**</border>");
+	assert.equal(paintGauge(50, taggedTheme, 4, { emptyGlyph: "." }), "<accent>▰▰</accent><border>..</border>");
+	assert.equal(paintGauge(100, taggedTheme, 4, { filled: "(" }), "<error>((((</error><border></border>");
+});
+
+test("a malformed theme file throws for the raw resolver and is swallowed by the memoized one", () => {
+	assert.throws(() => resolveGaugePaint(withThemeSource("not json")));
+	assert.equal(gaugePaintFor(withThemeSource("not json")), undefined);
+});
+
+test("gaugePaintFor memoizes by stat and picks up file changes", () => {
+	const path = withThemeSource(BASE_THEME);
+	try {
+		clearGaugePaintCache();
+		assert.equal(gaugePaintFor(path), undefined);
+		assert.equal(gaugePaintFor(undefined), undefined);
+		writeFileSync(path, JSON.stringify({ ...BASE_THEME, vars: { "gauge.ok": "success", "gauge.filled": "█" } }));
+		// Same-second writes are not enough: touch mtime explicitly.
+		utimesSync(path, new Date(), new Date(Date.now() + 5_000));
+		assert.deepEqual(gaugePaintFor(path), { ok: "success", filled: "█" });
+	} finally {
+		clearGaugePaintCache();
+		rmSync(join(path, ".."), { recursive: true, force: true });
+	}
+});