gentle-pi 2.1.2 → 2.2.0

package/assets/sdd-orchestrator-workflow.md

@@ -68,9 +68,11 @@ The preflight captures:
 
 - execution mode: `interactive` or `auto`;
 - artifact store: `openspec`, `engram`, or `both` when callable memory tools are available;
-- chained PR strategy: `auto-forecast`, `ask-always`, `single-pr-default`, or `force-chained`;
+- chained PR strategy: the canonical `delivery_strategy` — `ask-on-risk`, `auto-chain`, `single-pr`, or `exception-ok`. The preflight menu offers the first three; `exception-ok` is reachable only when the user explicitly accepts `size:exception`, either up front or when `ask-on-risk` stops to ask;
 - review budget in changed lines.
 
+Those four PR values are exactly the `delivery_strategy` domain `sdd-tasks` and `sdd-apply` accept; never emit a value outside it. The preflight offers no separate chained option because `delivery_strategy` is only consulted once the tasks forecast flags review-budget risk: below that line there is nothing to chain, and above it `auto-chain` already resolves without asking again.
+
 The package should ensure SDD assets are present as global Pi runtime assets without the user needing to remember per-project setup commands. If assets are missing, install them non-destructively into:
 
 ```text
@@ -82,15 +84,19 @@ Manual install commands are recovery/debug paths, not the happy path. `/gentle:s
 
 ## Init Guard
 
-Before any SDD flow, make sure project context exists.
+Before any SDD flow, make sure project context exists. Where that context lives depends on the session's artifact store, so qualify the check by store before acting on it.
 
-In this Pi package, the default local artifact is:
+When the store is `openspec` or `both`, the local artifact is:
 
 ```text
 openspec/config.yaml
 ```
 
-If it is missing, ask the user for the minimal information needed or run `/sdd-init` if available. This init guard runs after the session preflight gate above; project config presence or absence never substitutes for session preflight choices. Do not proceed with a substantial SDD flow while pretending project context, testing capability, or session preflight choices are known.
+If it is missing, ask the user for the minimal information needed or run `/sdd-init` if available.
+
+When the store is `engram` or `none`, `/sdd-init` never writes that file, so its absence is expected and is not a missing init. Never re-trigger `/sdd-init` over it. Resolve project context from the Engram `sdd-init/{project}` topic for `engram`, or inline from the session for `none`, and ask the user only when that context is genuinely absent.
+
+This init guard runs after the session preflight gate above; project config presence or absence never substitutes for session preflight choices. Do not proceed with a substantial SDD flow while pretending project context, testing capability, or session preflight choices are known.
 
 ## Artifact Store Policy
 
@@ -104,8 +110,10 @@ This package does not provide persistent memory by itself.
 
 Use the session's SDD preflight choice:
 
-- `interactive`: default, pause between major phases and ask whether to continue.
-- `auto`: run phases back-to-back when the user explicitly wants speed and trusts the flow.
+- `auto`: phases run back-to-back without pausing, but the orchestrator gatekeeper validates after each phase before launching the next.
+- `interactive`: after each phase, show a concise summary and ask whether to adjust or continue.
+
+If the user doesn't specify, default to `auto`. After scope approval, expect zero further prompts on the happy path and at most one actionable prompt per recoverable failure; the gatekeeper summarizes phase progress instead of interrupting except on a second consecutive gate failure or a genuine scope/product decision.
 
 In interactive mode, between phases:
 
@@ -117,6 +125,28 @@ Interactive approval is phase-scoped. A user response such as "continue", "dale"
 
 Before `sdd-proposal` in interactive mode, offer the user a proposal question round instead of silently deciding whether the proposal is clear enough. Explain that the questions are meant to improve the PRD/proposal by uncovering business understanding, business rules, implications, impact, edge cases, and product tradeoffs. Prefer 3–5 concrete product questions per round, then summarize the resulting assumptions and ask whether the user wants to correct anything or run a second question round. Cover business/product/PRD decisions: business problem, target users and situations, business rules, product outcome, current-state gap, implications and impact, edge cases, decision gaps, first-slice scope boundaries, non-goals, product constraints, and business tradeoffs. Do not ask about test commands, PR shape, changed-line budget, or other harness mechanics at proposal time unless the user explicitly asks to discuss delivery.
 
+## Delivery Strategy
+
+On the first SDD chain request in a session, resolve the delivery strategy from preflight (or ask once) and cache it:
+
+- `ask-on-risk` — default; ask only when the tasks forecast detects review-budget risk.
+- `auto-chain` — automatically split into chained/stacked PR slices when needed.
+- `single-pr` — proceed as one PR only if the size is within budget.
+- `exception-ok` — user accepts `size:exception` when over budget. The preflight menu cannot select this; it is reached only when the user explicitly accepts `size:exception`, either up front or when `ask-on-risk` stops to ask.
+
+These four are the whole domain. Pass `delivery_strategy` to `sdd-tasks` and `sdd-apply`.
+
+## Chain Strategy
+
+When delivery planning yields chained PRs, ask once for chain strategy and cache it:
+
+- `stacked-to-main` — each PR targets the previous PR branch or main in sequence.
+- `feature-branch-chain` — PR #1 targets the tracker branch; child PRs target the immediate previous PR branch; only the tracker merges to main.
+
+When chained PRs are selected, treat the registry skill `gentle-ai-chained-pr` as a required skill match. Resolve and forward it by registry path to `sdd-tasks` and `sdd-apply`; do not hardcode its path.
+
+Pass it as `chain_strategy` to `sdd-tasks` and `sdd-apply` prompts alongside `delivery_strategy`.
+
 ## Result Contract
 
 Every phase result should include:
@@ -132,6 +162,10 @@ skill_resolution
 
 The parent should synthesize these envelopes, not paste long raw reports unless needed.
 
+### Key Learnings closing block (routing)
+
+Every installed SDD phase executor agent (`assets/agents/sdd-*.md`) carries the effective `## Key Learnings Closing` contract in its own loaded prompt; this workflow file documents routing only and is not the executor authority. Each phase executor closes its final report text with a `## Key Learnings` block that the Engram memory provider passively extracts. Generic delegated workers receive the same closing instruction via `assets/orchestrator-delegation.md`.
+
 ## Automatic Mode Gatekeeper
 
 In `auto` execution mode, the parent/orchestrator is the quality gate between SDD phases. After a delegated phase returns and before launching the next phase, validate that the phase actually reached its objective. This validation is autonomous: do not ask the user on the happy path, but stop and report if the gate catches a real problem.
@@ -154,9 +188,82 @@ On gate pass, continue automatically to the next phase. On gate fail, rerun the
 
 The gatekeeper is additive: it does not relax the Review Workload Guard, Strict TDD Forwarding, native status dependency checks, or mandatory delegation rules. It never creates a post-SDD review pass.
 
+## Native Runtime Attempt Authority
+
+The package-local Gentle AI runtime owns the Git-common-dir compact SDD attempt ledger. It is the sole attempt and changed-line budget authority for both OpenSpec and Engram flows on Pi. Pi must not implement a local attempt mirror, counter, token store, state machine, or extension interception layer; such code would duplicate provider authority and could not truthfully settle all runs.
+
+Before every runtime-bearing `sdd-apply`, `sdd-verify`, or remediation actor/harness launch, the orchestrator MUST call the compact acquire:
+
+```text
+gentle-ai sdd-attempt acquire --cwd <repo> --change <change> --request-id <id> --work-unit <label> --evidence-goal <goal> --max-attempts <count> --max-changed-lines <count>
+```
+
+Pass `--token` only to continue an active attempt; pass `--remediates-evidence-revision` only for an unmanaged remediation. Do not invent continuation or remediation state the provider has not returned.
+
+The provider returns exactly one routing state from `proceed|blocked|complete`:
+
+- `proceed`: launch only on `proceed`; retain the opaque token for settle.
+- `blocked`: do not launch; stop and report.
+- `complete`: do not launch; the objective is settled.
+
+Never persist caller-authored attempt counters, tokens, or state in OpenSpec artifacts, Engram memory, prompts, or any Pi-owned state.
+
+After the external run completes, call the compact settle with a request ID distinct from acquire, reusing an operation's own ID only for idempotent replay of that exact operation:
+
+```text
+gentle-ai sdd-attempt settle --cwd <repo> --change <change> --token <token> --request-id <id> --outcome <failed|interrupted|passed> --evidence-revision <sha256:...> --diagnosis <text> --harness-disposition <reused|invalidated> --cleanup-evidence <text> --process-evidence <text>
+```
+
+Every settle field is required: `cwd`, `change`, `token`, `request-id`, `outcome`, `evidence-revision`, `diagnosis`, `harness-disposition`, `cleanup-evidence`, and `process-evidence`. `evidence-revision` is never `none`. Pass `--successor-lineage` only for a distinct approved successor; the current/bound lineage remains itself otherwise. Pass `--remediates-evidence-revision` only when repairing a specific failed evidence revision. Settle derives binding and remediation inputs; the orchestrator never invents them.
+
+`status`, `begin`, `finish`, and `reset` are diagnostic/compatibility surfaces, not the normal runtime route. Route continuation only from the provider-returned `proceed|blocked|complete`. `reset` is never automatic and requires an explicit maintainer scope decision.
+
+### Gatekeeper Reconciliation
+
+The Automatic Mode Gatekeeper one-rerun rule above is a quality gate, not a launch authorization. A rerun never bypasses native attempt authority: every rerun still requires a fresh compact acquire, and the rerun must stop immediately if the provider returns `blocked` or `complete`. The gatekeeper quality rule is preserved and remains subordinate to this authority.
+
 ## SDD Phase Delegation Mode
 
-Launch SDD phase subagents with `subagent_run` `mode: "task"` when the parent needs the phase result to route the next step. Do not use `mode: "background"` for SDD phases that must feed continuation; background completion is a notification/history mechanism, not an orchestration resume guarantee.
+Launch SDD phase subagents with `subagent_run` `mode: "task"` when the parent needs the phase result to route the next step. SDD phases, writers, dependent verify evidence, and archive are foreground-mandatory under the background subagent policy block in the delegation contract; background completion is a notification/history mechanism, not an orchestration resume guarantee.
+
+## Model Assignments
+
+Read this table before the first SDD/Judgment-Day phase delegation in a session, cache it, and use it only for SDD/Judgment-Day phase agents. If a phase is missing, use the `default` row. If the assigned tier is unavailable, use the runtime's default model and continue.
+
+On Pi, phase model routing is user-owned and persisted, not prompt-passed: `/gentle:models` writes `.pi/gentle-ai/models.json`, and the package applies each saved assignment to the installed phase agent definitions (frontmatter `model:`/`thinking:`) or `.pi/settings.json` overrides. The table below is the default capability tier per phase when the user has saved no assignment.
+
+**Mandatory phase model gate:** before launching an SDD/Judgment-Day phase agent, confirm the phase resolves through the saved model config or these defaults. Never pass an ad-hoc `model` parameter for SDD/Judgment-Day phases, and never apply this table to generic Pi delegation — generic subagents resolve model/thinking through `pi-subagents` config, and `model` is passed there only on an explicit user override.
+
+| Phase        | Default tier   | Reason                                     |
+| ------------ | -------------- | ------------------------------------------ |
+| sdd-explore  | balanced       | Reads code, structural - not architectural |
+| sdd-proposal | deep-reasoning | Architectural decisions                    |
+| sdd-spec     | balanced       | Structured writing                         |
+| sdd-design   | deep-reasoning | Architecture decisions                     |
+| sdd-tasks    | balanced       | Mechanical breakdown                       |
+| sdd-apply    | balanced       | Implementation                             |
+| sdd-verify   | balanced       | Validation against spec                    |
+| sdd-sync     | fast           | Reflect verified state                     |
+| sdd-archive  | fast           | Copy and close                             |
+| jd-judge-a   | deep-reasoning | Adversarial review                         |
+| jd-judge-b   | deep-reasoning | Adversarial review                         |
+| jd-fix-agent | balanced       | Surgical confirmed fixes                   |
+| default      | balanced       | SDD/JD phase fallback                      |
+
+## Sub-Agent Launch Deduplication
+
+Maintain a session-scoped launch log of `(phase, task-fingerprint)` pairs. If the same pair already exists, do NOT launch again. Emit exactly one launch per distinct task and append the pair after launch.
+
+## Sub-Agent Launch Protocol
+
+Pre-flight before every SDD/Judgment-Day phase launch:
+
+1. Identify the phase key (`sdd-apply`, `sdd-verify`, `jd-judge-a`, etc.).
+2. Confirm its model routing per the Model Assignments gate above.
+3. Resolve matching skill paths once per session from the registry and pass exact `SKILL.md` paths under `## Skills to load before work`.
+4. If a delegated result reports `skill_resolution` as `fallback-registry`, `fallback-path`, or `none`, re-read the registry before subsequent delegations.
+
+**Key Learnings closing (generic delegations):** when delegating to generic agents (`gentle-ai-explore`, `gentle-ai-worker`, `gentle-ai-verify`, scout/worker roles, or the native `Agent` fallback), apply the rule exactly as stated under "Key Learnings closing block" in `assets/orchestrator-delegation.md`. That file is the single statement of the rule; do not restate or paraphrase it here. SDD phase launch prompts need no such injection: every installed SDD phase executor already carries the effective contract in its own prompt (see "Key Learnings closing block (routing)" above).
 
 ## Strict TDD Forwarding
 
@@ -170,12 +277,50 @@ STRICT TDD MODE IS ACTIVE. Test runner: <command>. Follow RED, GREEN, TRIANGULAT
 
 Do not rely on the child agent to discover this independently.
 
+## Archive Final-State Handoff
+
+When launching `sdd-archive`, forward explicit final-state facts for any work completed after `apply-progress`, `verify-report`, or `sync-report` were persisted — verify warnings fixed in later commits, blockers resolved, tasks finished, updated test or issue counts — with commit or evidence references where available. Those artifacts are intermediate snapshots, valid at the time they were written; the archive report records the state at close, and explicit final-state facts in the `sdd-archive` launch prompt outrank stale snapshot claims.
+
 ## Review Workload Guard
 
-After `sdd-tasks` and before `sdd-apply`, inspect the task output for review workload risk.
+After `sdd-tasks` completes and before launching `sdd-apply`, inspect the task output's `Review Workload Forecast`.
+
+If it says `Chained PRs recommended: Yes`, `400-line budget risk: High`, estimated changed lines exceed 400, or `Decision needed before apply: Yes`, apply the cached `delivery_strategy`:
+
+- `ask-on-risk`: stop and ask whether to split or proceed with `size:exception`.
+- `auto-chain`: split automatically; ask for `chain_strategy` only if missing.
+- `single-pr`: stop and require/record `size:exception` before apply.
+- `exception-ok`: continue and tell `sdd-apply` this run uses `size:exception`.
+
+Any other `delivery_strategy` value is invalid. Do NOT pick the nearest branch and do NOT proceed: STOP, report the unrecognised value, and re-collect the delivery strategy before launching `sdd-apply`.
 
-If estimated changed lines exceed 400, chained PRs are recommended, or a decision is needed, pause and ask unless the user already approved a delivery strategy.
+Always pass the resolved `delivery_strategy`, `chain_strategy`, and any chosen PR boundary/exception to `sdd-apply` in the launch prompt.
 
 Any review transaction explicitly started outside SDD persists through its own artifact-store branch and budget. SDD completion itself launches no review actors and mints no review authority.
 
 Automatic mode does not override reviewer burnout protection.
+
+## Recovery
+
+- `engram` → resolve state with the injected memory search/get tools on the change topic keys (`sdd/{change-name}/...`).
+- `openspec` → read `openspec/changes/<change>/` artifacts and re-derive readiness through the native status engine.
+- `none` → state is not persisted; explain the limitation.
+
+## Provider Defect Handoff
+
+This section applies when an SDD phase or review lifecycle operation appears blocked by a Gentle AI provider defect. The full contract lives in `assets/orchestrator-delegation.md` under `#### Gentle AI Provider Defect Handoff (MANDATORY)`; it ports Gentle AI's v2.4.0-rc.8 handoff consent contract (the `gentle-ai.review-integration.consent/v3` envelope; canonical source `internal/assets/generic/sdd-orchestrator.md` at tag `v2.4.0-rc.8`, a prerelease not present in v2.3.0 stable). Pi review commands use `gentle_review`.
+
+Concise rules:
+
+- Classify admissibility before relaying: offer the handoff only when a Gentle AI invocation produced the failure, not when its runtime merely hosted it.
+- Never offer to switch to, inspect, modify, or directly repair the Gentle AI repository from this SDD workflow. If an upstream envelope offers direct repair, reject it as semantically inadmissible and issue the orchestrator-owned handoff envelope instead.
+- Ask the user first, in the active conversation language, for explicit consent to report the apparent defect. Present one single-select blocking envelope with exactly three semantic choices in this order. Its exact internal answer tokens are `report_and_continue`, `continue_without_reporting`, `stop_here`. Do not expose machine or internal codes in user-facing labels.
+- Privacy scrub immediately before the first GitHub operation: exclude raw argv, absolute paths, private project names, usernames, hostnames, credentials, diffs, source contents, and environment values.
+- Complete a definitive lookup across open and closed issues in `Gentleman-Programming/gentle-ai` before any write; only a definitive lookup may branch to GitHub mutation.
+- Derive the evidence channel only from the installed build string: recognized prerelease tags are `-rc.` and `-main.`; every other build is stable. A fix counts only in the installed build's channel. A fix published only to the other channel gets one occurrence comment naming where it is published; never recommend switching channels.
+- If the installed build predates the relevant published fix, recommend installing it and reproducing; do not create or comment for that occurrence yet. If the installed build demonstrably contains the fix and still reproduces, treat it as a possible regression: comment on a suitable canonical tracker or create a linked regression issue; never reopen automatically.
+- Confirmed creation requires the GitHub create operation to confirm a newly-created issue identity/URL; never infer creation from output text alone.
+- On search, comment, or creation failure/ambiguity/timeout/permission/unknown: perform no further GitHub mutation and no blind retry; preserve all consumer state, then execute the exact captured provider-owned decline invocation exactly once, validate it, re-enter native negotiated STATUS, and resume the already-held consumer continuation.
+- Both continue choices execute that exact captured decline invocation exactly once; never synthesize the decline command, target, token, or consumer continuation from prose. If unavailable or ambiguous, fail closed.
+- Do not invoke `gentle-ai review mode disable` at clone or global scope within this handoff. Do not turn RDD off or on within this handoff.
+- Resume after an installed published fix or an explicit maintainer-authorized, documented native recovery or reset that the runtime contract supports; then re-enter through native status. Never resume against unpublished code.

package/assets/support/sdd-status-contract.md

@@ -13,6 +13,16 @@ Any phase that selects, continues, applies, verifies, syncs, or archives an SDD
 - If multiple active changes match or the active change is unclear, ask the user to choose. Do not guess.
 - If no active changes exist, report that no SDD change is active and suggest starting one.
 
+## Native Engine
+
+- When the session artifact store is `openspec` or `both` (with an `openspec/` directory) and the `gentle-ai` binary is available, prefer `gentle-ai sdd-status [change] --cwd <repo> --json --instructions` for read-only status and `gentle-ai sdd-continue [change] --cwd <repo>` for dispatcher output, and treat their native status JSON as authoritative over prompt inference or manually reconstructed state.
+- For non-authoritative stores (`engram`, `none`, and `both` without an `openspec/` directory), do not treat dispatcher output as authoritative; follow Engine Authority by Store below.
+- Runtime-attempt authority is different from artifact dispatch: normal runtime-bearing OpenSpec and Engram continuations MUST bracket external execution with `gentle-ai sdd-attempt acquire|settle --cwd <repo> --change <change>`. Their bounded result contains only `proceed`, `blocked`, or `complete` plus an opaque continuation token when required, and MAY carry `settle_obligation` on a `proceed`. The Git-common-dir immutable chain remains the sole authority for ordinals, cumulative attempt/line budgets, runtime evidence, and atomic bound remediation.
+- A phase actor launched BY a parent that already holds a `proceed`-state acquire for that exact work unit is a distinct call/process, not a fresh continuation: it MUST NOT `acquire` again blind. Colliding with its own parent's active attempt is not a genuine `blocked: active_attempt` (#2291). It authenticates as that SAME attempt by passing the parent's returned token on its own `acquire --token <token>` call: a token matching the ledger's live active attempt returns `proceed` with that same token and zero mutation, while a non-matching token gets the ordinary `blocked: active_attempt` naming the real active token.
+- When `blockedReasons` is non-empty, do not proceed to terminal, archive, or apply work. Return or report `blockedReasons` and stop unless `nextRecommended` is `verify`, in which case verification may run only to remediate or refresh evidence for the blockers. When `nextRecommended` is `resolve-blockers`, always report `blockedReasons` and stop. When `nextRecommended` is a planning token (`propose`, `spec`, `design`, or `tasks`), launch the corresponding planning phase — missing planning artifacts are the expected output of those phases, not genuine blockers.
+- `nextRecommended` is a bounded machine token for routing, not human prose. Route only by `nextRecommended` and dependency states. Human-readable explanation belongs in `blockedReasons`, not `nextRecommended`.
+- If the binary is unavailable, fall back to this prompt contract and the manual status schema below. Manual fallback status MUST stay shape-compatible with the native status JSON even when values are reconstructed manually.
+
 ## Status Schema
 
 Return status as markdown with these fields, or equivalent JSON when the host supports it:
@@ -71,7 +81,7 @@ actionContext:
   workspaceRoot: <absolute path>
   allowedEditRoots: [<absolute paths>]
   warnings: []
-nextRecommended: <command-or-action>
+nextRecommended: <bounded-machine-token>
 isNonAuthoritative: false  # boolean; true when the native engine is not authoritative for the store
 ```
 
@@ -107,6 +117,14 @@ The orchestrator MUST carry `actionContext` into any phase launch.
 - `openspec` and `both` (when `openspec/` directory exists): the native status engine resolves artifact state from disk and is authoritative. Phase executors must obey it.
 - `engram`, `none`, and `both` (when `openspec/` directory does NOT exist): the native status engine cannot read Engram artifacts. It returns `nextRecommended: "resolve-via-engram"` and empty `blockedReasons`. This output is **non-authoritative**. The orchestrator must resolve readiness directly from Engram using the Engram memory tools injected by the memory provider on the change topic keys (`sdd/{change-name}/proposal`, `sdd/{change-name}/spec`, etc.) instead of relying on the engine's dependency states. The `artifactStore` field still reflects the real chosen store value (e.g. `"both"`) and must not be rewritten.
 
+## Native Runtime Attempt Authority
+
+The compact SDD runtime attempt authority is separate from artifact dispatch and status. It is artifact-store agnostic: the same acquire/settle discipline applies to `openspec`, `engram`, `both`, and `none` stores. Its payload MUST NOT be embedded in the SDD v1 status schema above; status reports artifact state only, never attempt tokens or attempt counters. No OpenSpec or Engram attempt ledger may be created or mirrored by Pi.
+
+Before every runtime-bearing `sdd-apply`, `sdd-verify`, or remediation launch, the orchestrator MUST acquire a bounded attempt from the provider compact CLI; after the external run completes it MUST settle. The acquire and settle request IDs are distinct; an operation's own request ID is reused only for idempotent replay of that exact operation. Continuation routes only from the provider-returned `proceed|blocked|complete` — launch only on `proceed`, stop on `blocked` or `complete`. `reset` is never automatic and requires an explicit maintainer scope decision.
+
+For the exact compact acquire/settle shapes and the full field semantics, see the `Native Runtime Attempt Authority` section of the lazy-loaded `SDD Orchestrator Workflow` contract. Do not look up `assets/...` paths at runtime; those are package source paths before installation.
+
 ## Status Output
 
 Every command or agent that acts on a change MUST show or consume status before doing phase work:

package/contracts/review-integration/v1/fixtures/consent.fixture.json

@@ -4,7 +4,7 @@
   "operation": "review.start",
   "action": "consent_required",
   "blocking": true,
-  "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5",
+  "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04",
   "projection": "workspace",
   "risk_level": "high",
   "changed_files": 1,
@@ -20,13 +20,13 @@
       "answer": "granted",
       "label": "Run the review now",
       "effect": "Reviews this exact frozen candidate now; nothing is granted for later candidates, so each later medium- or high-risk candidate asks again.",
-      "invocation": "gentle-ai review start --contract gentle-ai.review-integration/v1 --cwd /repo --target sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5 --projection workspace --lineage review-consent-fixture --consent granted"
+      "invocation": "gentle-ai review start --contract gentle-ai.review-integration/v1 --cwd /repo --target sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04 --projection workspace --lineage review-consent-fixture --consent granted"
     },
     {
       "answer": "declined",
       "label": "Not now, just this once",
       "effect": "Skips the review for this candidate only; nothing is persisted and the next candidate is asked again. This is not the kill switch.",
-      "invocation": "gentle-ai review start --contract gentle-ai.review-integration/v1 --cwd /repo --target sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5 --projection workspace --lineage review-consent-fixture --consent declined"
+      "invocation": "gentle-ai review start --contract gentle-ai.review-integration/v1 --cwd /repo --target sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04 --projection workspace --lineage review-consent-fixture --consent declined"
     }
   ],
   "off_path": {

package/contracts/review-integration/v1/fixtures/start-v2.fixture.json

@@ -27,45 +27,45 @@
   "artifact_subjects": [
     {
       "schema": "gentle-ai.review-artifact-subject/v1",
-      "subject_hash": "sha256:38a55988f6b3ae6f520690d52fd29255f425a4048b0f8694de3a80c5daf265cd",
+      "subject_hash": "sha256:462591bc0cfab672cdf741536c5f1d8122a1f31b1773b9f1d12c5f2b72c76d23",
       "lineage_id": "review-start-fixture",
-      "authority_revision": "sha256:3411d049f39e891b50adfc76473199b473927d10245a227a3bc967eae0caf68c",
-      "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5",
+      "authority_revision": "sha256:e10bced7198e3c817c5ff6d1172d6aa8ce3321d45ec4d68834e0b5f03a4246d9",
+      "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04",
       "candidate_diff_sha256": "sha256:c18ffcaf6f41a8cd5f3399a10355eb8de3e5eb561cb65cb551ea93bdf4df921b",
-      "changed_path_manifest_sha256": "sha256:049219ea30e21c409608ea8527e65bcc6774d764363031a6cf0cb05e35c734ef",
+      "changed_path_manifest_sha256": "sha256:dc754e73f2d661e2f914fdc5dd8d2a399be18567481137f43ae9d8d45aae3397",
       "lens": "review-risk",
       "selected_order": 0
     },
     {
       "schema": "gentle-ai.review-artifact-subject/v1",
-      "subject_hash": "sha256:06d86f981a8c0b16c2179696d467c8157580214ad72c952adee423fe596d2c21",
+      "subject_hash": "sha256:6374e313d6524b832afa399bdd205d4e852e1a19ea8d87000804789df6117e3b",
       "lineage_id": "review-start-fixture",
-      "authority_revision": "sha256:3411d049f39e891b50adfc76473199b473927d10245a227a3bc967eae0caf68c",
-      "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5",
+      "authority_revision": "sha256:e10bced7198e3c817c5ff6d1172d6aa8ce3321d45ec4d68834e0b5f03a4246d9",
+      "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04",
       "candidate_diff_sha256": "sha256:c18ffcaf6f41a8cd5f3399a10355eb8de3e5eb561cb65cb551ea93bdf4df921b",
-      "changed_path_manifest_sha256": "sha256:049219ea30e21c409608ea8527e65bcc6774d764363031a6cf0cb05e35c734ef",
+      "changed_path_manifest_sha256": "sha256:dc754e73f2d661e2f914fdc5dd8d2a399be18567481137f43ae9d8d45aae3397",
       "lens": "review-resilience",
       "selected_order": 1
     },
     {
       "schema": "gentle-ai.review-artifact-subject/v1",
-      "subject_hash": "sha256:beacbf1eed52620ef7686087f8944cbc2304d71abf13281267efe9e4de20fb1e",
+      "subject_hash": "sha256:56924c7ad539c596fd584905c9be7a82765e551154375a8022fb1e820bc2f61a",
       "lineage_id": "review-start-fixture",
-      "authority_revision": "sha256:3411d049f39e891b50adfc76473199b473927d10245a227a3bc967eae0caf68c",
-      "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5",
+      "authority_revision": "sha256:e10bced7198e3c817c5ff6d1172d6aa8ce3321d45ec4d68834e0b5f03a4246d9",
+      "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04",
       "candidate_diff_sha256": "sha256:c18ffcaf6f41a8cd5f3399a10355eb8de3e5eb561cb65cb551ea93bdf4df921b",
-      "changed_path_manifest_sha256": "sha256:049219ea30e21c409608ea8527e65bcc6774d764363031a6cf0cb05e35c734ef",
+      "changed_path_manifest_sha256": "sha256:dc754e73f2d661e2f914fdc5dd8d2a399be18567481137f43ae9d8d45aae3397",
       "lens": "review-readability",
       "selected_order": 2
     },
     {
       "schema": "gentle-ai.review-artifact-subject/v1",
-      "subject_hash": "sha256:61a10b133e3f7a8ccad1d0f1d58989df75d2330ad530690137de625bfd10eec8",
+      "subject_hash": "sha256:0e15bc61702fd815c7140592e02d752143a0ac10a5fd59b4f8e8a8c0e8ea103b",
       "lineage_id": "review-start-fixture",
-      "authority_revision": "sha256:3411d049f39e891b50adfc76473199b473927d10245a227a3bc967eae0caf68c",
-      "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5",
+      "authority_revision": "sha256:e10bced7198e3c817c5ff6d1172d6aa8ce3321d45ec4d68834e0b5f03a4246d9",
+      "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04",
       "candidate_diff_sha256": "sha256:c18ffcaf6f41a8cd5f3399a10355eb8de3e5eb561cb65cb551ea93bdf4df921b",
-      "changed_path_manifest_sha256": "sha256:049219ea30e21c409608ea8527e65bcc6774d764363031a6cf0cb05e35c734ef",
+      "changed_path_manifest_sha256": "sha256:dc754e73f2d661e2f914fdc5dd8d2a399be18567481137f43ae9d8d45aae3397",
       "lens": "review-reliability",
       "selected_order": 3
     }
@@ -77,21 +77,12 @@
     "byte_size": 226
   },
   "changed_path_manifest": [
-    {
-      "path": "scripts/deploy.sh",
-      "status": "A",
-      "old_mode": "000000",
-      "new_mode": "100644",
-      "deleted": false,
-      "type_changed": false,
-      "mode_only": false,
-      "intended_untracked": true
-    }
+    {"path":"scripts/deploy.sh","status":"A","old_mode":"000000","new_mode":"100644","deleted":false,"type_changed":false,"mode_only":false,"intended_untracked":false}
   ],
   "repository_context": {
     "capability": "review.opaque_repository_context",
     "handle": "rctx1_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-    "revision": "sha256:3411d049f39e891b50adfc76473199b473927d10245a227a3bc967eae0caf68c",
-    "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5"
+    "revision": "sha256:e10bced7198e3c817c5ff6d1172d6aa8ce3321d45ec4d68834e0b5f03a4246d9",
+    "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04"
   }
 }

package/contracts/review-integration/v1/fixtures/start.fixture.json

@@ -31,16 +31,7 @@
     "byte_size": 226
   },
   "changed_path_manifest": [
-    {
-      "path": "scripts/deploy.sh",
-      "status": "A",
-      "old_mode": "000000",
-      "new_mode": "100644",
-      "deleted": false,
-      "type_changed": false,
-      "mode_only": false,
-      "intended_untracked": true
-    }
+    {"path":"scripts/deploy.sh","status":"A","old_mode":"000000","new_mode":"100644","deleted":false,"type_changed":false,"mode_only":false,"intended_untracked":true}
   ],
   "repository_context": {
     "capability": "review.opaque_repository_context",

package/contracts/review-integration/v1/fixtures/status-v2.fixture.json

@@ -8,7 +8,7 @@
     "lineage_id": "review-status-fixture",
     "state": "reviewing",
     "generation": 1,
-    "revision": "sha256:81cdad8f3182d4919147d3c4fe8f614814068e5ef68417e3dcbd5e326dd3e390"
+    "revision": "sha256:c978e5383ae788a963c5e80c4f887d3b65ca415767398d57de827a9f0905f423"
   },
   "receipt": {
     "status": "expected_missing"
@@ -20,7 +20,7 @@
     "original_changed_lines": 2,
     "correction_budget": 1
   },
-  "target_identity": "sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6",
+  "target_identity": "sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49",
   "projection": {
     "schema": "gentle-ai.review-integration.projection/v1",
     "kind": "current-changes",
@@ -34,8 +34,8 @@
     ],
     "intended_untracked": [],
     "intended_untracked_proof": "sha256:b97229718d4c7fe50a8892eb474ae5aa6491697bccb400e3e31dbaca4894d2f3",
-    "initial_snapshot_identity": "sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6",
-    "current_snapshot_identity": "sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6"
+    "initial_snapshot_identity": "sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49",
+    "current_snapshot_identity": "sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49"
   },
   "repair": {
     "schema": "gentle-ai.review-authority-repair-assessment/v1",
@@ -133,13 +133,13 @@
             },
             {
               "name": "expected-revision",
-              "value": "sha256:81cdad8f3182d4919147d3c4fe8f614814068e5ef68417e3dcbd5e326dd3e390",
-              "token": "--expected-revision=sha256:81cdad8f3182d4919147d3c4fe8f614814068e5ef68417e3dcbd5e326dd3e390"
+              "value": "sha256:c978e5383ae788a963c5e80c4f887d3b65ca415767398d57de827a9f0905f423",
+              "token": "--expected-revision=sha256:c978e5383ae788a963c5e80c4f887d3b65ca415767398d57de827a9f0905f423"
             },
             {
               "name": "target",
-              "value": "sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6",
-              "token": "--target=sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6"
+              "value": "sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49",
+              "token": "--target=sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49"
             },
             {
               "name": "repository-context",
@@ -159,10 +159,10 @@
           ],
           "artifact_subject": {
             "schema": "gentle-ai.review-artifact-subject/v1",
-            "subject_hash": "sha256:fe57db2ea45a33c7e852d039e8af3291c3bc31911f0c92a710b5fef547b1999d",
+            "subject_hash": "sha256:d8f46ff5cdcd86385033ce73f18cbfd61651c81deba1340b743e034cdf9dce48",
             "lineage_id": "review-status-fixture",
-            "authority_revision": "sha256:81cdad8f3182d4919147d3c4fe8f614814068e5ef68417e3dcbd5e326dd3e390",
-            "target_identity": "sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6",
+            "authority_revision": "sha256:c978e5383ae788a963c5e80c4f887d3b65ca415767398d57de827a9f0905f423",
+            "target_identity": "sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49",
             "candidate_diff_sha256": "sha256:8ed4bd24d5beb3f73f6026355f6755f5aef7feebcd76447be820860c22bc47c6",
             "changed_path_manifest_sha256": "sha256:64d028ff676fb4ef10f2d4a3488d568854b364b4cc4399578b5932d144d2347b",
             "lens": "review-reliability",
@@ -175,16 +175,7 @@
             "byte_size": 209
           },
           "changed_path_manifest": [
-            {
-              "path": "tracked.txt",
-              "status": "M",
-              "old_mode": "100644",
-              "new_mode": "100644",
-              "deleted": false,
-              "type_changed": false,
-              "mode_only": false,
-              "intended_untracked": false
-            }
+            {"path":"tracked.txt","status":"M","old_mode":"100644","new_mode":"100644","deleted":false,"type_changed":false,"mode_only":false,"intended_untracked":false}
           ]
         }
       ]

package/contracts/review-integration/v1/schemas/correction-plan-request.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v1/schemas/correction-plan-request.schema.json",
+  "title": "Gentle AI provider-owned bounded correction plan request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema", "request_hash", "lineage_id", "expected_revision", "target_identity",
+    "correction_budget", "fix_finding_ids", "findings"
+  ],
+  "properties": {
+    "schema": {"const": "gentle-ai.review-correction-plan-request/v1"},
+    "request_hash": {"$ref": "#/$defs/sha256"},
+    "lineage_id": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "expected_revision": {"$ref": "#/$defs/sha256"},
+    "target_identity": {"$ref": "#/$defs/sha256"},
+    "correction_budget": {"type": "integer", "minimum": 1, "maximum": 200},
+    "fix_finding_ids": {
+      "type": "array", "minItems": 1, "uniqueItems": true,
+      "items": {"type": "string", "minLength": 1}
+    },
+    "findings": {
+      "type": "array", "minItems": 1, "uniqueItems": true,
+      "items": {"$ref": "#/$defs/finding"}
+    }
+  },
+  "$defs": {
+    "sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id", "lens", "location", "severity", "claim", "proof_refs", "evidence",
+        "evidence_class", "causal_disposition"
+      ],
+      "properties": {
+        "id": {"type": "string", "minLength": 1},
+        "lens": {"enum": ["risk", "resilience", "readability", "reliability"]},
+        "location": {"type": "string", "minLength": 1},
+        "severity": {"enum": ["BLOCKER", "CRITICAL"]},
+        "claim": {"type": "string", "minLength": 1},
+        "proof_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+        "evidence": {"type": "string", "minLength": 1},
+        "evidence_class": {"enum": ["deterministic", "inferential"]},
+        "causal_disposition": {"enum": ["introduced", "behavior-activated", "worsened"]}
+      }
+    }
+  }
+}